diff --git a/CMakeLists.txt b/CMakeLists.txt index 9fc1894fd..c5fa2fe78 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -41,6 +41,7 @@ option(MOD_SDL2 "Enable SDL2 module" ON) option(MOD_SOX "Enable SoX module" ON) option(MOD_SPATIALAUDIO "Enable SpatialAudio module" ON) option(MOD_VIDSTAB "Enable vid.stab module (GPL)" ON) +option(MOD_OPENFX "Enable OpenFX module (GPL)" ON) option(MOD_VORBIS "Enable Vorbis module" ON) option(MOD_XINE "Enable XINE module (GPL)" ON) option(MOD_XML "Enable XML module" ON) @@ -171,6 +172,7 @@ if(NOT GPL) set(MOD_RESAMPLE OFF) set(MOD_RUBBERBAND OFF) set(MOD_VIDSTAB OFF) + set(MOD_OPENFX OFF) set(MOD_XINE OFF) endif() @@ -633,6 +635,7 @@ add_feature_info("Module: SDL2" MOD_SDL2 "") add_feature_info("Module: SoX" MOD_SOX "") add_feature_info("Module: SpatialAudio" MOD_SPATIALAUDIO "") add_feature_info("Module: vid.stab" MOD_VIDSTAB "") +add_feature_info("Module: OpenFX" MOD_OPENFX "") add_feature_info("Module: Vorbis" MOD_VORBIS "") add_feature_info("Module: XINE" MOD_XINE "") add_feature_info("Module: XML" MOD_XML "") diff --git a/src/modules/CMakeLists.txt b/src/modules/CMakeLists.txt index 9b04d9006..e06a7039e 100644 --- a/src/modules/CMakeLists.txt +++ b/src/modules/CMakeLists.txt @@ -92,6 +92,10 @@ if(MOD_VIDSTAB) add_subdirectory(vid.stab) endif() +if(MOD_OPENFX) + add_subdirectory(openfx) +endif() + if(MOD_VORBIS) add_subdirectory(vorbis) endif() diff --git a/src/modules/openfx/CMakeLists.txt b/src/modules/openfx/CMakeLists.txt new file mode 100644 index 000000000..4261b354d --- /dev/null +++ b/src/modules/openfx/CMakeLists.txt @@ -0,0 +1,20 @@ +add_library(mltopenfx MODULE + factory.c + mlt_openfx.c mlt_openfx.h + filter_openfx.c +) + +file(GLOB YML "*.yml") +add_custom_target(Other_openfx_Files SOURCES + ${YML} +) + +target_compile_options(mltopenfx PRIVATE ${MLT_COMPILE_OPTIONS}) + +target_link_libraries(mltopenfx PRIVATE mlt m) + +set_target_properties(mltopenfx PROPERTIES LIBRARY_OUTPUT_DIRECTORY "${MLT_MODULE_OUTPUT_DIRECTORY}") + +install(TARGETS mltopenfx LIBRARY DESTINATION ${MLT_INSTALL_MODULE_DIR}) + +install(FILES filter_openfx.yml DESTINATION ${MLT_INSTALL_DATA_DIR}/openfx) diff --git a/src/modules/openfx/factory.c b/src/modules/openfx/factory.c new file mode 100644 index 000000000..0d845b83d --- /dev/null +++ b/src/modules/openfx/factory.c @@ -0,0 +1,285 @@ +/* + * factory.c -- the factory method interfaces + * Copyright (C) 2024 Meltytech, LLC + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software Foundation, + * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + */ + +#include "mlt_openfx.h" + +extern OfxHost MltOfxHost; + +static OfxStatus (*OfxSetHostFn)(const OfxHost *host); +static OfxPlugin *(*OfxGetPluginFn) (int nth); +static int (*OfxGetNumberOfPluginsFn) (void); +static int NumberOfPlugins; +mlt_properties mltofx_context; +mlt_properties mltofx_dl; + +#if defined (__linux__) || defined (__FreeBSD__) + +#define OFX_DIRLIST_SEP_CHARS ":;" +#define OFX_DIRSEP "/" +#include + +static const char *getArchStr() +{ + if(sizeof(void *) == 4) { +#if defined(__linux__) + return "Linux-x86"; +#else + return "FreeBSD-x86"; +#endif + } + else { +#if defined(__linux__) + return "Linux-x86-64"; +#else + return "FreeBSD-x86-64"; +#endif + } +} + +#define OFX_ARCHSTR getArchStr() + +#elif defined (__APPLE__) + +#define OFX_DIRLIST_SEP_CHARS ";:" +#if defined(__x86_64) || defined(__x86_64__) +#define OFX_ARCHSTR "MacOS-x86-64" +#else +#define OFX_ARCHSTR "MacOS" +#endif +#define OFX_DIRSEP "/" +#include + +#elif defined (WINDOWS) +#define OFX_DIRLIST_SEP_CHARS ";" +#ifdef _WIN64 +#define OFX_ARCHSTR "win64" +#else +#define OFX_ARCHSTR "win32" +#endif +#define OFX_DIRSEP "\\" + +#include "shlobj.h" +#include "tchar.h" +#endif + +extern mlt_filter filter_openfx_init(mlt_profile profile, + mlt_service_type type, + const char *id, + char *arg); + +static void plugin_mgr_destroy(mlt_properties p) +{ + int cN = mlt_properties_count(mltofx_context); + + int j; + for (j = 0; j < cN; ++j) + { + char *id = mlt_properties_get_name (mltofx_context, j); + mlt_properties pb = (mlt_properties) mlt_properties_get_data(mltofx_context, id, NULL); + + char *dli = mlt_properties_get (pb, "dli"); + dli[0] = 'g'; + int index = mlt_properties_get_int (pb, "index"); + + OfxPlugin *(*GetPluginFn) (int nth) = mlt_properties_get_data(mltofx_dl, dli, NULL); + + if (GetPluginFn != NULL) + { + OfxPlugin *pt = GetPluginFn (index); + if (pt == NULL) continue; + pt->mainEntry (kOfxActionUnload, NULL, NULL, NULL); + } + } + + int N = mlt_properties_get_int (p, "N"); + + int i; + for (i = 0; i < N; ++i) + { + char tstr[12] = {'\0',}; + sprintf (tstr, "%d", i); + void *current_dlhandle = mlt_properties_get_data(mltofx_dl, tstr, NULL); + dlclose (current_dlhandle); + } +} + +static mlt_properties metadata(mlt_service_type type, const char *id, void *data) +{ + char file[PATH_MAX]; + snprintf(file, PATH_MAX, "%s/openfx/%s", mlt_environment("MLT_DATA"), (char *) data); + mlt_properties result = mlt_properties_parse_yaml(file); + + mlt_properties pb = (mlt_properties) mlt_properties_get_data(mltofx_context, id, NULL); + + char *dli = mlt_properties_get (pb, "dli"); + int index = mlt_properties_get_int (pb, "index"); + + OfxPlugin *(*GetPluginFn) (int nth) = mlt_properties_get_data(mltofx_dl, dli, NULL); + OfxPlugin *pt = GetPluginFn (index); + + dli[0] = 's'; + OfxStatus (*OfxSetHost)(const OfxHost *host) = mlt_properties_get_data(mltofx_dl, dli, NULL); + if (OfxSetHost != NULL) OfxSetHost (&MltOfxHost); + + mlt_properties_set (result, "identifier", id); + mlt_properties_set (result, "title", id); + + /* parameters */ + mlt_properties params = mlt_properties_new(); + mlt_properties_set_data(result, + "parameters", + params, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + + mltofx_fetch_params (pt, params); + return result; +} + +MLT_REPOSITORY +{ + MltOfxHost.host = (OfxPropertySetHandle) mlt_properties_new (); + mltofx_init_host_properties (MltOfxHost.host); + + char *dir, *openfx_path = getenv("OFX_PLUGIN_PATH"); + size_t archstr_len = strlen (OFX_ARCHSTR); + + mltofx_context = mlt_properties_new (); + mltofx_dl = mlt_properties_new (); + + if (openfx_path) + { + int dli = 0; + + for (dir = strtok(openfx_path, MLT_DIRLIST_DELIMITER); dir; + dir = strtok(NULL, MLT_DIRLIST_DELIMITER)) + { + size_t dir_len = strlen (dir); + + DIR *d = opendir(dir); + if (!d) continue; + + struct dirent *de = readdir(d); + while (de) + { + char *name = de->d_name; + + char *bni = NULL; + if ((bni = strstr (name, ".ofx.bundle")) != NULL) + { + char *barename = strndup (name, (int) (bni - name) + 4); + size_t name_len = (size_t) (bni - name) + 4 + 7; + /* 12b sizeof `Contents` word, 1 sizeof null byte */ + char *binpath = malloc(dir_len + name_len + 12 + (name_len-7) + archstr_len + 1); + sprintf(binpath, "%s/%s/Contents/%s/%s", dir, name, OFX_ARCHSTR, barename); + + void *dlhandle = dlopen (binpath, RTLD_LOCAL | RTLD_LAZY); + + OfxSetHostFn = dlsym (dlhandle, "OfxSetHost"); + + OfxGetPluginFn = dlsym (dlhandle, "OfxGetPlugin"); + OfxGetNumberOfPluginsFn = dlsym (dlhandle, "OfxGetNumberOfPlugins"); + NumberOfPlugins = OfxGetNumberOfPluginsFn (); + + char dl_n[16] = {'\0',}; + sprintf (dl_n, "%d", dli); + + mlt_properties_set_data(mltofx_dl, + dl_n, + dlhandle, + 0, + NULL, + NULL); + dl_n[0] = '\0'; + sprintf (dl_n, "gn%d", dli); + mlt_properties_set_data(mltofx_dl, + dl_n, + OfxGetNumberOfPluginsFn, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + dl_n[0] = '\0'; + sprintf (dl_n, "s%d", dli); + mlt_properties_set_data(mltofx_dl, + dl_n, + OfxSetHostFn, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + + dl_n[0] = '\0'; + sprintf (dl_n, "g%d", dli); + mlt_properties_set_data(mltofx_dl, + dl_n, + OfxGetPluginFn, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + + dli++; + + if (OfxGetPluginFn == NULL) goto parse_error; + + int i; + for (i = 0; i < NumberOfPlugins; ++i) + { + OfxPlugin *plugin_ptr = OfxGetPluginFn (i); + + char *s = NULL; + size_t pluginIdentifier_len = strlen (plugin_ptr->pluginIdentifier); + s = malloc (pluginIdentifier_len + 8); + sprintf (s, "openfx.%s", plugin_ptr->pluginIdentifier); + + mlt_properties p; + p = mlt_properties_new (); + mlt_properties_set_data(mltofx_context, + s, + p, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + + mlt_properties_set(p, "dli", dl_n); + mlt_properties_set_int(p, "index", i); + + /* WIP: this is only creating them as filter I should find a way to see howto detect producers + if they exists in OpenFX plugins + */ + MLT_REGISTER(mlt_service_filter_type, s, filter_openfx_init); + MLT_REGISTER_METADATA(mlt_service_filter_type, s, metadata, "filter_openfx.yml"); + + } + + + parse_error: + + free (binpath); + free (barename); + } + + de = readdir(d); + } + + } + + mlt_properties_set_int(mltofx_dl, "N", dli); + mlt_factory_register_for_clean_up(mltofx_dl, (mlt_destructor) plugin_mgr_destroy); + } +} diff --git a/src/modules/openfx/filter_openfx.c b/src/modules/openfx/filter_openfx.c new file mode 100644 index 000000000..1956c34ae --- /dev/null +++ b/src/modules/openfx/filter_openfx.c @@ -0,0 +1,230 @@ +/* + * filter_openfx.c -- filter Video through OpenFX plugins + * Copyright (C) 2024 Meltytech, LLC + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software Foundation, + * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + */ + +#include "ofxImageEffect.h" +#include "mlt_openfx.h" +#include +#include + +extern OfxHost MltOfxHost; +extern mlt_properties mltofx_context; +extern mlt_properties mltofx_dl; + +static int filter_get_image(mlt_frame frame, + uint8_t **image, + mlt_image_format *format, + int *width, + int *height, + int writable) +{ + mlt_filter filter = (mlt_filter) mlt_frame_pop_service(frame); + + mlt_properties properties = MLT_FILTER_PROPERTIES(filter); + OfxPlugin *plugin = mlt_properties_get_data (properties, "ofx_plugin", NULL); + mlt_properties image_effect = mlt_properties_get_data (properties, "ofx_image_effect", NULL); + mlt_properties params = mlt_properties_get_data (image_effect, "mltofx_params", NULL); + mlt_properties image_effect_params = mlt_properties_get_data (image_effect, "params", NULL); + + *format = mlt_image_rgba; + int error = mlt_frame_get_image(frame, image, format, width, height, 1); + + if (error == 0) + { + mlt_position position = mlt_filter_get_position(filter, frame); + mlt_position length = mlt_filter_get_length2(filter, frame); + int params_count = mlt_properties_count(params); + + int i; + for (i = 0; i < params_count; ++i) + { + char *iprop_name = mlt_properties_get_name(params, i); + + char *mlt_value = mlt_properties_get (properties, iprop_name); + + if (mlt_value != NULL) + { + mlt_properties param = mlt_properties_get_data_at(params, i, NULL); + + char *type = mlt_properties_get (param, "type"); + + if (type != NULL) + { + if (strcmp (type, "double") == 0) + { + double value = mlt_properties_anim_get_double (properties, iprop_name, position, length); + mltofx_param_set_value (image_effect_params, iprop_name, mltofx_prop_double, value); + } + else if (strcmp (type, "integer") == 0) + { + int value = mlt_properties_anim_get_int (properties, iprop_name, position, length); + mltofx_param_set_value (image_effect_params, iprop_name, mltofx_prop_int, value); + } + else if (strcmp (type, "string") == 0) + { + char *value = mlt_properties_anim_get (properties, iprop_name, position, length); + mltofx_param_set_value (image_effect_params, iprop_name, mltofx_prop_string, value); + } + else if (strcmp (type, "boolean") == 0) + { + int value = mlt_properties_anim_get_int (properties, iprop_name, position, length); + mltofx_param_set_value (image_effect_params, iprop_name, mltofx_prop_int, value); + } + } + } + } + + mltofx_begin_sequence_render (plugin, image_effect); + + mltofx_get_regions_of_interest (plugin, image_effect, (double) *width, (double) *height); + mltofx_get_clip_preferences (plugin, image_effect); + + uint8_t *src_copy = malloc(*width * *height * 4); + if (src_copy == NULL) + goto out; + memcpy (src_copy, *image, *width * *height * 4); + mltofx_set_source_clip_data (plugin, image_effect, src_copy, *width, *height); + mltofx_set_output_clip_data (plugin, image_effect, *image, *width, *height); + + mltofx_action_render (plugin, image_effect, *width, *height); + + free (src_copy); + + mltofx_end_sequence_render (plugin, image_effect); + } + out: + return error; +} + + +static mlt_frame filter_process(mlt_filter filter, mlt_frame frame) +{ + mlt_frame_push_service(frame, filter); + mlt_frame_push_get_image(frame, filter_get_image); + return frame; +} + +static void filter_close(mlt_filter filter) +{ + mlt_properties properties = MLT_FILTER_PROPERTIES(filter); + + OfxPlugin *plugin = mlt_properties_get_data (properties, "ofx_plugin", NULL); + mlt_properties image_effect = mlt_properties_get_data (properties, "ofx_image_effect", NULL); + + mltofx_destroy_instance (plugin, image_effect); +} + +mlt_filter filter_openfx_init(mlt_profile profile, mlt_service_type type, const char *id, char *arg) +{ + mlt_filter this = mlt_filter_new(); + if (this != NULL) { + mlt_properties properties = MLT_FILTER_PROPERTIES(this); + this->process = filter_process; + this->close = filter_close; + + /* + WIP + resource, _pluginid are properties set to the filter properties + also the parameters are set in the filter properties so I need + to make sure that no plugin will create property with the same + name as 'resource', '_pluginid' and other default filter properties + thats why modules like jackrack use to set parameters properties based + on numbered labels such as 0,1,2,3,4,...etc because there is no default + property like that. + */ + + mlt_properties_set(properties, "resource", arg); + if (!strncmp(id, "openfx.", 7)) + { + mlt_properties_set(properties, "_pluginid", id + 7); + + mlt_properties pb = (mlt_properties) mlt_properties_get_data(mltofx_context, id, NULL); + + char *dli = mlt_properties_get (pb, "dli"); + int index = mlt_properties_get_int (pb, "index"); + + dli[0] = 'g'; + + OfxPlugin *(*GetPluginFn) (int nth) = mlt_properties_get_data(mltofx_dl, dli, NULL); + + if (GetPluginFn != NULL) + { + OfxPlugin *pt = GetPluginFn (index); + if (pt == NULL) + return NULL; + + mlt_properties params = mlt_properties_new(); + mlt_properties image_effect = mltofx_fetch_params (pt, params); + + mltofx_create_instance (pt, image_effect); + + mlt_properties begin_sequence_props = mlt_properties_new (); + mlt_properties end_sequence_props = mlt_properties_new (); + mlt_properties_set_data (image_effect, + "begin_sequence_props", + begin_sequence_props, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + mlt_properties_set_data (image_effect, + "end_sequence_props", + end_sequence_props, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + + + mlt_properties get_roi_in_args = mlt_properties_new (); + mlt_properties get_roi_out_args = mlt_properties_new (); + mlt_properties_set_data (image_effect, + "get_roi_in_args", + get_roi_in_args, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + mlt_properties_set_data (image_effect, + "get_roi_out_args", + get_roi_out_args, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + + mlt_properties get_clippref_args = mlt_properties_new (); + mlt_properties_set_data (image_effect, + "get_clippref_args", + get_clippref_args, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + + mlt_properties render_in_args = mlt_properties_new (); + mlt_properties_set_data (image_effect, + "render_in_args", + render_in_args, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + + mlt_properties_set_data (properties, "ofx_plugin", pt, 0, NULL, NULL); + mlt_properties_set_data (properties, "ofx_image_effect", image_effect, 0, (mlt_destructor) mlt_properties_close, NULL); + } + + } + } + return this; +} diff --git a/src/modules/openfx/filter_openfx.yml b/src/modules/openfx/filter_openfx.yml new file mode 100644 index 000000000..767135deb --- /dev/null +++ b/src/modules/openfx/filter_openfx.yml @@ -0,0 +1,12 @@ +schema_version: 7.0 +type: filter +identifier: openfx +title: OPENFX +version: 1 +license: GPLv2 +language: en +url: https://openeffects.org/ +creator: mr.fantastic +tags: + - Video +description: Process videos using OpenFX plugins. diff --git a/src/modules/openfx/mlt_openfx.c b/src/modules/openfx/mlt_openfx.c new file mode 100644 index 000000000..134852bef --- /dev/null +++ b/src/modules/openfx/mlt_openfx.c @@ -0,0 +1,2020 @@ +/* + * MLT OpenFX + * + * Copyright (C) 2024 Meltytech, LLC + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + */ + +#include "mlt_openfx.h" +#include "ofxImageEffect.h" +#include "ofxDrawSuite.h" +#include "ofxProgress.h" +#include "ofxTimeLine.h" +#include "ofxParametricParam.h" +#include + +static OfxStatus +getPropertySet (OfxImageEffectHandle imageEffect, + OfxPropertySetHandle *propHandle) +{ + mlt_properties image_effect = (mlt_properties) imageEffect; + *propHandle = mlt_properties_get_data (image_effect, "props", NULL); + + return kOfxStatOK; +} + +static OfxStatus +getParamSet (OfxImageEffectHandle imageEffect, + OfxParamSetHandle *paramSet) +{ + if (imageEffect == NULL) return kOfxStatErrBadHandle; + + mlt_properties image_effect = (mlt_properties) imageEffect; + *paramSet = mlt_properties_get_data (image_effect, "params", NULL); + + return kOfxStatOK; +} + +static OfxStatus +clipDefine (OfxImageEffectHandle imageEffect, + const char *name, + OfxPropertySetHandle *propertySet) +{ + mlt_log_debug(NULL, "clipDefine: `%s` ## %p\n", name, propertySet); + + mlt_properties image_effect = (mlt_properties) imageEffect; + mlt_properties set = mlt_properties_get_data (image_effect, "clips", NULL); + + mlt_properties clip = mlt_properties_new (); + mlt_properties clip_props = mlt_properties_new (); + if (clip == NULL) + return kOfxStatErrMemory; + + mlt_properties_set_data(set, + name, + clip, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + mlt_properties_set_data(clip, + "props", + clip_props, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + + *propertySet = (OfxPropertySetHandle) clip_props; + + return kOfxStatOK; +} + +static OfxStatus +clipGetHandle (OfxImageEffectHandle imageEffect, + const char *name, + OfxImageClipHandle *clip, + OfxPropertySetHandle *propertySet) +{ + mlt_properties image_effect = (mlt_properties) imageEffect; + mlt_properties set = mlt_properties_get_data (image_effect, "clips", NULL); + + mlt_properties clip_temp = mlt_properties_get_data (set, name, NULL); + *clip = (OfxImageClipHandle) clip_temp; + + if (propertySet != NULL) + *propertySet = (OfxPropertySetHandle) mlt_properties_get_data (clip_temp, "props", NULL); + + return kOfxStatOK; +} + +static OfxStatus +clipGetPropertySet (OfxImageClipHandle clip, + OfxPropertySetHandle *propHandle) +{ + mlt_properties c = (mlt_properties) clip; + *propHandle = (OfxPropertySetHandle) mlt_properties_get_data (c, "props", NULL); + + return kOfxStatOK; +} + +static OfxStatus +clipGetImage (OfxImageClipHandle clip, + OfxTime time, + const OfxRectD *region, + OfxPropertySetHandle *imageHandle) +{ + mlt_properties clip_temp = (mlt_properties) clip; + *imageHandle = (OfxPropertySetHandle) mlt_properties_get_data (clip_temp, "props", NULL); + + /* WIP give him the default region if *region is not NULL */ + + return kOfxStatOK; +} + +static OfxStatus +clipReleaseImage (OfxPropertySetHandle imageHandle) +{ + return kOfxStatOK; +} + +static OfxStatus +clipGetRegionOfDefinition (OfxImageClipHandle clip, + OfxTime time, + OfxRectD *bounds) +{ + return kOfxStatOK; +} + +static int +abortOfxFn (OfxImageEffectHandle imageEffect) +{ + return 0; +} + +static OfxStatus +imageMemoryAlloc (OfxImageEffectHandle instanceHandle, + size_t nBytes, + OfxImageMemoryHandle *memoryHandle) +{ + if (instanceHandle == NULL) + { + *memoryHandle = NULL; + return kOfxStatErrBadHandle; + } + + void *temp = calloc (1, nBytes); + + if (temp == NULL) + return kOfxStatErrMemory; + + *memoryHandle = temp; + + return kOfxStatOK; +} + +static OfxStatus +imageMemoryFree (OfxImageMemoryHandle memoryHandle) +{ + free (memoryHandle); + + return kOfxStatOK; +} + +static OfxStatus +imageMemoryLock (OfxImageMemoryHandle memoryHandle, + void **returnedPtr) +{ + return kOfxStatOK; +} + +static OfxStatus +imageMemoryUnlock (OfxImageMemoryHandle memoryHandle) +{ + return kOfxStatOK; +} + +static OfxImageEffectSuiteV1 MltOfxImageEffectSuiteV1 = + { + getPropertySet, + getParamSet, + clipDefine, + clipGetHandle, + clipGetPropertySet, + clipGetImage, + clipReleaseImage, + clipGetRegionOfDefinition, + abortOfxFn, + imageMemoryAlloc, + imageMemoryFree, + imageMemoryLock, + imageMemoryUnlock + }; + +#define MLTOFX_DEF_SETTER(fn, fa, vt, ofxproptype) static OfxStatus propSet ## fn (OfxPropertySetHandle properties, \ + const char *property, \ + int index, \ + fa value) \ + { \ + if (properties == NULL) return kOfxStatErrBadHandle; \ + if (index < 0) return kOfxStatErrBadIndex; \ + mlt_properties props = (mlt_properties) properties; \ + int length = 0; \ + mlt_properties p = mlt_properties_get_data (props, property, &length); \ + if (p == NULL) \ + { \ + mlt_properties pt = mlt_properties_new (); \ + mlt_properties_set_data (props, property, pt, 0, (mlt_destructor) mlt_properties_close, NULL); \ + mlt_properties_set_int (pt, "t", ofxproptype); \ + p = pt; \ + } \ + vt *v = mlt_properties_get_data (p, "v", &length); \ + if (length == 0 || length <= index) \ + { \ + vt *values = realloc (v, sizeof(vt) * (index+1)); \ + if (values == NULL) return kOfxStatErrMemory; \ + values[index] = value; \ + mlt_properties_set_data (p, "v", values, index+1, NULL, NULL); \ + } \ + else \ + { \ + v[index] = value; \ + } \ + return kOfxStatOK; \ + } + +MLTOFX_DEF_SETTER(Pointer, void *, void *, mltofx_prop_pointer); +//MLTOFX_DEF_SETTER(String, const char *, char *, mltofx_prop_string); +MLTOFX_DEF_SETTER(Double, double, double, mltofx_prop_double); +MLTOFX_DEF_SETTER(Int, int, int, mltofx_prop_int); + + +static OfxStatus propSetString (OfxPropertySetHandle properties, + const char *property, + int index, + const char *value) +{ + if (properties == NULL) return kOfxStatErrBadHandle; + if (index < 0) return kOfxStatErrBadIndex; + mlt_properties props = (mlt_properties) properties; + int length = 0; + mlt_properties p = mlt_properties_get_data (props, property, &length); + if (p == NULL) + { + mlt_properties pt = mlt_properties_new (); + mlt_properties_set_data (props, property, pt, 0, (mlt_destructor) mlt_properties_close, NULL); + mlt_properties_set_int (pt, "t", mltofx_prop_string); + p = pt; + } + char **v = mlt_properties_get_data (p, "v", &length); + if (length == 0 || length <= index) + { + char **values = realloc (v, sizeof(char *) * (index+1)); + if (values == NULL) return kOfxStatErrMemory; + values[index] = strdup(value); /* WIP take care of freeing mem */ + mlt_properties_set_data (p, "v", values, index+1, NULL, NULL); + } + else + { + v[index] = value; + } + return kOfxStatOK; +} + +#define MLTOFX_DEF_GETTER(fn, fa) static OfxStatus propGet ## fn (OfxPropertySetHandle properties, \ + const char *property, \ + int index, \ + fa *value) \ + { \ + if (properties == NULL) return kOfxStatErrBadHandle; \ + mlt_properties props = (mlt_properties) properties; \ + int length = 0; \ + mlt_properties p = mlt_properties_get_data (props, property, &length); \ + if (p != NULL) \ + { \ + fa *v = mlt_properties_get_data (p, "v", &length); \ + if (index < 0 || index >= length) return kOfxStatErrBadIndex; \ + *value = v[index]; \ + return kOfxStatOK; \ + } \ + return kOfxStatErrUnknown; \ + } + +MLTOFX_DEF_GETTER(Pointer, void *); +MLTOFX_DEF_GETTER(String, char *); +MLTOFX_DEF_GETTER(Double, double); +MLTOFX_DEF_GETTER(Int, int); + +#define MLTOFX_DEF_SETTER_N(fn, fa, vt, ofxproptype) static OfxStatus propSet ## fn ## N (OfxPropertySetHandle properties, \ + const char *property, \ + int count, \ + fa *value) \ + { \ + if (properties == NULL) return kOfxStatErrBadHandle; \ + if (count < 0) return kOfxStatErrBadIndex; \ + if (value == NULL) return kOfxStatErrValue; \ + mlt_properties props = (mlt_properties) properties; \ + int length = 0; \ + mlt_properties p = mlt_properties_get_data (props, property, &length); \ + if (p == NULL) \ + { \ + mlt_properties pt = mlt_properties_new (); \ + mlt_properties_set_data (props, property, pt, 0, (mlt_destructor) mlt_properties_close, NULL); \ + mlt_properties_set_int (pt, "t", ofxproptype); \ + p = pt; \ + } \ + vt *v = mlt_properties_get_data (p, "v", &length); \ + vt *values = realloc (v, sizeof(vt) * (count)); \ + if (values == NULL) return kOfxStatErrUnknown; \ + memcpy (values, value, sizeof(vt) * (count)); \ + mlt_properties_set_data (p, "v", values, count, free, NULL); \ + return kOfxStatOK; \ + } + +MLTOFX_DEF_SETTER_N(Pointer, void *const, void *, mltofx_prop_pointer); +MLTOFX_DEF_SETTER_N(String, const char *const, char *, mltofx_prop_string); +MLTOFX_DEF_SETTER_N(Double, const double, double, mltofx_prop_double); +MLTOFX_DEF_SETTER_N(Int, const int, int, mltofx_prop_int); + +#define MLTOFX_DEF_GETTER_N(fn, fa) static OfxStatus propGet ## fn ## N (OfxPropertySetHandle properties, \ + const char *property, \ + int count, \ + fa *value) \ + { \ + if (properties == NULL) return kOfxStatErrBadHandle; \ + if (count < 0) return kOfxStatErrBadIndex; \ + mlt_properties props = (mlt_properties) properties; \ + int length = 0; \ + mlt_properties p = mlt_properties_get_data (props, property, &length); \ + if (p == NULL) return kOfxStatErrUnknown; \ + fa *v = mlt_properties_get_data (p, "v", &length); \ + if (count > length) return kOfxStatErrUnknown; \ + memcpy (value, v, sizeof(fa) * (count)); \ + return kOfxStatOK; \ + } + +MLTOFX_DEF_GETTER_N(Pointer, void *); +MLTOFX_DEF_GETTER_N(String, char *); +MLTOFX_DEF_GETTER_N(Double, double); +MLTOFX_DEF_GETTER_N(Int, int); + +static OfxStatus +propReset (OfxPropertySetHandle properties, + const char *property) +{ + if (properties == NULL) return kOfxStatErrBadHandle; + + mlt_properties props = (mlt_properties) properties; + int length = 0; + mlt_properties p = mlt_properties_get_data (props, property, &length); + if (p == NULL) return kOfxStatErrUnknown; + + mltofx_property_type prop_type = 0; + prop_type = mlt_properties_get_int (p, "t"); + void *values = mlt_properties_get_data (p, "v", &length); + + if (length == 0) return kOfxStatErrUnknown; + + switch (prop_type) + { + case mltofx_prop_int: + memset (values, 0, sizeof (int) * length); + break; + + case mltofx_prop_double: + memset (values, 0, sizeof (double) * length); + break; + + case mltofx_prop_string: + case mltofx_prop_pointer: + memset (values, 0, sizeof (void *) * length); + break; + + default: + break; + } + + return kOfxStatOK; +} + +static OfxStatus +propGetDimension (OfxPropertySetHandle properties, + const char *property, + int *count) +{ + if (properties == NULL) return kOfxStatErrBadHandle; + mlt_properties props = (mlt_properties) properties; + mlt_properties p = mlt_properties_get_data (props, property, count); + + if (p == NULL) + { + *count = 0; + } + else + { + int length = 0; + mlt_properties_get_data (p, "v", &length); + *count = length; + } + + return kOfxStatOK; +} + +static OfxPropertySuiteV1 MltOfxPropertySuiteV1 = + { + propSetPointer, + propSetString, + propSetDouble, + propSetInt, + propSetPointerN, + propSetStringN, + propSetDoubleN, + propSetIntN, + propGetPointer, + propGetString, + propGetDouble, + propGetInt, + propGetPointerN, + propGetStringN, + propGetDoubleN, + propGetIntN, + propReset, + propGetDimension + }; + +static OfxStatus +paramDefine (OfxParamSetHandle paramSet, + const char *paramType, + const char *name, + OfxPropertySetHandle *propertySet) +{ + mlt_log_debug(NULL, "`%s`:`%s`\n", name, paramType); + if (paramSet == NULL) return kOfxStatErrBadHandle; + mlt_properties params = (mlt_properties) paramSet; + + int length = 0; + mlt_properties p = mlt_properties_get_data (params, name, &length); + + if (p != NULL) return kOfxStatErrExists; + + if (strcmp(kOfxParamTypeInteger, paramType) == 0 || + strcmp(kOfxParamTypeDouble, paramType) == 0 || + strcmp(kOfxParamTypeBoolean, paramType) == 0 || + strcmp(kOfxParamTypeChoice, paramType) == 0 || + strcmp(kOfxParamTypeStrChoice, paramType) == 0 || + strcmp(kOfxParamTypeRGBA, paramType) == 0 || + strcmp(kOfxParamTypeRGB, paramType) == 0 || + strcmp(kOfxParamTypeDouble2D, paramType) == 0 || + strcmp(kOfxParamTypeInteger2D, paramType) == 0 || + strcmp(kOfxParamTypeDouble3D, paramType) == 0 || + strcmp(kOfxParamTypeInteger3D, paramType) == 0 || + strcmp(kOfxParamTypeString, paramType) == 0 || + strcmp(kOfxParamTypeCustom, paramType) == 0 || + strcmp(kOfxParamTypeBytes, paramType) == 0 || + strcmp(kOfxParamTypeGroup, paramType) == 0) + { + mlt_properties pt = mlt_properties_new (); + mlt_properties_set_string (pt, "t", paramType); + mlt_properties param_props = mlt_properties_new (); + mlt_properties_set_data (pt, "p", param_props, 0, (mlt_destructor) mlt_properties_close, NULL); + mlt_properties_set_data (params, name, pt, 0, (mlt_destructor) mlt_properties_close, NULL); + + if (propertySet != NULL) + { + *propertySet = (OfxPropertySetHandle) param_props; + } + } + else if (strcmp(kOfxParamTypePage, paramType) == 0 || strcmp(kOfxParamTypePushButton, paramType) == 0) + { + return kOfxStatErrUnsupported; + } + else + { + return kOfxStatErrUnknown; + } + + + return kOfxStatOK; +} + +static OfxStatus +paramGetHandle (OfxParamSetHandle paramSet, + const char *name, + OfxParamHandle *param, + OfxPropertySetHandle *propertySet) +{ + if (paramSet == NULL) return kOfxStatErrBadHandle; + + mlt_properties params = (mlt_properties) paramSet; + int length = 0; + mlt_properties p = mlt_properties_get_data (params, name, &length); + + if (p == NULL) return kOfxStatErrUnknown; + + *param = (OfxParamHandle) p; + + mlt_properties param_props = mlt_properties_get_data (p, "p", &length); + + if (param_props != NULL && propertySet != NULL) + { + *propertySet = (OfxPropertySetHandle) param_props; + } + + return kOfxStatOK; +} + +static OfxStatus +paramSetGetPropertySet (OfxParamSetHandle paramSet, + OfxPropertySetHandle *propHandle) +{ + if (paramSet == NULL) return kOfxStatErrBadHandle; + + mlt_properties params = (mlt_properties) paramSet; + + OfxPropertySetHandle plugin_props = mlt_properties_get_data (params, "plugin_props", NULL); + + if (plugin_props == NULL) return kOfxStatErrUnknown; + + *propHandle = plugin_props; + + return kOfxStatOK; +} + +static OfxStatus +paramGetPropertySet (OfxParamHandle param, + OfxPropertySetHandle *propHandle) +{ + if (param == NULL) return kOfxStatErrBadHandle; + + mlt_properties p = (mlt_properties) param; + int length = 0; + mlt_properties param_props = mlt_properties_get_data (p, "p", &length); + + if (param_props == NULL) return kOfxStatErrUnknown; + + *propHandle = (OfxPropertySetHandle) param_props; + + return kOfxStatOK; +} + +static OfxStatus +paramGetValue (OfxParamHandle paramHandle, ...) +{ + if (paramHandle == NULL) return kOfxStatErrBadHandle; + + va_list ap; + va_start (ap, paramHandle); + + mlt_properties param = (mlt_properties) paramHandle; + char *param_type = mlt_properties_get (param, "t"); + mlt_properties param_props = mlt_properties_get_data (param, "p", NULL); + + if (strcmp (param_type, kOfxParamTypeInteger) == 0 || + strcmp (param_type, kOfxParamTypeBoolean) == 0 || + strcmp (param_type, kOfxParamTypeChoice) == 0) + { + int *value = va_arg (ap, int *); + OfxStatus status = propGetInt((OfxPropertySetHandle) param_props, "MltOfxParamValue", 0, value); + if (status != kOfxStatOK) + { + status = propGetInt((OfxPropertySetHandle) param_props, "OfxParamPropDefault", 0, value); + if (status != kOfxStatOK) + { + va_end (ap); + return kOfxStatErrUnknown; + } + } + } + else if (strcmp (param_type, kOfxParamTypeDouble) == 0) + { + double *value = va_arg (ap, double *); + OfxStatus status = propGetDouble((OfxPropertySetHandle) param_props, "MltOfxParamValue", 0, value); + + if (status != kOfxStatOK) + { + status = propGetDouble((OfxPropertySetHandle) param_props, "OfxParamPropDefault", 0, value); + if (status != kOfxStatOK) + { + va_end (ap); + return kOfxStatErrUnknown; + } + } + } + else if (strcmp (param_type, kOfxParamTypeString) == 0 || strcmp (param_type, kOfxParamTypeStrChoice) == 0) + { + char **value = va_arg (ap, char **); + OfxStatus status = propGetString((OfxPropertySetHandle) param_props, "MltOfxParamValue", 0, value); + if (status != kOfxStatOK) + { + status = propGetString((OfxPropertySetHandle) param_props, "OfxParamPropDefault", 0, value); + if (status != kOfxStatOK) + { + va_end (ap); + return kOfxStatErrUnknown; + } + } + } + else if (strcmp (param_type, kOfxParamTypeRGBA) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeRGB) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeDouble2D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeInteger2D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeDouble3D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeInteger3D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeCustom) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeBytes) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeGroup) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypePage) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypePushButton) == 0) + { + } + + va_end (ap); + return kOfxStatOK; +} + +static OfxStatus +paramGetValueAtTime (OfxParamHandle paramHandle, + OfxTime time, ...) +{ + if (paramHandle == NULL) return kOfxStatErrBadHandle; + + va_list ap; + va_start (ap, time); + + mlt_properties param = (mlt_properties) paramHandle; + char *param_type = mlt_properties_get (param, "t"); + mlt_properties param_props = mlt_properties_get_data (param, "p", NULL); + + /* WIP make this use mlt_properties_anim_get_* functions maybe */ + + if (strcmp (param_type, kOfxParamTypeInteger) == 0 || + strcmp (param_type, kOfxParamTypeBoolean) == 0 || + strcmp (param_type, kOfxParamTypeChoice) == 0) + { + int *value = va_arg (ap, int *); + OfxStatus status = propGetInt((OfxPropertySetHandle) param_props, "MltOfxParamValue", 0, value); + if (status != kOfxStatOK) + { + status = propGetInt((OfxPropertySetHandle) param_props, "OfxParamPropDefault", 0, value); + if (status != kOfxStatOK) + { + va_end (ap); + return kOfxStatErrUnknown; + } + } + } + else if (strcmp (param_type, kOfxParamTypeDouble) == 0) + { + double *value = va_arg (ap, double *); + OfxStatus status = propGetDouble((OfxPropertySetHandle) param_props, "MltOfxParamValue", 0, value); + + if (status != kOfxStatOK) + { + status = propGetDouble((OfxPropertySetHandle) param_props, "OfxParamPropDefault", 0, value); + if (status != kOfxStatOK) + { + va_end (ap); + return kOfxStatErrUnknown; + } + } + } + else if (strcmp (param_type, kOfxParamTypeString) == 0 || strcmp (param_type, kOfxParamTypeStrChoice) == 0) + { + char **value = va_arg (ap, char **); + OfxStatus status = propGetString((OfxPropertySetHandle) param_props, "MltOfxParamValue", 0, value); + if (status != kOfxStatOK) + { + status = propGetString((OfxPropertySetHandle) param_props, "OfxParamPropDefault", 0, value); + if (status != kOfxStatOK) + { + va_end (ap); + return kOfxStatErrUnknown; + } + } + } + else if (strcmp (param_type, kOfxParamTypeRGBA) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeRGB) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeDouble2D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeInteger2D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeDouble3D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeInteger3D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeCustom) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeBytes) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeGroup) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypePage) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypePushButton) == 0) + { + } + + va_end (ap); + return kOfxStatOK; +} + +static OfxStatus +paramGetDerivative (OfxParamHandle paramHandle, + OfxTime time, ...) +{ + return kOfxStatOK; +} + +static OfxStatus +paramGetIntegral (OfxParamHandle paramHandle, + OfxTime time1, + OfxTime time2, ...) +{ + return kOfxStatOK; +} + +static OfxStatus +paramSetValue (OfxParamHandle paramHandle, ...) +{ + if (paramHandle == NULL) return kOfxStatErrBadHandle; + + va_list ap; + va_start (ap, paramHandle); + + mlt_properties param = (mlt_properties) paramHandle; + char *param_type = mlt_properties_get (param, "t"); + mlt_properties param_props = mlt_properties_get_data (param, "p", NULL); + + if (strcmp (param_type, kOfxParamTypeInteger) == 0 || + strcmp (param_type, kOfxParamTypeChoice) == 0 || + strcmp (param_type, kOfxParamTypeBoolean) == 0) + { + int value = va_arg (ap, int); + propSetInt ((OfxPropertySetHandle) param_props, "MltOfxParamValue", 0, value); + } + else if (strcmp (param_type, kOfxParamTypeDouble) == 0) + { + double value = va_arg (ap, double); + propSetDouble ((OfxPropertySetHandle) param_props, "MltOfxParamValue", 0, value); + } + else if (strcmp (param_type, kOfxParamTypeStrChoice) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeRGBA) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeRGB) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeDouble2D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeInteger2D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeDouble3D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeInteger3D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeString) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeCustom) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeBytes) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeGroup) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypePage) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypePushButton) == 0) + { + } + + va_end (ap); + return kOfxStatOK; +} + +/* time in frames it seems */ +static OfxStatus +paramSetValueAtTime (OfxParamHandle paramHandle, + OfxTime time, ...) +{ + mlt_log_debug(NULL, "<----paramSetValueAtTime---->\n"); + if (paramHandle == NULL) return kOfxStatErrBadHandle; + + /* WIP: animation is not supported yet */ + + va_list ap; + va_start (ap, time); + + mlt_properties param = (mlt_properties) paramHandle; + char *param_type = mlt_properties_get (param, "t"); + mlt_properties param_props = mlt_properties_get_data (param, "p", NULL); + + if (strcmp (param_type, kOfxParamTypeInteger) == 0 || + strcmp (param_type, kOfxParamTypeChoice) == 0 || + strcmp (param_type, kOfxParamTypeBoolean) == 0) + { + int value = va_arg (ap, int); + propSetInt ((OfxPropertySetHandle) param_props, "MltOfxParamValue", 0, value); + } + else if (strcmp (param_type, kOfxParamTypeDouble) == 0) + { + double value = va_arg (ap, double); + propSetDouble ((OfxPropertySetHandle) param_props, "MltOfxParamValue", 0, value); + } + else if (strcmp (param_type, kOfxParamTypeStrChoice) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeRGBA) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeRGB) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeDouble2D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeInteger2D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeDouble3D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeInteger3D) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeString) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeCustom) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeBytes) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypeGroup) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypePage) == 0) + { + } + else if (strcmp (param_type, kOfxParamTypePushButton) == 0) + { + } + + va_end (ap); + return kOfxStatOK; +} + +static OfxStatus +paramGetNumKeys (OfxParamHandle paramHandle, + unsigned int *numberOfKeys) +{ + return kOfxStatOK; +} + +static OfxStatus +paramGetKeyTime (OfxParamHandle paramHandle, + unsigned int nthKey, + OfxTime *time) +{ + return kOfxStatOK; +} + +static OfxStatus +paramGetKeyIndex (OfxParamHandle paramHandle, + OfxTime time, + int direction, + int *index) +{ + return kOfxStatOK; +} + +static OfxStatus +paramDeleteKey (OfxParamHandle paramHandle, + OfxTime time) +{ + return kOfxStatOK; +} + +static OfxStatus +paramDeleteAllKeys (OfxParamHandle paramHandle) +{ + return kOfxStatOK; +} + +static OfxStatus +paramCopy (OfxParamHandle paramTo, + OfxParamHandle paramFrom, + OfxTime dstOffset, + const OfxRangeD *frameRange) +{ + return kOfxStatOK; +} + +static OfxStatus +paramEditBegin (OfxParamSetHandle paramSet, + const char *name) +{ + return kOfxStatOK; +} + +static OfxStatus +paramEditEnd (OfxParamSetHandle paramSet) +{ + return kOfxStatOK; +} + +static OfxParameterSuiteV1 MltOfxParameterSuiteV1 = + { + paramDefine, + paramGetHandle, + paramSetGetPropertySet, + paramGetPropertySet, + paramGetValue, + paramGetValueAtTime, + paramGetDerivative, + paramGetIntegral, + paramSetValue, + paramSetValueAtTime, + paramGetNumKeys, + paramGetKeyTime, + paramGetKeyIndex, + paramDeleteKey, + paramDeleteAllKeys, + paramCopy, + paramEditBegin, + paramEditEnd + }; + +static OfxStatus +memoryAlloc (void *handle, + size_t nBytes, + void **allocatedData) +{ + /* handle is ignored */ + + void *temp = calloc (1, nBytes); + + if (temp == NULL) + return kOfxStatErrMemory; + + *allocatedData = temp; + + return kOfxStatOK; +} + +static OfxStatus +memoryFree (void *allocatedData) +{ + free (allocatedData); + + return kOfxStatOK; +} + +static OfxMemorySuiteV1 MltOfxMemorySuiteV1 = + { + memoryAlloc, + memoryFree + }; + +static OfxStatus +multiThread (OfxThreadFunctionV1 func, + unsigned int nThreads, + void *customArg) +{ + if (!func) { + return kOfxStatFailed; + } + + /* just ignore multi Threading for now use one thread */ + func(0,1,customArg); + + return kOfxStatOK; +} + +static OfxStatus +multiThreadNumCPUs (unsigned int *nCPUs) +{ + if (!nCPUs) + { + return kOfxStatFailed; + } + + *nCPUs = 1; + + return kOfxStatOK; +} + +static OfxStatus +multiThreadIndex (unsigned int *threadIndex) +{ + if (!threadIndex) + return kOfxStatFailed; + *threadIndex = 0; + + return kOfxStatOK; +} + +int +multiThreadIsSpawnedThread (void) +{ + return false; +} + +static OfxStatus +mutexCreate (OfxMutexHandle *mutex, + int lockCount) +{ + if (!mutex) + return kOfxStatFailed; + + // do nothing single threaded + *mutex = 0; + + return kOfxStatOK; +} + +static OfxStatus +mutexDestroy (const OfxMutexHandle mutex) +{ + if (mutex != 0) + return kOfxStatErrBadHandle; + // do nothing single threaded + + return kOfxStatOK; +} + +static OfxStatus +mutexLock (const OfxMutexHandle mutex) +{ + if (mutex != 0) + return kOfxStatErrBadHandle; + // do nothing single threaded + + return kOfxStatOK; +} + +static OfxStatus +mutexUnLock (const OfxMutexHandle mutex) +{ + if (mutex != 0) + return kOfxStatErrBadHandle; + // do nothing single threaded + + return kOfxStatOK; +} + +static OfxStatus +mutexTryLock (const OfxMutexHandle mutex) +{ + if (mutex != 0) + return kOfxStatErrBadHandle; + // do nothing single threaded + + return kOfxStatOK; +} + +static OfxMultiThreadSuiteV1 MltOfxMultiThreadSuiteV1 = + { + multiThread, + multiThreadNumCPUs, + multiThreadIndex, + multiThreadIsSpawnedThread, + mutexCreate, + mutexDestroy, + mutexLock, + mutexUnLock, + mutexTryLock + }; + +static OfxStatus +message (void *handle, + const char *messageType, + const char *messageId, + const char *format, ...) +{ + return kOfxStatOK; +} + +static OfxMessageSuiteV1 MltOfxMessageSuiteV1 = + { + message + }; + +static OfxStatus +setPersistentMessage (void *handle, + const char *messageType, + const char *messageId, + const char *format, ...) +{ + return kOfxStatOK; +} + +static OfxStatus +clearPersistentMessage (void *handle) +{ + return kOfxStatOK; +} + +static OfxMessageSuiteV2 MltOfxMessageSuiteV2 = + { + message, /* Same as the V1 message suite call. */ + setPersistentMessage, + clearPersistentMessage + }; + +static OfxStatus +interactSwapBuffers (OfxInteractHandle interactInstance) +{ + return kOfxStatOK; +} + +static OfxStatus +interactRedraw (OfxInteractHandle interactInstance) +{ + return kOfxStatOK; +} + +static OfxStatus +interactGetPropertySet (OfxInteractHandle interactInstance, + OfxPropertySetHandle *property) +{ + return kOfxStatOK; +} + +static OfxInteractSuiteV1 MltOfxInteractSuiteV1 = + { + interactSwapBuffers, + interactRedraw, + interactGetPropertySet + }; + +static OfxStatus +getColour (OfxDrawContextHandle context, + OfxStandardColour std_colour, + OfxRGBAColourF *colour) +{ + mlt_log_debug(NULL, "OfxDrawSuite `%s`\n", __FUNCTION__); + return kOfxStatOK; +} + +static OfxStatus +setColour (OfxDrawContextHandle context, + const OfxRGBAColourF *colour) +{ + mlt_log_debug(NULL, "OfxDrawSuite `%s`\n", __FUNCTION__); + return kOfxStatOK; +} + +static OfxStatus +setLineWidth (OfxDrawContextHandle context, + float width) +{ + mlt_log_debug(NULL, "OfxDrawSuite `%s`\n", __FUNCTION__); + return kOfxStatOK; +} + +static OfxStatus +setLineStipple (OfxDrawContextHandle context, + OfxDrawLineStipplePattern pattern) +{ + mlt_log_debug(NULL, "OfxDrawSuite `%s`\n", __FUNCTION__); + return kOfxStatOK; +} + +static OfxStatus +draw (OfxDrawContextHandle context, + OfxDrawPrimitive primitive, + const OfxPointD *points, + int point_count) +{ + mlt_log_debug(NULL, "OfxDrawSuite `%s`\n", __FUNCTION__); + return kOfxStatOK; +} + +static OfxStatus +drawText (OfxDrawContextHandle context, + const char *text, + const OfxPointD *pos, + int alignment) +{ + mlt_log_debug(NULL, "OfxDrawSuite `%s`\n", __FUNCTION__); + return kOfxStatOK; +} + +static OfxDrawSuiteV1 MltOfxDrawSuiteV1 = + { + getColour, + setColour, + setLineWidth, + setLineStipple, + draw, + drawText + }; + +static OfxStatus +progressStartV1 (void *effectInstance, + const char *label) +{ + return kOfxStatOK; +} + +static OfxStatus +progressUpdateV1 (void *effectInstance, + double progress) +{ + return kOfxStatOK; +} + +static OfxStatus +progressEndV1 (void *effectInstance) +{ + return kOfxStatOK; +} + +static OfxProgressSuiteV1 MltOfxProgressSuiteV1 = + { + progressStartV1, + progressUpdateV1, + progressEndV1 + }; + +static OfxStatus +progressStartV2 (void *effectInstance, + const char *message, + const char *messageid) +{ + return kOfxStatOK; +} + +static OfxStatus +progressUpdateV2 (void *effectInstance, + double progress) +{ + return kOfxStatOK; +} + +static OfxStatus +progressEndV2 (void *effectInstance) +{ + return kOfxStatOK; +} + +static OfxProgressSuiteV2 MltOfxProgressSuiteV2 = + { + progressStartV2, + progressUpdateV2, + progressEndV2 + }; + +static OfxStatus +getTime (void *instance, + double *time) +{ + return kOfxStatOK; +} + +static OfxStatus +gotoTime (void *instance, + double time) +{ + return kOfxStatOK; +} + +static OfxStatus +getTimeBounds (void *instance, + double *firstTime, + double *lastTime) +{ + return kOfxStatOK; +} + +static OfxTimeLineSuiteV1 MltOfxTimeLineSuiteV1 = + { + getTime, + gotoTime, + getTimeBounds + }; + +static OfxStatus +parametricParamGetValue (OfxParamHandle param, + int curveIndex, + OfxTime time, + double parametricPosition, + double *returnValue) +{ + return kOfxStatOK; +} + +static OfxStatus +parametricParamGetNControlPoints(OfxParamHandle param, + int curveIndex, + double time, + int *returnValue) +{ + return kOfxStatOK; +} + +static OfxStatus +parametricParamGetNthControlPoint (OfxParamHandle param, + int curveIndex, + double time, + int nthCtl, + double *key, + double *value) +{ + return kOfxStatOK; +} + +static OfxStatus +parametricParamSetNthControlPoint (OfxParamHandle param, + int curveIndex, + double time, + int nthCtl, + double key, + double value, + bool addAnimationKey) +{ + return kOfxStatOK; +} + +static OfxStatus +parametricParamAddControlPoint (OfxParamHandle param, + int curveIndex, + double time, + double key, + double value, + bool addAnimationKey) +{ + return kOfxStatOK; +} + +static OfxStatus +parametricParamDeleteControlPoint (OfxParamHandle param, + int curveIndex, + int nthCtl) +{ + return kOfxStatOK; +} + +static OfxStatus +parametricParamDeleteAllControlPoints (OfxParamHandle param, + int curveIndex) +{ + return kOfxStatOK; +} + +static OfxParametricParameterSuiteV1 MltOfxParametricParameterSuiteV1 = + { + parametricParamGetValue, + parametricParamGetNControlPoints, + parametricParamGetNthControlPoint, + parametricParamSetNthControlPoint, + parametricParamAddControlPoint, + parametricParamDeleteControlPoint, + parametricParamDeleteAllControlPoints + }; + +const void * +MltOfxfetchSuite (OfxPropertySetHandle host, + const char *suiteName, + int suiteVersion) +{ + if (strcmp (suiteName, kOfxImageEffectSuite) == 0 && suiteVersion == 1) + { + return &MltOfxImageEffectSuiteV1; + } + else if (strcmp (suiteName, kOfxParameterSuite) == 0 && suiteVersion == 1) + { + return &MltOfxParameterSuiteV1; + } + else if (strcmp (suiteName, kOfxPropertySuite) == 0 && suiteVersion == 1) + { + return &MltOfxPropertySuiteV1; + } + else if (strcmp (suiteName, kOfxMemorySuite) == 0 && suiteVersion == 1) + { + return &MltOfxMemorySuiteV1; + } + else if (strcmp (suiteName, kOfxMultiThreadSuite) == 0 && suiteVersion == 1) + { + return &MltOfxMultiThreadSuiteV1; + } + else if (strcmp (suiteName, kOfxMessageSuite) == 0 && suiteVersion == 1) + { + return &MltOfxMessageSuiteV1; + } + else if (strcmp (suiteName, kOfxMessageSuite) == 0 && suiteVersion == 2) + { + return &MltOfxMessageSuiteV2; + } + else if (strcmp (suiteName, kOfxInteractSuite) == 0 && suiteVersion == 1) + { + return &MltOfxInteractSuiteV1; + } + else if (strcmp (suiteName, kOfxDrawSuite) == 0 && suiteVersion == 1) + { + return &MltOfxDrawSuiteV1; + } + else if (strcmp (suiteName, kOfxProgressSuite) == 0 && suiteVersion == 1) + { + return &MltOfxProgressSuiteV1; + } + else if (strcmp (suiteName, kOfxProgressSuite) == 0 && suiteVersion == 2) + { + return &MltOfxProgressSuiteV2; + } + else if (strcmp (suiteName, kOfxTimeLineSuite) == 0 && suiteVersion == 1) + { + return &MltOfxTimeLineSuiteV1; + } + else if (strcmp (suiteName, kOfxParametricParameterSuite) == 0 && suiteVersion == 1) + { + return &MltOfxParametricParameterSuiteV1; + } + + mlt_log_debug(NULL, "%s v%d is not supported\n", suiteName, suiteVersion); + return NULL; +} + +void +mltofx_init_host_properties (OfxPropertySetHandle host_properties) +{ + propSetString (host_properties, kOfxPropName, 0, "MLT"); + propSetString (host_properties, kOfxImageEffectPropContext, 0, kOfxImageEffectContextGeneral); + propSetString (host_properties, kOfxImageEffectPropSupportedPixelDepths, 0, kOfxBitDepthByte); /* kOfxBitDepthByte is hardcoded */ + propSetString (host_properties, kOfxImageEffectPropSupportedPixelDepths, 1, kOfxBitDepthShort); + propSetString (host_properties, kOfxImageEffectPropSupportedPixelDepths, 2, kOfxBitDepthHalf); + propSetString (host_properties, kOfxImageEffectPropSupportedPixelDepths, 3, kOfxBitDepthFloat); +} + + +OfxHost MltOfxHost = + { + NULL, + MltOfxfetchSuite + }; + +static void mltofx_log_status_code (OfxStatus code, char *msg) +{ + mlt_log_debug(NULL, "output of `%s` is ", msg); + switch (code) + { + case kOfxStatOK: + mlt_log_debug(NULL, "kOfxStatOK\n"); + break; + + case kOfxStatFailed: + mlt_log_debug(NULL, "kOfxStatFailed\n"); + break; + + case kOfxStatErrFatal: + mlt_log_debug(NULL, "kOfxStatErrFatal\n"); + break; + + case kOfxStatErrUnknown: + mlt_log_debug(NULL, "kOfxStatErrUnknown\n"); + break; + + case kOfxStatErrMissingHostFeature: + mlt_log_debug(NULL, "kOfxStatErrMissingHostFeature\n"); + break; + + case kOfxStatErrUnsupported: + mlt_log_debug(NULL, "kOfxStatErrUnsupported\n"); + break; + + case kOfxStatErrExists: + mlt_log_debug(NULL, "kOfxStatErrExists\n"); + break; + + case kOfxStatErrFormat: + mlt_log_debug(NULL, "kOfxStatErrFormat\n"); + break; + + case kOfxStatErrMemory: + mlt_log_debug(NULL, "kOfxStatErrMemory\n"); + break; + + case kOfxStatErrBadHandle: + mlt_log_debug(NULL, "kOfxStatErrBadHandle\n"); + break; + + case kOfxStatErrBadIndex: + mlt_log_debug(NULL, "kOfxStatErrBadIndex\n"); + break; + + case kOfxStatErrValue: + mlt_log_debug(NULL, "kOfxStatErrValue\n"); + break; + + case kOfxStatReplyYes: + mlt_log_debug(NULL, "kOfxStatReplyYes\n"); + break; + + case kOfxStatReplyNo: + mlt_log_debug(NULL, "kOfxStatReplyNo\n"); + break; + + case kOfxStatReplyDefault: + mlt_log_debug(NULL, "kOfxStatReplyDefault\n"); + break; + + default: + break; + } + mlt_log_debug(NULL, "\n"); +} + +void +mltofx_action_render (OfxPlugin *plugin, mlt_properties image_effect, int width, int height) +{ + mlt_properties render_in_args = mlt_properties_get_data (image_effect, "render_in_args", NULL); + propSetDouble ((OfxPropertySetHandle) render_in_args, kOfxPropTime, 0, 0.0); + + propSetString ((OfxPropertySetHandle) render_in_args, kOfxImageEffectPropFieldToRender, 0, kOfxImageFieldBoth); + + propSetInt ((OfxPropertySetHandle) render_in_args, kOfxImageEffectPropRenderWindow, 0, 0); + propSetInt ((OfxPropertySetHandle) render_in_args, kOfxImageEffectPropRenderWindow, 1, 0); + propSetInt ((OfxPropertySetHandle) render_in_args, kOfxImageEffectPropRenderWindow, 2, width); + propSetInt ((OfxPropertySetHandle) render_in_args, kOfxImageEffectPropRenderWindow, 3, height); + + propSetDouble ((OfxPropertySetHandle) render_in_args, kOfxImageEffectPropRenderScale, 0, 1.0); + propSetDouble ((OfxPropertySetHandle) render_in_args, kOfxImageEffectPropRenderScale, 1, 1.0); + + propSetInt ((OfxPropertySetHandle) render_in_args, kOfxImageEffectPropSequentialRenderStatus, 0, 1); + + propSetInt ((OfxPropertySetHandle) render_in_args, kOfxImageEffectPropInteractiveRenderStatus, 0, 0); + + propSetInt ((OfxPropertySetHandle) render_in_args, kOfxImageEffectPropRenderQualityDraft, 0, 0); + + OfxStatus status_code = + plugin->mainEntry (kOfxImageEffectActionRender, + (OfxImageEffectHandle) image_effect, + (OfxPropertySetHandle) render_in_args, + NULL); + + mltofx_log_status_code (status_code, kOfxImageEffectActionRender); +} + +void +mltofx_set_output_clip_data (OfxPlugin *plugin, mlt_properties image_effect, uint8_t *image, int width, int height) +{ + mlt_properties clip; + mlt_properties clip_prop; + + clipGetHandle ((OfxImageEffectHandle) image_effect, "Output", (OfxImageClipHandle *) &clip, (OfxPropertySetHandle *) &clip_prop); + + propSetInt ((OfxPropertySetHandle) clip_prop, kOfxImagePropRowBytes, 0, width*4); /* WIP change this 4 hardcoded depth size */ + propSetString ((OfxPropertySetHandle) clip_prop, "OfxImageEffectPropPixelDepth", 0, kOfxBitDepthByte); + propSetString ((OfxPropertySetHandle) clip_prop, "OfxImageEffectPropComponents", 0, kOfxImageComponentRGBA); + + propSetPointer ((OfxPropertySetHandle) clip_prop, "OfxImagePropData", 0, (void *) image); + propSetInt ((OfxPropertySetHandle) clip_prop, "OfxImagePropBounds", 0, 0); + propSetInt ((OfxPropertySetHandle) clip_prop, "OfxImagePropBounds", 1, 0); + propSetInt ((OfxPropertySetHandle) clip_prop, "OfxImagePropBounds", 2, width); + propSetInt ((OfxPropertySetHandle) clip_prop, "OfxImagePropBounds", 3, height); + + propSetInt ((OfxPropertySetHandle) clip_prop, kOfxImagePropRegionOfDefinition, 0, 0); + propSetInt ((OfxPropertySetHandle) clip_prop, kOfxImagePropRegionOfDefinition, 1, 0); + propSetInt ((OfxPropertySetHandle) clip_prop, kOfxImagePropRegionOfDefinition, 2, width); + propSetInt ((OfxPropertySetHandle) clip_prop, kOfxImagePropRegionOfDefinition, 3, height); + + propSetString ((OfxPropertySetHandle) clip_prop, kOfxImageEffectPropPreMultiplication, 0, kOfxImageUnPreMultiplied); + propSetString ((OfxPropertySetHandle) clip_prop, kOfxImagePropField, 0, kOfxImageFieldNone); /* I'm not sure about this */ + + char *tstr = calloc(1, strlen ("Output") + 11); + sprintf (tstr, "%s%04d%04d", "Output", rand () % 9999, rand () % 9999); /* WIP: do something better */ + propSetString ((OfxPropertySetHandle) clip_prop, kOfxImagePropUniqueIdentifier, 0, tstr); + free (tstr); + + propSetDouble ((OfxPropertySetHandle) clip_prop, kOfxImageEffectPropRenderScale, 0, 1.0); + propSetDouble ((OfxPropertySetHandle) clip_prop, kOfxImageEffectPropRenderScale, 1, 1.0); + + propSetDouble ((OfxPropertySetHandle) clip_prop, kOfxImagePropPixelAspectRatio, 0, (double) width / (double) height); +} + +void +mltofx_set_source_clip_data (OfxPlugin *plugin, mlt_properties image_effect, uint8_t *image, int width, int height) +{ + mlt_properties clip; + mlt_properties clip_prop; + + clipGetHandle ((OfxImageEffectHandle) image_effect, "Source", (OfxImageClipHandle *) &clip, (OfxPropertySetHandle *) &clip_prop); + + propSetInt ((OfxPropertySetHandle) clip_prop, "OfxImagePropRowBytes", 0, width*4); /* WIP change this 4 hardcoded depth size */ + propSetString ((OfxPropertySetHandle) clip_prop, "OfxImageEffectPropPixelDepth", 0, kOfxBitDepthByte); + propSetString ((OfxPropertySetHandle) clip_prop, "OfxImageEffectPropComponents", 0, kOfxImageComponentRGBA); + propSetPointer ((OfxPropertySetHandle) clip_prop, "OfxImagePropData", 0, (void *) image); + propSetInt ((OfxPropertySetHandle) clip_prop, "OfxImagePropBounds", 0, 0); + propSetInt ((OfxPropertySetHandle) clip_prop, "OfxImagePropBounds", 1, 0); + propSetInt ((OfxPropertySetHandle) clip_prop, "OfxImagePropBounds", 2, width); + propSetInt ((OfxPropertySetHandle) clip_prop, "OfxImagePropBounds", 3, height); + + propSetInt ((OfxPropertySetHandle) clip_prop, kOfxImagePropRegionOfDefinition, 0, 0); + propSetInt ((OfxPropertySetHandle) clip_prop, kOfxImagePropRegionOfDefinition, 1, 0); + propSetInt ((OfxPropertySetHandle) clip_prop, kOfxImagePropRegionOfDefinition, 2, width); + propSetInt ((OfxPropertySetHandle) clip_prop, kOfxImagePropRegionOfDefinition, 3, height); + + propSetDouble ((OfxPropertySetHandle) clip_prop, kOfxImagePropPixelAspectRatio, 0, (double) width / (double) height); + + propSetString ((OfxPropertySetHandle) clip_prop, kOfxImageEffectPropPreMultiplication, 0, kOfxImageUnPreMultiplied); + propSetString ((OfxPropertySetHandle) clip_prop, kOfxImagePropField, 0, kOfxImageFieldNone); /* I'm not sure about this */ + + char *tstr = calloc(1, strlen ("Source") + 11); + sprintf (tstr, "%s%04d%04d", "Source", rand () % 9999, rand () % 9999); /* WIP: do something better */ + propSetString ((OfxPropertySetHandle) clip_prop, kOfxImagePropUniqueIdentifier, 0, tstr); + free (tstr); + + propSetDouble ((OfxPropertySetHandle) clip_prop, kOfxImageEffectPropRenderScale, 0, 1.0); + propSetDouble ((OfxPropertySetHandle) clip_prop, kOfxImageEffectPropRenderScale, 1, 1.0); + + propSetInt ((OfxPropertySetHandle) clip_prop, kOfxImageClipPropConnected, 0, 1); +} + +void +mltofx_get_clip_preferences (OfxPlugin *plugin, mlt_properties image_effect) +{ + mlt_properties get_clippref_args = mlt_properties_get_data (image_effect, "get_clippref_args", NULL); + OfxStatus status_code = + plugin->mainEntry (kOfxImageEffectActionGetClipPreferences, + (OfxImageEffectHandle) image_effect, + NULL, + (OfxPropertySetHandle) get_clippref_args); + mltofx_log_status_code (status_code, kOfxImageEffectActionGetClipPreferences); +} + +void +mltofx_get_regions_of_interest (OfxPlugin *plugin, mlt_properties image_effect, double width, double height) +{ + mlt_properties get_roi_in_args = mlt_properties_get_data (image_effect, "get_roi_in_args", NULL); + mlt_properties get_roi_out_args = mlt_properties_get_data (image_effect, "get_roi_out_args", NULL); + + propSetDouble ((OfxPropertySetHandle) get_roi_in_args, kOfxPropTime, 0, 0.0); + propSetDouble ((OfxPropertySetHandle) get_roi_in_args, kOfxPropTime, 1, 0.0); + propSetDouble ((OfxPropertySetHandle) get_roi_in_args, kOfxImageEffectPropRenderScale, 0, 1.0); + propSetDouble ((OfxPropertySetHandle) get_roi_in_args, kOfxImageEffectPropRenderScale, 1, 1.0); + + propSetDouble ((OfxPropertySetHandle) get_roi_in_args, kOfxImageEffectPropRegionOfInterest, 0, 0.0); + propSetDouble ((OfxPropertySetHandle) get_roi_in_args, kOfxImageEffectPropRegionOfInterest, 1, 0.0); + propSetDouble ((OfxPropertySetHandle) get_roi_in_args, kOfxImageEffectPropRegionOfInterest, 2, width); + propSetDouble ((OfxPropertySetHandle) get_roi_in_args, kOfxImageEffectPropRegionOfInterest, 3, height); + + OfxStatus status_code = + plugin->mainEntry (kOfxImageEffectActionGetRegionsOfInterest, + (OfxImageEffectHandle) image_effect, + (OfxPropertySetHandle) get_roi_in_args, + (OfxPropertySetHandle) get_roi_out_args); + mltofx_log_status_code (status_code, kOfxImageEffectActionGetRegionsOfInterest); +} + +void +mltofx_end_sequence_render (OfxPlugin *plugin, mlt_properties image_effect) +{ + mlt_properties end_sequence_props = mlt_properties_get_data (image_effect, "end_sequence_props", NULL); + propSetDouble ((OfxPropertySetHandle) end_sequence_props, kOfxImageEffectPropFrameRange, 0, 0.0); + + propSetDouble ((OfxPropertySetHandle) end_sequence_props, kOfxImageEffectPropFrameRange, 1, 0.0); + + propSetDouble ((OfxPropertySetHandle) end_sequence_props, kOfxImageEffectPropFrameStep, 0, 1.0); + + propSetInt ((OfxPropertySetHandle) end_sequence_props, kOfxPropIsInteractive, 0, 0); + + propSetDouble ((OfxPropertySetHandle) end_sequence_props, kOfxImageEffectPropRenderScale, 0, 1.0); + propSetDouble ((OfxPropertySetHandle) end_sequence_props, kOfxImageEffectPropRenderScale, 1, 1.0); + + propSetInt ((OfxPropertySetHandle) end_sequence_props, kOfxImageEffectPropSequentialRenderStatus, 0, 1); + + propSetInt ((OfxPropertySetHandle) end_sequence_props, kOfxImageEffectPropInteractiveRenderStatus, 0, 0); + + OfxStatus status_code = + plugin->mainEntry (kOfxImageEffectActionEndSequenceRender, + (OfxImageEffectHandle) image_effect, + (OfxPropertySetHandle) end_sequence_props, + NULL); + mltofx_log_status_code (status_code, kOfxImageEffectActionEndSequenceRender); +} + +void +mltofx_begin_sequence_render (OfxPlugin *plugin, mlt_properties image_effect) +{ + mlt_properties begin_sequence_props = mlt_properties_get_data (image_effect, "begin_sequence_props", NULL); + propSetDouble ((OfxPropertySetHandle) begin_sequence_props, kOfxImageEffectPropFrameRange, 0, 0.0); + propSetDouble ((OfxPropertySetHandle) begin_sequence_props, kOfxImageEffectPropFrameRange, 1, 0.0); + propSetDouble ((OfxPropertySetHandle) begin_sequence_props, kOfxImageEffectPropFrameStep, 0, 1.0); + + propSetInt ((OfxPropertySetHandle) begin_sequence_props, kOfxPropIsInteractive, 0, 0); + + propSetDouble ((OfxPropertySetHandle) begin_sequence_props, kOfxImageEffectPropRenderScale, 0, 1.0); + propSetDouble ((OfxPropertySetHandle) begin_sequence_props, kOfxImageEffectPropRenderScale, 1, 1.0); + + propSetInt ((OfxPropertySetHandle) begin_sequence_props, kOfxImageEffectPropSequentialRenderStatus, 0, 1); + + propSetInt ((OfxPropertySetHandle) begin_sequence_props, kOfxImageEffectPropInteractiveRenderStatus, 0, 0); + OfxStatus status_code = + plugin->mainEntry (kOfxImageEffectActionBeginSequenceRender, + (OfxImageEffectHandle) image_effect, + (OfxPropertySetHandle) begin_sequence_props, + NULL); + mltofx_log_status_code (status_code, kOfxImageEffectActionBeginSequenceRender); +} + +void +mltofx_create_instance (OfxPlugin *plugin, mlt_properties image_effect) +{ + OfxStatus status_code = + plugin->mainEntry (kOfxActionCreateInstance, (OfxImageEffectHandle) image_effect, NULL, NULL); + mltofx_log_status_code (status_code, kOfxActionCreateInstance); +} + +void +mltofx_destroy_instance (OfxPlugin *plugin, mlt_properties image_effect) +{ + OfxStatus status_code = + plugin->mainEntry (kOfxActionDestroyInstance, (OfxImageEffectHandle) image_effect, NULL, NULL); + mltofx_log_status_code (status_code, kOfxActionDestroyInstance); +} + +void +mltofx_param_set_value (mlt_properties params, char *key, mltofx_property_type type, ...) +{ + mlt_properties param = NULL; + paramGetHandle ((OfxParamSetHandle) params, key, (OfxParamHandle *) ¶m, NULL); + + /* WIP: maybe it will be better idea to use paramSetValueAtTime */ + + va_list ap; + va_start (ap, type); + + switch (type) + { + case mltofx_prop_int: + { + int value = va_arg (ap, int); + paramSetValue ((OfxParamHandle) param, value); + } + break; + + case mltofx_prop_double: + { + double value = va_arg (ap, double); + paramSetValue ((OfxParamHandle) param, value); + } + break; + + case mltofx_prop_string: + { + char *value = va_arg (ap, char *); + paramSetValue ((OfxParamHandle) param, value); + } + break; + + default: + break; + } + + va_end (ap); +} + +void * +mltofx_fetch_params (OfxPlugin *plugin, + mlt_properties params) +{ + mlt_properties image_effect = mlt_properties_new (); + mlt_properties clips = mlt_properties_new (); + mlt_properties props = mlt_properties_new (); + mlt_properties iparams = mlt_properties_new (); + + mlt_properties_set_data (image_effect, "clips", clips, 0, (mlt_destructor) mlt_properties_close, NULL); + mlt_properties_set_data (image_effect, "props", props, 0, (mlt_destructor) mlt_properties_close, NULL); + mlt_properties_set_data (image_effect, "params", iparams, 0, (mlt_destructor) mlt_properties_close, NULL); + mlt_properties_set_data (iparams, "plugin_props", props, 0, (mlt_destructor) mlt_properties_close, NULL); + mlt_properties_set_data (image_effect, "mltofx_params", params, 0, (mlt_destructor) mlt_properties_close, NULL); + + propSetString ((OfxPropertySetHandle) props, kOfxImageEffectPropContext, 0, kOfxImageEffectContextGeneral); + + plugin->setHost (&MltOfxHost); + + OfxStatus status_code = kOfxStatErrUnknown; + status_code = plugin->mainEntry (kOfxActionLoad, NULL, NULL, NULL); + mltofx_log_status_code (status_code, "kOfxActionLoad"); + + status_code = plugin->mainEntry (kOfxActionDescribe, (OfxImageEffectHandle) image_effect, NULL, NULL); + mltofx_log_status_code (status_code, "kOfxActionDescribe"); + + status_code = plugin->mainEntry (kOfxImageEffectActionDescribeInContext, (OfxImageEffectHandle) image_effect, (OfxPropertySetHandle) MltOfxHost.host, NULL); + mltofx_log_status_code (status_code, "kOfxImageEffectActionDescribeInContext"); + + int iparams_length = mlt_properties_count (iparams); + int ipiter; + + /* starting with 1 to skip the plugin_props */ + for (ipiter = 1; ipiter < iparams_length; ++ipiter) + { + char *name = mlt_properties_get_name(iparams, ipiter); + mlt_properties pp = mlt_properties_get_data (iparams, name, NULL); + char *pt = mlt_properties_get (pp, "t"); + + mlt_properties ppp = mlt_properties_get_data (pp, "p", NULL); + + int is_secret = -1; + propGetInt ((OfxPropertySetHandle) ppp, kOfxParamPropSecret, 0, &is_secret); + if (is_secret == 1) continue; + + mlt_properties p = mlt_properties_new (); + + mlt_properties_set_data(params, + name, + p, + 0, + (mlt_destructor) mlt_properties_close, + NULL); + + int p_length = mlt_properties_count (ppp); + + if (strcmp (pt, kOfxParamTypeInteger) == 0) + { + mlt_properties_set (p, "type", "integer"); + } + else if (strcmp (pt, kOfxParamTypeDouble) == 0) + { + mlt_properties_set (p, "type", "double"); + } + else if (strcmp (pt, kOfxParamTypeChoice) == 0) + { + mlt_properties_set (p, "type", "integer"); + } + else if (strcmp (pt, kOfxParamTypeString) == 0) + /* else if (strcmp (pt, kOfxParamTypeChoice) == 0 || + strcmp (pt, kOfxParamTypeString) == 0) */ + { + mlt_properties_set (p, "type", "string"); + } + else if (strcmp (pt, kOfxParamTypeBoolean) == 0) + { + mlt_properties_set (p, "type", "boolean"); + } + else if (strcmp (pt, kOfxParamTypeGroup) == 0) + { + mlt_properties_set (p, "type", "group"); + int opened = 0; + propGetInt ((OfxPropertySetHandle) ppp, kOfxParamPropGroupOpen, 0, &opened); + mlt_properties_set_int (p, "opened", opened); + } + + int animation = 1; + propGetInt ((OfxPropertySetHandle) ppp, kOfxParamPropAnimates, 0, &animation); + mlt_properties_set (p, "animation", animation ? "yes" : "no"); + + int jt; + for (jt = 0; jt < p_length; ++jt) + { + char *p_name = mlt_properties_get_name(ppp, jt); + + if (strcmp (p_name, kOfxParamPropDefault) == 0) + { + if (strcmp (pt, kOfxParamTypeInteger) == 0 || + strcmp (pt, kOfxParamTypeChoice) == 0 || + strcmp (pt, kOfxParamTypeBoolean) == 0) + { + int default_value = 0; + propGetInt ((OfxPropertySetHandle) ppp, p_name, 0, &default_value); + mlt_properties_set_int (p, "default", default_value); + } + else if (strcmp (pt, kOfxParamTypeDouble) == 0) + { + double default_value = 0.0; + propGetDouble ((OfxPropertySetHandle) ppp, p_name, 0, &default_value); + mlt_properties_set_double (p, "default", default_value); + } + else if (strcmp (pt, kOfxParamTypeString) == 0) + { + char *default_value = ""; + propGetString ((OfxPropertySetHandle) ppp, p_name, 0, &default_value); + mlt_properties_set (p, "default", default_value); + } + + if (strcmp (pt, kOfxParamTypeChoice) == 0) + { + char key[20]; + int count = 0; + mlt_properties choices = mlt_properties_new (); + mlt_properties_set_data (p, "values", choices, 0, (mlt_destructor) mlt_properties_close, NULL); + + propGetDimension ((OfxPropertySetHandle) ppp, kOfxParamPropChoiceOption, &count); + + int jtr; + for (jtr = 0; jtr < count; ++jtr) + { + key[0] = '\0'; + sprintf (key, "%d", jtr); + char *choice_str = NULL; + propGetString ((OfxPropertySetHandle) ppp, kOfxParamPropChoiceOption, jtr, &choice_str); + mlt_properties_set (choices, key, choice_str); + } + } + } + else if (strcmp (p_name, kOfxParamPropMin) == 0) + { + if (strcmp (pt, kOfxParamTypeInteger) == 0 || + strcmp (pt, kOfxParamTypeChoice) == 0 || + strcmp (pt, kOfxParamTypeBoolean) == 0) + { + int minimum_value = 0; + propGetInt ((OfxPropertySetHandle) ppp, p_name, 0, &minimum_value); + mlt_properties_set_int (p, "minimum", minimum_value); + } + else if (strcmp (pt, kOfxParamTypeDouble) == 0) + { + double minimum_value = 0.0; + propGetDouble ((OfxPropertySetHandle) ppp, p_name, 0, &minimum_value); + mlt_properties_set_double (p, "minimum", minimum_value); + } + else if (strcmp (pt, kOfxParamTypeString) == 0) + { + char *minimum_value = ""; + propGetString ((OfxPropertySetHandle) ppp, p_name, 0, &minimum_value); + mlt_properties_set (p, "minimum", minimum_value); + } + } + else if (strcmp (p_name, kOfxParamPropMax) == 0) + { + if (strcmp (pt, kOfxParamTypeInteger) == 0 || + strcmp (pt, kOfxParamTypeChoice) == 0 || + strcmp (pt, kOfxParamTypeBoolean) == 0) + { + int maximum_value = 0; + propGetInt ((OfxPropertySetHandle) ppp, p_name, 0, &maximum_value); + mlt_properties_set_int (p, "maximum", maximum_value); + } + else if (strcmp (pt, kOfxParamTypeDouble) == 0) + { + double maximum_value = 0.0; + propGetDouble ((OfxPropertySetHandle) ppp, p_name, 0, &maximum_value); + mlt_properties_set_double (p, "maximum", maximum_value); + } + else if (strcmp (pt, kOfxParamTypeString) == 0) + { + char *maximum_value = ""; + propGetString ((OfxPropertySetHandle) ppp, p_name, 0, &maximum_value); + mlt_properties_set (p, "maximum", maximum_value); + } + } + else if (strcmp (p_name, kOfxParamPropStringMode) == 0) + { + char *str_value = ""; + propGetString ((OfxPropertySetHandle) ppp, p_name, 0, &str_value); + if (strcmp (str_value, kOfxParamStringIsLabel) == 0) + { + mlt_properties_set (p, "readonly", "yes"); + } + } + else if (strcmp (p_name, kOfxParamPropParent) == 0) + { + char *str_value = ""; + propGetString ((OfxPropertySetHandle) ppp, p_name, 0, &str_value); + mlt_properties_set (p, "group", str_value); + } + else if (strcmp (p_name, kOfxPropLabel) == 0) + { + char *str_value = ""; + propGetString ((OfxPropertySetHandle) ppp, p_name, 0, &str_value); + mlt_properties_set (p, "title", str_value); + } + } + } + + return image_effect; +} diff --git a/src/modules/openfx/mlt_openfx.h b/src/modules/openfx/mlt_openfx.h new file mode 100644 index 000000000..9098da0f0 --- /dev/null +++ b/src/modules/openfx/mlt_openfx.h @@ -0,0 +1,78 @@ +/* + * MLT OpenFX + * + * Copyright (C) 2024 Meltytech, LLC + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + */ + +#ifndef MLT_OPENFX_H +#define MLT_OPENFX_H + +#include +#include +#include +#include +#include +#include +#include +#include "ofxCore.h" + +typedef enum { + mltofx_prop_none = 0, + mltofx_prop_int = 1, + mltofx_prop_string = 2, + mltofx_prop_double = 8, + mltofx_prop_pointer = 16, +} mltofx_property_type; + +void * +mltofx_fetch_params (OfxPlugin *plugin, + mlt_properties params); + +void +mltofx_create_instance (OfxPlugin *plugin, mlt_properties image_effect); + +void +mltofx_begin_sequence_render (OfxPlugin *plugin, mlt_properties image_effect); + +void +mltofx_end_sequence_render (OfxPlugin *plugin, mlt_properties image_effect); + +void +mltofx_get_regions_of_interest (OfxPlugin *plugin, mlt_properties image_effect, double width, double height); + +void +mltofx_get_clip_preferences (OfxPlugin *plugin, mlt_properties image_effect); + +void +mltofx_set_source_clip_data (OfxPlugin *plugin, mlt_properties image_effect, uint8_t *image, int width, int height); + +void +mltofx_set_output_clip_data (OfxPlugin *plugin, mlt_properties image_effect, uint8_t *image, int width, int height); + +void +mltofx_action_render (OfxPlugin *plugin, mlt_properties image_effect, int width, int height); + +void +mltofx_destroy_instance (OfxPlugin *plugin, mlt_properties image_effect); + +void +mltofx_init_host_properties (OfxPropertySetHandle host_properties); + +void +mltofx_param_set_value (mlt_properties params, char *key, mltofx_property_type type, ...); + +#endif diff --git a/src/modules/openfx/ofxCore.h b/src/modules/openfx/ofxCore.h new file mode 100644 index 000000000..772826efa --- /dev/null +++ b/src/modules/openfx/ofxCore.h @@ -0,0 +1,964 @@ +#ifndef _ofxCore_h_ +#define _ofxCore_h_ + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + + +#include "stddef.h" // for size_t +#include // for INT_MIN & INT_MAX + +#ifdef __cplusplus +extern "C" { +#endif + +/** @file ofxCore.h +Contains the core OFX architectural struct and function definitions. For more details on the basic OFX architecture, see \ref Architecture. +*/ + + +/** @brief Platform independent export macro. + * + * This macro is to be used before any symbol that is to be + * exported from a plug-in. This is OS/compiler dependent. + */ +#if defined(WIN32) || defined(WIN64) + #define OfxExport extern __declspec(dllexport) +#else + #define OfxExport extern +#endif + +/** @brief Blind data structure to manipulate sets of properties through */ +typedef struct OfxPropertySetStruct *OfxPropertySetHandle; + +/** @brief OFX status return type */ +typedef int OfxStatus; + +/** @brief Generic host structure passed to OfxPlugin::setHost function + + This structure contains what is needed by a plug-in to bootstrap its connection + to the host. +*/ +typedef struct OfxHost { + /** @brief Global handle to the host. Extract relevant host properties from this. + This pointer will be valid while the binary containing the plug-in is loaded. + */ + OfxPropertySetHandle host; + + /** @brief The function which the plug-in uses to fetch suites from the host. + + \arg \c host the host the suite is being fetched from this \em must be the \e host member of the OfxHost struct containing fetchSuite. + \arg \c suiteName ASCII string labelling the host supplied API + \arg \c suiteVersion version of that suite to fetch + + Any API fetched will be valid while the binary containing the plug-in is loaded. + + Repeated calls to fetchSuite with the same parameters will return the same pointer. + + It is recommended that hosts should return the same host and suite pointers to all plugins + in the same shared lib or bundle. + + returns + - NULL if the API is unknown (either the api or the version requested), + - pointer to the relevant API if it was found + */ + const void *(*fetchSuite)(OfxPropertySetHandle host, const char *suiteName, int suiteVersion); +} OfxHost; + + +/** @brief Entry point for plug-ins + + \arg \c action ASCII c string indicating which action to take + \arg \c 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 + \arg \c inData handle that contains action specific properties + \arg \c outData handle where the plug-in should set various action specific properties + + This is how the host generally communicates with a plug-in. Entry points are used to pass messages + to various objects used within OFX. The main use is within the OfxPlugin struct. + + The exact set of actions is determined by the plug-in API that is being implemented, however all plug-ins + can perform several actions. For the list of actions consult \ref ActionsAll. + */ +typedef OfxStatus (OfxPluginEntryPoint)(const char *action, const void *handle, OfxPropertySetHandle inArgs, OfxPropertySetHandle outArgs); + +/** @brief The structure that defines a plug-in to a host. + * + * This structure is the first element in any plug-in structure + * using the OFX plug-in architecture. By examining its members + * a host can determine the API that the plug-in implements, + * the version of that API, its name and version. + * + * For details see \ref Architecture. + * + */ +typedef struct OfxPlugin { + /** Defines the type of the plug-in, this will tell the host what the plug-in does. e.g.: an image + effects plug-in would be a "OfxImageEffectPlugin" + */ + const char *pluginApi; + + /** Defines the version of the pluginApi that this plug-in implements */ + int apiVersion; + + /** String that uniquely labels the plug-in among all plug-ins that implement an API. + It need not necessarily be human sensible, however the preference is to use reverse + internet domain name of the developer, followed by a '.' then by a name that represents + the plug-in.. It must be a legal ASCII string and have no whitespace in the + name and no non printing chars. + For example "uk.co.somesoftwarehouse.myPlugin" + */ + const char *pluginIdentifier; + + /** Major version of this plug-in, this gets incremented when backwards compatibility is broken. */ + unsigned int pluginVersionMajor; + + /** Major version of this plug-in, this gets incremented when software is changed, + but does not break backwards compatibility. */ + unsigned int pluginVersionMinor; + + /** @brief Function the host uses to connect the plug-in to the host's api fetcher + + \arg \c fetchApi pointer to host's API fetcher + + Mandatory function. + + 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. + + \pre + - nothing else has been called + + \post + - the pointer suite is valid until the plug-in is unloaded + + It is recommended that hosts should return the same host and suite pointers to all plugins + in the same shared lib or bundle. + */ + void (*setHost)(OfxHost *host); + + /** @brief Main entry point for plug-ins + + Mandatory function. + + The exact set of actions is determined by the plug-in API that is being implemented, however all plug-ins + can perform several actions. For the list of actions consult \ref ActionsAll. + + Preconditions + - setHost has been called + */ + OfxPluginEntryPoint *mainEntry; +} OfxPlugin; + +/** + \defgroup ActionsAll OFX Actions + +These are the actions passed to a plug-in's 'main' function +*/ +/*@{*/ + +/** @brief + + This action is the first action passed to a plug-in after the + binary containing the plug-in has been loaded. It is there to allow a + plug-in to create any global data structures it may need and is also + when the plug-in should fetch suites from the host. + + The \ref handle, \ref inArgs and \ref outArgs arguments to the \ref mainEntry + are redundant and should be set to NULL. + + + + \pre + - The plugin's \ref OfxPlugin::setHost function has been called + + \post + This action will not be called again while the binary containing the plug-in remains loaded. + + @returns + - \ref kOfxStatOK, the action was trapped and all was well, + - \ref kOfxStatReplyDefault, the action was ignored, + - \ref kOfxStatFailed, the load action failed, no further actions will be passed to the plug-in. + Interpret if possible kOfxStatFailed as plug-in indicating it does not want to load + Do not create an entry in the host's UI for plug-in then. + Plug-in also has the option to return 0 for OfxGetNumberOfPlugins or kOfxStatFailed if host supports OfxSetHost in which case kOfxActionLoad will never be called. + - \ref kOfxStatErrFatal, fatal error in the plug-in. + */ +#define kOfxActionLoad "OfxActionLoad" + +/** @brief + + The kOfxActionDescribe is the second action passed to a plug-in. It is + where a plugin defines how it behaves and the resources it needs to + function. + + Note that the handle passed in acts as a descriptor for, rather than an + instance of the plugin. The handle is global and unique. The plug-in is + at liberty to cache the handle away for future reference until the + plug-in is unloaded. + + Most importantly, the effect must set what image effect contexts it is + capable of working in. + + This action *must* be trapped, it is not optional. + + + @param handle handle to the plug-in descriptor, cast to an \ref OfxImageEffectHandle + @param inArgs is redundant and is set to NULL + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionLoad has been called + + \post + - \ref kOfxActionDescribe will not be called again, unless it fails and + returns one of the error codes where the host is allowed to attempt + the action again + - the handle argument, being the global plug-in description handle, is + a valid handle from the end of a sucessful describe action until the + end of the \ref kOfxActionUnload action (ie: the plug-in can cache it away + without worrying about it changing between actions). + - \ref kOfxImageEffectActionDescribeInContext + will be called once for each context that the host and plug-in + mutually support. If a plug-in does not report to support any context supported by host, + host should not enable the plug-in. + + @returns + - \ref kOfxStatOK, the action was trapped and all was well + - \ref kOfxStatErrMissingHostFeature, in which the plugin will be unloaded + and ignored, plugin may post message + - \ref kOfxStatErrMemory, in which case describe may be called again after a + memory purge + - \ref kOfxStatFailed, something wrong, but no error code appropriate, + plugin to post message + - \ref kOfxStatErrFatal + + */ +#define kOfxActionDescribe "OfxActionDescribe" + +/** @brief + + This action is the last action passed to the plug-in before the + binary containing the plug-in is unloaded. It is there to allow a + plug-in to destroy any global data structures it may have created. + + The handle, inArgs and outArgs arguments to the main entry + are redundant and should be set to NULL. + + \pre + - the \ref kOfxActionLoad action has been called + - all instances of a plugin have been destroyed + + \post + - No other actions will be called. + + @returns + - \ref kOfxStatOK, the action was trapped all was well + - \ref kOfxStatReplyDefault, the action was ignored + - \ref kOfxStatErrFatal, in which case we the program will be forced to quit + + */ +#define kOfxActionUnload "OfxActionUnload" + +/** @brief + + This action is an action that may be passed to a plug-in + instance from time to time in low memory situations. Instances recieving + this action should destroy any data structures they may have and release + the associated memory, they can later reconstruct this from the effect's + parameter set and associated information. + + For Image Effects, it is generally a bad idea to call this after each + render, but rather it should be called after + \ref kOfxImageEffectActionEndSequenceRender + Some effects, typically those flagged with the + \ref kOfxImageEffectInstancePropSequentialRender + property, may need to cache information from previously rendered frames + to function correctly, or have data structures that are expensive to + reconstruct at each frame (eg: a particle system). Ideally, such effect + should free such structures during the + \ref kOfxImageEffectActionEndSequenceRender action. + + @param handle handle to the plug-in instance, cast to an \ref OfxImageEffectHandle + @param inArgs is redundant and is set to NULL + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance has been called on the instance handle, + + @returns + - \ref kOfxStatOK, the action was trapped and all was well + - \ref kOfxStatReplyDefault, the action was ignored + - \ref kOfxStatErrFatal, + - \ref kOfxStatFailed, something went wrong, but no error code appropriate, + the plugin should to post a message + */ +#define kOfxActionPurgeCaches "OfxActionPurgeCaches" + +/** @brief + + This action is called when a plugin should synchronise any private data + structures to its parameter set. This generally occurs when an effect is + about to be saved or copied, but it could occur in other situations as + well. + + @param handle handle to the plug-in instance, cast to an \ref OfxImageEffectHandle + @param inArgs is redundant and is set to NULL + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance has been called on the instance handle, + + \post + - Any private state data can be reconstructed from the parameter set, + + @returns + - \ref kOfxStatOK, the action was trapped and all was well + - \ref kOfxStatReplyDefault, the action was ignored + - \ref kOfxStatErrFatal, + - \ref kOfxStatFailed, something went wrong, but no error code appropriate, + the plugin should to post a message + */ +#define kOfxActionSyncPrivateData "OfxActionSyncPrivateData" + +/** @brief + + This action is the first action passed to a plug-in's + instance after its creation. It is there to allow a plugin to create any + per-instance data structures it may need. + + @param handle handle to the plug-in instance, cast to an \ref OfxImageEffectHandle + @param inArgs is redundant and is set to NULL + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionDescribe has been called + - the instance is fully constructed, with all objects requested in the + describe actions (eg, parameters and clips) have been constructed and + have had their initial values set. This means that if the values are + being loaded from an old setup, that load should have taken place + before the create instance action is called. + + \post + - the instance pointer will be valid until the + \ref kOfxActionDestroyInstance + action is passed to the plug-in with the same instance handle + + @returns + - \ref kOfxStatOK, the action was trapped and all was well + - \ref kOfxStatReplyDefault, the action was ignored, but all was well anyway + - \ref kOfxStatErrFatal + - \ref kOfxStatErrMemory, in which case this may be called again after a + memory purge + - \ref kOfxStatFailed, something went wrong, but no error code appropriate, + the plugin should to post a message if possible and the host should + destroy the instanace handle and not attempt to proceed further + */ +#define kOfxActionCreateInstance "OfxActionCreateInstance" + +/** @brief + + + This action is the last passed to a plug-in's instance before its + destruction. It is there to allow a plugin to destroy any per-instance + data structures it may have created. + + @param handle + handle to the plug-in instance, cast to an \ref OfxImageEffectHandle + @param inArgs is redundant and is set to NULL + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance + has been called on the handle, + - the instance has not had any of its members destroyed yet, + + \post + - the instance pointer is no longer valid and any operation on it will + be undefined + + @returns + To some extent, what is returned is moot, a bit like throwing an + exception in a C++ destructor, so the host should continue destruction + of the instance regardless. + + - \ref kOfxStatOK, the action was trapped and all was well, + - \ref kOfxStatReplyDefault, the action was ignored as the effect had nothing + to do, + - \ref kOfxStatErrFatal, + - \ref kOfxStatFailed, something went wrong, but no error code appropriate, + the plugin should to post a message. + + */ +#define kOfxActionDestroyInstance "OfxActionDestroyInstance" + +/** @brief + + This action signals that something has changed in a plugin's instance, + either by user action, the host or the plugin itself. All change actions + are bracketed by a pair of \ref kOfxActionBeginInstanceChanged and + \ref kOfxActionEndInstanceChanged actions. The ``inArgs`` property set is + used to determine what was the thing inside the instance that was + changed. + + @param handle handle to the plug-in instance, cast to an \ref OfxImageEffectHandle + @param inArgs has the following properties + - \ref kOfxPropType The type of the thing that changed which will be one of.. + + - \ref kOfxTypeParameter Indicating a parameter's value has changed + in some way + - \ref kOfxTypeClip A clip to an image effect has changed in some + way (for Image Effect Plugins only) + + - \ref kOfxPropName the name of the thing that was changed in the instance + - \ref kOfxPropChangeReason what triggered the change, which will be one of... + + - \ref kOfxChangeUserEdited - the user or host changed the instance + somehow and caused a change to something, this includes + undo/redos, resets and loading values from files or presets, + + - \ref kOfxChangePluginEdited - the plugin itself has changed the + value of the instance in some action + - \ref kOfxChangeTime - the time has changed and this has affected the + value of the object because it varies over time + + - \ref kOfxPropTime + - the effect time at which the chang occured (for Image Effect Plugins only) + - \ref kOfxImageEffectPropRenderScale + - the render scale currently being applied to any image fetched + from a clip (for Image Effect Plugins only) + + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance has been called on the instance handle, + - \ref kOfxActionBeginInstanceChanged has been called on the instance + handle. + + \post + - \ref kOfxActionEndInstanceChanged will be called on the instance handle. + + @returns + - \ref kOfxStatOK, the action was trapped and all was well + - \ref kOfxStatReplyDefault, the action was ignored + - \ref kOfxStatErrFatal, + - \ref kOfxStatFailed, something went wrong, but no error code appropriate, + the plugin should to post a message + + */ +#define kOfxActionInstanceChanged "OfxActionInstanceChanged" + +/** @brief + + The \ref kOfxActionBeginInstanceChanged and \ref kOfxActionEndInstanceChanged actions + are used to bracket all \ref kOfxActionInstanceChanged actions, whether a + single change or multiple changes. Some changes to a plugin instance can + be grouped logically (eg: a 'reset all' button resetting all the + instance's parameters), the begin/end instance changed actions allow a + plugin to respond appropriately to a large set of changes. For example, + a plugin that maintains a complex internal state can delay any changes + to that state until all parameter changes have completed. + + @param handle + handle to the plug-in instance, cast to an \ref OfxImageEffectHandle + @param inArgs has the following properties + - \ref kOfxPropChangeReason what triggered the change, which will be one of... + - \ref kOfxChangeUserEdited - the user or host changed the instance + somehow and caused a change to something, this includes + undo/redos, resets and loading values from files or presets, + - \ref kOfxChangePluginEdited - the plugin itself has changed the + value of the instance in some action + - \ref kOfxChangeTime - the time has changed and this has affected the + value of the object because it varies over time + + @param outArgs is redundant and is set to NULL + + \post + - For \ref kOfxActionBeginInstanceChanged , \ref kOfxActionCreateInstance has been called on the instance handle. + - For \ref kOfxActionEndInstanceChanged , \ref kOfxActionBeginInstanceChanged has been called on the instance handle. + - \ref kOfxActionCreateInstance has been called on the instance handle. + + \post + - For \ref kOfxActionBeginInstanceChanged, \ref kOfxActionInstanceChanged will be called at least once on the instance handle. + - \ref kOfxActionEndInstanceChanged will be called on the instance handle. + + @returns + - \ref kOfxStatOK, the action was trapped and all was well + - \ref kOfxStatReplyDefault, the action was ignored + - \ref kOfxStatErrFatal, + - \ref kOfxStatFailed, something went wrong, but no error code appropriate, + the plugin should to post a message +*/ +#define kOfxActionBeginInstanceChanged "OfxActionBeginInstanceChanged" + +/** @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*/ +#define kOfxActionEndInstanceChanged "OfxActionEndInstanceChanged" + +/** @brief + + This is called when an instance is *first* actively edited by a user, + ie: and interface is open and parameter values and input clips can be + modified. It is there so that effects can create private user interface + structures when necassary. Note that some hosts can have multiple + editors open on the same effect instance simulateously. + + + @param handle handle to the plug-in instance, cast to an \ref OfxImageEffectHandle + @param inArgs is redundant and is set to NULL + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance has been called on the instance handle, + + \post + - \ref kOfxActionEndInstanceEdit will be called when the last editor is + closed on the instance + + @returns + - \ref kOfxStatOK, the action was trapped and all was well + - \ref kOfxStatReplyDefault, the action was ignored + - \ref kOfxStatErrFatal, + - \ref kOfxStatFailed, something went wrong, but no error code appropriate, + the plugin should to post a message + */ +#define kOfxActionBeginInstanceEdit "OfxActionBeginInstanceEdit" + +/** @brief + + This is called when the *last* user interface on an instance closed. It + is there so that effects can destroy private user interface structures + when necassary. Note that some hosts can have multiple editors open on + the same effect instance simulateously, this will only be called when + the last of those editors are closed. + + @param handle handle to the plug-in instance, cast to an \ref OfxImageEffectHandle + @param inArgs is redundant and is set to NULL + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionBeginInstanceEdit has been called on the instance handle, + + \post + - no user interface is open on the instance + + @returns + - \ref kOfxStatOK, the action was trapped and all was well + - \ref kOfxStatReplyDefault, the action was ignored + - \ref kOfxStatErrFatal, + - \ref kOfxStatFailed, something went wrong, but no error code appropriate, + the plugin should to post a message + */ +#define kOfxActionEndInstanceEdit "OfxActionEndInstanceEdit" + +/*@}*/ + +/** @brief Returns the 'nth' plug-in implemented inside a binary + * + * Returns a pointer to the 'nth' plug-in implemented in the binary. A function of this type + * must be implemented in and exported from each plug-in binary. + */ +OfxExport OfxPlugin *OfxGetPlugin(int nth); + +/** @brief Defines the number of plug-ins implemented inside a binary + * + * A host calls this to determine how many plug-ins there are inside + * a binary it has loaded. A function of this type + * must be implemented in and exported from each plug-in binary. + */ +OfxExport int OfxGetNumberOfPlugins(void); + +/** @brief First thing host should call +* +* This host call, added in 2020, is not specified in earlier implementation of the API. +* Therefore host must check if the plugin implemented it and not assume symbol exists. +* The order of calls is then: 1) OfxSetHost, 2) OfxGetNumberOfPlugins, 3) OfxGetPlugin +* The host pointer is only assumed valid until OfxGetPlugin where it might get reset. +* Plug-in can return kOfxStatFailed to indicate it has nothing to do here, it's not for this Host and it should be skipped silently. +*/ + +OfxExport OfxStatus OfxSetHost(const OfxHost *host); + +/** + \defgroup PropertiesAll Ofx Properties + +These strings are used to identify properties within OFX, they are broken up by the host suite or API they relate to. +*/ +/*@{*/ + +/** + \defgroup PropertiesGeneral General Properties + +These properties are general properties and apply to may objects across OFX +*/ +/*@{*/ + +/** @brief Property on the host descriptor, saying what API version of the API is being implemented + + - Type - int X N + - Property Set - host descriptor. + +This is a version string that will specify which version of the API is being implemented by a host. It +can have multiple values. For example "1.0", "1.2.4" etc..... + +If this is not present, it is safe to assume that the version of the API is "1.0". +*/ +#define kOfxPropAPIVersion "OfxPropAPIVersion" + +/** @brief General property used to get/set the time of something. + + - Type - double X 1 + - Default - 0, if a setable property + - Property Set - commonly used as an argument to actions, input and output. +*/ +#define kOfxPropTime "OfxPropTime" + +/** @brief Indicates if a host is actively editing the effect with some GUI. + + - Type - int X 1 + - Property Set - effect instance (read only) + - Valid Values - 0 or 1 + +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. + +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. +*/ +#define kOfxPropIsInteractive "OfxPropIsInteractive" + +/** @brief The file path to the plugin. + + - Type - C string X 1 + - Property Set - effect descriptor (read only) + +This is a string that indicates the file path where the plug-in was found by the host. The path is in the native +path format for the host OS (eg: UNIX directory separators are forward slashes, Windows ones are backslashes). + +The path is to the bundle location, see \ref InstallationLocation. +eg: '/usr/OFX/Plugins/AcmePlugins/AcmeFantasticPlugin.ofx.bundle' +*/ +#define kOfxPluginPropFilePath "OfxPluginPropFilePath" + +/** @brief A private data pointer that the plug-in can store its own data behind. + + - Type - pointer X 1 + - Property Set - plugin instance (read/write), + - Default - NULL + +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. +*/ +#define kOfxPropInstanceData "OfxPropInstanceData" + +/** @brief General property, used to identify the kind of an object behind a handle + + - Type - ASCII C string X 1 + - Property Set - any object handle (read only) + - Valid Values - currently this can be... + - ::kOfxTypeImageEffectHost + - ::kOfxTypeImageEffect + - ::kOfxTypeImageEffectInstance + - ::kOfxTypeParameter + - ::kOfxTypeParameterInstance + - ::kOfxTypeClip + - ::kOfxTypeImage +*/ +#define kOfxPropType "OfxPropType" + +/** @brief Unique name of an object. + + - Type - ASCII C string X 1 + - Property Set - on many objects (descriptors and instances), see \ref PropertiesByObject (read only) + +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. +*/ +#define kOfxPropName "OfxPropName" + +/** @brief Identifies a specific version of a host or plugin. + + - Type - int X N + - Property Set - host descriptor (read only), plugin descriptor (read/write) + - Default - "0" + - Valid Values - positive integers + +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. + +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). +*/ +#define kOfxPropVersion "OfxPropVersion" + +/** @brief Unique user readable version string of a plugin or host. + + - Type - string X 1 + - Property Set - host descriptor (read only), plugin descriptor (read/write) + - Default - none, the host needs to set this + - Valid Values - ASCII string + +This is purely for user feedback, a plugin or host should use ::kOfxPropVersion if they need +to check for specific versions. +*/ +#define kOfxPropVersionLabel "OfxPropVersionLabel" + +/** @brief Description of the plug-in to a user. + + - Type - string X 1 + - Property Set - plugin descriptor (read/write) and instance (read only) + - Default - "" + - Valid Values - UTF8 string + +This is a string giving a potentially verbose description of the effect. +*/ +#define kOfxPropPluginDescription "OfxPropPluginDescription" + +/** @brief User visible name of an object. + + - Type - UTF8 C string X 1 + - Property Set - on many objects (descriptors and instances), see \ref PropertiesByObject. Typically readable and writable in most cases. + - Default - the ::kOfxPropName the object was created with. + +The label is what a user sees on any interface in place of the object's name. + +Note that resetting this will also reset ::kOfxPropShortLabel and ::kOfxPropLongLabel. +*/ +#define kOfxPropLabel "OfxPropLabel" + +/** @brief If set this tells the host to use an icon instead of a label for some object in the interface. + + - Type - string X 2 + - Property Set - various descriptors in the API + - Default - "" + - Valid Values - ASCII string + +The value is a path is defined relative to the Resource folder that points to an SVG or PNG file containing the icon. + +The first dimension, if set, will the name of and SVG file, the second a PNG file. +*/ +#define kOfxPropIcon "OfxPropIcon" + +/** @brief Short user visible name of an object. + + - Type - UTF8 C string X 1 + - Property Set - on many objects (descriptors and instances), see \ref PropertiesByObject. Typically readable and writable in most cases. + - Default - initially ::kOfxPropName, but will be reset if ::kOfxPropLabel is changed. + +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. +*/ +#define kOfxPropShortLabel "OfxPropShortLabel" + +/** @brief Long user visible name of an object. + + - Type - UTF8 C string X 1 + - Property Set - on many objects (descriptors and instances), see \ref PropertiesByObject. Typically readable and writable in most cases. + - Default - initially ::kOfxPropName, but will be reset if ::kOfxPropLabel is changed. + +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. +*/ +#define kOfxPropLongLabel "OfxPropLongLabel" + +/** @brief Indicates why a plug-in changed. + + - Type - ASCII C string X 1 + - Property Set - inArgs parameter on the ::kOfxActionInstanceChanged action. + - Valid Values - this can be... + - ::kOfxChangeUserEdited - the user directly edited the instance somehow and caused a change to something, this includes undo/redos and resets + - ::kOfxChangePluginEdited - the plug-in itself has changed the value of the object in some action + - ::kOfxChangeTime - the time has changed and this has affected the value of the object because it varies over time + +Argument property for the ::kOfxActionInstanceChanged action. +*/ +#define kOfxPropChangeReason "OfxPropChangeReason" + +/** @brief A pointer to an effect instance. + + - Type - pointer X 1 + - Property Set - on an interact instance (read only) + +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, +the interact instance will have one of these so that the plug-in can connect back to the effect the GUI links to. +*/ +#define kOfxPropEffectInstance "OfxPropEffectInstance" + +/** @brief A pointer to an operating system specific application handle. + + - Type - pointer X 1 + - Property Set - host descriptor. + +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. +*/ +#define kOfxPropHostOSHandle "OfxPropHostOSHandle" + +/*@}*/ + +/*@}*/ + +/** @brief String used as a value to ::kOfxPropChangeReason to indicate a user has changed something */ +#define kOfxChangeUserEdited "OfxChangeUserEdited" + +/** @brief String used as a value to ::kOfxPropChangeReason to indicate the plug-in itself has changed something */ +#define kOfxChangePluginEdited "OfxChangePluginEdited" + +/** @brief String used as a value to ::kOfxPropChangeReason to a time varying object has changed due to a time change */ +#define kOfxChangeTime "OfxChangeTime" + +/** @brief How time is specified within the OFX API */ +typedef double OfxTime; + +/** @brief Defines one dimensional integer bounds */ +typedef struct OfxRangeI { + int min, max; +} OfxRangeI; + +/** @brief Defines one dimensional double bounds */ +typedef struct OfxRangeD { + double min, max; +} OfxRangeD; + +/** @brief Defines two dimensional integer point */ +typedef struct OfxPointI { + int x, y; +} OfxPointI; + +/** @brief Defines two dimensional double point */ +typedef struct OfxPointD { + double x, y; +} OfxPointD; + +/** @brief Used to flag infinite rects. Set minimums to this to indicate infinite + +This is effectively INT_MAX. + */ +#define kOfxFlagInfiniteMax INT_MAX + +/** @brief Used to flag infinite rects. Set minimums to this to indicate infinite. + +This is effectively INT_MIN + */ +#define kOfxFlagInfiniteMin INT_MIN + +/** @brief Defines two dimensional integer region + +Regions are x1 <= x < x2 + +Infinite regions are flagged by setting +- x1 = \ref kOfxFlagInfiniteMin +- y1 = \ref kOfxFlagInfiniteMin +- x2 = \ref kOfxFlagInfiniteMax +- y2 = \ref kOfxFlagInfiniteMax + + */ +typedef struct OfxRectI { + int x1, y1, x2, y2; +} OfxRectI; + +/** @brief Defines two dimensional double region + +Regions are x1 <= x < x2 + +Infinite regions are flagged by setting +- x1 = \ref kOfxFlagInfiniteMin +- y1 = \ref kOfxFlagInfiniteMin +- x2 = \ref kOfxFlagInfiniteMax +- y2 = \ref kOfxFlagInfiniteMax + + */ +typedef struct OfxRectD { + double x1, y1, x2, y2; +} OfxRectD; + +/** @brief String used to label unset bitdepths */ +#define kOfxBitDepthNone "OfxBitDepthNone" + +/** @brief String used to label unsigned 8 bit integer samples */ +#define kOfxBitDepthByte "OfxBitDepthByte" + +/** @brief String used to label unsigned 16 bit integer samples */ +#define kOfxBitDepthShort "OfxBitDepthShort" + +/** @brief String used to label half-float (16 bit floating point) samples + * \version Added in Version 1.4. Was in ofxOpenGLRender.h before. + */ +#define kOfxBitDepthHalf "OfxBitDepthHalf" + +/** @brief String used to label signed 32 bit floating point samples */ +#define kOfxBitDepthFloat "OfxBitDepthFloat" + +/** + \defgroup StatusCodes Status Codes + +These strings are used to identify error states within ofx, they are returned +by various host suite functions, as well as plug-in functions. The valid return codes +for each function are documented with that function. +*/ +/*@{*/ + +/** + \defgroup StatusCodesGeneral General Status Codes + +General status codes start at 1 and continue until 999 + +*/ +/*@{*/ + +/** @brief Status code indicating all was fine */ +#define kOfxStatOK 0 + +/** @brief Status error code for a failed operation. */ +#define kOfxStatFailed ((int)1) + +/** @brief Status error code for a fatal error + + Only returned in the case where the plug-in or host cannot continue to function and needs to be restarted. + */ +#define kOfxStatErrFatal ((int)2) + +/** @brief Status error code for an operation on or request for an unknown object */ +#define kOfxStatErrUnknown ((int)3) + +/** @brief Status error code returned by plug-ins when they are missing host functionality, either an API or some optional functionality (eg: custom params). + + Plug-Ins returning this should post an appropriate error message stating what they are missing. + */ +#define kOfxStatErrMissingHostFeature ((int) 4) + +/** @brief Status error code for an unsupported feature/operation */ +#define kOfxStatErrUnsupported ((int) 5) + +/** @brief Status error code for an operation attempting to create something that exists */ +#define kOfxStatErrExists ((int) 6) + +/** @brief Status error code for an incorrect format */ +#define kOfxStatErrFormat ((int) 7) + +/** @brief Status error code indicating that something failed due to memory shortage */ +#define kOfxStatErrMemory ((int) 8) + +/** @brief Status error code for an operation on a bad handle */ +#define kOfxStatErrBadHandle ((int) 9) + +/** @brief Status error code indicating that a given index was invalid or unavailable */ +#define kOfxStatErrBadIndex ((int)10) + +/** @brief Status error code indicating that something failed due an illegal value */ +#define kOfxStatErrValue ((int) 11) + +/** @brief OfxStatus returned indicating a 'yes' */ +#define kOfxStatReplyYes ((int) 12) + +/** @brief OfxStatus returned indicating a 'no' */ +#define kOfxStatReplyNo ((int) 13) + +/** @brief OfxStatus returned indicating that a default action should be performed */ +#define kOfxStatReplyDefault ((int) 14) + +/*@}*/ + +/*@}*/ + +#ifdef __cplusplus +} +#endif + +/** @mainpage OFX : Open Plug-Ins For Special Effects + +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). +A more complete reference manual is https://openfx.readthedocs.io . + +*/ + +#endif diff --git a/src/modules/openfx/ofxDialog.h b/src/modules/openfx/ofxDialog.h new file mode 100644 index 000000000..5296080f4 --- /dev/null +++ b/src/modules/openfx/ofxDialog.h @@ -0,0 +1,76 @@ + +#ifndef _ofxDialog_h_ +#define _ofxDialog_h_ + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + +#include "ofxCore.h" +#include "ofxProperty.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** @file ofxDialog.h + +This file contains an optional suite which should be used to popup a native OS dialog +from a host parameter changed action. + +When a host uses a fullscreen window and is running the OFX plugins in another thread +it can lead to a lot of conflicts if that plugin will try to open its own window. + +This suite will provide the functionality for a plugin to request running its dialog +in the UI thread, and informing the host it will do this so it can take the appropriate +actions needed. (Like lowering its priority etc..) +*/ + +/** @brief The name of the Dialog suite, used to fetch from a host via + OfxHost::fetchSuite + */ +#define kOfxDialogSuite "OfxDialogSuite" + +/** @brief Action called after a dialog has requested a 'Dialog' + The arguments to the action are: + \arg \c user_data Pointer which was provided when the plugin requested the Dialog + + When the plugin receives this action it is safe to popup a dialog. + It runs in the host's UI thread, which may differ from the main OFX processing thread. + Plugin should return from this action when all Dialog interactions are done. + At that point the host will continue again. + The host will not send any other messages asynchronous to this one. +*/ +#define kOfxActionDialog "OfxActionDialog" + +typedef struct OfxDialogSuiteV1 +{ + /** @brief Request the host to send a kOfxActionDialog to the plugin from its UI thread. + \pre + - user_data: A pointer to any user data + \post + @returns + - ::kOfxStatOK - The host has queued the request and will send an 'OfxActionDialog' + - ::kOfxStatFailed - The host has no provisio for this or can not deal with it currently. + */ + OfxStatus (*RequestDialog)( void *user_data ); + + /** @brief Inform the host of redraw event so it can redraw itself + If the host runs fullscreen in OpenGL, it would otherwise not receive +redraw event when a dialog in front would catch all events. + \pre + \post + @returns + - ::kOfxStatReplyDefault + */ + OfxStatus (*NotifyRedrawPending)( void ); +} OfxDialogSuiteV1; + + + +#ifdef __cplusplus +} +#endif + + +#endif + diff --git a/src/modules/openfx/ofxDrawSuite.h b/src/modules/openfx/ofxDrawSuite.h new file mode 100644 index 000000000..874d0719d --- /dev/null +++ b/src/modules/openfx/ofxDrawSuite.h @@ -0,0 +1,183 @@ +#ifndef _ofxDraw_h_ +#define _ofxDraw_h_ + +#include "ofxCore.h" +#include "ofxPixels.h" + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + + +#ifdef __cplusplus +extern "C" { +#endif + +/** @file ofxDrawSuite.h +API for host- and GPU API-independent drawing. +@version Added in OpenFX 1.5 +*/ + + +/** @brief the string that names the DrawSuite, passed to OfxHost::fetchSuite */ +#define kOfxDrawSuite "OfxDrawSuite" + +/** @brief Blind declaration of an OFX drawing context + */ +typedef struct OfxDrawContext *OfxDrawContextHandle; + +/** @brief The Draw Context handle + + - Type - pointer X 1 + - Property Set - read only property on the inArgs of the following actions... + - ::kOfxInteractActionDraw + */ +#define kOfxInteractPropDrawContext "OfxInteractPropDrawContext" + +/** @brief Defines valid values for OfxDrawSuiteV1::getColour */ +typedef enum OfxStandardColour +{ + kOfxStandardColourOverlayBackground, + kOfxStandardColourOverlayActive, + kOfxStandardColourOverlaySelected, + kOfxStandardColourOverlayDeselected, + kOfxStandardColourOverlayMarqueeFG, + kOfxStandardColourOverlayMarqueeBG, + kOfxStandardColourOverlayText +} OfxStandardColour; + +/** @brief Defines valid values for OfxDrawSuiteV1::setLineStipple */ +typedef enum OfxDrawLineStipplePattern +{ + kOfxDrawLineStipplePatternSolid, // ----- + kOfxDrawLineStipplePatternDot, // ..... + kOfxDrawLineStipplePatternDash, // - - - + kOfxDrawLineStipplePatternAltDash, // - - - + kOfxDrawLineStipplePatternDotDash // .-.-.- +} OfxDrawLineStipplePattern; + +/** @brief Defines valid values for OfxDrawSuiteV1::draw */ + +typedef enum OfxDrawPrimitive +{ + kOfxDrawPrimitiveLines, + kOfxDrawPrimitiveLineStrip, + kOfxDrawPrimitiveLineLoop, + kOfxDrawPrimitiveRectangle, + kOfxDrawPrimitivePolygon, + kOfxDrawPrimitiveEllipse +} OfxDrawPrimitive; + +/** @brief Defines text alignment values for OfxDrawSuiteV1::drawText */ +typedef enum OfxDrawTextAlignment +{ + kOfxDrawTextAlignmentLeft = 0x0001, + kOfxDrawTextAlignmentRight = 0x0002, + kOfxDrawTextAlignmentTop = 0x0004, + kOfxDrawTextAlignmentBottom = 0x0008, + kOfxDrawTextAlignmentBaseline = 0x0010, + kOfxDrawTextAlignmentCenterH = (kOfxDrawTextAlignmentLeft | kOfxDrawTextAlignmentRight), + kOfxDrawTextAlignmentCenterV = (kOfxDrawTextAlignmentTop | kOfxDrawTextAlignmentBaseline) +} OfxDrawTextAlignment; + +/** @brief OFX suite that allows an effect to draw to a host-defined display context. + +*/ +typedef struct OfxDrawSuiteV1 { + /** @brief Retrieves the host's desired draw colour for + + \arg \c context draw context + \arg \c std_colour desired colour type + \arg \c colour returned RGBA colour + + @returns + - ::kOfxStatOK - the colour was returned + - ::kOfxStatErrValue - std_colour was invalid + - ::kOfxStatFailed - failure, e.g. if function is called outside kOfxInteractActionDraw + */ + OfxStatus (*getColour)(OfxDrawContextHandle context, OfxStandardColour std_colour, OfxRGBAColourF *colour); + + /** @brief Sets the colour for future drawing operations (lines, filled shapes and text) + + \arg \c context draw context + \arg \c colour RGBA colour + + The host should use "over" compositing when using a non-opaque colour. + + @returns + - ::kOfxStatOK - the colour was changed + - ::kOfxStatFailed - failure, e.g. if function is called outside kOfxInteractActionDraw + */ + OfxStatus (*setColour)(OfxDrawContextHandle context, const OfxRGBAColourF *colour); + + /** @brief Sets the line width for future line drawing operations + + \arg \c context draw context + \arg \c width line width + + Use width 0 for a single pixel line or non-zero for a smooth line of the desired width + + The host should adjust for screen density. + + @returns + - ::kOfxStatOK - the width was changed + - ::kOfxStatFailed - failure, e.g. if function is called outside kOfxInteractActionDraw + */ + OfxStatus (*setLineWidth)(OfxDrawContextHandle context, float width); + + /** @brief Sets the stipple pattern for future line drawing operations + + \arg \c context draw context + \arg \c pattern desired stipple pattern + + @returns + - ::kOfxStatOK - the pattern was changed + - ::kOfxStatErrValue - pattern was not valid + - ::kOfxStatFailed - failure, e.g. if function is called outside kOfxInteractActionDraw + */ + OfxStatus (*setLineStipple)(OfxDrawContextHandle context, OfxDrawLineStipplePattern pattern); + + /** @brief Draws a primitive of the desired type + + \arg \c context draw context + \arg \c primitive desired primitive + \arg \c points array of points in the primitive + \arg \c point_count number of points in the array + + kOfxDrawPrimitiveLines - like GL_LINES, n points draws n/2 separated lines + kOfxDrawPrimitiveLineStrip - like GL_LINE_STRIP, n points draws n-1 connected lines + kOfxDrawPrimitiveLineLoop - like GL_LINE_LOOP, n points draws n connected lines + kOfxDrawPrimitiveRectangle - draws an axis-aligned filled rectangle defined by 2 opposite corner points + kOfxDrawPrimitivePolygon - like GL_POLYGON, draws a filled n-sided polygon + kOfxDrawPrimitiveEllipse - draws a axis-aligned elliptical line (not filled) within the rectangle defined by 2 opposite corner points + + @returns + - ::kOfxStatOK - the draw was completed + - ::kOfxStatErrValue - invalid primitive, or point_count not valid for primitive + - ::kOfxStatFailed - failure, e.g. if function is called outside kOfxInteractActionDraw + */ + OfxStatus (*draw)(OfxDrawContextHandle context, OfxDrawPrimitive primitive, const OfxPointD *points, int point_count); + + + /** @brief Draws text at the specified position + + \arg \c context draw context + \arg \c text text to draw (UTF-8 encoded) + \arg \c pos position at which to align the text + \arg \c alignment text alignment flags (see kOfxDrawTextAlignment*) + + The text font face and size are determined by the host. + + @returns + - ::kOfxStatOK - the text was drawn + - ::kOfxStatErrValue - text or pos were not defined + - ::kOfxStatFailed - failure, e.g. if function is called outside kOfxInteractActionDraw + */ + OfxStatus (*drawText)(OfxDrawContextHandle context, const char *text, const OfxPointD *pos, int alignment); + +} OfxDrawSuiteV1; + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/src/modules/openfx/ofxGPURender.h b/src/modules/openfx/ofxGPURender.h new file mode 100644 index 000000000..1fc21125e --- /dev/null +++ b/src/modules/openfx/ofxGPURender.h @@ -0,0 +1,840 @@ +#pragma once +#ifndef __OFXGPURENDER_H__ +#define __OFXGPURENDER_H__ + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + +/** @file ofxGPURender.h + + This file contains an optional suite for performing GPU-accelerated + rendering of OpenFX Image Effect Plug-ins. For details see + \ref ofxGPURender. + + It allows hosts and plug-ins to support OpenGL, OpenCL, CUDA, and Metal. + Additional GPU APIs, such a Vulkan, could use similar techniques. +*/ + +#include "ofxImageEffect.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** @defgroup OpenGLRenderSuite OpenGL Render Suite + * @{ + */ + +/** @brief The name of the OpenGL render suite, used to fetch from a host +via OfxHost::fetchSuite +*/ +#define kOfxOpenGLRenderSuite "OfxImageEffectOpenGLRenderSuite" +//#define kOfxOpenGLRenderSuite_ext "OfxImageEffectOpenGLRenderSuite_ext" + + +#ifndef kOfxBitDepthHalf +/** @brief String used to label the OpenGL half float (16 bit floating +point) sample format */ + #define kOfxBitDepthHalf "OfxBitDepthHalf" +#endif + +/** @brief Indicates whether a host or plug-in can support OpenGL accelerated +rendering + + - Type - C string X 1 + - Property Set - plug-in descriptor (read/write), host descriptor (read +only) - plug-in instance change (read/write) + - Default - "false" for a plug-in + - Valid Values - This must be one of + - "false" - in which case the host or plug-in does not support OpenGL + accelerated rendering + - "true" - which means a host or plug-in can support OpenGL accelerated + rendering, in the case of plug-ins this also means that it + is capable of CPU based rendering in the absence of a GPU + - "needed" - only for plug-ins, this means that an plug-in has to have + OpenGL support, without which it cannot work. + +V1.4: It is now expected from host reporting v1.4 that the plug-in can during instance change switch from true to false and false to true. + +*/ +#define kOfxImageEffectPropOpenGLRenderSupported "OfxImageEffectPropOpenGLRenderSupported" + + +/** @brief Indicates the bit depths supported by a plug-in during OpenGL renders. + + This is analogous to ::kOfxImageEffectPropSupportedPixelDepths. When a + plug-in sets this property, the host will try to provide buffers/textures + in one of the supported formats. Additionally, the target buffers where + the plug-in renders to will be set to one of the supported formats. + + Unlike ::kOfxImageEffectPropSupportedPixelDepths, this property is + optional. Shader-based effects might not really care about any + format specifics when using OpenGL textures, so they can leave this unset + and allow the host the decide the format. + + + - Type - string X N + - Property Set - plug-in descriptor (read only) + - Default - none set + - Valid Values - This must be one of + - ::kOfxBitDepthNone (implying a clip is unconnected, not valid for an + image) + - ::kOfxBitDepthByte + - ::kOfxBitDepthShort + - ::kOfxBitDepthHalf + - ::kOfxBitDepthFloat +*/ +#define kOfxOpenGLPropPixelDepth "OfxOpenGLPropPixelDepth" + + +/** @brief Indicates that a plug-in SHOULD use OpenGL acceleration in +the current action + + When a plug-in and host have established they can both use OpenGL renders + then when this property has been set the host expects the plug-in to render + its result into the buffer it has setup before calling the render. The + plug-in can then also safely use the 'OfxImageEffectOpenGLRenderSuite' + + - Type - int X 1 + - Property Set - inArgs property set of the following actions... + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionEndSequenceRender + - Valid Values + - 0 indicates that the plug-in cannot use the OpenGL suite + - 1 indicates that the plug-in should render into the texture, + and may use the OpenGL suite functions. + +\note Once this property is set, the host and plug-in have agreed to +use OpenGL, so the effect SHOULD access all its images through the +OpenGL suite. + +v1.4: kOfxImageEffectPropOpenGLEnabled should probably be checked in Instance Changed prior to try to read image via clipLoadTexture + +*/ +#define kOfxImageEffectPropOpenGLEnabled "OfxImageEffectPropOpenGLEnabled" + + +/** @brief Indicates the texture index of an image turned into an OpenGL +texture by the host + + - Type - int X 1 + - Property Set - texture handle returned by +` OfxImageEffectOpenGLRenderSuiteV1::clipLoadTexture (read only) + + This value should be cast to a GLuint and used as the texture index when + performing OpenGL texture operations. + + The property set of the following actions should contain this property: + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionEndSequenceRender +*/ +#define kOfxImageEffectPropOpenGLTextureIndex "OfxImageEffectPropOpenGLTextureIndex" + + +/** @brief Indicates the texture target enumerator of an image turned into + an OpenGL texture by the host + + - Type - int X 1 + - Property Set - texture handle returned by + OfxImageEffectOpenGLRenderSuiteV1::clipLoadTexture (read only) + This value should be cast to a GLenum and used as the texture target + when performing OpenGL texture operations. + + The property set of the following actions should contain this property: + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionEndSequenceRender +*/ +#define kOfxImageEffectPropOpenGLTextureTarget "OfxImageEffectPropOpenGLTextureTarget" + + +/** @name StatusReturnValues +OfxStatus returns indicating that a OpenGL render error has occurred: + + - If a plug-in returns ::kOfxStatGLRenderFailed, the host should retry the + render with OpenGL rendering disabled. + + - If a plug-in returns ::kOfxStatGLOutOfMemory, the host may choose to free + resources on the GPU and retry the OpenGL render, rather than immediately + falling back to CPU rendering. + */ +/** + * @{ + */ +/** @brief GPU render ran out of memory */ +#define kOfxStatGPUOutOfMemory ((int) 1001) +/** @brief OpenGL render ran out of memory (same as ``kOfxStatGPUOutOfMemory``) */ +#define kOfxStatGLOutOfMemory ((int) 1001) +/** @brief GPU render failed in a non-memory-related way */ +#define kOfxStatGPURenderFailed ((int) 1002) +/** @brief OpenGL render failed in a non-memory-related way (same as ``kOfxStatGPURenderFailed``) */ +#define kOfxStatGLRenderFailed ((int) 1002) /* for backward compatibility */ +/** @} */ + +/** @brief OFX suite that provides image to texture conversion for OpenGL + processing + */ +typedef struct OfxImageEffectOpenGLRenderSuiteV1 +{ + /** @brief loads an image from an OFX clip as a texture into OpenGL + + \arg \c clip clip to load the image from + \arg \c time effect time to load the image from + \arg \c format requested texture format (As in + none,byte,word,half,float, etc..) + When set to NULL, the host decides the format based on the + plug-in's ::kOfxOpenGLPropPixelDepth setting. + \arg \c region region of the image to load (optional, set to NULL to + get a 'default' region) + this is in the \ref CanonicalCoordinates. + \arg \c textureHandle property set containing information about the + texture + + An image is fetched from a clip at the indicated time for the given region + and loaded into an OpenGL texture. When a specific format is requested, the + host ensures it gives the requested format. + When the clip specified is the "Output" clip, the format is ignored and + the host must bind the resulting texture as the current color buffer + (render target). This may also be done prior to calling the + ::kOfxImageEffectActionRender action. + If the \em region parameter is set to non-NULL, then it will be clipped to + the clip's Region of Definition for the given time. + The returned image will be \em at \em least as big as this region. + If the region parameter is not set or is NULL, then the region fetched will be at + least the Region of Interest the effect has previously specified, clipped to + the clip's Region of Definition. + Information about the texture, including the texture index, is returned in + the \em textureHandle argument. + The properties on this handle will be... + - ::kOfxImageEffectPropOpenGLTextureIndex + - ::kOfxImageEffectPropOpenGLTextureTarget + - ::kOfxImageEffectPropPixelDepth + - ::kOfxImageEffectPropComponents + - ::kOfxImageEffectPropPreMultiplication + - ::kOfxImageEffectPropRenderScale + - ::kOfxImagePropPixelAspectRatio + - ::kOfxImagePropBounds + - ::kOfxImagePropRegionOfDefinition + - ::kOfxImagePropRowBytes + - ::kOfxImagePropField + - ::kOfxImagePropUniqueIdentifier + + With the exception of the OpenGL specifics, these properties are the same + as the properties in an image handle returned by clipGetImage in the image + effect suite. +\pre + - clip was returned by clipGetHandle + - Format property in the texture handle + +\post + - texture handle to be disposed of by clipFreeTexture before the action +returns + - when the clip specified is the "Output" clip, the format is ignored and + the host must bind the resulting texture as the current color buffer + (render target). + This may also be done prior to calling the render action. + +@returns + - ::kOfxStatOK - the image was successfully fetched and returned + in the handle, + - ::kOfxStatFailed - the image could not be fetched because it does + not exist in the clip at the indicated + time and/or region, the plug-in should continue + operation, but assume the image was black and + transparent. + - ::kOfxStatErrBadHandle - the clip handle was invalid, + - ::kOfxStatErrMemory - not enough OpenGL memory was available for the + effect to load the texture. + The plug-in should abort the GL render and + return ::kOfxStatErrMemory, after which the host can + decide to retry the operation with CPU based processing. + +\note + - this is the OpenGL equivalent of clipGetImage from OfxImageEffectSuiteV1 + + +*/ + + OfxStatus (*clipLoadTexture)(OfxImageClipHandle clip, + OfxTime time, + const char *format, + const OfxRectD *region, + OfxPropertySetHandle *textureHandle); + + /** @brief Releases the texture handle previously returned by +clipLoadTexture + + For input clips, this also deletes the texture from OpenGL. + This should also be called on the output clip; for the Output + clip, it just releases the handle but does not delete the + texture (since the host will need to read it). + + \pre + - textureHandle was returned by clipGetImage + + \post + - all operations on textureHandle will be invalid, and the OpenGL texture + it referred to has been deleted (for source clips) + + @returns + - ::kOfxStatOK - the image was successfully fetched and returned in the + handle, + - ::kOfxStatFailed - general failure for some reason, + - ::kOfxStatErrBadHandle - the image handle was invalid, +*/ + OfxStatus (*clipFreeTexture)(OfxPropertySetHandle textureHandle); + + + /** @brief Request the host to minimize its GPU resource load + + When a plug-in fails to allocate GPU resources, it can call this function to + request the host to flush its GPU resources if it holds any. + After the function the plug-in can try again to allocate resources which then + might succeed if the host actually has released anything. + + \pre + \post + - No changes to the plug-in GL state should have been made. + + @returns + - ::kOfxStatOK - the host has actually released some +resources, + - ::kOfxStatReplyDefault - nothing the host could do.. + */ + OfxStatus (*flushResources)( ); + +} OfxImageEffectOpenGLRenderSuiteV1; + + +/** @brief Action called when an effect has just been attached to an OpenGL +context. + +The purpose of this action is to allow a plug-in to set up any data it may need +to do OpenGL rendering in an instance. For example... + - allocate a lookup table on a GPU, + - create an OpenCL or CUDA context that is bound to the host's OpenGL + context so it can share buffers. + +The plug-in will be responsible for deallocating any such shared resource in the +\ref ::kOfxActionOpenGLContextDetached action. + +A host cannot call ::kOfxActionOpenGLContextAttached on the same instance +without an intervening ::kOfxActionOpenGLContextDetached. A host can have a +plug-in swap OpenGL contexts by issuing a attach/detach for the first context +then another attach for the next context. + +The arguments to the action are... + \arg \c handle handle to the plug-in instance, cast to an + \ref OfxImageEffectHandle + \arg \c inArgs is redundant and set to NULL + \arg \c outArgs is redundant and set to NULL + +A plug-in can return... + - ::kOfxStatOK, the action was trapped and all was well + - ::kOfxStatReplyDefault, the action was ignored, but all was well anyway + - ::kOfxStatErrMemory, in which case this may be called again after a memory + purge + - ::kOfxStatFailed, something went wrong, but no error code appropriate, + the plug-in should to post a message if possible and the host should not + attempt to run the plug-in in OpenGL render mode. +*/ +#define kOfxActionOpenGLContextAttached "OfxActionOpenGLContextAttached" + +/** @brief Action called when an effect is about to be detached from an +OpenGL context + +The purpose of this action is to allow a plug-in to deallocate any resource +allocated in \ref ::kOfxActionOpenGLContextAttached just before the host +decouples a plug-in from an OpenGL context. +The host must call this with the same OpenGL context active as it +called with the corresponding ::kOfxActionOpenGLContextAttached. + +The arguments to the action are... + \arg \c handle handle to the plug-in instance, cast to an + \ref OfxImageEffectHandle + \arg \c inArgs is redundant and set to NULL + \arg \c outArgs is redundant and set to NULL + +A plug-in can return... + - ::kOfxStatOK, the action was trapped and all was well + - ::kOfxStatReplyDefault, the action was ignored, but all was well anyway + - ::kOfxStatErrMemory, in which case this may be called again after a memory + purge + - ::kOfxStatFailed, something went wrong, but no error code appropriate, + the plug-in should to post a message if possible and the host should not + attempt to run the plug-in in OpenGL render mode. +*/ +#define kOfxActionOpenGLContextDetached "kOfxActionOpenGLContextDetached" + + +/** @page ofxOpenGLRender OpenGL Acceleration of Rendering + +@section ofxOpenGLRenderIntro Introduction + +The OfxOpenGLRenderSuite allows image effects to use OpenGL commands +(hopefully backed by a GPU) to accelerate rendering +of their outputs. The basic scheme is simple.... + - An effect indicates it wants to use OpenGL acceleration by setting the + ::kOfxImageEffectPropOpenGLRenderSupported flag on its descriptor + - A host indicates it supports OpenGL acceleration by setting + ::kOfxImageEffectPropOpenGLRenderSupported on its descriptor + - In an effect's ::kOfxImageEffectActionGetClipPreferences action, an + effect indicates what clips it will be loading images from onto the GPU's + memory during an effect's ::kOfxImageEffectActionRender action. + +@section ofxOpenGLRenderHouseKeeping OpenGL House Keeping + +If a host supports OpenGL rendering then it flags this with the string +property ::kOfxImageEffectPropOpenGLRenderSupported on its descriptor property +set. Effects that cannot run without OpenGL support should examine this in +::kOfxActionDescribe action and return a ::kOfxStatErrMissingHostFeature +status flag if it is not set to "true". + +Effects flag to a host that they support OpenGL rendering by setting the +string property ::kOfxImageEffectPropOpenGLRenderSupported on their effect +descriptor during the ::kOfxActionDescribe action. Effects can work in three +ways.... + - purely on CPUs without any OpenGL support at all, in which case they + should set ::kOfxImageEffectPropOpenGLRenderSupported to be "false" (the + default), + - on CPUs but with optional OpenGL support, in which case they should set + ::kOfxImageEffectPropOpenGLRenderSupported to be "true", + - only with OpenGL support, in which case they should set + ::kOfxImageEffectPropOpenGLRenderSupported to be "needed". + +Hosts can examine this flag and respond to it appropriately. + +Effects can use OpenGL accelerated rendering during the following +action... + - ::kOfxImageEffectActionRender + +If an effect has indicated that it optionally supports OpenGL acceleration, +it should check the property ::kOfxImageEffectPropOpenGLEnabled +passed as an in argument to the following actions, + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionEndSequenceRender + +If this property is set to 0, then it should not attempt to use any calls to +the OpenGL suite or OpenGL calls whilst rendering. + + +@section ofxOpenGLRenderGettingTextures Getting Images as Textures + +An effect could fetch an image into memory from a host via the standard +Image Effect suite "clipGetImage" call, then create an OpenGL +texture from that. However as several buffer copies and various other bits +of house keeping may need to happen to do this, it is more +efficient for a host to create the texture directly. + +The OfxOpenGLRenderSuiteV1::clipLoadTexture function does this. The +arguments and semantics are similar to the +OfxImageEffectSuiteV2::clipGetImage function, with a few minor changes. + +The effect is passed back a property handle describing the texture. Once the +texture is finished with, this should be disposed +of via the OfxOpenGLRenderSuiteV1::clipFreeTexture function, which will also +delete the associated OpenGL texture (for source clips). + +The returned handle has a set of properties on it, analogous to the +properties returned on the image handle by +OfxImageEffectSuiteV2::clipGetImage. These are: + - ::kOfxImageEffectPropOpenGLTextureIndex + - ::kOfxImageEffectPropOpenGLTextureTarget + - ::kOfxImageEffectPropPixelDepth + - ::kOfxImageEffectPropComponents + - ::kOfxImageEffectPropPreMultiplication + - ::kOfxImageEffectPropRenderScale + - ::kOfxImagePropPixelAspectRatio + - ::kOfxImagePropBounds + - ::kOfxImagePropRegionOfDefinition + - ::kOfxImagePropRowBytes + - ::kOfxImagePropField + - ::kOfxImagePropUniqueIdentifier + +The main difference between this and an image handle is that the +::kOfxImagePropData property is replaced by the +kOfxImageEffectPropOpenGLTextureIndex property. +This integer property should be cast to a GLuint and is the index to use for +the OpenGL texture. +Next to texture handle the texture target enumerator is given in +kOfxImageEffectPropOpenGLTextureTarget + +Note, because the image is being directly loaded into a texture by the host +it need not obey the Clip Preferences action to remap the image to the pixel +depth the effect requested. + +@section ofxOpenGLRenderOutput Render Output Directly with OpenGL + +Effects can use the graphics context as they see fit. They may be doing +several render passes with fetch back from the card to main memory +via 'render to texture' mechanisms interleaved with passes performed on the +CPU. The effect must leave output on the graphics card in the provided output +image texture buffer. + +The host will create a default OpenGL viewport that is the size of the +render window passed to the render action. The following +code snippet shows how the viewport should be rooted at the bottom left of +the output texture. + +\verbatim + // set up the OpenGL context for the render to texture + ... + + // figure the size of the render window + int dx = renderWindow.x2 - renderWindow.x1; + int dy = renderWindow.y2 - renderWindow.y2; + + // setup the output viewport + glViewport(0, 0, dx, dy); + +\endverbatim + +Prior to calling the render action the host may also choose to +bind the output texture as the current color buffer (render target), or they +may defer doing this until clipLoadTexture is called for the output clip. + +After this, it is completely up to the effect to choose what OpenGL +operations to render with, including projections and so on. + +@section ofxOpenGLRenderContext OpenGL Current Context + +The host is only required to make the OpenGL context current (e.g., +using wglMakeCurrent, for Windows) during the following actions: + + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionEndSequenceRender + - ::kOfxActionOpenGLContextAttached + - ::kOfxActionOpenGLContextDetached + +For the first 3 actions, Render through EndSequenceRender, the host is only +required to set the OpenGL context if ::kOfxImageEffectPropOpenGLEnabled is +set. In other words, a plug-in should not expect the OpenGL context to be +current for other OFX calls, such as ::kOfxImageEffectActionDescribeInContext. + +*/ + +/** @}*/ // end of OpenGLRender doc group + +/** + * @defgroup CudaRender CUDA Rendering + * @version CUDA rendering was added in version 1.5. + * + * @{ + */ +/** @brief Indicates whether a host or plug-in can support CUDA render + + - Type - string X 1 + - Property Set - plug-in descriptor (read/write), host descriptor (read only) + - Default - "false" for a plug-in + - Valid Values - This must be one of + - "false" - the host or plug-in does not support CUDA render + - "true" - the host or plug-in can support CUDA render + */ +#define kOfxImageEffectPropCudaRenderSupported "OfxImageEffectPropCudaRenderSupported" + +/** @brief Indicates that a plug-in SHOULD use CUDA render in +the current action + + If a plug-in and host have both set + kOfxImageEffectPropCudaRenderSupported="true" then the host MAY set + this property to indicate that it is passing images as CUDA memory + pointers. + + - Type - int X 1 + - Property Set - inArgs property set of the following actions... + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionEndSequenceRender + - Valid Values + - 0 indicates that the kOfxImagePropData of each image of each clip + is a CPU memory pointer. + - 1 indicates that the kOfxImagePropData of each image of each clip + is a CUDA memory pointer. +*/ +#define kOfxImageEffectPropCudaEnabled "OfxImageEffectPropCudaEnabled" + +/** @brief Indicates whether a host or plug-in can support CUDA streams + + - Type - string X 1 + - Property Set - plug-in descriptor (read/write), host descriptor (read only) + - Default - "false" for a plug-in + - Valid Values - This must be one of + - "false" - in which case the host or plug-in does not support CUDA streams + - "true" - which means a host or plug-in can support CUDA streams + +*/ +#define kOfxImageEffectPropCudaStreamSupported "OfxImageEffectPropCudaStreamSupported" + +/** @brief The CUDA stream to be used for rendering + + - Type - pointer X 1 + - Property Set - inArgs property set of the following actions... + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionEndSequenceRender + +This property will only be set if the host and plug-in both support CUDA streams. + +If set: + +- this property contains a pointer to the stream of CUDA render (cudaStream_t). + In order to use it, reinterpret_cast(pointer) is needed. + +- the plug-in SHOULD ensure that its render action enqueues any + asynchronous CUDA operations onto the supplied queue. + +- the plug-in SHOULD NOT wait for final asynchronous operations to + complete before returning from the render action, and SHOULD NOT + call cudaDeviceSynchronize() at any time. + +If not set: + +- the plug-in SHOULD ensure that any asynchronous operations it + enqueues have completed before returning from the render action. +*/ +#define kOfxImageEffectPropCudaStream "OfxImageEffectPropCudaStream" + +/** @}*/ // end CudaRender doc group + +/** + * @defgroup MetalRender Apple Metal Rendering + * @version Metal rendering was added in version 1.5. + * @{ + */ +/** @brief Indicates whether a host or plug-in can support Metal render + + - Type - string X 1 + - Property Set - plug-in descriptor (read/write), host descriptor (read only) + - Default - "false" for a plug-in + - Valid Values - This must be one of + - "false" - the host or plug-in does not support Metal render + - "true" - the host or plug-in can support Metal render + */ +#define kOfxImageEffectPropMetalRenderSupported "OfxImageEffectPropMetalRenderSupported" + +/** @brief Indicates that a plug-in SHOULD use Metal render in +the current action + + If a plug-in and host have both set + kOfxImageEffectPropMetalRenderSupported="true" then the host MAY + set this property to indicate that it is passing images as Metal + buffers. + + - Type - int X 1 + - Property Set - inArgs property set of the following actions... + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionEndSequenceRender + - Valid Values + - 0 indicates that the kOfxImagePropData of each image of each clip + is a CPU memory pointer. + - 1 indicates that the kOfxImagePropData of each image of each clip + is a Metal id. +*/ +#define kOfxImageEffectPropMetalEnabled "OfxImageEffectPropMetalEnabled" + +/** @brief The command queue of Metal render + + - Type - pointer X 1 + - Property Set - inArgs property set of the following actions... + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionEndSequenceRender + +This property contains a pointer to the command queue to be used for +Metal rendering (id). In order to use it, +reinterpret_cast>(pointer) is needed. + +The plug-in SHOULD ensure that its render action enqueues any +asynchronous Metal operations onto the supplied queue. + +The plug-in SHOULD NOT wait for final asynchronous operations to +complete before returning from the render action. +*/ +#define kOfxImageEffectPropMetalCommandQueue "OfxImageEffectPropMetalCommandQueue" +/** @}*/ // end MetalRender doc group + +/** + * @defgroup OpenClRender OpenCL Rendering + * @version OpenCL rendering was added in version 1.5. + * @{ + */ +/** @brief Indicates whether a host or plug-in can support OpenCL Buffers render + + - Type - string X 1 + - Property Set - plug-in descriptor (read/write), host descriptor (read only) + - Default - "false" for a plug-in + - Valid Values - This must be one of + - "false" - the host or plug-in does not support OpenCL Buffers render + - "true" - the host or plug-in can support OpenCL Buffers render + */ +#define kOfxImageEffectPropOpenCLRenderSupported "OfxImageEffectPropOpenCLRenderSupported" + + /** @brief Indicates whether a host or plug-in can support OpenCL Images render + + - Type - string X 1 + - Property Set - plug-in descriptor (read/write), host descriptor (read only) + - Default - "false" for a plug-in + - Valid Values - This must be one of + - "false" - in which case the host or plug-in does not support OpenCL Images render + - "true" - which means a host or plug-in can support OpenCL Images render + */ +#define kOfxImageEffectPropOpenCLSupported "OfxImageEffectPropOpenCLSupported" + + /** @brief Indicates that a plug-in SHOULD use OpenCL render in +the current action + + If a plug-in and host have both set + kOfxImageEffectPropOpenCLRenderSupported="true" or have both + set kOfxImageEffectPropOpenCLSupported="true" then the host MAY + set this property to indicate that it is passing images as OpenCL + Buffers or Images. + + When rendering using OpenCL Buffers, the cl_mem of the buffers are retrieved using ::kOfxImagePropData. + When rendering using OpenCL Images, the cl_mem of the images are retrieved using ::kOfxImageEffectPropOpenCLImage. + If both ::kOfxImageEffectPropOpenCLSupported (Buffers) and ::kOfxImageEffectPropOpenCLRenderSupported (Images) are + enabled by the plug-in, it should use ::kOfxImageEffectPropOpenCLImage to determine which is being used by the host. + + - Type - int X 1 + - Property Set - inArgs property set of the following actions... + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionEndSequenceRender + - Valid Values + - 0 indicates that a plug-in SHOULD use OpenCL render in + the render action + - 1 indicates that a plug-in SHOULD NOT use OpenCL render in + the render action +*/ +#define kOfxImageEffectPropOpenCLEnabled "OfxImageEffectPropOpenCLEnabled" + +/** @brief Indicates the OpenCL command queue that should be used for rendering + + - Type - pointer X 1 + - Property Set - inArgs property set of the following actions... + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionEndSequenceRender + +This property contains a pointer to the command queue to be used for +OpenCL rendering (cl_command_queue). In order to use it, +reinterpret_cast(pointer) is needed. + +The plug-in SHOULD ensure that its render action enqueues any +asynchronous OpenCL operations onto the supplied queue. + +The plug-in SHOULD NOT wait for final asynchronous operations to +complete before returning from the render action. +*/ +#define kOfxImageEffectPropOpenCLCommandQueue "OfxImageEffectPropOpenCLCommandQueue" + +/** @brief Indicates the image handle of an image supplied as an OpenCL Image by the host + +- Type - pointer X 1 +- Property Set - image handle returned by clipGetImage + +This value should be cast to a cl_mem and used as the image handle when performing +OpenCL Images operations. The property should be used (not ::kOfxImagePropData) when +rendering with OpenCL Images (::kOfxImageEffectPropOpenCLSupported), and should be used +to determine whether Images or Buffers should be used if a plug-in supports both +::kOfxImageEffectPropOpenCLSupported and ::kOfxImageEffectPropOpenCLRenderSupported. +Note: the kOfxImagePropRowBytes property is not required to be set by the host, since +OpenCL Images do not have the concept of row bytes. +*/ +#define kOfxImageEffectPropOpenCLImage "OfxImageEffectPropOpenCLImage" + + +#define kOfxOpenCLProgramSuite "OfxOpenCLProgramSuite" + +/** @brief OFX suite that allows a plug-in to get OpenCL programs compiled + +This is an optional suite the host can provide for building OpenCL programs for the plug-in, +as an alternative to calling clCreateProgramWithSource / clBuildProgram. There are two advantages to +doing this: The host can add flags (such as -cl-denorms-are-zero) to the build call, and may also +cache program binaries for performance (however, if the source of the program or the OpenCL +environment changes, the host must recompile so some mechanism such as hashing must be used). +*/ +typedef struct OfxOpenCLProgramSuiteV1 { + /** @brief Compiles the OpenCL program */ + OfxStatus(*compileProgram)(const char *pszProgramSource, + int fOptional, // if non-zero, host may skip compiling on this call + void *pResult); // cast to cl_program* +} OfxOpenCLProgramSuiteV1; + + +/** @page ofxOpenCLRender OpenCL Acceleration of Rendering + +@section ofxOpenCLRenderIntro Introduction + +The OpenCL extension enables plug-ins to use OpenCL commands (typically backed by a GPU) to accelerate rendering of their outputs. The basic scheme is simple.... +- an plug-in indicates it wants to use OpenCL acceleration by setting the ::kOfxImageEffectPropOpenCLSupported (Images) and/or ::kOfxImageEffectPropOpenCLRenderSupported (Buffers) flags on it's descriptor. +- a host indicates it supports OpenCL acceleration by setting ::kOfxImageEffectPropOpenCLSupported (Images) and/or ::kOfxImageEffectPropOpenCLRenderSupported (Buffers) on it's descriptor. +- the host decides when to use OpenCL, and sets the ::kOfxImageEffectPropOpenCLEnabled property on the BeginRender/Render/EndRender calls to indicate this. +- when OpenCL Images are being used (::kOfxImageEffectPropOpenCLSupported) the clip image property ::kOfxImageEffectPropOpenCLImage will be set and non-null. +- when OpenCL Buffers are being used (::kOfxImageEffectPropOpenCLRenderSupported) the clip image property ::kOfxImagePropData will be set and non-null. + +@section ofxOpenCLRenderDiscoveryAndEnabling Discovery and Enabling + +If a host supports OpenCL rendering then it flags with the string property ::kOfxImageEffectPropOpenCLSupported (Images) and/or +::kOfxImageEffectPropOpenCLRenderSupported (Buffers) on its descriptor property set. Effects that cannot run without OpenCL support +should examine this in ::kOfxActionDescribe action and return a ::kOfxStatErrMissingHostFeature status flag if it is not set to "true". + +Effects flag to a host that they support OpenCL rendering by setting the string property ::kOfxImageEffectPropOpenCLSupported (Images) +and/or ::kOfxImageEffectPropOpenCLRenderSupported (Buffers) on their effect descriptor during the ::kOfxActionDescribe action. +Effects can work in two ways.... +- purely on CPUs without any OpenCL support at all, in which case they should set ::kOfxImageEffectPropOpenCLSupported (Images) and ::kOfxImageEffectPropOpenCLRenderSupported (Buffers) to be "false" (the default), +- on CPUs but with optional OpenCL support, in which case they should set ::kOfxImageEffectPropOpenCLSupported (Images) and/or ::kOfxImageEffectPropOpenCLRenderSupported (Buffers) to be "true" + +Host may support just OpenCL Images, just OpenCL Buffers, or both, as indicated by which of these two properties they set "true". +Likewise plug-ins may support just OpenCL Images, just OpenCL Buffers, or both, as indicated by which of these two properties they set "true". +If both host and plug-in support both, it is up to the host which it uses. Typically, it will be based on what it uses natively (to avoid an extra copy operation). +If a plug-in supports both, it must use ::kOfxImageEffectPropOpenCLImage to determine if Images or Buffers are being used for a given render action. + +Effects can use OpenCL render only during the following action: +- ::kOfxImageEffectActionRender + +If a plug-in has indicated that it optionally supports OpenCL acceleration, it should check the property ::kOfxImageEffectPropOpenCLEnabled +passed as an in argument to the following actions, +- ::kOfxImageEffectActionRender +- ::kOfxImageEffectActionBeginSequenceRender +- ::kOfxImageEffectActionEndSequenceRender + +If this property is set to 0, then it must not attempt to use OpenCL while rendering. +If this property is set to 1, then it must use OpenCL buffers or images while rendering. + +If a call using OpenCL rendering fails, the host may re-attempt using CPU buffers instead, but this is not required, and might not be efficient. + +@section ofxOpenCLRenderVersion OpenCL platform and device versions and feature support + +Assume an in-order command queue. Do not assume a profiling command queue. + +Effects should target OpenCL 1.1 API and OpenCL C kernel language support. Only minimum required features required +in OpenCL 1.1 should be used (for example, see "5.3.2.1 Minimum List of Supported Image Formats" for the list +of image types which can be expected to be supported across all devices). If you have specific requirements +for features beyond these minimums, you will need to check the device (e.g., using clGetDeviceInfo with +CL_DEVICE_EXTENSIONS) to see if your feature is available, and have a fallback if it's not. + +Temporary buffers and images should not be kept past the render action. A separate extension for host managed caching is in the works. + +Do not retain OpenCL objects without a matching release within the render action. + +@section ofxOpenCLRenderMultipleDevices Multiple OpenCL Devices + +This is very important: The host may support multiple OpenCL devices. Therefore the plug-in should keep a separate set of kernels per OpenCL content (e.g., using a map). +The OpenCL context can be found from the command queue using clGetCommandQueueInfo with CL_QUEUE_CONTEXT. +Failure to do this will cause crashes or incorrect results when the host switches to another OpenCL device. + +*/ + +/** @}*/ // end OpenCLRender doc group + + +#ifdef __cplusplus +} +#endif + +#endif /*__OFXGPURENDER_H__ */ diff --git a/src/modules/openfx/ofxImageEffect.h b/src/modules/openfx/ofxImageEffect.h new file mode 100644 index 000000000..26b84a186 --- /dev/null +++ b/src/modules/openfx/ofxImageEffect.h @@ -0,0 +1,1735 @@ +#pragma once +#ifndef _ofxImageEffect_h_ +#define _ofxImageEffect_h_ + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + +#include "ofxCore.h" +#include "ofxParam.h" +#include "ofxInteract.h" +#include "ofxMessage.h" +#include "ofxMemory.h" +#include "ofxMultiThread.h" +#include "ofxInteract.h" + + +#ifdef __cplusplus +extern "C" { +#endif + +/** @brief String used to label OFX Image Effect Plug-ins + + Set the pluginApi member of the OfxPluginHeader inside any OfxImageEffectPluginStruct + to be this so that the host knows the plugin is an image effect. + */ +#define kOfxImageEffectPluginApi "OfxImageEffectPluginAPI" + +/** @brief The current version of the Image Effect API + */ +#define kOfxImageEffectPluginApiVersion 1 + +/** @brief Blind declaration of an OFX image effect +*/ +typedef struct OfxImageEffectStruct *OfxImageEffectHandle; + +/** @brief Blind declaration of an OFX image effect +*/ +typedef struct OfxImageClipStruct *OfxImageClipHandle; + +/** @brief Blind declaration for an handle to image memory returned by the image memory management routines */ +typedef struct OfxImageMemoryStruct *OfxImageMemoryHandle; + +/** @brief String to label something with unset components */ +#define kOfxImageComponentNone "OfxImageComponentNone" + +/** @brief String to label images with RGBA components */ +#define kOfxImageComponentRGBA "OfxImageComponentRGBA" + +/** @brief String to label images with RGB components */ +#define kOfxImageComponentRGB "OfxImageComponentRGB" + +/** @brief String to label images with only Alpha components */ +#define kOfxImageComponentAlpha "OfxImageComponentAlpha" + +/** @brief Use to define the generator image effect context. See \ref ::kOfxImageEffectPropContext + */ +#define kOfxImageEffectContextGenerator "OfxImageEffectContextGenerator" + +/** @brief Use to define the filter effect image effect context See \ref ::kOfxImageEffectPropContext */ +#define kOfxImageEffectContextFilter "OfxImageEffectContextFilter" + +/** @brief Use to define the transition image effect context See \ref ::kOfxImageEffectPropContext */ +#define kOfxImageEffectContextTransition "OfxImageEffectContextTransition" + +/** @brief Use to define the paint image effect context See \ref ::kOfxImageEffectPropContext */ +#define kOfxImageEffectContextPaint "OfxImageEffectContextPaint" + +/** @brief Use to define the general image effect context See \ref ::kOfxImageEffectPropContext */ +#define kOfxImageEffectContextGeneral "OfxImageEffectContextGeneral" + +/** @brief Use to define the retimer effect context See \ref ::kOfxImageEffectPropContext */ +#define kOfxImageEffectContextRetimer "OfxImageEffectContextRetimer" + +/** @brief Used as a value for ::kOfxPropType on image effect host handles */ +#define kOfxTypeImageEffectHost "OfxTypeImageEffectHost" + +/** @brief Used as a value for ::kOfxPropType on image effect plugin handles */ +#define kOfxTypeImageEffect "OfxTypeImageEffect" + +/** @brief Used as a value for ::kOfxPropType on image effect instance handles */ +#define kOfxTypeImageEffectInstance "OfxTypeImageEffectInstance" + +/** @brief Used as a value for ::kOfxPropType on image effect clips */ +#define kOfxTypeClip "OfxTypeClip" + +/** @brief Used as a value for ::kOfxPropType on image effect images */ +#define kOfxTypeImage "OfxTypeImage" + +/** + \addtogroup ActionsAll +*/ +/*@{*/ +/** + \defgroup ImageEffectActions Image Effect Actions + +These are the list of actions passed to an image effect plugin's main function. For more details on how to deal with actions, see \ref ImageEffectActions. +*/ +/*@{*/ + +/** @brief + + The region of definition for an image effect is the rectangular section + of the 2D image plane that it is capable of filling, given the state of + its input clips and parameters. This action is used to calculate the RoD + for a plugin instance at a given frame. For more details on regions of + definition see \ref ImageEffectArchitectures "Image Effect Architectures" + + Note that hosts that have constant sized imagery need not call this + action, only hosts that allow image sizes to vary need call this. + + @param handle handle to the instance, cast to an \ref OfxImageEffectHandle + + @param inArgs has the following properties + - \ref kOfxPropTime the effect time for which a region of definition is being + requested + - \ref kOfxImageEffectPropRenderScale the render scale that should be used in any calculations in this + action + + @param outArgs has the following property which the plug-in may set + - \ref kOfxImageEffectPropRegionOfDefinition the calculated region of definition, initially set by the host + to the default RoD (see below), in Canonical Coordinates. + + + If the effect did not trap this, it means the host should use the + default RoD instead, which depends on the context. This is... + + - generator context - defaults to the project window, + - filter and paint contexts - defaults to the RoD of the 'Source' input + clip at the given time, + - transition context - defaults to the union of the RoDs of the + 'SourceFrom' and 'SourceTo' input clips at the given time, + - general context - defaults to the union of the RoDs of all the non + optional input clips and the 'Source' input clip (if it exists and it + is connected) at the given time, if none exist, then it is the + project window + - retimer context - defaults to the union of the RoD of the 'Source' + input clip at the frame directly preceding the value of the + 'SourceTime' double parameter and the frame directly after it + +@returns + - \ref kOfxStatOK the action was trapped and the RoD was set in the outArgs property set + - \ref kOfxStatReplyDefault, the action was not trapped and the host should use the default values + - \ref kOfxStatErrMemory, in which case the action may be called again after a memory purge + - \ref kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message + - \ref kOfxStatErrFatal + + */ +#define kOfxImageEffectActionGetRegionOfDefinition "OfxImageEffectActionGetRegionOfDefinition" + +/** @brief + + This action allows a host to ask an effect, given a region I want to + render, what region do you need from each of your input clips. In that + way, depending on the host architecture, a host can fetch the minimal + amount of the image needed as input. Note that there is a region of + interest to be set in ``outArgs`` for each input clip that exists on the + effect. For more details see \ref ImageEffectArchitectures "Image Effect + Architectures" + + + The default RoI is simply the value passed in on the + \ref kOfxImageEffectPropRegionOfInterest + ``inArgs`` property set. All the RoIs in the ``outArgs`` property set + must initialised to this value before the action is called. + + + @param handle handle to the instance, cast to an \ref OfxImageEffectHandle + @param inArgs has the following properties + - \ref kOfxPropTime the effect time for which a region of definition is being requested + - \ref kOfxImageEffectPropRenderScale the render scale that should be used in any calculations in this action + - \ref kOfxImageEffectPropRegionOfInterest the region to be rendered in the output image, in Canonical Coordinates. + + @param outArgs has a set of 4 dimensional double properties, one for each of the input clips to the effect. + The properties are each named ``OfxImageClipPropRoI_`` with the clip name post pended, for example + ``OfxImageClipPropRoI_Source``. These are initialised to the default RoI. + + + @returns + - \ref kOfxStatOK, the action was trapped and at least one RoI was set in the outArgs property set + - \ref kOfxStatReplyDefault, the action was not trapped and the host should use the default values + - \ref kOfxStatErrMemory, in which case the action may be called again after a memory purge + - \ref kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message + - \ref kOfxStatErrFatal + + + */ +#define kOfxImageEffectActionGetRegionsOfInterest "OfxImageEffectActionGetRegionsOfInterest" + +/** @brief + This action allows a host to ask an effect what range of frames it can + produce images over. Only effects instantiated in the \ref generalContext "General + Context" can have this called on them. In all other + the host is in strict control over the temporal duration of the effect. + + The default is: + + - the union of all the frame ranges of the non optional input clips, + - infinite if there are no non optional input clips. + + @param handle handle to the instance, cast to an \ref OfxImageEffectHandle + @param inArgs is redundant and is null + @param outArgs has the following property + - \ref kOfxImageEffectPropFrameRange the frame range an effect can produce images for + + + \pre + - \ref kOfxActionCreateInstance has been called on the instance + - the effect instance has been created in the general effect context + + @returns + - \ref kOfxStatOK, the action was trapped and the \ref kOfxImageEffectPropFrameRange was set in the outArgs property set + - \ref kOfxStatReplyDefault, the action was not trapped and the host should use the default value + - \ref kOfxStatErrMemory, in which case the action may be called again after a memory purge + - \ref kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message + - \ref kOfxStatErrFatal + + + + */ +#define kOfxImageEffectActionGetTimeDomain "OfxImageEffectActionGetTimeDomain" + +/** @brief + + This action lets the host ask the effect what frames are needed from + each input clip to process a given frame. For example a temporal based + degrainer may need several frames around the frame to render to do its + work. + + This action need only ever be called if the plugin has set the + \ref kOfxImageEffectPropTemporalClipAccess + property on the plugin descriptor to be true. Otherwise the host assumes + that the only frame needed from the inputs is the current one and this + action is not called. + + Note that each clip can have it's required frame range specified, and + that you can specify discontinuous sets of ranges for each clip, for + example + + \code{.cpp} + + // The effect always needs the initial frame of the source as well as the previous and current frame + double rangeSource[4]; + + // required ranges on the source + rangeSource[0] = 0; // we always need frame 0 of the source + rangeSource[1] = 0; + rangeSource[2] = currentFrame - 1; // we also need the previous and current frame on the source + rangeSource[3] = currentFrame; + + gPropHost->propSetDoubleN(outArgs, "OfxImageClipPropFrameRange_Source", 4, rangeSource); + + \endcode + + Which sets two discontinuous range of frames from the 'Source' clip + required as input. + + + The default frame range is simply the single frame, + kOfxPropTime..kOfxPropTime, found on the ``inArgs`` property set. All + the frame ranges in the ``outArgs`` property set must initialised to + this value before the action is called. + + @param handle handle to the instance, cast to an \ref OfxImageEffectHandle + @param inArgs has the following property + - \ref kOfxPropTime the effect time for which we need to calculate the frames needed on input + - \ref outArgs has a set of properties, one for each input clip, named + ``OfxImageClipPropFrameRange_`` with the name of the clip post-pended. + For example ``OfxImageClipPropFrameRange_Source``. All these properties + are multi-dimensional doubles, with the dimension is a multiple of + two. Each pair of values indicates a continuous range of frames that + is needed on the given input. They are all initalised to the default value. + + + @returns + - \ref kOfxStatOK, the action was trapped and at least one frame range in the outArgs property set + - \ref kOfxStatReplyDefault, the action was not trapped and the host should use the default values + - \ref kOfxStatErrMemory, in which case the action may be called again after a memory purge + - \ref kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message + - \ref kOfxStatErrFatal + */ +#define kOfxImageEffectActionGetFramesNeeded "OfxImageEffectActionGetFramesNeeded" + +/** @brief + + This action allows a plugin to dynamically specify its preferences for + input and output clips. Please see \ref ImageEffectClipPreferences "Image Effect Clip Preferences" for more details on the + behaviour. Clip preferences are constant for the duration of an effect, + so this action need only be called once per clip, not once per frame. + + This should be called once after creation of an instance, each time an + input clip is changed, and whenever a parameter named in the + \ref kOfxImageEffectPropClipPreferencesSlaveParam + has its value changed. + + @param handle handle to the instance, cast to an \ref OfxImageEffectHandle + @param inArgs is redundant and is set to NULL + @param outArgs has the following properties which the plugin can set + - a set of char \* X 1 properties, one for each of the input clips + currently attached and the output clip, labelled with + ``OfxImageClipPropComponents_`` post pended with the clip's name. + This must be set to one of the component types which the host + supports and the effect stated it can accept on that input + + - a set of char \* X 1 properties, one for each of the input clips + currently attached and the output clip, labelled with + ``OfxImageClipPropDepth_`` post pended with the clip's name. This + must be set to one of the pixel depths both the host and plugin + supports + + - a set of double X 1 properties, one for each of the input clips + currently attached and the output clip, labelled with + ``OfxImageClipPropPAR_`` post pended with the clip's name. This is + the pixel aspect ratio of the input and output clips. This must be + set to a positive non zero double value, + + - \ref kOfxImageEffectPropFrameRate the frame rate of the output clip, this must be set to a positive non zero double value + - \ref kOfxImageClipPropFieldOrder the fielding of the output clip + - \ref kOfxImageEffectPropPreMultiplication the premultiplication of the output clip + - \ref kOfxImageClipPropContinuousSamples whether the output clip can produce different images at non-frame intervals, defaults to false, + - \ref kOfxImageEffectFrameVarying whether the output clip can produces different images at + different times, even if all parameters and inputs are constant, + defaults to false. + +@returns + - \ref kOfxStatOK, the action was trapped and at least one of the properties in the outArgs + was changed from its default value + - \ref kOfxStatReplyDefault, the action was not trapped and the host should + use the default values + - \ref kOfxStatErrMemory, in which case the action may be called again after + a memory purge + - \ref kOfxStatFailed, something wrong, but no error code appropriate, + plugin to post message + - \ref kOfxStatErrFatal + */ +#define kOfxImageEffectActionGetClipPreferences "OfxImageEffectActionGetClipPreferences" + +/** @brief + + Sometimes an effect can pass through an input uprocessed, for example a + blur effect with a blur size of 0. This action can be called by a host + before it attempts to render an effect to determine if it can simply + copy input directly to output without having to call the render action + on the effect. + + If the effect does not need to process any pixels, it should set the + value of the \ref kOfxPropName to the clip that the host should us as the + output instead, and the \ref kOfxPropTime property on ``outArgs`` to be + the time at which the frame should be fetched from a clip. + + The default action is to call the render action on the effect. + + + @param handle handle to the instance, cast to an \ref OfxImageEffectHandle + @param inArgs has the following properties + - \ref kOfxPropTime the time at which to test for identity + - \ref kOfxImageEffectPropFieldToRender the field to test for identity + - \ref kOfxImageEffectPropRenderWindow the window (in \\ref PixelCoordinates) to test for identity under + - \ref kOfxImageEffectPropRenderScale the scale factor being applied to the images being renderred + + @param outArgs has the following properties which the plugin can set + - \ref kOfxPropName + this to the name of the clip that should be used if the effect is + an identity transform, defaults to the empty string + - \ref kOfxPropTime + the time to use from the indicated source clip as an identity + image (allowing time slips to happen), defaults to the value in + \ref kOfxPropTime in inArgs + + + + @returns + - \ref kOfxStatOK, the action was trapped and the effect should not have its + render action called, the values in outArgs + indicate what frame from which clip to use instead + - \ref kOfxStatReplyDefault, the action was not trapped and the host should + call the render action + - \ref kOfxStatErrMemory, in which case the action may be called again after + a memory purge + - \ref kOfxStatFailed, something wrong, but no error code appropriate, + plugin to post message + - \ref kOfxStatErrFatal + + */ +#define kOfxImageEffectActionIsIdentity "OfxImageEffectActionIsIdentity" + +/** @brief + + This action is where an effect gets to push pixels and turn its input + clips and parameter set into an output image. This is possibly quite + complicated and covered in the \ref RenderingEffects "Rendering Image Effects" chapter. + + The render action *must* be trapped by the plug-in, it cannot return + \ref kOfxStatReplyDefault. The pixels needs be pushed I'm afraid. + + @param handle handle to the instance, cast to an \ref OfxImageEffectHandle + @param inArgs has the following properties + - \ref kOfxPropTime the time at which to render + - \ref kOfxImageEffectPropFieldToRender the field to render + - \ref kOfxImageEffectPropRenderWindow the window (in \\ref PixelCoordinates) to render + - \ref kOfxImageEffectPropRenderScale the scale factor being applied to the images being renderred + - \ref kOfxImageEffectPropSequentialRenderStatus whether the effect is currently being rendered in strict frame order on a single instance + - \ref kOfxImageEffectPropInteractiveRenderStatus if the render is in response to a user modifying the effect in an interactive session + - \ref kOfxImageEffectPropRenderQualityDraft if the render should be done in draft mode (e.g. for faster scrubbing) + + @param outArgs is redundant and should be set to NULL + +\pre + - \ref kOfxActionCreateInstance has been called on the instance + - \ref kOfxImageEffectActionBeginSequenceRender has been called on the + instance + + \post + - \ref kOfxImageEffectActionEndSequenceRender action will be called on the + instance + + @returns + - \ref kOfxStatOK, the effect rendered happily + - \ref kOfxStatErrMemory, in which case the action may be called again after + a memory purge + - \ref kOfxStatFailed, something wrong, but no error code appropriate, + plugin to post message + - \ref kOfxStatErrFatal + + */ +#define kOfxImageEffectActionRender "OfxImageEffectActionRender" + +/** @brief + + This action is passed to an image effect before it renders a range of + frames. It is there to allow an effect to set things up for a long + sequence of frames. Note that this is still called, even if only a + single frame is being rendered in an interactive environment. + + @param handle handle to the instance, cast to an \ref OfxImageEffectHandle + + @param inArgs has the following properties + - \ref kOfxImageEffectPropFrameRange the range of frames (inclusive) that will be renderred + - \ref kOfxImageEffectPropFrameStep what is the step between frames, generally set to 1 (for full frame renders) or 0.5 (for fielded renders) + - \ref kOfxPropIsInteractive is this a single frame render due to user interaction in a GUI, or a proper full sequence render. + - \ref kOfxImageEffectPropRenderScale the scale factor to apply to images for this call + - \ref kOfxImageEffectPropSequentialRenderStatus whether the effect is currently being rendered in strict frame order on a single instance + - \ref kOfxImageEffectPropInteractiveRenderStatus if the render is in response to a user modifying the effect in an interactive session + + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance has been called on the instance + + \post + - \ref kOfxImageEffectActionRender action will be called at least once on the instance + - \ref kOfxImageEffectActionEndSequenceRender action will be called on the + instance + + @returns + - \ref kOfxStatOK, the action was trapped and handled cleanly by the effect, + - \ref kOfxStatReplyDefault, the action was not trapped, but all is well + anyway, + - \ref kOfxStatErrMemory, in which case the action may be called again after + a memory purge, + - \ref kOfxStatFailed, something wrong, but no error code appropriate, + plugin to post message, + - \ref kOfxStatErrFatal + */ +#define kOfxImageEffectActionBeginSequenceRender "OfxImageEffectActionBeginSequenceRender" + +/** @brief + + This action is passed to an image effect after is has rendered a range + of frames. It is there to allow an effect to free resources after a long + sequence of frame renders. Note that this is still called, even if only + a single frame is being rendered in an interactive environment. + + @param handle handle to the instance, cast to an \ref OfxImageEffectHandle + @param inArgs has the following properties + - \ref kOfxImageEffectPropFrameRange the range of frames (inclusive) that will be rendered + - \ref kOfxImageEffectPropFrameStep what is the step between frames, generally set to 1 (for full frame renders) or 0.5 (for fielded renders), + - \ref kOfxPropIsInteractive + - \ref is this a single frame render due to user interaction in a GUI, or a proper full sequence render. + - \ref kOfxImageEffectPropRenderScale + - \ref the scale factor to apply to images for this call + - \ref kOfxImageEffectPropSequentialRenderStatus + - \ref whether the effect is currently being rendered in strict frame order on a single instance + - \ref kOfxImageEffectPropInteractiveRenderStatus + - \ref if the render is in response to a user modifying the effect in an interactive session + + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance has been called on the instance + - \ref kOfxImageEffectActionEndSequenceRender action was called on the + instance + - \ref kOfxImageEffectActionRender action was called at least once on the + instance + + @returns + - \ref kOfxStatOK, the action was trapped and handled cleanly by the effect, + - \ref kOfxStatReplyDefault, the action was not trapped, but all is well + anyway, + - \ref kOfxStatErrMemory, in which case the action may be called again after + a memory purge, + - \ref kOfxStatFailed, something wrong, but no error code appropriate, + plugin to post message, + - \ref kOfxStatErrFatal + + */ +#define kOfxImageEffectActionEndSequenceRender "OfxImageEffectActionEndSequenceRender" + +/** @brief + + This action is unique to OFX Image Effect plug-ins. Because a plugin is + able to exhibit different behaviour depending on the context of use, + each separate context will need to be described individually. It is + within this action that image effects describe which parameters and + input clips it requires. + + This action will be called multiple times, one for each of the contexts + the plugin says it is capable of implementing. If a host does not + support a certain context, then it need not call + \ref kOfxImageEffectActionDescribeInContext for that context. + + This action *must* be trapped, it is not optional. + + @param handle handle to the context descriptor, cast to an \ref OfxImageEffectHandle + this may or may not be the same as passed to \ref kOfxActionDescribe + + @param inArgs has the following property: + - \ref kOfxImageEffectPropContext the context being described + + @param outArgs is redundant and is set to NULL + +\pre + - \ref kOfxActionDescribe has been called on the descriptor handle, + - \ref kOfxActionCreateInstance has not been called + + @returns + - \ref kOfxStatOK, the action was trapped and all was well + - \ref kOfxStatErrMissingHostFeature, in which the context will be ignored + by the host, the plugin may post a message + - \ref kOfxStatErrMemory, in which case the action may be called again after + a memory purge + - \ref kOfxStatFailed, something wrong, but no error code appropriate, + plugin to post message + - \ref kOfxStatErrFatal + + */ +#define kOfxImageEffectActionDescribeInContext "OfxImageEffectActionDescribeInContext" + +/*@}*/ +/*@}*/ + +/** + \addtogroup PropertiesAll +*/ +/*@{*/ +/** + \defgroup ImageEffectPropDefines Image Effect Property Definitions + +These are the list of properties used by the Image Effects API. +*/ +/*@{*/ +/** @brief Indicates to the host the contexts a plugin can be used in. + + - Type - string X N + - Property Set - image effect descriptor passed to kOfxActionDescribe (read/write) + - Default - this has no defaults, it must be set + - Valid Values - This must be one of + - ::kOfxImageEffectContextGenerator + - ::kOfxImageEffectContextFilter + - ::kOfxImageEffectContextTransition + - ::kOfxImageEffectContextPaint + - ::kOfxImageEffectContextGeneral + - ::kOfxImageEffectContextRetimer +*/ +#define kOfxImageEffectPropSupportedContexts "OfxImageEffectPropSupportedContexts" + +/** @brief The plugin handle passed to the initial 'describe' action. + + - Type - pointer X 1 + - Property Set - plugin instance, (read only) + +This value will be the same for all instances of a plugin. +*/ +#define kOfxImageEffectPropPluginHandle "OfxImageEffectPropPluginHandle" + +/** @brief Indicates if a host is a background render. + + - Type - int X 1 + - Property Set - host descriptor (read only) + - Valid Values - This must be one of + - 0 if the host is a foreground host, it may open the effect in an interactive session (or not) + - 1 if the host is a background 'processing only' host, and the effect will never be opened in an interactive session. +*/ +#define kOfxImageEffectHostPropIsBackground "OfxImageEffectHostPropIsBackground" + +/** @brief Indicates whether only one instance of a plugin can exist at the same time + + - Type - int X 1 + - Property Set - plugin descriptor (read/write) + - Default - 0 + - Valid Values - This must be one of + - 0 - which means multiple instances can exist simultaneously, + - 1 - which means only one instance can exist at any one time. + +Some plugins, for whatever reason, may only be able to have a single instance in existance at any one time. This plugin property is used to indicate that. +*/ +#define kOfxImageEffectPluginPropSingleInstance "OfxImageEffectPluginPropSingleInstance" + +/** @brief Indicates how many simultaneous renders the plugin can deal with. + + - Type - string X 1 + - Property Set - plugin descriptor (read/write) + - Default - ::kOfxImageEffectRenderInstanceSafe + - Valid Values - This must be one of + - ::kOfxImageEffectRenderUnsafe - indicating that only a single 'render' call can be made at any time amoung all instances, + - ::kOfxImageEffectRenderInstanceSafe - indicating that any instance can have a single 'render' call at any one time, + - ::kOfxImageEffectRenderFullySafe - indicating that any instance of a plugin can have multiple renders running simultaneously +*/ +#define kOfxImageEffectPluginRenderThreadSafety "OfxImageEffectPluginRenderThreadSafety" + +/** @brief String used to label render threads as un thread safe, see, \ref ::kOfxImageEffectPluginRenderThreadSafety */ +#define kOfxImageEffectRenderUnsafe "OfxImageEffectRenderUnsafe" +/** @brief String used to label render threads as instance thread safe, \ref ::kOfxImageEffectPluginRenderThreadSafety */ +#define kOfxImageEffectRenderInstanceSafe "OfxImageEffectRenderInstanceSafe" +/** @brief String used to label render threads as fully thread safe, \ref ::kOfxImageEffectPluginRenderThreadSafety */ +#define kOfxImageEffectRenderFullySafe "OfxImageEffectRenderFullySafe" + +/** @brief Indicates whether a plugin lets the host perform per frame SMP threading + + - Type - int X 1 + - Property Set - plugin descriptor (read/write) + - Default - 1 + - Valid Values - This must be one of + - 0 - which means that the plugin will perform any per frame SMP threading + - 1 - which means the host can call an instance's render function simultaneously at the same frame, but with different windows to render. +*/ +#define kOfxImageEffectPluginPropHostFrameThreading "OfxImageEffectPluginPropHostFrameThreading" + +/** @brief Indicates whether a host or plugin can support clips of differing component depths going into/out of an effect + + - Type - int X 1 + - Property Set - plugin descriptor (read/write), host descriptor (read only) + - Default - 0 for a plugin + - Valid Values - This must be one of + - 0 - in which case the host or plugin does not support clips of multiple pixel depths, + - 1 - which means a host or plugin is able to to deal with clips of multiple pixel depths, + +If a host indicates that it can support multiple pixels depths, then it will allow the plugin to explicitly set +the output clip's pixel depth in the ::kOfxImageEffectActionGetClipPreferences action. See \ref ImageEffectClipPreferences. +*/ +#define kOfxImageEffectPropSupportsMultipleClipDepths "OfxImageEffectPropMultipleClipDepths" + +/** @brief Indicates whether a host or plugin can support clips of differing pixel aspect ratios going into/out of an effect + + - Type - int X 1 + - Property Set - plugin descriptor (read/write), host descriptor (read only) + - Default - 0 for a plugin + - Valid Values - This must be one of + - 0 - in which case the host or plugin does not support clips of multiple pixel aspect ratios + - 1 - which means a host or plugin is able to to deal with clips of multiple pixel aspect ratios + +If a host indicates that it can support multiple pixel aspect ratios, then it will allow the plugin to explicitly set +the output clip's aspect ratio in the ::kOfxImageEffectActionGetClipPreferences action. See \ref ImageEffectClipPreferences. +*/ +#define kOfxImageEffectPropSupportsMultipleClipPARs "OfxImageEffectPropSupportsMultipleClipPARs" + + +/** @brief Indicates the set of parameters on which a value change will trigger a change to clip preferences + + - Type - string X N + - Property Set - plugin descriptor (read/write) + - Default - none set + - Valid Values - the name of any described parameter + +The plugin uses this to inform the host of the subset of parameters that affect the effect's clip preferences. A value change in any one of these will trigger a call to the clip preferences action. + +The plugin can be slaved to multiple parameters (setting index 0, then index 1 etc...) + */ +#define kOfxImageEffectPropClipPreferencesSlaveParam "OfxImageEffectPropClipPreferencesSlaveParam" + +/** @brief Indicates whether the host will let a plugin set the frame rate of the output clip. + + - Type - int X 1 + - Property Set - host descriptor (read only) + - Valid Values - This must be one of + - 0 - in which case the plugin may not change the frame rate of the output clip, + - 1 - which means a plugin is able to change the output clip's frame rate in the ::kOfxImageEffectActionGetClipPreferences action. + +See \ref ImageEffectClipPreferences. + +If a clip can be continously sampled, the frame rate will be set to 0. +*/ +#define kOfxImageEffectPropSetableFrameRate "OfxImageEffectPropSetableFrameRate" + +/** @brief Indicates whether the host will let a plugin set the fielding of the output clip. + + - Type - int X 1 + - Property Set - host descriptor (read only) + - Valid Values - This must be one of + - 0 - in which case the plugin may not change the fielding of the output clip, + - 1 - which means a plugin is able to change the output clip's fielding in the ::kOfxImageEffectActionGetClipPreferences action. + +See \ref ImageEffectClipPreferences. +*/ +#define kOfxImageEffectPropSetableFielding "OfxImageEffectPropSetableFielding" + +/** @brief Indicates whether a plugin needs sequential rendering, and a host support it + + - Type - int X 1 + - Property Set - plugin descriptor (read/write) or plugin instance (read/write), and host descriptor (read only) + - Default - 0 + - Valid Values - + - 0 - for a plugin, indicates that a plugin does not need to be sequentially rendered to be correct, for a host, indicates that it cannot ever guarantee sequential rendering, + - 1 - for a plugin, indicates that it needs to be sequentially rendered to be correct, for a host, indicates that it can always support sequential rendering of plugins that are sequentially rendered, + - 2 - for a plugin, indicates that it is best to render sequentially, but will still produce correct results if not, for a host, indicates that it can sometimes render sequentially, and will have set ::kOfxImageEffectPropSequentialRenderStatus on the relevant actions + +Some effects have temporal dependancies, some information from from the rendering of frame N-1 is needed to render frame N correctly. This property is set by an effect to indicate such a situation. Also, some effects are more efficient if they run sequentially, but can still render correct images even if they do not, eg: a complex particle system. + +During an interactive session a host may attempt to render a frame out of sequence (for example when the user scrubs the current time), and the effect needs to deal with such a situation as best it can to provide feedback to the user. + +However if a host caches output, any frame frame generated in random temporal order needs to be considered invalid and needs to be re-rendered when the host finally performs a first to last render of the output sequence. + +In all cases, a host will set the kOfxImageEffectPropSequentialRenderStatus flag to indicate its sequential render status. +*/ +#define kOfxImageEffectInstancePropSequentialRender "OfxImageEffectInstancePropSequentialRender" + +/** @brief Property on all the render action that indicate the current sequential render status of a host + + - Type - int X 1 + - Property Set - read only property on the inArgs of the following actions... + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionEndSequenceRender + - Valid Values - + - 0 - the host is not currently sequentially rendering, + - 1 - the host is currentely rendering in a way so that it guarantees sequential rendering. + +This property is set to indicate whether the effect is currently being rendered in frame order on a single effect instance. See ::kOfxImageEffectInstancePropSequentialRender for more details on sequential rendering. +*/ +#define kOfxImageEffectPropSequentialRenderStatus "OfxImageEffectPropSequentialRenderStatus" + +#define kOfxHostNativeOriginBottomLeft "kOfxImageEffectHostPropNativeOriginBottomLeft" +#define kOfxHostNativeOriginTopLeft "kOfxImageEffectHostPropNativeOriginTopLeft" +#define kOfxHostNativeOriginCenter "kOfxImageEffectHostPropNativeOriginCenter" +/** @brief Property that indicates the host native UI space - this is only a UI hint, has no impact on pixel processing + + - Type - UTF8 string X 1 + - Property Set - read only property (host) + - Valid Values - + "kOfxImageEffectHostPropNativeOriginBottomLeft" - 0,0 bottom left + "kOfxImageEffectHostPropNativeOriginTopLeft" - 0,0 top left + "kOfxImageEffectHostPropNativeOriginCenter" - 0,0 center (screen space) + +This property is set to kOfxHostNativeOriginBottomLeft pre V1.4 and was to be discovered by plug-ins. This is useful for drawing overlay for points... so everything matches the rest of the app (for example expression linking to other tools, or simply match the reported location of the host viewer). + +*/ +#define kOfxImageEffectHostPropNativeOrigin "OfxImageEffectHostPropNativeOrigin" + + +/** @brief Property that indicates if a plugin is being rendered in response to user interaction. + + - Type - int X 1 + - Property Set - read only property on the inArgs of the following actions... + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionEndSequenceRender + - Valid Values - + - 0 - the host is rendering the instance due to some reason other than an interactive tweak on a UI, + - 1 - the instance is being rendered because a user is modifying parameters in an interactive session. + +This property is set to 1 on all render calls that have been triggered because a user is actively modifying an effect (or up stream effect) in an interactive session. This typically means that the effect is not being rendered as a part of a sequence, but as a single frame. +*/ +#define kOfxImageEffectPropInteractiveRenderStatus "OfxImageEffectPropInteractiveRenderStatus" + +/** @brief Indicates the effect group for this plugin. + + - Type - UTF8 string X 1 + - Property Set - plugin descriptor (read/write) + - Default - "" + +This is purely a user interface hint for the host so it can group related effects on any menus it may have. +*/ +#define kOfxImageEffectPluginPropGrouping "OfxImageEffectPluginPropGrouping" + +/** @brief Indicates whether a host support image effect \ref ImageEffectOverlays. + + - Type - int X 1 + - Property Set - host descriptor (read only) + - Valid Values - This must be one of + - 0 - the host won't allow a plugin to draw a GUI over the output image, + - 1 - the host will allow a plugin to draw a GUI over the output image. +*/ +#define kOfxImageEffectPropSupportsOverlays "OfxImageEffectPropSupportsOverlays" + +/** @brief Sets the entry for an effect's overlay interaction + + - Type - pointer X 1 + - Property Set - plugin descriptor (read/write) + - Default - NULL + - Valid Values - must point to an ::OfxPluginEntryPoint + +The entry point pointed to must be one that handles custom interaction actions. +*/ +#define kOfxImageEffectPluginPropOverlayInteractV1 "OfxImageEffectPluginPropOverlayInteractV1" + +/** @brief Sets the entry for an effect's overlay interaction. Unlike + kOfxImageEffectPluginPropOverlayInteractV1, the overlay interact in the plug-in is expected + to implement the kOfxInteractActionDraw using the OfxDrawSuiteV1. + + - Type - pointer X 1 + - Property Set - plugin descriptor (read/write) + - Default - NULL + - Valid Values - must point to an ::OfxPluginEntryPoint + +The entry point pointed to must be one that handles custom interaction actions. +*/ +#define kOfxImageEffectPluginPropOverlayInteractV2 "OfxImageEffectPluginPropOverlayInteractV2" + +/** @brief Indicates whether a plugin or host support multiple resolution images. + + - Type - int X 1 + - Property Set - host descriptor (read only), plugin descriptor (read/write) + - Default - 1 for plugins + - Valid Values - This must be one of + - 0 - the plugin or host does not support multiple resolutions + - 1 - the plugin or host does support multiple resolutions + +Multiple resolution images mean... + - input and output images can be of any size + - input and output images can be offset from the origin +*/ +#define kOfxImageEffectPropSupportsMultiResolution "OfxImageEffectPropSupportsMultiResolution" + +/** @brief Indicates whether a clip, plugin or host supports tiled images + + - Type - int X 1 + - Property Set - host descriptor (read only), plugin descriptor (read/write), clip descriptor (read/write), instance (read/write) + - Default - to 1 for a plugin and clip + - Valid Values - This must be one of 0 or 1 + +Tiled images mean that input or output images can contain pixel data that is only a subset of their full RoD. + +If a clip or plugin does not support tiled images, then the host should supply full RoD images to the effect whenever it fetches one. + +V1.4: It is now possible (defined) to change OfxImageEffectPropSupportsTiles in Instance Changed +*/ +#define kOfxImageEffectPropSupportsTiles "OfxImageEffectPropSupportsTiles" + + +/** @brief Indicates support for random temporal access to images in a clip. + + - Type - int X 1 + - Property Set - host descriptor (read only), plugin descriptor (read/write), clip descriptor (read/write) + - Default - to 0 for a plugin and clip + - Valid Values - This must be one of 0 or 1 + +On a host, it indicates whether the host supports temporal access to images. + +On a plugin, indicates if the plugin needs temporal access to images. + +On a clip, it indicates that the clip needs temporal access to images. +*/ +#define kOfxImageEffectPropTemporalClipAccess "OfxImageEffectPropTemporalClipAccess" + +/** @brief Indicates the context a plugin instance has been created for. + + - Type - string X 1 + - Property Set - image effect instance (read only) + - Valid Values - This must be one of + - ::kOfxImageEffectContextGenerator + - ::kOfxImageEffectContextFilter + - ::kOfxImageEffectContextTransition + - ::kOfxImageEffectContextPaint + - ::kOfxImageEffectContextGeneral + - ::kOfxImageEffectContextRetimer + + */ +#define kOfxImageEffectPropContext "OfxImageEffectPropContext" + +/** @brief Indicates the type of each component in a clip or image (after any mapping) + + - Type - string X 1 + - Property Set - clip instance (read only), image instance (read only) + - Valid Values - This must be one of + - kOfxBitDepthNone (implying a clip is unconnected, not valid for an image) + - kOfxBitDepthByte + - kOfxBitDepthShort + - kOfxBitDepthHalf + - kOfxBitDepthFloat + +Note that for a clip, this is the value set by the clip preferences action, not the raw 'actual' value of the clip. +*/ +#define kOfxImageEffectPropPixelDepth "OfxImageEffectPropPixelDepth" + +/** @brief Indicates the current component type in a clip or image (after any mapping) + + - Type - string X 1 + - Property Set - clip instance (read only), image instance (read only) + - Valid Values - This must be one of + - kOfxImageComponentNone (implying a clip is unconnected, not valid for an image) + - kOfxImageComponentRGBA + - kOfxImageComponentRGB + - kOfxImageComponentAlpha + +Note that for a clip, this is the value set by the clip preferences action, not the raw 'actual' value of the clip. +*/ +#define kOfxImageEffectPropComponents "OfxImageEffectPropComponents" + +/** @brief Uniquely labels an image + + - Type - ASCII string X 1 + - Property Set - image instance (read only) + +This is host set and allows a plug-in to differentiate between images. This is especially +useful if a plugin caches analysed information about the image (for example motion vectors). The plugin can label the +cached information with this identifier. If a user connects a different clip to the analysed input, or the image has changed in some way +then the plugin can detect this via an identifier change and re-evaluate the cached information. +*/ +#define kOfxImagePropUniqueIdentifier "OfxImagePropUniqueIdentifier" + +/** @brief Clip and action argument property which indicates that the clip can be sampled continously + + - Type - int X 1 + - Property Set - clip instance (read only), as an out argument to ::kOfxImageEffectActionGetClipPreferences action (read/write) + - Default - 0 as an out argument to the ::kOfxImageEffectActionGetClipPreferences action + - Valid Values - This must be one of... + - 0 if the images can only be sampled at discreet times (eg: the clip is a sequence of frames), + - 1 if the images can only be sampled continuously (eg: the clip is infact an animating roto spline and can be rendered anywhen). + +If this is set to true, then the frame rate of a clip is effectively infinite, so to stop arithmetic +errors the frame rate should then be set to 0. +*/ +#define kOfxImageClipPropContinuousSamples "OfxImageClipPropContinuousSamples" + +/** @brief Indicates the type of each component in a clip before any mapping by clip preferences + + - Type - string X 1 + - Property Set - clip instance (read only) + - Valid Values - This must be one of + - kOfxBitDepthNone (implying a clip is unconnected image) + - kOfxBitDepthByte + - kOfxBitDepthShort + - kOfxBitDepthHalf + - kOfxBitDepthFloat + +This is the actual value of the component depth, before any mapping by clip preferences. +*/ +#define kOfxImageClipPropUnmappedPixelDepth "OfxImageClipPropUnmappedPixelDepth" + +/** @brief Indicates the current 'raw' component type on a clip before any mapping by clip preferences + + - Type - string X 1 + - Property Set - clip instance (read only), + - Valid Values - This must be one of + - kOfxImageComponentNone (implying a clip is unconnected) + - kOfxImageComponentRGBA + - kOfxImageComponentRGB + - kOfxImageComponentAlpha +*/ +#define kOfxImageClipPropUnmappedComponents "OfxImageClipPropUnmappedComponents" + +/** @brief Indicates the premultiplication state of a clip or image + + - Type - string X 1 + - Property Set - clip instance (read only), image instance (read only), out args property in the ::kOfxImageEffectActionGetClipPreferences action (read/write) + - Valid Values - This must be one of + - kOfxImageOpaque - the image is opaque and so has no premultiplication state + - kOfxImagePreMultiplied - the image is premultiplied by its alpha + - kOfxImageUnPreMultiplied - the image is unpremultiplied + +See the documentation on clip preferences for more details on how this is used with the ::kOfxImageEffectActionGetClipPreferences action. +*/ +#define kOfxImageEffectPropPreMultiplication "OfxImageEffectPropPreMultiplication" + +/** Used to flag the alpha of an image as opaque */ +#define kOfxImageOpaque "OfxImageOpaque" + +/** Used to flag an image as premultiplied */ +#define kOfxImagePreMultiplied "OfxImageAlphaPremultiplied" + +/** Used to flag an image as unpremultiplied */ +#define kOfxImageUnPreMultiplied "OfxImageAlphaUnPremultiplied" + + +/** @brief Indicates the bit depths support by a plug-in or host + + - Type - string X N + - Property Set - host descriptor (read only), plugin descriptor (read/write) + - Default - plugin descriptor none set + - Valid Values - This must be one of + - kOfxBitDepthNone (implying a clip is unconnected, not valid for an image) + - kOfxBitDepthByte + - kOfxBitDepthShort + - kOfxBitDepthHalf + - kOfxBitDepthFloat + +The default for a plugin is to have none set, the plugin \em must define at least one in its describe action. +*/ +#define kOfxImageEffectPropSupportedPixelDepths "OfxImageEffectPropSupportedPixelDepths" + +/** @brief Indicates the components supported by a clip or host, + + - Type - string X N + - Property Set - host descriptor (read only), clip descriptor (read/write) + - Valid Values - This must be one of + - kOfxImageComponentNone (implying a clip is unconnected) + - kOfxImageComponentRGBA + - kOfxImageComponentRGB + - kOfxImageComponentAlpha + +This list of strings indicate what component types are supported by a host or are expected as input to a clip. + +The default for a clip descriptor is to have none set, the plugin \em must define at least one in its define function +*/ +#define kOfxImageEffectPropSupportedComponents "OfxImageEffectPropSupportedComponents" + +/** @brief Indicates if a clip is optional. + + - Type - int X 1 + - Property Set - clip descriptor (read/write) + - Default - 0 + - Valid Values - This must be one of 0 or 1 + +*/ +#define kOfxImageClipPropOptional "OfxImageClipPropOptional" + +/** @brief Indicates that a clip is intended to be used as a mask input + + - Type - int X 1 + - Property Set - clip descriptor (read/write) + - Default - 0 + - Valid Values - This must be one of 0 or 1 + +Set this property on any clip which will only ever have single channel alpha images fetched from it. Typically on an optional clip such as a junk matte in a keyer. + +This property acts as a hint to hosts indicating that they could feed the effect from a rotoshape (or similar) rather than an 'ordinary' clip. +*/ +#define kOfxImageClipPropIsMask "OfxImageClipPropIsMask" + + +/** @brief The pixel aspect ratio of a clip or image. + + - Type - double X 1 + - Property Set - clip instance (read only), image instance (read only) and ::kOfxImageEffectActionGetClipPreferences action out args property (read/write) + +*/ +#define kOfxImagePropPixelAspectRatio "OfxImagePropPixelAspectRatio" + +/** @brief The frame rate of a clip or instance's project. + + - Type - double X 1 + - Property Set - clip instance (read only), effect instance (read only) and ::kOfxImageEffectActionGetClipPreferences action out args property (read/write) + +For an input clip this is the frame rate of the clip. + +For an output clip, the frame rate mapped via pixel preferences. + +For an instance, this is the frame rate of the project the effect is in. + +For the outargs property in the ::kOfxImageEffectActionGetClipPreferences action, it is used to change the frame rate of the ouput clip. +*/ +#define kOfxImageEffectPropFrameRate "OfxImageEffectPropFrameRate" + +/** @brief Indicates the original unmapped frame rate (frames/second) of a clip + + - Type - double X 1 + - Property Set - clip instance (read only), + +If a plugin changes the output frame rate in the pixel preferences action, this property allows a plugin to get to the original value. +*/ +#define kOfxImageEffectPropUnmappedFrameRate "OfxImageEffectPropUnmappedFrameRate" + +/** @brief The frame step used for a sequence of renders + + - Type - double X 1 + - Property Set - an in argument for the ::kOfxImageEffectActionBeginSequenceRender action (read only) + - Valid Values - can be any positive value, but typically + - 1 for frame based material + - 0.5 for field based material +*/ +#define kOfxImageEffectPropFrameStep "OfxImageEffectPropFrameStep" + +/** @brief The frame range over which a clip has images. + + - Type - double X 2 + - Property Set - clip instance (read only) + +Dimension 0 is the first frame for which the clip can produce valid data. + +Dimension 1 is the last frame for which the clip can produce valid data. +*/ +#define kOfxImageEffectPropFrameRange "OfxImageEffectPropFrameRange" + + +/** @brief The unmaped frame range over which an output clip has images. + + - Type - double X 2 + - Property Set - clip instance (read only) + +Dimension 0 is the first frame for which the clip can produce valid data. + +Dimension 1 is the last frame for which the clip can produce valid data. + +If a plugin changes the output frame rate in the pixel preferences action, it will affect the frame range +of the output clip, this property allows a plugin to get to the original value. +*/ +#define kOfxImageEffectPropUnmappedFrameRange "OfxImageEffectPropUnmappedFrameRange" + +/** @brief Says whether the clip is actually connected at the moment. + + - Type - int X 1 + - Property Set - clip instance (read only) + - Valid Values - This must be one of 0 or 1 + +An instance may have a clip may not be connected to an object that can produce image data. Use this to find out. + +Any clip that is not optional will \em always be connected during a render action. However, during interface actions, even non optional clips may be unconnected. + */ +#define kOfxImageClipPropConnected "OfxImageClipPropConnected" + +/** @brief Indicates whether an effect will generate different images from frame to frame. + + - Type - int X 1 + - Property Set - out argument to ::kOfxImageEffectActionGetClipPreferences action (read/write). + - Default - 0 + - Valid Values - This must be one of 0 or 1 + +This property indicates whether a plugin will generate a different image from frame to frame, even if no parameters +or input image changes. For example a generater that creates random noise pixel at each frame. + */ +#define kOfxImageEffectFrameVarying "OfxImageEffectFrameVarying" + +/** @brief The proxy render scale currently being applied. + + - Type - double X 2 + - Property Set - an image instance (read only) and as read only an in argument on the following actions, + - ::kOfxImageEffectActionRender + - ::kOfxImageEffectActionBeginSequenceRender + - ::kOfxImageEffectActionEndSequenceRender + - ::kOfxImageEffectActionIsIdentity + - ::kOfxImageEffectActionGetRegionOfDefinition + - ::kOfxImageEffectActionGetRegionsOfInterest + - ::kOfxActionInstanceChanged + - ::kOfxInteractActionDraw + - ::kOfxInteractActionPenMotion + - ::kOfxInteractActionPenDown + - ::kOfxInteractActionPenUp + - ::kOfxInteractActionKeyDown + - ::kOfxInteractActionKeyUp + - ::kOfxInteractActionKeyRepeat + - ::kOfxInteractActionGainFocus + - ::kOfxInteractActionLoseFocus + +This should be applied to any spatial parameters to position them correctly. Not that the 'x' value does not include any pixel aspect ratios. +*/ +#define kOfxImageEffectPropRenderScale "OfxImageEffectPropRenderScale" + +/** @brief Indicates whether an effect can take quality shortcuts to improve speed. + + - Type - int X 1 + - Property Set - render calls, host (read-only) + - Default - 0 - 0: Best Quality (1: Draft) + - Valid Values - This must be one of 0 or 1 + +This property indicates that the host provides the plug-in the option to render in Draft/Preview mode. This is useful for applications that must support fast scrubbing. These allow a plug-in to take short-cuts for improved performance when the situation allows and it makes sense, for example to generate thumbnails with effects applied. +For example switch to a cheaper interpolation type or rendering mode. A plugin should expect frames rendered in this manner that will not be stucked in host cache unless the cache is only used in the same draft situations. +If an host does not support that property a value of 0 is assumed. +Also note that some hosts do implement kOfxImageEffectPropRenderScale - these two properties can be used independently. + */ +#define kOfxImageEffectPropRenderQualityDraft "OfxImageEffectPropRenderQualityDraft" + +/** @brief The extent of the current project in canonical coordinates. + + - Type - double X 2 + - Property Set - a plugin instance (read only) + +The extent is the size of the 'output' for the current project. See \ref NormalisedCoordinateSystem for more infomation on the project extent. + +The extent is in canonical coordinates and only returns the top right position, as the extent is always rooted at 0,0. + +For example a PAL SD project would have an extent of 768, 576. + */ +#define kOfxImageEffectPropProjectExtent "OfxImageEffectPropProjectExtent" + +/** @brief The size of the current project in canonical coordinates. + + - Type - double X 2 + - Property Set - a plugin instance (read only) + +The size of a project is a sub set of the ::kOfxImageEffectPropProjectExtent. For example a project may be a PAL SD project, but only be a letter-box within that. The project size is the size of this sub window. + +The project size is in canonical coordinates. + +See \ref NormalisedCoordinateSystem for more infomation on the project extent. + */ +#define kOfxImageEffectPropProjectSize "OfxImageEffectPropProjectSize" + +/** @brief The offset of the current project in canonical coordinates. + + - Type - double X 2 + - Property Set - a plugin instance (read only) + +The offset is related to the ::kOfxImageEffectPropProjectSize and is the offset from the origin of the project 'subwindow'. + +For example for a PAL SD project that is in letterbox form, the project offset is the offset to the bottom left hand corner of the letter box. + +The project offset is in canonical coordinates. + +See \ref NormalisedCoordinateSystem for more infomation on the project extent. +*/ +#define kOfxImageEffectPropProjectOffset "OfxImageEffectPropProjectOffset" + +/** @brief The pixel aspect ratio of the current project + + - Type - double X 1 + - Property Set - a plugin instance (read only) + + */ +#define kOfxImageEffectPropProjectPixelAspectRatio "OfxImageEffectPropPixelAspectRatio" + +/** @brief The duration of the effect + + - Type - double X 1 + - Property Set - a plugin instance (read only) + +This contains the duration of the plug-in effect, in frames. + */ +#define kOfxImageEffectInstancePropEffectDuration "OfxImageEffectInstancePropEffectDuration" + +/** @brief Which spatial field occurs temporally first in a frame. + + - Type - string X 1 + - Property Set - a clip instance (read only) + - Valid Values - This must be one of + - ::kOfxImageFieldNone - the material is unfielded + - ::kOfxImageFieldLower - the material is fielded, with image rows 0,2,4.... occuring first in a frame + - ::kOfxImageFieldUpper - the material is fielded, with image rows line 1,3,5.... occuring first in a frame + */ +#define kOfxImageClipPropFieldOrder "OfxImageClipPropFieldOrder" + +/** @brief The pixel data pointer of an image. + + - Type - pointer X 1 + - Property Set - an image instance (read only) + +This property contains one of: + - a pointer to memory that is the lower left hand corner of an image + - a pointer to CUDA memory, if the Render action arguments includes kOfxImageEffectPropCudaEnabled=1 + - an id, if the Render action arguments includes kOfxImageEffectPropMetalEnabled=1 + - a cl_mem, if the Render action arguments includes kOfxImageEffectPropOpenCLEnabled=1 + +See \ref kOfxImageEffectPropCudaEnabled, \ref kOfxImageEffectPropMetalEnabled and \ref kOfxImageEffectPropOpenCLEnabled +*/ +#define kOfxImagePropData "OfxImagePropData" + +/** @brief The bounds of an image's pixels. + + - Type - integer X 4 + - Property Set - an image instance (read only) + +The bounds, in \ref PixelCoordinates, are of the addressable pixels in an image's data pointer. + +The order of the values is x1, y1, x2, y2. + +X values are x1 <= X < x2 +Y values are y1 <= Y < y2 + +For less than full frame images, the pixel bounds will be contained by the ::kOfxImagePropRegionOfDefinition bounds. + */ +#define kOfxImagePropBounds "OfxImagePropBounds" + +/** @brief The full region of definition of an image. + + - Type - integer X 4 + - Property Set - an image instance (read only) + +An image's region of definition, in \ref PixelCoordinates, is the full frame area of the image plane that the image covers. + +The order of the values is x1, y1, x2, y2. + +X values are x1 <= X < x2 +Y values are y1 <= Y < y2 + +The ::kOfxImagePropBounds property contains the actuall addressable pixels in an image, which may be less than its full region of definition. + */ +#define kOfxImagePropRegionOfDefinition "OfxImagePropRegionOfDefinition" + +/** @brief The number of bytes in a row of an image. + + - Type - integer X 1 + - Property Set - an image instance (read only) + +For various alignment reasons, a row of pixels may need to be padded at the end with several bytes before the next row starts in memory. + +This property indicates the number of bytes in a row of pixels. This will be at least sizeof(PIXEL) * (bounds.x2-bounds.x1). Where bounds +is fetched from the ::kOfxImagePropBounds property. + +Note that (for CPU images only, not CUDA/Metal/OpenCL Buffers, nor OpenGL textures accessed via the OpenGL Render Suite) row bytes can be negative, which allows hosts with a native top down row order to pass image into OFX without having to repack pixels. +Row bytes is not supported for OpenCL Images. + */ +#define kOfxImagePropRowBytes "OfxImagePropRowBytes" + + +/** @brief Which fields are present in the image + + - Type - string X 1 + - Property Set - an image instance (read only) + - Valid Values - This must be one of + - ::kOfxImageFieldNone - the image is an unfielded frame + - ::kOfxImageFieldBoth - the image is fielded and contains both interlaced fields + - ::kOfxImageFieldLower - the image is fielded and contains a single field, being the lower field (rows 0,2,4...) + - ::kOfxImageFieldUpper - the image is fielded and contains a single field, being the upper field (rows 1,3,5...) + + */ +#define kOfxImagePropField "OfxImagePropField" + +/** @brief Controls how a plugin renders fielded footage. + + - Type - integer X 1 + - Property Set - a plugin descriptor (read/write) + - Default - 1 + - Valid Values - This must be one of + - 0 - the plugin is to have its render function called twice, only if there is animation in any of its parameters + - 1 - the plugin is to have its render function called twice always +*/ +#define kOfxImageEffectPluginPropFieldRenderTwiceAlways "OfxImageEffectPluginPropFieldRenderTwiceAlways" + +/** @brief Controls how a plugin fetched fielded imagery from a clip. + + - Type - string X 1 + - Property Set - a clip descriptor (read/write) + - Default - kOfxImageFieldDoubled + - Valid Values - This must be one of + - kOfxImageFieldBoth - fetch a full frame interlaced image + - kOfxImageFieldSingle - fetch a single field, making a half height image + - kOfxImageFieldDoubled - fetch a single field, but doubling each line and so making a full height image + +This controls how a plug-in wishes to fetch images from a fielded clip, so it can tune it behaviour when it renders fielded footage. + +Note that if it fetches kOfxImageFieldSingle and the host stores images natively as both fields interlaced, it can return a single image by doubling rowbytes and tweaking the starting address of the image data. This saves on a buffer copy. + */ +#define kOfxImageClipPropFieldExtraction "OfxImageClipPropFieldExtraction" + +/** @brief Indicates which field is being rendered. + + - Type - string X 1 + - Property Set - a read only in argument property to ::kOfxImageEffectActionRender and ::kOfxImageEffectActionIsIdentity + - Valid Values - this must be one of + - kOfxImageFieldNone - there are no fields to deal with, all images are full frame + - kOfxImageFieldBoth - the imagery is fielded and both scan lines should be renderred + - kOfxImageFieldLower - the lower field is being rendered (lines 0,2,4...) + - kOfxImageFieldUpper - the upper field is being rendered (lines 1,3,5...) + */ +#define kOfxImageEffectPropFieldToRender "OfxImageEffectPropFieldToRender" + +/** @brief Used to indicate the region of definition of a plug-in + + - Type - double X 4 + - Property Set - a read/write out argument property to the ::kOfxImageEffectActionGetRegionOfDefinition action + - Default - see ::kOfxImageEffectActionGetRegionOfDefinition + +The order of the values is x1, y1, x2, y2. + +This will be in \ref CanonicalCoordinates + */ +#define kOfxImageEffectPropRegionOfDefinition "OfxImageEffectPropRegionOfDefinition" + +/** @brief The value of a region of interest. + + - Type - double X 4 + - Property Set - a read only in argument property to the ::kOfxImageEffectActionGetRegionsOfInterest action + +A host passes this value into the region of interest action to specify the region it is interested in rendering. + +The order of the values is x1, y1, x2, y2. + +This will be in \ref CanonicalCoordinates. + */ +#define kOfxImageEffectPropRegionOfInterest "OfxImageEffectPropRegionOfInterest" + +/** @brief The region to be rendered. + + - Type - integer X 4 + - Property Set - a read only in argument property to the ::kOfxImageEffectActionRender and ::kOfxImageEffectActionIsIdentity actions + +The order of the values is x1, y1, x2, y2. + +This will be in \ref PixelCoordinates + + */ +#define kOfxImageEffectPropRenderWindow "OfxImageEffectPropRenderWindow" + +/** String used to label imagery as having no fields */ +#define kOfxImageFieldNone "OfxFieldNone" +/** String used to label the lower field (scan lines 0,2,4...) of fielded imagery */ +#define kOfxImageFieldLower "OfxFieldLower" +/** String used to label the upper field (scan lines 1,3,5...) of fielded imagery */ +#define kOfxImageFieldUpper "OfxFieldUpper" +/** String used to label both fields of fielded imagery, indicating interlaced footage */ +#define kOfxImageFieldBoth "OfxFieldBoth" +/** String used to label an image that consists of a single field, and so is half height */ +#define kOfxImageFieldSingle "OfxFieldSingle" +/** String used to label an image that consists of a single field, but each scan line is double, + and so is full height */ +#define kOfxImageFieldDoubled "OfxFieldDoubled" + +/*@}*/ +/*@}*/ + +/** @brief String that is the name of the standard OFX output clip */ +#define kOfxImageEffectOutputClipName "Output" + +/** @brief String that is the name of the standard OFX single source input clip */ +#define kOfxImageEffectSimpleSourceClipName "Source" + +/** @brief String that is the name of the 'from' clip in the OFX transition context */ +#define kOfxImageEffectTransitionSourceFromClipName "SourceFrom" + +/** @brief String that is the name of the 'from' clip in the OFX transition context */ +#define kOfxImageEffectTransitionSourceToClipName "SourceTo" + +/** @brief the name of the mandated 'Transition' param for the transition context */ +#define kOfxImageEffectTransitionParamName "Transition" + +/** @brief the name of the mandated 'SourceTime' param for the retime context */ +#define kOfxImageEffectRetimerParamName "SourceTime" + + + + +/** @brief the string that names image effect suites, passed to OfxHost::fetchSuite */ +#define kOfxImageEffectSuite "OfxImageEffectSuite" + +/** @brief The OFX suite for image effects + +This suite provides the functions needed by a plugin to defined and use an image effect plugin. + */ +typedef struct OfxImageEffectSuiteV1 { + /** @brief Retrieves the property set for the given image effect + + \arg \c imageEffect image effect to get the property set for + \arg \c propHandle pointer to a the property set pointer, value is returned here + + The property handle is for the duration of the image effect handle. + + @returns + - ::kOfxStatOK - the property set was found and returned + - ::kOfxStatErrBadHandle - if the paramter handle was invalid + - ::kOfxStatErrUnknown - if the type is unknown + */ + OfxStatus (*getPropertySet)(OfxImageEffectHandle imageEffect, + OfxPropertySetHandle *propHandle); + + /** @brief Retrieves the parameter set for the given image effect + + \arg \c imageEffect image effect to get the property set for + \arg \c paramSet pointer to a the parameter set, value is returned here + + The param set handle is valid for the lifetime of the image effect handle. + + @returns + - ::kOfxStatOK - the property set was found and returned + - ::kOfxStatErrBadHandle - if the paramter handle was invalid + - ::kOfxStatErrUnknown - if the type is unknown + */ + OfxStatus (*getParamSet)(OfxImageEffectHandle imageEffect, + OfxParamSetHandle *paramSet); + + + /** @brief Define a clip to the effect. + + \arg \c pluginHandle handle passed into 'describeInContext' action + \arg \c name unique name of the clip to define + \arg \c propertySet property handle for the clip descriptor will be returned here + + This function defines a clip to a host, the returned property set is used to describe + various aspects of the clip to the host. Note that this does not create a clip instance. + +\pre + - we are inside the describe in context action. + + @returns + */ + OfxStatus (*clipDefine)(OfxImageEffectHandle imageEffect, + const char *name, + OfxPropertySetHandle *propertySet); + + /** @brief Get the propery handle of the named input clip in the given instance + + \arg \c imageEffect an instance handle to the plugin + \arg \c name name of the clip, previously used in a clip define call + \arg \c clip where to return the clip + \arg \c propertySet if not NULL, the descriptor handle for a parameter's property set will be placed here. + + The propertySet will have the same value as would be returned by OfxImageEffectSuiteV1::clipGetPropertySet + + This return a clip handle for the given instance, note that this will \em not be the same as the + clip handle returned by clipDefine and will be distanct to clip handles in any other instance + of the plugin. + + Not a valid call in any of the describe actions. + +\pre + - create instance action called, + - \e name passed to clipDefine for this context, + - not inside describe or describe in context actions. + +\post + - handle will be valid for the life time of the instance. + + */ + OfxStatus (*clipGetHandle)(OfxImageEffectHandle imageEffect, + const char *name, + OfxImageClipHandle *clip, + OfxPropertySetHandle *propertySet); + + /** @brief Retrieves the property set for a given clip + + \arg \c clip clip effect to get the property set for + \arg \c propHandle pointer to a the property set handle, value is returedn her + + The property handle is valid for the lifetime of the clip, which is generally the lifetime of the instance. + + @returns + - ::kOfxStatOK - the property set was found and returned + - ::kOfxStatErrBadHandle - if the paramter handle was invalid + - ::kOfxStatErrUnknown - if the type is unknown + */ + OfxStatus (*clipGetPropertySet)(OfxImageClipHandle clip, + OfxPropertySetHandle *propHandle); + + /** @brief Get a handle for an image in a clip at the indicated time and indicated region + + \arg \c clip clip to extract the image from + \arg \c time time to fetch the image at + \arg \c region region to fetch the image from (optional, set to NULL to get a 'default' region) + this is in the \ref CanonicalCoordinates. + \arg \c imageHandle property set containing the image's data + + An image is fetched from a clip at the indicated time for the given region and returned in the imageHandle. + + If the \e region parameter is not set to NULL, then it will be clipped to the clip's Region of Definition for the given time. The returned image will be \em at \em least as big as this region. If the region parameter is not set, then the region fetched will be at least the Region of Interest the effect has previously specified, clipped the clip's Region of Definition. + +If clipGetImage is called twice with the same parameters, then two separate image handles will be returned, each of which must be release. The underlying implementation could share image data pointers and use reference counting to maintain them. + +\pre + - clip was returned by clipGetHandle + +\post + - image handle is only valid for the duration of the action clipGetImage is called in + - image handle to be disposed of by clipReleaseImage before the action returns + +@returns +- ::kOfxStatOK - the image was successfully fetched and returned in the handle, +- ::kOfxStatFailed - the image could not be fetched because it does not exist in the clip at the indicated time and/or region, the plugin + should continue operation, but assume the image was black and transparent. +- ::kOfxStatErrBadHandle - the clip handle was invalid, +- ::kOfxStatErrMemory - the host had not enough memory to complete the operation, plugin should abort whatever it was doing. + + */ + OfxStatus (*clipGetImage)(OfxImageClipHandle clip, + OfxTime time, + const OfxRectD *region, + OfxPropertySetHandle *imageHandle); + + /** @brief Releases the image handle previously returned by clipGetImage + + +\pre + - imageHandle was returned by clipGetImage + +\post + - all operations on imageHandle will be invalid + +@returns +- ::kOfxStatOK - the image was successfully fetched and returned in the handle, +- ::kOfxStatErrBadHandle - the image handle was invalid, + */ + OfxStatus (*clipReleaseImage)(OfxPropertySetHandle imageHandle); + + + /** @brief Returns the spatial region of definition of the clip at the given time + + \arg \c clipHandle clip to extract the image from + \arg \c time time to fetch the image at + \arg \c region region to fetch the image from (optional, set to NULL to get a 'default' region) + this is in the \ref CanonicalCoordinates. + \arg \c imageHandle handle where the image is returned + + An image is fetched from a clip at the indicated time for the given region and returned in the imageHandle. + + If the \e region parameter is not set to NULL, then it will be clipped to the clip's Region of Definition for the given time. The returned image will be \em at \em least as big as this region. If the region parameter is not set, then the region fetched will be at least the Region of Interest the effect has previously specified, clipped the clip's Region of Definition. + +\pre + - clipHandle was returned by clipGetHandle + +\post + - bounds will be filled the RoD of the clip at the indicated time + +@returns +- ::kOfxStatOK - the image was successfully fetched and returned in the handle, +- ::kOfxStatFailed - the image could not be fetched because it does not exist in the clip at the indicated time, the plugin + should continue operation, but assume the image was black and transparent. +- ::kOfxStatErrBadHandle - the clip handle was invalid, +- ::kOfxStatErrMemory - the host had not enough memory to complete the operation, plugin should abort whatever it was doing. + + + */ + OfxStatus (*clipGetRegionOfDefinition)(OfxImageClipHandle clip, + OfxTime time, + OfxRectD *bounds); + + /** @brief Returns whether to abort processing or not. + + \arg \c imageEffect instance of the image effect + + A host may want to signal to a plugin that it should stop whatever rendering it is doing and start again. + Generally this is done in interactive threads in response to users tweaking some parameter. + + This function indicates whether a plugin should stop whatever processing it is doing. + + @returns + - 0 if the effect should continue whatever processing it is doing + - 1 if the effect should abort whatever processing it is doing + */ + int (*abort)(OfxImageEffectHandle imageEffect); + + /** @brief Allocate memory from the host's image memory pool + + \arg \c instanceHandle effect instance to associate with this memory allocation, may be NULL. + \arg \c nBytes number of bytes to allocate + \arg \c memoryHandle pointer to the memory handle where a return value is placed + + Memory handles allocated by this should be freed by OfxImageEffectSuiteV1::imageMemoryFree. + To access the memory behind the handle you need to call OfxImageEffectSuiteV1::imageMemoryLock. + + See \ref ImageEffectsMemoryAllocation. + + @returns + - kOfxStatOK if all went well, a valid memory handle is placed in \e memoryHandle + - kOfxStatErrBadHandle if instanceHandle is not valid, memoryHandle is set to NULL + - kOfxStatErrMemory if there was not enough memory to satisfy the call, memoryHandle is set to NULL + */ + OfxStatus (*imageMemoryAlloc)(OfxImageEffectHandle instanceHandle, + size_t nBytes, + OfxImageMemoryHandle *memoryHandle); + + /** @brief Frees a memory handle and associated memory. + + \arg \c memoryHandle memory handle returned by imageMemoryAlloc + + This function frees a memory handle and associated memory that was previously allocated via OfxImageEffectSuiteV1::imageMemoryAlloc + + If there are outstanding locks, these are ignored and the handle and memory are freed anyway. + + See \ref ImageEffectsMemoryAllocation. + + @returns + - kOfxStatOK if the memory was cleanly deleted + - kOfxStatErrBadHandle if the value of \e memoryHandle was not a valid pointer returned by OfxImageEffectSuiteV1::imageMemoryAlloc + */ + OfxStatus (*imageMemoryFree)(OfxImageMemoryHandle memoryHandle); + + /** @brief Lock the memory associated with a memory handle and make it available for use. + + \arg \c memoryHandle memory handle returned by imageMemoryAlloc + \arg \c returnedPtr where to the pointer to the locked memory + + This function locks them memory associated with a memory handle and returns a pointer to it. The memory will be 16 byte aligned, to allow use of vector operations. + + Note that memory locks and unlocks nest. + + After the first lock call, the contents of the memory pointer to by \e returnedPtr is undefined. All subsequent calls to lock will return memory with the same contents as the previous call. + + Also, if unlocked, then relocked, the memory associated with a memory handle may be at a different address. + + See also OfxImageEffectSuiteV1::imageMemoryUnlock and \ref ImageEffectsMemoryAllocation. + + @returns + - kOfxStatOK if the memory was locked, a pointer is placed in \e returnedPtr + - kOfxStatErrBadHandle if the value of \e memoryHandle was not a valid pointer returned by OfxImageEffectSuiteV1::imageMemoryAlloc, null is placed in \e *returnedPtr + - kOfxStatErrMemory if there was not enough memory to satisfy the call, \e *returnedPtr is set to NULL + */ + OfxStatus (*imageMemoryLock)(OfxImageMemoryHandle memoryHandle, + void **returnedPtr); + + /** @brief Unlock allocated image data + + \arg \c allocatedData pointer to memory previously returned by OfxImageEffectSuiteV1::imageAlloc + + This function unlocks a previously locked memory handle. Once completely unlocked, memory associated with a memoryHandle is no longer available for use. Attempting to use it results in undefined behaviour. + + Note that locks and unlocks nest, and to fully unlock memory you need to match the count of locks placed upon it. + + Also note, if you unlock a completely unlocked handle, it has no effect (ie: the lock count can't be negative). + + If unlocked, then relocked, the memory associated with a memory handle may be at a different address, however the contents will remain the same. + + See also OfxImageEffectSuiteV1::imageMemoryLock and \ref ImageEffectsMemoryAllocation. + + @returns + - kOfxStatOK if the memory was unlocked cleanly, + - kOfxStatErrBadHandle if the value of \e memoryHandle was not a valid pointer returned by OfxImageEffectSuiteV1::imageMemoryAlloc, null is placed in \e *returnedPtr + */ + OfxStatus (*imageMemoryUnlock)(OfxImageMemoryHandle memoryHandle); + +} OfxImageEffectSuiteV1; + + + +/** + \addtogroup StatusCodes +*/ +/*@{*/ +/** + \defgroup StatusCodesImageEffect Image Effect API Status Codes + +These are status codes returned by functions in the OfxImageEffectSuite and Image Effect plugin functions. + +They range from 1000 until 1999 +*/ +/*@{*/ +/** @brief Error code for incorrect image formats */ +#define kOfxStatErrImageFormat ((int) 1000) + + +/*@}*/ +/*@}*/ + +#ifdef __cplusplus +} +#endif + + +#endif + diff --git a/src/modules/openfx/ofxInteract.h b/src/modules/openfx/ofxInteract.h new file mode 100644 index 000000000..3acc6d338 --- /dev/null +++ b/src/modules/openfx/ofxInteract.h @@ -0,0 +1,548 @@ +#ifndef _ofxInteract_h_ +#define _ofxInteract_h_ + +#include "ofxCore.h" + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + + +#ifdef __cplusplus +extern "C" { +#endif + +/** @file ofxInteract.h +Contains the API for ofx plugin defined GUIs and interaction. +*/ + +#define kOfxInteractSuite "OfxInteractSuite" + + +/** @brief Blind declaration of an OFX interactive gui +*/ +typedef struct OfxInteract *OfxInteractHandle; + +/** + \addtogroup PropertiesAll +*/ +/*@{*/ +/** + \defgroup PropertiesInteract Interact Property Definitions + +These are the list of properties used by the Interact API documented in \ref CustomInteractionPage. +*/ +/*@{*/ +/** @brief The set of parameters on which a value change will trigger a redraw for an interact. + + - Type - string X N + - Property Set - interact instance property (read/write) + - Default - no values set + - Valid Values - the name of any parameter associated with this interact. + +If the interact is representing the state of some set of OFX parameters, then is will +need to be redrawn if any of those parameters' values change. This multi-dimensional property +links such parameters to the interact. + +The interact can be slaved to multiple parameters (setting index 0, then index 1 etc...) + */ +#define kOfxInteractPropSlaveToParam "OfxInteractPropSlaveToParam" + +/** @brief The size of a real screen pixel under the interact's canonical projection. + + - Type - double X 2 + - Property Set - interact instance and actions (read only) + + */ +#define kOfxInteractPropPixelScale "OfxInteractPropPixelScale" + + + +/** @brief The background colour of the application behind an interact instance + + - Type - double X 3 + - Property Set - read only on the interact instance and in argument to the ::kOfxInteractActionDraw action + - Valid Values - from 0 to 1 + +The components are in the order red, green then blue. + + */ +#define kOfxInteractPropBackgroundColour "OfxInteractPropBackgroundColour" + +/** @brief The suggested colour to draw a widget in an interact, typically for overlays. + + - Type - double X 3 + - Property Set - read only on the interact instance + - Default - 1.0 + - Valid Values - greater than or equal to 0.0 + +Some applications allow the user to specify colours of any overlay via a colour picker, this +property represents the value of that colour. Plugins are at liberty to use this or not when +they draw an overlay. + +If a host does not support such a colour, it should return kOfxStatReplyDefault +*/ +#define kOfxInteractPropSuggestedColour "OfxInteractPropSuggestedColour" + +/** @brief The position of the pen in an interact. + + - Type - double X 2 + - Property Set - read only in argument to the ::kOfxInteractActionPenMotion, ::kOfxInteractActionPenDown and ::kOfxInteractActionPenUp actions + +This value passes the postion of the pen into an interact. This is in the interact's canonical coordinates. + */ +#define kOfxInteractPropPenPosition "OfxInteractPropPenPosition" + +/** @brief The position of the pen in an interact in viewport coordinates. + + - Type - int X 2 + - Property Set - read only in argument to the ::kOfxInteractActionPenMotion, ::kOfxInteractActionPenDown and ::kOfxInteractActionPenUp actions + +This value passes the postion of the pen into an interact. This is in the interact's openGL viewport coordinates, with 0,0 being at the bottom left. + */ +#define kOfxInteractPropPenViewportPosition "OfxInteractPropPenViewportPosition" + +/** @brief The pressure of the pen in an interact. + + - Type - double X 1 + - Property Set - read only in argument to the ::kOfxInteractActionPenMotion, ::kOfxInteractActionPenDown and ::kOfxInteractActionPenUp actions + - Valid Values - from 0 (no pressure) to 1 (maximum pressure) + +This is used to indicate the status of the 'pen' in an interact. If a pen has only two states (eg: a mouse button), these should map to 0.0 and 1.0. + */ +#define kOfxInteractPropPenPressure "OfxInteractPropPenPressure" + +/** @brief Indicates whether the dits per component in the interact's openGL frame buffer + + - Type - int X 1 + - Property Set - interact instance and descriptor (read only) + + */ +#define kOfxInteractPropBitDepth "OfxInteractPropBitDepth" + +/** @brief Indicates whether the interact's frame buffer has an alpha component or not + + - Type - int X 1 + - Property Set - interact instance and descriptor (read only) + - Valid Values - This must be one of + - 0 indicates no alpha component + - 1 indicates an alpha component + */ +#define kOfxInteractPropHasAlpha "OfxInteractPropHasAlpha" + +/*@}*/ +/*@}*/ + +/** + \addtogroup ActionsAll +*/ +/*@{*/ +/** + \defgroup InteractActions Interact Actions + +These are the list of actions passed to an interact's entry point function. For more details on how to deal with actions, see \ref InteractActions. +*/ +/*@{*/ + +/** @brief + + This action is the first action passed to an interact. It is + where an interact defines how it behaves and the resources it needs to + function. + If not trapped, the default action is for the host to carry on as normal + Note that the handle passed in acts as a descriptor for, rather than an + instance of the interact. + + @param handle handle to the interact descriptor, cast to an \ref OfxInteractHandle + @param inArgs is redundant and is set to NULL + @param outArgs is redundant and is set to NULL + + + \pre + - The plugin has been loaded and the effect described. + + @returns + - \ref kOfxStatOK the action was trapped and all was well + - \ref kOfxStatErrMemory in which case describe may be called again after a memory purge + - \ref kOfxStatFailed something was wrong, the host should ignore the interact + - \ref kOfxStatErrFatal + */ +#define kOfxActionDescribeInteract kOfxActionDescribe + + +/** @brief + + This action is the first action passed to an interact instance after its creation. + It is there to allow a plugin to create any per-instance data structures it may need. + + @param handle handle to the interact instance, cast to an \ref OfxInteractHandle + @param inArgs is redundant and is set to NULL + @param outArgs is redundant and is set to NULL + + + \pre + - \ref kOfxActionDescribe has been called on this interact + + \post + - the instance pointer will be valid until the \ref kOfxActionDestroyInstance + action is passed to the plug-in with the same instance handle + + @returns + - \ref kOfxStatOK the action was trapped and all was well + - \ref kOfxStatReplyDefault the action was ignored, but all was well anyway + - \ref kOfxStatErrFatal + - \ref kOfxStatErrMemory in which case this may be called again after a memory purge + - \ref kOfxStatFailed in which case the host should ignore this interact + */ +#define kOfxActionCreateInstanceInteract kOfxActionCreateInstance + +/**@brief + + This action is the last passed to an interact's instance before its + destruction. It is there to allow a plugin to destroy any per-instance + data structures it may have created. + + @param handle handle to the interact instance, cast to an \ref OfxInteractHandle + @param inArgs is redundant and is set to NULL + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance + has been called on the handle, + - the instance has not had any of its members destroyed yet + + \post + - the instance pointer is no longer valid and any operation on it will be undefined + + @returns + To some extent, what is returned is moot, a bit like throwing an + exception in a C++ destructor, so the host should continue destruction + of the instance regardless + - \ref kOfxStatOK the action was trapped and all was well + - \ref kOfxStatReplyDefault the action was ignored as the effect had nothing to do + - \ref kOfxStatErrFatal + - \ref kOfxStatFailed something went wrong, but no error code appropriate. + */ +#define kOfxActionDestroyInstanceInteract kOfxActionDestroyInstance + +/** @brief + + This action is issued to an interact whenever the host needs the plugin + to redraw the given interact. + + The interact should either issue OpenGL calls to draw itself, or use DrawSuite calls. + + If this is called via kOfxImageEffectPluginPropOverlayInteractV2, drawing MUST use DrawSuite. + + If this is called via kOfxImageEffectPluginPropOverlayInteractV1, drawing SHOULD use OpenGL. Some existing plugins may use DrawSuite via kOfxImageEffectPluginPropOverlayInteractV1 if it's supported by the host, but this is discouraged. + + Note that the interact may (in the case of custom parameter GUIS) or may + not (in the case of image effect overlays) be required to swap buffers, + that is up to the kind of interact. + + @param handle handle to an interact instance, cast to an \ref OfxInteractHandle + @param inArgs has the following properties on an image effect plugin + - \ref kOfxPropEffectInstance a handle to the effect for which the interact has been, + - \ref kOfxInteractPropPixelScale the scale factor to convert cannonical pixels to screen pixels + - \ref kOfxInteractPropBackgroundColour the background colour of the application behind the current view + - \ref kOfxPropTime the effect time at which changed occured + - \ref kOfxImageEffectPropRenderScale the render scale applied to any image fetched + + @param outArgs is redundant and is set to NULL + +\pre + - \ref kOfxActionCreateInstance has been called on the instance handle + - the openGL context for this interact has been set + - the projection matrix will correspond to the interact's cannonical view + + @returns + - \ref kOfxStatOK the action was trapped and all was well + - \ref kOfxStatReplyDefault the action was ignored + - \ref kOfxStatErrFatal + - \ref kOfxStatFailed something went wrong, the host should ignore this interact in future + */ +#define kOfxInteractActionDraw "OfxInteractActionDraw" + +/** @brief + + This action is issued whenever the pen moves an the interact's has + focus. It should be issued whether the pen is currently up or down. + No openGL calls should be issued by the plug-in during this action. + + + @param handle handle to an interact instance, cast to an \ref OfxInteractHandle + @param inArgs has the following properties on an image effect plugin + - \ref kOfxPropEffectInstance a handle to the effect for which the interact has been, + - \ref kOfxInteractPropPixelScale the scale factor to convert cannonical pixels to screen pixels + - \ref kOfxInteractPropBackgroundColour the background colour of the application behind the current view + - \ref kOfxPropTime the effect time at which changed occured + - \ref kOfxImageEffectPropRenderScale the render scale applied to any image fetched + - \ref kOfxInteractPropPenPosition postion of the pen in, + - \ref kOfxInteractPropPenViewportPosition position of the pen in, + - \ref kOfxInteractPropPenPressure the pressure of the pen, + + @param outArgs is redundant and is set to NULL + +\pre + - \ref kOfxActionCreateInstance + has been called on the instance handle + - the current instance handle has had + \ref kOfxInteractActionGainFocus called on it + +\post + - if the instance returns \ref kOfxStatOK the host should not + pass the pen motion to any other interactive object it may own that + shares the same view. + + @returns + - \ref kOfxStatOK the action was trapped and the host should not pass the event to other objects it may own + - \ref kOfxStatReplyDefault the action was not trapped and the host can deal with it if it wants + */ +#define kOfxInteractActionPenMotion "OfxInteractActionPenMotion" + +/**@brief + + This action is issued when a pen transitions for the 'up' to the 'down' + state. + No openGL calls should be issued by the plug-in during this action. + + + @param handle handle to an interact instance, cast to an \ref OfxInteractHandle + @param inArgs has the following properties on an image effect plugin, + - \ref kOfxPropEffectInstance a handle to the effect for which the interact has been, + - \ref kOfxInteractPropPixelScale the scale factor to convert cannonical pixels to screen pixels + - \ref kOfxInteractPropBackgroundColour the background colour of the application behind the current view + - \ref kOfxPropTime the effect time at which changed occured + - \ref kOfxImageEffectPropRenderScale the render scale applied to any image fetched + - \ref kOfxInteractPropPenPosition position of the pen in + - \ref kOfxInteractPropPenViewportPosition position of the pen in + - \ref kOfxInteractPropPenPressure the pressure of the pen + + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance + has been called on the instance handle, + - the current instance handle has had + \ref kOfxInteractActionGainFocus + called on it + +\post + - if the instance returns \ref kOfxStatOK, the host should not + pass the pen motion to any other interactive object it may own that + shares the same view. + + @returns + - \ref kOfxStatOK, the action was trapped and the host should not pass the event to other objects it may own + - \ref kOfxStatReplyDefault , the action was not trapped and the host can deal with it if it wants + */ +#define kOfxInteractActionPenDown "OfxInteractActionPenDown" + +/**@brief + + This action is issued when a pen transitions for the 'down' to the 'up' + state. + No openGL calls should be issued by the plug-in during this action. + + @param handle handle to an interact instance, cast to an \ref OfxInteractHandle + @param inArgs has the following properties on an image effect plugin, + - \ref kOfxPropEffectInstance a handle to the effect for which the interact has been, + - \ref kOfxInteractPropPixelScale the scale factor to convert cannonical pixels to screen pixels + - \ref kOfxInteractPropBackgroundColour the background colour of the application behind the current view + - \ref kOfxPropTime the effect time at which changed occured + - \ref kOfxImageEffectPropRenderScale the render scale applied to any image fetched + - \ref kOfxInteractPropPenPosition position of the pen in + - \ref kOfxInteractPropPenViewportPosition position of the pen in + - \ref kOfxInteractPropPenPressure the pressure of the pen + + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance + has been called on the instance handle, + - the current instance handle has had + \ref kOfxInteractActionGainFocus called on it + + \post + - if the instance returns \ref kOfxStatOK, the host should not + pass the pen motion to any other interactive object it may own that + shares the same view. + + @returns + - \ref kOfxStatOK, the action was trapped and the host should not pass the event to other objects it may own + - \ref kOfxStatReplyDefault , the action was not trapped and the host can deal with it if it wants + */ +#define kOfxInteractActionPenUp "OfxInteractActionPenUp" + +/**@brief + + This action is issued when a key on the keyboard is depressed. + No openGL calls should be issued by the plug-in during this action. + + @param handle handle to an interact instance, cast to an \ref OfxInteractHandle + @param inArgs has the following properties on an image effect plugin + - \ref kOfxPropEffectInstance a handle to the effect for which the interact has been, + - \ref kOfxPropKeySym single integer value representing the key that was manipulated, + this may not have a UTF8 representation (eg: a return key) + - \ref kOfxPropKeyString UTF8 string representing a character key that was pressed, some + keys have no UTF8 encoding, in which case this is "" + - \ref kOfxPropTime the effect time at which changed occured + - \ref kOfxImageEffectPropRenderScale the render scale applied to any image fetched + + @param outArgs is redundant and is set to NULL + +\pre + - \ref kOfxActionCreateInstance + has been called on the instance handle, + - the current instance handle has had + \ref kOfxInteractActionGainFocus called on it + + \post + - if the instance returns \ref kOfxStatOK, the host should not + pass the pen motion to any other interactive object it may own that + shares the same focus. + + @returns + - \ref kOfxStatOK , the action was trapped and the host should not pass the event to other objects it may own + - \ref kOfxStatReplyDefault , the action was not trapped and the host can deal with it if it wants + */ +#define kOfxInteractActionKeyDown "OfxInteractActionKeyDown" + +/**@brief + This action is issued when a key on the keyboard is released. + No openGL calls should be issued by the plug-in during this action. + + @param handle handle to an interact instance, cast to an \ref OfxInteractHandle + @param inArgs has the following properties on an image effect plugin + - \ref kOfxPropEffectInstance a handle to the effect for which the interact has been, + - \ref kOfxPropKeySym single integer value representing the key that was manipulated, + this may not have a UTF8 representation (eg: a return key) + - \ref kOfxPropKeyString UTF8 string representing a character key that was pressed, some + keys have no UTF8 encoding, in which case this is "" + - \ref kOfxPropTime the effect time at which changed occured + - \ref kOfxImageEffectPropRenderScale the render scale applied to any image fetched + + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance + has been called on the instance handle, + - the current instance handle has had + \ref kOfxInteractActionGainFocus called on it + + \post + - if the instance returns \ref kOfxStatOK, the host should not + pass the pen motion to any other interactive object it may own that + shares the same focus. + + @returns + - \ref kOfxStatOK , the action was trapped and the host should not pass the event to other objects it may own + - \ref kOfxStatReplyDefault , the action was not trapped and the host can deal with it if it wants + */ +#define kOfxInteractActionKeyUp "OfxInteractActionKeyUp" + +/**@brief + This action is issued when a key on the keyboard is repeated. + No openGL calls should be issued by the plug-in during this action. + + @param handle handle to an interact instance, cast to an \ref OfxInteractHandle + @param inArgs has the following properties on an image effect plugin + - \ref kOfxPropEffectInstance a handle to the effect for which the interact has been, + - \ref kOfxPropKeySym single integer value representing the key that was manipulated, + this may not have a UTF8 representation (eg: a return key) + - \ref kOfxPropKeyString UTF8 string representing a character key that was pressed, some + keys have no UTF8 encoding, in which case this is "" + - \ref kOfxPropTime the effect time at which changed occured + - \ref kOfxImageEffectPropRenderScale the render scale applied to any image fetched + + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance + has been called on the instance handle, + - the current instance handle has had + \ref kOfxInteractActionGainFocus called on it + + \post + - if the instance returns \ref kOfxStatOK, the host should not + pass the pen motion to any other interactive object it may own that + shares the same focus. + + @returns + - \ref kOfxStatOK , the action was trapped and the host should not pass the event to other objects it may own + - \ref kOfxStatReplyDefault , the action was not trapped and the host can deal with it if it wants + */ +#define kOfxInteractActionKeyRepeat "OfxInteractActionKeyRepeat" + +/**@brief + This action is issued when an interact gains input focus. + No openGL calls should be issued by the plug-in during this action. + + @param handle handle to an interact instance, cast to an \ref OfxInteractHandle + @param inArgs has the following properties on an image effect plugin + - \ref kOfxPropEffectInstance a handle to the effect for which the interact is being used on, + - \ref kOfxInteractPropPixelScale the scale factor to convert cannonical pixels to screen pixels, + - \ref kOfxInteractPropBackgroundColour the background colour of the application behind the current view + - \ref kOfxPropTime the effect time at which changed occured + - \ref kOfxImageEffectPropRenderScale the render scale applied to any image fetched + + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance + has been called on the instance handle, + + + @returns + - \ref kOfxStatOK the action was trapped + - \ref kOfxStatReplyDefault the action was not trapped + */ +#define kOfxInteractActionGainFocus "OfxInteractActionGainFocus" + +/**@brief + This action is issued when an interact loses input focus. + No openGL calls should be issued by the plug-in during this action. + + @param handle handle to an interact instance, cast to an \ref OfxInteractHandle + @param inArgs has the following properties on an image effect plugin + - \ref kOfxPropEffectInstance a handle to the effect for which the interact is being used on, + - \ref kOfxInteractPropPixelScale the scale factor to convert cannonical pixels to screen pixels, + - \ref kOfxInteractPropBackgroundColour the background colour of the application behind the current view + - \ref kOfxPropTime the effect time at which changed occured + - \ref kOfxImageEffectPropRenderScale the render scale applied to any image fetched + + @param outArgs is redundant and is set to NULL + + \pre + - \ref kOfxActionCreateInstance + has been called on the instance handle, + + + @returns + - \ref kOfxStatOK the action was trapped + - \ref kOfxStatReplyDefault the action was not trapped + */ +#define kOfxInteractActionLoseFocus "OfxInteractActionLoseFocus" + +/*@}*/ +/*@}*/ + +/** @brief OFX suite that allows an effect to interact with an openGL window so as to provide custom interfaces. + +*/ +typedef struct OfxInteractSuiteV1 { + /** @brief Requests an openGL buffer swap on the interact instance */ + OfxStatus (*interactSwapBuffers)(OfxInteractHandle interactInstance); + + /** @brief Requests a redraw of the interact instance */ + OfxStatus (*interactRedraw)(OfxInteractHandle interactInstance); + + /** @brief Gets the property set handle for this interact handle */ + OfxStatus (*interactGetPropertySet)(OfxInteractHandle interactInstance, + OfxPropertySetHandle *property); +} OfxInteractSuiteV1; + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/src/modules/openfx/ofxKeySyms.h b/src/modules/openfx/ofxKeySyms.h new file mode 100644 index 000000000..01397f6a3 --- /dev/null +++ b/src/modules/openfx/ofxKeySyms.h @@ -0,0 +1,526 @@ +#ifndef _ofxKeySyms_h_ +#define _ofxKeySyms_h_ + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + + +/** + \addtogroup PropertiesGeneral +*/ +/*@{*/ + +/** @brief Property used to indicate which a key on the keyboard or a button on a button device has been pressed + + - Type - int X 1 + - Property Set - an read only in argument for the actions ::kOfxInteractActionKeyDown, ::kOfxInteractActionKeyUp and ::kOfxInteractActionKeyRepeat. + - Valid Values - one of any specified by #defines in the file ofxKeySyms.h. + +This property represents a raw key press, it does not represent the 'character value' of the key. + +This property is associated with a ::kOfxPropKeyString property, which encodes the UTF8 +value for the keypress/button press. Some keys (for example arrow keys) have no UTF8 equivalant. + +Some keys, especially on non-english language systems, may have a UTF8 value, but \em not a keysym values, in these +cases, the keysym will have a value of kOfxKey_Unknown, but the ::kOfxPropKeyString property will still be set with +the UTF8 value. + + */ +#define kOfxPropKeySym "kOfxPropKeySym" + +/** @brief This property encodes a single keypresses that generates a unicode code point. The value is stored as a UTF8 string. + + - Type - C string X 1, UTF8 + - Property Set - an read only in argument for the actions ::kOfxInteractActionKeyDown, ::kOfxInteractActionKeyUp and ::kOfxInteractActionKeyRepeat. + - Valid Values - a UTF8 string representing a single character, or the empty string. + +This property represents the UTF8 encode value of a single key press by a user in an OFX interact. + +This property is associated with a ::kOfxPropKeySym which represents an integer value for the key press. Some keys (for example arrow keys) have no UTF8 equivalant, +in which case this is set to the empty string "", and the associate ::kOfxPropKeySym is set to the equivilant raw key press. + +Some keys, especially on non-english language systems, may have a UTF8 value, but \em not a keysym values, in these +cases, the keysym will have a value of kOfxKey_Unknown, but the ::kOfxPropKeyString property will still be set with +the UTF8 value. +*/ +#define kOfxPropKeyString "kOfxPropKeyString" + +/* + The keysyms below have been lifted wholesale out of the X-Windows key symbol header file. Only + the names have been changed to protect the innocent. +*/ + +/*@}*/ + +/* +Copyright (c) 1987, 1994 X Consortium + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + +Except as contained in this notice, the name of the X Consortium shall +not be used in advertising or otherwise to promote the sale, use or +other dealings in this Software without prior written authorization +from the X Consortium. + + +Copyright 1987 by Digital Equipment Corporation, Maynard, Massachusetts + + All Rights Reserved + +Permission to use, copy, modify, and distribute this software and its +documentation for any purpose and without fee is hereby granted, +provided that the above copyright notice appear in all copies and that +both that copyright notice and this permission notice appear in +supporting documentation, and that the name of Digital not be +used in advertising or publicity pertaining to distribution of the +software without specific, written prior permission. + +DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING +ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL +DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR +ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +SOFTWARE. + +**/ + +/** + \defgroup KeySyms OFX Key symbols + + These keysymbols are used as values by the ::kOfxPropKeySym property to indicate the value +of a key that has been pressed. A corresponding ::kOfxPropKeyString property is also set to +contain the unicode value of the key (if it has one). + + The special keysym ::kOfxKey_Unknown is used to set the ::kOfxPropKeySym property in cases +where the key has a UTF8 value which is not supported by the symbols below. + +*/ +/*@{*/ + +#define kOfxKey_Unknown 0x0 + +/* + * TTY Functions, cleverly chosen to map to ascii, for convenience of + * programming, but could have been arbitrary (at the cost of lookup + * tables in client code. + */ +#define kOfxKey_BackSpace 0xFF08 /* back space, back char */ +#define kOfxKey_Tab 0xFF09 +#define kOfxKey_Linefeed 0xFF0A /* Linefeed, LF */ +#define kOfxKey_Clear 0xFF0B +#define kOfxKey_Return 0xFF0D /* Return, enter */ +#define kOfxKey_Pause 0xFF13 /* Pause, hold */ +#define kOfxKey_Scroll_Lock 0xFF14 +#define kOfxKey_Sys_Req 0xFF15 +#define kOfxKey_Escape 0xFF1B +#define kOfxKey_Delete 0xFFFF /* Delete, rubout */ + + + +/* International & multi-key character composition */ + +#define kOfxKey_Multi_key 0xFF20 /* Multi-key character compose */ +#define kOfxKey_SingleCandidate 0xFF3C +#define kOfxKey_MultipleCandidate 0xFF3D +#define kOfxKey_PreviousCandidate 0xFF3E + +/* Japanese keyboard support */ + +#define kOfxKey_Kanji 0xFF21 /* Kanji, Kanji convert */ +#define kOfxKey_Muhenkan 0xFF22 /* Cancel Conversion */ +#define kOfxKey_Henkan_Mode 0xFF23 /* Start/Stop Conversion */ +#define kOfxKey_Henkan 0xFF23 /* Alias for Henkan_Mode */ +#define kOfxKey_Romaji 0xFF24 /* to Romaji */ +#define kOfxKey_Hiragana 0xFF25 /* to Hiragana */ +#define kOfxKey_Katakana 0xFF26 /* to Katakana */ +#define kOfxKey_Hiragana_Katakana 0xFF27 /* Hiragana/Katakana toggle */ +#define kOfxKey_Zenkaku 0xFF28 /* to Zenkaku */ +#define kOfxKey_Hankaku 0xFF29 /* to Hankaku */ +#define kOfxKey_Zenkaku_Hankaku 0xFF2A /* Zenkaku/Hankaku toggle */ +#define kOfxKey_Touroku 0xFF2B /* Add to Dictionary */ +#define kOfxKey_Massyo 0xFF2C /* Delete from Dictionary */ +#define kOfxKey_Kana_Lock 0xFF2D /* Kana Lock */ +#define kOfxKey_Kana_Shift 0xFF2E /* Kana Shift */ +#define kOfxKey_Eisu_Shift 0xFF2F /* Alphanumeric Shift */ +#define kOfxKey_Eisu_toggle 0xFF30 /* Alphanumeric toggle */ +#define kOfxKey_Zen_Koho 0xFF3D /* Multiple/All Candidate(s) */ +#define kOfxKey_Mae_Koho 0xFF3E /* Previous Candidate */ + +/* Cursor control & motion */ + +#define kOfxKey_Home 0xFF50 +#define kOfxKey_Left 0xFF51 /* Move left, left arrow */ +#define kOfxKey_Up 0xFF52 /* Move up, up arrow */ +#define kOfxKey_Right 0xFF53 /* Move right, right arrow */ +#define kOfxKey_Down 0xFF54 /* Move down, down arrow */ +#define kOfxKey_Prior 0xFF55 /* Prior, previous */ +#define kOfxKey_Page_Up 0xFF55 +#define kOfxKey_Next 0xFF56 /* Next */ +#define kOfxKey_Page_Down 0xFF56 +#define kOfxKey_End 0xFF57 /* EOL */ +#define kOfxKey_Begin 0xFF58 /* BOL */ + + +/* Misc Functions */ + +#define kOfxKey_Select 0xFF60 /* Select, mark */ +#define kOfxKey_Print 0xFF61 +#define kOfxKey_Execute 0xFF62 /* Execute, run, do */ +#define kOfxKey_Insert 0xFF63 /* Insert, insert here */ +#define kOfxKey_Undo 0xFF65 /* Undo, oops */ +#define kOfxKey_Redo 0xFF66 /* redo, again */ +#define kOfxKey_Menu 0xFF67 +#define kOfxKey_Find 0xFF68 /* Find, search */ +#define kOfxKey_Cancel 0xFF69 /* Cancel, stop, abort, exit */ +#define kOfxKey_Help 0xFF6A /* Help */ +#define kOfxKey_Break 0xFF6B +#define kOfxKey_Mode_switch 0xFF7E /* Character set switch */ +#define kOfxKey_script_switch 0xFF7E /* Alias for mode_switch */ +#define kOfxKey_Num_Lock 0xFF7F + +/* Keypad Functions, keypad numbers cleverly chosen to map to ascii */ + +#define kOfxKey_KP_Space 0xFF80 /* space */ +#define kOfxKey_KP_Tab 0xFF89 +#define kOfxKey_KP_Enter 0xFF8D /* enter */ +#define kOfxKey_KP_F1 0xFF91 /* PF1, KP_A, ... */ +#define kOfxKey_KP_F2 0xFF92 +#define kOfxKey_KP_F3 0xFF93 +#define kOfxKey_KP_F4 0xFF94 +#define kOfxKey_KP_Home 0xFF95 +#define kOfxKey_KP_Left 0xFF96 +#define kOfxKey_KP_Up 0xFF97 +#define kOfxKey_KP_Right 0xFF98 +#define kOfxKey_KP_Down 0xFF99 +#define kOfxKey_KP_Prior 0xFF9A +#define kOfxKey_KP_Page_Up 0xFF9A +#define kOfxKey_KP_Next 0xFF9B +#define kOfxKey_KP_Page_Down 0xFF9B +#define kOfxKey_KP_End 0xFF9C +#define kOfxKey_KP_Begin 0xFF9D +#define kOfxKey_KP_Insert 0xFF9E +#define kOfxKey_KP_Delete 0xFF9F +#define kOfxKey_KP_Equal 0xFFBD /* equals */ +#define kOfxKey_KP_Multiply 0xFFAA +#define kOfxKey_KP_Add 0xFFAB +#define kOfxKey_KP_Separator 0xFFAC /* separator, often comma */ +#define kOfxKey_KP_Subtract 0xFFAD +#define kOfxKey_KP_Decimal 0xFFAE +#define kOfxKey_KP_Divide 0xFFAF + +#define kOfxKey_KP_0 0xFFB0 +#define kOfxKey_KP_1 0xFFB1 +#define kOfxKey_KP_2 0xFFB2 +#define kOfxKey_KP_3 0xFFB3 +#define kOfxKey_KP_4 0xFFB4 +#define kOfxKey_KP_5 0xFFB5 +#define kOfxKey_KP_6 0xFFB6 +#define kOfxKey_KP_7 0xFFB7 +#define kOfxKey_KP_8 0xFFB8 +#define kOfxKey_KP_9 0xFFB9 + + + +/* + * Auxilliary Functions; note the duplicate definitions for left and right + * function keys; Sun keyboards and a few other manufactures have such + * function key groups on the left and/or right sides of the keyboard. + * We've not found a keyboard with more than 35 function keys total. + */ + +#define kOfxKey_F1 0xFFBE +#define kOfxKey_F2 0xFFBF +#define kOfxKey_F3 0xFFC0 +#define kOfxKey_F4 0xFFC1 +#define kOfxKey_F5 0xFFC2 +#define kOfxKey_F6 0xFFC3 +#define kOfxKey_F7 0xFFC4 +#define kOfxKey_F8 0xFFC5 +#define kOfxKey_F9 0xFFC6 +#define kOfxKey_F10 0xFFC7 +#define kOfxKey_F11 0xFFC8 +#define kOfxKey_L1 0xFFC8 +#define kOfxKey_F12 0xFFC9 +#define kOfxKey_L2 0xFFC9 +#define kOfxKey_F13 0xFFCA +#define kOfxKey_L3 0xFFCA +#define kOfxKey_F14 0xFFCB +#define kOfxKey_L4 0xFFCB +#define kOfxKey_F15 0xFFCC +#define kOfxKey_L5 0xFFCC +#define kOfxKey_F16 0xFFCD +#define kOfxKey_L6 0xFFCD +#define kOfxKey_F17 0xFFCE +#define kOfxKey_L7 0xFFCE +#define kOfxKey_F18 0xFFCF +#define kOfxKey_L8 0xFFCF +#define kOfxKey_F19 0xFFD0 +#define kOfxKey_L9 0xFFD0 +#define kOfxKey_F20 0xFFD1 +#define kOfxKey_L10 0xFFD1 +#define kOfxKey_F21 0xFFD2 +#define kOfxKey_R1 0xFFD2 +#define kOfxKey_F22 0xFFD3 +#define kOfxKey_R2 0xFFD3 +#define kOfxKey_F23 0xFFD4 +#define kOfxKey_R3 0xFFD4 +#define kOfxKey_F24 0xFFD5 +#define kOfxKey_R4 0xFFD5 +#define kOfxKey_F25 0xFFD6 +#define kOfxKey_R5 0xFFD6 +#define kOfxKey_F26 0xFFD7 +#define kOfxKey_R6 0xFFD7 +#define kOfxKey_F27 0xFFD8 +#define kOfxKey_R7 0xFFD8 +#define kOfxKey_F28 0xFFD9 +#define kOfxKey_R8 0xFFD9 +#define kOfxKey_F29 0xFFDA +#define kOfxKey_R9 0xFFDA +#define kOfxKey_F30 0xFFDB +#define kOfxKey_R10 0xFFDB +#define kOfxKey_F31 0xFFDC +#define kOfxKey_R11 0xFFDC +#define kOfxKey_F32 0xFFDD +#define kOfxKey_R12 0xFFDD +#define kOfxKey_F33 0xFFDE +#define kOfxKey_R13 0xFFDE +#define kOfxKey_F34 0xFFDF +#define kOfxKey_R14 0xFFDF +#define kOfxKey_F35 0xFFE0 +#define kOfxKey_R15 0xFFE0 + +/* Modifiers */ + +#define kOfxKey_Shift_L 0xFFE1 /* Left shift */ +#define kOfxKey_Shift_R 0xFFE2 /* Right shift */ +#define kOfxKey_Control_L 0xFFE3 /* Left control */ +#define kOfxKey_Control_R 0xFFE4 /* Right control */ +#define kOfxKey_Caps_Lock 0xFFE5 /* Caps lock */ +#define kOfxKey_Shift_Lock 0xFFE6 /* Shift lock */ + +#define kOfxKey_Meta_L 0xFFE7 /* Left meta */ +#define kOfxKey_Meta_R 0xFFE8 /* Right meta */ +#define kOfxKey_Alt_L 0xFFE9 /* Left alt */ +#define kOfxKey_Alt_R 0xFFEA /* Right alt */ +#define kOfxKey_Super_L 0xFFEB /* Left super */ +#define kOfxKey_Super_R 0xFFEC /* Right super */ +#define kOfxKey_Hyper_L 0xFFED /* Left hyper */ +#define kOfxKey_Hyper_R 0xFFEE /* Right hyper */ + +#define kOfxKey_space 0x020 +#define kOfxKey_exclam 0x021 +#define kOfxKey_quotedbl 0x022 +#define kOfxKey_numbersign 0x023 +#define kOfxKey_dollar 0x024 +#define kOfxKey_percent 0x025 +#define kOfxKey_ampersand 0x026 +#define kOfxKey_apostrophe 0x027 +#define kOfxKey_quoteright 0x027 /* deprecated */ +#define kOfxKey_parenleft 0x028 +#define kOfxKey_parenright 0x029 +#define kOfxKey_asterisk 0x02a +#define kOfxKey_plus 0x02b +#define kOfxKey_comma 0x02c +#define kOfxKey_minus 0x02d +#define kOfxKey_period 0x02e +#define kOfxKey_slash 0x02f +#define kOfxKey_0 0x030 +#define kOfxKey_1 0x031 +#define kOfxKey_2 0x032 +#define kOfxKey_3 0x033 +#define kOfxKey_4 0x034 +#define kOfxKey_5 0x035 +#define kOfxKey_6 0x036 +#define kOfxKey_7 0x037 +#define kOfxKey_8 0x038 +#define kOfxKey_9 0x039 +#define kOfxKey_colon 0x03a +#define kOfxKey_semicolon 0x03b +#define kOfxKey_less 0x03c +#define kOfxKey_equal 0x03d +#define kOfxKey_greater 0x03e +#define kOfxKey_question 0x03f +#define kOfxKey_at 0x040 +#define kOfxKey_A 0x041 +#define kOfxKey_B 0x042 +#define kOfxKey_C 0x043 +#define kOfxKey_D 0x044 +#define kOfxKey_E 0x045 +#define kOfxKey_F 0x046 +#define kOfxKey_G 0x047 +#define kOfxKey_H 0x048 +#define kOfxKey_I 0x049 +#define kOfxKey_J 0x04a +#define kOfxKey_K 0x04b +#define kOfxKey_L 0x04c +#define kOfxKey_M 0x04d +#define kOfxKey_N 0x04e +#define kOfxKey_O 0x04f +#define kOfxKey_P 0x050 +#define kOfxKey_Q 0x051 +#define kOfxKey_R 0x052 +#define kOfxKey_S 0x053 +#define kOfxKey_T 0x054 +#define kOfxKey_U 0x055 +#define kOfxKey_V 0x056 +#define kOfxKey_W 0x057 +#define kOfxKey_X 0x058 +#define kOfxKey_Y 0x059 +#define kOfxKey_Z 0x05a +#define kOfxKey_bracketleft 0x05b +#define kOfxKey_backslash 0x05c +#define kOfxKey_bracketright 0x05d +#define kOfxKey_asciicircum 0x05e +#define kOfxKey_underscore 0x05f +#define kOfxKey_grave 0x060 +#define kOfxKey_quoteleft 0x060 /* deprecated */ +#define kOfxKey_a 0x061 +#define kOfxKey_b 0x062 +#define kOfxKey_c 0x063 +#define kOfxKey_d 0x064 +#define kOfxKey_e 0x065 +#define kOfxKey_f 0x066 +#define kOfxKey_g 0x067 +#define kOfxKey_h 0x068 +#define kOfxKey_i 0x069 +#define kOfxKey_j 0x06a +#define kOfxKey_k 0x06b +#define kOfxKey_l 0x06c +#define kOfxKey_m 0x06d +#define kOfxKey_n 0x06e +#define kOfxKey_o 0x06f +#define kOfxKey_p 0x070 +#define kOfxKey_q 0x071 +#define kOfxKey_r 0x072 +#define kOfxKey_s 0x073 +#define kOfxKey_t 0x074 +#define kOfxKey_u 0x075 +#define kOfxKey_v 0x076 +#define kOfxKey_w 0x077 +#define kOfxKey_x 0x078 +#define kOfxKey_y 0x079 +#define kOfxKey_z 0x07a +#define kOfxKey_braceleft 0x07b +#define kOfxKey_bar 0x07c +#define kOfxKey_braceright 0x07d +#define kOfxKey_asciitilde 0x07e + +#define kOfxKey_nobreakspace 0x0a0 +#define kOfxKey_exclamdown 0x0a1 +#define kOfxKey_cent 0x0a2 +#define kOfxKey_sterling 0x0a3 +#define kOfxKey_currency 0x0a4 +#define kOfxKey_yen 0x0a5 +#define kOfxKey_brokenbar 0x0a6 +#define kOfxKey_section 0x0a7 +#define kOfxKey_diaeresis 0x0a8 +#define kOfxKey_copyright 0x0a9 +#define kOfxKey_ordfeminine 0x0aa +#define kOfxKey_guillemotleft 0x0ab /* left angle quotation mark */ +#define kOfxKey_notsign 0x0ac +#define kOfxKey_hyphen 0x0ad +#define kOfxKey_registered 0x0ae +#define kOfxKey_macron 0x0af +#define kOfxKey_degree 0x0b0 +#define kOfxKey_plusminus 0x0b1 +#define kOfxKey_twosuperior 0x0b2 +#define kOfxKey_threesuperior 0x0b3 +#define kOfxKey_acute 0x0b4 +#define kOfxKey_mu 0x0b5 +#define kOfxKey_paragraph 0x0b6 +#define kOfxKey_periodcentered 0x0b7 +#define kOfxKey_cedilla 0x0b8 +#define kOfxKey_onesuperior 0x0b9 +#define kOfxKey_masculine 0x0ba +#define kOfxKey_guillemotright 0x0bb /* right angle quotation mark */ +#define kOfxKey_onequarter 0x0bc +#define kOfxKey_onehalf 0x0bd +#define kOfxKey_threequarters 0x0be +#define kOfxKey_questiondown 0x0bf +#define kOfxKey_Agrave 0x0c0 +#define kOfxKey_Aacute 0x0c1 +#define kOfxKey_Acircumflex 0x0c2 +#define kOfxKey_Atilde 0x0c3 +#define kOfxKey_Adiaeresis 0x0c4 +#define kOfxKey_Aring 0x0c5 +#define kOfxKey_AE 0x0c6 +#define kOfxKey_Ccedilla 0x0c7 +#define kOfxKey_Egrave 0x0c8 +#define kOfxKey_Eacute 0x0c9 +#define kOfxKey_Ecircumflex 0x0ca +#define kOfxKey_Ediaeresis 0x0cb +#define kOfxKey_Igrave 0x0cc +#define kOfxKey_Iacute 0x0cd +#define kOfxKey_Icircumflex 0x0ce +#define kOfxKey_Idiaeresis 0x0cf +#define kOfxKey_ETH 0x0d0 +#define kOfxKey_Eth 0x0d0 /* deprecated */ +#define kOfxKey_Ntilde 0x0d1 +#define kOfxKey_Ograve 0x0d2 +#define kOfxKey_Oacute 0x0d3 +#define kOfxKey_Ocircumflex 0x0d4 +#define kOfxKey_Otilde 0x0d5 +#define kOfxKey_Odiaeresis 0x0d6 +#define kOfxKey_multiply 0x0d7 +#define kOfxKey_Ooblique 0x0d8 +#define kOfxKey_Ugrave 0x0d9 +#define kOfxKey_Uacute 0x0da +#define kOfxKey_Ucircumflex 0x0db +#define kOfxKey_Udiaeresis 0x0dc +#define kOfxKey_Yacute 0x0dd +#define kOfxKey_THORN 0x0de +#define kOfxKey_ssharp 0x0df +#define kOfxKey_agrave 0x0e0 +#define kOfxKey_aacute 0x0e1 +#define kOfxKey_acircumflex 0x0e2 +#define kOfxKey_atilde 0x0e3 +#define kOfxKey_adiaeresis 0x0e4 +#define kOfxKey_aring 0x0e5 +#define kOfxKey_ae 0x0e6 +#define kOfxKey_ccedilla 0x0e7 +#define kOfxKey_egrave 0x0e8 +#define kOfxKey_eacute 0x0e9 +#define kOfxKey_ecircumflex 0x0ea +#define kOfxKey_ediaeresis 0x0eb +#define kOfxKey_igrave 0x0ec +#define kOfxKey_iacute 0x0ed +#define kOfxKey_icircumflex 0x0ee +#define kOfxKey_idiaeresis 0x0ef +#define kOfxKey_eth 0x0f0 +#define kOfxKey_ntilde 0x0f1 +#define kOfxKey_ograve 0x0f2 +#define kOfxKey_oacute 0x0f3 +#define kOfxKey_ocircumflex 0x0f4 +#define kOfxKey_otilde 0x0f5 +#define kOfxKey_odiaeresis 0x0f6 +#define kOfxKey_division 0x0f7 +#define kOfxKey_oslash 0x0f8 +#define kOfxKey_ugrave 0x0f9 +#define kOfxKey_uacute 0x0fa +#define kOfxKey_ucircumflex 0x0fb +#define kOfxKey_udiaeresis 0x0fc +#define kOfxKey_yacute 0x0fd +#define kOfxKey_thorn 0x0fe +#define kOfxKey_ydiaeresis 0x0ff + +/*@}*/ + +#endif diff --git a/src/modules/openfx/ofxMemory.h b/src/modules/openfx/ofxMemory.h new file mode 100644 index 000000000..efc30f801 --- /dev/null +++ b/src/modules/openfx/ofxMemory.h @@ -0,0 +1,66 @@ +#ifndef _ofxMemory_h_ +#define _ofxMemory_h_ + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + + +#ifdef __cplusplus +extern "C" { +#endif + +#define kOfxMemorySuite "OfxMemorySuite" + +/** @brief The OFX suite that implements general purpose memory management. + +Use this suite for ordinary memory management functions, where you would normally use malloc/free or new/delete on ordinary objects. + +For images, you should use the memory allocation functions in the image effect suite, as many hosts have specific image memory pools. + +\note C++ plugin developers will need to redefine new and delete as skins ontop of this suite. + */ +typedef struct OfxMemorySuiteV1 { + /** @brief Allocate memory. + + \arg \c handle - effect instance to assosciate with this memory allocation, or NULL. + \arg \c nBytes number of bytes to allocate + \arg \c allocatedData pointer to the return value. Allocated memory will be alligned for any use. + + This function has the host allocate memory using its own memory resources + and returns that to the plugin. + + @returns + - ::kOfxStatOK the memory was sucessfully allocated + - ::kOfxStatErrMemory the request could not be met and no memory was allocated + + */ + OfxStatus (*memoryAlloc)(void *handle, + size_t nBytes, + void **allocatedData); + + /** @brief Frees memory. + + \arg \c allocatedData pointer to memory previously returned by OfxMemorySuiteV1::memoryAlloc + + This function frees any memory that was previously allocated via OfxMemorySuiteV1::memoryAlloc. + + @returns + - ::kOfxStatOK the memory was sucessfully freed + - ::kOfxStatErrBadHandle \e allocatedData was not a valid pointer returned by OfxMemorySuiteV1::memoryAlloc + + */ + OfxStatus (*memoryFree)(void *allocatedData); + } OfxMemorySuiteV1; + + +/** @file ofxMemory.h + This file contains the API for general purpose memory allocation from a host. +*/ + + + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/src/modules/openfx/ofxMessage.h b/src/modules/openfx/ofxMessage.h new file mode 100644 index 000000000..67232162a --- /dev/null +++ b/src/modules/openfx/ofxMessage.h @@ -0,0 +1,169 @@ +#ifndef _ofxMessage_h_ +#define _ofxMessage_h_ + +#include "ofxCore.h" + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + + +#ifdef __cplusplus +extern "C" { +#endif + +#define kOfxMessageSuite "OfxMessageSuite" + + +/** @brief String used to type fatal error messages + + Fatal error messages should only be posted by a plugin when it can no longer continue operation. + */ +#define kOfxMessageFatal "OfxMessageFatal" + +/** @brief String used to type error messages + + Ordinary error messages should be posted when there is an error in operation that is recoverable by + user intervention. +*/ +#define kOfxMessageError "OfxMessageError" + +/** @brief String used to type warning messages + + Warnings indicate states that allow for operations to proceed, but are not necessarily optimal. +*/ +#define kOfxMessageWarning "OfxMessageWarning" + +/** @brief String used to type simple ordinary messages + + Ordinary messages simply convey information from the plugin directly to the user. +*/ +#define kOfxMessageMessage "OfxMessageMessage" + +/** @brief String used to type log messages + + Log messages are written out to a log and not to the end user. +*/ +#define kOfxMessageLog "OfxMessageLog" + +/** @brief String used to type yes/no messages + + The host is to enter a modal state which waits for the user to respond yes or no. +The OfxMessageSuiteV1::message function which posted the message will only return after +the user responds. When asking a question, the OfxStatus code returned by the message function will be, + - kOfxStatReplyYes - if the user replied 'yes' to the question + - kOfxStatReplyNo - if the user replied 'no' to the question + - some error code if an error was encounterred + + It is an error to post a question message if the plugin is not in an interactive session. + */ +#define kOfxMessageQuestion "OfxMessageQuestion" + +/** @brief The OFX suite that allows a plug-in to pass messages back to a user. The V2 suite extends on this + in a backwards compatible manner. + */ +typedef struct OfxMessageSuiteV1 { + + /** @brief Post a message on the host, using printf style varargs + + \arg \c handle effect handle (descriptor or instance) the message should be associated with, may be NULL + \arg \c messageType string describing the kind of message to post, one of the kOfxMessageType* constants + \arg \c messageId plugin specified id to associate with this message. If overriding the message in XML resource, the message is identified with this, this may be NULL, or "", in which case no override will occur, + \arg \c format printf style format string + \arg \c ... printf style varargs list to print + +\returns + - ::kOfxStatOK - if the message was sucessfully posted + - ::kOfxStatReplyYes - if the message was of type kOfxMessageQuestion and the user reply yes + - ::kOfxStatReplyNo - if the message was of type kOfxMessageQuestion and the user reply no + - ::kOfxStatFailed - if the message could not be posted for some reason + + */ + OfxStatus (*message)(void *handle, + const char *messageType, + const char *messageId, + const char *format, + ...); + +} OfxMessageSuiteV1; + +/** @brief The OFX suite that allows a plug-in to pass messages back to a user. + + This extends OfxMessageSuiteV1, and should be considered a replacement to version 1. + + Note that this suite has been extended in backwards compatible manner, so that a host can return this struct + for both V1 and V2. + */ +typedef struct OfxMessageSuiteV2 { + + /** @brief Post a transient message on the host, using printf style varargs. Same as the V1 message suite call. + + \arg \c handle effect handle (descriptor or instance) the message should be associated with, may be null + \arg \c messageType string describing the kind of message to post, one of the kOfxMessageType* constants + \arg \c messageId plugin specified id to associate with this message. If overriding the message in XML resource, the message is identified with this, this may be NULL, or "", in which case no override will occur, + \arg \c format printf style format string + \arg \c ... printf style varargs list to print + + \returns + - ::kOfxStatOK - if the message was sucessfully posted + - ::kOfxStatReplyYes - if the message was of type kOfxMessageQuestion and the user reply yes + - ::kOfxStatReplyNo - if the message was of type kOfxMessageQuestion and the user reply no + - ::kOfxStatFailed - if the message could not be posted for some reason + */ + OfxStatus (*message)(void *handle, + const char *messageType, + const char *messageId, + const char *format, + ...); + + /** @brief Post a persistent message on an effect, using printf style varargs, and set error states. New for V2 message suite. + + \arg \c handle effect instance handle the message should be associated with, may NOT be null, + \arg \c messageType string describing the kind of message to post, should be one of... + - kOfxMessageError + - kOfxMessageWarning + - kOfxMessageMessage + \arg \c messageId plugin specified id to associate with this message. If overriding the message in XML resource, the message is identified with this, this may be NULL, or "", in which case no override will occur, + \arg \c format printf style format string + \arg \c ... printf style varargs list to print + + \returns + - ::kOfxStatOK - if the message was sucessfully posted + - ::kOfxStatErrBadHandle - the handle was rubbish + - ::kOfxStatFailed - if the message could not be posted for some reason + + Persistent messages are associated with an effect handle until explicitly cleared by an effect. So if an error message is posted the error state, and associated message will persist and be displayed on the effect appropriately. (eg: draw a node in red on a node based compostor and display the message when clicked on). + + If \e messageType is error or warning, associated error states should be flagged on host applications. Posting an error message implies that the host cannot proceeed, a warning allows the host to proceed, whilst a simple message should have no stop anything. + */ + OfxStatus (*setPersistentMessage)(void *handle, + const char *messageType, + const char *messageId, + const char *format, + ...); + + + /** @brief Clears any persistent message on an effect handle that was set by OfxMessageSuiteV2::setPersistentMessage. New for V2 message suite. + + \arg \c handle effect instance handle messages should be cleared from. + \arg \c handle effect handle (descriptor or instance) + + \returns + - ::kOfxStatOK - if the message was sucessfully cleared + - ::kOfxStatErrBadHandle - the handle was rubbish + - ::kOfxStatFailed - if the message could not be cleared for some reason + + Clearing a message will clear any associated error state. + */ + OfxStatus (*clearPersistentMessage)(void *handle); + +} OfxMessageSuiteV2; + +/** @file ofxMessage.h + This file contains the Host API for end user message communication. +*/ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/src/modules/openfx/ofxMultiThread.h b/src/modules/openfx/ofxMultiThread.h new file mode 100644 index 000000000..baed346f8 --- /dev/null +++ b/src/modules/openfx/ofxMultiThread.h @@ -0,0 +1,166 @@ +#ifndef _ofxMultiThread_h_ +#define _ofxMultiThread_h_ + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + + +#include "ofxCore.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** @file ofxMultiThread.h + + This file contains the Host Suite for threading +*/ + +#define kOfxMultiThreadSuite "OfxMultiThreadSuite" + +/** @brief Mutex blind data handle + */ +typedef struct OfxMutex *OfxMutexHandle; + +/** @brief The function type to passed to the multi threading routines + + \arg \c threadIndex unique index of this thread, will be between 0 and threadMax + \arg \c threadMax to total number of threads executing this function + \arg \c customArg the argument passed into multiThread + +A function of this type is passed to OfxMultiThreadSuiteV1::multiThread to be launched in multiple threads. + */ +typedef void (OfxThreadFunctionV1)(unsigned int threadIndex, + unsigned int threadMax, + void *customArg); + +/** @brief OFX suite that provides simple SMP style multi-processing + */ +typedef struct OfxMultiThreadSuiteV1 { + /**@brief Function to spawn SMP threads + + \arg \c func function to call in each thread. + \arg \c nThreads number of threads to launch + \arg \c customArg paramter to pass to customArg of func in each thread. + + This function will spawn nThreads separate threads of computation (typically one per CPU) + to allow something to perform symmetric multi processing. Each thread will call 'func' passing + in the index of the thread and the number of threads actually launched. + + multiThread will not return until all the spawned threads have returned. It is up to the host + how it waits for all the threads to return (busy wait, blocking, whatever). + + \e nThreads can be more than the value returned by multiThreadNumCPUs, however the threads will + be limitted to the number of CPUs returned by multiThreadNumCPUs. + + This function cannot be called recursively. + + @returns + - ::kOfxStatOK, the function func has executed and returned sucessfully + - ::kOfxStatFailed, the threading function failed to launch + - ::kOfxStatErrExists, failed in an attempt to call multiThread recursively, + + */ + OfxStatus (*multiThread)(OfxThreadFunctionV1 func, + unsigned int nThreads, + void *customArg); + + /**@brief Function which indicates the number of CPUs available for SMP processing + + \arg \c nCPUs pointer to an integer where the result is returned + + This value may be less than the actual number of CPUs on a machine, as the host may reserve other CPUs for itself. + + @returns + - ::kOfxStatOK, all was OK and the maximum number of threads is in nThreads. + - ::kOfxStatFailed, the function failed to get the number of CPUs + */ + OfxStatus (*multiThreadNumCPUs)(unsigned int *nCPUs); + + /**@brief Function which indicates the index of the current thread + + \arg \c threadIndex pointer to an integer where the result is returned + + This function returns the thread index, which is the same as the \e threadIndex argument passed to the ::OfxThreadFunctionV1. + + If there are no threads currently spawned, then this function will set threadIndex to 0 + + @returns + - ::kOfxStatOK, all was OK and the maximum number of threads is in nThreads. + - ::kOfxStatFailed, the function failed to return an index + */ + OfxStatus (*multiThreadIndex)(unsigned int *threadIndex); + + /**@brief Function to enquire if the calling thread was spawned by multiThread + + @returns + - 0 if the thread is not one spawned by multiThread + - 1 if the thread was spawned by multiThread + */ + int (*multiThreadIsSpawnedThread)(void); + + /** @brief Create a mutex + + \arg \c mutex where the new handle is returned + \arg \c count initial lock count on the mutex. This can be negative. + + Creates a new mutex with lockCount locks on the mutex intially set. + + @returns + - kOfxStatOK - mutex is now valid and ready to go + */ + OfxStatus (*mutexCreate)(OfxMutexHandle *mutex, int lockCount); + + /** @brief Destroy a mutex + + Destroys a mutex intially created by mutexCreate. + + @returns + - kOfxStatOK - if it destroyed the mutex + - kOfxStatErrBadHandle - if the handle was bad + */ + OfxStatus (*mutexDestroy)(const OfxMutexHandle mutex); + + /** @brief Blocking lock on the mutex + + This trys to lock a mutex and blocks the thread it is in until the lock suceeds. + + A sucessful lock causes the mutex's lock count to be increased by one and to block any other calls to lock the mutex until it is unlocked. + + @returns + - kOfxStatOK - if it got the lock + - kOfxStatErrBadHandle - if the handle was bad + */ + OfxStatus (*mutexLock)(const OfxMutexHandle mutex); + + /** @brief Unlock the mutex + + This unlocks a mutex. Unlocking a mutex decreases its lock count by one. + + @returns + - kOfxStatOK if it released the lock + - kOfxStatErrBadHandle if the handle was bad + */ + OfxStatus (*mutexUnLock)(const OfxMutexHandle mutex); + + /** @brief Non blocking attempt to lock the mutex + + This attempts to lock a mutex, if it cannot, it returns and says so, rather than blocking. + + A sucessful lock causes the mutex's lock count to be increased by one, if the lock did not suceed, the call returns immediately and the lock count remains unchanged. + + @returns + - kOfxStatOK - if it got the lock + - kOfxStatFailed - if it did not get the lock + - kOfxStatErrBadHandle - if the handle was bad + */ + OfxStatus (*mutexTryLock)(const OfxMutexHandle mutex); + + } OfxMultiThreadSuiteV1; + +#ifdef __cplusplus +} +#endif + + +#endif diff --git a/src/modules/openfx/ofxOld.h b/src/modules/openfx/ofxOld.h new file mode 100644 index 000000000..c1f5968b9 --- /dev/null +++ b/src/modules/openfx/ofxOld.h @@ -0,0 +1,110 @@ +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + +#ifndef _ofxOLD_h_ +#define _ofxOLD_h_ + + +/** @brief String to label images with YUVA components +--ofxImageEffects.h +@deprecated - removed in v1.4. Note, this has been deprecated in v1.3 + + */ +#define kOfxImageComponentYUVA "OfxImageComponentYUVA" + +/** @brief Indicates whether an effect is performing an analysis pass. +--ofxImageEffects.h + - Type - int X 1 + - Property Set - plugin instance (read/write) + - Default - to 0 + - Valid Values - This must be one of 0 or 1 + +@deprecated - This feature has been deprecated - officially commented out v1.4. +*/ +#define kOfxImageEffectPropInAnalysis "OfxImageEffectPropInAnalysis" + + +/** @brief Defines an 8 bit per component YUVA pixel +-- ofxPixels.h +Deprecated in 1.3, removed in 1.4 +*/ + +typedef struct OfxYUVAColourB { + unsigned char y, u, v, a; +}OfxYUVAColourB; + + +/** @brief Defines an 16 bit per component YUVA pixel +-- ofxPixels.h +@deprecated - Deprecated in 1.3, removed in 1.4 +*/ + +typedef struct OfxYUVAColourS { + unsigned short y, u, v, a; +}OfxYUVAColourS; + +/** @brief Defines an floating point component YUVA pixel +-- ofxPixels.h +@deprecated - Deprecated in 1.3, removed in 1.4 + */ +typedef struct OfxYUVAColourF { + float y, u, v, a; +}OfxYUVAColourF; + + +/** @brief The size of an interact's openGL viewport +-- ofxInteract.h + - Type - int X 2 + - Property Set - read only property on the interact instance and in argument to all the interact actions. + +@deprecated - V1.3: This property is the redundant and its use will be deprecated in future releases. +V1.4: Removed + */ +#define kOfxInteractPropViewportSize "OfxInteractPropViewport" + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating a size normalised to the X dimension. See \ref ::kOfxParamPropDoubleType. +-- ofxParam.h +@deprecated - V1.3: Deprecated in favour of ::OfxParamDoubleTypeX +V1.4: Removed + */ +#define kOfxParamDoubleTypeNormalisedX "OfxParamDoubleTypeNormalisedX" + + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating a size normalised to the Y dimension. See \ref ::kOfxParamPropDoubleType. +-- ofxParam.h +@deprecated - V1.3: Deprecated in favour of ::OfxParamDoubleTypeY +V1.4: Removed + */ +#define kOfxParamDoubleTypeNormalisedY "OfxParamDoubleTypeNormalisedY" + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating an absolute position normalised to the X dimension. See \ref ::kOfxParamPropDoubleType. +-- ofxParam.h +@deprecated - V1.3: Deprecated in favour of ::OfxParamDoubleTypeXAbsolute +V1.4: Removed + */ +#define kOfxParamDoubleTypeNormalisedXAbsolute "OfxParamDoubleTypeNormalisedXAbsolute" + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating an absolute position normalised to the Y dimension. See \ref ::kOfxParamPropDoubleType. +-- ofxParam.h +@deprecated - V1.3: Deprecated in favour of ::OfxParamDoubleTypeYAbsolute +V1.4: Removed + */ +#define kOfxParamDoubleTypeNormalisedYAbsolute "OfxParamDoubleTypeNormalisedYAbsolute" + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating normalisation to the X and Y dimension for 2D params. See \ref ::kOfxParamPropDoubleType. +-- ofxParam.h +@deprecated - V1.3: Deprecated in favour of ::OfxParamDoubleTypeXY +V1.4: Removed + */ +#define kOfxParamDoubleTypeNormalisedXY "OfxParamDoubleTypeNormalisedXY" + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating normalisation to the X and Y dimension for a 2D param that can be interpretted as an absolute spatial position. See \ref ::kOfxParamPropDoubleType. +-- ofxParam.h +@deprecated - V1.3: Deprecated in favour of ::kOfxParamDoubleTypeXYAbsolute +V1.4: Removed + */ +#define kOfxParamDoubleTypeNormalisedXYAbsolute "OfxParamDoubleTypeNormalisedXYAbsolute" + + + +#endif diff --git a/src/modules/openfx/ofxOpenGLRender.h b/src/modules/openfx/ofxOpenGLRender.h new file mode 100644 index 000000000..1d4014328 --- /dev/null +++ b/src/modules/openfx/ofxOpenGLRender.h @@ -0,0 +1,8 @@ +#pragma once +#ifndef _ofxOpenGLRender_h_ +#define _ofxOpenGLRender_h_ + +// Copyright OpenFX and Contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + +#endif // _ofxOpenGLRender_h_ diff --git a/src/modules/openfx/ofxParam.h b/src/modules/openfx/ofxParam.h new file mode 100644 index 000000000..af834e0fa --- /dev/null +++ b/src/modules/openfx/ofxParam.h @@ -0,0 +1,1293 @@ +#ifndef _ofxParam_h_ +#define _ofxParam_h_ + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + +#include "ofxCore.h" +#include "ofxProperty.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** @brief string value to the ::kOfxPropType property for all parameters */ +#define kOfxParameterSuite "OfxParameterSuite" + +/** @brief string value on the ::kOfxPropType property for all parameter definitions (ie: the handle returned in describe) */ +#define kOfxTypeParameter "OfxTypeParameter" + +/** @brief string value on the ::kOfxPropType property for all parameter instances */ +#define kOfxTypeParameterInstance "OfxTypeParameterInstance" + +/** @brief Blind declaration of an OFX param + +*/ +typedef struct OfxParamStruct *OfxParamHandle; + +/** @brief Blind declaration of an OFX parameter set + + */ +typedef struct OfxParamSetStruct *OfxParamSetHandle; + + +/** + \defgroup ParamTypeDefines Parameter Type definitions + +These strings are used to identify the type of the parameter when it is defined, they are also on the ::kOfxParamPropType in any parameter instance. +*/ +/*@{*/ + +/** @brief String to identify a param as a single valued integer */ +#define kOfxParamTypeInteger "OfxParamTypeInteger" +/** @brief String to identify a param as a Single valued floating point parameter */ +#define kOfxParamTypeDouble "OfxParamTypeDouble" +/** @brief String to identify a param as a Single valued boolean parameter */ +#define kOfxParamTypeBoolean "OfxParamTypeBoolean" +/** @brief String to identify a param as a Single valued, 'one-of-many' parameter */ +#define kOfxParamTypeChoice "OfxParamTypeChoice" +/** @brief String to identify a param as a string-valued 'one-of-many' parameter. \since Version 1.5 */ +#define kOfxParamTypeStrChoice "OfxParamTypeStrChoice" +/** @brief String to identify a param as a Red, Green, Blue and Alpha colour parameter */ +#define kOfxParamTypeRGBA "OfxParamTypeRGBA" +/** @brief String to identify a param as a Red, Green and Blue colour parameter */ +#define kOfxParamTypeRGB "OfxParamTypeRGB" +/** @brief String to identify a param as a Two dimensional floating point parameter */ +#define kOfxParamTypeDouble2D "OfxParamTypeDouble2D" +/** @brief String to identify a param as a Two dimensional integer point parameter */ +#define kOfxParamTypeInteger2D "OfxParamTypeInteger2D" +/** @brief String to identify a param as a Three dimensional floating point parameter */ +#define kOfxParamTypeDouble3D "OfxParamTypeDouble3D" +/** @brief String to identify a param as a Three dimensional integer parameter */ +#define kOfxParamTypeInteger3D "OfxParamTypeInteger3D" +/** @brief String to identify a param as a String (UTF8) parameter */ +#define kOfxParamTypeString "OfxParamTypeString" +/** @brief String to identify a param as a Plug-in defined parameter */ +#define kOfxParamTypeCustom "OfxParamTypeCustom" +/** @brief String to identify a param as a Plug-in defined opaque data parameter */ +#define kOfxParamTypeBytes "OfxParamTypeBytes" +/** @brief String to identify a param as a Grouping parameter */ +#define kOfxParamTypeGroup "OfxParamTypeGroup" +/** @brief String to identify a param as a page parameter */ +#define kOfxParamTypePage "OfxParamTypePage" +/** @brief String to identify a param as a PushButton parameter */ +#define kOfxParamTypePushButton "OfxParamTypePushButton" +/*@}*/ + +/** @brief Provides information for a parameter of type kOfxParamTypeBytes + */ +typedef struct OfxBytes +{ + /** @brief a pointer to the data buffer */ + const unsigned char *data; + /** @brief the length of the data buffer, in bytes */ + size_t length; +} OfxBytes; + +/** + \addtogroup PropertiesAll +*/ +/*@{*/ +/** + \defgroup ParamPropDefines Parameter Property Definitions + +These are the list of properties used by the parameters suite. +*/ +/*@{*/ + +/** @brief Indicates if the host supports animation of custom parameters + + - Type - int X 1 + - Property Set - host descriptor (read only) + - Value Values - 0 or 1 +*/ +#define kOfxParamHostPropSupportsCustomAnimation "OfxParamHostPropSupportsCustomAnimation" + +/** @brief Indicates if the host supports animation of string params + + - Type - int X 1 + - Property Set - host descriptor (read only) + - Valid Values - 0 or 1 +*/ +#define kOfxParamHostPropSupportsStringAnimation "OfxParamHostPropSupportsStringAnimation" + +/** @brief Indicates if the host supports animation of boolean params + + - Type - int X 1 + - Property Set - host descriptor (read only) + - Valid Values - 0 or 1 +*/ +#define kOfxParamHostPropSupportsBooleanAnimation "OfxParamHostPropSupportsBooleanAnimation" + +/** @brief Indicates if the host supports animation of choice params + + - Type - int X 1 + - Property Set - host descriptor (read only) + - Valid Values - 0 or 1 +*/ +#define kOfxParamHostPropSupportsChoiceAnimation "OfxParamHostPropSupportsChoiceAnimation" + +/** @brief Indicates if the host supports custom interacts for parameters + + - Type - int X 1 + - Property Set - host descriptor (read only) + - Valid Values - 0 or 1 + +Currently custom interacts for parameters can only be drawn using OpenGL. +APIs will be added later to support using the new Draw Suite. +*/ +#define kOfxParamHostPropSupportsCustomInteract "OfxParamHostPropSupportsCustomInteract" + +/** @brief Indicates the maximum numbers of parameters available on the host. + + - Type - int X 1 + - Property Set - host descriptor (read only) + +If set to -1 it implies unlimited number of parameters. +*/ +#define kOfxParamHostPropMaxParameters "OfxParamHostPropMaxParameters" + +/** @brief Indicates the maximum number of parameter pages. + + - Type - int X 1 + - Property Set - host descriptor (read only) + + If there is no limit to the number of pages on a host, set this to -1. + +Hosts that do not support paged parameter layout should set this to zero. +*/ +#define kOfxParamHostPropMaxPages "OfxParamHostPropMaxPages" + +/** @brief This indicates the number of parameter rows and coloumns on a page. + + - Type - int X 2 + - Property Set - host descriptor (read only) + +If the host has supports paged parameter layout, used dimension 0 as the number of columns per page and dimension 1 as the number of rows per page. +*/ +#define kOfxParamHostPropPageRowColumnCount "OfxParamHostPropPageRowColumnCount" + +/** @brief Pseudo parameter name used to skip a row in a page layout. + +Passed as a value to the \ref kOfxParamPropPageChild property. + +See \ref ParametersInterfacesPagedLayouts for more details. +*/ +#define kOfxParamPageSkipRow "OfxParamPageSkipRow" + +/** @brief Pseudo parameter name used to skip a row in a page layout. + +Passed as a value to the \ref kOfxParamPropPageChild property. + +See \ref ParametersInterfacesPagedLayouts for more details. +*/ +#define kOfxParamPageSkipColumn "OfxParamPageSkipColumn" + +/** @brief Overrides the parameter's standard user interface with the given interact. + + - Type - pointer X 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read only) + - Default - NULL + - Valid Values - must point to a OfxPluginEntryPoint + +If set, the parameter's normal interface is replaced completely by the interact gui. + +Currently custom interacts for parameters can only be drawn using OpenGL. +APIs will be added later to support using the new Draw Suite. +*/ +#define kOfxParamPropInteractV1 "OfxParamPropInteractV1" + +/** @brief The size of a parameter instance's custom interface in screen pixels. + + - Type - double x 2 + - Property Set - plugin parameter instance (read only) + +This is set by a host to indicate the current size of a custom interface if the plug-in has one. If not this is set to (0,0). +*/ +#define kOfxParamPropInteractSize "OfxParamPropInteractSize" + +/** @brief The preferred aspect ratio of a parameter's custom interface. + + - Type - double x 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read only) + - Default - 1.0 + - Valid Values - greater than or equal to 0.0 + +If set to anything other than 0.0, the custom interface for this parameter will be of a size with this aspect ratio (x size/y size). +*/ +#define kOfxParamPropInteractSizeAspect "OfxParamPropInteractSizeAspect" + +/** @brief The minimum size of a parameter's custom interface, in screen pixels. + + - Type - double x 2 + - Property Set - plugin parameter descriptor (read/write) and instance (read only) + - Default - 10,10 + - Valid Values - greater than (0, 0) + +Any custom interface will not be less than this size. +*/ +#define kOfxParamPropInteractMinimumSize "OfxParamPropInteractMinimumSize" + +/** @brief The preferred size of a parameter's custom interface. + + - Type - int x 2 + - Property Set - plugin parameter descriptor (read/write) and instance (read only) + - Default - 10,10 + - Valid Values - greater than (0, 0) + + A host should attempt to set a parameter's custom interface on a parameter to be this size if possible, otherwise it will be of ::kOfxParamPropInteractSizeAspect aspect but larger than ::kOfxParamPropInteractMinimumSize. +*/ +#define kOfxParamPropInteractPreferedSize "OfxParamPropInteractPreferedSize" + +/** @brief The type of a parameter. + + - Type - C string X 1 + - Property Set - plugin parameter descriptor (read only) and instance (read only) + +This string will be set to the type that the parameter was create with. +*/ +#define kOfxParamPropType "OfxParamPropType" + +/** @brief Flags whether a parameter can animate. + + - Type - int x 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read only) + - Default - 1 + - Valid Values - 0 or 1 + +A plug-in uses this property to indicate if a parameter is able to animate. +*/ +#define kOfxParamPropAnimates "OfxParamPropAnimates" + +/** @brief Flags whether changes to a parameter should be put on the undo/redo stack + + - Type - int x 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read only) + - Default - 1 + - Valid Values - 0 or 1 +*/ +#define kOfxParamPropCanUndo "OfxParamPropCanUndo" + +/** @brief States whether the plugin needs to resync its private data + + - Type - int X 1 + - Property Set - param set instance (read/write) + - Default - 0 + - Valid Values - + - 0 - no need to sync + - 1 - paramset is not synced + +The plugin should set this flag to true whenever any internal state has not +been flushed to the set of params. + +The host will examine this property each time it does a copy or save +operation on the instance. + * If it is set to 1, the host will call SyncPrivateData and then set + it to zero before doing the copy/save. + * If it is set to 0, the host will assume that the param data + correctly represents the private state, and will not call + SyncPrivateData before copying/saving. + * If this property is not set, the host will always call + SyncPrivateData before copying or saving the effect (as if the + property were set to 1 -- but the host will not create or + modify the property). +*/ +#define kOfxPropParamSetNeedsSyncing "OfxPropParamSetNeedsSyncing" + +/** @brief Flags whether a parameter is currently animating. + + - Type - int x 1 + - Property Set - plugin parameter instance (read only) + - Valid Values - 0 or 1 + +Set by a host on a parameter instance to indicate if the parameter has a non-constant value set on it. This can +be as a consequence of animation or of scripting modifying the value, or of a parameter being connected to +an expression in the host. +*/ +#define kOfxParamPropIsAnimating "OfxParamPropIsAnimating" + +/** @brief Flags whether the plugin will attempt to set the value of a parameter in some callback or analysis pass + + - Type - int x 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read only) + - Default - 0 + - Valid Values - 0 or 1 + +This is used to tell the host whether the plug-in is going to attempt to set the value of the parameter. + +@deprecated - v1.4: deprecated - to be removed in 1.5 +*/ + +#define kOfxParamPropPluginMayWrite "OfxParamPropPluginMayWrite" + +/** @brief Flags whether the value of a parameter should persist. + + - Type - int x 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read only) + - Default - 1 + - Valid Values - 0 or 1 + +This is used to tell the host whether the value of the parameter is important and should be save in any description of the plug-in. +*/ +#define kOfxParamPropPersistant "OfxParamPropPersistant" + +/** @brief Flags whether changing a parameter's value forces an evalution (ie: render), + + - Type - int x 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read/write only) + - Default - 1 + - Valid Values - 0 or 1 + +This is used to indicate if the value of a parameter has any affect on an effect's output, eg: the parameter may be purely for GUI purposes, and so changing its value should not trigger a re-render. +*/ +#define kOfxParamPropEvaluateOnChange "OfxParamPropEvaluateOnChange" + +/** @brief Flags whether a parameter should be exposed to a user, + + - Type - int x 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read/write) + - Default - 0 + - Valid Values - 0 or 1 + +If secret, a parameter is not exposed to a user in any interface, but should otherwise behave as a normal parameter. + +Secret params are typically used to hide important state detail that would otherwise be unintelligible to a user, for example the result of a statical analysis that might need many parameters to store. +*/ +#define kOfxParamPropSecret "OfxParamPropSecret" + +/** @brief The value to be used as the id of the parameter in a host scripting language. + + - Type - ASCII C string X 1, + - Property Set - plugin parameter descriptor (read/write) and instance (read only), + - Default - the unique name the parameter was created with. + - Valid Values - ASCII string unique to all parameters in the plug-in. + +Many hosts have a scripting language that they use to set values of parameters and more. If so, this is the name of a parameter in such scripts. +*/ +#define kOfxParamPropScriptName "OfxParamPropScriptName" + +/** @brief Specifies how modifying the value of a param will affect any output of an effect over time. + + - Type - C string X 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read only), + - Default - ::kOfxParamInvalidateValueChange + - Valid Values - This must be one of + - ::kOfxParamInvalidateValueChange + - ::kOfxParamInvalidateValueChangeToEnd + - ::kOfxParamInvalidateAll + +Imagine an effect with an animating parameter in a host that caches +rendered output. Think of the what happens when you add a new key frame. + -If the parameter represents something like an absolute position, the cache will only need to be invalidated for the range of frames that keyframe affects. +- If the parameter represents something like a speed which is integrated, the cache will be invalidated from the keyframe until the end of the clip. +- There are potentially other situations where the entire cache will need to be invalidated (though I can't think of one off the top of my head). +*/ +#define kOfxParamPropCacheInvalidation "OfxParamPropCacheInvalidation" + + /** @brief Used as a value for the ::kOfxParamPropCacheInvalidation property */ +#define kOfxParamInvalidateValueChange "OfxParamInvalidateValueChange" + + /** @brief Used as a value for the ::kOfxParamPropCacheInvalidation property */ +#define kOfxParamInvalidateValueChangeToEnd "OfxParamInvalidateValueChangeToEnd" + + /** @brief Used as a value for the ::kOfxParamPropCacheInvalidation property */ +#define kOfxParamInvalidateAll "OfxParamInvalidateAll" + +/** @brief A hint to the user as to how the parameter is to be used. + + - Type - UTF8 C string X 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read/write), + - Default - "" +*/ +#define kOfxParamPropHint "OfxParamPropHint" + +/** @brief The default value of a parameter. + + - Type - The type is dependant on the parameter type as is the dimension. + - Property Set - plugin parameter descriptor (read/write) and instance (read/write only), + - Default - 0 cast to the relevant type (or "" for strings and custom parameters) + +The exact type and dimension is dependant on the type of the parameter. These are.... + - ::kOfxParamTypeInteger - integer property of one dimension + - ::kOfxParamTypeDouble - double property of one dimension + - ::kOfxParamTypeBoolean - integer property of one dimension + - ::kOfxParamTypeChoice - integer property of one dimension + - ::kOfxParamTypeStrChoice - string property of one dimension + - ::kOfxParamTypeRGBA - double property of four dimensions + - ::kOfxParamTypeRGB - double property of three dimensions + - ::kOfxParamTypeDouble2D - double property of two dimensions + - ::kOfxParamTypeInteger2D - integer property of two dimensions + - ::kOfxParamTypeDouble3D - double property of three dimensions + - ::kOfxParamTypeInteger3D - integer property of three dimensions + - ::kOfxParamTypeString - string property of one dimension + - ::kOfxParamTypeCustom - string property of one dimension + - ::kOfxParamTypeBytes - pointer to OfxBytes struct of one dimension, or nullptr + - ::kOfxParamTypeGroup - does not have this property + - ::kOfxParamTypePage - does not have this property + - ::kOfxParamTypePushButton - does not have this property + */ +#define kOfxParamPropDefault "OfxParamPropDefault" + +/** @brief Describes how the double parameter should be interpreted by a host. + + - Type - C string X 1 + - Default - ::kOfxParamDoubleTypePlain + - Property Set - 1D, 2D and 3D float plugin parameter descriptor (read/write) and instance (read only), + - Valid Values -This must be one of + - ::kOfxParamDoubleTypePlain - parameter has no special interpretation, + - ::kOfxParamDoubleTypeAngle - parameter is to be interpretted as an angle, + - ::kOfxParamDoubleTypeScale - parameter is to be interpretted as a scale factor, + - ::kOfxParamDoubleTypeTime - parameter represents a time value (1D only), + - ::kOfxParamDoubleTypeAbsoluteTime - parameter represents an absolute time value (1D only), + + - ::kOfxParamDoubleTypeX - size wrt to the project's X dimension (1D only), in canonical coordinates, + - ::kOfxParamDoubleTypeXAbsolute - absolute position on the X axis (1D only), in canonical coordinates, + - ::kOfxParamDoubleTypeY - size wrt to the project's Y dimension(1D only), in canonical coordinates, + - ::kOfxParamDoubleTypeYAbsolute - absolute position on the Y axis (1D only), in canonical coordinates, + - ::kOfxParamDoubleTypeXY - size in 2D (2D only), in canonical coordinates, + - ::kOfxParamDoubleTypeXYAbsolute - an absolute position on the image plane, in canonical coordinates. + +Double parameters can be interpreted in several different ways, this property tells the host how to do so and thus gives hints +as to the interface of the parameter. +*/ +#define kOfxParamPropDoubleType "OfxParamPropDoubleType" + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating the parameter has no special interpretation and should be interpretted as a raw numeric value. */ +#define kOfxParamDoubleTypePlain "OfxParamDoubleTypePlain" + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating the parameter is to be interpreted as a scale factor. See \ref ::kOfxParamPropDoubleType. */ +#define kOfxParamDoubleTypeScale "OfxParamDoubleTypeScale" + +/** @brief value for the ::kOfxParamDoubleTypeAngle property, indicating the parameter is to be interpreted as an angle. See \ref ::kOfxParamPropDoubleType. */ +#define kOfxParamDoubleTypeAngle "OfxParamDoubleTypeAngle" + +/** @brief value for the ::kOfxParamDoubleTypeAngle property, indicating the parameter is to be interpreted as a time. See \ref ::kOfxParamPropDoubleType. */ +#define kOfxParamDoubleTypeTime "OfxParamDoubleTypeTime" + +/** @brief value for the ::kOfxParamDoubleTypeAngle property, indicating the parameter is to be interpreted as an absolute time from the start of the effect. See \ref ::kOfxParamPropDoubleType. */ +#define kOfxParamDoubleTypeAbsoluteTime "OfxParamDoubleTypeAbsoluteTime" + + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating a size in canonical coords in the X dimension. See \ref ::kOfxParamPropDoubleType. */ +#define kOfxParamDoubleTypeX "OfxParamDoubleTypeX" + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating a size in canonical coords in the Y dimension. See \ref ::kOfxParamPropDoubleType. */ +#define kOfxParamDoubleTypeY "OfxParamDoubleTypeY" + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating an absolute position in canonical coords in the X dimension. See \ref ::kOfxParamPropDoubleType. */ +#define kOfxParamDoubleTypeXAbsolute "OfxParamDoubleTypeXAbsolute" + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating an absolute position in canonical coords in the Y dimension. See \ref ::kOfxParamPropDoubleType. */ +#define kOfxParamDoubleTypeYAbsolute "OfxParamDoubleTypeYAbsolute" + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating a 2D size in canonical coords. See \ref ::kOfxParamPropDoubleType. */ +#define kOfxParamDoubleTypeXY "OfxParamDoubleTypeXY" + +/** @brief value for the ::kOfxParamPropDoubleType property, indicating a 2D position in canonical coords. See \ref ::kOfxParamPropDoubleType. */ +#define kOfxParamDoubleTypeXYAbsolute "OfxParamDoubleTypeXYAbsolute" + +/** @brief Describes in which coordinate system a spatial double parameter's default value is specified. + + - Type - C string X 1 + - Default - kOfxParamCoordinatesCanonical + - Property Set - Non normalised spatial double parameters, ie: any double param who's ::kOfxParamPropDoubleType is set to one of... + - kOfxParamDoubleTypeX + - kOfxParamDoubleTypeXAbsolute + - kOfxParamDoubleTypeY + - kOfxParamDoubleTypeYAbsolute + - kOfxParamDoubleTypeXY + - kOfxParamDoubleTypeXYAbsolute + - Valid Values - This must be one of + - kOfxParamCoordinatesCanonical - the default is in canonical coords + - kOfxParamCoordinatesNormalised - the default is in normalised coordinates + +This allows a spatial param to specify what its default is, so by saying normalised and "0.5" it would be in the 'middle', by saying canonical and 100 it would be at value 100 independent of the size of the image being applied to. +*/ +#define kOfxParamPropDefaultCoordinateSystem "OfxParamPropDefaultCoordinateSystem" + +/** @brief Define the canonical coordinate system */ +#define kOfxParamCoordinatesCanonical "OfxParamCoordinatesCanonical" + +/** @brief Define the normalised coordinate system */ +#define kOfxParamCoordinatesNormalised "OfxParamCoordinatesNormalised" + +/** @brief A flag to indicate if there is a host overlay UI handle for the given parameter. + + - Type - int x 1 + - Property Set - plugin parameter descriptor (read only) + - Valid Values - 0 or 1 + +If set to 1, then the host is flagging that there is some sort of native user overlay interface handle available for the given parameter. +*/ +#define kOfxParamPropHasHostOverlayHandle "OfxParamPropHasHostOverlayHandle" + +/** @brief A flag to indicate that the host should use a native UI overlay handle for the given parameter. + + - Type - int x 1 + - Property Set - plugin parameter descriptor (read/write only) and instance (read only) + - Default - 0 + - Valid Values - 0 or 1 + +If set to 1, then a plugin is flaging to the host that the host should use a native UI overlay handle for the given parameter. A plugin can use this to keep a native look and feel for parameter handles. A plugin can use ::kOfxParamPropHasHostOverlayHandle to see if handles are available on the given parameter. +*/ +#define kOfxParamPropUseHostOverlayHandle "kOfxParamPropUseHostOverlayHandle" + + +/** @brief Enables the display of a time marker on the host's time line to indicate the value of the absolute time param. + + - Type - int x 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read/write) + - Default - 0 + - Valid Values - 0 or 1 + +If a double parameter is has ::kOfxParamPropDoubleType set to ::kOfxParamDoubleTypeAbsoluteTime, then this indicates whether +any marker should be made visible on the host's time line. + +*/ +#define kOfxParamPropShowTimeMarker "OfxParamPropShowTimeMarker" + +/** @brief Sets the parameter pages and order of pages. + + - Type - C string X N + - Property Set - plugin parameter descriptor (read/write) and instance (read only) + - Default - "" + - Valid Values - the names of any page param in the plugin + +This property sets the preferred order of parameter pages on a host. If this is never set, the preferred order is the order the parameters were declared in. +*/ +#define kOfxPluginPropParamPageOrder "OfxPluginPropParamPageOrder" + +/** @brief The names of the parameters included in a page parameter. + + - Type - C string X N + - Property Set - plugin parameter descriptor (read/write) and instance (read only) + - Default - "" + - Valid Values - the names of any parameter that is not a group or page, as well as ::kOfxParamPageSkipRow and ::kOfxParamPageSkipColumn + +This is a property on parameters of type ::kOfxParamTypePage, and tells the page what parameters it contains. The parameters are added to the page from the top left, filling in columns as we go. The two pseudo param names ::kOfxParamPageSkipRow and ::kOfxParamPageSkipColumn are used to control layout. + +Note parameters can appear in more than one page. +*/ +#define kOfxParamPropPageChild "OfxParamPropPageChild" + +/** @brief The name of a parameter's parent group. + + - Type - C string X 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read only), + - Default - "", which implies the "root" of the hierarchy, + - Valid Values - the name of a parameter with type of ::kOfxParamTypeGroup + +Hosts that have hierarchical layouts of their params use this to recursively group parameter. + +By default parameters are added in order of declaration to the 'root' hierarchy. This property is used to reparent params to a predefined param of type ::kOfxParamTypeGroup. +*/ +#define kOfxParamPropParent "OfxParamPropParent" + +/** @brief Whether the initial state of a group is open or closed in a hierarchical layout. + + - Type - int X 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read only) + - Default - 1 + - Valid Values - 0 or 1 + +This is a property on parameters of type ::kOfxParamTypeGroup, and tells the group whether it should be open or closed by default. + +*/ +#define kOfxParamPropGroupOpen "OfxParamPropGroupOpen" + +/** @brief Used to enable a parameter in the user interface. + + - Type - int X 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read/write), + - Default - 1 + - Valid Values - 0 or 1 + +When set to 0 a user should not be able to modify the value of the parameter. Note that the plug-in itself can still change the value of a disabled parameter. +*/ +#define kOfxParamPropEnabled "OfxParamPropEnabled" + +/** @brief A private data pointer that the plug-in can store its own data behind. + + - Type - pointer X 1 + - Property Set - plugin parameter instance (read/write), + - Default - NULL + +This data pointer is unique to each parameter instance, so two instances of the same parameter do not share the same data pointer. Use it to hang any needed private data structures. + */ +#define kOfxParamPropDataPtr "OfxParamPropDataPtr" + +/** @brief Set options of a choice parameter. + + - Type - UTF8 C string X N + - Property Set - plugin parameter descriptor (read/write) and instance (read/write), + - Default - the property is empty with no options set. + +This property contains the set of options that will be presented to a user +from a choice parameter. See @ref ParametersChoice for more details. +*/ +#define kOfxParamPropChoiceOption "OfxParamPropChoiceOption" + +/** @brief Set values the host should store for a choice parameter. + + - Type - int X N + - Property Set - plugin parameter descriptor (read/write) and instance +(read/write), + - Default - Zero-based ordinal list of same length as +`OfxParamPropChoiceOption` + +This property specifies the order in which the options are presented. +See @ref "Choice Parameters" for more details. +This property is optional; if not set, the host will present the options in +their natural order. + +This property is useful when changing order of choice param options, or adding +new options in the middle, in a new version of the plugin. + + @verbatim + Plugin v1: + Option = {"OptA", "OptB", "OptC"} + Order = {1, 2, 3} + + Plugin v2: + // will be shown as OptA / OptB / NewOpt / OptC + Option = {"OptA", "OptB", "OptC", NewOpt"} + Order = {1, 2, 4, 3} + @endverbatim + +Note that this only affects the host UI's display order; the project still +stores the index of the selected option as always. Plugins should never +reorder existing options if they desire backward compatibility. + +Values may be arbitrary 32-bit integers. Behavior is undefined if the same +value occurs twice in the list; plugins should not do that. + +\since Version 1.5 +*/ +#define kOfxParamPropChoiceOrder "OfxParamPropChoiceOrder" + + +/** @brief Set a enumeration string in a StrChoice (string-valued choice) parameter. + + - Type - UTF8 C string X N + - Property Set - plugin parameter descriptor (read/write) and instance +(read/write), + - Default - the property is empty with no options set. + +This property contains the set of enumeration strings stored by the host in +the project corresponding to the options that will be presented to a user +from a StrChoice parameter. See @ref ParametersChoice for more details. + +\since Version 1.5 +*/ +#define kOfxParamPropChoiceEnum "OfxParamPropChoiceEnum" + +/** @brief Indicates if the host supports animation of string choice params. + + - Type - int X 1 + - Property Set - host descriptor (read only) + - Valid Values - 0 or 1 + +\since Version 1.5 +*/ +#define kOfxParamHostPropSupportsStrChoiceAnimation "OfxParamHostPropSupportsStrChoiceAnimation" + +/** @brief Indicates if the host supports the StrChoice param type. + + - Type - int X 1 + - Property Set - host descriptor (read only) + - Valid Values - 0 or 1 + +\since Version 1.5 +*/ +#define kOfxParamHostPropSupportsStrChoice "OfxParamHostPropSupportsStrChoice" + +/** @brief The minimum value for a numeric parameter. + + - Type - int or double X N + - Property Set - plugin parameter descriptor (read/write) and instance (read/write), + - Default - the smallest possible value corresponding to the parameter type (eg: INT_MIN for an integer, -DBL_MAX for a double parameter) + +Setting this will also reset ::kOfxParamPropDisplayMin. +*/ +#define kOfxParamPropMin "OfxParamPropMin" + +/** @brief The maximum value for a numeric parameter. + + - Type - int or double X N + - Property Set - plugin parameter descriptor (read/write) and instance (read/write), + - Default - the largest possible value corresponding to the parameter type (eg: INT_MAX for an integer, DBL_MAX for a double parameter) + +Setting this will also reset :;kOfxParamPropDisplayMax. +*/ +#define kOfxParamPropMax "OfxParamPropMax" + +/** @brief The minimum value for a numeric parameter on any user interface. + + - Type - int or double X N + - Property Set - plugin parameter descriptor (read/write) and instance (read/write), + - Default - the smallest possible value corresponding to the parameter type (eg: INT_MIN for an integer, -DBL_MAX for a double parameter) + +If a user interface represents a parameter with a slider or similar, this should be the minumum bound on that slider. +*/ +#define kOfxParamPropDisplayMin "OfxParamPropDisplayMin" + +/** @brief The maximum value for a numeric parameter on any user interface. + + - Type - int or double X N + - Property Set - plugin parameter descriptor (read/write) and instance (read/write), + - Default - the largest possible value corresponding to the parameter type (eg: INT_MAX for an integer, DBL_MAX for a double parameter) + +If a user interface represents a parameter with a slider or similar, this should be the maximum bound on that slider. +*/ +#define kOfxParamPropDisplayMax "OfxParamPropDisplayMax" + +/** @brief The granularity of a slider used to represent a numeric parameter. + + - Type - double X 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read/write), + - Default - 1 + - Valid Values - any greater than 0. + +This value is always in canonical coordinates for double parameters that are normalised. +*/ +#define kOfxParamPropIncrement "OfxParamPropIncrement" + +/** @brief How many digits after a decimal point to display for a double param in a GUI. + + - Type - int X 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read/write), + - Default - 2 + - Valid Values - any greater than 0. + +This applies to double params of any dimension. +*/ +#define kOfxParamPropDigits "OfxParamPropDigits" + +/** @brief Label for individual dimensions on a multidimensional numeric parameter. + + - Type - UTF8 C string X 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read only), + - Default - "x", "y" and "z" + - Valid Values - any + +Use this on 2D and 3D double and integer parameters to change the label on an individual dimension in any GUI for that parameter. +*/ +#define kOfxParamPropDimensionLabel "OfxParamPropDimensionLabel" + +/** @brief Will a value change on the parameter add automatic keyframes. + + - Type - int X 1 + - Property Set - plugin parameter instance (read only), + - Valid Values - 0 or 1 + +This is set by the host simply to indicate the state of the property. +*/ +#define kOfxParamPropIsAutoKeying "OfxParamPropIsAutoKeying" + +/** @brief A pointer to a custom parameter's interpolation function. + + - Type - pointer X 1 + - Property Set - plugin parameter descriptor (read/write) and instance (read only), + - Default - NULL + - Valid Values - must point to a ::OfxCustomParamInterpFuncV1 + +It is an error not to set this property in a custom parameter during a plugin's define call if the custom parameter declares itself to be an animating parameter. + */ +#define kOfxParamPropCustomInterpCallbackV1 "OfxParamPropCustomCallbackV1" + +/** @brief Used to indicate the type of a string parameter. + + - Type - C string X 1 + - Property Set - plugin string parameter descriptor (read/write) and instance (read only), + - Default - ::kOfxParamStringIsSingleLine + - Valid Values - This must be one of the following + - ::kOfxParamStringIsSingleLine + - ::kOfxParamStringIsMultiLine + - ::kOfxParamStringIsFilePath + - ::kOfxParamStringIsDirectoryPath + - ::kOfxParamStringIsLabel + - ::kOfxParamStringIsRichTextFormat + +*/ +#define kOfxParamPropStringMode "OfxParamPropStringMode" + +/** @brief Indicates string parameters of file or directory type need that file to exist already. + + - Type - int X 1 + - Property Set - plugin string parameter descriptor (read/write) and instance (read only), + - Default - 1 + - Valid Values - 0 or 1 + +If set to 0, it implies the user can specify a new file name, not just a pre-existing one. + */ +#define kOfxParamPropStringFilePathExists "OfxParamPropStringFilePathExists" + +/** @brief Used to set a string parameter to be single line, + value to be passed to a ::kOfxParamPropStringMode property */ +#define kOfxParamStringIsSingleLine "OfxParamStringIsSingleLine" + +/** @brief Used to set a string parameter to be multiple line, + value to be passed to a ::kOfxParamPropStringMode property */ +#define kOfxParamStringIsMultiLine "OfxParamStringIsMultiLine" + +/** @brief Used to set a string parameter to be a file path, + value to be passed to a ::kOfxParamPropStringMode property */ +#define kOfxParamStringIsFilePath "OfxParamStringIsFilePath" + +/** @brief Used to set a string parameter to be a directory path, + value to be passed to a ::kOfxParamPropStringMode property */ +#define kOfxParamStringIsDirectoryPath "OfxParamStringIsDirectoryPath" + +/** @brief Use to set a string parameter to be a simple label, + value to be passed to a ::kOfxParamPropStringMode property */ +#define kOfxParamStringIsLabel "OfxParamStringIsLabel" + + /** @brief String value on the ::kOfxParamPropStringMode property of a + string parameter (added in 1.3) */ +#define kOfxParamStringIsRichTextFormat "OfxParamStringIsRichTextFormat" + +/** @brief Used by interpolating custom parameters to get and set interpolated values. + - Type - C string X 1 or 2 + +This property is on the \e inArgs property and \e outArgs property of a ::OfxCustomParamInterpFuncV1 and in both cases contains the encoded value of a custom parameter. As an \e inArgs property it will have two values, being the two keyframes to interpolate. As an \e outArgs property it will have a single value and the plugin should fill this with the encoded interpolated value of the parameter. + */ +#define kOfxParamPropCustomValue "OfxParamPropCustomValue" + +/** @brief Used by interpolating custom parameters to indicate the time a key occurs at. + + - Type - double X 2 + - Property Set - inArgs parameter of a ::OfxCustomParamInterpFuncV1 (read only) + +The two values indicate the absolute times the surrounding keyframes occur at. The keyframes are encoded in a ::kOfxParamPropCustomValue property. + + */ +#define kOfxParamPropInterpolationTime "OfxParamPropInterpolationTime" + +/** @brief Property used by ::OfxCustomParamInterpFuncV1 to indicate the amount of interpolation to perform + + - Type - double X 1 + - Property Set - inArgs parameter of a ::OfxCustomParamInterpFuncV1 (read only) + - Valid Values - from 0 to 1 + +This property indicates how far between the two ::kOfxParamPropCustomValue keys to interpolate. + */ +#define kOfxParamPropInterpolationAmount "OfxParamPropInterpolationAmount" + +/*@}*/ +/*@}*/ + +/** @brief Function prototype for custom parameter interpolation callback functions + + \arg \c instance the plugin instance that this parameter occurs in + \arg \c inArgs handle holding the following properties... + - kOfxPropName - the name of the custom parameter to interpolate + - kOfxPropTime - absolute time the interpolation is ocurring at + - kOfxParamPropCustomValue - string property that gives the value of the two keyframes to interpolate, in this case 2D + - kOfxParamPropInterpolationTime - 2D double property that gives the time of the two keyframes we are interpolating + - kOfxParamPropInterpolationAmount - 1D double property indicating how much to interpolate between the two keyframes + + \arg \c outArgs handle holding the following properties to be set + - kOfxParamPropCustomValue - the value of the interpolated custom parameter, in this case 1D + +This function allows custom parameters to animate by performing interpolation between keys. + +The plugin needs to parse the two strings encoding keyframes on either side of the time +we need a value for. It should then interpolate a new value for it, encode it into a string and set +the ::kOfxParamPropCustomValue property with this on the outArgs handle. + +The interp value is a linear interpolation amount, however his may be derived from a cubic (or other) curve. +*/ +typedef OfxStatus (OfxCustomParamInterpFuncV1)(OfxParamSetHandle instance, + OfxPropertySetHandle inArgs, + OfxPropertySetHandle outArgs); + + +/** @brief The OFX suite used to define and manipulate user visible parameters + */ +typedef struct OfxParameterSuiteV1 { + /** @brief Defines a new parameter of the given type in a describe action + + \arg \c paramSet handle to the parameter set descriptor that will hold this parameter + \arg \c paramType type of the parameter to create, one of the kOfxParamType* #defines + \arg \c name unique name of the parameter + \arg \c propertySet if not null, a pointer to the parameter descriptor's property set will be placed here. + + This function defines a parameter in a parameter set and returns a property set which is used to describe that parameter. + + This function does not actually create a parameter, it only says that one should exist in any subsequent instances. To fetch an + parameter instance paramGetHandle must be called on an instance. + + This function can always be called in one of a plug-in's "describe" functions which defines the parameter sets common to all instances of a plugin. + +@returns + - ::kOfxStatOK - the parameter was created correctly + - ::kOfxStatErrBadHandle - if the plugin handle was invalid + - ::kOfxStatErrExists - if a parameter of that name exists already in this plugin + - ::kOfxStatErrUnknown - if the type is unknown + - ::kOfxStatErrUnsupported - if the type is known but unsupported + */ + OfxStatus (*paramDefine)(OfxParamSetHandle paramSet, + const char *paramType, + const char *name, + OfxPropertySetHandle *propertySet); + + /** @brief Retrieves the handle for a parameter in a given parameter set + + \arg \c paramSet instance of the plug-in to fetch the property handle from + \arg \c name parameter to ask about + \arg \c param pointer to a param handle, the value is returned here + \arg \c propertySet if not null, a pointer to the parameter's property set will be placed here. + + Parameter handles retrieved from an instance are always distinct in each instance. The paramter handle is valid for the life-time of the instance. Parameter handles in instances are distinct from paramter handles in plugins. You cannot call this in a plugin's describe function, as it needs an instance to work on. + +@returns + - ::kOfxStatOK - the parameter was found and returned + - ::kOfxStatErrBadHandle - if the plugin handle was invalid + - ::kOfxStatErrUnknown - if the type is unknown + */ + OfxStatus (*paramGetHandle)(OfxParamSetHandle paramSet, + const char *name, + OfxParamHandle *param, + OfxPropertySetHandle *propertySet); + + /** @brief Retrieves the property set handle for the given parameter set + + \arg \c paramSet parameter set to get the property set for + \arg \c propHandle pointer to a the property set handle, value is returedn her + + \note The property handle belonging to a parameter set is the same as the property handle belonging to the plugin instance. + +@returns + - ::kOfxStatOK - the property set was found and returned + - ::kOfxStatErrBadHandle - if the paramter handle was invalid + - ::kOfxStatErrUnknown - if the type is unknown + */ + OfxStatus (*paramSetGetPropertySet)(OfxParamSetHandle paramSet, + OfxPropertySetHandle *propHandle); + + /** @brief Retrieves the property set handle for the given parameter + + \arg \c param parameter to get the property set for + \arg \c propHandle pointer to a the property set handle, value is returedn her + + The property handle is valid for the lifetime of the parameter, which is the lifetime of the instance that owns the parameter + +@returns + - ::kOfxStatOK - the property set was found and returned + - ::kOfxStatErrBadHandle - if the paramter handle was invalid + - ::kOfxStatErrUnknown - if the type is unknown + */ + OfxStatus (*paramGetPropertySet)(OfxParamHandle param, + OfxPropertySetHandle *propHandle); + + /** @brief Gets the current value of a parameter, + + \arg \c paramHandle parameter handle to fetch value from + \arg \c ... one or more pointers to variables of the relevant type to hold the parameter's value + + This gets the current value of a parameter. The varargs ... argument needs to be pointer to C variables + of the relevant type for this parameter. Note that params with multiple values (eg Colour) take + multiple args here. For example... + + @verbatim + OfxParamHandle myDoubleParam, *myColourParam; + ofxHost->paramGetHandle(instance, "myDoubleParam", &myDoubleParam); + double myDoubleValue; + ofxHost->paramGetValue(myDoubleParam, &myDoubleValue); + ofxHost->paramGetHandle(instance, "myColourParam", &myColourParam); + double myR, myG, myB; + ofxHost->paramGetValue(myColourParam, &myR, &myG, &myB); + @endverbatim + + \note \c paramGetValue should only be called from within a ::kOfxActionInstanceChanged or interact action and never from the render actions (which should always use paramGetValueAtTime). + +@returns + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the parameter handle was invalid + */ + OfxStatus (*paramGetValue)(OfxParamHandle paramHandle, + ...); + + + /** @brief Gets the value of a parameter at a specific time. + + \arg \c paramHandle parameter handle to fetch value from + \arg \c time at what point in time to look up the parameter + \arg \c ... one or more pointers to variables of the relevant type to hold the parameter's value + + This gets the current value of a parameter. The varargs needs to be pointer to C variables + of the relevant type for this parameter. See OfxParameterSuiteV1::paramGetValue for notes on + the varags list + +@returns + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the parameter handle was invalid + */ + OfxStatus (*paramGetValueAtTime)(OfxParamHandle paramHandle, + OfxTime time, + ...); + + /** @brief Gets the derivative of a parameter at a specific time. + + \arg \c paramHandle parameter handle to fetch value from + \arg \c time at what point in time to look up the parameter + \arg \c ... one or more pointers to variables of the relevant type to hold the parameter's derivative + + This gets the derivative of the parameter at the indicated time. + + The varargs needs to be pointer to C variables + of the relevant type for this parameter. See OfxParameterSuiteV1::paramGetValue for notes on + the varags list. + + Only double and colour params can have their derivatives found. + +@returns + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the parameter handle was invalid + */ + OfxStatus (*paramGetDerivative)(OfxParamHandle paramHandle, + OfxTime time, + ...); + + /** @brief Gets the integral of a parameter over a specific time range, + + \arg \c paramHandle parameter handle to fetch integral from + \arg \c time1 where to start evaluating the integral + \arg \c time2 where to stop evaluating the integral + \arg \c ... one or more pointers to variables of the relevant type to hold the parameter's integral + + This gets the integral of the parameter over the specified time range. + + The varargs needs to be pointer to C variables + of the relevant type for this parameter. See OfxParameterSuiteV1::paramGetValue for notes on + the varags list. + + Only double and colour params can be integrated. + +@returns + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the parameter handle was invalid + */ + OfxStatus (*paramGetIntegral)(OfxParamHandle paramHandle, + OfxTime time1, OfxTime time2, + ...); + + /** @brief Sets the current value of a parameter + + \arg \c paramHandle parameter handle to set value in + \arg \c ... one or more variables of the relevant type to hold the parameter's value + + This sets the current value of a parameter. The varargs ... argument needs to be values + of the relevant type for this parameter. Note that params with multiple values (eg Colour) take + multiple args here. For example... + @verbatim + ofxHost->paramSetValue(instance, "myDoubleParam", double(10)); + ofxHost->paramSetValue(instance, "myColourParam", double(pix.r), double(pix.g), double(pix.b)); + @endverbatim + + \note \c paramSetValue should only be called from within a ::kOfxActionInstanceChanged or interact action. + +@returns + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the parameter handle was invalid + */ + OfxStatus (*paramSetValue)(OfxParamHandle paramHandle, + ...); + + /** @brief Keyframes the value of a parameter at a specific time. + + \arg \c paramHandle parameter handle to set value in + \arg \c time at what point in time to set the keyframe + \arg \c ... one or more variables of the relevant type to hold the parameter's value + + This sets a keyframe in the parameter at the indicated time to have the indicated value. + The varargs ... argument needs to be values of the relevant type for this parameter. See the note on + OfxParameterSuiteV1::paramSetValue for more detail + + \note \c paramSetValueAtTime should only be called from within a ::kOfxActionInstanceChanged or interact action. + + V1.3: This function can be called the ::kOfxActionInstanceChanged action and during image effect analysis render passes. + V1.4: This function can be called the ::kOfxActionInstanceChanged action +@returns + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the parameter handle was invalid + */ + OfxStatus (*paramSetValueAtTime)(OfxParamHandle paramHandle, + OfxTime time, // time in frames + ...); + + +/** @name Keyframe Handling + +These functions allow the plug-in to delete and get information about keyframes. + +To set keyframes, use paramSetValueAtTime(). + +paramGetKeyTime and paramGetKeyIndex use indices to refer to keyframes. +Keyframes are stored by the host in increasing time order, so time(kf[i]) < time(kf[i+1]). +Keyframe indices will change whenever keyframes are added, deleted, or moved in time, +whether by the host or by the plug-in. They may vary between actions if the user +changes a keyframe. The keyframe indices will not change within a single action. + */ +/** @{ */ + + /** @brief Returns the number of keyframes in the parameter + + \arg \c paramHandle parameter handle to interrogate + \arg \c numberOfKeys pointer to integer where the return value is placed + + V1.3: This function can be called the ::kOfxActionInstanceChanged action and during image effect analysis render passes. + V1.4: This function can be called the ::kOfxActionInstanceChanged action + + Returns the number of keyframes in the parameter. + +@returns + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the parameter handle was invalid + */ + OfxStatus (*paramGetNumKeys)(OfxParamHandle paramHandle, + unsigned int *numberOfKeys); + + /** @brief Returns the time of the nth key + + \arg \c paramHandle parameter handle to interrogate + \arg \c nthKey which key to ask about (0 to paramGetNumKeys -1), ordered by time + \arg \c time pointer to OfxTime where the return value is placed + +@returns + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the parameter handle was invalid + - ::kOfxStatErrBadIndex - the nthKey does not exist + */ + OfxStatus (*paramGetKeyTime)(OfxParamHandle paramHandle, + unsigned int nthKey, + OfxTime *time); + + + /** @brief Finds the index of a keyframe at/before/after a specified time. + + \arg \c paramHandle parameter handle to search + \arg \c time what time to search from + \arg \c direction + - == 0 indicates search for a key at the indicated time (some small delta) + - > 0 indicates search for the next key after the indicated time + - < 0 indicates search for the previous key before the indicated time + \arg \c index pointer to an integer which in which the index is returned set to -1 if no key was found + +@returns + - ::kOfxStatOK - all was OK + - ::kOfxStatFailed - if the search failed to find a key + - ::kOfxStatErrBadHandle - if the parameter handle was invalid + */ + OfxStatus (*paramGetKeyIndex)(OfxParamHandle paramHandle, + OfxTime time, + int direction, + int *index); + + /** @brief Deletes a keyframe if one exists at the given time. + + \arg \c paramHandle parameter handle to delete the key from + \arg \c time time at which a keyframe is + +@returns + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the parameter handle was invalid + - ::kOfxStatErrBadIndex - no key at the given time + */ + OfxStatus (*paramDeleteKey)(OfxParamHandle paramHandle, + OfxTime time); + + /** @brief Deletes all keyframes from a parameter. + + \arg \c paramHandle parameter handle to delete the keys from + \arg \c name parameter to delete the keyframes frome is + + V1.3: This function can be called the ::kOfxActionInstanceChanged action and during image effect analysis render passes. + V1.4: This function can be called the ::kOfxActionInstanceChanged action + +@returns + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the parameter handle was invalid + */ + OfxStatus (*paramDeleteAllKeys)(OfxParamHandle paramHandle); + +/** @} */ + + /** @brief Copies one parameter to another, including any animation etc... + + \arg \c paramTo parameter to set + \arg \c paramFrom parameter to copy from + \arg \c dstOffset temporal offset to apply to keys when writing to the paramTo + \arg \c frameRange if paramFrom has animation, and frameRange is not null, only this range of keys will be copied + + This copies the value of \e paramFrom to \e paramTo, including any animation it may have. All the previous values in \e paramTo will be lost. + + To choose all animation in \e paramFrom set \e frameRange to [0, 0] + + V1.3: This function can be called the ::kOfxActionInstanceChanged action and during image effect analysis render passes. + V1.4: This function can be called the ::kOfxActionInstanceChanged action + + \pre + - Both parameters must be of the same type. + + \return + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the parameter handle was invalid + */ + OfxStatus (*paramCopy)(OfxParamHandle paramTo, OfxParamHandle paramFrom, OfxTime dstOffset, const OfxRangeD *frameRange); + + + /** @brief Used to group any parameter changes for undo/redo purposes + + \arg \c paramSet the parameter set in which this is happening + \arg \c name label to attach to any undo/redo string UTF8 + + If a plugin calls paramSetValue/paramSetValueAtTime on one or more parameters, either from custom GUI interaction + or some analysis of imagery etc.. this is used to indicate the start of a set of a parameter + changes that should be considered part of a single undo/redo block. + + \note \c paramEditBegin should only be called from within a ::kOfxActionInstanceChanged or interact action. + + See also OfxParameterSuiteV1::paramEditEnd + + \return + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the instance handle was invalid + + */ + OfxStatus (*paramEditBegin)(OfxParamSetHandle paramSet, const char *name); + + /** @brief Used to group any parameter changes for undo/redo purposes + + \arg \c paramSet parameter set in which this is happening + + If a plugin calls paramSetValue/paramSetValueAtTime on one or more parameters, either from custom GUI interaction + or some analysis of imagery etc.. this is used to indicate the end of a set of parameter + changes that should be considerred part of a single undo/redo block + + \note \c paramEditEnd should only be called from within a ::kOfxActionInstanceChanged or interact action. + + See also OfxParameterSuiteV1::paramEditBegin + +@returns + - ::kOfxStatOK - all was OK + - ::kOfxStatErrBadHandle - if the instance handle was invalid + + */ + OfxStatus (*paramEditEnd)(OfxParamSetHandle paramSet); + } OfxParameterSuiteV1; + +#ifdef __cplusplus +} +#endif + + +/** @file ofxParam.h + + This header contains the suite definition to manipulate host side parameters. + + For more details go see @ref ParametersPage +*/ + + +#endif diff --git a/src/modules/openfx/ofxParametricParam.h b/src/modules/openfx/ofxParametricParam.h new file mode 100644 index 000000000..2d52fdd0f --- /dev/null +++ b/src/modules/openfx/ofxParametricParam.h @@ -0,0 +1,284 @@ +#ifndef _ofxParametricParam_h_ +#define _ofxParametricParam_h_ + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + +/** @file ofxParametricParam.h + +This header file defines the optional OFX extension to define and manipulate parametric +parameters. + +*/ + +#include "ofxParam.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** @brief string value to the ::kOfxPropType property for all parameters */ +#define kOfxParametricParameterSuite "OfxParametricParameterSuite" + + +/** + \defgroup ParamTypeDefines Parameter Type definitions + +These strings are used to identify the type of the parameter when it is defined, they are also on the ::kOfxParamPropType in any parameter instance. +*/ +/*@{*/ + +/** @brief String to identify a param as a single valued integer */ +#define kOfxParamTypeParametric "OfxParamTypeParametric" + +/*@}*/ + +/** + \addtogroup PropertiesAll +*/ +/*@{*/ +/** + \defgroup ParamPropDefines Parameter Property Definitions + +These are the list of properties used by the parameters suite. +*/ +/*@{*/ + +/** @brief The dimension of a parametric param + + - Type - int X 1 + - Property Set - parametric param descriptor (read/write) and instance (read only) + - default - 1 + - Value Values - greater than 0 + +This indicates the dimension of the parametric param. +*/ +#define kOfxParamPropParametricDimension "OfxParamPropParametricDimension" + +/** @brief The colour of parametric param curve interface in any UI. + + - Type - double X N + - Property Set - parametric param descriptor (read/write) and instance (read only) + - default - unset, + - Value Values - three values for each dimension (see ::kOfxParamPropParametricDimension) + being interpretted as R, G and B of the colour for each curve drawn in the UI. + +This sets the colour of a parametric param curve drawn a host user interface. A colour triple +is needed for each dimension of the oparametric param. + +If not set, the host should generally draw these in white. +*/ +#define kOfxParamPropParametricUIColour "OfxParamPropParametricUIColour" + +/** @brief Interact entry point to draw the background of a parametric parameter. + + - Type - pointer X 1 + - Property Set - plug-in parametric parameter descriptor (read/write) and instance (read only), + - Default - NULL, which implies the host should draw its default background. + +Defines a pointer to an interact which will be used to draw the background of a parametric +parameter's user interface. None of the pen or keyboard actions can ever be called on the interact. + +The openGL transform will be set so that it is an orthographic transform that maps directly to the +'parametric' space, so that 'x' represents the parametric position and 'y' represents the evaluated +value. +*/ +#define kOfxParamPropParametricInteractBackground "OfxParamPropParametricInteractBackground" + +/** @brief Property on the host to indicate support for parametric parameter animation. + + - Type - int X 1 + - Property Set - host descriptor (read only) + - Valid Values + - 0 indicating the host does not support animation of parmetric params, + - 1 indicating the host does support animation of parmetric params, +*/ +#define kOfxParamHostPropSupportsParametricAnimation "OfxParamHostPropSupportsParametricAnimation" + +/** @brief Property to indicate the min and max range of the parametric input value. + + - Type - double X 2 + - Property Set - parameter descriptor (read/write only), and instance (read only) + - Default Value - (0, 1) + - Valid Values - any pair of numbers so that the first is less than the second. + +This controls the min and max values that the parameter will be evaluated at. +*/ +#define kOfxParamPropParametricRange "OfxParamPropParametricRange" + +/*@}*/ +/*@}*/ + + +/** @brief The OFX suite used to define and manipulate 'parametric' parameters. + +This is an optional suite. + +Parametric parameters are in effect 'functions' a plug-in can ask a host to arbitrarily +evaluate for some value 'x'. A classic use case would be for constructing look-up tables, +a plug-in would ask the host to evaluate one at multiple values from 0 to 1 and use that +to fill an array. + +A host would probably represent this to a user as a cubic curve in a standard curve editor +interface, or possibly through scripting. The user would then use this to define the 'shape' +of the parameter. + +The evaluation of such params is not the same as animation, they are returning values based +on some arbitrary argument orthogonal to time, so to evaluate such a param, you need to pass +a parametric position and time. + +Often, you would want such a parametric parameter to be multi-dimensional, for example, a +colour look-up table might want three values, one for red, green and blue. Rather than +declare three separate parametric parameters, it would be better to have one such parameter +with multiple values in it. + +The major complication with these parameters is how to allow a plug-in to set values, and +defaults. The default default value of a parametric curve is to be an identity lookup. If +a plugin wishes to set a different default value for a curve, it can use the suite to set +key/value pairs on the \em descriptor of the param. When a new instance is made, it will +have these curve values as a default. +*/ +typedef struct OfxParametricParameterSuiteV1 { + + /** @brief Evaluates a parametric parameter + + \arg \c param handle to the parametric parameter + \arg \c curveIndex which dimension to evaluate + \arg \c time the time to evaluate to the parametric param at + \arg \c parametricPosition the position to evaluate the parametric param at + \arg \c returnValue pointer to a double where a value is returned + + @returns + - ::kOfxStatOK - all was fine + - ::kOfxStatErrBadHandle - if the paramter handle was invalid + - ::kOfxStatErrBadIndex - the curve index was invalid + */ + OfxStatus (*parametricParamGetValue)(OfxParamHandle param, + int curveIndex, + OfxTime time, + double parametricPosition, + double *returnValue); + + + /** @brief Returns the number of control points in the parametric param. + + \arg \c param handle to the parametric parameter + \arg \c curveIndex which dimension to check + \arg \c time the time to check + \arg \c returnValue pointer to an integer where the value is returned. + + @returns + - ::kOfxStatOK - all was fine + - ::kOfxStatErrBadHandle - if the paramter handle was invalid + - ::kOfxStatErrBadIndex - the curve index was invalid + */ + OfxStatus (*parametricParamGetNControlPoints)(OfxParamHandle param, + int curveIndex, + double time, + int *returnValue); + + /** @brief Returns the key/value pair of the nth control point. + + \arg \c param handle to the parametric parameter + \arg \c curveIndex which dimension to check + \arg \c time the time to check + \arg \c nthCtl the nth control point to get the value of + \arg \c key pointer to a double where the key will be returned + \arg \c value pointer to a double where the value will be returned + + @returns + - ::kOfxStatOK - all was fine + - ::kOfxStatErrBadHandle - if the paramter handle was invalid + - ::kOfxStatErrUnknown - if the type is unknown + */ + OfxStatus (*parametricParamGetNthControlPoint)(OfxParamHandle param, + int curveIndex, + double time, + int nthCtl, + double *key, + double *value); + + /** @brief Modifies an existing control point on a curve + + \arg \c param handle to the parametric parameter + \arg \c curveIndex which dimension to set + \arg \c time the time to set the value at + \arg \c nthCtl the control point to modify + \arg \c key key of the control point + \arg \c value value of the control point + \arg \c addAnimationKey if the param is an animatable, setting this to true will + force an animation keyframe to be set as well as a curve key, + otherwise if false, a key will only be added if the curve is already + animating. + + @returns + - ::kOfxStatOK - all was fine + - ::kOfxStatErrBadHandle - if the paramter handle was invalid + - ::kOfxStatErrUnknown - if the type is unknown + + This modifies an existing control point. Note that by changing key, the order of the + control point may be modified (as you may move it before or after anther point). So be + careful when iterating over a curves control points and you change a key. + */ + OfxStatus (*parametricParamSetNthControlPoint)(OfxParamHandle param, + int curveIndex, + double time, + int nthCtl, + double key, + double value, + bool addAnimationKey); + + /** @brief Adds a control point to the curve. + + \arg \c param handle to the parametric parameter + \arg \c curveIndex which dimension to set + \arg \c time the time to set the value at + \arg \c key key of the control point + \arg \c value value of the control point + \arg \c addAnimationKey if the param is an animatable, setting this to true will + force an animation keyframe to be set as well as a curve key, + otherwise if false, a key will only be added if the curve is already + animating. + + @returns + - ::kOfxStatOK - all was fine + - ::kOfxStatErrBadHandle - if the paramter handle was invalid + - ::kOfxStatErrUnknown - if the type is unknown + + This will add a new control point to the given dimension of a parametric parameter. If a key exists + sufficiently close to 'key', then it will be set to the indicated control point. + */ + OfxStatus (*parametricParamAddControlPoint)(OfxParamHandle param, + int curveIndex, + double time, + double key, + double value, + bool addAnimationKey); + + /** @brief Deletes the nth control point from a parametric param. + + \arg \c param handle to the parametric parameter + \arg \c curveIndex which dimension to delete + \arg \c nthCtl the control point to delete + */ + OfxStatus (*parametricParamDeleteControlPoint)(OfxParamHandle param, + int curveIndex, + int nthCtl); + + /** @brief Delete all curve control points on the given param. + + \arg \c param handle to the parametric parameter + \arg \c curveIndex which dimension to clear + */ + OfxStatus (*parametricParamDeleteAllControlPoints)(OfxParamHandle param, + int curveIndex); + } OfxParametricParameterSuiteV1; + +#ifdef __cplusplus +} +#endif + + + + +#endif diff --git a/src/modules/openfx/ofxPixels.h b/src/modules/openfx/ofxPixels.h new file mode 100644 index 000000000..4de4f8d61 --- /dev/null +++ b/src/modules/openfx/ofxPixels.h @@ -0,0 +1,62 @@ +#ifndef _ofxPixels_h_ +#define _ofxPixels_h_ + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + + +#ifdef __cplusplus +extern "C" { +#endif + +/** @file ofxPixels.h +Contains pixel struct definitions +*/ + +/** @brief Defines an 8 bit per component RGBA pixel */ +typedef struct OfxRGBAColourB { + unsigned char r, g, b, a; +}OfxRGBAColourB; + +/** @brief Defines a 16 bit per component RGBA pixel */ +typedef struct OfxRGBAColourS { + unsigned short r, g, b, a; +}OfxRGBAColourS; + +/** @brief Defines a floating point component RGBA pixel */ +typedef struct OfxRGBAColourF { + float r, g, b, a; +}OfxRGBAColourF; + + +/** @brief Defines a double precision floating point component RGBA pixel */ +typedef struct OfxRGBAColourD { + double r, g, b, a; +}OfxRGBAColourD; + + +/** @brief Defines an 8 bit per component RGB pixel */ +typedef struct OfxRGBColourB { + unsigned char r, g, b; +}OfxRGBColourB; + +/** @brief Defines a 16 bit per component RGB pixel */ +typedef struct OfxRGBColourS { + unsigned short r, g, b; +}OfxRGBColourS; + +/** @brief Defines a floating point component RGB pixel */ +typedef struct OfxRGBColourF { + float r, g, b; +}OfxRGBColourF; + +/** @brief Defines a double precision floating point component RGB pixel */ +typedef struct OfxRGBColourD { + double r, g, b; +}OfxRGBColourD; + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/src/modules/openfx/ofxProgress.h b/src/modules/openfx/ofxProgress.h new file mode 100644 index 000000000..c28e2818c --- /dev/null +++ b/src/modules/openfx/ofxProgress.h @@ -0,0 +1,151 @@ +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + +#ifndef _ofxProgressSuite_h_ +#define _ofxProgressSuite_h_ + +/** @brief suite for displaying a progress bar */ +#define kOfxProgressSuite "OfxProgressSuite" + +/** @brief A suite that provides progress feedback from a plugin to an application + + A plugin instance can initiate, update and close a progress indicator with + this suite. + + This is an optional suite in the Image Effect API. + + API V1.4: Amends the documentation of progress suite V1 so that it is + expected that it can be raised in a modal manner and have a "cancel" + button when invoked in instanceChanged. Plugins that perform analysis + post an appropriate message, raise the progress monitor in a modal manner + and should poll to see if processing has been aborted. Any cancellation + should be handled gracefully by the plugin (eg: reset analysis parameters + to default values), clear allocated memory... + + Many hosts already operate as described above. kOfxStatReplyNo should be + returned to the plugin during progressUpdate when the user presses + cancel. + + Suite V2: Adds an ID that can be looked up for internationalisation and + so on. When a new version is introduced, because plug-ins need to support + old versions, and plug-in's new releases are not necessary in synch with + hosts (or users don't immediately update), best practice is to support + the 2 suite versions. That is, the plugin should check if V2 exists; if + not then check if V1 exists. This way a graceful transition is + guaranteed. So plugin should fetchSuite passing 2, + (OfxProgressSuiteV2*) fetchSuite(mHost->mHost->host, kOfxProgressSuite,2); + and if no success pass (OfxProgressSuiteV1*) + fetchSuite(mHost->mHost->host, kOfxProgressSuite,1); +*/ +typedef struct OfxProgressSuiteV1 { + + /** @brief Initiate a progress bar display. + + Call this to initiate the display of a progress bar. + + \arg \c effectInstance the instance of the plugin this progress bar is + associated with. It cannot be NULL. + \arg \c label a text label to display in any message portion of the + progress object's user interface. A UTF8 string. + + \pre - There is no currently ongoing progress display for this instance. + + \returns + - ::kOfxStatOK - the handle is now valid for use + - ::kOfxStatFailed - the progress object failed for some reason + - ::kOfxStatErrBadHandle - effectInstance was invalid + */ + OfxStatus (*progressStart)(void *effectInstance, + const char *label); + + /** @brief Indicate how much of the processing task has been completed and reports on any abort status. + + \arg \c effectInstance the instance of the plugin this progress bar is + associated with. It cannot be NULL. + \arg \c progress a number between 0.0 and 1.0 indicating what proportion of the current task has been processed. + + \returns + - ::kOfxStatOK - the progress object was successfully updated and the task should continue + - ::kOfxStatReplyNo - the progress object was successfully updated and the task should abort + - ::kOfxStatErrBadHandle - the progress handle was invalid, + */ + OfxStatus (*progressUpdate)(void *effectInstance, double progress); + + /** @brief Signal that we are finished with the progress meter. + + Call this when you are done with the progress meter and no + longer need it displayed. + + \arg \c effectInstance the instance of the plugin this progress bar is + associated with. It cannot be NULL. + + \post - you can no longer call progressUpdate on the instance + + \returns + - ::kOfxStatOK - the progress object was successfully closed + - ::kOfxStatErrBadHandle - the progress handle was invalid, + */ + OfxStatus (*progressEnd)(void *effectInstance); + +} OfxProgressSuiteV1 ; + + + +typedef struct OfxProgressSuiteV2 { + + /** @brief Initiate a progress bar display. + + Call this to initiate the display of a progress bar. + + \arg \c effectInstance the instance of the plugin this progress bar is + associated with. It cannot be NULL. + \arg \c message a text label to display in any message portion of the + progress object's user interface. A UTF8 string. + \arg \c messageId plugin-specified id to associate with this message. + If overriding the message in an XML resource, the message + is identified with this, this may be NULL, or "", in + which case no override will occur. + New in V2 of this suite. + + \pre - There is no currently ongoing progress display for this instance. + + \returns + - ::kOfxStatOK - the handle is now valid for use + - ::kOfxStatFailed - the progress object failed for some reason + - ::kOfxStatErrBadHandle - effectInstance was invalid + */ +OfxStatus (*progressStart)(void *effectInstance, + const char *message, + const char *messageid); + /** @brief Indicate how much of the processing task has been completed and reports on any abort status. + + \arg \c effectInstance the instance of the plugin this progress bar is + associated with. It cannot be NULL. + \arg \c progress a number between 0.0 and 1.0 indicating what proportion of the current task has been processed. + + \returns + - ::kOfxStatOK - the progress object was successfully updated and the task should continue + - ::kOfxStatReplyNo - the progress object was successfully updated and the task should abort + - ::kOfxStatErrBadHandle - the progress handle was invalid, + */ +OfxStatus (*progressUpdate)(void *effectInstance, double progress); + + /** @brief Signal that we are finished with the progress meter. + + Call this when you are done with the progress meter and no + longer need it displayed. + + \arg \c effectInstance the instance of the plugin this progress bar is + associated with. It cannot be NULL. + + \post - you can no longer call progressUpdate on the instance + + \returns + - ::kOfxStatOK - the progress object was successfully closed + - ::kOfxStatErrBadHandle - the progress handle was invalid, + */ +OfxStatus (*progressEnd)(void *effectInstance); + +} OfxProgressSuiteV2 ; + +#endif diff --git a/src/modules/openfx/ofxProperty.h b/src/modules/openfx/ofxProperty.h new file mode 100644 index 000000000..086adb54b --- /dev/null +++ b/src/modules/openfx/ofxProperty.h @@ -0,0 +1,319 @@ +#ifndef _ofxPropertyHost_h_ +#define _ofxPropertyHost_h_ + +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + + +#include "ofxCore.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** @file ofxProperty.h +Contains the API for manipulating generic properties. For more details see \ref PropertiesPage. +*/ + +#define kOfxPropertySuite "OfxPropertySuite" + +/** @brief The OFX suite used to access properties on OFX objects. + +*/ +typedef struct OfxPropertySuiteV1 { + /** @brief Set a single value in a pointer property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c index for multidimenstional properties and is dimension of the one we are setting + \arg \c value value of the property we are setting + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + - ::kOfxStatErrValue + */ + OfxStatus (*propSetPointer)(OfxPropertySetHandle properties, const char *property, int index, void *value); + + /** @brief Set a single value in a string property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c index for multidimenstional properties and is dimension of the one we are setting + \arg \c value value of the property we are setting + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + - ::kOfxStatErrValue + */ + OfxStatus (*propSetString) (OfxPropertySetHandle properties, const char *property, int index, const char *value); + + /** @brief Set a single value in a double property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c index for multidimenstional properties and is dimension of the one we are setting + \arg \c value value of the property we are setting + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + - ::kOfxStatErrValue + */ + OfxStatus (*propSetDouble) (OfxPropertySetHandle properties, const char *property, int index, double value); + + /** @brief Set a single value in an int property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c index for multidimenstional properties and is dimension of the one we are setting + \arg \c value value of the property we are setting + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + - ::kOfxStatErrValue +*/ + OfxStatus (*propSetInt) (OfxPropertySetHandle properties, const char *property, int index, int value); + + /** @brief Set multiple values of the pointer property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c count number of values we are setting in that property (ie: indicies 0..count-1) + \arg \c value pointer to an array of property values + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + - ::kOfxStatErrValue + */ + OfxStatus (*propSetPointerN)(OfxPropertySetHandle properties, const char *property, int count, void *const*value); + + /** @brief Set multiple values of a string property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c count number of values we are setting in that property (ie: indicies 0..count-1) + \arg \c value pointer to an array of property values + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + - ::kOfxStatErrValue + */ + OfxStatus (*propSetStringN) (OfxPropertySetHandle properties, const char *property, int count, const char *const*value); + + /** @brief Set multiple values of a double property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c count number of values we are setting in that property (ie: indicies 0..count-1) + \arg \c value pointer to an array of property values + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + - ::kOfxStatErrValue + + */ + OfxStatus (*propSetDoubleN) (OfxPropertySetHandle properties, const char *property, int count, const double *value); + + /** @brief Set multiple values of an int property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c count number of values we are setting in that property (ie: indicies 0..count-1) + \arg \c value pointer to an array of property values + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + - ::kOfxStatErrValue + + */ + OfxStatus (*propSetIntN) (OfxPropertySetHandle properties, const char *property, int count, const int *value); + + /** @brief Get a single value from a pointer property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c index refers to the index of a multi-dimensional property + \arg \c value pointer the return location + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + */ + OfxStatus (*propGetPointer)(OfxPropertySetHandle properties, const char *property, int index, void **value); + + /** @brief Get a single value of a string property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c index refers to the index of a multi-dimensional property + \arg \c value pointer the return location + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + */ + OfxStatus (*propGetString) (OfxPropertySetHandle properties, const char *property, int index, char **value); + + /** @brief Get a single value of a double property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c index refers to the index of a multi-dimensional property + \arg \c value pointer the return location + + See the note \ref ArchitectureStrings for how to deal with strings. + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + */ + OfxStatus (*propGetDouble) (OfxPropertySetHandle properties, const char *property, int index, double *value); + + /** @brief Get a single value of an int property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c index refers to the index of a multi-dimensional property + \arg \c value pointer the return location + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + */ + OfxStatus (*propGetInt) (OfxPropertySetHandle properties, const char *property, int index, int *value); + + /** @brief Get multiple values of a pointer property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c count number of values we are getting of that property (ie: indicies 0..count-1) + \arg \c value pointer to an array of where we will return the property values + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + */ + OfxStatus (*propGetPointerN)(OfxPropertySetHandle properties, const char *property, int count, void **value); + + /** @brief Get multiple values of a string property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c count number of values we are getting of that property (ie: indicies 0..count-1) + \arg \c value pointer to an array of where we will return the property values + + See the note \ref ArchitectureStrings for how to deal with strings. + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + */ + OfxStatus (*propGetStringN) (OfxPropertySetHandle properties, const char *property, int count, char **value); + + /** @brief Get multiple values of a double property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c count number of values we are getting of that property (ie: indicies 0..count-1) + \arg \c value pointer to an array of where we will return the property values + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + */ + OfxStatus (*propGetDoubleN) (OfxPropertySetHandle properties, const char *property, int count, double *value); + + /** @brief Get multiple values of an int property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property + \arg \c count number of values we are getting of that property (ie: indicies 0..count-1) + \arg \c value pointer to an array of where we will return the property values + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + - ::kOfxStatErrBadIndex + */ + OfxStatus (*propGetIntN) (OfxPropertySetHandle properties, const char *property, int count, int *value); + + /** @brief Resets all dimensions of a property to its default value + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property we are resetting + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + */ + OfxStatus (*propReset) (OfxPropertySetHandle properties, const char *property); + + /** @brief Gets the dimension of the property + + \arg \c properties handle of the thing holding the property + \arg \c property string labelling the property we are resetting + \arg \c count pointer to an integer where the value is returned + + @returns + - ::kOfxStatOK + - ::kOfxStatErrBadHandle + - ::kOfxStatErrUnknown + */ + OfxStatus (*propGetDimension) (OfxPropertySetHandle properties, const char *property, int *count); +} OfxPropertySuiteV1; + +/** + \addtogroup ErrorCodes +*/ +/*@{*/ + + +/*@}*/ + + + +#ifdef __cplusplus +} +#endif + + +#endif diff --git a/src/modules/openfx/ofxTimeLine.h b/src/modules/openfx/ofxTimeLine.h new file mode 100644 index 000000000..654eae6e2 --- /dev/null +++ b/src/modules/openfx/ofxTimeLine.h @@ -0,0 +1,65 @@ +// Copyright OpenFX and contributors to the OpenFX project. +// SPDX-License-Identifier: BSD-3-Clause + +#ifndef _ofxTimeLine_h_ +#define _ofxTimeLine_h_ + +/** @brief Name of the time line suite */ +#define kOfxTimeLineSuite "OfxTimeLineSuite" + +/** @brief Suite to control timelines + + This suite is used to enquire and control a timeline associated with a plug-in + instance. + + This is an optional suite in the Image Effect API. +*/ +typedef struct OfxTimeLineSuiteV1 { + /** @brief Get the time value of the timeline that is controlling to the indicated effect. + + \arg \c instance is the instance of the effect changing the timeline, cast to a void * + \arg \c time pointer through which the timeline value should be returned + + This function returns the current time value of the timeline associated with the effect instance. + + @returns + - ::kOfxStatOK - the time enquiry was sucessful + - ::kOfxStatFailed - the enquiry failed for some host specific reason + - ::kOfxStatErrBadHandle - the effect handle was invalid + */ + OfxStatus (*getTime)(void *instance, double *time); + + /** @brief Move the timeline control to the indicated time. + + \arg \c instance is the instance of the effect changing the timeline, cast to a void * + \arg \c time is the time to change the timeline to. This is in the temporal coordinate system of the effect. + + This function moves the timeline to the indicated frame and returns. Any side effects of the timeline + change are also triggered and completed before this returns (for example instance changed actions and renders + if the output of the effect is being viewed). + + @returns + - ::kOfxStatOK - the time was changed sucessfully, will all side effects if the change completed + - ::kOfxStatFailed - the change failed for some host specific reason + - ::kOfxStatErrBadHandle - the effect handle was invalid + - ::kOfxStatErrValue - the time was an illegal value + */ + OfxStatus (*gotoTime)(void *instance, double time); + + /** @brief Get the current bounds on a timeline + + \arg \c instance is the instance of the effect changing the timeline, cast to a void * + \arg \c firstTime is the first time on the timeline. This is in the temporal coordinate system of the effect. + \arg \c lastTime is last time on the timeline. This is in the temporal coordinate system of the effect. + + This function + + @returns + - ::kOfxStatOK - the time enquiry was sucessful + - ::kOfxStatFailed - the enquiry failed for some host specific reason + - ::kOfxStatErrBadHandle - the effect handle was invalid + */ + OfxStatus (*getTimeBounds)(void *instance, double *firstTime, double *lastTime); +} OfxTimeLineSuiteV1; + +#endif