Skip to content

Useful Utility Functions

PF_EffectUISuite

Although not strictly concerned with parameters, this suite can change the name of the options button.

Function

Purpose

PF_SetOptionsButtonName

Changes the text on the options button in the effect controls palette.

Note

This must be called during PF_Cmd_PARAM_SETUP.

PF_SetOptionsButtonName(
  PF_ProgPtr    effect_ref,
  const A_char  *nameZ);

nameZ may be up to A_char[31] in length.

PF_AppSuite

Roughly 437 years ago, when we released After Effects 5.0, we published some useful utility callbacks in PF_AppSuite. They're as useful today as they were then. After Effects has user-controllable UI brightness.

In addition to the PF_EffectCustomUIOverlayThemeSuite for custom UI in effects, use these calls to integrate seamlessly into the After Effects UI.

What better way to shame someone into purchasing a copy of your plug-in than by putting their personal information into a watermark, eh? Or set the cursor to add mask vertices, just to confuse people? Heh heh heh. But that would be wrong.

Function

Purpose

PF_AppGetBgColor

Retrieves the current background color.

PF_AppGetBgColor(
  PF_App_Color  bg_colorP);

PF_AppGetColor

Retrieves the color for the specified UI element.

See AE_EffectSuites.h for a complete enumeration of available PF_App_Color values; basically any color in After Effects' UI can be retrieved.

CC adds several new PF_App_ColorType enum values for new elements that can be queried.

Note that in CS6, the color definitions are off from FILL_LIGHT downward.

Use following psuedocode for CS6 only:

GetColor(enum e)
{
  if host_is_CS6 and e >= FILL_LIGHT
  e += 3
    call real GetColor
}

PF_AppGetColor(
  PF_App_ColorType  color_type,
  PF_App_Color      *app_colorP);

PF_AppGetLanguage

New in CC. Retrieves the active displayed language of AE UI so plug-in can match. Here are the possible language codes as of CC:

  • Chinese - zh_CN
  • English - en_US
  • French - fr_FR
  • German - de_DE
  • Italian - it_IT
  • Japanese - ja_JP
  • Korean - ko_KR
  • Spanish - es_ES

PF_AppGetLanguage(
  A_char  lang_tagZ);

PF_GetPersonalInfo

Retrieves the user's registration information.

PF_GetPersonalInfo(
  PF_AppPersonalTextInfo  *ptiP);

typedef struct PF_AppPersonalTextInfo {
  A_char  name[PF_APP_MAX_PERS_LEN + 1];
  A_char  org[PF_APP_MAX_PERS_LEN + 1];
  A_char  serial_str[PF_APP_MAX_PERS_LEN+1];
} PF_AppPersonalTextInfo;

PF_GetFontStyleSheet

Retrieves font style sheet information for the fonts used in After Effects' UI.

Trivia: The font used in After Effects' UI starting in 15.0 is Adobe Clean.

Before that, it was Tahoma on Windows and Lucida Grande on macOS X.

PF_GetFontStyleSheet(
  PF_FontStyleSheet  sheet,
  PF_FontName        *font_nameP0,
  A_short            *font_numPS0,
  A_short            *sizePS0,
  A_short            *stylePS0);

PF_SetCursor

Sets the cursor to any of After Effects' cursors. See AE_EffectUI.h for a complete enumeration.

Set to: - PF_Cursor_NONE to allow After Effects to set the cursor. - PF_Cursor_CUSTOM if you've used OS-specific calls to change the cursor (After Effects will honor your changes).

PF_SetCursor(
  PF_CursorType  cursor);

PF_IsRenderEngine

Returns TRUE if After Effects is running in watched folder mode, or is a render engine installation.

PF_IsRenderEngine(
  PF_Boolean  *render_enginePB);

As of AE6.5, this function returns TRUE if the installation is the render engine, or if the After Effects is being run with no UI, or if After Effects is in watched folder mode.

PF_AppColorPickerDialog

