data-types

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.	AEGP Memory Suite
	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_ProjectH`	The current After Effects project. Projects are a set of elements arranged hierarchically in a tree to preserve semantic relationships.	AEGP Project Suite
	Interior nodes of the tree are folders.
	As of CS6, there will only ever be one open project.
`AEGP_ItemH`	An abstraction describing any element of a project, including folders. An item is anything that can be selected.	AEGP Item Suite
	Since multiple object types can be selected, we treat them as AEGP_ItemHs until more specificity is required.
`AEGP_Collection2H`	A set of selected items.	AEGP Collection Suite
`AEGP_CompH`	A composition is a sequence of renderable items that, together, produce output.	AEGP Composition Suite
	A composition exists over a time interval.
	Multiple compositions can exist within one project.
`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.	AEGP Layer Suite
	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_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.	AEGP Stream Suite,
		AEGP Dynamic Stream Suite,
	See the description of `AEGP_GetNewLayerStream` from AEGP_StreamSuite5 for a full list of stream types.	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.	AEGP Mask Suite
	A mask is a rasterized path (sequence of vertices) that partitions a layer into two pieces, allowing each to be rendered differently.
`AEGP_MaskOutlineValH`	The specific points which constitute the mask.	AEGP Mask Outline Suite
	The points in a mask outline are ordered, and the mask need not be closed.
`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