Add kOfxParamPropColourManagement for colour-managed RGB/RGBA params (#158)

Implements the agreed spec change from #158: a string-enum property a
plug-in sets on an RGB or RGBA parameter to declare the colourspace of
the parameter's values (defaults, current value and keyframes):

  - kOfxParamColourManagementNone    - legacy, unmanaged (default)
  - kOfxParamColourManagementManaged - ACES2065-1 (AP0), scene-linear,
                                       unclamped; for processing colours
  - kOfxParamColourManagementSRGB    - sRGB, [0..1]; for display-referred
                                       UI colours such as Draw Suite overlays

The encoding is fixed at parameter-definition time and needs no OCIO
config, so both colour-managed and unmanaged hosts can support it.
Defaults to None, so existing plug-ins are unaffected.

- include/ofxParam.h: the property and its three values with full
  @propdef metadata (enum, dim 1), plus ParamsRGB / ParamsRGBA property
  sets (the colour param types were not previously modelled).
- Documentation/sources/Reference/ofxParameter.rst: spec text with the
  musts/shoulds for hosts and plug-ins.
- Examples/Rectangle/rectangle.cpp: declares its solid-fill colour param
  as Managed, demonstrating the mandatory set-status check.
- release-notes.md: noted under 1.5.1.
- openfx-cpp/include/openfx/*: regenerated metadata, property sets and
  typed accessors via scripts/gen-props.py.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Gary Oberbrunner <garyo@darkstarsystems.com>

Author: garyo

Documentation/sources/Reference/ofxParameter.rst

@@ -150,9 +150,80 @@ These are typed by :c:macro:`kOfxParamTypeRGB` and :c:macro:`kOfxParamTypeRGBA`.
 
 Colour parameters are 3 or 4 dimensional double precision floating point
 parameters. They are displayed using the host's appropriate interface
-for a colour. Values are always normalised in the range [0 .. 1], with 0
+for a colour. By default values are normalised in the range [0 .. 1], with 0
 being the nominal black point and 1 being the white point.
 
+Colour-Managed Colour Parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The legacy behaviour above does not say which colourspace a colour parameter's
+values are in, so plug-ins and hosts have historically had to guess (usually
+assuming sRGB). A plug-in may instead declare the encoding explicitly by setting
+:c:macro:`kOfxParamPropColourManagement` on an RGB or RGBA parameter. This
+property governs the colourspace of *every* value exchanged for the parameter,
+including its default, its current value and any keyframes. It does not change
+the parameter's type, dimension or numeric API — values are still read and
+written as 3 or 4 doubles through the ordinary parameter suite.
+
+The property must be one of:
+
+- :c:macro:`kOfxParamColourManagementNone` — the parameter is not
+  colour-managed; its values are interpreted as in legacy OpenFX. This is the
+  default, so existing plug-ins are unaffected.
+- :c:macro:`kOfxParamColourManagementManaged` — the values are in the
+  **ACES2065-1 (AP0)** reference colourspace. They are scene-linear and are not
+  constrained to the [0 .. 1] range. Use this for colours that participate in
+  image processing, such as a key colour or a solid-fill colour.
+- :c:macro:`kOfxParamColourManagementSRGB` — the values are in the **sRGB**
+  colourspace ("web" RGB, with the sRGB transfer function), constrained to the
+  [0 .. 1] range. Use this for display-referred user-interface colours, such as
+  overlay and on-screen-control colours drawn with the
+  :c:struct:`OfxDrawSuiteV1`. It is not intended for processing image pixels.
+
+ACES2065-1 is the reference colourspace of the OpenFX native colour management
+config (see ``ofxColour.h``). It was chosen because it is a
+single, well-specified, scene-referred linear space wide enough to carry any
+colour without clamping. Restricting the managed encoding to this one space,
+rather than an arbitrary colourspace name, keeps both hosts and plug-ins simple
+and makes stored colours portable between applications. Plug-ins that need to
+convert managed values to or from another space can do so themselves; the
+conversions are standard and need no host involvement.
+
+Rules for plug-ins:
+
+- A plug-in **must** set this property, if at all, only when defining the
+  parameter (during the describe stage), before the parameter instance exists.
+- A plug-in **must not** change the property on a parameter instance, and in
+  particular **must not** change it during a render or other action to influence
+  a subsequent read. Hosts may evaluate parameters concurrently; the encoding is
+  a fixed property of the parameter, not a per-read mode.
+- A plug-in **must** check the status returned when setting the property. A host
+  that does not support it will fail the set; the plug-in **must** then fall
+  back to :c:macro:`kOfxParamColourManagementNone` behaviour.
+- A plug-in that declares a managed or sRGB encoding **must** supply every value
+  it sets (defaults included) in the declared colourspace, and **must** interpret
+  every value it reads as being in that colourspace.
+
+Rules for hosts:
+
+- A host that supports the property **must** accept all three values.
+- A host **should** convert the parameter's colour from its declared encoding
+  into whatever space it needs — for example to draw an accurate swatch, to feed
+  the value to the Draw Suite, or to hand a wide-gamut colour to the plug-in at
+  render time.
+- A host **should** store managed values as ACES2065-1 and sRGB values as sRGB
+  in its project files, so colour parameters are portable between applications
+  and across versions.
+- When a host first loads a project saved before a parameter became
+  colour-managed, it **should** convert the previously stored values into the
+  parameter's declared colourspace, assuming the legacy values were sRGB if it
+  has no better information.
+
+Support for this property does **not** require the host to advertise any
+particular :c:macro:`kOfxImageEffectPropColourManagementStyle`: the managed and
+sRGB encodings are fully specified here and need no OCIO config. See
+``ofxColour.h`` for the native colour management properties and reference
+colourspaces.
 
 Boolean Parameters
 ------------------

Examples/Rectangle/rectangle.cpp

@@ -803,6 +803,20 @@ describeInContext(OfxImageEffectHandle effect, OfxPropertySetHandle inArgs)
   gPropHost->propSetString(paramProps, kOfxParamPropHint, 0, "The colour of the rectangle");
   gPropHost->propSetString(paramProps, kOfxParamPropScriptName, 0, "colour");
   gPropHost->propSetString(paramProps, kOfxPropLabel, 0, "Colour");
+
+  // The rectangle is a solid fill, so its colour participates in image
+  // processing. Declare the parameter colour-managed: its values (including
+  // the default set below) are then in the ACES2065-1 reference colourspace.
+  // A plugin must check the status -- a host that does not support this
+  // property fails the set, in which case the colour is simply a legacy,
+  // unmanaged value. This minimal example treats the value identically either
+  // way; the default is opaque black, which is (0,0,0) in every RGB
+  // colourspace.
+  OfxStatus colourManagedStat =
+    gPropHost->propSetString(paramProps, kOfxParamPropColourManagement, 0,
+                             kOfxParamColourManagementManaged);
+  (void) colourManagedStat;
+
   gPropHost->propSetDouble(paramProps, kOfxParamPropDefault, 0, 0);
   gPropHost->propSetDouble(paramProps, kOfxParamPropDefault, 1, 0);
   gPropHost->propSetDouble(paramProps, kOfxParamPropDefault, 2, 0);

include/ofxParam.h

@@ -421,6 +421,97 @@ The exact type and dimension is dependent on the type of the parameter. These ar
  */
 #define kOfxParamPropDefault "OfxParamPropDefault"
 
+/** @brief Declares how an RGB or RGBA parameter's colour values are encoded,
+so that a host can interpret, convert and display them correctly.
+
+This property applies only to parameters of type ::kOfxParamTypeRGB and
+::kOfxParamTypeRGBA. It governs the colourspace of *every* value exchanged for
+the parameter through the parameter suite, including its default
+(::kOfxParamPropDefault), its current value, and any keyframes. It does not
+change the parameter's type, dimension, or numeric API: values are still 3 or 4
+doubles passed through the ordinary ::OfxParameterSuiteV1 calls.
+
+   - Valid Values - This must be one of
+      - ::kOfxParamColourManagementNone - the parameter is not colour-managed;
+        its values are interpreted as they always have been (the legacy,
+        unmanaged behaviour). This is the default.
+      - ::kOfxParamColourManagementManaged - the parameter's values are in the
+        ACES2065-1 (AP0) reference colourspace. The values are scene-linear and
+        are not constrained to the [0..1] range.
+      - ::kOfxParamColourManagementSRGB - the parameter's values are in the sRGB
+        colourspace (IEC 61966-2-1, i.e. "web" RGB, with the sRGB transfer
+        function), constrained to the [0..1] range. This is intended for
+        display-referred user-interface colours such as overlay and on-screen
+        control colours drawn with the Draw Suite, not for processing image
+        pixels.
+
+ACES2065-1 is the reference colourspace of the OFX native colour management
+config (see @ref ofxColour.h), chosen because it is a single, well-specified,
+scene-referred linear space wide enough to carry any colour the host or plug-in
+may need without clamping. Restricting the managed encoding to this one space
+(rather than an arbitrary colourspace name) keeps both hosts and plug-ins simple
+and makes stored colours portable between applications.
+
+A plug-in MUST set this property, if at all, only during the describe-in-context
+/ parameter-definition stage, before the parameter instance exists. A plug-in
+MUST NOT change it on a parameter instance, and in particular MUST NOT change it
+during a render or other action in order to influence a subsequent read: hosts
+may evaluate parameters concurrently, and the encoding is a fixed property of
+the parameter, not a per-read mode.
+
+A plug-in MUST check the status returned when setting this property. A host that
+does not implement it will fail the set; in that case the plug-in MUST fall back
+to ::kOfxParamColourManagementNone behaviour (old-style, unmanaged values). A
+plug-in that sets ::kOfxParamColourManagementManaged or
+::kOfxParamColourManagementSRGB MUST supply every value it sets (defaults
+included) in the declared colourspace, and MUST interpret every value it reads
+as being in that colourspace.
+
+This property does not require the host to advertise any particular
+::kOfxImageEffectPropColourManagementStyle: the managed and sRGB encodings are
+fully specified by this spec and need no OCIO config. A host that supports this
+property MUST accept all three values; a host SHOULD convert the parameter's
+colour from its declared encoding into whatever space it needs (for example to
+draw an accurate swatch, to feed the value to the Draw Suite, or to hand a
+wide-gamut colour to the plug-in at render time).
+
+A host SHOULD store ::kOfxParamColourManagementManaged values as ACES2065-1 and
+::kOfxParamColourManagementSRGB values as sRGB in its project files, so that
+colour params are portable between applications and across versions. When a host
+first loads a project saved before the parameter became colour-managed, it
+SHOULD convert the previously stored values into the parameter's declared
+colourspace (assuming the legacy values were sRGB if it has no better
+information).
+
+The property is ignored on parameter types other than RGB and RGBA. It defaults
+to ::kOfxParamColourManagementNone, so existing plug-ins are unaffected.
+
+    @propdef
+    type: enum
+    dimension: 1
+    introduced: "1.5.1"
+    values:
+      - OfxParamColourManagementNone
+      - OfxParamColourManagementManaged
+      - OfxParamColourManagementSRGB
+*/
+#define kOfxParamPropColourManagement "OfxParamPropColourManagement"
+
+/** @brief Value for ::kOfxParamPropColourManagement: the colour parameter is
+not colour-managed; its values are interpreted as in legacy OpenFX. This is the
+default. */
+#define kOfxParamColourManagementNone "OfxParamColourManagementNone"
+
+/** @brief Value for ::kOfxParamPropColourManagement: the colour parameter's
+values (defaults, current value and keyframes) are in the ACES2065-1 (AP0)
+reference colourspace, scene-linear and not constrained to [0..1]. */
+#define kOfxParamColourManagementManaged "OfxParamColourManagementManaged"
+
+/** @brief Value for ::kOfxParamPropColourManagement: the colour parameter's
+values are in the sRGB colourspace, constrained to [0..1], intended for
+display-referred user-interface colours such as Draw Suite overlays. */
+#define kOfxParamColourManagementSRGB "OfxParamColourManagementSRGB"
+
 /** @brief Describes how the double parameter should be interpreted by a host.
 
    - Valid Values -This must be one of
@@ -1453,6 +1544,26 @@ changes a keyframe.  The keyframe indices will not change within a single action
       - ParamsNumeric_REF
 */
 
+/** @propset ParamsRGB
+    write: plugin
+    props:
+      - OfxParamPropColourManagement
+      - ParamsCommon_REF
+      - ParamsAllButGroupPage_REF
+      - ParamsValue_REF
+      - ParamsNumeric_REF
+*/
+
+/** @propset ParamsRGBA
+    write: plugin
+    props:
+      - OfxParamPropColourManagement
+      - ParamsCommon_REF
+      - ParamsAllButGroupPage_REF
+      - ParamsValue_REF
+      - ParamsNumeric_REF
+*/
+
 /** @propset ParamsChoice
     write: plugin
     props: