Video Effects API

Introduction

This chapter describes the constants, data types, and functions defined in QuickTime that support video effects.

Constants

This section describes the constants defined in QuickTime to support video effects.

Effects List Atom Names

These constants specify the four character codes for the two atom types in the atom container returned by calls to QTGetEffectsList.

enum {
    kEffectNameAtom = FOUR_CHAR_CODE('name'),
    kEffectTypeAtom = FOUR_CHAR_CODE('type')
}

Term

Definition

kEffectNameAtom

The code for the atom containing the name of an entry in the effects list.

kEffectTypeAtom

The code for the atom containing the type of an entry in the effects list.

Effect Action Selectors

These constants specify the action selectors you can pass to the functions QTStandardParameterDialogDoAction and ImageCodecStandardParameterDialogDoAction.

enum {
    pdActionConfirmDialog,
    pdActionSetAppleMenu,
    pdActionSetEditMenu,
    pdActionGetDialogValues,
    pdActionSetPreviewUserItem,
    pdActionSetPreviewPicture,
    pdActionSetColorPickerEventProc,
    pdActionSetDialogTitle
    pdActionGetSubPanelMenu,
    pdActionActivateSubPanel,
    pdActionConductStopAlert
}

Term

Definition

pdActionConfirmDialog

Retrieves the current parameter values from the standard parameters dialog box. The parameter values are placed in the parameters parameter that was passed to the function that created the dialog box.

pdActionSetAppleMenu

Passes the menu handle for the current Apple menu to the standard parameters dialog box.

pdActionSetEditMenu

Passes the menu handle for your application's Edit menu to the standard parameters dialog box.

pdActionGetDialogValues

Retrieves the current parameter values from the standard parameters dialog box. This parameter values are placed in the params parameter of the QTStandardParameterDialogDoAction or ImageCodecStandardParameterDialogDoAction function.

pdActionSetPreviewUserItem

Passes the number of the user item resource that should be replaced by the effect preview movie clip.

pdActionSetPreviewPicture

Sets the images that are used in the preview window of the standard parameters dialog box.

pdActionSetColorPickerEventProc

Sets the function that will be used when the standard parameters dialog box needs to display a color picker control.

pdActionSetDialogTitle

Sets the title of the standard parameters dialog box.

pdActionGetSubPanelMenu

Returns a menuHandle containing the pop-up menu used to switch between multiple parameter panels. You can parse this data structure to derive a list of the panels that are being used by the standard parameters dialog box.

pdActionActivateSubPanel

Sets the currently active panel of the standard parameter dialog box.

pdActionConductStopAlert

Displays a Stop Alert containing a message.

Get Options for QTGetEffectsList

These constants define the flags that can be passed in the getOptions parameter of the QTGetEffectsList function.

enum {
    elOptionsIncludeNoneInList
}

Term

Definition

elOptionsIncludeNoneInList

Includes the "none" effect in the list of effects returned by QTGetEffectsList.

Standard Parameter Dialog Box Options

These constants are used to control how parameter values are entered into a standard parameters dialog box that is generated when you call the function ImageCodecCreateStandardParameterDialog.

enum {
    pdOptionsCollectOneValue,
    pdOptionsAllowOptionalInterpolations
}

Parameters that are flagged as kAtomInterpolateIsOptional in their parameter description can contain single values or tweens. These constants are used to specify that the dialog box should allow entry of either a single value or a pair of values for such parameters.

Term

Definition

pdOptionsCollectOneValue

This value indicates that only one value should be entered for parameters that can optionally be tweened.

pdOptionsAllowOptionalInterpolations

This value indicates that optionally-tweened parameters should be displayed with a user interface that allows the entry of tweened values.

ImageCodecValidateParameters Options

These are the values that can be passed in the validationFlags parameter of a call to ImageCodecValidateParameters.

enum {
    kParameterValidationNoFlags,
    kParameterValidationFinalValidation
}

Term

Definition

kParameterValidationNoFlags

This value indicates that a standard validation should take place. ImageCodecValidateParameters is being called because the user has changed the value of a parameter in the standard parameters dialog box.

kParameterValidationFinalValidation

This value indicates that this validation is the final validation before the standard parameters dialog box is dismissed. This is useful if you want to perform a single validation of the parameters just after the user clicks the OK button to dismiss the dialog box.

Effect Speed Flag

This is the value that an effect should return when QTGetEffectSpeed is called and the component can run the effect in real time.

enum {
    effectIsRealtime
}

Term

Definition

effectIsRealtime

The effect can process frames in real time.

Data Types

This section describes the data types that are relevant to calling and creating effects.

The section describes the data types defined in QuickTime to support video effects.

Parameter Dialog Box Preview Image Specifier

This data structure contains a picture that will be used as one of the preview images in the preview window of the standard parameters dialog box. The preview window shows previews of the effects the user chooses in the dialog box. QuickTime provides a default images, but you can replace one or more of these by calling QTStandardParameterDialogDoAction (or its low-level equivalent, ImageCodecStandardParameterDialogDoAction ) with a pdActionSetPreviewPicture action selector.

The sourceID numbers correspond to the sources an effect uses. For example, an effect that uses one source will use the preview image with sourceID set to 1, while a two source effect will use preview pictures 1 and 2.

