1 #ifndef _ofxNatron_h_ 2 #define _ofxNatron_h_ 3 4 /** @brief The kOfxPropName property of the Natron Host */ 5 #define kNatronOfxHostName "fr.inria.Natron" 6 7 /** @brief int x 1 property used on the image effect host descriptor. 8 It indicates whether the host is Natron as another mean than just the host name. 9 This was added because it may be required to activate certain plug-ins by changing the host-name 10 (since some plug-ins don't allow to be loaded on any host) 11 but to keep some other functionnalities specific to the Natron extensions working. 12 13 Valid values: 14 - 0: Indicates that the host is not Natron 15 - 1: Indicates that the host is Natron and can support all extensions provided by this header 16 17 Default value: 18 - 0 19 */ 20 #define kNatronOfxHostIsNatron "NatronOfxHostIsNatron" 21 22 /** @brief int x 1 property used on the image effect host descriptor. 23 It indicates whether the host supports dynamic choice param entries changes or not. 24 25 Reasoning: 26 By default most of hosts expect the entries of a choice param to be statically defined in the describeInContext action. 27 However this might often be a need to re-populate the entries depending on other dynamic parameters, such as the pixel 28 components. 29 You would then have to call propReset on the kOfxParamPropChoiceOption property via the param suite and then call 30 propSetString on the kOfxParamPropChoiceOption property to re-build the entries list. 31 32 Valid values: 33 - 0: Indicates that the host does not support dynamic choices 34 - 1: Indicates that the host supports dynamic choices 35 36 Default value: 37 - 0 38 */ 39 #define kNatronOfxParamHostPropSupportsDynamicChoices "NatronOfxParamHostPropSupportsDynamicChoices" 40 41 /** @brief The name of a string parameter that maps to a sublabel in the GUI, 42 e.g. the name of the file in a Reader node, or the name of the operation 43 in a Merge node, or the name of the track in a Tracker node. 44 45 Whenever the host sets the value of this parameter, 46 kOfxActionInstanceChanged is called (as with any other parameter). 47 It may be kOfxParamPropSecret=1 if it should not appear in the instance UI. 48 It may be kOfxParamPropEnabled=0 if only the host should set its value via 49 a special GUI. 50 51 This parameter should have the properties 52 - kOfxParamPropPersistent=1, 53 - kOfxParamPropEvaluateOnChange=0. 54 You should set its default value during the kOfxImageEffectActionDescribeInContext action. 55 */ 56 #define kNatronOfxParamStringSublabelName "NatronOfxParamStringSublabelName" 57 58 59 /* 60 ----------------------------------------------- ----------------------------------------------------------------- 61 //////////////////////////////////////////////////////////////////////////////////////////////////////////////// 62 Natron multi-plane definitions and extensions brought to Nuke multi-plane extensions defined in fnOfxExtensions.h: 63 //////////////////////////////////////////////////////////////////////////////////////////////////////////////// 64 ----------------------------------------------- ----------------------------------------------------------------- 65 66 Definitions: 67 ------------ 68 69 - Layer: Corresponds to 1 image plane and has a unique name 70 71 - Components: The "type" of data (i.e: the number of channels) contained by a Layer. This may be equal to any of the default 72 components defined by OpenFX (e.g: kOfxImageComponentRGBA) but also to the one added by fnOfxExtensions.h (namely 73 kFnOfxImagePlaneForwardMotionVector or kFnOfxImagePlaneBackwardMotionVector) and finally to the custom planes extension 74 defined by Natron. 75 76 ----------------------------------------------- ----------------------------------------------------------------- 77 78 The Foundry multi-plane suite: 79 ------------------------------ 80 81 - In The Foundry specification, some layers are paired and can be requested at the same time: 82 this is the (kFnOfxImagePlaneBackwardMotionVector, kFnOfxImagePlaneForwardMotionVector) and (kFnOfxImagePlaneStereoDisparityLeft, kFnOfxImagePlaneStereoDisparityRight) layers. A pair means both layers have the same components type and are generally rendered together. 83 These layers are the only one added by this extension. 84 85 - The color layer (kFnOfxImagePlaneColour) can have the default OpenFX types. 86 87 - The only plug-ins to support The Foundry multi-plane suite are the Furnace ones (among potentially others) and the only (known) hosts to support it are Natron and Nuke. 88 89 - In The Foundry multi-plane suite, the plug-in specify that it wants to operate on a motion vector plane or disparity plane by setting kFnOfxImageComponentMotionVectors or kFnOfxImageComponentStereoDisparity on the clip components during the getClipPreferences action. They do not support other planes. 90 91 - The getClipComponents action is unused. 92 93 - If the clip components are set to kFnOfxImageComponentMotionVectors or kFnOfxImageComponentStereoDisparity it is expected that the following render actions are called on both paired planes (the plug-in will attempt to fetch both from the render action). 94 95 Natron modifications: 96 --------------------- 97 98 - Some file formats (OpenEXR, TIFF) allow multiple arbitrary image layers (= planes) to be embedded in a single file. 99 In the same way, a host application may want/need to use multiple arbitrary image layers into the same image stream 100 coming from a clip. 101 The multi-plane extension defined in fnOfxExtensions.h by The Foundry has nothing set in this regard and we had to come-up 102 with one. 103 104 A custom Layer (a.k.a plane) is defined as follows: 105 106 - A unique name, e.g: "fr.myRenderer.RenderLayer" 107 - An optional label, e.g: "RenderLayer". If empty, this will be set to the name. 108 - A set of 1 to 4 channels represented by strings, e.g: ["R","G","B","A"] 109 - An optional string to better illustrate the channels type, e.g: "MotionVectors" would better represent "XY". If empty, this will be set to the concatenation of all channel strings. 110 111 Typically it would be presented like this to the user in a choice parameter: 112 113 RenderLayer.RGBA 114 DisparityLeft.Disparity 115 116 Internally instead of passing this string and parsing it, we encode the layer as such: 117 118 kNatronOfxImageComponentsPlaneName + planeName + 119 <optional> kNatronOfxImageComponentsPlaneLabel + planeLabel + 120 <optional> kNatronOfxImageComponentsPlaneChannelsLabel + channelsLabel + 121 kNatronOfxImageComponentsPlaneChannel + channel1Name + 122 kNatronOfxImageComponentsPlaneChannel + channel2Name + 123 kNatronOfxImageComponentsPlaneChannel + channel3Name 124 125 Examples: 126 127 kNatronOfxImageComponentsPlaneName + "fr.unique.id.position" + kNatronOfxImageComponentsPlaneLabel + "Position" + kNatronOfxImageComponentsPlaneChannel + "X" + kNatronOfxImageComponentsPlaneChannel + "Y" + kNatronOfxImageComponentsPlaneChannel + "Z" 128 129 130 kNatronOfxImageComponentsPlaneName + "DisparityLeft" + kNatronOfxImageComponentsPlaneChannelsLabel + "Disparity" + kNatronOfxImageComponentsPlaneChannel + "X" + kNatronOfxImageComponentsPlaneChannel + "Y" 131 132 133 134 135 136 Natron custom layers can be passed wherever layers are used (clipGetImage,render action) or components are used: getClipComponents. They may not be used 137 in getClipPreferences. 138 139 - Multi-plane effects (kFnOfxImageEffectPropMultiPlanar=1) request their layers via the getClipComponents action 140 141 - getClipPreferences has not changed and may only be used to specify the type of components onto which the color layer (kFnOfxImagePlaneColour) will be mapped 142 143 - Multi-plane effects (kFnOfxImageEffectPropMultiPlanar=1) are expected to support arbitrary component types and should not rely on the components set during getClipPreferences except for the kFnOfxImagePlaneColour layer. 144 145 - OpenFX didn't allow to pass 2-channel image natively through a clip, even for plug-ins that are not multi-plane. 146 The color layer (kFnOfxImagePlaneColour) can now have the default OpenFX types of components as well as kNatronOfxImageComponentXY to specify 2-channel images. 147 kNatronOfxImageComponentXY may be specified wherever default OpenFX components types are used. 148 149 150 151 152 Notes: 153 ------ 154 155 - Layers are what is passed to the render actionn getClipComponents action and clipGetImage function whereas components are what is used for getClipPreferences 156 157 - The kFnOfxImageEffectPropComponentsPresent property on clip instances must return a list of planes available on that clip (not components). 158 159 */ 160 161 162 /** @brief string property to indicate the presence of custom components on a clip in or out. 163 The string should be formed as such: 164 165 kNatronOfxImageComponentsPlaneName + 166 planeName + 167 <optional> kNatronOfxImageComponentsPlaneLabel + planeLabel + 168 <optional> kNatronOfxImageComponentsPlaneChannelsLabel + channelsLabel + 169 kNatronOfxImageComponentsPlaneChannel + channel1Name + 170 kNatronOfxImageComponentsPlaneChannel + channel2Name + 171 kNatronOfxImageComponentsPlaneChannel + channel3Name 172 173 Examples: 174 175 kNatronOfxImageComponentsPlaneName + "fr.unique.id.position" + kNatronOfxImageComponentsPlaneLabel + "Position" + kNatronOfxImageComponentsPlaneChannel + "X" + kNatronOfxImageComponentsPlaneChannel + "Y" + kNatronOfxImageComponentsPlaneChannel + "Z" 176 177 kNatronOfxImageComponentsPlaneName + "DisparityLeft" + kNatronOfxImageComponentsPlaneChannelsLabel + "Disparity" + kNatronOfxImageComponentsPlaneChannel + "X" + kNatronOfxImageComponentsPlaneChannel + "Y" 178 179 This indicates to the host in which plane should the given components appear and how many pixel channels it contains. 180 It can be used at any place where kOfxImageComponentAlpha, kOfxImageComponentRGB, kOfxImageComponentRGBA, kOfxImageComponentNone (etc...) is 181 given. 182 */ 183 #define kNatronOfxImageComponentsPlaneName "NatronOfxImageComponentsPlaneName_" 184 185 #define kNatronOfxImageComponentsPlaneLabel "_PlaneLabel_" 186 187 #define kNatronOfxImageComponentsPlaneChannelsLabel "_ChannelsLabel_" 188 189 #define kNatronOfxImageComponentsPlaneChannel "_Channel_" 190 191 192 /** @brief String to label images with 2 components. If the plug-in supports this then the host can attempt to send to the plug-in 193 planes with 2 components.*/ 194 #define kNatronOfxImageComponentXY "NatronOfxImageComponentXY" 195 196 /** @brief Whether the menu should be hierarchical/cascading, and each option contains a slash-separated path to the item. 197 198 - Type - int X 1 199 - Property Set - plugin parameter descriptor (read/write) and instance (read only), and on the image effect host descriptor (read only) 200 - Default - 0 201 - Valid Values - 0 or 1 202 203 This is a property on parameters of type ::kOfxParamTypeChoice, and tells the choice whether menu should be hierarchical/cascading, and each option contains a slash-separated path to the item. 204 205 */ 206 #define kNatronOfxParamPropChoiceCascading "NatronOfxParamPropChoiceCascading" 207 208 /** @brief 209 DEPRECATED: No longer used as of Natron 3 210 int x1 property on a choice parameter descriptor (read/write) and choice parameter instance (read-only) to indicate whether 211 the host can add a new choice on its own (probably via a GUI specific to this parameter). 212 The plugin may then retrieve the option enum whenever a choice value is out of its initial range. 213 214 This property primarily targets image plane choices, where the host should be able to create a new plane and add it to the menu. 215 216 Valid values: 217 - 0: Indicates that the parameter does not support/want that the host adds new options 218 - 1: Indicates that the parameter wants to have the choice "New" so that the host can create a new option 219 Default value: 220 - 0 221 */ 222 #define kNatronOfxParamPropChoiceHostCanAddOptions "NatronOfxParamPropChoiceHostCanAddOptions" 223 224 /** @brief 225 DEPRECATED: No longer used as of Natron 3 226 The standard parameter for setting output channels of a plugin (used by Shuffle) 227 */ 228 #define kNatronOfxParamOutputChannels "outputChannels" 229 230 /** @brief String xN property, similar to kFnOfxImageEffectPropComponentsPresent, except that this indicates for an effect 231 a set of extraneous planes that were created by the user though some sort of interface which should be made available 232 in output of this effect. 233 234 Property Set - image effect instance (read only) 235 Valid values - A list of one or multiple planes as described in the multi-plane definition 236 Default value - None 237 */ 238 #define kNatronOfxExtraCreatedPlanes "NatronOfxExtraCreatedPlanes" 239 240 /** @brief Indicates if the host may add a channel selector, and which components should be selected by default. 241 242 - Type - string X 1 243 - Property Set - image effect descriptor (read/write), host descriptor (read only) 244 - Valid Values - This must be one of 245 - kOfxImageComponentNone (channel selector is disabled) 246 - kOfxImageComponentRGBA (enabled, with RGBA selected by default) 247 - kOfxImageComponentRGB (enabled, with RGB selected by default) 248 - kOfxImageComponentAlpha (enabled, with Alpha selected by default) 249 250 This string indicates if the host may add a channel selector, and which components should be selected by default. 251 252 If the property is not present the the host descriptor, or its value is not kOfxImageComponentRGBA, then the host does not have a channel selector, and the plugin may propose its own solution (e.g. a checkbox for each channel). 253 254 The default for an image effect descriptor is kOfxImageComponentRGBA. 255 */ 256 #define kNatronOfxImageEffectPropChannelSelector "NatronOfxImageEffectPropChannelSelector" 257 258 259 /** @brief Indicates if the host may add a mask that will be handled automatically. 260 261 - Type - int X 1 262 - Property Set - image effect descriptor (read/write), host descriptor (read only) 263 - Valid Values - 0 or 1 264 - Default value: 0 265 266 When set to 1, the plug-in should be able to call clipGetHandle on the clip created by the host. 267 */ 268 269 #define kNatronOfxImageEffectPropHostMasking "kNatronOfxImageEffectPropHostMasking" 270 271 /** @brief Indicates if the host may add a "Mix" double parameter that will dissolve 272 between the source image at 0 and the full effect at 1. 273 274 - Type - int X 1 275 - Property Set - image effect descriptor (read/write), host descriptor (read only) 276 - Valid Values - 0 or 1 277 - Default value: 0 278 */ 279 #define kNatronOfxImageEffectPropHostMixing "kNatronOfxImageEffectPropHostMixing" 280 281 282 /** @brief Generic parameter name for a channel selector. If the plugin doesn't define these, and 283 kNatronOfxImageEffectPropChannelSelector is not set by the plugin, the host may add its own channel selector. 284 **/ 285 #define kNatronOfxParamProcessR "NatronOfxParamProcessR" 286 #define kNatronOfxParamProcessRLabel "R" 287 #define kNatronOfxParamProcessRHint "Process red component." 288 #define kNatronOfxParamProcessG "NatronOfxParamProcessG" 289 #define kNatronOfxParamProcessGLabel "G" 290 #define kNatronOfxParamProcessGHint "Process green component." 291 #define kNatronOfxParamProcessB "NatronOfxParamProcessB" 292 #define kNatronOfxParamProcessBLabel "B" 293 #define kNatronOfxParamProcessBHint "Process blue component." 294 #define kNatronOfxParamProcessA "NatronOfxParamProcessA" 295 #define kNatronOfxParamProcessALabel "A" 296 #define kNatronOfxParamProcessAHint "Process alpha component." 297 298 /** @brief Used to define the tracker effect context. 299 In this context the effect instance will be exactly 1 track. 300 It will define 4 buttons parameters, namely: 301 - kNatronParamTrackingPrevious 302 - kNatronParamTrackingNext 303 - kNatronParamTrackingBackward 304 - kNatronParamTrackingForward 305 and 1 string parameter containing the name of the track: 306 - kNatronOfxParamStringSublabelName 307 308 The instance changed action on the 4 push-buttons parameters can be called on a thread different than the main-thread, allowing multiple instance changed action 309 to be called on the same parameter concurrently but with a different 'time' parameter. It is up to the Host application to schedule correctly the 310 multi-threading of the tracks. 311 312 In this context, typically the host would provide a general interface under which multiple instances of the plug-in in this context would co-exist. 313 The name parameter is here to identity the track. 314 This could be a table in which each instance would have a separate row on its own. 315 Such instances would probably have shared parameters, such as parameters of the tracking algorithm. On the other hand the instances have "specific" parameters 316 that could not be shared among instances, e.g: the resulting position of a point tracking would be unique for each separate track instance. 317 The host could propose in its user interface to display instance-specific parameters in each row of the table, but could display the shared parameter as a global 318 parameter for all instances. To flag that a parameter is instance-specific, a new property on the parameter descriptor has been introduced, kNatronOfxImageEffectContextTracker. This property should be set to 1 for the kNatronOfxParamStringSublabelName parameter. 319 */ 320 #define kNatronOfxImageEffectContextTracker "NatronOfxImageEffectContextTracker" 321 322 /** @brief Button param that must be present on a plug-in in the kNatronOfxImageEffectContextTracker context. When the instance changed action 323 is called on this parameter, it should apply the analysis on the frame preceding the current frame on the timeline.*/ 324 #define kNatronParamTrackingPrevious "trackPrevious" 325 326 /** @brief Button param that must be present on a plug-in in the kNatronOfxImageEffectContextTracker context. When the instance changed action 327 is called on this parameter, it should apply the analysis on the frame following the current frame on the timeline.*/ 328 #define kNatronParamTrackingNext "trackNext" 329 330 /** @brief Button param that must be present on a plug-in in the kNatronOfxImageEffectContextTracker context. When the instance changed action 331 is called on this parameter, it should apply the analysis on all the frames from the preceding frame until the left 332 bound of the timeline..*/ 333 #define kNatronParamTrackingBackward "trackBackward" 334 335 /** @brief Button param that must be present on a plug-in in the kNatronOfxImageEffectContextTracker context. When the instance changed action 336 is called on this parameter, it should apply the analysis on all the frames from the following frame until the right 337 bound of the timeline..*/ 338 #define kNatronParamTrackingForward "trackForward" 339 340 341 /** @brief int property to indicate whether a double 3D parameter is associated to a matrix 3x3 342 - Type - int x 1 343 - Property Set - plugin parameter descriptor (read/write) and instance (read/write only) 344 - Valid values - 0, 1, 2, 3 345 0: The parameter is a regular Double3D and the host should use it as any other parameter 346 1: The parameter is the first row of the 3x3 matrix 347 2: The parameter is the second row of the 3x3 matrix 348 3: The parameter is the third row of the 3x3 matrix 349 350 The 3 parameters are identified by the host by their name: the share the same name, but they end with "_rowX", with X being replaced 351 by the 1-based index row of the matrix, e.g: 352 353 transform_row1 354 transform_row2 355 transform_row3 356 357 would be recognized by the host as a parameter of type Matrix3x3 with the name "transform". 358 In this case the properties of the host rectangle parameter are taken from the row1 parameter, except 359 for the kOfxParamPropDimensionLabel, kOfxParamPropDefault 360 */ 361 #define kNatronOfxParamPropDoubleTypeMatrix3x3 "NatronOfxParamTypeMatrix3x3" 362 363 364 /** @brief int property to indicate whether a double or int 2D parameter is associated to a rectangle [(x,y),(w,h)] 365 - Type - int x 1 366 - Property Set - plugin parameter descriptor (read/write) and instance (read/write only) 367 - Valid values - 0, 1, or 2 368 0: The parameter is a regular Int2D/Double2D and the host should use its double type property 369 1: The parameter is the position component of the rectangle (x,y) 370 2: The parameter is the size component of the rectangle (w,h) 371 372 The 2 parameters are identified by the host by their name: the share both the same name, but one end with "_position" 373 and the other with "_size", e.g: 374 375 rectangle_position 376 rectangle_size 377 378 would be recognized by the host as a parameter of type rectangle with the name "rectangle". 379 In this case the properties of the host rectangle parameter are taken from the position component parameter, except 380 for the kOfxParamPropMin, kOfxParamPropMax, kOfxParamPropDisplayMin, kOfxParamPropDisplayMax, kOfxParamPropDimensionLabel, 381 kOfxParamPropDefault 382 */ 383 #define kNatronOfxParamPropTypeRectangle "NatronOfxParamPropTypeRectangle" 384 385 386 387 /** @brief int property to indicate whether a parameter is instance-specific or not. 388 - Type - int x 1 389 - Property Set - plugin parameter descriptor (read/write) and instance (read/write only) 390 - Default - 0 391 - Valid Values - 0 or 1 392 When set to 1, the parameter is specific to an effect instance of the plug-in and should have a 393 unique representation for each instance. See descripton of kNatronOfxImageEffectContextTracker for more details 394 on multiple instances and difference between shared and specific parameters. 395 */ 396 #define kNatronOfxParamPropIsInstanceSpecific "NatronOfxParamPropIsInstanceSpecific" 397 398 /** @brief bool property to indicate that an effect should be considered deprecated 399 - Type - int x 1 400 - Property Set - image effect descriptor (read/write) image effect (read only) 401 - Default - 0 402 - Valid Values - 0 or 1 403 When set to 1, the host may disable using this plugin in new projects. 404 */ 405 #define kNatronOfxImageEffectPropDeprecated "NatronOfxImageEffectPropDeprecated" 406 407 /** @brief This extension is to allow the Host application to add extra formats 408 (which are a set of 3 values: width, height, pixel aspect ratio) to a choice parameter. 409 If the host application finds the following 3 parameters: 410 - kNatronParamFormatChoice 411 - kNatronParamFormatSize 412 - kNatronParamFormatPar 413 The host will then control the choice parameter itself, including: 414 - Refreshing the list of available formats in the choice parameter 415 - Handling the instanceChanged action calls instead of the plug-in on the parameter kNatronParamFormatChoice by setting 416 the values of kNatronParamFormatSize and kNatronParamFormatPar accordingly. The handler will not be called on the plug-in. 417 418 The plug-in should still handle the case where the instanceChanged action is called for kNatronParamFormatChoice 419 which would indicate that the host does not handle the parameter itself. 420 421 */ 422 423 /** @brief Choice parameter used to choose the target format*/ 424 #define kNatronParamFormatChoice "NatronParamFormatChoice" 425 426 /** @brief Int2D parameter used to store the width,height of the format. Should be secret and evaluateOnChange=false 427 The values returned are in pixel coordinates. 428 */ 429 #define kNatronParamFormatSize "NatronParamFormatSize" 430 431 /** @brief Double parameter used to store the pixel aspect ratio of the format. Should be secret and evaluateOnChange=false*/ 432 #define kNatronParamFormatPar "NatronParamFormatPar" 433 434 /** @brief string property that uniquely identifies the project which holds the instance within the host 435 - Type - string x 1 436 - Property Set - image effect descriptor (read only) image effect (read only) 437 - Default - "" 438 - Valid Values - any 439 */ 440 #define kNatronOfxImageEffectPropProjectId "NatronOfxImageEffectPropProjectId" 441 442 /** @brief string property that uniquely identifies the group (if any) containing the instance within the current project 443 If the instance os within nested groups, this should be something like "Group1.Group2" with each group level separated by a dot. 444 - Type - string x 1 445 - Property Set - image effect descriptor (read only) image effect (read only) 446 - Default - "" 447 - Valid Values - any 448 */ 449 #define kNatronOfxImageEffectPropGroupId "NatronOfxImageEffectPropGroupId" 450 451 /** @brief string property that uniquely identifies the instance within the group (if any) or within the current project 452 - Type - string x 1 453 - Property Set - image effect descriptor (read only) image effect (read only) 454 - Default - "" 455 - Valid Values - any 456 */ 457 #define kNatronOfxImageEffectPropInstanceId "NatronOfxImageEffectPropInstanceId" 458 459 /** @brief Indicates if a plug-in can make use of multiple CPU threads within a single call of the kOfxImageEffectActionRender action, for instance 460 by using the multi-thread suite. 461 The host should only account this as a hint to better organize its multi-threading priority queue. 462 Unlike the kOfxImageEffectPluginRenderThreadSafety property, it does not inform in any way about the multi-thread safety of the plug-in. 463 464 - Type - int X 1 465 - Property Set - plugin descriptor (read/write) 466 - Default - 0 467 - Valid Values - 468 - 0: indicating that only the thread calling the kOfxImageEffectActionRender action is the only thread expected to be doing processing 469 - 1: indicating that the plug-in can launch multiple processing threads during a single call to the kOfxImageEffectActionRender action. 470 The plug-in should try to use at most the multi-thread suite and especially the multiThreadNumCPUs function to help the host application 471 schedule threads over concurrent tasks. 472 */ 473 #define kNatronOfxImageEffectPluginUsesMultipleThread "NatronOfxImageEffectPluginUsesMultipleThread" 474 475 476 //////////////////////////////////////////////////////////////////////////////////////////////////////////// 477 //////////////////////////////////////////////////////////////////////////////////////////////////////////// 478 //////////////////////////////////// Natron in-viewer interface extension ///////////////////////////////// 479 /* 480 The need for this extension was to be able to create parameters within the viewport of the host application when the user 481 would be engaged in a fullscreen task and to get better support with the viewport. 482 483 Several things are covered in this extension: 484 485 1) In-viewer parameters that behave like normal parameters but have their interface directly next to the viewport. 486 2) Toggable buttons, implemented as Boolean parameters. 487 3) Buttons and toggable buttons can be assigned shortcuts 488 4) Ability to add toolbars which can let the user define the "state" of the interaction (selecting, editing, etc...) Implemented using page group and boolean parameters. 489 5) Ability to pop a menu during overlay actions that uses the native software menu interface (typically a right click menu) 490 6) Addition of the kOfxInteractPropPenPosition and kOfxInteractPropPenViewportPosition properties for ALL interact actions (even draw, focus in/out) so the plug-in can now at any moment where the position of the cursor is 491 7) A lot of overlay interacts require some sort of selection where the user can draw a rectangle to select specific items. Rather than re-create a new custom-looking selection rectangle, let the host make one for us through its own interact actions and notify us if needed. 492 A new parameter with a special name can be used to let the host know we are interested in knowing the state of the selection. 493 494 8) Let the plug-in a way to control the host application cursor. 495 9) Add a way to show a custom dialog with fields represented as parameters. This is implemented as a property on a group parameter whether its content can be represented as a non-modal dialog or not. 496 10) Plug-ins description (kOfxPropPluginDescription) and parameters hint (kOfxParamPropHint) may be written in markdown. 497 11) A plug-in might want to be able to access the host undo/redo actions of the Edit menu when doing special actions from within the overlay interact actions not involving parameters. 498 12) Deprecate kOfxParamPropUseHostOverlayHandle, instead add a property on the image effect descriptor indicating group of parameters which altogether control 499 more complex overlays. A host can then provide default overlay interact handling. 500 501 1) In the host viewport, parameters can be arranged by widget rows controlled by the kNatronOfxImageEffectPropInViewerContextParamsOrder property. 502 This index indicates the order of the parameter in the rows. 503 New rows are created if the parameter also have the property kNatronOfxParamPropInViewerContextLayoutHint set to kNatronOfxParamPropInViewerContextLayoutHintAddNewLine. 504 Note that the host should try to make the parameters UI concise. 505 506 Several properties are a duplicate of existing properties on the parameter descriptor, because there was a need to differentiate 507 the state of the interface of the parameter on the viewer and at the same time in its standard page. 508 The Host should carefully ensure that the state of the interface of a parameter in the viewer and in the page are synchronized. 509 510 2) Boolean parameters now have a property kNatronOfxBooleanParamPropIsToggableButton that indicate whether it should be 511 displayed as a toggable button instead of a checkbox. 512 513 3) PushButton parameters, Boolean Parameters with property kNatronOfxBooleanParamPropIsToggableButton, and Group parameters with the property kNatronOfxParamPropInViewerContextIsInToolbar can have shortcuts. Instead of responding to specific key strokes in the overlay interact actions, the plug-in can then just inform the host about the shortcut associated to this parameter. This enables the host to represent the shortcut in some sort of shortcut editor where the user could modify the shortcut. 514 The plug-in informs to the host via the property on the image effect kNatronOfxImageEffectPropInViewerContextDefaultShortcuts the default shortcuts for a parameter. 515 Each shortcut, should be specified with a symbol kNatronOfxImageEffectPropInViewerContextShortcutSymbol, as well and indicate its modifiers via 516 kNatronOfxImageEffectPropInViewerContextShortcutHasControlModifier, kNatronOfxImageEffectPropInViewerContextShortcutHasShiftModifier, kNatronOfxImageEffectPropInViewerContextShortcutHasAltModifier, kNatronOfxImageEffectPropInViewerContextShortcutHasMetaModifier and kNatronOfxImageEffectPropInViewerContextShortcutHasKeypadModifier. 517 All these properties should have the same dimension as kNatronOfxImageEffectPropInViewerContextDefaultShortcuts. 518 519 When a shortcut is triggered, the host will not call the associated keydown action but instead will call the action kOfxActionInstanceChanged. 520 521 4) It is also possible to add a toolbar to the host viewport, to indicate "states" in the plug-in, e.g: "Selecting", "Drawing", "Cloning", etc... 522 A toolbar is defined simply by defining a Page parameter with property kNatronOfxParamPropInViewerContextIsInToolbar set to 1. 523 To add toolbuttons, add Group parameters to the page, with the property kNatronOfxParamPropInViewerContextIsInToolbar set to 1. 524 To add an action to a toolbutton, add a BooleanParam to a group with the property kNatronOfxParamPropInViewerContextIsInToolbar set to 1. 525 A shortcut can be set on the group parameters which are represented as toolbuttons so that the user can cycle through the actions with the keyboard. 526 527 The selected toolbutton in the toolbar will have the property kOfxParamPropGroupOpen set to 1. 528 The selected tool action in a toolbutton will have its parameter value set to true. 529 To find out the active tool, retrieve the active action of the selected toolbutton. 530 The host should always make sure that there is a selected toolbutton and that it has an active action. 531 Similarly, the plug-in should by default ensure that one and only one toolbutton is selected and that for each toolbutton, one action is at least active. 532 533 5) A menu can be popped on the viewer under the position of the cursor when requested during overlay interacts actions. 534 The menu itself is described via a secret Choice parameter with the name kNatronOfxParamRightClickMenu 535 which kOfxParamPropChoiceOption are the script-name of parameters which have been defined as in-viewer parameters with the kNatronOfxParamPropInViewerContextIndex set. Only Boolean parameters and PushButton parameters can be specified in the menu, typically to represent a checkable state or that an action can be triggered. 536 The menu must be constructed by the plug-in during the action it wants to use it, hence the host must support kNatronOfxParamHostPropSupportsDynamicChoices 537 538 6) The kOfxInteractPropPenPosition and kOfxInteractPropPenViewportPosition properties have been added to all overlay interacts actions as they are sometimes needed to know the position of the cursor during the draw action, for example to draw something only if the cursor is in the window. 539 540 7) Add a way to use the host native selection rectangle to define the selection of items. To advertise to the host that we are interested in the selection state of the rectangle, we declare a Int parameter with the name kNatronOfxParamSelectionRectangleState. The host notifies the plug-in of the selection state change via the kOfxActionInstanceChanged action. 541 The value of the parameter can be 3-fold: 542 0 meaning that the selection has been cleared by the user 543 1 meaning that the selection is being actively edited by the user (i.e: during pen motion) 544 2 meaning that the selection is finilized by the user (i.e: during pen up) 545 The property kNatronOfxImageEffectSelectionRectangle will be updated prior to calling the kOfxActionInstanceChanged action for this parameter by the host, indicating the region covered by the selection rectangle. 546 547 8) The host application cursor can be controled by the plug-in via a secret String parameter with the name kNatronOfxParamCursorName. If this parameter is found, the host should display a cursor depending on the value of this parameter. The value of the parameter should be the name of the cursor. Several default cursor can be made available by the host as advertised by the kNatronOfxImageEffectPropDefaultCursors property. The plug-in may also embed custom cursors as PNG files located in the Resources directory of the plug-in bundle. To specify one the image in the plug-in bundle as an icon, you may set the value of this parameter to the filename of the image without any leading path. This is up to the host to figure out the path to the plug-in bundle Resources directory. 548 Whenever an event is sent to overlay interacts (PenDown, PenMotion, PenUp, KeyDown, KeyUp, KeyRepeat, GainFocus, LoseFocus, the OFX Host should set the cursor to the one of the first interact which catches the event by returning kOfxStatOK to the corresponding action. If no overlay interact returns kOfxStatOK, the cursor should be set to the default cursor. 549 550 9) It may be useful to show a dialog to a user to request a few informations before doing a task such as an analysis. 551 Instead of embedding the parameters in the settings of an image effect, the host could display a temporary dialog with the parameters requested. If the property kNatronOfxGroupParamPropIsDialog is set to 1, then whenever the property kOfxParamPropGroupOpen is set to 1, the dialog should be displayed by the host. 552 553 10) If the property kNatronOfxPropDescriptionIsMarkdown is set to 1 on a parameter descriptor or on an image effect descriptor, then their corresponding description (kOfxParamPropHint for a parameter descriptor and kOfxPropPluginDescription for an image effect descriptor) may be interpreted as markdown by the host. 554 555 11) To support undo/redo, the plug-in must define a string parameter named kNatronOfxParamUndoRedoText and a boolean parameter named kNatronOfxParamUndoRedoState. The parameters should have the following properties settings: 556 - kOfxParamPropEvaluateOnChange = 0 557 - kOfxParamPropPersistent = 0 558 - kOfxParamPropSecret = 1 559 The string parameter value represents the text that should be displayed by the host in the undo/redo action of the Edit menu. 560 The boolean parameter value is used to notify the plug-in about undo/Redo stack changes. If the value is set to false, the user just pressed Undo, otherwise he/she pressed Redo. 561 To notify the host that a new action has been pushed, call paramSetValue on the string parameter with the name of the action that was done. The host notifies the plug-in in-turn that an action has been redone/undone by calling the kOfxActionInstanceChanged action with kOfxPropChangeReason = kOfxChangeUserEdited. 562 It is up to the plug-in to maintain the actual undo/redo stack of actions. Also note the following: 563 - The first time an action is push, the host should not call kOfxActionInstanceChanged on the plug-in since the action has already been redone 564 - It is up to the plug-in to merge similar undo/redo actions (e.g: imagine each action being typing a letter, the plug-in could merge them under a single one to delimit words instead of letters whenever the user wants to undo something). The first action of such a merge should always call paramSetValue but if a merge is successful, it should not call it. 565 566 12) The new property kNatronOfxPropNativeOverlays is defined on the plug-in image effect descriptor and on the host descriptor. 567 It adds a way for a plug-in to let the host handle overlay interacts. 568 kOfxParamPropUseHostOverlayHandle is no longer needed with this new property. 569 See property description for more infos. 570 571 */ 572 573 /** 574 string property xN that indicates for a host the supported native overlay interacts and for a plug-in the native overlay interacts requested to the host. 575 576 Property set - image effect descriptor (read/write) and host descriptor (read only). 577 578 On the host side, each string describes one type of native overlay interact. Each native overlay interact is of the following form: 579 580 kNatronNativeOverlayType + '_' + "UniqueOverlayName" + '_' 581 582 Followed by an undefined number of strings representing parameters. Each parameter is defined of the following form: 583 584 kNatronNativeOverlayParameterHint + '_' + "RoleHint" + kNatronNativeOverlayParameterType + "ParamType" 585 586 The type of a parameter is as defined in ofxParam.h such as kOfxParamTypeInteger or kOfxParamTypeDouble2D. 587 Each parameter string is separated by a '_'. 588 589 For example: 590 591 "NatronNativeOverlayType_Point2D_kNatronNativeOverlayParameterHint_Position_NatronNativeOverlayParameterType_OfxParamTypeDouble2D" 592 593 Or 594 595 "NatronNativeOverlayType_CornerPin2D_NatronNativeOverlayParameterHint_TopLeft_NatronNativeOverlayParameterType_OfxParamTypeDouble2D_NatronNativeOverlayParameterHint_TopRight_NatronNativeOverlayParameterType_OfxParamTypeDouble2D_NatronNativeOverlayParameterHint_BottomRIght_NatronNativeOverlayParameterType_OfxParamTypeDouble2D_NatronNativeOverlayParameterHint_BottomLeft_NatronNativeOverlayParameterType_OfxParamTypeDouble2D" 596 597 598 On the plug-in side, each string describes which overlay type of the host to use and a number of parameter strings. 599 Each parameter string is of the form: 600 601 "NatronNativeOverlayParameterName" + '_' + "parameterName" 602 603 604 For example: 605 606 "NatronNativeOverlayType_Point2D_NatronNativeOverlayParameterName_myPositionParameter" 607 608 "NatronNativeOverlayType_CornerPin2D_NatronNativeOverlayParameterName_topLeft_NatronNativeOverlayParameterName_topRight_NatronNativeOverlayParameterName_bottomRight_NatronNativeOverlayParameterName_bottomLeft" 609 610 611 **/ 612 #define kNatronOfxPropNativeOverlays "NatronOfxPropNativeOverlays" 613 614 /** 615 String used to define native overlay interacts in the kNatronOfxPropNativeOverlays property 616 **/ 617 #define kNatronNativeOverlayType "NatronNativeOverlayType" 618 #define kNatronNativeOverlayParameterHint "NatronNativeOverlayParameterHint" 619 #define kNatronNativeOverlayParameterType "NatronNativeOverlayParameterType" 620 #define kNatronNativeOverlayParameterName "NatronNativeOverlayParameterName" 621 622 /** 623 int property that tells if a hint or description is written in markdown instead of plain text. 624 This can be applied either to the content of the kOfxPropPluginDescription property for plug-in descripion or the kOfxParamPropHint property for parameter description. 625 For a host, this indicates whether markdown is supported or not 626 - Type - int x 1 627 - Property Set - plugin parameter descriptor (read/write) and instance (read only) or image effect descriptor (read/write) and instance (read only) or host descriptor (read only) 628 - Default - 0 629 - Valid Values - 1 or 0 630 If the value is 1, the hint is written in markdown 631 If the value is 0, the hint is written in plain-text 632 */ 633 #define kNatronOfxPropDescriptionIsMarkdown "NatronOfxPropDescriptionIsMarkdown" 634 635 /** 636 int property that tells if a group parameter can be displayed as a dialog by the host when its kOfxParamPropGroupOpen 637 property is set to 1. 638 When a dialog is requested, all parameters within this group should be represented in the dialog. The dialog itself could be titled with the label of the group parameter. 639 - Type - int x 1 640 - Property Set - group parameter descriptor (read/write) and instance (read only) 641 - Default - 1 642 - Valid Values - 1 or 0 643 If the value is 1, this parameter cannot have an interface in the viewport. 644 If the value is 0, this corresponds to the index on the viewport at which the host should place the parameter. 645 */ 646 #define kNatronOfxGroupParamPropIsDialog "NatronOfxGroupParamPropIsDialog" 647 648 /** 649 The name of the string parameter that should be used to implement host undo/redo. See 11) of the extension description. 650 */ 651 #define kNatronOfxParamUndoRedoText "NatronOfxParamUndoRedoText" 652 653 /** 654 The name of the boolean parameter that should be used to implement host undo/redo. See 11) of the extension description. 655 */ 656 #define kNatronOfxParamUndoRedoState "NatronOfxParamUndoRedoState" 657 658 /** 659 The name of the choice parameter that should be used to implement host right click menus. See 5) of the extension description. 660 */ 661 #define kNatronOfxParamRightClickMenu "NatronOfxParamRightClickMenu" 662 663 664 /** 665 The name of the int parameter that should be used to implement host selection rectangle. See 7) of the extension description. 666 */ 667 #define kNatronOfxParamSelectionRectangleState "NatronOfxParamSelectionRectangleState" 668 669 /** 670 The name of the string parameter that should be used to implement host cursors. See 8) of the extension description. 671 */ 672 #define kNatronOfxParamCursorName "NatronOfxParamCursorName" 673 674 /** 675 double property that defines the current selection rectangle drawn by the user on the host viewport. 676 See 7) for the associated extension. This value is refreshed whenever calling the kOfxActionInstanceChanged action for the parameter kNatronOfxParamSelectionRectangleState to let the plug-in a change to correctly synchronized its selection. 677 678 - Type - double x 4 679 - Property Set - plugin parameter descriptor (read/write) and instance (read/write) 680 - Default - (0,0,0,0) 681 - Valid Values - (x1,y1,x2,y2) quadruplet such as x1 < x2 and y1 < y2 682 */ 683 #define kNatronOfxImageEffectSelectionRectangle "NatronOfxImageEffectSelectionRectangle" 684 685 /** 686 string property indicating for a host, which are the default cursors provided to the plug-in and for a plug-in which are the cursor that it provides a drawing for. 687 - Type - string x N 688 - Property Set - host descriptor (read only) 689 - Default - kNatronOfxDefaultCursor 690 - Valid Values: Any of the cursor defined below by the properties kNatronOfx*Cursor 691 For a plug-in, any cursor defined by the properties kNatronOfx*Cursor 692 693 The special value of kNatronOfxDefaultCursor means that the host should keep the default cursor. 694 The special value of kNatronOfxBlankCursor means that the host should not draw any cursor at all. 695 696 Whenever an event is sent to overlay interacts (PenDown, PenMotion, PenUp, KeyDown, KeyUp, KeyRepeat, GainFocus, LoseFocus, the OFX Host should set the cursor to the one of the first interact which catches the event by returning kOfxStatOK to the corresponding action. If no overlay interact returns kOfxStatOK, the cursor should be set to the default cursor. 697 698 */ 699 #define kNatronOfxImageEffectPropDefaultCursors "NatronOfxImageEffectPropDefaultCursors" 700 701 // Default cursors that can be defined by a host, see http://doc.qt.io/qt-4.8/qcursor.html for an illustration to how they could look 702 #define kNatronOfxDefaultCursor "NatronOfxDefaultCursor" 703 #define kNatronOfxBlankCursor "kNatronOfxBlankCursor" 704 #define kNatronOfxArrowCursor "NatronOfxArrowCursor" 705 #define kNatronOfxUpArrowCursor "NatronOfxUpArrowCursor" 706 #define kNatronOfxCrossCursor "NatronOfxCrossCursor" 707 #define kNatronOfxIBeamCursor "NatronOfxIBeamCursor" 708 #define kNatronOfxWaitCursor "NatronOfxWaitCursor" 709 #define kNatronOfxBusyCursor "NatronOfxBusyCursor" 710 #define kNatronOfxForbiddenCursor "NatronOfxForbiddenCursor" 711 #define kNatronOfxPointingHandCursor "NatronOfxPointingHandCursor" 712 #define kNatronOfxWhatsThisCursor "NatronOfxWhatsThisCursor" 713 #define kNatronOfxSizeVerCursor "NatronOfxSizeVerCursor" 714 #define kNatronOfxSizeHorCursor "NatronOfxSizeHorCursor" 715 #define kNatronOfxSizeBDiagCursor "NatronOfxSizeBDiagCursor" 716 #define kNatronOfxSizeFDiagCursor "NatronOfxSizeFDiagCursor" 717 #define kNatronOfxSizeAllCursor "NatronOfxSizeAllCursor" 718 #define kNatronOfxSplitVCursor "NatronOfxSplitVCursor" 719 #define kNatronOfxSplitHCursor "NatronOfxSplitHCursor" 720 #define kNatronOfxOpenHandCursor "NatronOfxOpenHandCursor" 721 #define kNatronOfxClosedHandCursor "NatronOfxClosedHandCursor" 722 723 /** 724 string property on the image effect descriptor that defines which parameters should have an interface on the host viewport 725 726 - Type - string x N 727 - Property Set - image effect descriptor (read/write) and instance (read only) 728 - Default - 729 730 This property should contain a list of all parameters name that should be visible in the viewer. The ordering on which they appear 731 on the viewport is defined by their order in this property, with index 0 defining the top-left parameter and last index the bottom-right 732 parameter. 733 */ 734 #define kNatronOfxImageEffectPropInViewerContextParamsOrder "NatronOfxParamPropInViewerContextParamsOrder" 735 736 /** 737 int property that controls the host viewer parameter layout. 738 - Type - int x 1 739 - Property Set - plugin parameter descriptor (read/write) and instance (read/write only) 740 - Default - 0 741 - Valid Values - kNatronOfxParamPropInViewerContextLayoutHintNormal, kNatronOfxParamPropInViewerContextLayoutHintNormalDivider, kNatronOfxParamPropInViewerContextLayoutHintAddNewLine 742 743 kNatronOfxParamPropInViewerContextLayoutHintNormal: the host will not create a new row in the viewer interface before creating the next parameter 744 kNatronOfxParamPropInViewerContextLayoutHintNormalDivider: the host will not create a new row in the viewer interface before creating the next parameter and will add a vertical separator before this parameter and the next 745 kNatronOfxParamPropInViewerContextLayoutHintAddNewLine: the host will create a new row after this parameter 746 */ 747 #define kNatronOfxParamPropInViewerContextLayoutHint "NatronOfxParamPropInViewerContextLayoutHint" 748 749 // lay out as normal, no need line added 750 #define kNatronOfxParamPropInViewerContextLayoutHintNormal 0 751 752 // put a divider after parameter and don't add a new line 753 #define kNatronOfxParamPropInViewerContextLayoutHintNormalDivider 1 754 755 // have the next parameter start on a new line after this parameter 756 #define kNatronOfxParamPropInViewerContextLayoutHintAddNewLine 2 757 758 /** @brief Layout padding between this parameter and the next in the viewport 759 760 - Type - int X 1 761 - Property Set - plugin parameter descriptor (read/write) and instance (read only) 762 - Default - 3 763 - Valid Values - any positive integer value 764 765 It tells the host how much space (in pixels) to leave between the current parameter and the next parameter in a viewport row 766 Note that this is only relevant if kNatronOfxParamPropInViewerContextLayoutHint is set to kNatronOfxParamPropInViewerContextLayoutHintNormal 767 */ 768 #define kNatronOfxParamPropInViewerContextLayoutPadWidth "NatronOfxParamPropInViewerContextLayoutPadWidth" 769 770 771 /** @brief Label for the parameter in the viewer. This is distinct from the parameter label, because for layout efficiency we might want to display the label 772 only in the page and not on the viewer. 773 774 - Type - UTF8 C string X 1 775 - Property Set - plugin parameter descriptor (read/write) and instance (read only), 776 - Default - 777 - Valid Values - any 778 */ 779 #define kNatronOfxParamPropInViewerContextLabel "NatronOfxParamPropInViewerContextLabel" 780 781 /** @brief Flags whether the viewer interface of a parameter should be exposed to a user 782 783 - Type - int x 1 784 - Property Set - plugin parameter descriptor (read/write) and instance (read/write) 785 - Default - 0 786 - Valid Values - 0 or 1 787 788 If secret, a parameter is not exposed to a user in the viewer interface, but should otherwise behave as a normal parameter. 789 */ 790 #define kNatronOfxParamPropInViewerContextSecret "NatronOfxParamPropInViewerContextSecret" 791 792 793 /** @brief Flags whether a Boolean parameter should be represented as a toggable button instead of a checkbox. 794 - Type - int x 1 795 - Property Set - plugin boolean parameter descriptor (read/write) and instance (read/write) 796 - Default - 0 797 - Valid Values - 0 or 1 798 If 0, the boolean parameter should be a checkbox. If 1, it should be a toggable button. 799 */ 800 #define kNatronOfxBooleanParamPropIsToggableButton "NatronOfxBooleanParamPropIsToggableButton" 801 802 803 /** @brief Valid for Page, Group and Boolean parameters: 804 For a page , flags whether a Page parameter should be represented as a tool bar inside the viewer 805 For a group , flags whether a Group parameter should be represented as a tool button inside a toolbar of the viewer 806 For a boolean param , flags whether a Boolean parameter should be represented as a tool button action inside a toolbar of the viewer 807 - Type - int x 1 808 - Property Set - plugin parameter descriptor (read/write) and instance (read/write) 809 - Default - 0 810 - Valid Values - 0 or 1 811 */ 812 #define kNatronOfxParamPropInViewerContextIsInToolbar "NatronOfxPageParamPropInViewerContextIsToolbar" 813 814 815 /** @brief Valid for Group parameters with the property kNatronOfxParamPropInViewerContextIsInToolbar set to 1, Boolean parameters with the property kNatronOfxBooleanParamPropIsToggableButton set to 1 and PushButton parameters: 816 Determines whether a parameter may be assigned a shortcut by the host or not. 817 - Type - int x 1 818 - Property Set - plugin parameter descriptor (read/write) and instance (read/write) 819 - Default - 0 820 - Valid Values - 0 or 1 821 If set to 1 then the host could display this parameter in some sort of shortcut editor where the user may modify it. 822 */ 823 #define kNatronOfxParamPropInViewerContextCanHaveShortcut "NatronOfxParamPropInViewerContextCanHaveShortcut" 824 825 826 /** @brief Property defining the default shortcuts for parameters that have the property kNatronOfxParamPropInViewerContextCanHaveShortcut set to 1. This property is a list 827 of the parameter names that have a default shortcut assigned. Parameter that do not appear here but have 828 the property kNatronOfxParamPropInViewerContextCanHaveShortcut set to 1 are assumed to have no default shortcut 829 assigned, but the user could modify it via the host appropriate interface. 830 831 Each parameter name should be accompanied by the following properties of the same dimension: 832 - kNatronOfxParamPropInViewerContextShortcutSymbol 833 - kNatronOfxParamPropInViewerContextShortcutHasControlModifier 834 - kNatronOfxParamPropInViewerContextShortcutHasShiftModifier 835 - kNatronOfxParamPropInViewerContextShortcutHasAltModifier 836 - kNatronOfxParamPropInViewerContextShortcutHasMetaModifier 837 - kNatronOfxParamPropInViewerContextShortcutHasKeypadModifier 838 839 - Type - string x N 840 - Property Set - image effect descriptor (read/write) and instance (read/write) 841 - Default - 842 - Valid Values - 843 */ 844 #define kNatronOfxImageEffectPropInViewerContextDefaultShortcuts "NatronOfxImageEffectPropInViewerContextDefaultShortcuts" 845 846 /** @brief Property indicating the symbol of a shortcut as defined in ofxKeySyms.h for a parameter with a shortcut. This should not include any modifier (that is kOfxKey_Control_L, kOfxKey_Control_R, kOfxKey_Shift_L, kOfxKey_Shift_R, kOfxKey_Alt_L, kOfxKey_Alt_R, kOfxKey_Meta_L, kOfxKey_Meta_R). 847 The shortcut is associated to kNatronOfxImageEffectPropInViewerContextDefaultShortcuts and should thus have the same dimension. 848 849 - Type - int x N 850 - Property Set - image effect descriptor (read/write) and instance (read/write) 851 - Default - 0 852 - Valid Values - Any symbol defined in ofxKeySyms.h 853 */ 854 #define kNatronOfxImageEffectPropInViewerContextShortcutSymbol "NatronOfxImageEffectPropInViewerContextShortcutSymbol" 855 856 /** @brief Property indicating whether the control modifier (kOfxKey_Control_L or kOfxKey_Control_R) must be held for a parameter shortcut to trigger. 857 The shortcut is associated to kNatronOfxImageEffectPropInViewerContextDefaultShortcuts and should thus have the same dimension. 858 859 - Type - int x N 860 - Property Set - image effect descriptor (read/write) and instance (read/write) 861 - Default - 0 862 - Valid Values - 0 or 1 863 */ 864 #define kNatronOfxImageEffectPropInViewerContextShortcutHasControlModifier "NatronOfxImageEffectPropInViewerContextShortcutHasControlModifier" 865 866 867 /** @brief Property indicating whether the shit modifier (kOfxKey_Shift_L or kOfxKey_Shift_R) must be held for a parameter shortcut to trigger. 868 The shortcut is associated to kNatronOfxImageEffectPropInViewerContextDefaultShortcuts and should thus have the same dimension. 869 870 - Type - int x N 871 - Property Set - image effect descriptor (read/write) and instance (read/write) 872 - Default - 0 873 - Valid Values - 0 or 1 874 */ 875 #define kNatronOfxImageEffectPropInViewerContextShortcutHasShiftModifier "NatronOfxImageEffectPropInViewerContextShortcutHasShiftModifier" 876 877 878 /** @brief Property indicating whether the control modifier (kOfxKey_Alt_L orkOfxKey_Alt_R) must be held for a parameter shortcut to trigger. 879 The shortcut is associated to kNatronOfxImageEffectPropInViewerContextDefaultShortcuts and should thus have the same dimension. 880 881 - Type - int x N 882 - Property Set - image effect descriptor (read/write) and instance (read/write) 883 - Default - 0 884 - Valid Values - 0 or 1 885 */ 886 #define kNatronOfxImageEffectPropInViewerContextShortcutHasAltModifier "NatronOfxImageEffectPropInViewerContextShortcutHasAltModifier" 887 888 889 /** @brief Property indicating whether the control modifier (kOfxKey_Meta_L or kOfxKey_Meta_R) must be held for a parameter shortcut to trigger. 890 The shortcut is associated to kNatronOfxImageEffectPropInViewerContextDefaultShortcuts and should thus have the same dimension. 891 892 - Type - int x N 893 - Property Set - image effect descriptor (read/write) and instance (read/write) 894 - Default - 0 895 - Valid Values - 0 or 1 896 */ 897 #define kNatronOfxImageEffectPropInViewerContextShortcutHasMetaModifier "NatronOfxImageEffectPropInViewerContextShortcutHasMetaModifier" 898 899 900 /** @brief Property indicating whether the key should be pressed on the keypad for a parameter shortcut to trigger. 901 The shortcut is associated to kNatronOfxImageEffectPropInViewerContextDefaultShortcuts and should thus have the same dimension. 902 903 - Type - int x N 904 - Property Set - image effect descriptor (read/write) and instance (read/write) 905 - Default - 0 906 - Valid Values - 0 or 1 907 */ 908 #define kNatronOfxImageEffectPropInViewerContextShortcutHasKeypadModifier "NatronOfxImageEffectPropInViewerContextShortcutHasKeypadModifier" 909 910 911 /** @brief A pointer property used to hold OpenGL context-specific data, such as texture or program IDs. 912 913 - Type - pointer X 1 914 - Property Set - inArgs property set of the following actions... 915 - ::kOfxImageEffectActionRender 916 - ::kOfxImageEffectActionBeginSequenceRender 917 - ::kOfxImageEffectActionEndSequenceRender 918 - ::kOfxActionOpenGLContextDetached 919 - outArgs property set of the following actions... 920 - ::kOfxActionOpenGLContextAttached 921 - Default - NULL 922 923 This pointer is a handle to plugin-owned data holding OpenGL context-specific data 924 (e.g. texture or program IDs). This is returned by the plugin when the context is first 925 attached, and then passed as inArgs to each render call in that context. This permits running 926 several parallel renders on different OpenGL contexts, but it violates the OpenFX spec, which 927 says: 928 929 "A host cannot call ::kOfxActionOpenGLContextAttached on the same instance 930 without an intervening ::kOfxActionOpenGLContextDetached. A host can have a 931 plugin swap OpenGL contexts by issuing a attach/detach for the first context 932 then another attach for the next context." 933 934 If the plugin returns NULL as outArgs of kOfxActionOpenGLContextDetached, it is supposed 935 to follow the OpenFX spec, and will have to be detached/attached when switching the render context. 936 937 */ 938 #define kNatronOfxImageEffectPropOpenGLContextData "NatronOfxImageEffectPropOpenGLContextData" 939 940 /** @brief A int property that tells whether an interact wants colour picking information from the host. 941 942 When set to 1, the picked colour is passed as an additional kNatronOfxPropPickerColour property 943 on the inArgs of every interact action, and the draw action is called every time the picked colour 944 changes. 945 This property must be set to 1 on the interact descriptor if the descriptor may use colour picking. 946 Then, it can be set to 0 or 1 on the interact instance in order to enable colour picking and 947 to call the draw action each time the picked colour changes. 948 This can also be set on the interact of parameter interacts (kOfxParamPropInteractV1) 949 and on the interact for the background of parametric parameters 950 (kOfxParamPropParametricInteractBackground). 951 952 - Type - int x1 953 - Property Set - interact descriptor and instance (read/write) 954 - Value values - 0 or 1 955 - Default value - 0 956 */ 957 #define kNatronOfxInteractColourPicking "NatronOfxInteractColourPicking" 958 959 /** @brief Double x4 property indicating the RGBA colour of the image visualized in the host 960 viewport under the mouse. This is passed in the inargs of the draw action of parametric 961 parameters interact (i.e: with property kOfxParamPropParametricInteractBackground). 962 The special value -1,-1,-1,-1 means no color. 963 - Type - Double x4 964 - Property Set - inArgs property set of the action kOfxInteractActionDraw called on the parametric parameter 965 - Default - -1,-1,-1,-1 966 */ 967 #define kNatronOfxPropPickerColour "NatronOfxPropPickerColour" 968 969 /** @brief Property to indicate the whether the curves in the parametric parametric 970 are considered to be periodic or not. If periodic the first and last control point 971 should be considered equal in the curve and cannot be moved from their parametric position. 972 The host should always evaluate the curve in-between the first and last keyframes. 973 974 - Type - int X 1 975 - Property Set - parametric parameter descriptor (read/write only), and instance (read only) 976 - Default Value - (0) 977 - Valid Values - 1 or 0 978 If 1 the curves are considered to be periodic. 979 */ 980 #define kNatronOfxParamPropParametricIsPeriodic "OfxParamPropParametricIsPeriodic" 981 982 /** Used to indicate the format size (in pixel coordinates) of the stream that should be displayed in output of this plug-in. It is not necessarily the same as the region of definition. 983 984 Example: User has a project size 2K. The user draws a rectangle which does not cover the full project size, the region of definition is thus smaller than the project size. Think now of a Reformat plug-in appended after the rectangle to perform a scale down to 1K: the region of definition in output of the plug-in should be half the region of the original rectangle and the format should become 1K. Without this property, the Reformat plug-in would be forced to have a region of definition of 1K and render many un-needed pixels. 985 986 - Type - int X4 987 - Property Set - a read/write out argument property of the kOfxImageEffectActionGetClipPreferences and a read only property of a clip instance 988 - Default - Host by default sets the format to the "Source" clip format. If the effect is in the General context, the format is initialized to the first non-optional input clip. 989 If there are no input clips, the format is initialized to the project extent/size. 990 991 The order of the values is x1, y1, x2, y2 where x1 <= x2 and y1 <= y2. 992 993 **/ 994 #define kOfxImageClipPropFormat "OfxImageClipPropFormat" 995 996 997 998 //////////////////////////////////////////////////////////////////////////////// 999 //////////////////////////////////////////////////////////////////////////////// 1000 //////////////////////////////////////////////////////////////////////////////// 1001 // Extensions for image effects that can return a distortion function rather 1002 // than an image. A distortion function gost from a 2D distorted position in 1003 // canonical coordinates in the output distorted image to the undistorted 1004 // position in canonical coordinates in the source image. 1005 1006 // This implemented the standard change originally proposed at http://openeffects.org/standard_changes/243 1007 1008 /** @brief Property to indicate that a plugin, clip or host can handle distortions 1009 1010 - Type - int X 1 1011 - Property Set - host descriptor (read only), plugin instance (read/write), clip descriptor (read/write) 1012 - Default - 0 1013 - Valid Values - This must be one of 1014 - 0 if the host or plugin cannot make use of the kOfxImageEffectActionGetInverseDistortion 1015 - 1 if the host or plugin can use the kOfxImageEffectActionGetInverseDistortion, or the clip 1016 can return images with a distortion function attached (@see kOfxPropInverseDistortionFunction) 1017 1018 This is a property on the descriptor. 1019 */ 1020 #define kOfxImageEffectPropCanDistort "OfxImageEffectPropCanDistort" 1021 1022 /** @brief Action called in place of a render to recover a distortion from an effect. 1023 1024 Some effects do a simple matrix transform or distortion on their images, the cleverness in the effect 1025 is how that transform is arrived at. For example a stabilisation effect which analyses 1026 it's input clip in user interface and writes key frames to a set of params which represent 1027 a transform. The render action of such an effect is just a transform by a matrix. 1028 1029 Often, such effects are chained together, and you are incurring both an extra compute cost 1030 and a degradation in the quality of the output image by having the effects in question 1031 perform multiple image transforms and filtering actions. 1032 1033 In such a situation it would be much better if you could recover the transforms from each 1034 of the effects and compose them together and transform the image once. This improves 1035 both performance and quality. This action allows you to do such a thing and serves in 1036 place of a standard render call. 1037 1038 To be able to successfully reproduce the same result as the render action with this 1039 action, any effects that implement it must adhere to several conditions... 1040 The effect does not need the following called to determine the correct transform, 1041 - The Get Region of Definition Action 1042 - The Get Regions Of Interest Action 1043 - The Get Frames Needed Action 1044 - The Is Identity Action 1045 - The Render Action 1046 - The Begin Sequence Render Action 1047 - The End Sequence Render Action 1048 The effect only needs a single image frome the clip named in the out args of this action 1049 1050 1051 For maximum flexibility, a plug-in must be allowed to fetch images inside this action, so as to be 1052 able to perform on the fly analysis to calculate the required transform. Ideally this should be 1053 discouraged in favour of simply returning pre-analysed values. 1054 1055 Note that the render action can still be called if a host so chooses, this action does not 1056 completely replace the render action of such an effect. 1057 1058 When the plug-in needs to sample a source clip, if the plug-in has flagged the source clip kOfxImageEffectCanDistort to 1 1059 then an image fetched from this clip *may* receive a pointer to such function. 1060 In this case, this is a pointer of a function of the host that will call in turn the distortion function of all concatenated source effects 1061 and return the final undistorted position. 1062 Note that even if this effect supports returning a distortion, 1063 the concatenation will not include the distortion provided by this effect, it will have to be applied on top of the concatenation function. 1064 1065 This action has the following properties on its arguments.... 1066 inargs - 1067 - kOfxPropTime (double x1)- the time at which to test for identity 1068 - kOfxImageEffectPropFieldToRender (string x1)- the field being transformed 1069 - kOfxImageEffectPropRenderScale (double x2)- the scale factor being applied to the images being transformed 1070 - kFnOfxImageEffectPropView (int x1) (only if view aware) 1071 1072 outargs - 1073 - kOfxPropName (string x1) - this to the name of the input clip that would be transformed by the effect during render 1074 defaults to "Source". The input clip image will be fetched at the time and view given in the inArgs. 1075 1076 - kOfxPropMatrix3x3 - (double x9) If the output distortion can be represented as a 3x3 matrix, then prefer this as the 1077 host may optimize the concatenation of 3x3 matrix into a single matrix. This is in canonical coordinates space, 1078 going from the source image to the destination, defaults to the identity matrix. 1079 1080 If however the distortion cannot be a simple 3x3 matrix, then the following properties should be set in the outArgs: 1081 1082 - kOfxPropInverseDistortionFunction (pointer x1): A pointer to the distortion function itself that the host should call. 1083 The function has the signature described below (OfxDistortionFunctionV1) 1084 1085 - kOfxPropInverseDistortionFunctionData (pointer x1) : Pointer to datas owned by the plug-in that should be passed back as customData 1086 to the OfxDistortionFunctionV1 function. This can contain parameter values or STMaps or anything custom to the plug-in. 1087 These datas will be freed by the kOfxPropInverseDistortionFunctionFreeData speficied below once the host does not need them anymore. 1088 Note that the host may cache these datas away and it is important to hint the host about the size these datas holds in the host cache. 1089 1090 - kOfxPropInverseDistortionFunctionDataSize (int x1): An estimated size in bytes of the memory held by the datas pointed to by kOfxPropInverseDistortionFunctionData. 1091 The host may cache these datas away and it is important to hint the host about the size these datas holds in the host cache. 1092 This should not overflow an integer size. 1093 1094 - kOfxPropInverseDistortionDataFreeFunction (pointer x1): Pointer to a function called by the host when the concatenation is done to free 1095 the datas pointed to by kOfxPropInverseDistortionFunctionData 1096 1097 1098 1099 @returns 1100 - ::kOfxStatDefault - don't attempt to any of the out args, but render the image as per normal, 1101 - ::kOfxStatOK - the transfrom and clip name were set and can be used to modify the named image appropriately, 1102 1103 */ 1104 1105 #define kOfxImageEffectActionGetInverseDistortion "OfxImageEffectActionGetInverseDistortion" 1106 1107 /* 1108 @brief Property that holds a pointer to a function of type OfxDistortionFunctionV1 1109 - Type - Pointer x1 1110 - Property Set - outArgs of kOfxImageEffectActionGetInverseDistortion and image instance (read only) 1111 - Default - 0 1112 1113 The plug-in returns a pointer of such as function in the kOfxImageEffectActionGetInverseDistortion action. 1114 */ 1115 #define kOfxPropInverseDistortionFunction "OfxPropInverseDistortionFunction" 1116 1117 /* 1118 @brief Property that holds a pointer to data used in the function pointed to by kOfxPropInverseDistortionFunction. 1119 - Type - Pointer x1 1120 - Property Set - outArgs of kOfxImageEffectActionGetInverseDistortion and image instance (read only) 1121 - Default - 0 1122 1123 When calling kOfxImageEffectActionGetInverseDistortion, the plug-in returns these data that should be used by the kOfxPropInverseDistortionFunction function 1124 passed in the outArgs of the action. 1125 1126 When the property is on the image instance, these are host data the should be passed to the function pointed to by the kOfxPropInverseDistortionFunction property 1127 on the same image. 1128 */ 1129 #define kOfxPropInverseDistortionFunctionData "OfxPropInverseDistortionFunctionData" 1130 1131 1132 /* 1133 @brief Property that hints the host about the total size of the datas pointed to by kOfxPropInverseDistortionFunctionData. If these datas contain buffers or images 1134 they should be summed up. 1135 The host may cache these datas away and it is important to hint the host about the size these datas holds in the host cache. 1136 This should not overflow an integer size. 1137 1138 - Type - Int x1 1139 - Property Set - outArgs of kOfxImageEffectActionGetInverseDistortion action 1140 - Default - 0 1141 1142 */ 1143 #define kOfxPropInverseDistortionFunctionDataSize "OfxPropInverseDistortionFunctionDataSize" 1144 1145 /* 1146 @brief Property that holds a pointer to a function that can be called to free the data pointed to by kOfxPropInverseDistortionFunctionData that were passed back 1147 by a plug-in in the kOfxImageEffectActionGetInverseDistortion action 1148 1149 - Type - Pointer x1 1150 - Property Set - outArgs of the kOfxImageEffectActionGetInverseDistortion action 1151 - Default - 0 1152 */ 1153 #define kOfxPropInverseDistortionDataFreeFunction "OfxPropInverseDistortionDataFreeFunction" 1154 1155 /** 1156 @brief Prototype of the distortion passed to the kOfxPropInverseDistortionFunction property. It takes in input the distorted position and should output the 1157 undistorted position, both in canonical coordinates. Optionnally the Jacobian may be output. 1158 @param customData These are custom datas that were returned by the plug-in in the kOfxImageEffectActionGetInverseDistortion action in kOfxPropInverseDistortionFunctionData 1159 @param wantsJacobian True if the caller would like the function to return a Jacobian, if possible. Note that the function may not return a Jacobian 1160 even if it was asked for, in which case the caller will have to compute it using for example finite differences. 1161 @param gotJaboian True if the jacobian was computed and set in output. If wantsJacobian is set to false, this parameter may be NULL. 1162 @param jacobian The 4 partial derivatives of the function: [dFx/dx, dFx/dy, dFy/dx, dFy/dy]. 1163 If wantsJacobian is set to false, this parameter may be NULL. 1164 **/ 1165 typedef void (*OfxInverseDistortionFunctionV1)(const void* customData, 1166 double distortedX, double distortedY, 1167 bool wantsJacobian, 1168 double *undistortedX, double *undistortedY, 1169 bool* gotJabobian, 1170 double jacobian[4]); 1171 1172 /* 1173 * @brief Prototype of the function passed to the kOfxPropInverseDistortionDataFreeFunction property. It takes in input the kOfxPropInverseDistortionFunctionData data that 1174 were returned by the kOfxImageEffectActionGetInverseDistortion action and should free them. 1175 */ 1176 typedef void (*OfxInverseDistortionDataFreeFunctionV1)(void* customData); 1177 1178 /** @brief Property that represents a 2D matrix 1179 1180 - Type - double X 9 1181 - Property Set - out args of kOfxImageEffectActionGetInverseDistortion, or on an image instance (read only) 1182 - Default - the identity matrix 1183 - Valid Values - any matrix value 1184 1185 The 9 values of this property represent a 2D 3 by 3 matrix. The matrix is in row/column format. 1186 **/ 1187 1188 #define kOfxPropMatrix3x3 "OfxPropMatrix3x3" 1189 1190 /** @brief The pixel ratio of the screen. On Retina screens, this would typically return 2. 1191 This is needed because typically when displayed on a Retina screen, the OpenGL framebuffer drawn to 1192 would be bigger, hence all functions taking pixels need to be scaled accordingly. Namely: 1193 - glPointSize 1194 - glLineWidth 1195 - glScissor, 1196 - etc... 1197 1198 - Type - double X 1 1199 - Property Set - read only in argument to the ::kOfxInteractActionPenMotion, ::kOfxInteractActionPenDown and ::kOfxInteractActionPenUp actions 1200 - Default value - 1. 1201 */ 1202 #define kOfxInteractPropScreenPixelRatio "OfxInteractPropScreenPixelRatio" 1203 1204 #endif // #ifndef _ofxNatron_h_ 1205