AEGP Suites¶
As mentioned earlier, AEGPs do everything through suites. The following suites are used by all types of AEGPs, and may be called from within any hook function (except for the RegisterSuite, which must be used from within the AEGP’s entry point). Following is a description of each function in every suite, and, where appropriate details on using those functions.
Suite |
Description |
|---|---|
Manage memory resources. Use this suite! Whenever memory-related errors are encountered, After Effects can report errors for you. |
|
Manage your AEGP’s menu items. Used in conjunction with the Register Suite. |
|
Used in conjunction with the Command Suite to add functions to menu commands. AEIOs and Artisans must use this suite’s functions to indicate to After Effects that they want to receive the appropriate message streams. You can replace some After Effects’ commands using this suite. |
|
Reads and modifies project data. |
|
Manages items within a project or composition. Folders, Compositions, Solids, and Footage are all items. |
|
Query which items are currently selected, and create your own selection sets. It’s often a good UI move to select all the items your AEGP has modified, just to give the user some idea what you’ve done. |
|
Manages (and creates) compositions in a project, and composition-specific items like solids. |
|
Manages footage. |
|
Provides information about the layers within a composition, and the relationship(s) between the source and layer times. Solids, text, paint, cameras, lights, images, and image sequences can all become layers. |
|
Provides access to the effects applied to a layer.
Use Stream suites to obtain effect keyframe information.
Use |
|
Used to access the values of a layer’s keyframe properties. |
|
Used to access the characteristics of dynamic streams associated with a layer. |
|
Used to access and manipulate all keyframe data. |
|
Used to manipulate markers. Use |
|
Provides access to retrieve information about a layer’s masks. |
|
Used in conjunction with Stream Suite, this suite provides detailed information about the path rendered to make a layer’s mask. |
|
Used to access the actual text on a text layer. |
|
Used to access the paths that make up the outlines of a text layer. |
|
Supplies error message handling, AEGP version checking and access to After Effects’ undo stack. |
|
Query and manage all persistent data (i.e., the preferences file). AEGPs can also add their own data to the prefs. |
|
Obtain information on After Effects’ current color management settings. |
|
Get rendered frames (and audio samples) from within an AEGP. |
|
Allocate, dispose of, and query AEGP_Worlds.
Also provides a way to convert a |
|
Exposes After Effects’ compositing functionality, including transfer modes, track matting, and good old fashioned bit copying. |
|
Functions for managing and accessing sound data. |
|
Add and remove items from the render queue. |
|
Query and modify items in the render queue. |
|
Query and manage all items exposed in a render queue item’s options dialog. |
|
Query and modify the output modules attached to items in the render queue. |
|
The functions in this suite, while technically part of the AEGP API, are for use by effects. |
|
Gives AEGPs a way to have a function (which has the required signature) to be run on any or all available processors. |
|
Registers AEGP file and project importers as part of After Effects’ file handling. |
Fail Gracefully¶
If a suite isn’t present, make every attempt to fail gracefully. Show the user a message indicating the nature of the problem. Attempt to acquire and use an earlier version of the same suite.
Since AEGPs are so deeply integrated with After Effects, make sure that users know who or what is encountering a given problem.
Identify yourself! Provide support and/or help information to the user whenever possible.
Handling Handles¶
Use the AEGP Memory Suite to manage memory used by the AEGP. Whenever memory related errors are encountered, After Effects can report errors for you to find early on.
AEGP_MemHandle is a structure that contains more than just the referenced memory. So it should not be dereferenced directly. Use AEGP_LockMemHandle to get a pointer to the memory referenced by the AEGP_MemHandle.
And of course, unlock it when you’re done.
AEGP_MemorySuite1¶
Function |
Purpose |
|---|---|
|
Create a new memory handle.
This memory is guaranteed to be 16-byte aligned.
Use AEGP_NewMemHandle(
AEGP_PluginID *plugin_id,
const A_char *whatZ,
AEGP_MemSize size,
AEGP_MemFlag flags,
AEGP_MemHandle *memPH);
|
|
Release a handle you allocated using AEGP_NewMemHandle(). AEGP_FreeMemHandle(
AEGP_MemHandle memH);
|
|
Locks the handle into memory (cannot be moved by OS).
Use this function prior to using memory allocated by AEGP_LockMemHandle(
AEGP_MemHandle memH,
void **ptr_to_ptr);
|
|
Allows OS to move the referenced memory. Always balance lock calls with unlocks. AEGP_UnlockMemHandle(
AEGP_MemHandle memH);
|
|
Returns the allocated size of the handle. AEGP_GetMemHandleSize AEGP_MemHandle memH,
AEGP_MemSize *sizeP);
|
|
Changes the allocated size of the handle. AEGP_ResizeMemHandle(
const char *whatZ,
AEGP_MemSize new_size,
AEGP_MemHandle memH);
|
|
If After Effects runs into problems with the memory handling, the error should be reported to the user. Make use of this during development! Only memory allocated and then leaked using this suite is reported using this call, so for example memory allocated using PF_HandleSuite1 will not be reported. AEGP_SetMemReportingOn(
A_Boolean turn_OnB);
|
|
Obtain information about the number of currently allocated handles and their total size. Only memory allocated using this suite is tracked and reported using this call, so for example memory allocated using PF_HandleSuite1 will not be reported here. AEGP_GetMemStats(
AEGP_MemID mem_id,
A_long *countPL,
A_long *sizePL);
|
Registering with After Effects¶
Register functions for After Effects’ use.
AEGP_RegisterSuites5¶
Function |
Purpose |
|---|---|
|
Register a hook (command handler) function with After Effects. If you are replacing a function which After Effects also handles,
For each menu item you add, obtain your own Determine which command was sent within this hook function, and act accordingly. Currently, AEGP_RegisterCommandHook(
AEGP_PluginID aegp_plugin_id,
AEGP_HookPriority hook_priority,
AEGP_Command command,
AEGP_CommandHook command_hook_func
void *refconPV);
|
|
Register your menu update function (which determines whether or not items are active), called every time any menu is to be drawn. This hook function handles updates for all menus. AEGP_RegisterUpdateMenuHook(
AEGP_PluginID aegp_plugin_id,
AEGP_UpdateMenuHook update_menu_hook_func,
void *refconPV);
|
|
Register your termination function. Called when the application quits. AEGP_RegisterDeathHook(
AEGP_PluginID aegp_plugin_id,
AEGP_DeathHook death_hook_func,
void *refconPV);
|
|
Currently not called. |
|
Currently not called. |
|
Currently not called. |
|
Register your Artisan. See Artisans for more details. AEGP_RegisterArtisan(
A_Version api_version,
A_Version Artisan_version,
long aegp_plugin_id,
void *aegp_refconPV,
const A_char *match_nameZ,
const A_char *Artisan_nameZ,
PR_ArtisanEntryPoints *entry_funcsP);
|
|
Register your AEIO plug-in. See AEIOs for more details. AEGP_RegisterIO (
AEGP_PluginID aegp_plugin_id,
AEGP_IORefcon aegp_refconP,
const AEIO_ModuleInfo *io_infoP,
const AEIO_FunctionBlock4 *aeio_fcn_blockP);
|
|
Register your IdleHook function. After Effects will call the function sporadically, while the user makes difficult artistic decisions (or while they’re getting more coffee). AEGP_RegisterIdleHook(
AEGP_PluginID aegp_plugin_id,
AEGP_IdleHook idle_hook_func,
AEGP_IdleRefcon refconP);
|
|
Registers your AEGP as an interactive artisan, for use in previewing and rendering all layers in a given composition. AEGP_RegisterInteractiveArtisan (
A_Version api_version,
A_Version artisan_version,
AEGP_PluginID aegp_plugin_id,
void *aegp_refconPV,
const A_char *match_nameZ,
const A_char *artisan_nameZ,
PR_ArtisanEntryPoints *entry_funcsP);
|
|
Call this to register as many strings as you like for name-replacement when presets are loaded. Any time a Property name is found, or referred to in an expression, and it starts with an ASCII tab character (’t’), followed by one of the English names, it will be replaced with the localized name. (In English the tab character will simply be removed). AEGP_RegisterPresetLocalizationString(
const A_char *english_nameZ,
const A_char *localized_nameZ);
|
Manage Projects¶
These functions access and modify project data. Support for multiple projects is included to prepare for future expansion; After Effects currently adheres to the single project model.
To save project-specific data in After Effects’ preferences (and thus, outside the projects themselves), use the Persistent Data Suite.
Use caution: the functions for opening and creating projects do not save changes to the project currently open when they are called!
AEGP_ProjSuite6¶
Function |
Purpose |
|---|---|
|
Currently will never return more than 1. After Effects can have only one project open at a time. AEGP_GetNumProjects(
A_long *num_projPL)
|
|
Retrieves a specific project by index. AEGP_GetProjectProjectByIndex(
A_long proj_indexL,
AEGP_ProjectH *projPH);
|
|
Get the project name (up to AEGP_GetProjectName(
AEGP_ProjectH projH,
A_char *nameZ);
|
|
Get the path of the project (empty string the project hasn’t been saved yet). The path is a handle to a NULL-terminated A_UTF16Char string, and must be disposed with AEGP_GetProjectPath(
AEGP_ProjectH projH,
AEGP_MemHandle *unicode_pathPH)
|
|
Get the root of the project, which After Effects also treats as a folder. AEGP_GetProjectRootFolder(
AEGP_ProjectH projH,
AEGP_ItemH *root_folderPH)
|
|
Saves the entire project to the specified full path. The file path is a NULL-terminated UTF-16 string with platform separators. AEGP_SaveProjectToPath(
AEGP_ProjectH projH,
const A_UTF16Char *pathZ);
|
|
Retrieves the current time display settings. AEGP_GetProjectTimeDisplay(
AEGP_ProjectH projH,
AEGP_TimeDisplay3 *time_displayP);
typedef struct {
AEGP_TimeDisplayMode display_mode;
AEGP_SourceTimecodeDisplayMode footage_display_mode;
A_Boolean display_dropframeB;
A_Boolean use_feet_framesB;
A_char timebaseC;
A_char frames_per_footC;
AEGP_FramesDisplayMode frames_display_mode;
} AEGP_TimeDisplay3;
enum {
AEGP_TimeDisplay_TIMECODE = 0,
AEGP_TimeDisplay_FRAMES
};
typedef char AEGP_TimeDisplayMode;
enum {
AEGP_SourceTimecode_ZERO= 0,
AEGP_SourceTimecode_SOURCE_TIMECODE
};
typedef char AEGP_SourceTimecodeDisplayMode;
enum {
AEGP_Frames_ZERO_BASED= 0,
AEGP_Frames_ONE_BASED,
AEGP_Frames_TIMECODE_CONVERSION
};
typedef char AEGP_FramesDisplayMode;
|
|
Specified the settings to be used for displaying time. AEGP_SetProjectTimeDisplay(
AEGP_ProjectH projH,
const AEGP_TimeDisplay3 *time_displayP);
|
|
Returns TRUE if the project has been modified since it was opened. AEGP_ProjectIsDirty(
AEGP_ProjectH projH,
A_Boolean *is_dirtyPB);
|
|
Saves the project to the specified path. The file path is a NULL-terminated UTF-16 string with platform separators. NOTE: This will overwrite an existing file. AEGP_SaveProjectAs(
AEGP_ProjectH projH,
const A_UTF16Char *pathZ);
|
|
Creates a new project. NOTE: Will close the current project without saving it first! AEGP_NewProject(
AEGP_ProjectH *new_projectPH);
|
|
Opens a project from the supplied path, and returns its The file path is a NULL-terminated UTF-16 string with platform separators. NOTE: Will close the current project without saving it first! AEGP_OpenProjectFromPath(
const A_UTF16Char *pathZ,
AEGP_ProjectH *projectPH);
|
|
Retrieves the project bit depth. AEGP_GetProjectBitDepth(
AEGP_Projec tH projectH,
AEGP_ProjBitDepth *bit_depthP);
AEGP_ProjBitDepth will be one of the following:
|
|
Sets the project bit depth. Undoable. AEGP_SetProjectBitDepth(
AEGP_ProjectH projectH,
AEGP_ProjBitDepth bit_depth);
|
AEGP_TimeDisplay2¶
Note
Values in unused fields persist when After Effects is using a different display type.
Member |
Description |
|---|---|
|
One of the following:
|
|
0 - 100. Only used for |
|
When the timebase is 30 and the item’s framerate is 29.97, determines whether to display as non-drop frame. |
|
Only used for |
|
Usually 0 or 1. Not used when type is usually 0 or 1, not used for |
|
If |
Control Items Within Projects¶
Accesses and modifies items within a project or composition.
Anything in the project bin is an AEGP_Item. Note that cameras have no source, and thus have no AEGP_ItemH.
Unless more specificity is required for the function(s) you’re using, remain as abstract as possible; AEGP_Comps are passed into and returned from most functions as AEGP_Items.
AEGP_ItemSuite9¶
Function |
Purpose |
|---|---|
|
Retrieves the first item in a given project. AEGP_GetFirstProjItem(
AEGP_ProjectH projectH,
AEGP_ItemH *itemPH);
|
|
Retrieves the next project item; AEGP_GetNextProjItem(
AEGP_ProjectH projectH,
AEGP_ItemH itemH,
AEGP_ItemH *next_itemPH);
|
|
If the Project window is active, the active item is the selected item (if only one item is selected). If a Composition, Timeline, or Footage window is active, returns the parent of the layer associated with the front-most tab in the window. Returns NULL if no item is active. AEGP_GetActiveItem(
AEGP_ItemH *itemPH,
|
|
Returns true if the Project window is active and the item is selected. AEGP_IsItemSelected(
AEGP_ItemH itemH,
A_Boolean *selectedPB)
|
|
Toggles the selection state of the item, and (depending on To make selections in the Composition panel, use AEGP_SelectItem(
AEGP_ItemH itemH,
A_Boolean selectB,
A_Boolean deselect_othersB);
|
|
Gets type of an item. Note: solids don’t appear in the project, but can be the source to a layer. AEGP_GetItemType(
AEGP_ItemH itemH,
AEGP_ItemType *item_typeP);
Items are one of the following types:
|
|
Get name of type. (name length up to AEGP_GetTypeName(
AEGP_ItemType item_type,
A_char *nameZ);
|
|
Get item name. (name length has no limit).
It must be disposed with AEGP_GetItemName(
AEGP_PluginID pluginID,
AEGP_ItemH itemH,
AEGP_MemHandle *unicode_namePH);
|
|
Specifies the name of the AEGP_ItemH. (name length has no limit). Undoable. AEGP_SetItemName(
AEGP_ItemH itemH,
const A_UTF16Char *nameZ);
|
|
Returns the item’s unique ID, which persists across saves and loads of the project. AEGP_GetItemID(
AEGP_ItemH itemH,
A_long *item_idPL);
|
|
Get properties of an item. AEGP_GetItemFlags(
AEGP_ItemH itemH,
AEGP_ItemFlags *item_flagsP);
Flag values (may be OR’d together):
Unlike the |
|
Toggle item’s proxy usage. Undoable. AEGP_SetItemUseProxy(
AEGP_ItemH itemH,
A_Boolean use_proxyB);
|
|
Get folder containing item. AEGP_GetItemParentFolder(
AEGP_ItemH itemH,
AEGP_ItemH *parent_itemPH);
|
|
Sets an item’s parent folder. Undoable. AEGP_SetItemParentFolder(
AEGP_ItemH itemH,
AEGP_ItemH parent_folderH);
|
|
Get duration of item, in seconds. AEGP_GetItemDuration(
AEGP_ItemH itemH,
A_Time *durationPT);
|
|
Get current time within item. Not updated while rendering. AEGP_GetItemCurrentTime(
AEGP_ItemH itemH,
A_long *curr_timePT);
|
|
Get width and height of item. AEGP_GetItemDimensions(
AEGP_ItemH itemH,
A_long *widthPL)
A_long *heightPL);
|
|
Get the width of a pixel, assuming its height is 1.0, as numerator over denominator. AEGP_GetItemPixelAspectRatio(
AEGP_ItemH itemH,
A_Ratio *ratioPRt);
|
|
Removes item from all compositions. Undo-able.
Do not use the AEGP_DeleteItem(
AEGP_ItemH itemH);
|
|
Removed in Given a solid item, return its color. AEGP_GetItemSolidColor(
AEGP_ItemH itemH,
PF_Pixel *PF_Pixel);
|
|
Removed in Sets the color of an existing solid (error if AEGP_SetSolidColor(
AEGP_ItemH itemH,
AEGP_ColorVal color);
|
|
Removed in Sets the dimensions of an existing solid (error if AEGP_SetSolidDimensions(
AEGP_ItemH itemH,
A_short widthS,
A_short heightS);
|
|
Creates a new folder in the project. The newly created folder is allocated and owned by After Effects. Passing AEGP_CreateNewFolder(
const A_UTF16Char *nameZ,
AEGP_ProjectH projH),
AEGP_ItemH parentH0),
AEGP_ItemH *new_folderPH);
|
|
Sets the current time within a given AEGP_SetItemCurrentTime(
AEGP_ItemH itemH,
const A_Time *new_timePT);
|
|
Removed in AEGP_GetItemCommentLength(
AEGP_ItemH itemH,
A_u_long *buf_sizePLu);
|
|
Updated to support Unicode in AEGP_GetItemComment(
AEGP_ItemH itemH,
AEGP_MemHandle *unicode_namePH);
|
|
Updated to support Unicode in AEGP_SetItemComment(
AEGP_ItemH itemH,
const A_UTF16Char *commentZ);
|
|
Retrieves an item’s label. AEGP_GetItemLabel(
AEGP_ItemH itemH,
AEGP_LabelID *labelP);
|
|
Sets an item’s label. AEGP_SetItemLabel(
AEGP_ItemH itemH,
AEGP_LabelID label);
|
|
Gets an item’s most recently used view.
The view can be used with two calls in the AEGP_GetItemMRUView(
AEGP_ItemH itemH,
AEGP_ItemViewP *mru_viewP);
|
Note
AEGP_RenderNewItemSoundData() used to be here, but is now part of AEGP_RenderSuite4.
Managing Selections¶
This suite manages selection states, mirroring the functionality supplied by vectors in the C++ Standard Template Library.
Many types of items may be simultaneously selected in After Effects; AEGP_CollectionItems are unions of layer, mask, effect, stream, mask vertex, and keyframe items.
First acquire the current collection, then iterate across its members to ensure that whatever your AEGP does is applicable to each.
We’ve added AEGP_Collection2H and AEGP_CollectionItemV2 so that selected dynamic streams can be handled with the AEGP_CollectionSuite.
AEGP_CollectionSuite2¶
Function |
Purpose |
|---|---|
|
Creates and returns a new, empty collection.
To obtain the current composition’s selection as a collection, use AEGP_NewCollection(
AEGP_PluginID plugin_id,
AEGP_Collection2H *collectionPH);
|
|
Disposes of a collection. AEGP_DisposeCollection(
AEGP_Collection2H collectionH);
|
|
Returns the number of items contained in the given collection. AEGP_GetCollectionNumItems(
AEGP_Collection2H collectionH,
A_u_long *num_itemsPL);
|
|
Retrieves (creates and populates) the index’d collection item. AEGP_GetCollectionItemByIndex(
AEGP_Collection2H collectionH,
A_u_long indexL,
AEGP_CollectionItemV2 *itemP);
|
|
Adds an item to the given collection. AEGP_CollectionPushBack(
AEGP_Collection2H collectionH,
const AEGP_CollectionItemV2 *itemP);
|
|
Removes an index’d item (or items) from a given collection. NOTE: this range is exclusive, like STL iterators. To erase the first item, you would pass 0 and 1, respectively. AEGP_CollectionErase(
AEGP_Collection2H collectionH,
A_u_long index_firstL,
A_u_long index_lastL);
|
Ownership Of Collection Items¶
When AEGP_StreamRefHs are inserted into a collection, they are adopted by the collection; do not free them.
AEGP_EffectRefHs, on the other hand, are not adopted, and must be freed by the calling AEGP.
Manipulate Compositions¶
Provide information about the compositions in a project, and create cameras, lights, and solids.
AEGP_CompSuite11¶
Function |
Purpose |
|---|---|
|
Retrieves the handle to the composition, given an item handle.
Returns AEGP_GetCompFromItem(
AEGP_ItemH itemH,
AEGP_CompH *compPH);
|
|
Used to get the item handle, given a composition handle. AEGP_GetItemFromComp(
AEGP_CompH compH,
AEGP_ItemH *itemPH);
|
|
Returns current downsample factor. Measured in pixels X by Y. Users can choose a custom downsample factor with independent X and Y. AEGP_GetCompDownsampleFactor(
AEGP_CompH compH,
AEGP_DownsampleFactor *dsfP);
|
|
Sets the composition’s downsample factor. AEGP_SetCompDownsampleFactor(
AEGP_CompH compH,
AEGP_DownsampleFactor *dsfP);
|
|
Returns the composition background color. AEGP_GetCompBGColor(
AEGP_CompH compH,
AEGP_ColorVal *bg_colorP);
|
|
Sets a composition’s background color. AEGP_SetCompBGColor(
AEGP_CompH compH,
const AEGP_ColorVal *bg_colorP);
|
|
Returns composition flags, or’d together. AEGP_GetCompFlags(
AEGP_CompH compH,
AEGP_CompFlags *AEGP_CompFlags);
|
|
New in CC. Passes back true if the Comp’s timeline shows layer names, false if source names. This will open the comp as a side effect. AEGP_GetShowLayerNameOrSourceName(
AEGP_CompH compH,
A_Boolean *layer_names_shownPB);
|
|
New in CC. Pass in true to have the Comp’s timeline show layer names, false for source names. This will open the comp as a side effect. AEGP_SetShowLayerNameOrSourceName(
AEGP_CompH compH,
A_Boolean *layer_names_shownPB);
|
|
New in CC. Passes back true if the Comp’s timeline shows blend modes column, false if hidden. This will open the comp as a side effect. AEGP_GetShowBlendModes(
AEGP_CompH compH,
A_Boolean *blend_modes_shownPB);
|
|
New in CC. Pass in true to have the Comp’s timeline show the blend modes column, false to hide it. This will open the comp as a side effect. AEGP_GetCompFlags(
AEGP_CompH compH,
A_Boolean show_blend_modesB);
|
|
Returns the composition’s frames per second. AEGP_GetCompFramerate(
AEGP_CompH compH,
A_FpLong *fpsPF);
|
|
Sets the composition’s frames per second. AEGP_SetCompFramerate(
AEGP_CompH compH,
A_FpLong *fpsPF);
|
|
The composition shutter angle and phase. AEGP_GetCompShutterAnglePhase(
AEGP_CompH compH,
A_Ratio *angle,
A_Ratio *phase);
|
|
The duration of the shutter frame, in seconds. AEGP_GetCompShutterFrameRange(
AEGP_CompH compH,
const A_Time *comp_timeP);
|
|
Retrieves the number of motion blur samples After Effects will perform in the given composition. AEGP_GetCompSuggestedMotionBlurSamples(
AEGP_CompH compH,
A_long *samplesPL)
|
|
Specifies the number of motion blur samples After Effects will perform in the given composition. Undoable. AEGP_SetCompSuggestedMotionBlurSamples(
AEGP_CompH compH,
A_long samplesL);
|
|
New in CC. Retrieves the motion blur adaptive sample limit for the given composition. As of CC, a new comp defaults to 128. AEGP_GetCompMotionBlurAdaptiveSampleLimit(
AEGP_CompH compH,
A_long *samplesPL)
|
|
New in CC. Specifies the motion blur adaptive sample limit for the given composition. As of CC, both the limit and the suggested values are clamped to [2,256] range and the limit value will not be allowed less than the suggested value. Undoable. AEGP_SetCompMotionBlurAdaptiveSampleLimit(
AEGP_CompH compH,
A_long samplesL);
|
|
Get the time where the current work area starts. AEGP_GetCompWorkAreaStart(
AEGP_CompH compH,
A_Time *startPT);
|
|
Get the duration of a composition’s current work area, in seconds. AEGP_GetCompWorkAreaDuration(
AEGP_CompH compH,
A_Time *durationPT);
|
|
Set the work area start and duration, in seconds. Undo-able. One call to this function is sufficient to set the layer’s in point and duration; it’s not necessary to call it twice, once for each timespace. AEGP_SetCompWorkAreaStartAndDuration(
AEGP_CompH compH,
const A_Time *startPT)
const A_Time *durationPT);
|
|
Creates a new solid with a specified width, height, color, and duration in the composition. Undo-able. If you pass AEGP_CreateSolidInComp(
const A_UTF16Char *utf_nameZ,
A_Long widthL,
A_Long heightL,
const PF_Pixel *color,
AEGP_CompH parent_compH,
const A_Time *durationPT0,
AEGP_LayerH *new_solidPH);
|
|
Creates and adds a camera to the specified composition. Once created, you can manipulate the camera’s parameter streams using the AEGP Stream Suite. To specify a two-node camera, use AEGP_CreateCameraInComp(
const A_UTF16Char *utf_nameZ,
A_FloatPoint center_point,
AEGP_CompH parent_compH,
AEGP_LayerH *new_cameraPH);
|
|
Creates and adds a light to the specified composition. Once created, you can manipulate the light’s parameter streams using the AEGP Stream Suite. AEGP_CreateLightInComp(
const A_UTF16Char *utf_nameZ,
A_FloatPoint center_point,
AEGP_CompH parent_compH,
AEGP_LayerH *new_lightPH);
|
|
Creates a new composition for the project. If you don’t provide a parent folder, the composition will be at the root level of the project. Undo-able. AEGP_CreateComp(
AEGP_ItemH parent_folderHO,
const A_UTF16Char *utf_nameZ,
A_Long widthL,
A_Long heightL,
const A_Ratio *pixel_aspect_ratioPRt,
const A_Time *durationPT,
const A_Ratio *frameratePRt,
AEGP_CompH *new_compPH);
|
|
Creates a new AEGP_Collection2H from the items selected in the given composition.
The plug-in is responsible for disposing of the AEGP_GetNewCollectionFromCompSelection(
AEGP_PluginID plugin_id,
AEGP_CompH compH,
AEGP_Collection2H *collectionPH);
|
|
Sets the selection within the given composition to the given AEGP_SetSelection(
AEGP_CompH compH,
AEGP_Collection2H collectionH);
|
|
Gets the displayed start time of a composition. AEGP_GetCompDisplayStartTime(
AEGP_CompH compH,
const A_Time *start_timePT);
|
|
Not undo-able. Sets the displayed start time of a composition (has no effect on the duration of the composition). AEGP_SetCompDisplayStartTime(
AEGP_CompH compH,
const A_Time *start_timePT);
|
|
Undoable. Sets the duration of the given composition. AEGP_SetCompDuration(
AEGP_CompH compH,
const A_Time *durationPT);
|
|
Creates a “null object” in the composition (useful for translating projects from 3D applications into After Effects). If you pass AEGP_CreateNullInComp(
const A_UTF16Char *utf_nameZ,
AEGP_CompH parent_compH,
const A_Time *durationPT0,
AEGP_LayerH *new_null_solidPH);
|
|
Sets the pixel aspect ratio of a composition. AEGP_SetCompPixelAspectRatio(
AEGP_CompH compH,
const A_Ratio *parPRt);
|
|
Updated in CS6. Creates a text layer in the composition, and returns its AEGP_CreateTextLayerInComp(
AEGP_CompH parent_compH,
A_Boolean select_new_layerB,
AEGP_LayerH *new_text_lyrPH);
|
|
Updated in CS6. Creates a new box text layer, and returns its AEGP_CreateBoxTextLayerInComp(
AEGP_CompH parent_compH,
A_Boolean select_new_layerB,
A_FloatPoint box_dimensions,
AEGP_LayerH *new_text_layerPH);
|
|
Sets the dimensions of the composition. Undoable. AEGP_SetCompDimensions(
AEGP_CompH compH,
A_long widthL,
A_long heightL);
|
|
Duplicates the composition. Undoable. AEGP_DuplicateComp(
AEGP_CompH compH,
AEGP_CompH *new_compPH);
|
|
Retrieves the duration of a frame in a composition. AEGP_GetCompFrameDuration(
AEGP_CompH compH,
A_Time *timeP);
|
|
Returns the most-recently-used composition. AEGP_GetMostRecentlyUsedComp(
AEGP_CompH *compPH);
|
|
Creates and returns a handle to a new vector layer. AEGP_CreateVectorLayerInComp(
AEGP_CompH parent_compH,
AEGP_LayerH *new_vec_layerPH);
|
|
Returns an AEGP_StreamRefH to the composition’s marker stream. Must be disposed by caller. AEGP_GetNewCompMarkerStream(
AEGP_PluginID aegp_plugin_id,
AEGP_CompH parent_compH,
AEGP_StreamRefH *streamPH);
|
|
Passes back a boolean that indicates whether the specified comp uses drop-frame timecode or not. AEGP_GetCompDisplayDropFrame(
AEGP_CompH compH,
A_Boolean *dropFramePB);
|
|
Sets the dropness of the timecode in the specified composition. AEGP_SetCompDisplayDropFrame(
AEGP_CompH compH,
A_Boolean dropFrameB);
|
|
Move the selection to a certain layer index. Use along with AEGP_SetCompDisplayDropFrame(
AEGP_CompH compH,
A_long index);
|
Work with Footage¶
Provides information about footage, or items in a project or composition. When getting and setting footage’s interpretation, it is possible to specify incompatible options.
If you encounter warnings and errors during development, be sure to make all related changes atomically, and reassess the logic of the operation you’re performing.
For example, changing the pull-down interpretation of footage won’t work unless there’s a difference between it’s native and conformed frame rate.
Depending on what you’re trying to accomplish, it may make sense to abort all of your operations at that point, inform the user of the problem encountered.
AEGP_FootageSuite5¶
Function |
Purpose |
|---|---|
|
Returns an error if item isn’t a footage item. Used to convert an item handle to a footage handle. AEGP_GetMainFootageFromItem(
AEGP_ItemH itemH,
AEGP_FootageH *footagePH);
|
|
Returns an error if item has no proxy. Returns the proxy footage handle. Note: a composition can have a proxy. AEGP_GetProxyFootageFromItem(
AEGP_ItemH itemH,
AEGP_FootageH *proxy_ftgPH);
|
|
Returns the number of data (RGBA or audio) files, and the number of files per frame (may be greater than one if the footage has auxiliary channels). AEGP_GetFootageNumFiles(
AEGP_FootageH footageH,
A_long *num_filesPL0,
A_long *files_per_frmPL0);
|
|
Get fully realized path to footage source file. Retrieves the footage path for a piece of footage (or for the specified frame of a footage sequence).
AEGP_GetFootagePath(
AEGP_FootageH footageH,
A_long frame_numL,
A_long file_indexL,
AEGP_MemHandle *unicode_pathPH);
|
|
Retrieves the footage signature of specified footage. AEGP_GetFootageSignature(
AEGP_FootageH footageH,
AEGP_FootageSignature *sigP);
The signature will be one of the following:
|
|
Creates a new footage item. The file path is a NULL-terminated UTF-16 string with platform separators. Note that footage filenames with colons are not allowed, since colons are used as path separators in the HFS+ file system. AEGP_NewFootage(
AEGP_PluginID aegp_plugin_id,
const A_UTF16Char *pathZ,
const AEGP_FootageLayerKey *layer_infoP0,
const AEGP_FileSequenceImportOptions *sequence_optionsP0,
AEGP_InterpretationStyle interp_style,
void *reserved,
AEGP_FootageH *footagePH);
Note the optional params. If typedef struct {
A_long layer_idL;
A_long layer_indexL
char *nameAC;
AEGP_LayerDrawStyle draw_style;
} AEGP_FootageLayerKey;
|
|
Adds a footage item to a project. Footage will be adopted by the project, and may be added only once. This is Undo-able; do not dispose of the returned added item if it’s undone. AEGP_AddFootageToProject(
AEGP_FootageH footageH,
AEGP_ItemH folderH,
AEGP_ItemH *add_itemPH0);
|
|
Sets footage as the proxy for an item. Will be adopted by the project. This is Undo-able; do not dispose of the returned added item if it’s undone. AEGP_SetItemProxyFootage(
AEGP_FootageH footageH,
AEGP_ItemH itemH);
|
|
Replaces footage for an item. The item will replace the main footage for this item. This is Undo-able; do not dispose of the returned added item if it’s undone. AEGP_ReplaceItemMainFootage(
AEGP_FootageH footageH,
AEGP_ItemH itemH);
|
|
Deletes a footage item. Do not dispose of footage you did not create, or that has been added to the project. AEGP_DisposeFootage(
AEGP_FootageH footageH);
|
|
Populates an AEGP_FootageInterp describing the settings of the AEGP_GetFootageInterpretation(
const AEGP_ItemH itemH,
A_Boolean proxyB,
AEGP_FootageInterp *interpP);
If proxyB is |
|
Apply the settings in the AEGP_SetFootageInterpreta tion(
const AEGP_ItemH itemH,
A_Boolean proxyB,
const AEGP_FootageInterp *interpP);
If |
|
Populates an AEGP_GetFootageLayerKey(
AEGP_FootageH footageH,
AEGP_FootageLayerKey* layerKeyP);
|
|
Deprecated. Adds a new placeholder footage item to the project. Using this function for missing footage will cause the user to search for each individual missing file, regardless of whether or not they’re all in the same directory. Undo-able. AEGP_NewPlaceholderFootage(
AEGP_PluginID plugin_id,
const A_char *nameZ,
A_long width,
A_long height,
const A_Time *durationPT,
AEGP_FootageH *footagePH);
|
|
This is the hip new way to add references to footage that can’t be found right this moment. The file path is a NULL-terminated UTF-16 string with platform separators. In CS6 and earlier, file_type was ignored and we previously recommendedsetting it to If the path may not exist, pass AEGP_NewPlaceholderFootageWithPath(
AEGP_PluginID plugin_id,
const A_UTF16Char *pathZ,
AEGP_Platform path_platform,
AEIO_FileType file_type,
A_long widthL,
A_long heightL,
const A_Time *durationPT,
AEGP_FootageH *footagePH);
|
|
This is the way to add a solid.
Until the footage is added to the project, the caller owns the AEGP_NewSolidFootage(
const A_char *nameZ,
A_long width,
A_long height,
const AEGP_ColorVal *colorP,
AEGP_FootageH *footagePH);
|
|
Returns the color of a given solid. Returns an error if the AEGP_GetSolidFootageColor(
AEGP_ItemH itemH,
A_Boolean proxyB,
AEGP_ColorVal *colorP);
If |
|
Sets the color of a solid. Undo-able. AEGP_SetSolidFootageColor(
AEGP_ItemH itemH,
A_Boolean proxyB,
AEGP_ColorVal *colorP);
If |
|
Sets the dimensions of a solid. Undo-able. AEGP_SetSolidFootageDimensions(
AEGP_ItemH itemH,
A_Boolean proxyB,
A_long widthL,
A_long heightL);
If |
|
Retrieves information about the audio data in the footage item (by populating the AEGP_GetFootageSoundDataFormat(
AEGP_FootageH footageH,
AEGP_SoundDataFormat *formatP);
|
|
Populates and returns a AEGP_GetFootageSequenceImportOptions(
AEGP_FootageH footageH,
AEGP_FileSequenceImportOptions *optionsP);
|
AEGP_FootageInterp Structure¶
Member |
Purpose |
|---|---|
|
The interlace settings for the footage item. A_u_long signature; // 'FIEL'
A_short version;
FIEL_Type type;
FIEL_Order order;
A_u_long reserved;
FIEL_Type is one of the following:
|
|
AEGP_AlphaFlag flags;
A_u_char redCu;
A_u_char greenCu;
A_u_char blueCu;
If |
|
Indicates the phase for use in 3:2 pulldown. One of the following:
|
|
Indicates the number of times the footage should loop. A_long loops;
A_long reserved;
|
|
Expresses the pixel aspect ratio of the footage (x over y). |
|
The original framerate (in frames per second) of the footage item. |
|
The framerate being used for the footage item. |
|
The pixel depth of the footage. One of the following:
|
|
Indicates whether motion de-interlacing is being applied to the footage item. |
Manage Layers¶
AEGP_LayerSuite provides information about layers within a composition, and the relationship(s) between the source and layer times.
As most After Effects usage boils down to layer manipulation, this is among the largest function suites in our API.
AEGP_LayerSuite9¶
Function |
Purpose |
|---|---|
|
Obtains the number of layers in a composition. AEGP_GetCompNumLayers(
AEGP_CompH compH,
A_long *num_layersPL);
|
|
Get a AEGP_GetCompLayerByIndex(
AEGP_CompH compH,
A_long layer_indexL,
AEGP_LayerH *layerPH);
|
|
Get the active layer. If a Layer or effect controls palette is active, the active layer is that associated with the front-most tab in the window.
If a composition or timeline window is active, the active layer is the selected layer (if only one is selected; otherwise AEGP_GetActiveLayer(
AEGP_LayerH *layerPH);
|
|
Get the index of the layer (0 is the topmost layer in the composition). AEGP_GetLayerIndex(
AEGP_LayerH layerH,
A_long *layer_indexPL);
|
|
Get the AEGP_ItemH of the layer’s source item. AEGP_GetLayerSourceItem(
AEGP_LayerH layerH,
AEGP_ItemH *source_itemPH);
|
|
Retrieves the ID of the given AEGP_GetLayerSourceItemID(
AEGP_LayerH layerH,
A_long *source_idPL);
|
|
Get the AEGP_CompH of the composition containing the layer. AEGP_GetLayerParentComp(
AEGP_LayerH layerH,
AEGP_CompH *compPH);
|
|
Get the name of a layer.
Both AEGP_GetLayerName(
AEGP_PluginID pluginID,
AEGP_LayerH layerH,
AEGP_MemHandle *utf_layer_namePH0,
AEGP_MemHandle *utf_source_namePH0);
|
|
Get the quality of a layer. AEGP_GetLayerQuality(
AEGP_LayerH layerH,
AEGP_LayerQuality *qualityP);
Layer quality is one of the following flags:
|
|
Sets the quality of a layer (see flag values above). Undoable. AEGP_SetLayerQuality(
AEGP_LayerH layerH,
AEGP_LayerQuality quality);
|
|
Get flags for a layer. AEGP_GetLayerFlags(
AEGP_LayerH layerH,
AEGP_LayerFlags *layer_flagsP);
|
|
Sets one layer flag at a time. Undoable. AEGP_SetLayerFlag(
AEGP_LayerH layerH,
AEGP_LayerFlags single_flag,
A_Boolean valueB);
|
|
Determines whether the layer’s video is visible. This is necessary to account for ‘solo’ status of other layers in the composition; non-solo’d layers are still on. AEGP_IsLayerVideoReallyOn(
AEGP_LayerH layerH,
A_Boolean *onPB);
|
|
Accounts for solo status of other layers in the composition. AEGP_IsLayerAudioReallyOn(
AEGP_LayerH layerH,
A_Boolean *onPB);
|
|
Get current time, in layer or composition timespace. This value is not updated during rendering. NOTE: If a layer starts at other than time 0 or is time-stretched other than 100%, layer time and composition time are distinct. AEGP_GetLayerCurrentTime(
AEGP_LayerH layerH,
AEGP_LTimeMode time_mode,
A_Time *curr_timePT);
|
|
Get time of first visible frame in composition or layer time.
In layer time, the AEGP_GetLayerInPoint(
AEGP_LayerH layerH,
AEGP_LTimeMode time_mode,
A_Time *in_pointPT);
|
|
Get duration of layer, in composition or layer time, in seconds. AEGP_GetLayerDuration(
AEGP_LayerH layerH,
AEGP_LTimeMode time_mode,
A_Time *durationPT);
|
|
Set duration and in point of layer in composition or layer time. Undo-able. AEGP_SetLayerInPointAndDuration(
AEGP_LayerH layerH,
AEGP_LTimeMode time_mode,
const A_Time *in_pointPT,
const A_Time *durationPT);
|
|
Get the offset from the start of the composition to layer time 0, in composition time. AEGP_GetLayerOffset(
AEGP_LayerH layerH,
A_Time *offsetPT);
|
|
Set the offset from the start of the composition to the first frame of the layer, in composition time. Undoable. AEGP_SetLayerOffset(
AEGP_LayerH layerH,
A_Time *offsetPT);
|
|
Get stretch factor of a layer. AEGP_GetLayerStretch(
AEGP_LayerH layerH,
A_Ratio *stretchPRt);
|
|
Set stretch factor of a layer. AEGP_SetLayerStretch(
AEGP_LayerH layerH,
A_Ratio *stretchPRt);
|
|
Get transfer mode of a layer. AEGP_GetLayerTransferMode(
AEGP_LayerH layerH,
AEGP_LayerTransferMode *modeP);
|
|
Set transfer mode of a layer. Undoable. AEGPSetLayerTransferMode(
AEGP_LayerH layerH,
AEGP_LayerTransferMode *modeP);
As of 23.0, when you make a layer a track matte, the layer being matted will be disabled, as when you do this via the interface. |
|
Tests whether it’s currently valid to add a given item to a composition. A composition cannot be added to itself, or to any compositions which it contains; other conditions can preclude successful adding too. Adding a layer without first using this function will produce undefined results. AEGP_IsAddLayerValid(
AEGP_ItemH item_to_addH,
AEGP_CompH into_compH,
A_Boolean *validPB);
|
|
Add an item to the composition, above all other layers. Undo-able.
Use AEGP_AddLayer(
AEGP_ItemH item_to_addH,
AEGP_CompH into_compH,
A_Boolean *added_layerPH0);
|
|
Change the order of layers. Undoable. AEGP_ReorderLayer(
AEGP_LayerH layerH,
A_long layer_indexL);
To add a layer to the end of the composition, to use |
|
Given a layer’s handle and a time, returns the bounds of area visible with masks applied. AEGP_GetLayerMaskedBounds(
AEGP_LayerH layerH,
const A_Time *comp_timePT,
A_FloatRect *boundsPR);
|
|
Returns a layer’s object type. AEGP_GetLayerObjectType(
AEGP_LayerH layerH,
AEGP_ObjectType *object_type);
|
|
Is the footage item a 3D layer. All AV layers are either 2D or 3D. AEGP_IsLayer3D(
AEGP_LayerH layerH,
A_Boolean *is_3DPB);
|
|
Is the footage item a 2D layer. All AV layers are either 2D or 3D. AEGP_IsLayer2D(
AEGP_LayerH layerH,
A_Boolean *is_2DPB);
|
|
Given composition time and a layer, see if the layer will render.
Time mode is either AEGP_IsVideoActive(
AEGP_LayerH layerH,
AEGP_LTimeMode time_mode,
A_Time *comp_timePT,
A_Boolean *is_activePB);
|
|
Is the layer used as a track matte? AEGP_IsLayerUsedAsTrackMatte(
AEGP_LayerH layerH,
A_Boolean fill_must_be_activeB,
A_Boolean *is_track_mattePB);
|
|
Does this layer have a Track Matte? AEGP_DoesLayerHaveTrackMatte(
AEGP_LayerH layerH,
A_Boolean *has_track_mattePB);
|
|
Given a time in composition space, returns the time relative to the layer source footage. AEGP_ConvertCompToLayerTime(
AEGP_LayerH layerH,
const A_Time *comp_timeP,
A_Time *layer_timeP);
|
|
Given a time in layer space, find the corresponding time in composition space. AEGP_ConvertLayerToCompTime(
AEGP_LayerH layerH,
const A_Time *layer_timePT,
A_Time *comp_timePT);
|
|
Used by the dancing dissolve transfer function. AEGP_GetLayerDancingRandValue(
AEGP_LayerH layerH,
const A_Time *comp_timePT,
A_long *rand_valuePL);
|
|
Supplies the layer’s unique ID. This ID never changes during the lifetime of the project. AEGP_GetLayerID(
AEGP_LayerH layerH,
AEGP_LayerIDVal *id_valP);
|
|
Given a layer handle and time, returns the layer-to-world transformation matrix. AEGP_GetLayerToWorldXform(
AEGP_LayerH aegp_layerH,
const A_Time *comp_timeP,
A_Matrix4 *transform);
|
|
Given a layer handle, the current (composition) time, and the requested view time, returns the translation between the user’s view and the layer, corrected for the composition’s current aspect ratio. AEGP_GetLayerToWorldXformFromView(
AEGP_LayerH aegp_layerH,
const A_Time *view_timeP,
const A_Time *comp_timeP,
A_Matrix4 *transform);
|
|
Sets the name of a layer. Undo-able. new_nameZ points to a null terminated UTF-16 string. AEGP_SetLayerName(
AEGP_LayerH aegp_layerH,
const A_UTF16Char *new_nameZ);
|
|
Retrieves the handle to a layer’s parent (none if not parented). AEGP_GetLayerParent(
AEGP_LayerH layerH,
AEGP_LayerH *parent_layerPH);
|
|
Sets a layer’s parent layer. AEGP_SetLayerParent(
AEGP_LayerH layerH,
const AEGP_LayerH parent_layerH);
|
|
Deletes a layer. Can you believe it took us three suite versions to add a delete function? Neither can we. AEGP_DeleteLayer(
AEGP_LayerH layerH);
|
|
Duplicates the layer. Undoable. AEGP_DuplicateLayer(
AEGP_LayerH orig_layerH,
AEGP_LayerH *dupe_layerPH);
|
|
Retrieves the AEGP_GetLayerFromLayerID(
AEGP_CompH parent_compH,
AEGP_LayerIDVal id,
AEGP_LayerH *layerPH);
|
|
Gets a layer’s AEGP_GetLayerLabel(
AEGP_LayerH layerH,
AEGP_LabelID *labelP);
|
|
Sets a layer’s AEGP_SetLayerLabel(
AEGP_LayerH layerH,
AEGP_LabelID label);
|
|
New in CC. Get the sampling quality of a layer. AEGP_GetLayerSamplingQuality(
AEGP_LayerH layerH,
AEGP_LayerSamplingQuality *label);
Layer sampling quality is one of the following flags:
|
|
New in CC. Sets the sampling quality of a layer (see flag values above).
Option is explicitly set on the layer independent of layer quality.
If you want to force it on you must also set the layer quality to AEGP_SetLayerSamplingQuality(
AEGP_LayerH layerH,
AEGP_LayerSamplingQuality label);
|
|
New in 23.0. Returns the track matte layer of AEGP_GetTrackMatteLayer(
const AEGP_LayerH layerH,
AEGP_LayerH *track_matte_layerPH);
|
|
New in 23.0. Sets the track matte layer and track matte type of Track Matte Types:
Setting the track matte type as AEGP_SetTrackMatte(
AEGP_LayerH layerH,
const AEGP_LayerH track_matte_layerH0,
const AEGP_TrackMatte track_matte_type);
|
|
New in 23.0. Removes the track matte layer of AEGP_RemoveTrackMatte(
AEGP_LayerH layerH);
|
Layer Creation Notes¶
All layers created using AEGP calls will start at composition time 0, and have the duration of the composition.
Use AEGP_SetLayerOffset() and AEGP_SetLayerInPointAndDuration() from AEGP_LayerSuite9 to properly set the layer’s time information.
When the layer stretch factor (obtained using AEGP_GetLayerStretch in AEGP_LayerSuite9, naturally) is not 100%, the following computation will be needed to yield the correct layer offset:
offset = compIn - stretch * layerIn;
Communication With A Layer’s Effects¶
Access the effects applied to a layer. This suite provides access to all parameter data streams.
Use the Stream Suite to work with those streams.
An AEGP_Effect_RefH is a reference to an applied effect. An AEGP_InstalledEffectKey is a reference to an installed effect, which may or may not be currently applied to anything.
If Foobarocity is applied to a layer twice, there will be two distinct AEGP_Effect_RefHs, but they’ll both return the same AEGP_InstalledEffectKey.
AEGP_EffectSuite4¶
Function |
Purpose |
|---|---|
|
Get number of effects applied to a layer. AEGP_GetLayerNumEffects(
AEGP_LayerH layerH,
A_long *num_effectsPL);
|
|
Retrieves (by index) a reference to an effect applied to the layer. AEGP_GetLayerEffectByIndex(
AEGP_PluginID aegp_plugin_id,
AEGP_LayerH layerH,
AEGP_EffectIndex effect_indexL,
AEGP_EffectRefH *effectPH);
|
|
Given an AEGP_GetInstalledKeyFromLayerEffect(
AEGP_EffectRefH effect_refH,
AEGP_InstalledEffectKey *installed_keyP);
|
|
Returns description of effect parameter.
Do not use the value(s) in the ParamDef returned by this function (Use Use AEGP_GetEffectParamUnionByIndex(
AEGP_PluginID aegp_plugin_id,
AEGP_EffectRefH effectH,
PF_ParamIndex param_index,
PF_ParamType *param_typeP
PF_ParamDefUnion *uP0);
|
|
Obtains the flags for the given AEGP_GetEffectFlags(
AEGP_EffectRefH effect_refH,
AEGP_EffectFlags *effect_flagsP);
Flags will be a combination of the following:
|
|
Sets the flags (enumerated above) for the given AEGP_SetEffectFlags(
AEGP_EffectRefH effect_refH,
AEGP_EffectFlags mask,
AEGP_EffectFlags effect_flags);
|
|
Change the order of applied effects (pass the requested index). AEGP_ReorderEffect(
AEGP_EffectRefH effect_refH,
A_long effect_indexL);
|
|
Call an effect plug-in, and pass it a pointer to any data you like; the effect can modify it.
This is how AEGPs communicate with effects.
Pass AEGP_EffectCallGeneric(
AEGP_PluginID aegp_plugin_id,
AEGP_EffectRefH effectH,
const A_Time *timePT,
PF_Cmd effect_cmd,
void *extraPV);
|
|
Disposes of an AEGP_EffectRefH. Use this to dispose of any AEGP_EffectRefH returned by After Effects. AEGP_DisposeEffect(
AEGP_EffectRefH effectH);
|
|
Apply an effect to a given layer. Returns the newly-created AEGP_ApplyEffect(
AEGP_PluginID aegp_plugin_id,
AEGP_LayerH layerH,
AEGP_InstalledEffectKey installed_key,
AEGP_EffectRefH *effect_refPH);
|
|
Remove an applied effect. AEGP_DeleteLayerEffect(
AEGP_EffectRefH effect_refH);
|
|
Returns the count of effects installed in After Effects. AEGP_GetNumInstalledEffects(
A_long *num_installed_effectsPL);
|
|
Returns the AEGP_GetNextInstalledEffect(
AEGP_InstalledEffectKey key,
AEGP_InstalledEffectKey *next_keyPH);
|
|
Get name of the effect. AEGP_GetEffectName(
AEGP_InstalledEffectKey installed_key,
A_char *nameZ);
Note: use |
|
Get match name of an effect (defined in PiPL). AEGP_GetEffectMatchName(
AEGP_InstalledEffectKey installed_key,
A_char *match_nameZ);
Match names are in 7-bit ASCII. UI names are in the current application runtime encoding; for example, ISO 8859-1 for most languages on Windows. |
|
Menu category of effect. AEGP_GetEffectCategory(
AEGP_InstalledEffectKey installed_key,
A_char *categoryZ);
|
|
Duplicates a given AEGP_DuplicateEffect(
AEGP_EffectRefH orig_effect_refH,
AEGP_EffectRefH *dupe_refPH);
|
|
New in CC 2014. How many masks are on this effect? AEGP_NumEffectMask(
AEGP_EffectRefH effect_refH,
A_u_long *num_masksPL);
|
|
New in CC 2014. For a given mask_indexL, returns the corresponding AEGP_GetEffectMaskID(
AEGP_EffectRefH effect_refH,
A_u_long mask_indexL,
AEGP_MaskIDVal *id_valP);
|
|
New in CC 2014. Add an effect mask, which may be created using the Mask Management.
Returns the local stream of the effect ref - useful if you want to add keyframes.
Caller must dispose of AEGP_AddEffectMask(
AEGP_EffectRefH effect_refH,
AEGP_MaskIDVal id_val,
AEGP_StreamRefH streamPH0);
|
|
New in CC 2014. Remove an effect mask. Undoable. AEGP_RemoveEffectMask(
AEGP_EffectRefH effect_refH,
AEGP_MaskIDVal id_val);
|
|
New in CC 2014. Set an effect mask on an existing index.
Returns the local stream of the effect ref - useful if you want to add keyframes.
Caller must dispose of AEGP_SetEffectMask(
AEGP_EffectRefH effect_refH,
A_u_long mask_indexL,
AEGP_MaskIDVal id_val,
AEGP_StreamRefH *streamPH0);
|
Exploiting Effect UI Behavior To Look Cool¶
Even if you manipulate a layer’s effects, its effect controls won’t necessarily become visible.
However, if you apply then immediately remove an effect, the layer’s effect controls will be made visible.
Tricky, eh?
StreamRefs And EffectRefs¶
How do you get an AEGP_StreamRef for an effect? Start by getting the effect’s AEGP_EffectRef, by calling AEGP_GetNewEffectForEffect().
Then call AEGP_GetNewEffectStreamByIndex(), say for param index 1, which passes back a parameter stream.
Then call AEGP_GetNewParentStreamRef() - voila, your AEGP_StreamRef sir!
If you acquire references to an effect’s streams, do not dispose of the AEGP_EffectRefH until you’re done with the streams, or you’ll unbalance After Effects’ checkout mechanism. Also remember that AEGP_StreamRefHs are opaque; AEGP_StreamValue2s are not (entirely).
To get an effect’s instance name (as renamed by the user), get the AEGP_StreamRef for the effect itself and call AEGP_GetStreamName.
Diving Into Streams!¶
Just about everything in After Effects is a stream. Effect parameters, layers, masks, and shapes are all internally represented by streams. The AEGP API can access nearly every aspect of every stream.
The After Effects timeline can contain numerous object types; each object supports a set of parameters called streams. All streams, regardless of which type of object to which they’re attached, are conceptually similar (and handled similarly by After Effects. But the way you access each type of stream varies because of their containment.
A stream, once acquired, represents a value which may change over time. Not all streams can vary over time, and a particular stream may not be time-variant at the time of access.
There are two ways to access the value of a stream. If the stream has keyframes, you can use the Working With Keyframes. The values provided won’t reflect the influence of expressions. Note: In any expression, the current keyframed value is always available as the variable value.
You can also use AEGP_GetNewStreamValue from AEGP_StreamSuite5, which samples the value of the stream at a particular time. For streams without expressions or keyframes, the time parameter is meaningless, and the function returns what essentially is the constant value of the stream. Use AEGP_SetStreamValue (which doesn’t take a time as a parameter) to set these streams.
Many StreamSuite functions populate a StreamH, which your AEGP must dispose. when done. After Effects allocates and passes you a copy of the values, not a direct handle to the original value. AEGP_GetNewLayerStream() is restricted to streams for which no memory allocation is required to access their values.
Okay, What Did I Just Get?¶
A stream value is a large union, only one structure of which (depending on the stream type) is populated. Note the similarity to the PF_ParamDef.
typedef union {
AEGP_FourDVal four_d;
AEGP_ThreeDVal three_d;
AEGP_TwoDVal two_d;
AEGP_OneDVal one_d;
AEGP_ColorVal color;
AEGP_ArbBlockVal arbH;
AEGP_MarkerValP markerP;
AEGP_LayerIDVal layer_id;
AEGP_MaskIDVal mask_id;
AEGP_MaskOutlineValH mask;
AEGP_TextDocumentH text_documentH;
} AEGP_StreamVal2;
Layers¶
AEGP_GetLayerStreamValue is used to access the parameters like anchor point and position, native to almost all layers in AE.
Use IsStreamLegal to allow you to determine if that stream type is offered on that layer.
Masks¶
Since a layer can have multiple masks, access the masks using AEGP_GetLayerMaskByIndex from AEGP_MaskSuite6.
Masks don’t have streams like layers do; they get their own enumeration. Access their streams using AEGP_GetNewMaskStream from AEGP_StreamSuite5.
Effects¶
They can have a variable number of streams/parameters, and the order and definition of them is not known when the AEGP is written.
Therefore we cannot offer an enum for selecting them, and instead you must get them by index, hence GetNewEffectStreamByIndex from AEGP_StreamSuite5.
Stream Suite¶
Access and manipulate the values of a layer’s streams. For paint and text streams, use Dynamic Streams instead.
AEGP_StreamSuite5¶
Function |
Purpose |
|---|---|
|
Determines if the given stream is appropriate for the given layer. AEGP_IsStreamLegal(
AEGP_LayerH layerH,
AEGP_LayerStream which_stream,
A_Boolean* is_legalP);
|
|
Given a stream, returns whether or not a stream is time-variant (and can be keyframed). AEGP_CanVaryOverTime(
AEGP_StreamRefH streamH,
A_Boolean *can_varyPB);
|
|
Retrieves an AEGP_GetValidInterpolations(
AEGP_StreamRefH streamH,
AEGP_KeyInterpolationMask *valid_interpP);
|
|
Get a layer’s data stream. Plug-in must dispose of AEGP_GetNewLayerStream(
AEGP_PluginID id,
AEGP_LayerH layerH,
AEGP_LayerStream which_stream,
AEGP_StreamRefH *streamPH);
Only valid for
Only valid for
Only valid for
Only valid for
enum {
AEGP_LightFalloff_NONE = 0,
AEGP_LightFalloff_SMOOTH,
AEGP_LightFalloff_INVERSE_SQUARE_CLAMPED
};
typedef A_u_long AEGP_LightFalloffType;
|
|
Get number of parameter streams associated with an effect. AEGP_GetEffectNumParamStreams(
AEGP_EffectRefH effect_refH,
A_long *num_parmsPL);
|
|
Get an effect’s parameter stream. Plug-in must dispose of AEGP_GetNewEffectStreamByIndex(
AEGP_PluginID id,
AEGP_EffectRefH effect_refH,
PF_ParamIndex param_index,
AEGP_StreamRefH *streamPH);
|
|
Get a mask’s stream. The stream must be disposed. Also see the AEGP_MaskSuite and AEGP_MaskOutlineSuite for additional Mask functions.
Useful for iteration:
AEGP_GetNewMaskStream(
AEGP_PluginID aegp_plugin_id,
AEGP_MaskRefH mask_refH,
AEGP_MaskStream which_stream,
AEGP_StreamRefH *mask_strmPH);
|
|
Dispose of a stream (do this with all streams passed to the plug-in by these functions). AEGP_DisposeStream(
AEGP_StreamRefH streamH);
|
|
Get the mask’s opacity stream. The stream must be disposed. AEGP_GetNewMaskOpacity(
AEGP_PluginID aegp_plugin_id,
AEGP_MaskH maskH,
PF_ParamIndex param_index,
AEGP_StreamRefH *mask_opacity_streamPH);
|
|
Get name of the stream (localized or forced English). is handle of AEGP_GetStreamName(
AEGP_PluginID pluginID,
AEGP_StreamRefH streamH,
A_Boolean force_englishB,
AEGP_MemHandle *utf_stream_namePH);
NOTE: if |
|
Get stream units, formatted as text (localized or forced English); AEGP_GetStreamUnitsText(
AEGP_StreamRefH streamH,
A_Boolean force_englishB,
A_char *unitsZ);
|
|
Get stream’s flags, as well as minimum and maximum values (as floats), if the stream has mins and maxes. StreamFlags values:
AEGP_GetStreamProperties(
AEGP_StreamRefH streamH,
AEGP_StreamFlags *flagsP,
A_FpLong *minP0,
A_FpLong *maxP0);
|
|
Returns whether or not the stream is affected by expressions. AEGP_IsStreamTimevarying(
AEGP_StreamRefH streamH,
A_Boolean *is_timevaryPB);
|
|
Get type (dimension) of a stream. AEGP_GetStreamType(
AEGP_StreamRefH streamH,
AEGP_StreamType *stream_typeP);
NOTE: always returns |
|
Get value, at a time you specify, of stream. AEGP_GetNewStreamValue(
AEGP_PluginID aegp_plugin_id,
AEGP_StreamRefH streamH,
AEGP_LTimeMode time_mode,
const A_Time *timePT,
A_Boolean pre_exprB,
AEGP_StreamValue2 *valueP);
|
|
Dispose of stream value. Always deallocate values passed to the plug-in. AEGP_DisposeStreamValue(
AEGP_StreamValue2 *valueP);
|
|
Only legal when stream is not time-variant. AEGP_SetStreamValue(
AEGP_PluginID aegp_plugin_id,
AEGP_StreamRefH streamH,
AEGP_StreamValue2 *valueP);
|
|
NOTE: This convenience function is only valid for streams with primitive data types,
and not for AEGP_GetLayerStreamValue(
AEGP_LayerH layerH,
AEGP_LayerStream which_stream,
AEGP_LTimeMode time_mode,
const A_Time *timePT,
A_Boolean pre_expB,
AEGP_StreamVal *stream_valP,
AEGP_StreamType *strm_typeP0);
|
|
Determines whether expressions are enabled on the given AEGP_GetExpressionState(
AEGP_PluginID aegp_plugin_id,
AEGP_StreamRefH streamH,
A_Boolean *enabledPB);
|
|
Enables and disables expressions on the given AEGP_SetExpressionState(
AEGP_PluginID aegp_plugin_id,
AEGP_StreamRefH streamH,
A_Boolean enabledB);
|
|
Obtains the expression’s text. Starting in suite version 5 (available in 15.0 and later), this now supports Unicode. AEGP_GetExpression(
AEGP_PluginID aegp_plugin_id,
AEGP_StreamRefH streamH,
AEGP_MemHandle *unicodeHZ);
|
|
Sets the expression’s text. Starting in suite version 5 (available in 15.0 and later), this now supports Unicode. AEGP_SetExpression(
AEGP_PluginID aegp_plugin_id,
AEGP_StreamRefH streamH,
const A_UTF16Char* expressionP);
|
|
Duplicates a given AEGP_DuplicateStreamRef(
AEGP_PluginID aegp_plugin_id,
AEGP_StreamRefH streamH,
AEGP_StreamRefH *dup_streamPH);
|
Dynamic Streams¶
AEGP_DynamicStreamSuite accesses and manipulates paint and text streams.
Use AEGP_GetStreamGroupingType and AEGP_GetDynamicStreamFlags to identify the stream before attempting to use functions which only work on certain stream types.
Also note that, often, you can simply use Stream Suite calls to work with dynamic streams. On the other hand, only those functions specific to dynamic streams are in this suite.
AEGP_DynamicStreamSuite4¶
Function |
Purpose |
|---|---|
|
Retrieves the AEGP_StreamRefH corresponding to the layer. This function is used to initiate a recursive walk of the layer’s streams. AEGP_GetNewStreamRefForLayer(
AEGP_PluginID aegp_plugin_id,
AEGP_LayerH layerH,
AEGP_StreamRefH *streamPH);
|
|
Retrieves the AEGP_StreamRefH corresponding to the mask. AEGP_GetNewStreamRefForMask(
AEGP_PluginID aegp_plugin_id,
AEGP_MaskRefH maskH,
AEGP_StreamRefH *streamPH);
|
|
Retrieves the number of sub-streams associated with the given AEGP_GetStreamDepth(
AEGP_StreamRefH streamH,
A_long *depthPL);
|
|
Retrieves the grouping type for the given AEGP_GetStreamGroupingType(
AEGP_StreamRefH streamH,
AEGP_StreamGroupingType *group_typeP);
AEGP_StreamGroupingType will be one of the following:
|
|
Retrieves the number of streams associated with the given AEGP_GetNumStreamsInGroup(
AEGP_StreamRefH streamH,
A_long *num_streamsPL);
|
|
Retrieves the flags for a given AEGP_StreamRefH. AEGP_GetDynamicStreamFlags(
AEGP_StreamRefH streamH,
AEGP_DynStreamFlags *flagsP);
|
|
Sets the specified flag for the Note: flags must be set individually. Undoable if AEGP_SetDynamicStreamFlag(
AEGP_StreamRefH streamH,
AEGP_DynStreamFlags one_flag,
A_Boolean undoableB,
A_Boolean setB);
This call may be used to dynamically show or hide parameters, by setting and clearing |
|
Retrieves a sub-stream by index from a given AEGP_GetNewStreamRefByIndex(
AEGP_PluginID aegp_plugin_id,
AEGP_StreamRefH parent_groupH,
A_long indexL,
AEGP_StreamRefH *streamPH);
|
|
Retrieves a sub-stream by match name from a given AEGP_GetNewStreamRefByMatchname(
AEGP_PluginID aegp_plugin_id,
AEGP_StreamRefH parent_groupH,
const A_char *match_nameZ,
AEGP_StreamRefH *streamPH);
Here are some handy stream names, for which references may be retrieved:
|
|
Deletes the specified stream from a stream grouping.
Note that the caller must still dispose of any AEGP_DeleteStream(
AEGP_StreamRefH streamH);
Note: as of 6.5, if a stream is deleted while it or any child stream is selected, the current composition selection will become |
|
Sets the new index of the specified AEGP_ReorderStream(
AEGP_StreamRefH streamH
A_long new_indexL);
|
|
Duplicates the specified stream and appends it to the stream group.
Undoable.
Only valid for children of AEGP_DuplicateStream(
AEGP_PluginID aegp_plugin_id,
AEGP_StreamRefH streamH,
A_long *new_indexPL0);
|
|
Sets the name of the given NOTE: If you retrieve the name with force_englishB set to AEGP_SetStreamName(
AEGP_StreamRefH streamH,
const A_UTF16Char *nameZ);
Note: Use this on an effect stream’s group to change the display name of an effect. |
|
Returns whether or not it is currently possible to add a stream through the API. AEGP_CanAddStream(
AEGP_StreamRefH group_streamH,
const A_char *match_nameZ,
A_Boolean *can_addPB);
|
|
Adds a stream to the specified stream group. Undoable. Only valid for AEGP_AddStream(
AEGP_PluginID aegp_plugin_id,
AEGP_StreamRefH indxd_grp_streamH,
const A_char *match_nameZ,
AEGP_StreamRefH *streamPH0);
|
|
Retrieves the match name for the specified Note that this may differ from the display name, which can be retrieves using AEGP_GetMatchName(
AEGP_StreamRefH streamH,
A_char *nameZ);
|
|
Retrieves an AEGP_GetNewParentStreamRef(
AEGP_PluginID plugin_id,
AEGP_StreamRefH streamH,
AEGP_StreamRefH *parentPH);
|
|
Returns whether or not the specified Note: the same result is available throught the After Effect user interface by typing “UU” with the composition selected. AEGP_GetStreamIsModified(
AEGP_StreamRefH streamH,
A_Boolean *modifiedPB);
|
|
Retrieves the index of a given stream, relative to its parent stream.
Only valid for children of AEGP_GetStreamIndexInParent(
AEGP_StreamRefH streamH,
A_long *indexPL);
NOTE: As mentioned elsewhere, |
|
Valid on leaf streams only. Returns true if this stream is a multidimensional stream that can have its dimensions separated, though they may not be currently separated. Terminology: A Leader is the stream that can be separated, a Follower is one of N automatic streams that correspond to the N dimensions of the Leader. A Leader isn’t always separated, call AEGP_IsSeparationLeader(
AEGP_StreamRefH streamH,
A_Boolean *leaderPB);
|
|
Methods such as AEGP_AreDimensionsSeparated(
AEGP_StreamRefH streamH,
A_Boolean *separatedPB);
|
|
Valid only if AEGP_AreDimensionsSeparated(
AEGP_StreamRefH streamH,
A_Boolean *separatedPB);
|
|
Retrieve the Follower stream corresponding to a given dimension of the Leader stream.
AEGP_GetSeparationFollower(
AEGP_StreamRefH leader_streamH
A_short dimS,
AEGP_StreamRefH *follower_streamPH);
|
|
Valid on leaf streams only.
Returns AEGP_IsSeparationFollower(
AEGP_StreamRefH streamH
A_Boolean *followerPB);
|
|
Valid on separation Followers only, returns the Leader it is part of. AEGP_GetSeparationLeader(
AEGP_StreamRefH follower_streamH,
AEGP_StreamRefH *leader_streamPH);
|
|
Valid on separation Followers only, returns which dimension of the Leader it corresponds to. AEGP_GetSeparationDimension(
AEGP_StreamRefH follower_streamH,
A_short *dimPS);
|
Working With Keyframes¶
Keyframes make After Effects what it is. AEGPs (and…ssshh, don’t tell anyone…effects) can use this suite to add, manipulate and remove keyframes from any keyframe-able stream.
AEGP_KeyframeSuite3¶
Function |
Purpose |
|---|---|
|
Retrieves the number of keyframes on the given stream.
Returns AEGP_GetStreamNumKFs(
AEGP_StreamRefH streamH,
A_long *num_kfsPL);
|
|
Retrieves the time of the specified keyframe. AEGP_GetKeyframeTime(
AEGP_StreamRefH streamH,
AEGP_KeyframeIndex index,
AEGP_LTimeMode time_mode,
A_Time *timePT);
|
|
Adds a keyframe to the specified stream (at the specified composition or layer time). Returns the new keyframe’s index. All indexes greater than the new index are now invalid (but you knew that). If there is already a keyframe at that time, the values will be updated. AEGP_InsertKeyframe(
AEGP_StreamRefH streamH,
AEGP_LTimeMode time_mode,
const A_Time *timePT,
AEGP_KeyframeIndex *key_indexP);
|
|
Deletes the specified keyframe. AEGP_DeleteKeyframe(
AEGP_StreamRefH streamH,
AEGP_KeyframeIndex key_index);
|
|
Creates and populates an AEGP_GetNewKeyframeValue(
AEGP_PluginID plugin_id,
AEGP_StreamRefH streamH,
AEGP_KeyframeIndex key_index,
AEGP_StreamValue2 *valueP);
|
|
Sets the stream’s value at the time of the keyframe. AEGP_SetKeyframeValue(
AEGP_StreamRefH streamH,
AEGP_KeyframeIndex index,
const AEGP_StreamValue2 *valP);
|
|
Retrieves the dimensionality of the stream’s value. AEGP_GetStreamValueDimensionality(
AEGP_StreamRefH streamH,
A_short *value_dimPS);
|
|
Retrieves the temporal dimensionality of the stream. AEGP_GetStreamTemporalDimensionality(
AEGP_StreamRefH streamH,
A_short *t_dimPS);
|
|
Returns the The returned AEGP_GetNewKeyframeSpatialTangents(
AEGP_PluginID plugin_id,
AEGP_StreamRefH streamH,
AEGP_KeyframeIndex key_index,
AEGP_StreamValue2 *in_tanP0,
AEGP_StreamValue2 *out_tanP0);
|
|
Specifies the tangential AEGP_SetKeyframeSpatialTangents(
AEGP_StreamRefH streamH,
AEGP_KeyframeIndex key_index,
const AEGP_StreamValue2 *in_tP0,
const AEGP_StreamValue2 *out_tP0);
NOTE: In |
|
Retrieves the AEGP_GetKeyframeTemporalEase(
AEGP_StreamRefH streamH,
AEGP_KeyframeIndex key_index,
A_long dimensionL,
AEGP_KeyframeEase *in_easeP0,
AEGP_KeyframeEase *out_easeP0);
NOTE: the returned ease values must be multiplied by layer height to match the values displayed in the After Effects UI. |
|
Specifies the AEGP_SetKeyframeTemporalEase(
AEGP_StreamRefH streamH,
AEGP_KeyframeIndex key_index,
A_long dimL,
const AEGP_KeyframeEase *in_P0,
const AEGP_KeyframeEase *outP0);
|
|
Retrieves the flags currently set for the keyframe. AEGP_GetKeyframeFlags(
AEGP_StreamRefH streamH,
AEGP_KeyframeIndex key_index,
AEGP_KeyframeFlags *flagsP);
|
|
Sets the specified flag for the keyframe. Flags must be set individually. AEGP_SetKeyframeFlag(
AEGP_StreamRefH streamH,
AEGP_KeyframeIndex key_index,
AEGP_KeyframeFlags flag,
A_Boolean valueB);
|
|
Retrieves the in and out AEGP_GetKeyframeInterpolation(
AEGP_StreamRefH streamH,
AEGP_KeyframeIndex key_index,
AEGP_KeyframeInterpolationType *inP0,
AEGP_KeyframeInterpolationType *outP0);
|
|
Specifies the in and out AEGP_SetKeyframeInterpolation(
AEGP_StreamRefH streamH,
AEGP_KeyframeIndex key_index,
AEGP_KeyframeInterpolationType in_interp,
AEGP_KeyframeInterpolationType out_interp);
|
|
Informs After Effects that you’re going to be adding several keyframes to the specified stream.
After Effects will return an allocated opaque AEGP_StartAddKeyframes(
AEGP_StreamRefH streamH,
AEGP_AddKeyframesInfoH *akPH);
|
|
Adds a keyframe to the specified stream at the specified (layer or composition) time. Note: this doesn’t actually do anything to the stream’s value. AEGP_AddKeyframes(
AEGP_AddKeyframesInfoH akH,
AEGP_LTimeMode time_mode,
const A_Time *timePT,
A_long *indexPL);
|
|
Sets the value of the specified keyframe. AEGP_SetAddKeyframe(
AEGP_AddKeyframesInfoH akH,
A_long indexL,
const AEGP_StreamValue2 *valueP);
|
|
Tells After Effects you’re done adding keyframes. AEGP_EndAddKeyframes(
A_Boolean addB,
AEGP_AddKeyframesInfoH akH);
|
Adding Multiple Keyframes¶
Each time you call AEGP_InsertKeyframe(), the entire stream is added to the undo stack.
If you’re adding one or two keyframes, this isn’t a problem. However, if you’re writing a keyframer, you’ll want to do things the right way.
Before you begin adding keyframes, call the (very-appropriately-named) AEGP_StartAddKeyframes, passing it an opaque AEGP_AddKeyframesInfoH.
For each keyframe to add, call AEGP_AddKeyframes to set the time to be used (and get the newly-added keyframe’s index), then AEGP_SetAddKeyframe to specify the value to be used.
Once you’re finished, call AEGP_EndAddKeyframes to let know After Effects know it’s time to add the changed parameter stream to the undo stack.
Marker Streams¶
AEGP_MarkerSuite allows for direct manipulation of marker data.
AEGP_MarkerSuite2¶
Function |
Purpose |
|---|---|
|
Creates a new marker. AEGP_NewMarker(
AEGP_MarkerValP *markerPP);
|
|
Disposes of a marker. AEGP_DisposeMarker(
AEGP_MarkerValP markerP);
|
|
Duplicates a marker (didn’t see that one coming, eh?). AEGP_DuplicateMarker(
AEGP_MarkerValP markerP,
AEGP_MarkerValP *new_markerP);
|
|
Sets a marker flag’s value. AEGP_SetMarkerFlag(
AEGP_MarkerValP markerP,
AEGP_MarkerFlagType flagType,
A_Boolean valueB);
Currently, AEGP_MarkerFlagType is one of the following:
|
|
Gets the value (see above) of a given AEGP_GetMarkerFlag(
AEGP_ConstMarkerValP markerP,
AEGP_MarkerFlagType flagType
A_Boolean *valueBP);
|
|
Retrieves the UTF-16, NULL-terminated string located in the specified marker field.
Must be disposed of by caller using AEGP_GetMarkerString(
AEGP_PluginID id,
AEGP_ConstMarkerValP markerP,
AEGP_MarkerStringType strType,
AEGP_MemHandle *unicodePH);
|
|
Sets the specified field of a marker to the provided text. AEGP_SetMarkerString(
AEGP_MarkerValP markerP,
AEGP_MarkerStringType strType,
const A_u_short *unicodeP,
A_long lengthL);
|
|
Returns the number of cue point parameters. AEGP_CountCuePointParams(
AEGP_ConstMarkerValP markerP,
A_long *paramsLP);
|
|
Returns the cue point param at the specified index (which must be between AEGP_GetIndCuePointParam(
AEGP_PluginID id,
AEGP_ConstMarkerValP markerP,
A_long param_indexL,
AEGP_MemHandle *unicodeKeyPH,
AEGP_MemHandle *uni_ValuePH);
|
|
Set the value of an indexed cue point parameter to the specified value.
AEGP_SetIndCuePointParam(
AEGP_MarkerValP markerP,
A_long param_idxL,
const A_u_short *unicode_KeyP,
A_long key_lengthL,
const A_u_short *unicode_ValueP,
A_long value_lengthL);
|
|
Inserts a cue point parameter.
This call is following by AEGP_InsertCuePointParam(
AEGP_MarkerValP markerP,
A_long param_idxL);
|
|
Deletes the cue point param at the specified index. AEGP_DeleteIndCuePointParam(
AEGP_MarkerValP markerP,
A_long param_idxL);
|
|
AEGP_SetMarkerDuration(
AEGP_MarkerValP markerP,
const A_Time *durationPT);
|
|
AEGP_GetMarkerDuration(
AEGP_ConstMarkerValP markerP,
A_Time *durationPT);
|
Mask Management¶
Access, manipulate, and delete a layer’s masks.
AEGP_MaskSuite6¶
Function |
Purpose |
|---|---|
|
Counts the masks applied to a layer, AEGP_GetLayerNumMasks(
AEGP_LayerH aegp_layerH,
A_long *num_masksPL);
|
|
Given a layer handle and mask index, returns a pointer to the mask handle.
You must destroy the mask handle by using AEGP_GetLayerMaskByIndex(
AEGP_LayerH aegp_layerH,
A_long mask_indexL,
AEGP_MaskRefH *maskPH);
|
|
Dispose of a mask handle. AEGP_DisposeMask(
AEGP_MaskRefH maskH);
|
|
Given a mask handle, determines if the mask is inverted or not. AEGP_GetMaskInvert(
AEGP_MaskRefH maskH,
A_Boolean *invertPB);
|
|
Sets the inversion state of a mask. AEGP_SetMaskInvert(
AEGP_MaskRefH mask_refH,
A_Boolean invertB);
|
|
Given a mask handle, returns the current mode of the mask.
AEGP_GetMaskMode(
AEGP_MaskRefH maskH,
PF_MaskMode *modeP);
|
|
Sets the mode of the given mask. AEGP_SetMaskMode(
AEGP_MaskRefH maskH,
PF_MaskMode mode);
|
|
Retrieves the motion blur setting for the given mask. AEGP_GetMaskMotionBlurState(
AEGP_MaskRefH mask_refH,
AEGP_MaskMBlur *blur_stateP);
|
|
New in CS6. Sets the motion blur setting for the given mask. AEGP_SetMaskMotionBlurState(
AEGP_MaskRefH mask_refH,
AEGP_MaskMBlur blur_state);
|
|
New in CS6. Gets the type of feather falloff for the given mask, either
AEGP_SetMaskMotionBlurState(
AEGP_MaskRefH mask_refH,
AEGP_MaskFeatherFalloff *feather_falloffP);
|
|
Sets the type of feather falloff for the given mask. AEGP_SetMaskMotionBlurState(
AEGP_MaskRefH mask_refH,
AEGP_MaskFeatherFalloff feather_falloff);
|
|
Removed in CS4. Use |
|
|
|
Retrieves the AEGP_GetMaskID(
AEGP_MaskRefH mask_refH,
AEGP_MaskIDVal *id_valP);
|
|
Creates a new mask on the referenced AEGP_CreateNewMask(
AEGP_LayerH layerH,
AEGP_MaskRefH *mask_refPH,
A_long *mask_indexPL0);
|
|
AEGP_DeleteMaskFromLayer(
AEGP_MaskRefH mask_refH);
NOTE: As of 6.5, if you delete a mask and it or a child stream is selected, the current selection within the composition will become NULL. |
|
Retrieves the color of the specified mask. AEGP_GetMaskColor(
AEGP_MaskRefH mask_refH,
AEGP_ColorVal *colorP);
|
|
Sets the color of the specified mask. AEGP_SetMaskColor(
AEGP_MaskRefH mask_refH,
const AEGP_ColorVal *colorP);
|
|
Retrieves the lock state of the specified mask. AEGP_GetMaskLockState(
AEGP_MaskRefH mask_refH,
A_Boolean *is_lockedPB);
|
|
Sets the lock state of the specified mask. AEGP_SetMaskLockState(
AEGP_MaskRefH mask_refH,
A_Boolean lockB);
|
|
Returns whether or not the given mask is used as a rotobezier. AEGP_GetMaskIsRotoBezier(
AEGP_MaskRefH mask_refH,
A_Boolean *is_roto_bezierPB);
|
|
Sets whether a given mask is to be used as a rotobezier. AEGP_SetMaskIsRotoBezier(
AEGP_MaskRefH mask_refH,
A_Boolean *is_roto_bezierPB);
|
|
Duplicates a given AEGP_DuplicateMask(
AEGP_MaskRefH orig_mask_refH,
AEGP_MaskRefH *dupe_mask_refPH);
|
Mask Outlines¶
The Mask Suite above tells plug-ins about the masks on a layer, but not about the details of those masks.
This is because processing is required on After Effects’ part to access the information; the information isn’t just lying around.
Plug-ins access that information using this Mask Outline Suite.
AEGP_MaskOutlineSuite3¶
Function |
Purpose |
|---|---|
|
Given an mask outline pointer (obtainable through the Stream Suite), determines if the mask path is open or closed. AEGP_IsMaskOutlineOpen(
AEGP_MaskOutlineVal *mask_outlineP,
A_Boolean *openPB);
|
|
Sets the open state of the given mask outline. AEGP_SetMaskOutlineOpen(
AEGP_MaskOutlineValH mask_outlineH,
A_Boolean openB);
|
|
Given a mask outline pointer, returns the number of segments in the path.
AEGP_GetMaskOutlineNumSegments(
AEGP_MaskOutlineVal *mask_outlineP,
A_long *num_segmentsPL);
|
|
Given a mask outline pointer and a point between 0 and the total number of segments.
For closed mask paths, AEGP_GetMaskOutlineVertexInfo(
AEGP_MaskOutlineVal *mask_outlineP,
A_long which_pointL,
AEGP_MaskVertex *vertexP);
|
|
Sets the vertex information for a given index.
Setting vertex 0 is special; its in tangent will actually set the out tangent of the last vertex in the outline.
Of course, AEGP_SetMaskOutlineVertexInfo(
AEGP_MaskOutlineValH mask_outlineH,
AEGP_VertexIndex which_pointL,
AEGP_MaskVertex *vertexP);
|
|
Creates a vertex at index position.
All vertices which formerly had an AEGP_CreateVertex(
AEGP_MaskOutlineValH mask_outlineH,
AEGP_VertexIndex position);.
NOTE: All masks must have at least one vertex. |
|
Removes a vertex from a mask. AEGP_DeleteVertex(
AEGP_MaskOutlineValH mask_outlineH,
AEGP_VertexIndex index);
|
|
New in CS6. AEGP_DeleteVertex(
AEGP_MaskOutlineValH mask_outlineH,
A_long *num_feathersPL);
|
|
New in CS6. AEGP_GetMaskOutlineFeatherInfo(
AEGP_MaskOutlineValH mask_outlineH,
AEGP_FeatherIndex which_featherL,
AEGP_MaskFeather *featherP);
|
|
New in CS6. Feather must already exist; use AEGP_SetMaskOutlineFeatherInfo(
AEGP_MaskOutlineValH mask_outlineH,
AEGP_VertexIndex which_featherL,
const AEGP_MaskFeather *featherP);
|
|
New in CS6. Index of new feather is passed back in AEGP_CreateMaskOutlineFeather(
AEGP_MaskOutlineValH mask_outlineH,
const AEGP_MaskFeather *featherP0,
AEGP_FeatherIndex *insert_positionP);
|
|
New in CS6. AEGP_DeleteMaskOutlineFeather(
AEGP_MaskOutlineValH mask_outlineH,
AEGP_FeatherIndex index);
|
Mask Feathering¶
New for CS6, masks can be feathered.
AEGP_MaskFeather is defined as follows:
typedef struct {
A_long segment; // mask segment where feather is
PF_FpLong segment_sF; // 0-1: feather location on segment
PF_FpLong radiusF; // negative value allowed if type == AEGP_MaskFeatherType_INNER
PF_FpShort ui_corner_angleF; // 0-1: angle of UI handle on corners
PF_FpShort tensionF; // 0-1: tension of boundary at feather pt
AEGP_MaskFeatherInterp interp;
AEGP_MaskFeatherType type;
} AEGP_MaskFeather;
AEGP_MaskFeatherInterp is either AEGP_MaskFeatherInterp_NORMAL or AEGP_MaskFeatherInterp_HOLD_CW.
AEGP_MaskFeatherType is either AEGP_MaskFeatherType_OUTER or AEGP_MaskFeatherType_INNER.
This suite enables AEGPs to get and set the text associated with text layers.
Note: to get started, retrieve an AEGP_TextDocumentH by calling AEGP_GetLayerStreamValue, above, and passing AEGP_StreamType_TEXT_DOCUMENT as the AEGP_StreamType.
Working With Text Layers¶
This suite enables AEGPs to get and set the text associated with text layers.
AEGP_TextDocumentSuite1¶
Function |
Purpose |
|---|---|
|
Retrieves the UTF-16, NULL-terminated string used in the Note: After Effects will allocate the AEGP_GetNewText(
AEGP_PluginID id,
AEGP_TextDocumentH text_docH,
AEGP_MemHandle *unicodePH);
|
|
Specifies the text to be used by the AEGP_SetText(
AEGP_TextDocumentH text_docH,
const A_u_short *unicodePS,
long lengthL);
|
Working With Text Outlines¶
The AEGP_TextLayerSuite provides access to the actual outlines of the text used by text layers.
Once you have a path, you can manipulate it with PF_PathQuerySuite1 and PF_PathDataSuite.
AEGP_TextLayerSuite1¶
Function |
Purpose |
|---|---|
|
Allocates and returns a handle to the AEGP_GetNewTextOutlines(
AEGP_LayerH layerH,
const A_Time *layer_timePT,
AEGP_TextOutlinesH *outlinesPH);
|
|
Dispose of those outlines we allocated on your behalf! AEGP_DisposeTextOutlines(
AEGP_TextOutlinesH outlinesH);
|
|
Retrieves the number of text outlines for the layer. AEGP_GetNumTextOutlines(
AEGP_TextOutlinesH outlinesH,
A_long *num_otlnsPL);
|
|
Returns a PF_PathOutlinePtr for the specifed text outline. AEGP_GetIndexedTextOutline(
AEGP_TextOutlinesH outlinesH,
A_long path_indexL,
PF_PathOutlinePtr *pathPP);
|
Utility Functions¶
The Utility suite supplies error message handling, AEGP version checking and access to the undo stack.
Everything you need to keep After Effects and your plug-in tidy.
AEGP_UtilitySuite6¶
Function |
Purpose |
|---|---|
|
Displays dialog with name of the AEGP followed by the string passed. AEGP_ReportInfo(
AEGP_PluginID aegp_plugin_id,
const A_char *info_stringZ);
|
|
New in CC. Displays dialog with name of the AEGP followed by the unicode string passed. AEGP_ReportInfoUnicode(
AEGP_PluginID aegp_plugin_id,
const A_UTF16Char *info_stringP);
|
|
Returns version of AEGP_GetDriverSpecVersion(
A_short *major_versionPS,
A_short *minor_versionPS);
|
|
Silences errors. Must be balanced with AEGP_StartQuietErrors(
AEGP_ErrReportState *err_stateP);
|
|
Re-enables errors. AEGP_EndQuietErrors(
AEGP_ErrReportState *err_stateP)
|
|
Add action(s) to the undo queue. The user may undo any actions between this and AEGP_StartUndoGroup(
const A_char *undo_nameZ);
|
|
Ends the undo list. AEGP_EndUndoGroup();
|
|
Returns an AEGP_PluginID, which effect plug-ins can then use in calls to many functions throughout the AEGP API.
Effects should only call this function once, during AEGP_RegisterWithAEGP(
AEGP_GlobalRefcon global_refcon,
const A_char *plugin_nameZ,
AEGP_PluginID *plugin_id);
|
|
Retrieves After Effects’ HWND; useful when displaying your own dialog on Windows. If you don’t use After Effects’ HWND, your modal dialog will not prevent interaction with the windows behind, and pain will ensue. AEGP_GetMainHWND(
void *main_hwnd);
|
|
Toggles whether or not floating palettes are displayed. Use this with care; users get twitchy when you unexpectedly change the UI on them. AEGP_ShowHideAllFloaters(
A_Boolean include_tool_palB);
|
|
Retrieves the foreground color from the paint palette. AEGP_PaintPalGetForeColor(
AEGP_ColorVal *fore_colorP);
|
|
Retrieves the background color from the paint palette. AEGP_PaintPalGetBackColor(
AEGP_ColorVal *back_colorP);
|
|
Sets the foreground color in the paint palette. AEGP_PaintPalSetForeColor(
const AEGP_ColorVal *fore_colorP);
|
|
Sets the background color in the paint palette. AEGP_PaintPalSetBackColor(
const AEGP_ColorVal *back_colorP);
|
|
Retrieves the fill color from the character palette. AEGP_CharPalGetFillColor(
A_Boolean *is_fcolor_definedPB,
AEGP_ColorVal *fill_colorP);
|
|
Retrieves the stroke color from the character palette. AEGP_CharPalGetStrokeColor(
A_Boolean *is_scolor_definedPB,
AEGP_ColorVal *stroke_colorP);
|
|
Sets the fill color in the character palette. AEGP_CharPalSetFillColor(
const AEGP_ColorVal *fill_colorP);
|
|
Sets the stroke color in the character palette. AEGP_CharPalSetStrokeColor(
const AEGP_ColorVal *stroke_colorP);
|
|
Returns whether or not the fill color is frontmost. If it isn’t, the stroke color is frontmost. AEGP_CharPalIsFillColorUIFrontmost(
A_Boolean *is_fcolor_selectedPB);
|
|
Returns an AEGP_ConvertFpLongToHSFRatio(
A_FpLong numberF,
A_Ratio *ratioPR);
|
|
Returns an AEGP_ConvertHSFRatioToFpLong(
A_Ratio ratioR,
A_FpLong *numberPF);
|
|
This routine is safe to call from threads other than the main thread. It is asynchronous and will return before the idle handler is called. The suite functions to get this function pointer are not thread safe; save it off in the main thread for use by the child thread. AEGP_CauseIdleRoutinesToBeCalled(void);
|
|
Returns whether After Effects is running without a user interface. AEGP_GetSuppressInteractiveUI(
A_Boolean *ui_is_suppressedPB);
|
|
Sends a string to the OS console. AEGP_WriteToOSConsole(
const A_char *textZ);
|
|
Writes a message to the debug log, or to the OS command line if After Effects was launched with the “-debug” option. AEGP_WriteToDebugLog(
const A_char *subsystemZ,
const A_char *event_typeZ,
const A_char *infoZ);
|
|
Retrieves the last error message displayed to the user, and its associated error number. Pass in the size of the character buffer to be returned. AEGP_GetLastErrorMessage(
A_long buffer_size,
A_char *error_string,
A_Err *error_num);
|
|
Returns AEGP_IsScriptingAvailable(
A_Boolean *outAvailablePB);
|
|
Have After Effects execute a script. The script passed in can be in either UTF-8 or the current application encoding (if platform_encodingB is passed in as TRUE). The two out arguments are optional. The value of the last line of the script is what is passed back in outResultPH0. AEGP_ExecuteScript(
AEGP_PluginID inPlugin_id,
const A_char *inScriptZ,
const A_Boolean platform_encodingB,
AEGP_MemHandle *outResultPH0,
AEGP_MemHandle *outErrStringPH0);
|
|
Returns TRUE if the user has successfully activated After Effects. AEGP_HostIsActivated(
A_Boolean *is_activatedPB);
|
|
On macOS, returns a AEGP_GetPluginPlatformRef(
AEGP_PluginID plug_id,
void **plat_refPPV);
|
|
Rescans the system font list. AEGP_UpdateFontList();
|
|
New in CC. Returns a particular path associated with the plug-in:
AEGP_GetPluginPaths(
AEGP_PluginID aegp_plugin_id,
AEGP_GetPathTypes path_type
AEGP_MemHandle *unicode_pathPH);
|
Persistent Data Suite¶
Plug-ins have read and write access to persistent data in After Effects’ preferences. AEGPs may add and manage their own persistent data using the following suite. The data entries are accessed by (section key, value key) pairs. It is recommended that plug-ins use their matchname as their section key, or as a prefix if using multiple section keys.
The available data types are A_long, A_FpLong, strings, and void*. A_FpLongs are stored with 6 decimal places of precision. There is no provision for specifying a different precision. String data supports the full 8-bit space. Only 0x00 is reserved for string ending. This makes them ideal for storing UTF-8 encoded strings, ISO 8859-1, and plain ASCII. Both section keys and value keys are of this type. For data types not represented by the simple data types provided, use data handles containing your custom data. void* unstructured data allows you to store any kind of data. You must pass in a size in bytes along with the data.
When calling any of the functions to retrieve the value of a key, if a given key is not found, the default value is both written to the blob and returned as the value; if no default is provided, a blank value will be written and returned.
Note that this data is stored in the application’s preferences, not in the project. As of 6.5, there is no way to store opaque AEGP-generated data in an After Effects project.
After Effects can handle plug-ins which change the preferences during their application; it checks the in-RAM copy of the prefs before acting upon pref-able settings, rather than relying on the saved prefs. It’s like we planned this, or something!
AEGP_PersistentDateSuite4¶
Function |
Purpose |
|---|---|
|
Obtains the handle to all persistent application data. Modifying this will modify the application. The
AEGP_GetApplicationBlob(
AEGP_PersistentType blob_type,
AEGP_PersistentBlobH *blobPH);
|
|
Obtains the number of sections in the application blob. AEGP_GetNumSections(
AEGP_PersistentBlobH blobH,
A_long *num_sectionPL);
|
|
Obtains the key at the given index. AEGP_GetSectionKeyByIndex(
AEGP_PersistentBlobH blobH,
A_long section_index,
A_long max_section_size,
A_char *section_keyZ);
|
|
Returns whether or not a given key/value pair exists with the blob. AEGP_DoesKeyExist(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
A_Boolean *existsPB);
|
|
Retrieves the number of value keys in the section. AEGP_GetNumKeys(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
A_long *num_keysPL);
|
|
Retrieves the value of the indexed key. AEGP_GetValueKeyByIndex(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
A_long key_index,
A_long max_key_size,
A_char *value_keyZ);
|
Note
For the functions below, if a given key is not found, the default value is both written to the blob and returned as the value; if no default is provided, a blank value will be written and returned.
Function |
Purpose |
|---|---|
|
Obtains the value associated with the given section’s key. If using in-memory data structures, watch for endian issues. AEGP_GetDataHandle(
AEGP_PluginID plugin_id,
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
AEGP_MemHandle defaultH0,
AEGP_MemHandle *valuePH);
|
|
Obtains the data located at a given section’s value. AEGP_GetData(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
A_u_long data_sizeLu,
const void *defaultPV0,
void *bufPV);
|
|
Obtains the string for a given section key’s value (and indicates its length in AEGP_GetString(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
const A_char *defaultZ0,
A_u_long buf_sizeLu,
char *bufZ,
A_u_long *actual_szLu0);
|
|
Obtains the AEGP_GetLong(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
A_long defaultL,
A_long *valuePL);
|
|
Obtains the AEGP_GetFpLong(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
A_FpLong defaultF,
A_FpLong *valuePF);
|
|
New in CC. Obtains the AEGP_GetTime(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
const A_Time *defaultPT0,
A_Time *valuePT);
|
|
New in CC. Obtains the AEGP_GetARGB(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
const PF_PixelFloat *defaultP0,
PF_PixelFloat *valueP);
|
|
Sets the given section key’s value to the handle passed in. AEGP_SetDataHandle(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
const AEGP_MemHandle valueH);
|
|
Sets the given section key’s value to the data contained in AEGP_SetData(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
A_u_long data_sizeLu,
const void *dataPV);
|
|
Sets the given section key’s string to AEGP_SetString(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
const A_char *strZ);
|
|
Sets the given section key’s value to AEGP_SetLong(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
A_long valueL);
|
|
Sets the given section key’s value to AEGP_SetFpLong(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
A_FpLong valueF);
|
|
New in CC. Sets the given section key’s value to AEGP_SetTime(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
A_Time *valuePT);
|
|
New in CC. Sets the given section key’s value to AEGP_SetARGB(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ,
PF_PixelFloat *valueP);
|
|
Removes the given section’s value from the blob. AEGP_DeleteEntry(
AEGP_PersistentBlobH blobH,
const A_char *section_keyZ,
const A_char *value_keyZ);
|
|
Get the path to the folder containing After Effects’ preference file.
The path is a handle to a NULL-terminated A_UTF16Char string, and must be disposed with AEGP_GetPrefsDirectory(
AEGP_MemHandle *unicode_pathPH);
|
Color Management¶
We’ve provided a function so AEGPs can obtain information on After Effects’ current color management settings.
AEGP_ColorSettingsSuite5¶
Function |
Purpose |
|---|---|
|
Retrieves the current opaque AEGP_GetBlendingTables(
PR_RenderContextH render_contextH,
PF_EffectBlendingTables *blending_tables);
|
|
Returns whether there is a colorspace transform applied to the current item view. AEGP_DoesViewHaveColorSpaceXform(
AEGP_ItemViewP viewP,
A_Boolean *has_xformPB);
|
|
Changes the view colorspace of the source to be the working colorspace of the destination. Source and destination can be the same. AEGP_XformWorkingToViewColorSpace(
AEGP_ItemViewP viewP,
AEGP_WorldH srcH,
AEGP_WorldH dstH);
|
|
Retrieves the opaque current working space ICC profile. Must be disposed. The “New” in the name does not indicate that you’re making up a new profile; rather, it’s part of our function naming standard; anything with “New” in the name allocates something which the caller must dispose. AEGP_GetNewWorkingSpaceColorProfile(
AEGP_PluginID aegp_plugin_id,
AEGP_MemHandle *icc_profPH);
|
|
Retrieves a new AEGP_GetNewColorProfile FromICCProfile(
AEGP_PluginID aegp_plugin_id,
A_long icc_sizeL,
const void *icc_dataPV,
AEGP_ColorProfileP *profilePP);
|
|
Retrieves a new ICC profile (stored in an AEGP_GetNewICCProfile FromColorProfile(
AEGP_PluginID plugin_id,
AEGP_ConstColorProfileP profileP,
AEGP_MemHandle *profilePH);
|
|
Returns a textual description of the specified color profile. Text will be a null-terminated UTF16 string, which must be disposed by the caller. AEGP_GetNewColorProfileDescription(
AEGP_PluginID aegp_plugin_id,
AEGP_ConstColorProfileP profileP,
AEGP_MemHandle *unicode_descPH);
|
|
Disposes of a color profile, obtained using other functions in this suite. AEGP_DisposeColorProfile(
AEGP_ColorProfileP profileP);
|
|
Returns a floating point number approximating the gamma setting used by the specified color profile. AEGP_GetColorProfileApproximateGamma(
AEGP_ConstColorProfileP profileP,
A_FpShort *approx_gammaP);
|
|
Returns whether the specified color profile is RGB. AEGP_IsRGBColorProfile(
AEGP_ConstColorProfileP profileP,
A_Boolean *is_rgbPB);
|
|
Sets the working space to the passed color profile. AEGP_SetWorkingColorSpace(
AEGP_PluginID aegp_plugin_id,
AEGP_CompH compH,
AEGP_ConstColorProfileP color_profileP);
|
|
Check if the current project is using the OCIO color engine or not. Returns true if current project uses OCIO color managed mode. AEGP_IsOCIOColorManagementUsed(
AEGP_PluginID aegp_plugin_id,
A_Boolean *is_OCIOColorManagementUsedPB);
|
|
Returns the OCIO configuration file used by the project. Returned config_filePH is a handle of AEGP_GetOCIOConfigurationFile(
AEGP_PluginID aegp_plugin_id,
AEGP_MemHandle *congif_filePH);
|
|
Returns the absolute file path to the OCIO configuration used by the project The returned config_filePH is a handle of AEGP_GetOCIOConfigurationFilePath(
AEGP_PluginID aegp_plugin_id,
AEGP_MemHandle *congif_filePH);
|
|
Returns the working color space of the project in OCIO mode. The returned ocio_working_colorspaceH is a handle of AEGPD_GetOCIOWorkingColorSpace(
AEGP_PluginID aegp_plugin_id,
AEGP_MemHandle *ocio_working_colorspaceH);
|
|
Returns the Display and View transforms used by the project. The returned ocio_displayH and ocio_viewH are handles of AEGPD_GetOCIODisplayColorSpace(
AEGP_PluginID aegp_plugin_id,
AEGP_MemHandle *ocio_displayH,
AEGP_MemHandle *ocio_viewH);
|
Render Suites¶
Since we introduced the AEGP API, we’ve been asked to provide functions for retrieving rendered frames.
These function suites allows you to do just that.
First, specify what you want rendered in the AEGP_RenderOptionsSuite4 or AEGP_LayerRenderOptionsSuite1.
Then do the rendering with AEGP_RenderSuite4.
AEGP_RenderOptionsSuite4¶
Function |
Purpose |
|---|---|
|
Returns the AEGP_NewFromItem(
AEGP_PluginID plugin_id,
AEGP_ItemH itemH,
AEGP_RenderOptionsH *optionsPH);
|
|
Duplicates an AEGP_Duplicate(
AEGP_PluginID plugin_id,
AEGP_RenderOptionsH optionsH,
AEGP_RenderOptionsH *copyPH);
|
|
Deletes an AEGP_Dispose(
AEGP_RenderOptionsH optionsH);
|
|
Sets the render time of an AEGP_SetTime(
AEGP_RenderOptionsH optionsH,
A_Time time);
|
|
Retrieves the render time of the given AEGP_GetTime(
AEGP_RenderOptionsH optionsH,
A_Time *timeP);
|
|
Specifies the time step (duration of a frame) for the referenced AEGP_SetTimeStep(
AEGP_RenderOptionsH optionsH,
A_Time time_step);
|
|
Retrieves the time step (duration of a frame) for the given AEGP_GetTimeStep(
AEGP_RenderOptionsH optionsH,
A_Time *timePT);
|
|
Specifies the field settings for the given AEGP_SetFieldRender(
AEGP_RenderOptionsH optionsH,
PF_Field field_render);
|
|
Retrieves the field settings for the given AEGP_GetFieldRender(
AEGP_RenderOptionsH optionsH,
PF_Field *field_renderP);
|
|
Specifies the AEGP_WorldType of the output of a given AEGP_SetWorldType(
AEGP_RenderOptionsH optionsH,
AEGP_WorldType type);
|
|
Retrieves the AEGP_GetWorldType(
AEGP_RenderOptionsH optionsH,
AEGP_WorldType *typeP);
|
|
Specifies the downsample factor (with independent horizontal and vertical settings) for the given AEGP_SetDownsampleFactor(
AEGP_RenderOptionsH optionsH,
A_short x,
A_short y);
|
|
Retrieves the downsample factor for the given AEGP_GetDownsampleFactor(
AEGP_RenderOptionsH optionsH,
A_short *xP,
A_short *yP);
|
|
Specifies the region of interest sub-rectangle for the given AEGP_SetRegionOfInterest(
AEGP_RenderOptionsH optionsH,
const A_LRect *roiP)
|
|
Retrieves the region of interest sub-rectangle for the given AEGP_GetRegionOfInterest(
AEGP_RenderOptionsH optionsH,
A_LRect *roiP);
|
|
Specifies the AEGP_SetMatteMode(
AEGP_RenderOptionsH optionsH,
AEGP_MatteMode mode);
|
|
Retrieves the AEGP_GetMatteMode(
AEGP_RenderOptionsH optionsH,
AEGP_MatteMode *modeP);
|
|
Gets the AEGP_GetChannelOrder(
AEGP_RenderOptionsH optionsH,
AEGP_ChannelOrder *orderP);
Factoid: this was added to facilitate live linking with Premiere Pro. |
|
Sets the AEGP_SetChannelOrder(
AEGP_RenderOptionsH optionsH,
AEGP_ChannelOrder order);
|
|
Passes back a boolean that is true if the render guide layers setting is on. AEGP_GetRenderGuideLayers)(
AEGP_RenderOptionsH optionsH,
A_Boolean *will_renderPB);
|
|
Specify whether or not to render guide layers. AEGP_SetRenderGuideLayers)(
AEGP_RenderOptionsH optionsH,
A_Boolean render_themB);
|
|
Get the render quality of the render queue item.
Quality can be either AEGP_GetRenderQuality)(
AEGP_RenderOptionsH optionsH,
AEGP_ItemQuality *qualityP);
|
|
Set the render quality of the render queue item. AEGP_GetRenderQuality)(
AEGP_RenderOptionsH optionsH,
AEGP_ItemQuality quality);
|
AEGP_LayerRenderOptionsSuite1¶
Note
New in 13.0
Function |
Purpose |
|---|---|
|
Returns the AEGP_NewFromLayer(
AEGP_PluginID plugin_id,
AEGP_LayerH layerH,
AEGP_LayerRenderOptionsH *optionsPH);
|
|
Returns the AEGP_NewFromUpstreamOfEffect(
AEGP_PluginID plugin_id,
AEGP_EffectRefH effectH,
AEGP_LayerRenderOptionsH *optionsPH);
|
|
Duplicates an AEGP_Duplicate(
AEGP_PluginID plugin_id,
AEGP_LayerRenderOptionsH optionsH,
AEGP_LayerRenderOptionsH *copyPH);
|
|
Deletes an AEGP_Dispose(
AEGP_LayerRenderOptionsH optionsH);
|
|
Sets the render time of an AEGP_SetTime(
AEGP_LayerRenderOptionsH optionsH,
A_Time time);
|
|
Retrieves the render time of the given AEGP_GetTime(
AEGP_LayerRenderOptionsH optionsH,
A_Time *timeP);
|
|
Specifies the time step (duration of a frame) for the referenced AEGP_SetTimeStep(
AEGP_LayerRenderOptionsH optionsH,
A_Time time_step);
|
|
Retrieves the time step (duration of a frame) for the given AEGP_GetTimeStep(
AEGP_LayerRenderOptionsH optionsH,
A_Time *timePT);
|
|
Specifies the AEGP_WorldType of the output of a given AEGP_SetWorldType(
AEGP_LayerRenderOptionsH optionsH,
AEGP_WorldType type);
|
|
Retrieves the AEGP_WorldType of the given AEGP_GetWorldType(
AEGP_LayerRenderOptionsH optionsH,
AEGP_WorldType *typeP);
|
|
Specifies the downsample factor (with independent horizontal and vertical settings) for the given AEGP_SetDownsampleFactor(
AEGP_LayerRenderOptionsH optionsH,
A_short x,
A_short y);
|
|
Retrieves the downsample factor for the given AEGP_GetDownsampleFactor(
AEGP_LayerRenderOptionsH optionsH,
A_short *xP,
A_short *yP);
|
|
Specifies the AEGP_MatteMode for the given AEGP_SetMatteMode(
AEGP_LayerRenderOptionsH optionsH,
AEGP_MatteMode mode);
AEGP_MatteMode will be one of the following:
|
|
Retrieves the AEGP_MatteMode for the given AEGP_GetMatteMode(
AEGP_LayerRenderOptionsH optionsH,
AEGP_MatteMode *modeP);
|
AEGP_RenderSuite4¶
Function |
Purpose |
|---|---|
|
Retrieves an Create the Optionally, the AEGP can pass a function to be called by After Effects if the user cancels the current render, as well as a refcon (constant reference to opaque data) for use during that function. AEGP_RenderAndCheckoutFrame(
AEGP_RenderOptionsH optionsH,
AEGP_RenderSuiteCheckForCancel cancel_functionP0,
AEGP_CancelRefcon cancel_function_refconP0,
AEGP_FrameReceiptH *receiptPH);
|
|
New in CC 2014. This allows frame checkout of a layer with effects applied at non-render time. This is useful for an operation that requires the frame, for example, when a button is clicked and it is acceptable to wait for a moment while it is rendering. Note: Since it is not asynchronous, it will not solve the general problem where custom UI needs to draw based on the frame. Retrieves an Create the You can actually use Optionally, the AEGP can pass a function to be called by After Effects if the user cancels the current render, as well as a refcon (constant reference to opaque data) for use during that function. AEGP_RenderAndCheckoutLayerFrame(
AEGP_LayerRenderOptionsH optionsH,
A_Boolean render_plain_layer_frameB,
AEGP_RenderSuiteCheckForCancel cancel_functionP0,
AEGP_CancelRefcon cancel_function_refconP0,
AEGP_FrameReceiptH *receiptPH);
|
|
Call this function as soon as your AEGP is done accessing the frame. After Effects makes caching decisions based on which frames are checked out, so don’t hog them! AEGP_CheckinFrame(
AEGP_FrameReceiptH receiptH);
|
|
Retrieves the pixels ( AEGP_GetReceiptWorld(
AEGP_FrameReceiptH receiptH,
AEGP_WorldH *worldPH);
|
|
Retrieves an AEGP_GetRenderedRegion(
AEGP_FrameReceiptH receiptH,
A_LRect *regionP);
|
|
Given two sets of AEGP_IsRenderedFrameSufficient(
AEGP_RenderOptionsH rendered_optionsH,
AEGP_RenderOptionsH proposed_optionsH,
A_Boolean *is_sufficientPB);
|
|
Obtains an AEGP_RenderNewItemSoundData(
AEGP_ItemH itemH,
const A_Time *start_timePT,
const A_Time *durationPT,
const AEGP_SoundDataFormat *formatP,
AEGP_SoundDataH *new_dataPH);
NOTE: This function, if called as part of |
|
Retrieves the current AEGP_GetCurrentTimestamp(
AEGP_TimeStamp *time_stampP);
|
|
Returns whether the video of an AEGP_ItemH has changed since the given Note: this does not track changes in audio. AEGP_HasItemChangedSinceTimestamp(
AEGP_ItemH itemH,
const A_Time *start_timeP,
const A_Time *durationP,
const AEGP_TimeStamp *time_stampP,
A_Boolean *changedPB);
|
|
Returns whether this frame would be worth rendering externally and checking in to the cache.
A speculative renderer should check this twice: before sending the frame out to render and when it is complete,
before calling This function is to be used with AEGP_IsItemWorthwhileToRender(
AEGP_RenderOptionsH roH,
const AEGP_TimeStamp *time_stampP,
A_Boolean *worthwhilePB);
|
|
Provide a rendered frame ( AEGP_CheckinRenderedFrame(
AEGP_RenderOptionsH roH,
const AEGP_TimeStamp* time_stampP,
A_u_long ticksL,
AEGP_PlatformWorldH imageH);
|
|
New in CS6. Retrieve a GUID for a rendered frame. The memory handle passed back must be disposed. AEGP_GetReceiptGuid(
AEGP_FrameReceiptH receiptH,
AEGP_MemHandle *guidMH)
|
The AEGP_World As We Know It¶
AEGP_Worlds are the common format used throughout the AEGP APIs to describe frames of pixels.
AEGP_WorldSuite3¶
Function |
Purpose |
|---|---|
|
Returns an allocated, initialized AEGP_New(
AEGP_PluginID plugin_id,
AEGP_WorldType type,
A_long widthL,
A_long heightL,
AEGP_WorldH *worldPH);
|
|
Disposes of an AEGP_Dispose(
AEGP_WorldH worldH);
|
|
Returns the type of a given AEGP_GetType(
AEGP_WorldH worldH,
AEGP_WorldType **typeP);
AEGP_WorldType will be one of the following:
|
|
Returns the width and height of the given AEGP_GetSize(
AEGP_WorldH worldH,
A_long *widthPL,
A_long *heightPL);
|
|
Returns the rowbytes for the given AEGP_GetRowBytes(
AEGP_WorldH worldH,
A_u_long *row_bytesPL);
|
|
Returns the base address of the AEGP_GetBaseAddr8(
AEGP_WorldH worldH,
PF_Pixel8 **base_addrP);
|
|
Returns the base address of the AEGP_GetBaseAddr16(
AEGP_WorldH worldH,
PF_Pixel16 **base_addrP);
|
|
Returns the base address of the AEGP_GetBaseAddr32(
AEGP_WorldH worldH,
PF_PixelFloat **base_addrP);
|
|
Populates and returns a PF_EffectWorld representing the given NOTE: This does not give your plug-in ownership of the world referenced; destroy the source AEGP_FillOutPFEffectWorld(
AEGP_WorldH worldH,
PF_EffectWorld *pf_worldP);
|
|
Performs a fast blur on a given AEGP_FastBlur(
A_FpLong radiusF,
PF_ModeFlags mode,
PF_Quality quality,
AEGP_WorldH worldH);
|
|
Creates a new AEGP_NewPlatformWorld(
AEGP_PluginID plugin_id,
AEGP_WorldType type,
A_long widthL,
A_long heightL,
AEGP_PlatformWorldH *worldPH);
|
|
Disposes of an AEGP_DisposePlatformWorld(
AEGP_PlatformWorldH worldH);
|
|
Retrieves an AEGP_WorldH referring to the given NOTE: This doesn’t allocate a new world, it simply provides a reference to an existing one. AEGP_NewReferenceFromPlatformWorld(
AEGP_PluginID plugin_id,
AEGP_PlatformWorldH plat_worldH,
AEGP_WorldH *worldPH);
|
Track Mattes and Transform Functions¶
Use the AEGP_CompositeSuite to copy pixel worlds, operate on track mattes, and apply transfer functions.
AEGP_CompositeSuite2¶
Function |
Purpose |
|---|---|
|
For the given AEGP_ClearAlphaExceptRect(
A_Rect *clipped_dst_rectPR,
PF_EffectWorld *dstP);
|
|
Mattes the pixels in a NOTE: Unlike most of the other pixel mangling functions provided by After Effects, this one doesn’t take AEGP_PrepTrackMatte(
A_long num_pix,
A_Boolean deepB,
const PF_Pixel *src_mask,
PF_MaskFlags mask_flags,
PF_Pixel *dst_mask);
|
|
Blends two AEGP_TransferRect(
PF_Quality quality,
PF_ModeFlags m_flags,
PF_Field field,
const A_Rect *src_rec,
const PF_EffectWorld *src_world,
const PF_CompositeMode *comp_mode,
PF_EffectBlendingTables blend_tablesP0,
const PF_MaskWorld *mask_world0,
A_long dest_x,
A_long dest_y,
PF_EffectWorld *dst_world);
|
|
Copies a rectangle of pixels (pass a AEGP_CopyBits_LQ(
PF_EffectWorld *src_worldP,
A_Rect *src_r,
A_Rect *dst_r,
PF_EffectWorld *dst_worldP);
|
|
Copies a rectangle of pixels (pass a AEGP_CopyBits_HQ_Straight(
PF_EffectWorld *src,
A_Rect *src_r,
A_Rect *dst_r,
PF_EffectWorld *dst);
|
|
Copies a rectangle of pixels (pass a AEGP_CopyBits_HQ_Premul(
PF_EffectWorld *src,
A_Rect *src_r,
A_Rect *dst_r,
PF_EffectWorld *dst);
|
Work With Audio¶
AEGP_SoundDataSuite allows AEGPs to obtain and manipulate the audio associated with compositions and footage items.
Audio-only items may be added to the render queue using AEGP_RenderNewItemSoundData().
AEGP_SoundDateSuite1¶
Function |
Purpose |
|---|---|
|
Creates a new AEGP_NewSoundData(
const AEGP_SoundDataFormat *formatP,
AEGP_SoundDataH *new_dataPH);
|
|
Frees an AEGP_DisposeSoundData(
AEGP_SoundDataH sound_dataH);
|
|
Obtains information about the format of a given AEGP_GetSoundDataFormat(
AEGP_SoundDataH soundH,
AEGP_SoundDataFormat *formatP);
|
|
Locks the AEGP_LockSoundDataSamples(
AEGP_SoundDataH soundH,
void **samples);
|
|
Unlocks an AEGP_UnlockSoundDataSamples(
AEGP_SoundDataH soundH);
|
|
Obtains the number of samples in the given AEGP_GetNumSamples(
AEGP_SoundDataH soundH,
A_long *numsamplesPL);
|
Audio Settings¶
Audio render settings are represented using the AEGP_SoundDataFormat.
struct AEGP_SoundDataFormat {
A_FpLong sample_rateF;
AEGP_SoundEncoding encoding;
A_long bytes_per_sampleL;
A_long num_channelsL; // 1 for mono, 2 for stereo
} AEGP_SoundDataFormat;
bytes_per_sampleL is always either 1, 2, or 4, and is ignored if float encoding is specified.
AEGP_SoundEncoding is one of the following:
AEGP_SoundEncoding_UNSIGNED_PCM
AEGP_SoundEncoding_SIGNED_PCM
AEGP_SoundEncoding_FLOAT
Render Queue Suite¶
This suite allows AEGPs to add items the to render queue (using default options), and control the basic state of the render queue.
AEGP_RenderQueueSuite1¶
Function |
Purpose |
|---|---|
|
Adds a composition to the render queue, using default options. AEGP_AddCompToRenderQueue(
AEGP_CompH compH,
const A_char* pathZ);
|
|
Sets the render queue to one of three valid states. It is not possible to go from stopped to paused. AEGP_SetRenderQueueState(
AEGP_RenderQueueState state);
|
|
Obtains the current render queue state. AEGP_GetRenderQueueState(
AEGP_RenderQueueState *stateP);
|
Render Queue Item Suite¶
Manipulate all aspects of render queue items using this suite.
AEGP_RQItemSuite4¶
Function |
Purpose |
|---|---|
|
Returns the number of items currently in the render queue. AEGP_GetNumRQItems(
A_long *num_itemsPL);
|
|
Returns an AEGP_GetRQItemByIndex(
A_long rq_item_index,
AEGP_RQItemRefH *rq_item_refPH);
|
|
Returns the next AEGP_GetNextRQItem(
AEGP_RQItemRefH current_rq_itemH,
AEGP_RQItemRefH *next_rq_itemPH);
|
|
Returns the number of output modules applied to the given AEGP_GetNumOutputModulesForRQItem(
AEGP_RQItemRefH rq_itemH,
A_long *num_outmodsPL);
|
|
Returns TRUE if the AEGP_GetRenderState(
AEGP_RQItemRefH rq_itemH,
A_Boolean *will_renderPB);
|
|
Controls whether or not the This function will return:
AEGP_SetRenderState(
AEGP_RQItemRefH rq_itemH,
A_Boolean renderB);
|
|
Returns the time (in seconds, since 1904) that rendering began. AEGP_GetStartedTime(
AEGP_RQItemRefH rq_itemH,
A_Time *started_timePT);
|
|
Returns the time elapsed since rendering began. AEGP_GetElapsedTime(
AEGP_RQItemRefH rq_itemH,
A_Time *render_timePT);
|
|
Returns the log type for the referenced AEGP_GetLogType(
AEGP_RQItemRefH rq_itemH,
AEGP_LogType *logtypeP);
|
|
Specifies the log type to be used with the referenced AEGP_SetLogType(
AEGP_RQItemRefH rq_itemH,
AEGP_LogType logtype);
|
|
Removes the specified output module from the referenced AEGP_RemoveOutputModule(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH);
|
|
Updated to support Unicode in AEGP_GetComment(
AEGP_RQItemRefH rq_itemH,
AEGP_MemHandle *unicodeH);
|
|
Updated to support Unicode in AEGP_SetComment(
AEGP_RQItemRefH rq_itemH,
const A_UTF16Char *commentZ);
|
|
Retrieves the AEGP_GetCompFromRQItem(
AEGP_RQItemRefH rq_itemH,
AEGP_CompH *compPH);
|
|
Deletes the render queue item. Undoable. AEGP_DeleteRQItem(
AEGP_RQItemRefH rq_itemH);
|
Render Queue Monitor Suite¶
New in CS6. This suite provides all the info a render queue manager needs to figure out what is happening at any point in a render.
AEGP_RenderQueueMonitorSuite1¶
Function |
Purpose |
|---|---|
|
Register a set of plug-in-defined functions to be called by the render queue.
Use the refcon to pass in data that you want to use later on when your plug-in-defined functions in AEGP_RegisterListener(
AEGP_PluginID aegp_plugin_id,
AEGP_RQM_Refcon aegp_refconP,
const AEGP_RQM_FunctionBlock1 *fcn_blockP);
The struct _AEGP_RQM_FunctionBlock1 {
A_Err (*AEGP_RQM_RenderJobStarted)(
AEGP_RQM_BasicData *basic_dataP,
AEGP_RQM_SessionId jobid);
A_Err (*AEGP_RQM_RenderJobEnded)(
AEGP_RQM_BasicData *basic_dataP,
AEGP_RQM_SessionId jobid);
A_Err (*AEGP_RQM_RenderJobItemStarted)(
AEGP_RQM_BasicData *basic_dataP,
AEGP_RQM_SessionId jobid,
AEGP_RQM_ItemId itemid);
A_Err (*AEGP_RQM_RenderJobItemUpdated)(
AEGP_RQM_BasicData *basic_dataP,
AEGP_RQM_SessionId jobid,
AEGP_RQM_ItemId itemid,
AEGP_RQM_FrameId frameid);
A_Err (*AEGP_RQM_RenderJobItemEnded)(
AEGP_RQM_BasicData *basic_dataP,
AEGP_RQM_SessionId jobid,
AEGP_RQM_ItemId itemid,
AEGP_RQM_FinishedStatus fstatus);
A_Err (*AEGP_RQM_RenderJobItemReportLog)(
AEGP_RQM_BasicData *basic_dataP,
AEGP_RQM_SessionId jobid,
AEGP_RQM_ItemId itemid,
A_Boolean isError,
AEGP_MemHandle logbuf);
} AEGP_RQM_FunctionBlock1;
The AEGP_RQM_BasicData is defined below. struct _AEGP_RQM_BasicData {
const struct SPBasicSuite *pica_basicP;
A_long aegp_plug_id;
AEGP_RQM_Refcon aegp_refconPV;
} AEGP_RQM_BasicData;
|
|
Deregister from the render queue. AEGP_DeregisterListener(
AEGP_PluginID aegp_plugin_id,
AEGP_RQM_Refcon aegp_refconP);
|
|
Obtain the current project name.
The project name is a handle to a NULL-terminated A_UTF16Char string, and must be disposed with AEGP_GetProjectName(
AEGP_RQM_SessionId sessid,
AEGP_MemHandle *utf_project_namePH0);
|
|
Obtain the app version.
The app version is a handle to a NULL-terminated A_UTF16Char string, and must be disposed with AEGP_GetAppVersion(
AEGP_RQM_SessionId sessid,
AEGP_MemHandle *utf_app_versionPH0);
|
|
Obtain the number of job items. AEGP_GetNumJobItems(
AEGP_RQM_SessionId sessid,
A_long *num_jobitemsPL);
|
|
Get the job with the index specified. AEGP_GetJobItemID(
AEGP_RQM_SessionId sessid,
A_long jobItemIndex,
AEGP_RQM_ItemId *jobItemID);
|
|
Get the number of render settings for the job with the index specified. AEGP_GetNumJobItemRenderSettings(
AEGP_RQM_SessionId sessid,
AEGP_RQM_ItemId itemid,
A_long *num_settingsPL);
|
|
Get a specific render setting of a specific job.
The setting name and value are handles to NULL-terminated A_UTF16Char strings, and must be disposed with AEGP_GetJobItemRenderSetting(
AEGP_RQM_SessionId sessid,
AEGP_RQM_ItemId itemid,
A_long settingIndex,
AEGP_MemHandle *utf_setting_namePH0,
AEGP_MemHandle *utf_setting_valuePH0);
|
|
Get the number of output modules for the job with the index specified. AEGP_GetNumJobItemOutputModules(
AEGP_RQM_SessionId sessid,
AEGP_RQM_ItemId itemid,
A_long *num_outputmodulesPL);
|
|
Get the number of settings for the output module with the index specified. AEGP_GetNumJobItemOutputModuleSettings(
AEGP_RQM_SessionId sessid,
AEGP_RQM_ItemId itemid,
A_long outputModuleIndex,
A_long *num_settingsPL);
|
|
Get a specific setting of a job item output module.
The setting name and value are handles to NULL-terminated A_UTF16Char strings, and must be disposed with AEGP_GetJobItemOutputModuleSetting(
AEGP_RQM_SessionId sessid,
AEGP_RQM_ItemId itemid,
A_long outputModuleIndex,
A_long settingIndex,
AEGP_MemHandle *utf_setting_namePH0,
AEGP_MemHandle *utf_setting_valuePH0);
|
|
Get the number of output module warnings for a job item. AEGP_GetNumJobItemOutputModuleWarnings(
AEGP_RQM_SessionId sessid,
AEGP_RQM_ItemId itemid,
A_long outputModuleIndex,
A_long *num_warningsPL);
|
|
Get a specific warning of a specific output module for a specific job item.
The warning value is a handle to NULL-terminated A_UTF16Char string, and must be disposed with AEGP_GetJobItemOutputModuleWarning(
AEGP_RQM_SessionId sessid,
AEGP_RQM_ItemId itemid,
A_long outputModuleIndex,
A_long warningIndex,
AEGP_MemHandle *utf_warning_valuePH0);
|
|
Get the number of properties for a job item frame. AEGP_GetNumJobItemFrameProperties(
AEGP_RQM_SessionId sessid,
AEGP_RQM_ItemId itemid,
AEGP_RQM_FrameId frameid,
A_long *num_propertiesPL);
|
|
Get a specific property on a job item frame.
The property name and values are handle to NULL-terminated A_UTF16Char strings, and must be disposed with AEGP_GetJobItemFrameProperty(
AEGP_RQM_SessionId sessid,
AEGP_RQM_ItemId itemid,
AEGP_RQM_FrameId frameid,
A_long propertyIndex,
AEGP_MemHandle *utf_property_namePH0,
AEGP_MemHandle *utf_property_valuePH0);
|
|
Get the number of properties for a job item output module. AEGP_GetNumJobItemOutputModuleProperties(
AEGP_RQM_SessionId sessid,
AEGP_RQM_ItemId itemid,
A_long outputModuleIndex,
A_long *num_propertiesPL);
|
|
Get a specific property off a job item output module.
The property name and values are handle to NULL-terminated A_UTF16Char strings, and must be disposed with AEGP_GetJobItemOutputModuleProperty(
AEGP_RQM_SessionId sessid,
AEGP_RQM_ItemId itemid,
A_long outputModuleIndex,
A_long propertyIndex,
AEGP_MemHandle *utf_property_namePH0,
AEGP_MemHandle *utf_property_valuePH0);
|
|
Get a buffer with a JPEG-encoded thumbnail of the job item frame. Pass in the maximum width and height, and the actual dimensions will be passed back. AEGP_GetJobItemFrameThumbnail(
AEGP_RQM_SessionId sessid,
AEGP_RQM_ItemId itemid,
AEGP_RQM_FrameId frameid,
A_long *widthPL,
A_long *heightPL,
AEGP_MemHandle *thumbnailPH0);
|
Output Module Suite¶
Every item in the render queue has at least one output module specified.
Use this suite to query and control all aspects of the output modules attached to a given render item.
You may also add and remove output modules.
Factoid: For each frame rendered for a given render item, the list of output modules is traversed. So, for frame 0, output module 0, then 1, then 2 are called.
AEGP_OutputModuleSuite4¶
Function |
Purpose |
|---|---|
|
Retrieves the indexed output module. NOTE: AEGP_GetOutputModuleByIndex(
AEGP_RQItemRefH rq_itemH,
A_long outmod_indexL,
AEGP_OutputModuleRefH *outmodPH);
|
|
Retrieves the embedding setting specified for the referenced AEGP_GetEmbedOptions(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
AEGP_EmbeddingType *embed_optionsP);
|
|
Specifies the embedding setting for the referenced AEGP_SetEmbedOptions(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
AEGP_EmbeddingType embed_options);
|
|
Retrieves the post-render action setting for the referenced AEGP_GetPostRenderAction(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
AEGP_PostRenderAction *actionP);
|
|
Specifies the post-render action setting for the referenced AEGP_SetPostRenderAction(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
AEGP_PostRenderAction action);
|
|
Retrieves which output types are enabled for the referenced AEGP_GetEnabledOutputs(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
AEGP_OutputTypes *typesP);
NOTE: These are flags, not an enumeration. |
|
Specifies which output types are enabled for the referenced AEGP_SetEnabledOutputs(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
AEGP_OutputTypes enabled_types);
|
|
Retrieves which video channels are enabled for output in the referenced AEGP_OutputModuleRefH. AEGP_GetOutputChannels(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
AEGP_VideoChannels *outchannelsP);
|
|
Specifies which video channels are enabled for output in the referenced AEGP_SetOutputChannels(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
AEGP_VideoChannels outchannels);
|
|
Retrieves the stretch information enabled for the referenced AEGP_GetStretchInfo(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
A_Boolean *enabledPB,
AEGP_StretchQuality *qualP,
A_Boolean *lockedPB);
|
|
Retrieves the stretch information enabled for the referenced AEGP_SetStretchInfo(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
A_Boolean is_enabledB,
AEGP_StretchQuality quality);
|
|
Retrieves whether or not the cropping is enabled for the referenced AEGP_GetCropInfo(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
A_Boolean *is_enabledBP,
A_Rect *crop_rectP);
|
|
Specifies whether cropping is enabled for the referenced AEGP_SetCropInfo(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
A_Boolean enableB,
A_Rect crop_rect);
|
|
Retrieves whether or not audio output is enabled for the referenced AEGP_GetSoundFormatInfo(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
AEGP_SoundDataFormat *formatP,
A_Boolean *enabledPB);
|
|
Specifies whether or not audio output is enabled for the referenced AEGP_SetSoundFormatInfo(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
AEGP_SoundDataFormat format_info,
A_Boolean enabledB);
|
|
Retrieves the path to which AEGP_GetOutputFilePath(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
AEGP_MemHandle *unicode_pathPH);
|
|
Specifies the path to which AEGP_SetOutputFilePath(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
const A_UTF16Char *pathZ);
|
|
Adds the default output module to the specified AEGP_AddDefaultOutputModule(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH *outmodPH);
|
|
Retrieves information about the output module.
AEGP_GetExtraOutputModuleInfo(
AEGP_RQItemRefH rq_itemH,
AEGP_OutputModuleRefH outmodH,
AEGP_MemHandle *format_uniPH,
AEGP_MemHandle *info_uniPH,
A_Boolean *is_sequenceBP,
A_Boolean *multi_frameBP);
|
Working With Effects¶
These functions provide a way for effects (and AEGPs) to obtain information about the context of an applied effect.
Note
Any time you modify or rely on data from outside the normal render pipeline, you run the risk of dependency problems.
There is no way for After Effects to know that you depend on this external information; consequently, you will not be notified if it changes out from under you.
AEGP_PFInterfaceSuite1¶
Function |
Purpose |
|---|---|
|
Obtain the layer handle of the layer to which the effect is applied. AEGP_GetEffectLayer(
PF_ProgPtr effect_ref,
AEGP_LayerH *layerPH);
|
|
Obtain the AEGP_GetNewEffectForEffect(
AEGP_PluginID aegp_plugin_id,
PF_ProgPtr effect_ref,
AEGP_EffectRefH *effectPH);
|
|
Retreive the composition time corresponding to the effect’s layer time. AEGP_ConvertEffectToCompTime(
PF_ProgPtr effect_ref,
long what_timeL,
unsigned long time_scaleLu,
A_Time *comp_timePT);
|
|
Obtain the camera (if any) being used by After Effects to view the effect’s layer. AEGP_GetEffectCamera(
PF_ProgPtr effect_ref,
const A_Time *comp_timePT,
AEGP_LayerH camera_layerPH);
|
|
Obtain the transform used to move between the layer’s coordinate space and that of the containing composition. AEGP_GetEffectCameraMatrix(
PF_ProgPtr effect_ref,
const A_Time *comp_timePT,
A_Matrix4 *camera_matrixP,
A_FpLong *dst_to_planePF,
A_short *plane_widthPL,
A_short *plane_heightPL);
NOTE: In cases where the effect’s input layer has square pixels, but is in a non-square pixel composition,
you must correct for the pixel aspect ratio by premultiplying the matrix by |
AEGP_GetEffectCameraMatrix Notes¶
The model view for the camera matrix is inverse of the matrix obtained from AEGP_GetEffectCameraMatrix().
Also note that our matrix is row-based; OpenGL’s is column-based.
Do This Many Times¶
Utilizes multiple processors (if available) for your computations.
AEGP_IterateSuite1¶
Function |
Purpose |
|---|---|
|
Ask After Effects how many threads are currently available. AEGP_GetNumThreads(
A_long *num_threadsPL);
|
|
Specify a function for After Effects to manage on multiple processors.
Can be any function pointer specified by AEGP_IterateGeneric(
A_long iterationsL,
void *refconPV,
A_Err (*fn_func)
(void *refconPV,
A_long thread_indexL,
A_long i,
A_long iterationsL));
|
File Import Manager Suite¶
The FIMSuite allows file types handled by AEGPs to appear as part of the After Effects import dialog, and drag-and-drop messaging.
These are not for use by AEIOs! Rather, they are for importing projects which are best represented as After Effects compositions.
AEGP_FIMSuite3¶
Function |
Purpose |
|---|---|
|
Registers the name of the file type(s) supported by the plug-in.
Upon return, AEGP_RegisterImportFlavor(
const char *nameZ,
AE_FIM_ImportFlavorRef *imp_refP);
|
|
Registers an array of file types and file extensions (the two arrays need not be of equal length) supported by the AEGP. AEGP_RegisterImportFlavorFileTypes(
AE_FIM_ImportFlavorRef imp_ref,
long num_filekindsL,
const AEIO_FileKind *kindsAP,
long num_fileextsL,
const AEIO_FileKind *extsAP);
|
|
Register the AEGP functions which will respond to import of different filetypes. AEGP_RegisterImportFlavorImportCallbacks(
AE_FIM_ImportFlavorRef ref,
AE_FIM_ImportFlags single_flag,
const AE_FIM_ImportCallbacks *imp_cbsP);
|
|
Designates an item as having been imported (possibly replacing an existing item), and sets associated import options. AEGP_SetImportedItem(
AE_FIM_ImportOptions imp_options,
AEGP_ItemH imported_itemH);
|