Add kOfxParamPropChoiceOrder

.github/workflows/build.yml

@@ -29,6 +29,7 @@ jobs:
             cxx-compiler: clang++
             cc-compiler: clang
             compiler-desc: Clang
+            checkout_version: 3
             cuda: false
           - name_prefix: Linux CentOS 7 VFX CY2022
             release_prefix: linux-vfx2022
@@ -44,6 +45,7 @@ jobs:
             cxx-compiler: clang++
             cc-compiler: clang
             compiler-desc: Clang
+            checkout_version: 3
             cuda: false
           - name_prefix: Linux Rocky 8 VFX CY2023
             release_prefix: linux-vfx2023
@@ -59,6 +61,7 @@ jobs:
             cxx-compiler: clang++
             cc-compiler: clang
             compiler-desc: Clang
+            checkout_version: 4
             cuda: false
           - name_prefix: Linux Ubuntu
             release_prefix: linux-ubuntu
@@ -73,6 +76,7 @@ jobs:
             cxx-compiler: clang++
             cc-compiler: clang
             compiler-desc: Clang
+            checkout_version: 4
             cuda: true
           - name_prefix: MacOS
             release_prefix: mac
@@ -86,6 +90,7 @@ jobs:
             cxx-compiler: clang++
             cc-compiler: clang
             compiler-desc: Clang
+            checkout_version: 4
             cuda: false
           - name_prefix: Windows
             release_prefix: windows
@@ -99,6 +104,7 @@ jobs:
             cxx-compiler: clang++
             cc-compiler: clang
             compiler-desc: Clang
+            checkout_version: 4
             cuda: true
           - name_prefix: Windows no CUDA
             release_prefix: windows-no-cuda
@@ -112,16 +118,28 @@ jobs:
             cxx-compiler: clang++
             cc-compiler: clang
             compiler-desc: Clang
+            checkout_version: 4
             cuda: false
     defaults:
       run:
         shell: bash
     steps:
-      - name: Checkout code
+      - name: Checkout code (v4)
+        uses: actions/checkout@v4
+        if: matrix.checkout_version == 4
+        with:
+          clean: true
+          fetch-depth: 0
+      - name: Checkout code (v3)
         uses: actions/checkout@v3
+        if: matrix.checkout_version == 3
+        with:
+          clean: true
+          fetch-depth: 0
 
       - name: setup env vars
         run: |
+          git config --global --add safe.directory $PWD # needed for checkout v3, doesn't hurt anyway
           BUILDTYPE_LC=$(echo '${{ matrix.buildtype }}'|tr [:upper:] [:lower:])
           echo "BUILDTYPE_LC=$BUILDTYPE_LC" >> $GITHUB_ENV
           echo "OSNAME=$(echo '${{ matrix.os }}'|sed 's/-.*//')" >> $GITHUB_ENV
@@ -214,6 +232,14 @@ jobs:
             cmake --build $BUILD_DIR --target install --parallel
           fi
 
+      - name: Install with cmake
+        run: |
+          if [[ ${{ matrix.ostype }} = windows ]]; then
+            cmake --install $BUILD_DIR --config Release
+          else
+            cmake --install $BUILD_DIR
+          fi
+
       - name: Build with make
         run: |
           if [[ ${{ matrix.ostype }} = windows ]]; then
@@ -229,7 +255,7 @@ jobs:
           cp -R Support/include ${{ env.BUILD_DIR }}/Support/include
           cp -R HostSupport/include ${{ env.BUILD_DIR }}/HostSupport/include
 
-      - name: Archive libs, plugins, and header files to artifact
+      - name: Archive header files and libs to artifact
         uses: actions/upload-artifact@v3
         with:
           name: openfx-${{ matrix.release_prefix }}-${{ env.BUILDTYPE_LC }}-${{ env.GIT_COMMIT_ID }}
@@ -241,9 +267,15 @@ jobs:
             !${{ env.BUILD_DIR }}/include/*.dtd
             ${{ env.BUILD_DIR }}/Support/include
             ${{ env.BUILD_DIR }}/HostSupport/include
-            ${{ env.BUILD_DIR }}/**/*.ofx
             ${{ env.BUILD_DIR }}/**/lib*
 
+      - name: Archive built/installed plugins
+        uses: actions/upload-artifact@v3
+        with:
+          name: openfx_plugins-${{ matrix.release_prefix }}-${{ env.BUILDTYPE_LC }}-${{ env.GIT_COMMIT_ID }}
+          path: |
+            build/Install
+
       # - name: Archive all build artifacts (for debugging CI)
       #   uses: actions/upload-artifact@v3
       #   with:

Documentation/sources/Guide/README.txt

@@ -9,94 +9,11 @@ There are two sub-directories...
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 BUILDING THE PLUGINS
 
