Add property checker/metadata system and C++ helpers

CMakeLists.txt

@@ -65,6 +65,7 @@ find_package(EXPAT)
 find_package(opengl_system REQUIRED)
 find_package(cimg REQUIRED)
 find_package(spdlog REQUIRED)
+find_package(tcb-span REQUIRED)
 
 # Macros
 include(OpenFX)

Documentation/README.md

@@ -26,6 +26,8 @@ system python if you like.)
 * Make sure your virtualenv above is activated: `source ofx-docgen/bin/activate`
 * Generate references:
   `python Documentation/genPropertiesReference.py -i include -o Documentation/sources/Reference/ofxPropertiesReference.rst -r`
+* Generate property documentation from YAML definitions:
+  `python scripts/gen-props-doc.py -v` (requires PyYAML)
 * Build the doxygen docs: `cd include; doxygen ofx.doxy; cd -` (you'll see
   some warnings)
 * Build the sphinx docs:

Documentation/build.sh

@@ -41,7 +41,17 @@ $UV_RUN python genPropertiesReference.py \
        > /tmp/ofx-doc-build.out 2>&1
 grep -v -E "$EXPECTED_ERRS" /tmp/ofx-doc-build.out || true
 
-# Build the Doxygen docs
+# Generate property documentation from YAML definitions
+cd ..
+if command -v uv > /dev/null 2>&1; then
+    uv run scripts/gen-props-doc.py -v >> /tmp/ofx-doc-build.out 2>&1
+else
+    # Fall back to regular python if uv is not available
+    python scripts/gen-props-doc.py -v >> /tmp/ofx-doc-build.out 2>&1
+fi
+cd Documentation
+
+# Build the Doxygen docs into $TOP/Documentation/doxygen_build
 EXPECTED_ERRS="malformed hyperlink target|Duplicate explicit|Definition list ends|unable to resolve|could not be resolved"
 cd ../include
 doxygen ofx.doxy > /tmp/ofx-doc-build.out 2>&1

Documentation/genPropertiesReference.py

@@ -4,68 +4,88 @@
 
 badlyNamedProperties = ["kOfxImageEffectFrameVarying", "kOfxImageEffectPluginRenderThreadSafety"]
 
-def getPropertiesFromDir(sourcePath, recursive, props):
+def getPropertiesFromFile(path):
+    """Get all OpenFX property definitions from C header file.
 
-    if os.path.isdir(sourcePath):
-        files=sorted(os.listdir(sourcePath))
-        for f in files:
-            absF = sourcePath + '/' + f
-            if not recursive and os.path.isdir(absF):
+    Uses a heuristic to identify property #define lines:
+    anything starting with '#define' and containing 'Prop' in the name.
+    """
+    props = set()
+    with open(path) as f:
+        try:
+            lines = f.readlines()
+        except UnicodeDecodeError as e:
+            logging.error(f'error reading {path}: {e}')
+            raise e
+        for l in lines:
+            # Detect lines that correspond to a property definition, e.g:
+            # #define kOfxPropLala "OfxPropLala"
+            splits=l.split()
+            if len(splits) < 3:
                 continue
