FxPlug Data Types Reference

Framework
/Library/Frameworks/FxPlug.framework

Overview

This document describes the data types defined in the FxPlug SDK that are not class specific.

Data Types

FxPoint2D

A 2D point representation.

typedef CGPoint FxPoint2D;

FxPoint3D

A 3D point representation

typedef struct FxPoint3D {
      CGFloat x;
      CGFloat y;
      CGFloat z;
} FxPoint3D;
Constants
x

The X coordinate of the 3D point.

y

The Y coordinate of the 3D point.

z

The Z coordinate of the 3D point.

FxRect

A 2D axis-aligned rectangle with integer coordinates.

typedef struct FxRect {
      SInt32 left;
      SInt32 bottom;
      SInt32 right;
      SInt32 top;
} FxRect;
Constants
left

The left edge component of the rectangle.

bottom

The bottom edge component of the rectangle.

right

The right edge component of the rectangle.

top

The top edge component of the rectangle.

FxSize

A structure to store width and height values.

typedef CGSize FxSize;

FxDepth

Constants used to identify bit depth.

enum {
   kFxDepth_UINT8   = 0,
   kFxDepth_FLOAT16 = 2,
   kFxDepth_FLOAT32 = 3
};
typedef NSUInteger FxDepth;
Constants
kFxDepth_UINT8

Each component is an 8-bit integer.

kFxDepth_FLOAT16

Each component is a 16-bit float.

kFxDepth_FLOAT32

Each component is a 32-bit float.

FxError

Some common errors which can be returned by plug-in hosts applications.

enum {
   kFxError_Success   = 0,
   kFxError_InvalidParameterID,
   kFxError_InvalidParameterChannelIndex,
   kFxError_InvalidKeyframeIndex,
   kFxError_InvalidTime,
   kFxError_InvalidParameter,
   kFxError_OutOfMemory,
   kFxError_MemoryNotAllocated,
   kFxError_OpenGLError,
   kFxError_InvalidPathID,
   kFxError_InvalidPathIndex,
   kFxError_InvalidSegmentIndex,
   kFxError_ThirdPartyDeveloperStart  = 100000
};
typedef NSUInteger  FxError;
Constants
kFxError_Success

No error occurred. The call succeeded.

kFxError_InvalidParameterID

An invalid parameter ID was used.

kFxError_InvalidParameterChannelIndex

An invalid channel number for a parameter was used.

kFxError_InvalidKeyframeIndex

An invalid keyframe index was used.

kFxError_InvalidTime

An invalid time was used.

kFxError_InvalidParameter

A parameter sent to an API method was invalid. For example, a nil pointer, the object doesn't implement a protocol, etc.

kFxError_OutOfMemory

Unable to allocate memory.

kFxError_MemoryNotAllocated

Trying to free memory not allocated.

kFxError_OpenGLError

OpenGL returned an error.

kFxError_InvalidPathID

No path with that ID exists.

kFxError_InvalidPathIndex

The index is greater than the number of paths.

kFxError_InvalidSegmentIndex

The index of the segment of the path is greater than the number of segments in the path.

kFxError_ThirdPartyDeveloperStart

All 3rd party error values should be greater than or equal to this value.

FxField

Constants used to identify a field. Prior to FxPlug SDK 1.2, this type was used to identify field order. As of FxPlug SDK 1.2, it is used to identify the field of an image.

enum {
   kFxField_NONE = 0,
   kFxField_UPPER = 1,
   kFxField_LOWER = 2
};
typedef NSUInteger FxFieldOrder;
Constants
kFxField_NONE

Full frame, progressive (no fields).

kFxField_UPPER

Upper field.

kFxField_LOWER

Lower field.

FxFieldOrder

Constants used to identify the field order of an image stream.

enum {
   kFxFieldOrder_PROGRESSIVE = 0,
   kFxFieldOrder_UPPER_FIRST = 1,
   kFxFieldOrder_LOWER_FIRST = 2
};
typedef NSUInteger FxFieldOrder;
Constants
kFxFieldOrder_PROGRESSIVE

Full frame, progressive (no fields).

kFxFieldOrder_UPPER_FIRST

Upper field first.

kFxFieldOrder_LOWER_FIRST

Lower field first.

FxKeyframeStyle

Constants for specifying the type of keyframe

enum {
   kFxKeyframeStyle_Constant   = 0x0001,
   kFxKeyframeStyle_Linear     = 0x0002,
   kFxKeyframeStyle_Quadratic  = 0x0004,
   kFxKeyframeStyle_Cubic      = 0x0008,
   kFxKeyframeStyle_Bezier     = 0x0010,
   kFxKeyframeStyle_EaseIn     = 0x0080,
   kFxKeyframeStyle_EaseOut    = 0x0100,
   kFxKeyframeStyle_BSpline    = 0x0400,
   kFxKeyframeStyle_XSpline    = 0x1000,
   kFxKeyframeStyle_Exponential= 0x2000,
   kFxKeyframeStyle_Logarithmic= 0x4000,
   kFxKeyframeStyle_Mixed  = 0x80000000,
   kFxKeyframeStyle_All    = 0x7fff,
   kFxKeyframeStyle_None   = 0x0000
};
typedef NSUInteger FxKeyframeStyle;
Constants
kFxKeyframeStyle_Constant

