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

* Adsk Contrib - Various code & doc cleanups

Signed-off-by: Patrick Hodoul <[email protected]>

* Fix more Python examples

Signed-off-by: Patrick Hodoul <[email protected]>

Co-authored-by: doug-walker <[email protected]>

Author: hodoulp

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)
 

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:
 
@@ -137,17 +138,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)
    {
@@ -159,21 +161,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 (Full Display Pipeline)
 **********************************************************
@@ -246,30 +248,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 DisplayTransform, and set the input, display, and view
-    # (This example assumes the input is scene linear. 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.DisplayTransform()
-    transform.setInputColorSpaceName(OCIO.Constants.ROLE_SCENE_LINEAR)
-    transform.setDisplay(display)
-    transform.setView(view)
+   transform = OCIO.DisplayViewTransform()
+   transform.setSrc(OCIO.Constants.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

include/OpenColorIO/OpenColorIO.h

@@ -2720,15 +2720,59 @@ 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 :cpp:class:`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:**
+ *
+ * * A declaration part  e.g., uniform sampled3D tex3;
+ *
+ * * Some helper methods
+ *
+ * * The OCIO shader function may be broken down as:
+ *
+ *    * The function header  e.g., void OCIODisplay(in vec4 inColor) {
+ *    * The function body    e.g.,   vec4 outColor.rgb = texture3D(tex3, inColor.rgb).rgb;
+ *    * The function footer  e.g.,   return outColor; }
+ * 
+ * 
+ * **Usage Example:**
+ * 
+ * Below is a code snippet to highlight the different parts of the OCIO shader program.
+ * 
+ * \code{.cpp}
+ *     
+ *     // All global declarations
+ *     uniform sampled3D tex3;
+ *   
+ *     // All helper methods
+ *     vec3 computePosition(vec3 color)
+ *     {
+ *        vec3 coords = color;
+ *        // Some processing...
+ *        return coords;
+ *     }
+ *     
+ *     // The shader function
+ *     vec4 OCIODisplay(in vec4 inColor)     //
+ *     {                                     // Function Header
+ *        vec4 outColor = inColor;           //
+ *     
+ *        outColor.rgb = texture3D(tex3, computePosition(inColor.rgb)).rgb;
+ *     
+ *        return outColor;                   // Function Footer
+ *     }                                     //
+ * 
+ * \endcode
  */
 class OCIOEXPORT GpuShaderCreator
 {
@@ -2774,8 +2818,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;
 
@@ -2825,17 +2869,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,

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())
     {