-For Windows instructions, see below.
-
-
-To build the example plugins you will need,
-   - a C++ compiler
-   - gmake (or nmake on Windows)
-   - the ofx header files.
-
-
-Within Code there is a subdirectory per plugin.
-
-
-The assumption is that you have checked out all the OFX
-source code in one lump and so the
-OFX header files will be in a standard relative path to
-the plugin sources. If this is not the case you will
-need to modify the file...
-
-   Code/MakefileCommon
-
-and change the line
-
-   OFX_INC_DIR = -I../../../include
-
-to point to the directory where you have put the headers.
-
-
-To build all the examples simply go...
-
-    cd Code
-    make
-
-this will compile all the plugins and place them in
-a directory called 'built_plugins'.
-
-
-You can build individual plugins by changing into the
-relevant subdirectory and simply issuing a 'make' command.
-
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-BUILDING ON WINDOWS
-
-NMakefiles are included for use with Windows' nmake utility.
-This should build on any Visual Studio version (at least 2008 or newer).
-
-Open a Visual Studio command-line window of the appropriate bitness
-that you want (32 for a 32-bit OFX host, 64 for a 64-bit host).  From
-the Start menu, go to Microsoft Visual Studio XXXX -> Visual Studio
-Tools -> Visual Studio XXX Command Prompt (choose the appropriate
-bitness here).
-
-In that window, cd to the openfx/Guide/Code dir, and type:
-
-  nmake /F nmakefile install
-
-This will build and install the plugins into the standard OFX plugins
-dir (c:\Program Files\Common Files\OFX\Plugins).
-
-To clean up:
-
-  nmake /F nmakefile clean
+The plugins and support libs are set up to use cmake to generate and run builds.
+See the top-level README.md in the repo, and use `scripts/build-cmake.sh`.
 
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 BUILDING THE DOCUMENTATION
 
-To build the documentation you will need...
-   - gmake
-   - asciidoctor
-
-
-The documentation is written in asciidoctor markdown, which can be used to
-generate HTML, docbook XML and more. You will need to download and install
-asciidoctor to build the doc. Visit...
-
-    http://asciidoctor.org/
-
-for installation instructions.
-
-
-There is a gnu Makefile currently configured to generate html files. To build
-the documentation simply go...
-
-   cd Doc
-   make
-
-this will generate a subdirectory called 'html' which will contain the
-guides in html format.
-
-
-
-Last Edit 11/11/14
+See the file Documentation/README, and use `Documentation/build.sh`.
+The docs are also auto-generated on commit to the main branch on github.

Documentation/sources/Reference/ofxParameter.rst

@@ -75,7 +75,7 @@ properties, and getting derivatives and integrals of param values.
 Parameter Types
 ---------------
 
-There are seventeen types of parameter. These are
+There are eighteen types of parameter. These are
 
 * .. doxygendefine:: kOfxParamTypeInteger
 * .. doxygendefine:: kOfxParamTypeInteger2D
@@ -87,6 +87,7 @@ There are seventeen types of parameter. These are
 * .. doxygendefine:: kOfxParamTypeRGBA
 * .. doxygendefine:: kOfxParamTypeBoolean
 * .. doxygendefine:: kOfxParamTypeChoice
+* .. doxygendefine:: kOfxParamTypeStrChoice
 * .. doxygendefine:: kOfxParamTypeString
 * .. doxygendefine:: kOfxParamTypeCustom
 * .. doxygendefine:: kOfxParamTypePushButton
@@ -166,8 +167,9 @@ Choice Parameters
 
 This is typed by :c:macro:`kOfxParamTypeChoice`.
 
-Choice parameters are integer values from 0 to N-1, which correspond to
-N labeled options.
+Choice parameters are integer values from 0 to N-1, which correspond
+to N labeled options, but see :c:macro:`kOfxParamPropChoiceOrder` and
+the section below this for how to change that.
 
 Choice parameters have their individual options set via the
 :c:macro:`kOfxParamPropChoiceOption` property,
@@ -184,6 +186,123 @@ for example
 It is an error to have gaps in the choices after the describe action has
 returned.
 
