Clip Property kOfxImageClipPropDisplayTimeOffset

Documentation/sources/Reference/ofxPropertiesReferenceGenerated.rst

@@ -943,6 +943,17 @@ Double Properties
 - **Dimension**: 1
 - **Doc**: For detailed doc, see :c:macro:`kOfxPropTime`.
 
+.. _prop_kOfxImageClipPropDisplayTimeOffset:
+
+**kOfxImageClipPropDisplayTimeOffset**
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- **C #define**: :c:macro:`kOfxImageClipPropDisplayTimeOffset`
+- **Type**: double
+- **Dimension**: 1
+- **Used in Property Sets**: :ref:`ClipInstance <propset_ClipInstance>` (host)
+- **Doc**: For detailed doc, see :c:macro:`kOfxImageClipPropDisplayTimeOffset`.
+
 
 Enumeration Properties
 ----------------------

Documentation/sources/Reference/ofxPropertySetsGenerated.rst

@@ -94,6 +94,7 @@ These property sets represent collections of properties associated with various
 - :ref:`OfxPropName <prop_OfxPropName>` - Type: string, Dimension: 1 (doc: :c:macro:`kOfxPropName`)
 - :ref:`OfxPropShortLabel <prop_OfxPropShortLabel>` - Type: string, Dimension: 1 (doc: :c:macro:`kOfxPropShortLabel`)
 - :ref:`OfxPropType <prop_OfxPropType>` - Type: string, Dimension: 1 (doc: :c:macro:`kOfxPropType`)
+- :ref:`kOfxImageClipPropDisplayTimeOffset <prop_kOfxImageClipPropDisplayTimeOffset>` - Type: double, Dimension: 1 (doc: :c:macro:`kOfxImageClipPropDisplayTimeOffset`)
 
 .. _propset_EffectDescriptor:
 

include/ofxImageEffect.h

@@ -1124,6 +1124,27 @@ then the plugin can detect this via an identifier change and re-evaluate the cac
 */
 #define kOfxImagePropUniqueIdentifier "OfxImagePropUniqueIdentifier"
 
