Adsk Contrib - Various code & doc cleanups (#1414)

* Adsk Contrib - Various code & doc cleanups Signed-off-by: Patrick Hodoul <Patrick.Hodoul@autodesk.com> * Fix more Python examples Signed-off-by: Patrick Hodoul <Patrick.Hodoul@autodesk.com>
AcademySoftwareFoundation · Jul 5, 2021 · a36a5be · a36a5be
1 parent 856f604
commit a36a5be
Show file tree

Hide file tree

Showing 4 changed files with 84 additions and 60 deletions.
diff --git a/docs/guides/authoring/looks_example.rst b/docs/guides/authoring/looks_example.rst
@@ -52,7 +52,7 @@ Example Python API call:
 .. code-block:: python
 
     look = OCIO.Look(name='di', processSpace='rclg16')
-    t = OCIO.FileTransform('look_di.cc', interpolation=OCIO.Constants.INTERP_LINEAR)
+    t = OCIO.FileTransform('look_di.cc', interpolation=OCIO.INTERP_LINEAR)
     look.setTransform(t)
     config.addLook(look)
 

diff --git a/docs/guides/developing/usage_examples.rst b/docs/guides/developing/usage_examples.rst
@@ -93,15 +93,16 @@ Python
    import PyOpenColorIO as OCIO
    
    try:
-       config = OCIO.GetCurrentConfig()
-       processor = config.getProcessor(OCIO.Constants.ROLE_COMPOSITING_LOG,
-                                       OCIO.Constants.ROLE_SCENE_LINEAR)
-       cpu = processor->getDefaultCPUProcessor()
+      config = OCIO.GetCurrentConfig()
+      processor = config.getProcessor(OCIO.ROLE_COMPOSITING_LOG,
+                                      OCIO.ROLE_SCENE_LINEAR)
+      cpu = processor.getDefaultCPUProcessor()
        
-       # Apply the color transform to the existing RGBA pixel data
-       img = cpu.applyRGBA(img)
-   except Exception, e:
-       print "OpenColorIO Error",e
+      # Apply the color transform to the existing RGBA pixel data
+      img = [1, 0, 0, 0]
+      img = cpu.applyRGBA(img)
+   except Exception as e:
+      print("OpenColorIO Error: ", e)
 
 .. _usage_displayimage:
 
@@ -133,17 +134,18 @@ C++
    
    try
    {
-     OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig();
+      OCIO::ConstConfigRcPtr config = OCIO::GetCurrentConfig();
    
-     const char * display = config->getDefaultDisplay();
-     const char * view = config->getDefaultView(display);
+      const char * display = config->getDefaultDisplay();
+      const char * view = config->getDefaultView(display);
    
-     OCIO::ConstProcessorRcPtr processor = config->getProcessor(OCIO::ROLE_SCENE_LINEAR,
-                                                                display, view);
-     OCIO::ConstCPUProcessorRcPtr cpu = processor->getDefaultCPUProcessor();
+      OCIO::ConstProcessorRcPtr processor = config->getProcessor(OCIO::ROLE_SCENE_LINEAR,
+                                                                 display, view,
+                                                                 OCIO::TRANSFORM_DIR_FORWARD);
+      OCIO::ConstCPUProcessorRcPtr cpu = processor->getDefaultCPUProcessor();
    
-     OCIO::PackedImageDesc img(imageData, width, height, 4);
-     cpu->apply(img);
+      OCIO::PackedImageDesc img(imageData, width, height, 4);
+      cpu->apply(img);
    }
    catch(OCIO::Exception & exception)
    {
@@ -155,21 +157,21 @@ Python
 
 .. code-block:: python
 
-    import PyOpenColorIO as OCIO
+   import PyOpenColorIO as OCIO
 
    try:
-    config = OCIO.GetCurrentConfig()
+      config = OCIO.GetCurrentConfig()
 
-     display = config.getDefaultDisplay()
-     view = config.getDefaultView(display)
+      display = config.getDefaultDisplay()
+      view = config.getDefaultView(display)
 
-     processor = config.getProcessor(OCIO.Constants.ROLE_SCENE_LINEAR, display, view)
-     cpu = processor.getDefaultCPUProcessor()
+      processor = config.getProcessor(OCIO.ROLE_SCENE_LINEAR, display, view, OCIO.TRANSFORM_DIR_FORWARD)
+      cpu = processor.getDefaultCPUProcessor()
 
-     imageData = [1, 0, 0]
-     cpu.applyRGB(img)
-   except Exception, e:
-       print "OpenColorIO Error",e
+      img = [1, 0, 0]
+      cpu.applyRGB(img)
+   except Exception as e:
+      print("OpenColorIO Error: ", e)
 
 
 Displaying an image, using the CPU using DisplayViewTransform
@@ -208,30 +210,30 @@ Python
 
 .. code-block:: python
 
-    import PyOpenColorIO as OCIO
+   import PyOpenColorIO as OCIO
 
-    # Step 1: Get the config
-    config = OCIO.GetCurrentConfig()
+   # Step 1: Get the config
+   config = OCIO.GetCurrentConfig()
 
-    # Step 2: Lookup the display ColorSpace
-    display = config.getDefaultDisplay()
-    view = config.getDefaultView(display)
+   # Step 2: Lookup the display ColorSpace
+   display = config.getDefaultDisplay()
+   view = config.getDefaultView(display)
 
-    # Step 3: Create a DisplayViewTransform, and set the input, display, and view
-    # (This example assumes the input is a role. Adapt as needed.)
+   # Step 3: Create a DisplayViewTransform, and set the input, display, and view
+   # (This example assumes the input is a role. Adapt as needed.)
 
-    transform = OCIO.DisplayViewTransform()
-    transform.setSrc(OCIO.Constants.ROLE_SCENE_LINEAR)
-    transform.setDisplay(display)
-    transform.setView(view)
+   transform = OCIO.DisplayViewTransform()
+   transform.setSrc(OCIO.ROLE_SCENE_LINEAR)
+   transform.setDisplay(display)
+   transform.setView(view)
 
-    # Step 4: Create the processor
-    processor = config.getProcessor(transform)
-    cpu = processor.getDefaultCPUProcessor()
+   # Step 4: Create the processor
+   processor = config.getProcessor(transform)
+   cpu = processor.getDefaultCPUProcessor()
 
-    # Step 5: Apply the color transform to an existing RGB pixel
-    imageData = [1, 0, 0]
-    print cpu.applyRGB(imageData)
+   # Step 5: Apply the color transform to an existing RGB pixel
+   imageData = [1, 0, 0]
+   print(cpu.applyRGB(imageData))
 
 
 Displaying an image, using the GPU (Full Display Pipeline)

diff --git a/include/OpenColorIO/OpenColorIO.h b/include/OpenColorIO/OpenColorIO.h
@@ -2679,15 +2679,17 @@ class OCIOEXPORT PlanarImageDesc : public ImageDesc
 // GpuShaderCreator
 /**
  * Inherit from the class to fully customize the implementation of a GPU shader program
- * from a color transformation.
+ * from a color transformation. 
  *
- * When no customizations are needed then the GpuShaderDesc is a better choice.
+ * When no customizations are needed and the intermediate in-memory step is acceptable then the
+ * \ref GpuShaderDesc is a better choice.
  *
- * To better decouple the DynamicProperties from their GPU implementation, the code provides
- * several addUniform() methods i.e. one per access function types. For example, an
- * ExposureContrastTransform instance owns three DynamicProperties and they are all
- * implemented by a double. When creating the GPU fragment shader program, the addUniform() with
- * GpuShaderCreator::DoubleGetter is called when property is dynamic, up to three times.
+ * \note
+ *   To better decouple the \ref DynamicProperties from their GPU implementation, the code provides
+ *   several addUniform() methods i.e. one per access function types. For example, an
+ *   \ref ExposureContrastTransform instance owns three \ref DynamicProperties and they are all
+ *   implemented by a double. When creating the GPU fragment shader program, the addUniform() with
+ *   GpuShaderCreator::DoubleGetter is called when property is dynamic, up to three times.
  * 
  * **An OCIO shader program could contain:**
  *
@@ -2775,8 +2777,8 @@ class OCIOEXPORT GpuShaderCreator
     virtual unsigned getTextureMaxWidth() const noexcept = 0;
 
     /**
-     * To avoid texture/unform name clashes always append
-     * an increasing number to the resource name.
+     * To avoid global texture sampler and uniform name clashes always append an increasing index
+     * to the resource name.
      */
     unsigned getNextResourceIndex() noexcept;
 
@@ -2826,17 +2828,32 @@ class OCIOEXPORT GpuShaderCreator
 
     enum TextureType
     {
-        TEXTURE_RED_CHANNEL, ///< Only use the red channel of the texture
-        TEXTURE_RGB_CHANNEL
+        TEXTURE_RED_CHANNEL, ///< Only need a red channel texture
+        TEXTURE_RGB_CHANNEL  ///< Need a RGB texture
     };
 
+    /**
+     *  Add a 2D texture (1D texture if height equals 1).
+     * 
+     * \note 
+     *   The 'values' parameter contains the LUT data which must be used as-is as the dimensions and
+     *   origin are hard-coded in the fragment shader program. So, it means one GPU texture per entry.
+     **/
     virtual void addTexture(const char * textureName,
                             const char * samplerName,
                             unsigned width, unsigned height,
                             TextureType channel,
                             Interpolation interpolation,
                             const float * values) = 0;
 
+    /**
+     *  Add a 3D texture with RGB channel type.
+     * 
+     * \note 
+     *   The 'values' parameter contains the 3D LUT data which must be used as-is as the dimension
+     *   and origin are hard-coded in the fragment shader program. So, it means one GPU 3D texture
+     *   per entry.
+     **/
     virtual void add3DTexture(const char * textureName,
                               const char * samplerName,
                               unsigned edgelen,

diff --git a/src/OpenColorIO/Config.cpp b/src/OpenColorIO/Config.cpp
@@ -1170,16 +1170,21 @@ ConstConfigRcPtr Config::CreateFromEnv()
     Platform::Getenv(OCIO_CONFIG_ENVVAR, file);
     if(!file.empty()) return CreateFromFile(file.c_str());
 
-    std::ostringstream os;
-    os << "Color management disabled. ";
-    os << "(Specify the $OCIO environment variable to enable.)";
-    LogInfo(os.str());
+    static const char err[] =
+        "Color management disabled. (Specify the $OCIO environment variable to enable.)";
+
+    LogInfo(err);
 
     return CreateRaw();
 }
 
 ConstConfigRcPtr Config::CreateFromFile(const char * filename)
 {
+    if (!filename || !*filename)
+    {
+        throw ExceptionMissingFile ("The config filepath is missing.");
+    }
+
     std::ifstream istream(filename);
     if (istream.fail())
     {