-            else:
-                getPropertiesFromDir(absF,recursive,props)
-    elif os.path.isfile(sourcePath):
-        ext = os.path.splitext(sourcePath)[1]
-        if ext.lower() in ('.c', '.cxx', '.cpp', '.h', '.hxx', '.hpp'):
-            with open(sourcePath) as f:
-                try:
-                    lines = f.readlines()
-                except UnicodeDecodeError as e:
-                    print('WARNING: error in', sourcePath, ':')
-                    raise e
-                for l in lines:
-                    # Detect lines that correspond to a property definition, e.g:
-                    # #define kOfxPropLala "OfxPropLala"
-                    splits=l.split(' ')
-                    if len(splits) != 3:
-                        continue
-                    if splits[0] != '#define':
-                        continue
-                    if 'Prop' in splits[1] and splits[1] != 'kOfxPropertySuite':
-                        #if l.startswith('#define kOfx') and 'Prop' in l:
-                        props.append(splits[1])
-    else:
-        raise ValueError('No such file or directory: %s' % sourcePath)
+            if splits[0] != '#define':
+                continue
+            # ignore these
+            nonProperties = ('kOfxPropertySuite',
+                             # prop values, not props
+                             'kOfxImageEffectPropColourManagementNone',
+                             'kOfxImageEffectPropColourManagementBasic',
+                             'kOfxImageEffectPropColourManagementCore',
+                             'kOfxImageEffectPropColourManagementFull',
+                             'kOfxImageEffectPropColourManagementOCIO',
+                             )
+            if splits[1] in nonProperties:
+                continue
+            # these are props, as well as anything with Prop in the name
+            badlyNamedProperties = ("kOfxImageEffectFrameVarying",
+                                    "kOfxImageEffectPluginRenderThreadSafety")
+            if 'Prop' in splits[1] \
+               or any(s in splits[1] for s in badlyNamedProperties):
+                props.add(splits[1])
+    return props
+
+def getPropertiesFromDir(dir):
+    """
+    Recursively get all property definitions from source files in a dir.
+    """
+
+    extensions = {'.c', '.h', '.cxx', '.hxx', '.cpp', '.hpp'}
+
+    props = set()
+    for root, _dirs, files in os.walk(dir):
+        for file in files:
+            # Get the file extension
+            file_extension = os.path.splitext(file)[1]
+
+            if file_extension in extensions:
+                file_path = os.path.join(root, file)
+                props |= getPropertiesFromFile(file_path)
+    return list(props)
 
 def main(argv):
 
-    recursive=False
     sourcePath=''
     outputFile=''
     try:
-        opts, args = getopt.getopt(argv,"i:o:r",["sourcePath=","outputFile","recursive"])
+        opts, args = getopt.getopt(argv,"i:o:r",["sourcePath=","outputFile"])
         for opt,value in opts:
             if opt == "-i":
                 sourcePath = value
             elif opt == "-o":
                 outputFile = value
-            elif opt == "-r":
-                    recursive=True
 
     except getopt.GetoptError:
         sys.exit(1)
 
-    props=badlyNamedProperties
-    getPropertiesFromDir(sourcePath, recursive, props)
+    props = getPropertiesFromDir(sourcePath)
 
-    re='/^#define k[\w_]*Ofx[\w_]*Prop/'
     with open(outputFile, 'w') as f:
         f.write('.. _propertiesReference:\n')
         f.write('Properties Reference\n')
         f.write('=====================\n')
-        props.sort()
-        for p in props:
-            f.write('.. doxygendefine:: ' + p + '\n\n')
+        for p in sorted(props):
+            f.write('.. doxygendefine:: ' + p + '\n')
+            f.write('.. property_link:: ' + p + '\n\n')
 
 if __name__ == "__main__":
     main(sys.argv[1:])

Documentation/pipreq.txt

@@ -1,3 +1,4 @@
 sphinx<7
 breathe
 sphinx_rtd_theme
+pyyaml>=6.0

Documentation/sources/Guide/ofxExample5_Circle.rst

@@ -4,7 +4,7 @@
 This guide will introduce the spatial coordinate system used by OFX and
 will illustrate that with a simple circle drawing plugin.
 Its source can be found in the source code file
-`circle.cpp <https://github.com/ofxa/openfx/blob/master/Guide/Code/Example5/circle.cpp>`_.
+`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/main/Documentation/sources/Guide/Code/Example5/circle.cpp>`_.
 This plugin takes a clip and draws a circle over it. The colour, size and position
 of the circle are controlled by several parameters.
 
@@ -127,7 +127,7 @@ depending on what the host says it can do.
 
 Here is the source for the load action…
 
-`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/doc/Documentation/sources/Guide/Code/Example5/circle.cpp#L348>`__
+`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/main/Documentation/sources/Guide/Code/Example5/circle.cpp#L348>`__
 
 .. code:: c++
 
@@ -191,7 +191,7 @@ Note, we are relying on a parameter type that is only available with the
 1.2 version of OFX. Our plugin checks for this version of the API the
 host supports and will fail gracefully during the load action.
 
