Data Types¶
Whenever possible, After Effects presents plug-ins with opaque data types, and provides accessor functions for manipulating them. For example, video frames are represented using the opaque AEGP_WorldH. While in some cases it might be more efficient to simply modify the underlying structure, by maintaining the opaqueness of the data types we allow for changes to our implementation without making you recompile (and redistribute) your plug-ins.
AEGP API Data Types¶
Type | Describes | Manage Using |
---|---|---|
AEGP_MemHandle |
This structure contains more than just the referenced memory. So it should not be dereferenced directly. Use AEGP_LockMemHandle in the AEGP Memory Suite to get a pointer to the memory referenced by the AEGP_MemHandle .And of course, unlock it when you're done. |
AEGP Memory Suite |
AEGP_ProjectH |
The current After Effects project. Projects are a set of elements arranged hierarchically in a tree to preserve semantic relationships. Interior nodes of the tree are folders. As of CS6, there will only ever be one open project. |
AEGP Project Suite |
AEGP_ItemH |
An abstraction describing any element of a project, including folders. An item is anything that can be selected. Since multiple object types can be selected, we treat them as AEGP_ItemHs until more specificity is required. |
AEGP Item Suite |
AEGP_Collection2H |
A set of selected items. | AEGP Collection Suite |
AEGP_CompH |
A composition is a sequence of renderable items that, together, produce output. A composition exists over a time interval. Multiple compositions can exist within one project. |
AEGP Composition Suite |
AEGP_FootageH |
An item that can be rendered. Folders and compositions are the only items that are not footage. | AEGP Footage Suite |
AEGP_LayerH |
An element of a composition. Layers are rendered in sequence, which allows for occlusions. Solids, text, paint, cameras, lights, images, and image sequences are all represented as layers. Layers may be defined over sub-intervals of the composition's time interval. |
AEGP Layer Suite |
AEGP_WorldH |
A frame of pixels. | AEGP World Suite |
AEGP_EffectRefH |
An effect applied to a layer. An effect is a function that takes as its argument a layer (and possibly other parameters) and returns an altered version of the layer for rendering. |
AEGP Effect Suite |
AEGP_StreamRefH |
Any parameter stream attached to a layer, in a composition. See the description of AEGP_GetNewLayerStream from AEGP_StreamSuite5 for a full list of stream types. |
AEGP Stream Suite, AEGP Dynamic Stream Suite AEGP Keyframe Suite |
AEGP_MaskRefH |
A mask applied to a layer. An AEGP_MaskRefH is used to access details about the mask stream, not the specific points which constitute the mask. A mask is a rasterized path (sequence of vertices) that partitions a layer into two pieces, allowing each to be rendered differently. |
AEGP Mask Suite |
AEGP_MaskOutlineValH |
The specific points which constitute the mask. The points in a mask outline are ordered, and the mask need not be closed. |
AEGP Mask Outline Suite |
AEGP_TextDocumentH |
Represents the actual text associated with a text layer. | AEGP Text Document Suite |
AEGP_TextOutlinesH |
A reference to all the paths that make up the outlines of a given text layer. | AEGP Text Layer Suite |
AEGP_MarkerVal |
The data associated with a given timeline marker. | AEGP Marker Suite |
AEGP_PersistentBlobH |
A "blob" of data containing the current preferences. | AEGP Persistent Data Suite |
AEGP_RenderOptionsH |
The settings associated with a render request. | AEGP Render Options Suite |
AEGP_LayerRenderOptionsH |
The settings associated with a layer render request. | AEGP Layer Render Options Suite |
AEGP_FrameReceiptH |
A reference to a rendered frame. | AEGP Render Suite |
AEGP_RQItemRefH |
An item in the render queue. | AEGP Render Queue Suite AEGP Render Queue Item Suite |
AEGP_OutputModuleRefH |
An output module, attached to a specific AEGP_RQItemRef in the render queue. | AEGP Output Module Suite |
AEGP_SoundDataH |
The audio settings used for a given layer. | AEGP Sound Data Suite |
AEGP_RenderLayerContextH |
State information at the time of a render request, sent to an Artisan by After Effects. | AEGP Canvas Suite |
AEGP_RenderReceiptH |
Used by Artisans when rendering. | AEGP Canvas Suite |
Nasty, Brutish, and Short¶
Information about layers, streams, and many other items doesn't survive long; it's often invalidated by user activity.
Anything that modifies the quantity (not quality) of items will invalidate references to those items; adding a keyframe to a stream invalidates references to that stream, but forcing a layer to be rendered doesn't invalidate references to it. Do not cache layer pixels.
Caching references between calls to a specific hook function within your plug-in is not recommended; acquire information when you need it, and forget (release) it as soon as possible.
Were You Just Going To Leave That Data Lying Around?¶
When you ask After Effects to populate and return handles to data structures, it's important that you clean up after yourself. For the following data types, you must call the appropriate disposal routines.
Data Types Requiring Disposal¶
Data Type | Disposal function |
---|---|
AEGP_Collection2H |
AEGP_DisposeCollection , from AEGP_CollectionSuite2 |
AEGP_FootageH |
AEGP_DisposeFootage , from AEGP_FootageSuite5 |
AEGP_WorldH |
AEGP_Dispose , from AEGP_WorldSuite3(Or AEGP_DisposeTexture , from AEGP_CanvasSuite8, if layer texture created using AEGP_RenderTexture ) |
AEGP_EffectRefH |
AEGP_DisposeEffect , from AEGP_EffectSuite4 |
AEGP_MaskRefH |
AEGP_DisposeMask , from AEGP_MaskSuite6 |
AEGP_RenderOptionsH |
AEGP_Dispose , from AEGP_RenderQueueMonitorSuite1 |
AEGP_LayerRenderOptionsH |
AEGP_Dispose , from AEGP_LayerRenderOptionsSuite1 |
AEGP_RenderReceiptH |
AEGP_DisposeRenderReceipt , from AEGP_CanvasSuite8 |