Displays the After Effects color picker dialog (which may be the system color picker, depending on the user's preferences).

Will return PF_Interrupt_CANCEL if user cancels dialog. Returned color is in the project's working color space.

PF_AppColorPickerDialog(
  const A_char         *dialog_titleZ0,
  const PF_PixelFloat  *sample_colorP,
  PF_PixelFloat        *result_colorP);

PF_GetMouse

Returns the position of the mouse in the custom UI coordinate space.

PF_GetMouse(
  PF_Point  *pointP);

PF_InvalidateRect

Queue up a redraw of a specific area of the custom UI for an effect.

Only valid while handling a non-drawing event in the effect.

Specify rectP0 as NULL to invalidate the entire window. The redraw will happen at the next available idle moment after returning from the event.

Set the PF_EO_UPDATE_NOW event outflag to update the window immediately after the event returns.

PF_InvalidateRect(
  const PF_ContextH  contextH,
  const PF_Rect*     rectP0);

PF_ConvertLocalToGlobal

Converts from the custom UI coordinate system to global screen coordinates. Use only during custom UI event handling.

PF_ConvertLocalToGlobal(
  const PF_Point  *localP,
  PF_Point        *globalP);

Advanced Appsuite: You Can Do That?!

PF_AdvAppSuite was originally designed for some pretty nefarious purposes; an external application was pretending to be an After Effects plug-in, and required ways to notify After Effects of the changes it had made to the project. Our API impurity is your gain.

PF_AdvAppSuite2

Function

Purpose

PF_SetProjectDirty

Tells After Effects that the project has been changed since it was last saved.

PF_SetProjectDirty(void);

PF_SaveProject

Saves the project to the current path. To save the project elsewhere, use AEGP_SaveProjectToPath().

PF_SaveProject(void);

PF_SaveBackgroundState

Stores the background state (After Effects' position in the stacking order of open applications and windows).

PF_SaveBackgroundState(void);

PF_ForceForeground

Brings After Effects to the front of all currently open applications and windows.

PF_ForceForeground(void);

PF_RestoreBackgroundState

Puts After Effects back where it was, in relation to other applications and windows.

PF_RestoreBackgroundState(void);

PF_RefreshAllWindows

Forces all After Effects windows to update.

Note that although the Composition panel will be refreshed, this does not guarantee a new frame will be sent to External Monitor Preview plug-ins.

PF_RefreshAllWindows(void);

PF_InfoDrawText

Writes text into the After Effects info palette.

PF_InfoDrawText(
  const A_char  *line1Z0,
  const A_char  *line2Z0);

PF_InfoDrawColor

Draws the specified color in the After Effects info palette (alpha is ignored).

PF_InfoDrawColor(
  PF_Pixel  color);

PF_InfoDrawText3

Writes three lines of text into the After Effects info palette.

PF_InfoDrawText3(
  const A_char  *line1Z0,
  const A_char  *line2Z0,
  const A_char  *line3Z0);

PF_InfoDrawText3Plus

Writes three lines of text into the After Effects info palette, with portions of the second and third lines left and right justified.

PF_InfoDrawText3Plus(
  const A_char  *line1Z0,
  const A_char  *line2_jrZ0,
  const A_char  *line2_jlZ0,
  const A_char  *line3_jrZ0,
  const A_char  *line3_jlZ0);

PF_AppendInfoText

Appends characters to the currently-displayed info text.

PF_AppendInfoText(
  const A_char  *appendZ0);

Formatting Time

PF_AdvTimeSuite provides several functions to match how After Effects displays time. In fact, these are the same functions we use internally.

PF_AdvTimeSuite4

Function

Purpose

PF_FormatTimeActiveItem

Given a time value and scale, returns a formatted string representing that time.

If durationB is TRUE, appropriate units will be appended.

PF_FormatTimeActiveItem(
  A_long      time_valueUL,
  A_u_long    time_scaleL,
  PF_Boolean  durationB,
  A_char      *time_buf);

PF_FormatTime

Contextualizes the formatted time string for the given PF_InData and PF_EffectWorld (i.e., layer time).

PF_FormatTime(
  PF_InData       *in_data,
  PF_EffectWorld  *world,
  A_long          time_valueUL,
  A_u_long        time_scaleL,
  PF_Boolean      durationB,
  A_char          *time_buf);

PF_FormatTimePlus

Allows you to select composition or layer time.

PF_FormatTimePlus(
  PF_InData       *in_data,
  PF_EffectWorld  *world,
  A_long          time_valueUL,
  A_u_long        time_scaleL,
  PF_Boolean      comp_timeB,
  PF_Boolean      durationB,
  A_char          *time_buf);

PF_GetTimeDisplayPref

Returns the starting frame number (specified by the user in composition settings), and the composition's time display preferences.

Updated in 14.2 to support higher frame rates.

PF_GetTimeDisplayPref(
  PF_TimeDisplayPref2  *tdp,
  A_long               *starting_num);
  typedef              struct {
  A_char               display_mode;
  A_long               framemax;
  A_long               frames_per_foot;
  A_char               frames_start;
  A_Boolean            nondrop30B;
  A_Boolean            honor_source_timecodeB;
  A_Boolean            use_feet_framesB;
  } PF_TimeDisplayPrefVersion3;

PF_TimeCountFrames

New in 15.0. Returns the index of the frame in the current comp.

PF_TimeCountFrames(
  const A_Time  *start_timeTP,
  const A_Time  *time_stepTP,
  A_Boolean     include_partial_frameB,
  A_long        *frame_countL);

Affecting The Timeline

Long ago, we helped a developer integrate their stand-alone tracker with After Effects by exposing a set of functions to give them some way to notify us of, and be notified of, changes to the timeline.

With the numerous AEGP API calls available, these aren't used much, but they're still available.

Don't confuse this suite with AEGP_ItemSuite.

PF_AdvItemSuite1

Function

Purpose

PF_MoveTimeStep

Moves current time num_stepsL in the specified direction.

PF_MoveTimeStep(
  PF_InData       *in_data,
  PF_EffectWorld  *world,
  PF_Step         time_dir,
  A_long          num_stepsL);

PF_MoveTimeStepActiveItem

Moves num_stepsL in the specified direction, for the active item.

PF_MoveTimeStepActiveItem(
  PF_Step  time_dir,
  A_long   num_stepsL);

PF_TouchActiveItem

Tells After Effects that the active item must be updated.

PF_TouchActiveItem (void);

PF_ForceRerender

Forces After Effects to rerender the current frame.

PF_ForceRerender(
  PF_InData       *in_data,
  PF_EffectWorld  *world);

PF_EffectIsActiveOrEnabled

Returns whether the effect which owns the PF_ContextH is currently active or enabled (if it isn't, After Effects won't be listening for function calls from it).

PF_EffectIsActiveOrEnabled(
  PF_ContextH  contextH,
  PF_Boolean   *enabledPB);

Accessing Auxiliary Channel Data

Some file types contain more than just pixel data; use PF_ChannelSuite to determine whether such information is present, and the macros in AE_ChannelSuites.h to retrieve it in the format you need.

PF_ChannelSuite1

Function

Purpose

PF_GetLayerChannelCount

Retrieves the number of auxiliary channels associated with the indexed layer.

PF_GetLayerChannelCount(
  PF_ProgPtr     effect_ref,
  PF_ParamIndex  param_index,
  A_long         *num_channelsPL);

PF_GetLayerChannelIndexedRefAndDesc

Retrieves (by index) a reference to, and description of, the specified channel.

PF_GetLayerChannelIndexedRefAndDesc(
  PF_ProgPtr       effect_ref,
  PF_ParamIndex    param_index,
  PF_ChannelIndex  channel_index,
  PF_Boolean       *foundPB,
  PF_ChannelRef    *channel_refP,
  PF_ChannelDesc   *channel_descP);

PF_GetLayerChannelTypedRefAndDesc

Retrieves an auxiliary channel by type.

Returned information is valid only if foundPB returns TRUE.

PF_GetLayerChannelTypedRefAndDesc(
  PF_ProgPtr      effect_ref,
  PF_ParamIndex   param_index,
  PF_ChannelType  channel_type,
  PF_Boolean      *foundPB,
  PF_ChannelRef   *channel_refP,
  PF_ChannelDesc  *channel_descP);

PF_DataType will be one of the following:

  • PF_DataType_FLOAT - 34 bytes
  • PF_DataType_DOUBLE - 38 bytes
  • PF_DataType_LONG - 34 bytes
  • PF_DataType_SHORT - 32 bytes
  • PF_DataType_FIXED_16_16 - 34 bytes
  • PF_DataType_CHAR - 31 byte
  • PF_DataType_U_BYTE - 31 byte
  • PF_DataType_U_SHORT - 32 bytes
  • PF_DataType_U_FIXED_16_16 - 34 bytes
  • PF_DataType_RGB - 3 bytes

PF_ChannelType will be one of the following:

  • PF_ChannelType_DEPTH
  • PF_ChannelType_NORMALS
  • PF_ChannelType_OBJECTID
  • PF_ChannelType_MOTIONVECTOR
  • PF_ChannelType_BK_COLOR
  • PF_ChannelType_TEXTURE
  • PF_ChannelType_COVERAGE
  • PF_ChannelType_NODE
  • PF_ChannelType_MATERIAL
  • PF_ChannelType_UNCLAMPED
  • PF_ChannelType_UNKNOWN

PF_CheckoutLayerChannel

Retrieves the PF_ChannelChunk containing the data associated with the given PF_ChannelRefPtr.

PF_CheckoutLayerChannel(
  PF_ProgPtr        effect_ref,
  PF_ChannelRefPtr  channel_refP,
  long              what_time,
  long              duration,
  unsigned long     time_scale,
  PF_DataType       data_type,
  PF_ChannelChunk   *channel_chunkP);

PF_CheckinLayerChannel

Checks in the PF_ChannelChunk. Always, always, always check the data back in.

PF_CheckinLayerChannel(
  PF_ProgPtr        effect_ref,
  PF_ChannelRefPtr  channel_refP,
  PF_ChannelChunk   *channel_chunkP);