Fix incorrect @propdef enum value names and guard against regressions (#247)

Several enum properties listed @propdef `values:` that did not match the
actual string literals their value #defines expand to, so the generated
openfx-cpp metadata advertised valid-value strings no host or plugin ever
uses. The macro string values are ABI and are left untouched; only the
metadata is corrected to match them:

  - Field props (FieldOrder, PropField, FieldExtraction, FieldToRender):
    OfxImageField* -> OfxField*  (kOfxImageFieldNone == "OfxFieldNone")
  - PreMultiplication: OfxImage{,Un}PreMultiplied
    -> OfxImageAlpha{,Un}Premultiplied
  - HostPropNativeOrigin: add the leading "k" the string literals actually
    have (kOfxHostNativeOriginBottomLeft == "kOfxImageEffectHostProp...")
  - ColourManagementStyle: drop the erroneous "Prop"
    (kOfxImageEffectColourManagementNone == "OfxImageEffectColourManagementNone")

The three irregularly-named value clusters (Field, PreMultiplication,
NativeOrigin) get a header comment noting the name/value mismatch is
ABI-locked and must not be copied as an example. (ColourManagementStyle
is conventionally named; only its @propdef had a typo.)

Guard: gen-props.py now emits a static_assert for every enum value
(value string == its #define), mirroring the existing per-property
asserts, and aborts generation if an `Ofx`-prefixed value names no
macro. A reintroduced typo therefore fails the generator and, failing
that, fails to compile. Verified by reintroducing a bad value.

Also removed dead `nonProperties` entries in gen-props.py that excluded
misspelled (extra-"Prop") ColourManagement value macros which never
existed; the real value macros contain no "Prop" and were never
collected as properties. Output is byte-identical.

Regenerated openfx-cpp metadata and the property reference docs. The
docs regen also picks up kOfxImageEffectPluginPropObsolete, whose
generated docs were stale on main.

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/ofxPropertiesReferenceGenerated.rst

@@ -112,6 +112,17 @@ Integer (Boolean) Properties
 - **Used in Property Sets**: :ref:`EffectDescriptor <propset_EffectDescriptor>` (plugin)
 - **Doc**: For detailed doc, see :c:macro:`kOfxImageEffectPluginPropHostFrameThreading`.
 
+.. _prop_OfxImageEffectPluginPropObsolete:
+
+**OfxImageEffectPluginPropObsolete**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- **C #define**: :c:macro:`kOfxImageEffectPluginPropObsolete`
+- **Type**: bool
+- **Dimension**: 1
+- **Used in Property Sets**: :ref:`EffectDescriptor <propset_EffectDescriptor>` (plugin)
+- **Doc**: For detailed doc, see :c:macro:`kOfxImageEffectPluginPropObsolete`.
+
 .. _prop_OfxImageEffectPluginPropSingleInstance:
 
 **OfxImageEffectPluginPropSingleInstance**
@@ -957,12 +968,12 @@ Enumeration Properties
 - **Dimension**: 1
 - **Used in Property Sets**: :ref:`ClipDescriptor <propset_ClipDescriptor>` (plugin), :ref:`ClipInstance <propset_ClipInstance>` (host)
 - **Valid Values**:
-  - ``OfxImageFieldNone``
-  - ``OfxImageFieldLower``
-  - ``OfxImageFieldUpper``
-  - ``OfxImageFieldBoth``
-  - ``OfxImageFieldSingle``
-  - ``OfxImageFieldDoubled``
+  - ``OfxFieldNone``
+  - ``OfxFieldLower``
+  - ``OfxFieldUpper``
+  - ``OfxFieldBoth``
+  - ``OfxFieldSingle``
+  - ``OfxFieldDoubled``
 - **Doc**: For detailed doc, see :c:macro:`kOfxImageClipPropFieldExtraction`.
 
 .. _prop_OfxImageClipPropFieldOrder:
@@ -975,9 +986,9 @@ Enumeration Properties
 - **Dimension**: 1
 - **Used in Property Sets**: :ref:`ClipInstance <propset_ClipInstance>` (host)
 - **Valid Values**:
-  - ``OfxImageFieldNone``
-  - ``OfxImageFieldLower``
-  - ``OfxImageFieldUpper``
+  - ``OfxFieldNone``
+  - ``OfxFieldLower``
+  - ``OfxFieldUpper``
 - **Doc**: For detailed doc, see :c:macro:`kOfxImageClipPropFieldOrder`.
 
 .. _prop_OfxImageClipPropUnmappedComponents:
@@ -1023,9 +1034,9 @@ Enumeration Properties
 - **Dimension**: 1
 - **Used in Property Sets**: :ref:`ImageEffectHost <propset_ImageEffectHost>` (host)
 - **Valid Values**:
-  - ``OfxImageEffectHostPropNativeOriginBottomLeft``
-  - ``OfxImageEffectHostPropNativeOriginTopLeft``
-  - ``OfxImageEffectHostPropNativeOriginCenter``
+  - ``kOfxImageEffectHostPropNativeOriginBottomLeft``
+  - ``kOfxImageEffectHostPropNativeOriginTopLeft``
+  - ``kOfxImageEffectHostPropNativeOriginCenter``
 - **Doc**: For detailed doc, see :c:macro:`kOfxImageEffectHostPropNativeOrigin`.
 
 .. _prop_OfxImageEffectPluginRenderThreadSafety:
@@ -1068,11 +1079,11 @@ Enumeration Properties
 - **Dimension**: 1
 - **Used in Property Sets**: :ref:`EffectDescriptor <propset_EffectDescriptor>` (plugin), :ref:`EffectInstance <propset_EffectInstance>` (host), :ref:`ImageEffectHost <propset_ImageEffectHost>` (host)
 - **Valid Values**:
-  - ``OfxImageEffectPropColourManagementNone``
-  - ``OfxImageEffectPropColourManagementBasic``
-  - ``OfxImageEffectPropColourManagementCore``
-  - ``OfxImageEffectPropColourManagementFull``
-  - ``OfxImageEffectPropColourManagementOCIO``
+  - ``OfxImageEffectColourManagementNone``
+  - ``OfxImageEffectColourManagementBasic``
+  - ``OfxImageEffectColourManagementCore``
+  - ``OfxImageEffectColourManagementFull``
+  - ``OfxImageEffectColourManagementOCIO``
 - **Introduced in**: version 1.5
 - **Doc**: For detailed doc, see :c:macro:`kOfxImageEffectPropColourManagementStyle`.
 
@@ -1147,10 +1158,10 @@ Enumeration Properties
 - **Type**: enum
 - **Dimension**: 1
 - **Valid Values**:
-  - ``OfxImageFieldNone``
-  - ``OfxImageFieldBoth``
-  - ``OfxImageFieldLower``
-  - ``OfxImageFieldUpper``
+  - ``OfxFieldNone``
+  - ``OfxFieldBoth``
+  - ``OfxFieldLower``
+  - ``OfxFieldUpper``
 - **Doc**: For detailed doc, see :c:macro:`kOfxImageEffectPropFieldToRender`.
 
 .. _prop_OfxImageEffectPropMetalRenderSupported:
@@ -1255,8 +1266,8 @@ Enumeration Properties
 - **Used in Property Sets**: :ref:`ClipInstance <propset_ClipInstance>` (host), :ref:`Image <propset_Image>` (host)
 - **Valid Values**:
   - ``OfxImageOpaque``
-  - ``OfxImagePreMultiplied``
-  - ``OfxImageUnPreMultiplied``
+  - ``OfxImageAlphaPremultiplied``
+  - ``OfxImageAlphaUnPremultiplied``
 - **Doc**: For detailed doc, see :c:macro:`kOfxImageEffectPropPreMultiplication`.
 
 .. _prop_OfxImageEffectPropSupportedComponents:
@@ -1334,10 +1345,10 @@ Enumeration Properties
 - **Dimension**: 1
 - **Used in Property Sets**: :ref:`Image <propset_Image>` (host)
 - **Valid Values**:
-  - ``OfxImageFieldNone``
-  - ``OfxImageFieldBoth``
-  - ``OfxImageFieldLower``
-  - ``OfxImageFieldUpper``
+  - ``OfxFieldNone``
+  - ``OfxFieldBoth``
+  - ``OfxFieldLower``
+  - ``OfxFieldUpper``
 - **Doc**: For detailed doc, see :c:macro:`kOfxImagePropField`.
 
 .. _prop_OfxOpenGLPropPixelDepth:

Documentation/sources/Reference/ofxPropertySetsGenerated.rst

@@ -104,6 +104,7 @@ These property sets represent collections of properties associated with various
 - :ref:`OfxImageEffectPluginPropFieldRenderTwiceAlways <prop_OfxImageEffectPluginPropFieldRenderTwiceAlways>` - Type: bool, Dimension: 1 (doc: :c:macro:`kOfxImageEffectPluginPropFieldRenderTwiceAlways`)
 - :ref:`OfxImageEffectPluginPropGrouping <prop_OfxImageEffectPluginPropGrouping>` - Type: string, Dimension: 1 (doc: :c:macro:`kOfxImageEffectPluginPropGrouping`)
 - :ref:`OfxImageEffectPluginPropHostFrameThreading <prop_OfxImageEffectPluginPropHostFrameThreading>` - Type: bool, Dimension: 1 (doc: :c:macro:`kOfxImageEffectPluginPropHostFrameThreading`)
+- :ref:`OfxImageEffectPluginPropObsolete <prop_OfxImageEffectPluginPropObsolete>` - Type: bool, Dimension: 1 (doc: :c:macro:`kOfxImageEffectPluginPropObsolete`)
 - :ref:`OfxImageEffectPluginPropOverlayInteractV1 <prop_OfxImageEffectPluginPropOverlayInteractV1>` - Type: pointer, Dimension: 1 (doc: :c:macro:`kOfxImageEffectPluginPropOverlayInteractV1`)
 - :ref:`OfxImageEffectPluginPropOverlayInteractV2 <prop_OfxImageEffectPluginPropOverlayInteractV2>` - Type: pointer, Dimension: 1 (doc: :c:macro:`kOfxImageEffectPluginPropOverlayInteractV2`)
 - :ref:`OfxImageEffectPluginPropSingleInstance <prop_OfxImageEffectPluginPropSingleInstance>` - Type: bool, Dimension: 1 (doc: :c:macro:`kOfxImageEffectPluginPropSingleInstance`)

include/ofxColour.h

@@ -55,11 +55,11 @@ effect instance.
    type: enum
    dimension: 1
    values:
-     - OfxImageEffectPropColourManagementNone
-     - OfxImageEffectPropColourManagementBasic
-     - OfxImageEffectPropColourManagementCore
-     - OfxImageEffectPropColourManagementFull
-     - OfxImageEffectPropColourManagementOCIO
+     - OfxImageEffectColourManagementNone
+     - OfxImageEffectColourManagementBasic
+     - OfxImageEffectColourManagementCore
+     - OfxImageEffectColourManagementFull
+     - OfxImageEffectColourManagementOCIO
    introduced: "1.5"
 */
 #define kOfxImageEffectPropColourManagementStyle "OfxImageEffectPropColourManagementStyle"

include/ofxImageEffect.h

@@ -897,9 +897,14 @@ This property is set to indicate whether the effect is currently being rendered
 */
 #define kOfxImageEffectPropSequentialRenderStatus "OfxImageEffectPropSequentialRenderStatus"
 
-#define kOfxHostNativeOriginBottomLeft   "kOfxImageEffectHostPropNativeOriginBottomLeft"  
-#define kOfxHostNativeOriginTopLeft      "kOfxImageEffectHostPropNativeOriginTopLeft"  
-#define kOfxHostNativeOriginCenter       "kOfxImageEffectHostPropNativeOriginCenter"  
+/* NOTE: these constants are irregularly named: the macro name differs from the
+   string value, and unusually the string value itself begins with "k" (e.g.
+   kOfxHostNativeOriginBottomLeft is "kOfxImageEffectHostPropNativeOriginBottomLeft").
+   The string values are fixed by ABI and cannot change. Do not copy this in new
+   constants; values should not begin with "k". */
+#define kOfxHostNativeOriginBottomLeft   "kOfxImageEffectHostPropNativeOriginBottomLeft"
+#define kOfxHostNativeOriginTopLeft      "kOfxImageEffectHostPropNativeOriginTopLeft"
+#define kOfxHostNativeOriginCenter       "kOfxImageEffectHostPropNativeOriginCenter"
 /** @brief Property that indicates the host native UI space - this is only a UI hint, has no impact on pixel processing
 
 This property is set to kOfxHostNativeOriginBottomLeft pre V1.4 and was to be discovered by plug-ins. This is useful for drawing overlay for points... so everything matches the rest of the app (for example expression linking to other tools, or simply match the reported location of the host viewer).
@@ -912,9 +917,9 @@ This property is set to kOfxHostNativeOriginBottomLeft pre V1.4 and was to be di
    type: enum
    dimension: 1
    values:
-     - OfxImageEffectHostPropNativeOriginBottomLeft
-     - OfxImageEffectHostPropNativeOriginTopLeft
-     - OfxImageEffectHostPropNativeOriginCenter
+     - kOfxImageEffectHostPropNativeOriginBottomLeft
+     - kOfxImageEffectHostPropNativeOriginTopLeft
+     - kOfxImageEffectHostPropNativeOriginCenter
 */
 #define kOfxImageEffectHostPropNativeOrigin  "OfxImageEffectHostPropNativeOrigin"
 
@@ -1178,14 +1183,18 @@ See the documentation on clip preferences for more details on how this is used w
    dimension: 1
    values:
      - OfxImageOpaque
-     - OfxImagePreMultiplied
-     - OfxImageUnPreMultiplied
+     - OfxImageAlphaPremultiplied
+     - OfxImageAlphaUnPremultiplied
 */
 #define kOfxImageEffectPropPreMultiplication "OfxImageEffectPropPreMultiplication"
 
 /** Used to flag the alpha of an image as opaque */
 #define kOfxImageOpaque  "OfxImageOpaque"
 
+/* NOTE: the two constants below are irregularly named: the string value differs
+   from the macro name (it inserts "Alpha" and changes case, e.g.
+   kOfxImagePreMultiplied is "OfxImageAlphaPremultiplied"). The string values are
+   fixed by ABI and cannot change. Do not copy this mismatch in new constants. */
 /** Used to flag an image as premultiplied */
 #define kOfxImagePreMultiplied "OfxImageAlphaPremultiplied"
 
@@ -1491,9 +1500,9 @@ This contains the duration of the plug-in effect, in frames.
     type: enum
     dimension: 1
     values:
-      - OfxImageFieldNone
-      - OfxImageFieldLower
-      - OfxImageFieldUpper
+      - OfxFieldNone
+      - OfxFieldLower
+      - OfxFieldUpper
  */
 #define kOfxImageClipPropFieldOrder "OfxImageClipPropFieldOrder"
 
@@ -1575,10 +1584,10 @@ Row bytes is not supported for OpenCL Images.
     type: enum
     dimension: 1
     values:
-      - OfxImageFieldNone
-      - OfxImageFieldBoth
-      - OfxImageFieldLower
-      - OfxImageFieldUpper
+      - OfxFieldNone
+      - OfxFieldBoth
+      - OfxFieldLower
+      - OfxFieldUpper
  */
 #define kOfxImagePropField "OfxImagePropField"
 
@@ -1607,12 +1616,12 @@ Note that if it fetches kOfxImageFieldSingle and the host stores images natively
     type: enum
     dimension: 1
     values:
-      - OfxImageFieldNone
-      - OfxImageFieldLower
-      - OfxImageFieldUpper
-      - OfxImageFieldBoth
-      - OfxImageFieldSingle
-      - OfxImageFieldDoubled
+      - OfxFieldNone
+      - OfxFieldLower
+      - OfxFieldUpper
+      - OfxFieldBoth
+      - OfxFieldSingle
+      - OfxFieldDoubled
  */
 #define kOfxImageClipPropFieldExtraction "OfxImageClipPropFieldExtraction"
 
@@ -1627,10 +1636,10 @@ Note that if it fetches kOfxImageFieldSingle and the host stores images natively
     type: enum
     dimension: 1
     values:
-      - OfxImageFieldNone
-      - OfxImageFieldBoth
-      - OfxImageFieldLower
-      - OfxImageFieldUpper
+      - OfxFieldNone
+      - OfxFieldBoth
+      - OfxFieldLower
+      - OfxFieldUpper
  */
 #define kOfxImageEffectPropFieldToRender "OfxImageEffectPropFieldToRender"
 
@@ -1672,6 +1681,10 @@ This will be in \ref PixelCoordinates
  */
 #define kOfxImageEffectPropRenderWindow "OfxImageEffectPropRenderWindow"
 
+/* NOTE: these kOfxImageField* constants are irregularly named: the macro name
+   contains "Image" but the string value does not (e.g. kOfxImageFieldNone is
+   "OfxFieldNone", not "OfxImageFieldNone"). The string values are fixed by ABI
+   and cannot change. Do not copy this name/value mismatch in new constants. */
 /** String used to label imagery as having no fields */
 #define kOfxImageFieldNone "OfxFieldNone"
 /** String used to label the lower field (scan lines 0,2,4...) of fielded imagery */