Also known as "Hold," constant keyframes have a constant value between keyframes.

kFxKeyframeStyle_Linear

The values are interpolated along a straight line between keyframes.

kFxKeyframeStyle_Quadratic

The values are interpolated along a quadratic curve.

kFxKeyframeStyle_Cubic

The values are interpolated along a cubic curve.

kFxKeyframeStyle_Bezier

The values are interpolated along a cubic curve the user can control by varying the tangent handles.

kFxKeyframeStyle_EaseIn

The values are interpolated along a pre-calculated cubic curve that smoothly transitions into the next value.

kFxKeyframeStyle_EaseOut

The values are interpolated along a pre-calculated cubic curve that smoothly transitions out of the previous value.

kFxKeyframeStyle_BSpline

The values are interpolated along a B-Spline.

kFxKeyframeStyle_XSpline

The values are interpolated along a weighted X-Spline.

kFxKeyframeStyle_Exponential

The values are interpolated along an exponential curve.

kFxKeyframeStyle_Logarithmic

The values are interpolated along a logarithmic curve.

kFxKeyframeStyle_Mixed

The keyframe is a mixture of two of the above types.

kFxKeyframeStyle_All

A mask for all types.

kFxKeyframeStyle_None

A mask for no types.

FxTimeBase

Defines whether time bases are relative or absolute.

enum {
   kFxTimeBase_TIMELINE = 0,
   kFxTimeBase_CLIP = 1
};
typedef NSUInteger FxTimeBase;
Constants
kFxTimeBase_TIMELINE

Times are absolute frame numbers, where 0 is the start of the timeline.

kFxTimeBase_CLIP

Times are "clip-relative," meaning that 0 is the start of the clip. For generators and transitions, the clip is the effect itself. For filters, the clip is the video item to which the filter is applied.

FxPathID

A unique identifier for a path

typedef void* FxPathID;

FxRenderInfo

Type definition used to specify a render request.

typedef struct {
      double frame;
      FxQuality qualityLevel;
      FxFieldOrder fieldOrder;
      double scaleX;
      double scaleY;
      CGLContextObj sharedContext;
      FxDepth depth;
} FxRenderInfo;
Constants
frame

The requested time to be rendered, expressed in a frame number on the project or sequence's timeline. Note that this is a floating-point frame number. In interlaced video, the time for the first field would be an integer i; for the second field, a non integer (i + 0.5).

qualityLevel

The requested render quality: kFxQuality_LOW, kFxQuality_MEDIUM, or kFxQuality_HIGH.

fieldOrder

The field-order of the frame to be rendered. The value will be kFxFieldOrder_PROGRESSIVE for rendering previews, and for progressive footage., When a plug-in needs to render interlaced footage, it will be a constant value for all fields your plug-in is asked to render. For example, if a plug-in is applied to NTSC DV footage, generally this type of footage has a field order of kFxFieldOrder_LOWER_FIRST. When asked to render fields, the fieldOrder value will always be kFxFieldOrder_LOWER_FIRST. When rendering thumbnails for the layer list in Motion the value will be kFxFieldOrder_PROGRESSIVE). In order to determine which field a plug-in is actually being asked to render, check the output image's field method. This will alternate between kFxField_UPPER and kFxField_LOWER for interlaced footage when rendering fields. Before FxPlug 1.2, this was an FxField, not an FxFieldOrder. The two are binary compatible, but plug-ins should use the FxFieldOrder type.

scaleX

The requested horizontal scale value. When the value is less than 1, then the calculation coordinates need to account for the scale before sampling from the input image.

scaleY

The requested vertical scale value. When the value is less than 1, then the calculation coordinates need to account for the scale before sampling from the input image.

sharedContext

The OpenGL shared context. This may be NULL when doing a software render.

depth

The pixel depth of the buffer: kFxDepth_UINT8, kFxDepth_FLOAT16, or kFxDepth_FLOAT32.

Discussion

The pixel aspect ratio is not taken into account when the scaleX and scaleY values are computed. Plug-ins should look at the input and output FxImageInfo structure to determine pixel aspect ratios.

The sharedContext allows the plug-in to create its own OpenGL context that shares the textures supplied by the application the plug-in. You do not normally need to use this context unless you have to create a new context of and wish for it to share the input and output textures. You would never use this context directly for drawing, either. The application sets the current context to draw into the output texture before calling the plug-in.

FxQuality

Constants used to identify rendering quality.

enum {
   kFxQuality_LOW    = 0,
   kFxQuality_MEDIUM = 1,
   kFxQuality_HIGH   = 2
};
typedef NSUInteger FxQuality;
Constants
kFxQuality_LOW

Lowest quality, fastest render.

kFxQuality_MEDIUM

Medium quality, slowest render.

kFxQuality_HIGH

High quality, slowest render.