Retired Document
Important: Apple recommends that developers explore QTKit and Core Video for new development in this technology area. See QTKit Framework Reference and Core Video Programming Guide for more information.
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 |
---|---|
|
The code for the atom containing the name of an entry in the effects list. |
|
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 |
---|---|
|
Retrieves the current parameter values from the standard parameters dialog box. The parameter values are placed in the |
|
Passes the menu handle for the current Apple menu to the standard parameters dialog box. |
|
Passes the menu handle for your application's Edit menu to the standard parameters dialog box. |
|
Retrieves the current parameter values from the standard parameters dialog box. This parameter values are placed in the |
|
Passes the number of the user item resource that should be replaced by the effect preview movie clip. |
|
Sets the images that are used in the preview window of the standard parameters dialog box. |
|
Sets the function that will be used when the standard parameters dialog box needs to display a color picker control. |
|
Sets the title of the standard parameters dialog box. |
|
Returns a |
|
Sets the currently active panel of the standard parameter dialog box. |
|
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 |
---|---|
|
Includes the "none" effect in the list of effects returned by |
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 |
---|---|
|
This value indicates that only one value should be entered for parameters that can optionally be tweened. |
|
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 |
---|---|
|
This value indicates that a standard validation should take place. |
|
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 |
---|---|
|
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 |
---|---|
|
The number of the preview image. |
|
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 |
---|---|
|
A pointer to the raw source image data. |
|
A pointer to the effect. |
struct EffectSource { |
long effectType; |
Ptr data; |
SourceData source; |
EffectSourcePtr next; |
}; |
Term |
Definition |
---|---|
|
The type of the effect or the constant |
|
A pointer to the track data for the effect. |
|
The source itself. |
|
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. |
|
The duration of a single effect frame. |
|
This field contains |
|
A pointer to the input sources. |
|
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 |
---|---|
|
A pointer to a |
|
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. |
|
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. |
|
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. |
|
A pointer to a |
|
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 |
|
Setting this field to true indicates to the ICM that your component's |
|
Setting this field to |
|
Specifies the width of the image buffer to use, in pixels. For this value to be used, the |
|
Specifies the height of the image buffer to use, in pixels. For this value to be used, the |
Functions
This section lists the functions supported by effects components. Applications developers will typically call the high-level functions directly.
High-Level Functions
QTGetEffectsList
QTCreateStandardParameterDialog
QTIsStandardParameterDialogEvent
QTDismissStandardParameterDialog
QTStandardParameterDialogDoAction
QTGetEffectSpeed
Low-level Functions
ImageCodecGetParameterList
ImageCodeCreateStandardParameterDialog
ImageCodecIsStandardParameterDialogEvent
ImageCodecStandardParameterDialogDoAction
ImageCodecDismissStandardParameterDialog
Utility Functions
MakeImageDescriptionForEffect
Copyright © 2005, 2009 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2009-06-01