1 #ifndef _ofxCore_h_ 2 #define _ofxCore_h_ 3 4 /* 5 Software License : 6 7 Copyright (c) 2003-2015, The Open Effects Association Ltd. All rights reserved. 8 9 Redistribution and use in source and binary forms, with or without 10 modification, are permitted provided that the following conditions are met: 11 12 * Redistributions of source code must retain the above copyright notice, 13 this list of conditions and the following disclaimer. 14 * Redistributions in binary form must reproduce the above copyright notice, 15 this list of conditions and the following disclaimer in the documentation 16 and/or other materials provided with the distribution. 17 * Neither the name The Open Effects Association Ltd, nor the names of its 18 contributors may be used to endorse or promote products derived from this 19 software without specific prior written permission. 20 21 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 22 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 23 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR 25 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 26 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 28 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 34 #include "stddef.h" // for size_t 35 #include <limits.h> // for INT_MIN & INT_MAX 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 /** @file ofxCore.h 42 Contains the core OFX architectural struct and function definitions. For more details on the basic OFX architecture, see \ref Architecture. 43 */ 44 45 46 /** @brief Platform independent export macro. 47 * 48 * This macro is to be used before any symbol that is to be 49 * exported from a plug-in. This is OS/compiler dependent. 50 */ 51 #if defined(WIN32) || defined(WIN64) 52 #define OfxExport extern __declspec(dllexport) 53 #else 54 #define OfxExport extern __attribute__ ((visibility ("default"))) 55 #endif 56 57 /** @brief Blind data structure to manipulate sets of properties through */ 58 typedef struct OfxPropertySetStruct *OfxPropertySetHandle; 59 60 /** @brief OFX status return type */ 61 typedef int OfxStatus; 62 63 /** @brief Generic host structure passed to OfxPlugin::setHost function 64 65 This structure contains what is needed by a plug-in to bootstrap its connection 66 to the host. 67 */ 68 typedef struct OfxHost { 69 /** @brief Global handle to the host. Extract relevant host properties from this. 70 This pointer will be valid while the binary containing the plug-in is loaded. 71 */ 72 OfxPropertySetHandle host; 73 74 /** @brief The function which the plug-in uses to fetch suites from the host. 75 76 \arg \e host - the host the suite is being fetched from this \em must be the \e host member of the OfxHost struct containing fetchSuite. 77 \arg \e suiteName - ASCII string labelling the host supplied API 78 \arg \e suiteVersion - version of that suite to fetch 79 80 Any API fetched will be valid while the binary containing the plug-in is loaded. 81 82 Repeated calls to fetchSuite with the same parameters will return the same pointer. 83 84 returns 85 - NULL if the API is unknown (either the api or the version requested), 86 - pointer to the relevant API if it was found 87 */ 88 const void *(*fetchSuite)(OfxPropertySetHandle host, const char *suiteName, int suiteVersion); 89 } OfxHost; 90 91 92 /** @brief Entry point for plug-ins 93 94 \arg \e action - ASCII c string indicating which action to take 95 \arg \e instance - object to which action should be applied, this will need to be cast to the appropriate blind data type depending on the \e action 96 \arg \e inData - handle that contains action specific properties 97 \arg \e outData - handle where the plug-in should set various action specific properties 98 99 This is how the host generally communicates with a plug-in. Entry points are used to pass messages 100 to various objects used within OFX. The main use is within the OfxPlugin struct. 101 102 The exact set of actions is determined by the plug-in API that is being implemented, however all plug-ins 103 can perform several actions. For the list of actions consult \ref ActionsAll. 104 */ 105 typedef OfxStatus (OfxPluginEntryPoint)(const char *action, const void *handle, OfxPropertySetHandle inArgs, OfxPropertySetHandle outArgs); 106 107 /** @brief The structure that defines a plug-in to a host. 108 * 109 * This structure is the first element in any plug-in structure 110 * using the OFX plug-in architecture. By examining its members 111 * a host can determine the API that the plug-in implements, 112 * the version of that API, its name and version. 113 * 114 * For details see \ref Architecture. 115 * 116 */ 117 typedef struct OfxPlugin { 118 /** Defines the type of the plug-in, this will tell the host what the plug-in does. e.g.: an image 119 effects plug-in would be a "OfxImageEffectPlugin" 120 */ 121 const char *pluginApi; 122 123 /** Defines the version of the pluginApi that this plug-in implements */ 124 int apiVersion; 125 126 /** String that uniquely labels the plug-in among all plug-ins that implement an API. 127 It need not necessarily be human sensible, however the preference is to use reverse 128 internet domain name of the developer, followed by a '.' then by a name that represents 129 the plug-in.. It must be a legal ASCII string and have no whitespace in the 130 name and no non printing chars. 131 For example "uk.co.somesoftwarehouse.myPlugin" 132 */ 133 const char *pluginIdentifier; 134 135 /** Major version of this plug-in, this gets incremented when backwards compatibility is broken. */ 136 unsigned int pluginVersionMajor; 137 138 /** Major version of this plug-in, this gets incremented when software is changed, 139 but does not break backwards compatibility. */ 140 unsigned int pluginVersionMinor; 141 142 /** @brief Function the host uses to connect the plug-in to the host's api fetcher 143 144 \arg \e fetchApi - pointer to host's API fetcher 145 146 Mandatory function. 147 148 The very first function called in a plug-in. The plug-in \em must \em not call any OFX functions within this, it must only set its local copy of the host pointer. 149 150 \pre 151 - nothing else has been called 152 153 \post 154 - the pointer suite is valid until the plug-in is unloaded 155 */ 156 void (*setHost)(OfxHost *host); 157 158 /** @brief Main entry point for plug-ins 159 160 Mandatory function. 161 162 The exact set of actions is determined by the plug-in API that is being implemented, however all plug-ins 163 can perform several actions. For the list of actions consult \ref ActionsAll. 164 165 Preconditions 166 - setHost has been called 167 */ 168 OfxPluginEntryPoint *mainEntry; 169 } OfxPlugin; 170 171 /** 172 \defgroup ActionsAll OFX Actions 173 174 These are the actions passed to a plug-in's 'main' function 175 */ 176 /*@{*/ 177 178 /** @brief 179 180 This action is the first action passed to a plug-in after the 181 binary containing the plug-in has been loaded. It is there to allow a 182 plug-in to create any global data structures it may need and is also 183 when the plug-in should fetch suites from the host. 184 185 The \ref handle, \ref inArgs and \ref outArgs arguments to the \ref mainEntry 186 are redundant and should be set to NULL. 187 188 \pre 189 - The plugin's \ref OfxPlugin::setHost function has been called 190 191 \post 192 This action will not be called again while the binary containing the plug-in remains loaded. 193 194 @returns 195 - \ref kOfxStatOK, the action was trapped and all was well, 196 - \ref kOfxStatReplyDefault, the action was ignored, 197 - \ref kOfxStatFailed, the load action failed, no further actions will be 198 passed to the plug-in, 199 - \ref kOfxStatErrFatal, fatal error in the plug-in. 200 */ 201 #define kOfxActionLoad "OfxActionLoad" 202 203 /** @brief 204 205 The kOfxActionDescribe is the second action passed to a plug-in. It is 206 where a plugin defines how it behaves and the resources it needs to 207 function. 208 209 Note that the handle passed in acts as a descriptor for, rather than an 210 instance of the plugin. The handle is global and unique. The plug-in is 211 at liberty to cache the handle away for future reference until the 212 plug-in is unloaded. 213 214 Most importantly, the effect must set what image effect contexts it is 215 capable of working in. 216 217 This action *must* be trapped, it is not optional. 218 219 220 @param handle handle to the plug-in descriptor, cast to an \ref OfxImageEffectHandle 221 @param inArgs is redundant and is set to NULL 222 @param outArgs is redundant and is set to NULL 223 224 \pre 225 - \ref kOfxActionLoad has been called 226 227 \post 228 - \ref kOfxActionDescribe will not be called again, unless it fails and 229 returns one of the error codes where the host is allowed to attempt 230 the action again 231 - the handle argument, being the global plug-in description handle, is 232 a valid handle from the end of a sucessful describe action until the 233 end of the \ref kOfxActionUnload action (ie: the plug-in can cache it away 234 without worrying about it changing between actions). 235 - \ref kOfxImageEffectActionDescribeInContext 236 will be called once for each context that the host and plug-in 237 mutually support. 238 239 @returns 240 - \ref kOfxStatOK, the action was trapped and all was well 241 - \ref kOfxStatErrMissingHostFeature, in which the plugin will be unloaded 242 and ignored, plugin may post message 243 - \ref kOfxStatErrMemory, in which case describe may be called again after a 244 memory purge 245 - \ref kOfxStatFailed, something wrong, but no error code appropriate, 246 plugin to post message 247 - \ref kOfxStatErrFatal 248 249 */ 250 #define kOfxActionDescribe "OfxActionDescribe" 251 252 /** @brief 253 254 This action is the last action passed to the plug-in before the 255 binary containing the plug-in is unloaded. It is there to allow a 256 plug-in to destroy any global data structures it may have created. 257 258 The handle, inArgs and outArgs arguments to the main entry 259 are redundant and should be set to NULL. 260 261 \pref 262 - the \ref kOfxActionLoad action has been called 263 - all instances of a plugin have been destroyed 264 265 \post 266 - No other actions will be called. 267 268 @returns 269 - \ref kOfxStatOK, the action was trapped all was well 270 - \ref kOfxStatReplyDefault, the action was ignored 271 - \ref kOfxStatErrFatal, in which case we the program will be forced to quit 272 273 */ 274 #define kOfxActionUnload "OfxActionUnload" 275 276 /** @brief 277 278 This action is an action that may be passed to a plug-in 279 instance from time to time in low memory situations. Instances recieving 280 this action should destroy any data structures they may have and release 281 the associated memory, they can later reconstruct this from the effect's 282 parameter set and associated information. 283 284 For Image Effects, it is generally a bad idea to call this after each 285 render, but rather it should be called after 286 \ref kOfxImageEffectActionEndSequenceRender 287 Some effects, typically those flagged with the 288 \ref kOfxImageEffectInstancePropSequentialRender 289 property, may need to cache information from previously rendered frames 290 to function correctly, or have data structures that are expensive to 291 reconstruct at each frame (eg: a particle system). Ideally, such effect 292 should free such structures during the 293 \ref kOfxImageEffectActionEndSequenceRender action. 294 295 @param handle handle to the plug-in instance, cast to an \ref OfxImageEffectHandle 296 @param inArgs is redundant and is set to NULL 297 @param outArgs is redundant and is set to NULL 298 299 \pre 300 - \ref kOfxActionCreateInstance has been called on the instance handle, 301 302 @returns 303 - \ref kOfxStatOK, the action was trapped and all was well 304 - \ref kOfxStatReplyDefault, the action was ignored 305 - \ref kOfxStatErrFatal, 306 - \ref kOfxStatFailed, something went wrong, but no error code appropriate, 307 the plugin should to post a message 308 */ 309 #define kOfxActionPurgeCaches "OfxActionPurgeCaches" 310 311 /** @brief 312 313 This action is called when a plugin should synchronise any private data 314 structures to its parameter set. This generally occurs when an effect is 315 about to be saved or copied, but it could occur in other situations as 316 well. 317 318 @param handle handle to the plug-in instance, cast to an \ref OfxImageEffectHandle 319 @param inArgs is redundant and is set to NULL 320 @param outArgs is redundant and is set to NULL 321 322 \pre 323 - \ref kOfxActionCreateInstance has been called on the instance handle, 324 325 \post 326 - Any private state data can be reconstructed from the parameter set, 327 328 @returns 329 - \ref kOfxStatOK, the action was trapped and all was well 330 - \ref kOfxStatReplyDefault, the action was ignored 331 - \ref kOfxStatErrFatal, 332 - \ref kOfxStatFailed, something went wrong, but no error code appropriate, 333 the plugin should to post a message 334 */ 335 #define kOfxActionSyncPrivateData "OfxActionSyncPrivateData" 336 337 /** @brief 338 339 This action is the first action passed to a plug-in's 340 instance after its creation. It is there to allow a plugin to create any 341 per-instance data structures it may need. 342 343 @param handle handle to the plug-in instance, cast to an \ref OfxImageEffectHandle 344 @param inArgs is redundant and is set to NULL 345 @param outArgs is redundant and is set to NULL 346 347 \pref 348 - \ref kOfxActionDescribe has been called 349 - the instance is fully constructed, with all objects requested in the 350 describe actions (eg, parameters and clips) have been constructed and 351 have had their initial values set. This means that if the values are 352 being loaded from an old setup, that load should have taken place 353 before the create instance action is called. 354 355 \post 356 - the instance pointer will be valid until the 357 \ref kOfxActionDestroyInstance 358 action is passed to the plug-in with the same instance handle 359 360 @returns 361 - \ref kOfxStatOK, the action was trapped and all was well 362 - \ref kOfxStatReplyDefault, the action was ignored, but all was well anyway 363 - \ref kOfxStatErrFatal 364 - \ref kOfxStatErrMemory, in which case this may be called again after a 365 memory purge 366 - \ref kOfxStatFailed, something went wrong, but no error code appropriate, 367 the plugin should to post a message if possible and the host should 368 destroy the instanace handle and not attempt to proceed further 369 */ 370 #define kOfxActionCreateInstance "OfxActionCreateInstance" 371 372 /** @brief 373 374 375 This action is the last passed to a plug-in's instance before its 376 destruction. It is there to allow a plugin to destroy any per-instance 377 data structures it may have created. 378 379 @param handle 380 handle to the plug-in instance, cast to an \ref OfxImageEffectHandle 381 @param inArgs is redundant and is set to NULL 382 @param outArgs is redundant and is set to NULL 383 384 \pre 385 - \ref kOfxActionCreateInstance 386 has been called on the handle, 387 - the instance has not had any of its members destroyed yet, 388 389 \post 390 - the instance pointer is no longer valid and any operation on it will 391 be undefined 392 393 @returns 394 To some extent, what is returned is moot, a bit like throwing an 395 exception in a C++ destructor, so the host should continue destruction 396 of the instance regardless. 397 398 - \ref kOfxStatOK, the action was trapped and all was well, 399 - \ref kOfxStatReplyDefault, the action was ignored as the effect had nothing 400 to do, 401 - \ref kOfxStatErrFatal, 402 - \ref kOfxStatFailed, something went wrong, but no error code appropriate, 403 the plugin should to post a message. 404 405 */ 406 #define kOfxActionDestroyInstance "OfxActionDestroyInstance" 407 408 /** @brief 409 410 This action signals that something has changed in a plugin's instance, 411 either by user action, the host or the plugin itself. All change actions 412 are bracketed by a pair of \ref kOfxActionBeginInstanceChanged and 413 \ref kOfxActionEndInstanceChanged actions. The ``inArgs`` property set is 414 used to determine what was the thing inside the instance that was 415 changed. 416 417 @param handle handle to the plug-in instance, cast to an \ref OfxImageEffectHandle 418 @param inArgs has the following properties 419 - \ref kOfxPropType The type of the thing that changed which will be one of.. 420 421 - \ref kOfxTypeParameter Indicating a parameter's value has changed 422 in some way 423 - \ref kOfxTypeClip A clip to an image effect has changed in some 424 way (for Image Effect Plugins only) 425 426 - \ref kOfxPropName the name of the thing that was changed in the instance 427 - \ref kOfxPropChangeReason what triggered the change, which will be one of... 428 429 - \ref kOfxChangeUserEdited - the user or host changed the instance 430 somehow and caused a change to something, this includes 431 undo/redos, resets and loading values from files or presets, 432 433 - \ref kOfxChangePluginEdited - the plugin itself has changed the 434 value of the instance in some action 435 - \ref kOfxChangeTime - the time has changed and this has affected the 436 value of the object because it varies over time 437 438 - \ref kOfxPropTime 439 - the effect time at which the chang occured (for Image Effect Plugins only) 440 - \ref kOfxImageEffectPropRenderScale 441 - the render scale currently being applied to any image fetched 442 from a clip (for Image Effect Plugins only) 443 444 @param outArgs is redundant and is set to NULL 445 446 \pre 447 - \ref kOfxActionCreateInstance has been called on the instance handle, 448 - \ref kOfxActionBeginInstanceChanged has been called on the instance 449 handle. 450 451 \post 452 - \ref kOfxActionEndInstanceChanged will be called on the instance handle. 453 454 @returns 455 - \ref kOfxStatOK, the action was trapped and all was well 456 - \ref kOfxStatReplyDefault, the action was ignored 457 - \ref kOfxStatErrFatal, 458 - \ref kOfxStatFailed, something went wrong, but no error code appropriate, 459 the plugin should to post a message 460 461 */ 462 #define kOfxActionInstanceChanged "OfxActionInstanceChanged" 463 464 /** @brief 465 466 The \ref kOfxActionBeginInstanceChanged and \ref kOfxActionEndInstanceChanged actions 467 are used to bracket all \ref kOfxActionInstanceChanged actions, whether a 468 single change or multiple changes. Some changes to a plugin instance can 469 be grouped logically (eg: a 'reset all' button resetting all the 470 instance's parameters), the begin/end instance changed actions allow a 471 plugin to respond appropriately to a large set of changes. For example, 472 a plugin that maintains a complex internal state can delay any changes 473 to that state until all parameter changes have completed. 474 475 @param handle 476 handle to the plug-in instance, cast to an \ref OfxImageEffectHandle 477 @param inArgs has the following properties 478 - \ref kOfxPropChangeReason what triggered the change, which will be one of... 479 - \ref kOfxChangeUserEdited - the user or host changed the instance 480 somehow and caused a change to something, this includes 481 undo/redos, resets and loading values from files or presets, 482 - \ref kOfxChangePluginEdited - the plugin itself has changed the 483 value of the instance in some action 484 - \ref kOfxChangeTime - the time has changed and this has affected the 485 value of the object because it varies over time 486 487 @param outArgs is redundant and is set to NULL 488 489 \post 490 - For \ref kOfxActionBeginInstanceChanged , \ref kOfxActionCreateInstance has been called on the instance handle. 491 - For \ref kOfxActionEndInstanceChanged , \ref kOfxActionBeginInstanceChanged has been called on the instance handle. 492 - \ref kOfxActionCreateInstance has been called on the instance handle. 493 494 \post 495 - For \ref kOfxActionBeginInstanceChanged, \ref kOfxActionInstanceChanged will be called at least once on the instance handle. 496 - \ref kOfxActionEndInstanceChanged will be called on the instance handle. 497 498 @returns 499 - \ref kOfxStatOK, the action was trapped and all was well 500 - \ref kOfxStatReplyDefault, the action was ignored 501 - \ref kOfxStatErrFatal, 502 - \ref kOfxStatFailed, something went wrong, but no error code appropriate, 503 the plugin should to post a message 504 */ 505 #define kOfxActionBeginInstanceChanged "OfxActionBeginInstanceChanged" 506 507 /** @brief Action called after the end of a set of \ref kOfxActionEndInstanceChanged actions, used with ::kOfxActionBeginInstanceChanged to bracket a grouped set of changes, see \ref kOfxActionBeginInstanceChanged*/ 508 #define kOfxActionEndInstanceChanged "OfxActionEndInstanceChanged" 509 510 /** @brief 511 512 This is called when an instance is *first* actively edited by a user, 513 ie: and interface is open and parameter values and input clips can be 514 modified. It is there so that effects can create private user interface 515 structures when necassary. Note that some hosts can have multiple 516 editors open on the same effect instance simulateously. 517 518 519 @param handle handle to the plug-in instance, cast to an \ref OfxImageEffectHandle 520 @param inArgs is redundant and is set to NULL 521 @param outArgs is redundant and is set to NULL 522 523 \pre 524 - \ref kOfxActionCreateInstance has been called on the instance handle, 525 526 \post 527 - \ref kOfxActionEndInstanceEdit will be called when the last editor is 528 closed on the instance 529 530 @returns 531 - \ref kOfxStatOK, the action was trapped and all was well 532 - \ref kOfxStatReplyDefault, the action was ignored 533 - \ref kOfxStatErrFatal, 534 - \ref kOfxStatFailed, something went wrong, but no error code appropriate, 535 the plugin should to post a message 536 */ 537 #define kOfxActionBeginInstanceEdit "OfxActionBeginInstanceEdit" 538 539 /** @brief 540 541 This is called when the *last* user interface on an instance closed. It 542 is there so that effects can destroy private user interface structures 543 when necassary. Note that some hosts can have multiple editors open on 544 the same effect instance simulateously, this will only be called when 545 the last of those editors are closed. 546 547 @param handle handle to the plug-in instance, cast to an \ref OfxImageEffectHandle 548 @param inArgs is redundant and is set to NULL 549 @param outArgs is redundant and is set to NULL 550 551 \pre 552 - \ref kOfxActionBeginInstanceEdit has been called on the instance handle, 553 554 \post 555 - no user interface is open on the instance 556 557 @returns 558 - \ref kOfxStatOK, the action was trapped and all was well 559 - \ref kOfxStatReplyDefault, the action was ignored 560 - \ref kOfxStatErrFatal, 561 - \ref kOfxStatFailed, something went wrong, but no error code appropriate, 562 the plugin should to post a message 563 */ 564 #define kOfxActionEndInstanceEdit "OfxActionEndInstanceEdit" 565 566 /*@}*/ 567 568 /** @brief Returns the 'nth' plug-in implemented inside a binary 569 * 570 * Returns a pointer to the 'nth' plug-in implemented in the binary. A function of this type 571 * must be implemented in and exported from each plug-in binary. 572 */ 573 OfxExport OfxPlugin *OfxGetPlugin(int nth); 574 575 /** @brief Defines the number of plug-ins implemented inside a binary 576 * 577 * A host calls this to determine how many plug-ins there are inside 578 * a binary it has loaded. A function of this type 579 * must be implemented in and exported from each plug-in binary. 580 */ 581 OfxExport int OfxGetNumberOfPlugins(void); 582 583 /** 584 \defgroup PropertiesAll Ofx Properties 585 586 These strings are used to identify properties within OFX, they are broken up by the host suite or API they relate to. 587 */ 588 /*@{*/ 589 590 /** 591 \defgroup PropertiesGeneral General Properties 592 593 These properties are general properties and apply to may objects across OFX 594 */ 595 /*@{*/ 596 597 /** @brief Property on the host descriptor, saying what API version of the API is being implemented 598 599 - Type - int X N 600 - Property Set - host descriptor. 601 602 This is a version string that will specify which version of the API is being implemented by a host. It 603 can have multiple values. For example "1.0", "1.2.4" etc..... 604 605 If this is not present, it is safe to assume that the version of the API is "1.0". 606 */ 607 #define kOfxPropAPIVersion "OfxPropAPIVersion" 608 609 /** @brief General property used to get/set the time of something. 610 611 - Type - double X 1 612 - Default - 0, if a setable property 613 - Property Set - commonly used as an argument to actions, input and output. 614 */ 615 #define kOfxPropTime "OfxPropTime" 616 617 /** @brief Indicates if a host is actively editing the effect with some GUI. 618 619 - Type - int X 1 620 - Property Set - effect instance (read only) 621 - Valid Values - 0 or 1 622 623 If false the effect currently has no interface, however this may be because the effect is loaded in a background render host, or it may be loaded on an interactive host that has not yet opened an editor for the effect. 624 625 The output of an effect should only ever depend on the state of its parameters, not on the interactive flag. The interactive flag is more a courtesy flag to let a plugin know that it has an interace. If a plugin want's to have its behaviour dependant on the interactive flag, it can always make a secret parameter which shadows the state if the flag. 626 */ 627 #define kOfxPropIsInteractive "OfxPropIsInteractive" 628 629 /** @brief The file path to the plugin. 630 631 - Type - C string X 1 632 - Property Set - effect descriptor (read only) 633 634 This is a string that indicates the file path where the plug-in was found by the host. The path is in the native 635 path format for the host OS (eg: UNIX directory separators are forward slashes, Windows ones are backslashes). 636 637 The path is to the bundle location, see \ref InstallationLocation. 638 eg: '/usr/OFX/Plugins/AcmePlugins/AcmeFantasticPlugin.ofx.bundle' 639 */ 640 #define kOfxPluginPropFilePath "OfxPluginPropFilePath" 641 642 /** @brief A private data pointer that the plug-in can store its own data behind. 643 644 - Type - pointer X 1 645 - Property Set - plugin instance (read/write), 646 - Default - NULL 647 648 This data pointer is unique to each plug-in instance, so two instances of the same plug-in do not share the same data pointer. Use it to hang any needed private data structures. 649 */ 650 #define kOfxPropInstanceData "OfxPropInstanceData" 651 652 /** @brief General property, used to identify the kind of an object behind a handle 653 654 - Type - ASCII C string X 1 655 - Property Set - any object handle (read only) 656 - Valid Values - currently this can be... 657 - ::kOfxTypeImageEffectHost 658 - ::kOfxTypeImageEffect 659 - ::kOfxTypeImageEffectInstance 660 - ::kOfxTypeParameter 661 - ::kOfxTypeParameterInstance 662 - ::kOfxTypeClip 663 - ::kOfxTypeImage 664 */ 665 #define kOfxPropType "OfxPropType" 666 667 /** @brief Unique name of an object. 668 669 - Type - ASCII C string X 1 670 - Property Set - on many objects (descriptors and instances), see \ref PropertiesByObject (read only) 671 672 This property is used to label objects uniquely amoung objects of that type. It is typically set when a plugin creates a new object with a function that takes a name. 673 */ 674 #define kOfxPropName "OfxPropName" 675 676 /** @brief Identifies a specific version of a host or plugin. 677 678 - Type - int X N 679 - Property Set - host descriptor (read only), plugin descriptor (read/write) 680 - Default - "0" 681 - Valid Values - positive integers 682 683 This is a multi dimensional integer property that represents the version of a host (host descriptor), or plugin (plugin descriptor). These represent a version number of the form '1.2.3.4', with each dimension adding another 'dot' on the right. 684 685 A version is considered to be more recent than another if its ordered set of values is lexicographically greater than another, reading left to right. (ie: 1.2.4 is smaller than 1.2.6). Also, if the number of dimensions is different, then the values of the missing dimensions are considered to be zero (so 1.2.4 is greater than 1.2). 686 */ 687 #define kOfxPropVersion "OfxPropVersion" 688 689 /** @brief Unique user readable version string of a plugin or host. 690 691 - Type - string X 1 692 - Property Set - host descriptor (read only), plugin descriptor (read/write) 693 - Default - none, the host needs to set this 694 - Valid Values - ASCII string 695 696 This is purely for user feedback, a plugin or host should use ::kOfxPropVersion if they need 697 to check for specific versions. 698 */ 699 #define kOfxPropVersionLabel "OfxPropVersionLabel" 700 701 /** @brief Description of the plug-in to a user. 702 703 - Type - string X 1 704 - Property Set - plugin descriptor (read/write) and instance (read only) 705 - Default - "" 706 - Valid Values - UTF8 string 707 708 This is a string giving a potentially verbose description of the effect. 709 */ 710 #define kOfxPropPluginDescription "OfxPropPluginDescription" 711 712 /** @brief User visible name of an object. 713 714 - Type - UTF8 C string X 1 715 - Property Set - on many objects (descriptors and instances), see \ref PropertiesByObject. Typically readable and writable in most cases. 716 - Default - the ::kOfxPropName the object was created with. 717 718 The label is what a user sees on any interface in place of the object's name. 719 720 Note that resetting this will also reset ::kOfxPropShortLabel and ::kOfxPropLongLabel. 721 */ 722 #define kOfxPropLabel "OfxPropLabel" 723 724 /** @brief If set this tells the host to use an icon instead of a label for some object in the interface. 725 726 - Type - string X 2 727 - Property Set - various descriptors in the API 728 - Default - "" 729 - Valid Values - ASCII string 730 731 The value is a path is defined relative to the Resource folder that points to an SVG or PNG file containing the icon. 732 733 The first dimension, if set, will the name of and SVG file, the second a PNG file. 734 */ 735 #define kOfxPropIcon "OfxPropIcon" 736 737 /** @brief Short user visible name of an object. 738 739 - Type - UTF8 C string X 1 740 - Property Set - on many objects (descriptors and instances), see \ref PropertiesByObject. Typically readable and writable in most cases. 741 - Default - initially ::kOfxPropName, but will be reset if ::kOfxPropLabel is changed. 742 743 This is a shorter version of the label, typically 13 character glyphs or less. Hosts should use this if they have limitted display space for their object labels. 744 */ 745 #define kOfxPropShortLabel "OfxPropShortLabel" 746 747 /** @brief Long user visible name of an object. 748 749 - Type - UTF8 C string X 1 750 - Property Set - on many objects (descriptors and instances), see \ref PropertiesByObject. Typically readable and writable in most cases. 751 - Default - initially ::kOfxPropName, but will be reset if ::kOfxPropLabel is changed. 752 753 This is a longer version of the label, typically 32 character glyphs or so. Hosts should use this if they have mucg display space for their object labels. 754 */ 755 #define kOfxPropLongLabel "OfxPropLongLabel" 756 757 /** @brief Indicates why a plug-in changed. 758 759 - Type - ASCII C string X 1 760 - Property Set - inArgs parameter on the ::kOfxActionInstanceChanged action. 761 - Valid Values - this can be... 762 - ::kOfxChangeUserEdited - the user directly edited the instance somehow and caused a change to something, this includes undo/redos and resets 763 - ::kOfxChangePluginEdited - the plug-in itself has changed the value of the object in some action 764 - ::kOfxChangeTime - the time has changed and this has affected the value of the object because it varies over time 765 766 Argument property for the ::kOfxActionInstanceChanged action. 767 */ 768 #define kOfxPropChangeReason "OfxPropChangeReason" 769 770 /** @brief A pointer to an effect instance. 771 772 - Type - pointer X 1 773 - Property Set - on an interact instance (read only) 774 775 This property is used to link an object to the effect. For example if the plug-in supplies an openGL overlay for an image effect, 776 the interact instance will have one of these so that the plug-in can connect back to the effect the GUI links to. 777 */ 778 #define kOfxPropEffectInstance "OfxPropEffectInstance" 779 780 /** @brief A pointer to an operating system specific application handle. 781 782 - Type - pointer X 1 783 - Property Set - host descriptor. 784 785 Some plug-in vendor want raw OS specific handles back from the host so they can do interesting things with host OS APIs. Typically this is to control windowing properly on Microsoft Windows. This property returns the appropriate 'root' window handle on the current operating system. So on Windows this would be the hWnd of the application main window. 786 */ 787 #define kOfxPropHostOSHandle "OfxPropHostOSHandle" 788 789 /*@}*/ 790 791 /*@}*/ 792 793 /** @brief String used as a value to ::kOfxPropChangeReason to indicate a user has changed something */ 794 #define kOfxChangeUserEdited "OfxChangeUserEdited" 795 796 /** @brief String used as a value to ::kOfxPropChangeReason to indicate the plug-in itself has changed something */ 797 #define kOfxChangePluginEdited "OfxChangePluginEdited" 798 799 /** @brief String used as a value to ::kOfxPropChangeReason to a time varying object has changed due to a time change */ 800 #define kOfxChangeTime "OfxChangeTime" 801 802 /** @brief How time is specified within the OFX API */ 803 typedef double OfxTime; 804 805 /** @brief Defines one dimensional integer bounds */ 806 typedef struct OfxRangeI { 807 int min, max; 808 } OfxRangeI; 809 810 /** @brief Defines one dimensional double bounds */ 811 typedef struct OfxRangeD { 812 double min, max; 813 } OfxRangeD; 814 815 /** @brief Defines two dimensional integer point */ 816 typedef struct OfxPointI { 817 int x, y; 818 } OfxPointI; 819 820 /** @brief Defines two dimensional double point */ 821 typedef struct OfxPointD { 822 double x, y; 823 } OfxPointD; 824 825 /** @brief Used to flag infinite rects. Set minimums to this to indicate infinite 826 827 This is effectively INT_MAX. 828 */ 829 #define kOfxFlagInfiniteMax INT_MAX 830 831 /** @brief Used to flag infinite rects. Set minimums to this to indicate infinite. 832 833 This is effectively INT_MIN 834 */ 835 #define kOfxFlagInfiniteMin INT_MIN 836 837 /** @brief Defines two dimensional integer region 838 839 Regions are x1 <= x < x2 840 841 Infinite regions are flagged by setting 842 - x1 = \ref kOfxFlagInfiniteMin 843 - y1 = \ref kOfxFlagInfiniteMin 844 - x2 = \ref kOfxFlagInfiniteMax 845 - y2 = \ref kOfxFlagInfiniteMax 846 847 */ 848 typedef struct OfxRectI { 849 int x1, y1, x2, y2; 850 } OfxRectI; 851 852 /** @brief Defines two dimensional double region 853 854 Regions are x1 <= x < x2 855 856 Infinite regions are flagged by setting 857 - x1 = \ref kOfxFlagInfiniteMin 858 - y1 = \ref kOfxFlagInfiniteMin 859 - x2 = \ref kOfxFlagInfiniteMax 860 - y2 = \ref kOfxFlagInfiniteMax 861 862 */ 863 typedef struct OfxRectD { 864 double x1, y1, x2, y2; 865 } OfxRectD; 866 867 /** @brief String used to label unset bitdepths */ 868 #define kOfxBitDepthNone "OfxBitDepthNone" 869 870 /** @brief String used to label unsigned 8 bit integer samples */ 871 #define kOfxBitDepthByte "OfxBitDepthByte" 872 873 /** @brief String used to label unsigned 16 bit integer samples */ 874 #define kOfxBitDepthShort "OfxBitDepthShort" 875 876 /** @brief String used to label half-float (16 bit floating point) samples 877 * \version Added in Version 1.4. Was in ofxOpenGLRender.h before. 878 */ 879 #define kOfxBitDepthHalf "OfxBitDepthHalf" 880 881 /** @brief String used to label signed 32 bit floating point samples */ 882 #define kOfxBitDepthFloat "OfxBitDepthFloat" 883 884 /** 885 \defgroup StatusCodes Status Codes 886 887 These strings are used to identify error states within ofx, they are returned 888 by various host suite functions, as well as plug-in functions. The valid return codes 889 for each function are documented with that function. 890 */ 891 /*@{*/ 892 893 /** 894 \defgroup StatusCodesGeneral General Status Codes 895 896 General status codes start at 1 and continue until 999 897 898 */ 899 /*@{*/ 900 901 /** @brief Status code indicating all was fine */ 902 #define kOfxStatOK 0 903 904 /** @brief Status error code for a failed operation */ 905 #define kOfxStatFailed ((int)1) 906 907 /** @brief Status error code for a fatal error 908 909 Only returned in the case where the plug-in or host cannot continue to function and needs to be restarted. 910 */ 911 #define kOfxStatErrFatal ((int)2) 912 913 /** @brief Status error code for an operation on or request for an unknown object */ 914 #define kOfxStatErrUnknown ((int)3) 915 916 /** @brief Status error code returned by plug-ins when they are missing host functionality, either an API or some optional functionality (eg: custom params). 917 918 Plug-Ins returning this should post an appropriate error message stating what they are missing. 919 */ 920 #define kOfxStatErrMissingHostFeature ((int) 4) 921 922 /** @brief Status error code for an unsupported feature/operation */ 923 #define kOfxStatErrUnsupported ((int) 5) 924 925 /** @brief Status error code for an operation attempting to create something that exists */ 926 #define kOfxStatErrExists ((int) 6) 927 928 /** @brief Status error code for an incorrect format */ 929 #define kOfxStatErrFormat ((int) 7) 930 931 /** @brief Status error code indicating that something failed due to memory shortage */ 932 #define kOfxStatErrMemory ((int) 8) 933 934 /** @brief Status error code for an operation on a bad handle */ 935 #define kOfxStatErrBadHandle ((int) 9) 936 937 /** @brief Status error code indicating that a given index was invalid or unavailable */ 938 #define kOfxStatErrBadIndex ((int)10) 939 940 /** @brief Status error code indicating that something failed due an illegal value */ 941 #define kOfxStatErrValue ((int) 11) 942 943 /** @brief OfxStatus returned indicating a 'yes' */ 944 #define kOfxStatReplyYes ((int) 12) 945 946 /** @brief OfxStatus returned indicating a 'no' */ 947 #define kOfxStatReplyNo ((int) 13) 948 949 /** @brief OfxStatus returned indicating that a default action should be performed */ 950 #define kOfxStatReplyDefault ((int) 14) 951 952 /*@}*/ 953 954 /*@}*/ 955 956 #ifdef __cplusplus 957 } 958 #endif 959 960 /** @mainpage OFX : Open Plug-Ins For Special Effects 961 962 This page represents the automatically extracted HTML documentation of the source headers for the OFX Image Effect API. The documentation was extracted by doxygen (http://www.doxygen.org). It breaks documentation into sets of pages, use the links at the top of this page (marked 'Modules', 'Compound List' and especially 'File List' etcc) to browse through the OFX doc. 963 964 A more complete reference manual is http://openfx.sourceforge.net . 965 966 */ 967 968 #endif 969