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

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_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