-`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/doc/Documentation/sources/Guide/Code/Example5/circle.cpp#L471>`__
+`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/main/Documentation/sources/Guide/Code/Example5/circle.cpp#L471>`__
 
 .. code:: c++
 
@@ -252,7 +252,7 @@ are being described relative to the project size. So our circle’s radius
 will default to be a quarter of the nominal project size’s x dimension.
 For a 1080 HD project, this would be a value of 480.
 
-`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/doc/Documentation/sources/Guide/Code/Example5/circle.cpp#L513>`__
+`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/main/Documentation/sources/Guide/Code/Example5/circle.cpp#L513>`__
 
 .. code:: c++
 
@@ -294,7 +294,7 @@ for such parameters to let you simply drag such positions around. We are
 also setting the default values relative to the project size, and in
 this case (0.5, 0.5), it should appear in the centre of the final image.
 
-`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/doc/Documentation/sources/Guide/Code/Example5/circle.cpp#L543>`__
+`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/main/Documentation/sources/Guide/Code/Example5/circle.cpp#L543>`__
 
 .. code:: c++
 
@@ -325,7 +325,7 @@ when you get and set the colour, you need to scale the values up to the
 nominal white point of your image, which is implicitly defined by the
 data type of the image.
 
-`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/doc/Documentation/sources/Guide/Code/Example5/circle.cpp#L564>`__
+`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/main/Documentation/sources/Guide/Code/Example5/circle.cpp#L564>`__
 
 .. code:: c++
 
@@ -382,7 +382,7 @@ To set the output rod, we need to trap the
 :c:macro:`kOfxImageEffectActionGetRegionOfDefinition` action. Our MainEntry
 function now has an extra conditional in there….
 
-`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/doc/Documentation/sources/Guide/Code/Example5/circle.cpp#L978>`__
+`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/main/Documentation/sources/Guide/Code/Example5/circle.cpp#L978>`__
 
 .. code:: c++
 
@@ -397,7 +397,7 @@ definition on those hosts RoDs are fixed.
 
 The code for the action itself is quite simple:
 
-`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/doc/Documentation/sources/Guide/Code/Example5/circle.cpp#L844>`__
+`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/main/Documentation/sources/Guide/Code/Example5/circle.cpp#L844>`__
 
 ::
 
@@ -479,7 +479,7 @@ The action code is fairly boiler plate, it fetches parameter values and
 images from clips before calling the templated PixelProcessing function.
 Which is below:
 
-`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/doc/Documentation/sources/Guide/Code/Example5/circle.cpp#L670>`__
+`circle.cpp <https://github.com/AcademySoftwareFoundation/openfx/blob/main/Documentation/sources/Guide/Code/Example5/circle.cpp#L670>`__
 
 ::
 

Documentation/sources/Reference/index.rst

@@ -28,8 +28,12 @@ the API. The changes to the API are listed in an addendum.
     ofxImageEffectActions
     ofxInteractActions
     suites/ofxSuiteReference
-    ofxPropertiesByObject
+    .. outdated:
+    .. ofxPropertiesByObject
     ofxPropertiesReference
+    ofxPropertiesReferenceGenerated
+    ofxPropertySetsGenerated
     DoxygenIndex
     ofxStatusCodes
-    apiChanges_1_2_Chapter
+    .. not needed:
+    .. apiChanges_1_2_Chapter

Documentation/sources/Reference/ofxInteracts.rst

@@ -5,7 +5,7 @@ Interacts
 When a host presents a graphical user interface to an image effect, it
 may optionally give it the chance to draw its own custom GUI tools and
 to be able to interact with pen and keyboard input. In OFX this is done
-via the OfxInteract suite, which is found in the file `ofxInteract.h <https://github.com/ofxa/openfx/blob/master/include/ofxInteract.h>`_.
+via the OfxInteract suite, which is found in the file `ofxInteract.h <https://github.com/AcademySoftwareFoundation/openfx/blob/main/include/ofxInteract.h>`_.
 
 OFX interacts by default use openGL to perform all drawing in
 interacts, due to its portabilty, robustness and wide implementation.