+/** @brief Clip property which indicates the display start frame of the clip
+
+   - Default - 0
+
+This is the frame number the host shows the user for time 0, in the same units
+as ::kOfxPropTime. For example, a host whose session starts at frame 1001 sets
+this to 1001.
+
+Plugins should add this value to internal OFX frame numbers when displayed in a
+plugin user interface, so the user will see the same frame numbers as they see
+in the host's UI, and subtract it from frame numbers the user enters.
+
+The property's string value keeps its leading "k" for compatibility with
+existing hosts and plugins.
+
+   @propdef
+   type: double
+   dimension: 1
+*/
+#define kOfxImageClipPropDisplayTimeOffset "kOfxImageClipPropDisplayTimeOffset"
+
 /** @brief Clip and action argument property which indicates that the clip can be sampled continuously
 
 If this is set to true, then the frame rate of a clip is effectively infinite, so to stop arithmetic
@@ -2215,6 +2236,7 @@ They range from 1000 until 1999
       - OfxImageEffectPropUnmappedFrameRange
       - OfxImageEffectPropUnmappedFrameRate
       - OfxImageClipPropContinuousSamples
+      - kOfxImageClipPropDisplayTimeOffset
 */
 
 /** @propset Image

openfx-cpp/include/openfx/ofxPropSetAccessors.h

@@ -278,6 +278,10 @@ class ClipInstance : public PropertySetAccessor {
         return props_.get<PropId::OfxImageClipPropContinuousSamples>(0, error_if_missing);
     }
 
+    double displayTimeOffset(bool error_if_missing = true) const {
+        return props_.get<PropId::OfxImageClipPropDisplayTimeOffset>(0, error_if_missing);
+    }
+
 };
 
 // Property set accessor for: CustomParamInterpFunc_InArgs

openfx-cpp/include/openfx/ofxPropSetAccessorsHost.h

@@ -335,6 +335,11 @@ class ClipInstance : public PropertySetAccessor {
         return *this;
     }
 
+    ClipInstance& setDisplayTimeOffset(double value, bool error_if_missing = true) {
+        props_.set<PropId::OfxImageClipPropDisplayTimeOffset>(value, 0, error_if_missing);
+        return *this;
+    }
+
 };
 
 // Property set accessor for: CustomParamInterpFunc_InArgs

openfx-cpp/include/openfx/ofxPropsBySet.h

@@ -73,7 +73,8 @@ static inline const std::map<const char *, std::vector<Prop>> prop_sets {
    { "OfxImageClipPropConnected", prop_defs[PropId::OfxImageClipPropConnected], true, false, false },
    { "OfxImageEffectPropUnmappedFrameRange", prop_defs[PropId::OfxImageEffectPropUnmappedFrameRange], true, false, false },
    { "OfxImageEffectPropUnmappedFrameRate", prop_defs[PropId::OfxImageEffectPropUnmappedFrameRate], true, false, false },
-   { "OfxImageClipPropContinuousSamples", prop_defs[PropId::OfxImageClipPropContinuousSamples], true, false, false } } },
+   { "OfxImageClipPropContinuousSamples", prop_defs[PropId::OfxImageClipPropContinuousSamples], true, false, false },
+   { "kOfxImageClipPropDisplayTimeOffset", prop_defs[PropId::OfxImageClipPropDisplayTimeOffset], true, false, false } } },
 // EffectDescriptor
 { "EffectDescriptor", {
    { "OfxPropType", prop_defs[PropId::OfxPropType], false, true, false },

openfx-cpp/include/openfx/ofxPropsMetadata.h

@@ -214,10 +214,11 @@ enum class PropId {
   OfxPropType, // 179
   OfxPropVersion, // 180
   OfxPropVersionLabel, // 181
-  OfxParamPropUseHostOverlayHandle, // 182 (orig name: OfxParamPropUseHostOverlayHandle)
-  OfxPropKeyString, // 183 (orig name: OfxPropKeyString)
-  OfxPropKeySym, // 184 (orig name: OfxPropKeySym)
-  NProps // 185
+  OfxImageClipPropDisplayTimeOffset, // 182 (orig name: OfxImageClipPropDisplayTimeOffset)
+  OfxParamPropUseHostOverlayHandle, // 183 (orig name: OfxParamPropUseHostOverlayHandle)
+  OfxPropKeyString, // 184 (orig name: OfxPropKeyString)
+  OfxPropKeySym, // 185 (orig name: OfxPropKeySym)
+  NProps // 186
 }; // PropId
 
 // Separate arrays for enum-values for enum props, to keep everything constexpr
@@ -475,6 +476,7 @@ static constexpr PropType OfxPropTime_types[] = {PropType::Double};
 static constexpr PropType OfxPropType_types[] = {PropType::String};
 static constexpr PropType OfxPropVersion_types[] = {PropType::Int};
 static constexpr PropType OfxPropVersionLabel_types[] = {PropType::String};
+static constexpr PropType kOfxImageClipPropDisplayTimeOffset_types[] = {PropType::Double};
 static constexpr PropType kOfxParamPropUseHostOverlayHandle_types[] = {PropType::Bool};
 static constexpr PropType kOfxPropKeyString_types[] = {PropType::String};
 static constexpr PropType kOfxPropKeySym_types[] = {PropType::Int};
@@ -873,6 +875,8 @@ static inline constexpr PropDefsArray<PropDef> prop_defs = {
   openfx::span(prop_type_arrays::OfxPropVersion_types, 1), 0, openfx::span<const char* const>()},
 { "OfxPropVersionLabel",
   openfx::span(prop_type_arrays::OfxPropVersionLabel_types, 1), 1, openfx::span<const char* const>()},
+{ "kOfxImageClipPropDisplayTimeOffset",
+  openfx::span(prop_type_arrays::kOfxImageClipPropDisplayTimeOffset_types, 1), 1, openfx::span<const char* const>()},
 { "kOfxParamPropUseHostOverlayHandle",
   openfx::span(prop_type_arrays::kOfxParamPropUseHostOverlayHandle_types, 1), 1, openfx::span<const char* const>()},
 { "kOfxPropKeyString",
@@ -1080,6 +1084,7 @@ DEFINE_PROP_TRAITS(OfxPropTime, double, false);
 DEFINE_PROP_TRAITS(OfxPropType, const char *, false);
 DEFINE_PROP_TRAITS(OfxPropVersion, int, false);
 DEFINE_PROP_TRAITS(OfxPropVersionLabel, const char *, false);
+DEFINE_PROP_TRAITS(OfxImageClipPropDisplayTimeOffset, double, false);
 DEFINE_PROP_TRAITS(OfxParamPropUseHostOverlayHandle, bool, false);
 DEFINE_PROP_TRAITS(OfxPropKeyString, const char *, false);
 DEFINE_PROP_TRAITS(OfxPropKeySym, int, false);
@@ -1271,6 +1276,7 @@ static_assert(string_view("OfxPropTime") == string_view(kOfxPropTime));
 static_assert(string_view("OfxPropType") == string_view(kOfxPropType));
 static_assert(string_view("OfxPropVersion") == string_view(kOfxPropVersion));
 static_assert(string_view("OfxPropVersionLabel") == string_view(kOfxPropVersionLabel));
+static_assert(string_view("kOfxImageClipPropDisplayTimeOffset") == string_view(kOfxImageClipPropDisplayTimeOffset));
 static_assert(string_view("kOfxParamPropUseHostOverlayHandle") == string_view(kOfxParamPropUseHostOverlayHandle));
 static_assert(string_view("kOfxPropKeyString") == string_view(kOfxPropKeyString));
 static_assert(string_view("kOfxPropKeySym") == string_view(kOfxPropKeySym));

release-notes-next.md

@@ -14,6 +14,7 @@ This is version NEXT of the OpenFX API.
 - **Parameter interpolation types**: Added `kOfxParamInterpType` and related definitions documenting standard keyframe interpolation modes (issue #116).
 - **Obsolete plugins**: Added `kOfxImageEffectPluginPropObsolete` so a plugin bundle can mark a plugin as obsolete: available for use in old projects but not offered to users for new use (issue #221).
 - **Windows ARM64 packaging**: Defined plugin install locations for Windows on ARM, including the new normative `Win-arm64ec` folder for Arm64EC/Arm64X plug-ins, with most-specific-first DLL search order (issue #160).
+- **Clip display time offset**: Added `kOfxImageClipPropDisplayTimeOffset`, the frame number the host displays for time 0 (e.g. 1001), so a plugin's own UI can show the same frame numbers as the host. Its string value keeps a leading `k` for compatibility with hosts and plugins that already use it (issue #58).
 - **Colour-Managed Colour Params**: Added `kOfxParamPropColourManagement`. Lets a plugin declare the colourspace of an RGB/RGBA parameter's values (including its default): `Managed` (ACES2065-1, scene-linear, unclamped) for processing colours, or `SRGB` (sRGB, [0..1]) for display-referred UI colours such as Draw Suite overlays, so a host can interpret and convert them correctly (issue #158).
 
 ## Behaviour Changes