struct QTParamPreviewRecord {
    long        sourceID;
    PicHandle   sourcePicture;
};
typedef struct QTParamPreviewRecord QTParamPreviewRecord;
typedef QTParamPreviewRecord *QTParamPreviewPtr;

Term

Definition

sourceID

The number of the preview image.

sourcePicture

The preview image itself.

Effect Source Descriptors

These data structures describe the sources to an effect. The SourceData data structure contains a pointer to raw image compression manager image data, if the effect is being executed outside of a QuickTime movie, or to an effect that acts as the source, if the effect is being executed as part of an effect track in a QuickTime movie. The EffectSourcePtr data structure holds information about the type of source, as well as pointers to the track data of the effect and to the next source in the input chain.

typedef struct EffectSource     EffectSource;
typedef EffectSource            *EffectSourcePtr;
union SourceData {
    CDSequenceDataSourcePtr image;
    EffectSourcePtr     effect;
};
typedef union SourceData SourceData;

Term

Definition

image

A pointer to the raw source image data.

effect

A pointer to the effect.

 
struct EffectSource {
    long                effectType;
    Ptr                 data;
    SourceData          source;
    EffectSourcePtr     next;
};

Term

Definition

effectType

The type of the effect or the constant kEffectRawSource if the source is raw image compression manager data.

data

A pointer to the track data for the effect.

source

The source itself.

next

A pointer to the next source in the input chain.

Effect Frame Description

This data structure contains the parameters of a single frame of an effect. It is passed to the MyEffectBegin and MyEffectRenderFrame functions to describe the frame to be rendered.

struct EffectsFrameParams {
    ICMFrameTimeRecord  frameTime;
    long                effectDuration;
    Boolean             doAsync;
    unsigned char       pad[3];
    EffectSourcePtr     source;
    void *              refCon;
};
typedef struct EffectsFrameParams EffectsFrameParams;
typedef EffectsFrameParams *EffectsFrameParamsPtr;

Term

Definition

frameTime

Timing data for the current frame. This record includes information such as the total number of frames being rendered in this sequence, and the current frame number.

effectDuration

The duration of a single effect frame.

doAsync

This field contains true if the effect can process asynchronously.

source

A pointer to the input sources.

refCon

A pointer to storage for this instantiation of the effect.

The Decompression Parameters Structure

Several fields of the decompression parameters structure (CodecDecompressParams ) are relevant to effects, and in particular are used when you are writing your own effect component. This section describes only those fields of this data structure that apply to effects.

struct CodecDecompressParams {
    ...
    CodecCapabilities           *capabilities;
    ...
    ICMFrameTimePtr             frameTime;
    ...
    UInt16                      majorSourceChangeSeed;
    UInt16                      minorSourceChangeSeed;
    CDSequenceDataSourcePtr     sourceData;
    ...
    OSType                      **wantedDestinationPixelTypes;
    ...
    Boolean                     needUpdateOnTimeChange;
    ...
    Boolean                     needUpdateOnSourceChange;
    ...
    long                        requestedBufferWidth;
    long                        requestedBufferHeight;
};
typedef struct CodecDecompressParams CodecDecompressParams;

Term

Definition

capabilities

A pointer to a CodecCapabilities data structure containing the required capabilities of the effect.

frameTime

The current frame time. The information in this parameter can be used to calculate the current frame number, relative to the total duration of the effect.

majorSourceChangeSeed

An integer value that is incremented each time a data source is added or removed. This provides a fast way for an effect component to know when its data sources have changed.

minorSourceChangeSeed

An integer value that is incremented each time a data source is added or removed, or the data contained in any of the sources changes.This provides a fast way for an effect component to know when a source changes.

sourceData

A pointer to a CDSequenceDataSource structure that contains the head of a linked list of all data sources. Because each data source contains a link to the next data source, an effect component can access all data sources from this field.

wantedDestinationPixelTypes

A handle to a zero-terminated list of non-RGB pixel formats that the component can decompress. Set this value to nil if your component does not support non-RGB pixel spaces. If your effect component supports non-RGB pixel formats, your component's MyEffectSetup function should place the list of them into this field.The Image Compression Manager (ICM) copies this data structure, so it is up to your component to dispose of it later. It is suggested that components allocate this handle during the Open routine and dispose of it during the Close routine.

needUpdateOnTimeChange

Setting this field to true indicates to the ICM that your component's EffectBegin and EffectRenderFrame functions should be called whenever the time of the movie changes. The default value of this field is true.

needUpdateOnSourceChange

Setting this field to true indicates to the ICM that your component's EffectBegin and EffectRenderFrame functions should be called whenever one or more of the sources to the effect changes. The default value of this field is false.

requestedBufferWidth

Specifies the width of the image buffer to use, in pixels. For this value to be used, the codecWantsSpecialScaling flag in the CodecCapabilities record must be set.

requestedBufferHeight

Specifies the height of the image buffer to use, in pixels. For this value to be used, the codecWantsSpecialScaling flag in the CodecCapabilities record must be set.

Functions

This section lists the functions supported by effects components. Applications developers will typically call the high-level functions directly.



Copyright © 2005, 2009 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2009-06-01