OpenFX Documentation Release 1.4

ofxa

Apr 29, 2020

CONTENTS

1 OpenFX reference 3

2 OpenFX Programming Guide 173

Index 179

i ii OpenFX Documentation, Release 1.4

The OpenFX documentation is organized as follows: • The programming guide contains everything to get started with OpenFX to create a new plug-in or host appli- cation • The reference guide contains the full documentation about the OpenFX protocol and design This documentation is also available online and can be downloaded as a PDF or HTML zip file. This manual is maintained largely by volunteers. The Creative Commons Attribution-ShareAlike 4.0 International License (CC-BY-SA 4.0) is used for this manual, which is a free and open license. Though there are certain restrictions that come with this license you may in general freely reproduce it and even make changes to it. However, rather than distribute your own version of this manual, we would much prefer if you would send any corrections or changes to the OpenFX association.

CONTENTS 1 OpenFX Documentation, Release 1.4

2 CONTENTS CHAPTER ONE

OPENFX REFERENCE

This is a mostly complete reference guide to the OFX image effect plugin architecture. It is a backwards compatible update to the 1.2 version of the API. The changes to the API are listed in an addendum.

1.1 Structure of The OFX and the Image Effect API

1.1.1 The Structure Of The Generic OFX API

OFX is actually several things. At its base it is a generic plug-in architecture which can be used to implement a variety of plug-in APIs. The first such API to be implemented on the core architecture is the OFX Image Effect Plug-in API. It is all specified using the ‘’ programming language. C and C++ are the languages mainly used to write visual effects applications (the initial target for OFX plug-in APIs) and have a very wide adoption across most operating systems with many available compilers. By making the API C, rather than C++, you remove the whole set of problems around C++ symbol mangling between the host and plug-in. APIs are defined in OFX by only a set of C header files and associated documentation. There are no binary libraries for a plug-in or host to link against. Hosts rely on two symbols within a plug-in, all other communication is boot strapped from those two symbols. The plug-in has no symbolic dependancies from the host. This minimal symbolic dependancy allows for run-time de- termination of what features to provide over the API, making implementation much more flexible and less prone to backwards compatibility problems. Plug-ins, via the two exposed symbols, indicate the API they implement, the version of the API, their name, their version and their main entry point. A host communicates with a plug-in via sending ‘actions’ to the plug-in’s main entry function. Actions are C strings that indicate the specific operation to be carried out. They are associated with sets of properties, which allows the main entry function to behave as a generic function. A plug-in communicates with a host by using sets of function pointers given it by the host. These sets of function pointers, known as ‘suites’, are named via a C string and a version number. They are returned on request from the host as pointers within a C struct. Properties are typed value/name pairs that exist on the various OFX objects and are action argument values to the plug-in’s main entry point. They are how a plug-in and host pass individual values back and forth to each other. The property suite, defined inside ofxProperty.h is used to do this.

3 OpenFX Documentation, Release 1.4

1.1.2 OFX APIs

An OFX plug-in API is a named set of actions, properties and suites to perform some specific set of tasks. The first such API that has been defined on the OFX core is the OFX Image Effect API. The set of actions, properties and suites that constitute the API makes up the major part of this document. Variou