Standard version: 1.5

Major Change

Subcommittee

Robert Laycock (Hitfilm),  Paul Garmon (Borisfx)

Overview

Some hosts support 3d compositing with cameras and lights. AE even has this. The OFX API could allow plug-ins to use the host's camera and lighting information, where available, to create interesting effects.

Nuke has a private suite for Camera already.

Solution

None at this time, though other proprietary plug-in APIs have implemented it.

 

/*

Copyright (c) 2016, FXHOME Limited (UK)

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*/

#ifndef _ofxHitFilmExtensions_h_
#define _ofxHitFilmExtensions_h_

#include "ofxCore.h"
#include "ofxImageEffect.h"

#ifdef __cplusplus
extern "C" {
#endif

/** @brief Search keywords for the effect descriptor

- Type - UTF8 C string
- Property Set - effect descriptor (read/write)
*/
#define kOfxHitFilmPropKeywords "OfxHitFilmPropKeywords"

 

/** @brief the string that names the HitFilm 3D Suite, passed to OfxHost::fetchSuite */
#define kOfxHitFilm3DSuite "OfxHitFilm3DSuite"

/** @brief Blind declaration of an OFX Camera
*/
typedef struct OfxHitFilmCameraStruct *OfxHitFilmCameraHandle;

/** @brief Blind declaration of OFX Lights
*/
typedef struct OfxHitFilmLightsStruct *OfxHitFilmLightsHandle;

/** @brief Used as a value for ::kOfxPropType on image effect camera handle */
#define kOfxTypeHitFilmCamera "OfxTypeHitFilmCamera"
/** @brief Used as a value for ::kOfxPropType on image effect lights handle */
#define kOfxTypeHitFilmLights "OfxTypeHitFilmLights"
/** @brief Used as a value for ::kOfxPropType on image effect camera transform */
#define kOfxTypeHitFilmCameraTransform "OfxTypeHitFilmCameraTransform"
/** @brief Used as a value for ::kOfxPropType on image effect light transform */
#define kOfxTypeHitFilmLightTransform "OfxTypeHitFilmLightTransform"
/** @brief Used as a value for ::kOfxPropType on image effect clip transform */
#define kOfxTypeHitFilmClipTransform "OfxTypeHitFilmClipTransform"

 

/** @brief The 3D matrix used by the application to transform the selected object

- Type - double X 16
- Property Set - HitFilm Clip Transform (read only),
HitFilm Camera Transform (read only),
HitFilm Light Transform (read only)

This property contains a 4x4 matrix, stored in row major order
It uses a left handed coordinate system, with y pointing up
*/
#define kOfxHitFilmProp3DTransformMatrix "OfxHitFilmProp3DTransformMatrix"

 

/** @brief String that is the name of the standard default camera */
#define kOfxHitFilmDefaultCamera "OfxHitFilmDefaultCamera"

/** @brief Indicates if a clip is optional.

- Type - int X 1
- Property Set - HitFilm Camera Descriptor (read/write)
- Default - 0
- Valid Values - This must be one of 0 or 1

*/
#define kOfxHitFilmCameraPropOptional "OfxHitFilmCameraPropOptional"

/** @brief Says whether the camera is actually connected at the moment.

- Type - int X 1
- Property Set - HitFilm Camera Instance (read only)
- Valid Values - This must be one of 0 or 1
*/
#define kOfxHitFilmCameraPropConnected "OfxHitFilmCameraPropConnected"

/** @brief The 3D matrix used to transform the scene when viewing through a camera

- Type - double X 16
- Property Set - HitFilm Camera Transform (read only)

This property contains a 4x4 matrix, stored in row major order
It uses a left handed coordinate system, with y pointing up.
*/
#define kOfxHitFilmCameraPropMatrix "OfxHitFilmCameraPropMatrix"

/** @brief The zoom of the camera

- Type - double X 1
- Property Set - HitFilm Camera Transform (read only)
*/
#define kOfxHitFilmCameraPropZoom "OfxHitFilmCameraPropZoom"

/** @brief The fov of the camera

- Type - double X 2
- Property Set - HitFilm Camera Transform (read only)
*/
#define kOfxHitFilmCameraPropFOV "OfxHitFilmCameraPropFOV"

/** @brief The focus distance of the camera

- Type - double X 1
- Property Set - HitFilm Camera Transform (read only)
*/
#define kOfxHitFilmCameraPropFocusDistance "OfxHitFilmCameraPropFocusDistance"

/** @brief The blur level of the camera

- Type - double X 1
- Property Set - HitFilm Camera Transform (read only)
*/
#define kOfxHitFilmCameraPropBlurLevel "OfxHitFilmCameraPropBlurLevel"

/** @brief The aperture of the camera

- Type - double X 1
- Property Set - HitFilm Camera Transform (read only)
*/
#define kOfxHitFilmCameraPropAperture "OfxHitFilmCameraPropAperture"

 

 

/** @brief String that is the name of the default lights input */
#define kOfxHitFilmDefaultLights "OfxHitFilmDefaultLights"

/** @brief The number of lights linked to the HitFilm Lights Instance

- Type - integer X 1
- Property Set - HitFilm Lights Instance (read only)
*/
#define kOfxHitFilmLightsPropNumberOfLights "OfxHitFilmLightsPropNumberOfLights"

/** @brief Says whether the light is currently enabled

- Type - int X 1
- Property Set - HitFilm Light Transform (read only)
- Valid Values - This is either 0 or 1
*/
#define kOfxHitFilmLightPropEnabled "OfxHitFilmLightPropEnabled"

/** @brief The type of light

- Type - string X 1
- Property Set - HitFilm Light Transform (read only)
- Valid Values - This must be one of
- ::kOfxHitFilmLightAmbient
- ::kOfxHitFilmLightPoint
- ::kOfxHitFilmLightSpot
- ::kOfxHitFilmLightDirectional
*/
#define kOfxHitFilmLightPropType "OfxHitFilmLightPropType"

/** @brief Used to find the light type as an ambient light. See \ref ::kOfxHitFilmLightPropType
*/
#define kOfxHitFilmLightAmbient "OfxHitFilmLightAmbient"

/** @brief Used to find the light type as a point light. See \ref ::kOfxHitFilmLightPropType
*/
#define kOfxHitFilmLightPoint "OfxHitFilmLightPoint"

/** @brief Used to find the light type as a spot light. See \ref ::kOfxHitFilmLightPropType
*/
#define kOfxHitFilmLightSpot "OfxHitFilmLightSpot"

/** @brief Used to find the light type as a directional light. See \ref ::kOfxHitFilmLightPropType
*/
#define kOfxHitFilmLightDirectional "OfxHitFilmLightDirectional"

/** @brief The intensity of the light

- Type - double X 1
- Property Set - HitFilm Light Transform (read only)
*/
#define kOfxHitFilmLightPropIntensity "OfxHitFilmLightPropIntensity"

/** @brief The Color of the light

- Type - double X 4
- Property Set - HitFilm Light Transform (read only)
*/
#define kOfxHitFilmLightPropColor "OfxHitFilmLightPropColor"

/** @brief The cone angle of the light

- Type - double X 1
- Property Set - HitFilm Light Transform (read only)
*/
#define kOfxHitFilmLightPropConeAngle "OfxHitFilmLightPropConeAngle"

/** @brief The cone feather of the light

- Type - double X 1
- Property Set - HitFilm Light Transform (read only)
*/
#define kOfxHitFilmLightPropConeFeather "OfxHitFilmLightPropConeFeather"

/** @brief If the light casts shadows

- Type - int X 1
- Property Set - HitFilm Light Transform (read only)
- Valid Values - This is either 0 or 1
*/
#define kOfxHitFilmLightPropCastsShadows "OfxHitFilmLightPropCastsShadows"

/** @brief The shadow color of the light, alpha controls the opacity of the shadow

- Type - double X 4
- Property Set - HitFilm Light Transform (read only)
*/
#define kOfxHitFilmLightPropShadowColor "OfxHitFilmLightPropShadowColor"

/** @brief The shadow diffusion of the light

- Type - double X 1
- Property Set - HitFilm Light Transform (read only)
*/
#define kOfxHitFilmLightPropShadowDiffusion "OfxHitFilmLightPropShadowDiffusion"

/** @brief The falloff type of the light

- Type - string X 1
- Property Set - HitFilm Light Transform (read only)
- Valid Values - This must be one of
- ::kOfxHitFilmLightFalloffNone
- ::kOfxHitFilmLightFalloffLinear
- ::kOfxHitFilmLightFalloffQuadratic
*/
#define kOfxHitFilmLightPropFalloffType "OfxHitFilmLightPropFalloffType"

/** @brief Use to define that the light has no falloff. See \ref ::kOfxHitFilmLightPropFalloffType
*/
#define kOfxHitFilmLightFalloffNone "OfxHitFilmLightFalloffNone"

/** @brief Use to define that the light has a linear falloff. See \ref ::kOfxHitFilmLightPropFalloffType
*/
#define kOfxHitFilmLightFalloffLinear "OfxHitFilmLightFalloffLinear"

/** @brief Use to define that the light has a quadratic falloff. See \ref ::kOfxHitFilmLightPropFalloffType
*/
#define kOfxHitFilmLightFalloffQuadratic "OfxHitFilmLightFalloffQuadratic"

/** @brief The falloff start of the light

- Type - double X 1
- Property Set - HitFilm Light Transform (read only)
*/
#define kOfxHitFilmLightPropFalloffStart "OfxHitFilmLightPropFalloffStart"

/** @brief The falloff distance of the light

- Type - double X 1
- Property Set - HitFilm Light Transform (read only)
*/
#define kOfxHitFilmLightPropFalloffDistance "OfxHitFilmLightPropFalloffDistance"

 

/** @brief Indicates if an image clip is 3D

- Type - int X 1
- Property Set - HitFilm Clip Transform (read only)

- 0 if the clip is 2D
- 1 if the clip is 3D
*/
#define kOfxHitFilmImageClipPropIs3D "OfxHitFilmImageClipPropIs3D"

 

/** @brief OFX suite that provides access to cameras and lights
*/
typedef struct OfxHitFilm3DSuiteV1 {

/** @brief Defines a camera input for the effect

\arg imageEffect image effect
\arg name unique name of the camera input
\arg propertySet if not null, a pointer to the camera descriptor's property set will be placed here.

To use the default HitFilm camera use the name kOfxHitFilmDefaultCamera.
If another name is used, a layer picker will be added, which can be used to select a camera layer.

The camera descriptor contains the following properties:
- kOfxPropType (read only): set to kOfxTypeHitFilmCamera
- kOfxPropName (read only)
- kOfxPropLabel (read/write)
- kOfxPropShortLabel (read/write)
- kOfxPropLongLabel (read/write)
- kOfxHitFilmCameraPropOptional (read/write)

This function defines a camera input and returns a property set which is used to describe that camera.

This function does not actually create a camera input instance,
it only says that one should exist in any subsequent effect instances.
To fetch a camera input instance, cameraGetHandle must be called on an effect instance.

This function can always be called in one of a plug-in's "describe" functions.

@returns
- ::kOfxStatOK - the camera input was created correctly
- ::kOfxStatErrBadHandle - if the plugin handle was invalid
- ::kOfxStatErrExists - if a camera of that name exists already in this plugin
- ::kOfxStatErrUnknown - if the type is unknown
- ::kOfxStatErrUnsupported - if the type is known but unsupported
*/
OfxStatus(*cameraDefine)(
OfxImageEffectHandle imageEffect,
const char *name,
OfxPropertySetHandle *propertySet);

/** @brief Retrieves the handle for a camera input

\arg imageEffect image effect
\arg name camera input to ask about
\arg camera pointer to a camera handle, the value is returned here
\arg propertySet if not null, a pointer to the camera's property set will be placed here.

The camera instance contains the following properties:
- kOfxPropType (read only): set to kOfxTypeHitFilmCamera
- kOfxPropName (read only)
- kOfxPropLabel (read only)
- kOfxPropShortLabel (read only)
- kOfxPropLongLabel (read only)
- kOfxHitFilmCameraPropOptional (read only)
- kOfxHitFilmCameraPropConnected (read only)

 

Camera handles retrieved from an instance are always distinct in each instance.
The camera handle is valid for the life-time of the instance.
You cannot call this in a plugin's describe function, as it needs an instance to work on.

@returns
- ::kOfxStatOK - the camera input was found and returned
- ::kOfxStatErrBadHandle - if the plugin handle was invalid
- ::kOfxStatErrUnknown - if the type is unknown
*/
OfxStatus(*cameraGetHandle)(
OfxImageEffectHandle imageEffect,
const char *name,
OfxHitFilmCameraHandle *camera,
OfxPropertySetHandle *propertySet);

/** @brief Retrieves the property set handle for the given camera

\arg camera the camera handle to get the property set for
\arg propHandle pointer to a the property set handle, value is returned here

@returns
- ::kOfxStatOK - the property set was found and returned
- ::kOfxStatErrBadHandle - if the camera handle was invalid
- ::kOfxStatErrUnknown - if the type is unknown
*/
OfxStatus(*cameraGetPropertySet)(
OfxHitFilmCameraHandle camera,
OfxPropertySetHandle *propertySet);

/** @brief Retrieves camera transform information for the requested time

\arg camera the camera handle to get the transform for
\arg time the time at which the camera transform values should be sampled
\arg cameraTransform pointer to a property set handle, value is returned here

The camera transform contains the following properties:
- kOfxPropType (read only): set to kOfxTypeHitFilmCameraTransform
- kOfxPropTime (read only)
- kOfxHitFilmProp3DTransformMatrix (read only)
- kOfxHitFilmCameraPropMatrix (read only)
- kOfxHitFilmCameraPropZoom (read only)
- kOfxHitFilmCameraPropFOV (read only)
- kOfxHitFilmCameraPropFocusDistance (read only)
- kOfxHitFilmCameraPropBlurLevel (read only)
- kOfxHitFilmCameraPropAperture (read only)

The transform handle is valid for the current action.

@returns
- ::kOfxStatOK - the property set was found and returned
- ::kOfxStatErrBadHandle - if the camera handle was invalid
- ::kOfxStatErrUnknown - if the type is unknown
*/
OfxStatus(*cameraGetTransform)(
OfxHitFilmCameraHandle camera,
OfxTime time,
OfxPropertySetHandle *cameraTransform);

 

/** @brief Defines lights input for the effect

\arg imageEffect image effect to get the property set for
\arg name unique name of the lights input (in HitFilm must be set to kOfxHitFilmDefaultLights)
\arg propertySet if not null, a pointer to the lights input descriptor's property set will be placed here.

To use the default HitFilm lights use the name kOfxHitFilmDefaultLights.
Using this name, all lights inside the same Composite Shot will be connected to this input.
(Other light names are currently not implement inside HitFilm)

The lights descriptor contains the following properties:
- kOfxPropType (read only): set to kOfxTypeHitFilmLights
- kOfxPropName (read only)
- kOfxPropLabel (read/write)
- kOfxPropShortLabel (read/write)
- kOfxPropLongLabel (read/write)

 

This function defines a lights input and returns a property set which is used to describe that lights input.

This function does not actually create a lights input instance,
it only says that one should exist in any subsequent effect instances.
To fetch a lights input instance, lightsGetHandle must be called on an effect instance.

This function can always be called in one of a plug-in's "describe" functions.

@returns
- ::kOfxStatOK - the lights input was created correctly
- ::kOfxStatErrBadHandle - if the plugin handle was invalid
- ::kOfxStatErrExists - if a lights input of that name exists already in this plugin
- ::kOfxStatErrUnknown - if the type is unknown
- ::kOfxStatErrUnsupported - if the type is known but unsupported
*/
OfxStatus(*lightsDefine)(
OfxImageEffectHandle imageEffect,
const char *name,
OfxPropertySetHandle *propertySet);

/** @brief Retrieves the handle for a lights input

\arg imageEffect image effect to get the property set for
\arg name lights input to ask about
\arg lightsHandle pointer to a lights handle, the value is returned here
\arg propertySet if not null, a pointer to the lights input instance property set will be placed here.

The lights instance contains the following properties:
- kOfxPropType (read only): set to kOfxTypeHitFilmLights
- kOfxPropName (read only)
- kOfxPropLabel (read only)
- kOfxPropShortLabel (read only)
- kOfxPropLongLabel (read only)
- kOfxHitFilmLightsPropNumberOfLights (read only)

Lights instance handles retrieved from an effect instance are always distinct in each effect instance.
The lights instance handle is valid for the life-time of the effect instance.
You cannot call this in a plugin's describe function, as it needs an instance to work on.

@returns
- ::kOfxStatOK - the lights input was found and returned
- ::kOfxStatErrBadHandle - if the plugin handle was invalid
- ::kOfxStatErrUnknown - if the type is unknown
*/
OfxStatus(*lightsGetHandle)(
OfxImageEffectHandle imageEffect,
const char *name,
OfxHitFilmLightsHandle *lightsHandle,
OfxPropertySetHandle *propertySet);

/** @brief Retrieves the property set handle for the given lights input

\arg lightsHandle the lights input handle to get the property set for
\arg propHandle pointer to a the property set handle, value is returned here

@returns
- ::kOfxStatOK - the property set was found and returned
- ::kOfxStatErrBadHandle - if the lights input handle was invalid
- ::kOfxStatErrUnknown - if the type is unknown
*/
OfxStatus(*lightsGetPropertySet)(
OfxHitFilmLightsHandle lightsHandle,
OfxPropertySetHandle *propertySet);

/** @brief Retrieves light transform information for the requested time

\arg lightsHandle the lights input handle to get the transform for
\arg light_index the index of the light to be sampled, range: [0, kOfxHitFilmLightsPropNumberOfLights)
\arg time the time at which the light transform values should be sampled
\arg lightTransform pointer to a property set handle, value is returned here

The light transform contains the following properties:
- kOfxPropType (read only): set to kOfxTypeHitFilmLightTransform
- kOfxPropTime (read only)
- kOfxHitFilmLightPropEnabled (read only)
- kOfxHitFilmLightPropType (read only)
- kOfxHitFilmLightPropIntensity (read only)
- kOfxHitFilmLightPropColor (read only)
- kOfxHitFilmProp3DTransformMatrix (read only)
- kOfxHitFilmLightPropConeAngle (read only)
- kOfxHitFilmLightPropConeFeather (read only)
- kOfxHitFilmLightPropCastsShadows (read only)
- kOfxHitFilmLightPropShadowColor (read only)
- kOfxHitFilmLightPropShadowDiffusion (read only)
- kOfxHitFilmLightPropFalloffType (read only)
- kOfxHitFilmLightPropFalloffStart (read only)
- kOfxHitFilmLightPropFalloffDistance (read only)

The transform handle is valid for the current action.

@returns
- ::kOfxStatOK - the property set was found and returned
- ::kOfxStatErrBadHandle - if the lights handle was invalid
- ::kOfxStatErrBadIndex - if the light index was invalid
- ::kOfxStatErrUnknown - if the type is unknown
*/
OfxStatus(*lightGetTransform)(
OfxHitFilmLightsHandle lightsHandle,
int light_index,
double time,
OfxPropertySetHandle *lightTransform);

 

/** @brief Retrieves clip transform information for the requested time

\arg clip the clip handle to get the transform for
\arg time the time at which the clip transform values should be sampled
\arg cameraTransform pointer to a property set handle, value is returned here

The clip transform contains the following properties:
- kOfxPropType (read only): set to kOfxTypeHitFilmCameraTransform
- kOfxPropTime (read only)
- kOfxHitFilmProp3DTransformMatrix (read only)
- kOfxHitFilmImageClipPropIs3D (read only)

The transform handle is valid for the current action.

@returns
- ::kOfxStatOK - the property set was found and returned
- ::kOfxStatErrBadHandle - if the clip handle was invalid
- ::kOfxStatErrUnknown - if the type is unknown
*/
OfxStatus(*clipGetTransform)(
OfxImageClipHandle clip, OfxTime time,
OfxPropertySetHandle *clipTransform);

} OfxHitFilm3DSuiteV1;

#ifdef __cplusplus
}
#endif

#endif // _ofxHitFilmExtensions_h_