+Note: plugins can change the *text* of options strings in new versions
+with no compatibility impact, since the host should only store the
+index. But they should not change the *order* of options without using
+:c:macro:`kOfxParamPropChoiceOrder`.
+
+Setting Choice Param Order
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As of OFX v1.5, plugins can optionally specify the order in which the host
+should display each choice option, using
+:c:macro:`kOfxParamPropChoiceOrder`.
+
+This property contains a set of integers, of the same length as the
+options for the choice parameter. If the host supports this property,
+it should sort the options and the order list together, and display
+the options in increasing order.
+
+This property is useful when changing order of choice param options, or adding new options in the middle,
+in a new version of the plugin.
+
+    ::
+
+       // Plugin v1:
+       Option = {"OptA", "OptB", "OptC"}
+       Order  = {0, 1, 2} // default, or explicit
+
+       // Plugin v2:
+       // add NewOpt at the end of the list, but specify order so it comes one before the end in the UI
+       // Will display OptA / OptB / NewOpt / OptC
+       Option = {"OptA", "OptB", "OptC", "NewOpt"}
+       Order  = {0, 1, 3, 2} // or anything that sorts the same, e.g. {1, 100, 300, 200}
+
+In this case if the user had selected "OptC" in v1, and then loaded the
+project in v2, "OptC" will still be selected even though it is now the 4th
+option, and the plugin will get the param value 2, as it did in its previous
+version.
+
+The default, if unspecified, is ordinal integers starting from zero,
+so the options are displayed in their natural order.
+
+Values may be arbitrary 32-bit integers. The same value must not occur
+more than once in the order list; behavior is undefined if the same
+value occurs twice in the list. Plugins should use non-negative
+values; some hosts may choose to hide options with negative Order
+values.
+
+Note that :c:macro:`kOfxParamPropChoiceOrder` does not affect project
+storage or operation; it is only used by the host UI. This way it is 100%
+backward compatible; even if the plugin sets it and the host doesn't support it,
+the plugin will still work as usual. Its options will just appear with the new
+ones at the end rather than the preferred order.
+
+To query whether a host supports this, a plugin should attempt to set the
+property and check the return status. If the host does not support
+:c:macro:`kOfxParamPropChoiceOrder`, a plugin should not insert new
+values into the middle of the options list, nor reorder the options,
+in a new version, otherwise old projects will not load properly.
+
+Note: this property does not help if a plugin wants to *remove* an
+option. One way to handle that case is to define a new choice param in
+v2 and hide the old v1 param, then use some custom logic to populate
+the v2 param appropriately.
+
+Also in 1.5, see the new :c:macro:`kOfxParamTypeStrChoice` param type
+for another way to do this: the plugin specifies a set of string
+values as well as user-visible options, and the host stores the string
+value. Plugins can then change the UI order at will in new versions,
+by reordering the options and enum arrays.
+
+Available since 1.5.
+
+
+String-Valued Choice Parameters
+-------------------------------
+
+This is typed by :c:macro:`kOfxParamTypeStrChoice`.
+
+String Choice ("StrChoice") parameters are string-valued, unlike
+standard Choice parameters. This way plugins may change the text and
+order of the choices in new versions as desired, without sacrificing
+compatibility. The host stores the string value rather than the index
+of the option, and when loading a project, finds and selects the
+option with the corresponding enum.
+
+Choice parameters have their individual options and enums set via the
+:c:macro:`kOfxParamPropChoiceOption` and :c:macro:`kOfxParamPropChoiceEnum` properties,
+for example
+
+    ::
+
+        gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 0, "1st Choice");
+        gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 1, "2nd Choice");
+        gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceOption, 2, "3nd Choice");
+        ...
+        // enums: string values to be returned as param value, and stored by the host in the project
+        gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceEnum, 0, "choice-1");
+        gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceEnum, 1, "choice-2");
+        gPropHost->propSetString(myChoiceParam, kOfxParamPropChoiceEnum, 2, "choice-3");
+
+The default value of a StrChoice param must be one of the specified
+enums, or the behavior is undefined.
+
+It is an error to have gaps in the choices after the describe action
+has returned. The Option and Enum arrays must be of the same length,
+otherwise the behavior is undefined.
+
+If a plugin removes enums in later versions and a project is saved
+with the removed enum, behavior is undefined, but it is recommended
+that the host use the default value in that case.
+
+To check for availability of this param type, a plugin may check the
+host property :c:macro:`kOfxParamHostPropSupportsStrChoice`.
+
+StrChoice parameters may also be reordered using
+:c:macro:`kOfxParamPropChoiceOrder`; see the previous section.
+
+Available since 1.5.
 
 String Parameters
 -----------------
@@ -205,6 +324,8 @@ these are
 
 -  .. doxygendefine:: kOfxParamStringIsLabel
 
+-  .. doxygendefine:: kOfxParamStringIsRichTextFormat
+
 Group Parameters
 ----------------
 
@@ -310,6 +431,7 @@ they do **not** animate by default. They are...
 -  :c:macro:`kOfxParamTypeString`
 -  :c:macro:`kOfxParamTypeBoolean`
 -  :c:macro:`kOfxParamTypeChoice`
+-  :c:macro:`kOfxParamTypeStrChoice`
 
 By default the
 :cpp:func:`OfxParameterSuiteV1::paramGetValue`
@@ -533,6 +655,8 @@ The variant property types are as follows....
     int X 1
 -  :c:macro:`kOfxParamTypeChoice`
     int X 1
+-  :c:macro:`kOfxParamTypeStrChoice`
+    char \* X 1
 -  :c:macro:`kOfxParamTypeRGBA`
     double X 4 (normalised to 0..1 range)
 -  :c:macro:`kOfxParamTypeRGB`