PF_OutData¶

Communicate changes made by your plug-in to After Effects using PF_OutData. Valid times for altering these fields are noted.

PF_OutData Members¶

Field	Description
`my_version`	Set this flag (using the PF_VERSION macro) to the version of your plug-in code. After Effects uses this data to decide which of duplicate effects to load.
`name`	Unused.
`global_data`	Handle which will be returned to you in PF_InData with every call. Use After Effects’ memory allocation functions.
`num_params`	After Effects checks this field against the number of calls made to PF_ADD_PARAM, as well as the implicit input layer.
`sequence_data`	Allocatable upon receiving PF_Cmd_SEQUENCE_SETUP, this handle will be passed back to you in PF_InData during all subsequent calls.
`flat_sdata_size`	Unused (After Effects knows the size, because you used its allocation functions to get the memory in the first place).
`frame_data`	Handle you (might have) allocated during PF_Cmd_FRAME_SETUP. This is never written to disk; it was used to pass information from your PF_Cmd_FRAME_SETUP response to your PF_Cmd_RENDER or PF_Cmd_FRAME_SETDOWN (which you must do if you resize the output buffer). Otherwise, this memory is rarely used.
`width`, `height`, `origin`	Set during PF_Cmd_FRAME_SETUP if the output image size differs from the input. `width` and `height` are the size of the output buffer, and `origin` is the point the input should map to in the output. To create a 5-pixel drop shadow up and left, set origin to (5, 5).
out_flags	Send messages to After Effects. OR together multiple values.
`return_msg`	After Effects displays any C string you put here (checked and cleared after every command selector).
`start_sampL`, `dur_sampL`, `dest_snd`	Used only for Audio commands
out_flags2	Send messages to After Effects. OR together multiple values.

PF_OutFlags¶

These flags communicate capability and status information to After Effects. In previous versions they were also used to send rudimentary messages, e.g. refresh the UI, send an error message.

These capabilities have been supplanted by function suites, and all new messaging functions will come in that format. However, capability flags are still contained in the PiPL.

Update both the PiPL and your source code when you make a change. Many of these flags can be changed during an After Effects session.

Flag	Indicates
`PF_OutFlag_KEEP_RESOURCE_OPEN`	The plug-in’s resources must be available during all commands. During PF_Cmd_GLOBAL_SETUP, the plug-in’s resources are always open, but unavailable at all other times (except during PF_Cmd_ABOUT and PF_Cmd_DO_DIALOG), unless this flag has been set. Set if you need access to resources at any time other than during PF_Cmd_GLOBAL_SETUP. NOTE: We recommend the plug-in load and store the necessary resources in global data, rather than keeping the file’s resources open.
`PF_OutFlag_WIDE_TIME_INPUT`	The effect checks out a parameter at a time other than `current_time`. If you use a parameter (including layer parameters) from another time, set this flag. Otherwise, After Effects won’t correctly invalidate cached frames used by your effect. Set during PF_Cmd_GLOBAL_SETUP. If you set this flag, we strongly recommend you also set `PF_OutFlag2_AUTOMATIC_WIDE_TIME_INPUT` for better performance.
`PF_OutFlag_NON_PARAM_VARY`	With this flag set, After Effects will not cache output when the effect is applied to a still. Otherwise, After Effects will cache your output to be used to render other frames, if possible. Set this flag if output varies based on something besides a parameter value. If the effect produces changing frames when applied to a still image and all parameters are constant, that’s a sure sign that this bit should be set (e.g. Wave Warp). Particle effects, for example, will need this. Set during PF_Cmd_GLOBAL_SETUP. Can be overridden dynamically if needed during PF_Cmd_QUERY_DYNAMIC_FLAGS. Turn this off whenever possible to improve performance.
`PF_OutFlag_RESERVED6`	Unused. Formerly PF_OutFlag_SEND_PARAMS_UPDATE. Replaced by `PF_OutFlag_REFRESH_UI`.
`PF_OutFlag_SEQUENCE_DATA_NEEDS_FLATTENING`	Both After Effects and Premiere Pro assume this flag is set. Flattening is necessary when sequence data contains referencing items (pointers, handles), which must be flattened for storage and unflattened for use. See PF_Cmd_SEQUENCE_RESETUP.
`PF_OutFlag_I_DO_DIALOG`	Effect displays a dialog in response to PF_Cmd_DO_DIALOG. Set during PF_Cmd_GLOBAL_SETUP, checked during PF_Cmd_SEQUENCE_SETUP. Note: the effect’s response to PF_OutFlag_I_DO_DIALOG is not undoable. You can use arbitrary data with a custom UI, should such changes become necessary.
`PF_OutFlag_USE_OUTPUT_EXTENT`	Effect honors the output `extent_rect`. Set during PF_Cmd_GLOBAL_SETUP. See details at the end of the chapter for proper usage. Note: Obsolete for SmartFX.
`PF_OutFlag_SEND_DO_DIALOG`	Effect must show dialog to function (added for compatibility with Photoshop plug-ins). After Effects sends PF_Cmd_DO_DIALOG after PF_Cmd_SEQUENCE_SETUP. Set during PF_Cmd_SEQUENCE_RESETUP, not during PF_Cmd_GLOBAL_SETUP.
`PF_OutFlag_DISPLAY_ERROR_MESSAGE`	Display the contents of `return_msg` in an error dialog. Whenever return_msg is non-NULL, After Effects displays the contents in a dialog, which will be an error dialog if this flag is set. Set after any command, and can be used during debugging. This is also a good way to implement nag messages for tryout versions.
`PF_OutFlag_I_EXPAND_BUFFER`	Effect expands the output buffer. Set during PF_Cmd_GLOBAL_SETUP. Set this flag and `PF_OutFlag_USE_OUTPUT_EXTENT` to use the intersection of the output `extent_rect` and your new buffer size during PF_Cmd_FRAME_SETUP. Use `pre_effect_source_origin` fields to detect other transformations. Note: Only set this flag if you need to; it drastically reduces caching efficiency. Note: Obsolete for SmartFX.
`PF_OutFlag_PIX_INDEPENDENT`	A given pixel is independent of the pixels around it. Set during PF_Cmd_GLOBAL_SETUP or PF_Cmd_QUERY_DYNAMIC_FLAGS. As an example, color correction effects are typically pixel independent, distortions are not. NOTE: If your effect doesn’t use the color values of one pixel to affect those of adjacent pixels, set this outflag! It can provide dramatic performance improvements.
`PF_OutFlag_I_WRITE_INPUT_BUFFER`	The effect writes into the input buffer. This is of limited use; while saving an allocation, it invalidates some pipeline caching. Set during PF_Cmd_GLOBAL_SETUP.
`PF_OutFlag_I_SHRINK_BUFFER`	The effect shrinks its buffer based on the `extent_rect` in order to be more memory efficient. Set during PF_Cmd_GLOBAL_SETUP whenever possible. Note: Obsolete for SmartFX.
`PF_OutFlag_WORKS_IN_PLACE`	Unused.
`PF_OutFlag_SQUARE_PIX_ONLY`	Unused.
`PF_OutFlag_CUSTOM_UI`	The effect has a custom user interface and requires PF_Cmd_EVENT messages. Set during PF_Cmd_GLOBAL_SETUP.
`PF_OutFlag_RESERVED5`	Unused.
`PF_OutFlag_REFRESH_UI`	Refresh the entire effect controls, composition, and layer windows. Set during PF_Cmd_EVENT, PF_Cmd_RENDER, and PF_Cmd_DO_DIALOG. If refreshing custom UI during `PF_Cmd_EVENT`, we recommend using the new redraw mechanism with finer granularity.
`PF_OutFlag_NOP_RENDER`	Set this flag during PF_Cmd_FRAME_SETUP to invalidate the current render.
`PF_OutFlag_I_USE_SHUTTER_ANGLE`	Indicates rendered images depend upon the value of `shutter_angle`.
`PF_OutFlag_I_USE_AUDIO`	Effect’s parameters depend on audio data, obtained using PF_CHECKOUT_LAYER_AUDIO.
`PF_OutFlag_I_AM_OBSOLETE`	Effect is available for use when working with an old project in which it was originally applied, but doesn’t appear in the effect menu.
`PF_OutFlag_FORCE_RERENDER`	Effect made a change that requires a re-render. PF_ChangeFlag_CHANGED_VALUE also forces a re-render.
`PF_OutFlag_PiPL_OVERRIDES_OUTDATA_OUTFLAGS`	After Effects will use PiPL outflags, and ignore those set during PF_Cmd_GLOBAL_SETUP.
`PF_OutFlag_I_HAVE_EXTERNAL_DEPENDENCIES`	Effect depends on an external file (or external font). If set, After Effects sends PF_Cmd_GET_EXTERNAL_DEPENDENCIES.
`PF_OutFlag_DEEP_COLOR_AWARE`	The effect handles 16-bpc color.
`PF_OutFlag_SEND_UPDATE_PARAMS_UI`	Set this flag during PF_Cmd_GLOBAL_SETUP to receive PF_Cmd_UPDATE_PARAMS_UI.
`PF_OutFlag_AUDIO_FLOAT_ONLY`	Effect requires audio data in PF_SIGNED_FLOAT format. After Effects will perform any required format conversion. You must also set either `PF_OutFlag_AUDIO_EFFECT_TOO` or `PF_OutFlag_AUDIO_EFFECT_ONLY`.
`PF_OutFlag_AUDIO_IIR`	Set during PF_Cmd_GLOBAL_SETUP if the (audio) effect is an Infinite Impulse Response filter. This is true if output at a given time depends on output from previous times. When an IIR filter receives PF_Cmd_AUDIO_RENDER, the input audio time span is the same as the output audio time span (when they intersect with the output time span requested in PF_Cmd_AUDIO_SETUP). In response to PF_Cmd_AUDIO_SETUP, the filter can request audio from earlier times (as for delay effects). The filter can access parameters from that earlier time, and should cache them (along with interim audio) in sequence data. If the audio generated does not correspond to the requested output audio’s time, the output audio duration should be set to zero. The filter can update its delay line using the parameters and the input audio. Having cached its delay line, request more input audio during PF_Cmd_AUDIO_SETUP based on the last cached delay line. Use PF_HasParamChanged to determine whether or not your cache is valid.
`PF_OutFlag_I_SYNTHESIZE_AUDIO`	Set during PF_Cmd_GLOBAL_SETUP time if the effect generates audio, even when passed silence. You must also set either `PF_OutFlag_AUDIO_EFFECT_TOO` or `PF_OutFlag_AUDIO_EFFECT_ONLY`.
`PF_OutFlag_AUDIO_EFFECT_TOO`	Set during PF_Cmd_GLOBAL_SETUP if the effect alters audio.
`PF_OutFlag_AUDIO_EFFECT_ONLY`	Set during PF_Cmd_GLOBAL_SETUP if the effect alters only audio output.

PF_OutFlags2¶

We added a second set of outflags in After Effects 5.0; partly for room to expand in the future, and partly to break ourselves of the bad habit of repurposing existing flags.

As with PF_OutFlags, many of these flags can be changed during an After Effects session.

And don’t forget to update both the PiPL and your source code when you make a change.

Flag	Indicates
`PF_OutFlag2_NONE`	Nothing.
`PF_OutFlag2_SUPPORTS_QUERY_DYNAMIC_FLAGS`	The effect responds to PF_Cmd_QUERY_DYNAMIC_FLAGS. Must be set in the PiPL and during PF_Cmd_GLOBAL_SETUP.
`PF_OutFlag2_I_USE_3D_CAMERA`	The effect accesses 3D camera information.
`PF_OutFlag2_I_USE_3D_LIGHTS`	The effect accesses 3D lighting information.
`PF_OutFlag2_PARAM_GROUP_START_COLLAPSED_FLAG`	This flag in itself doesn’t control the state of the param group twirlies. The initial collapse state of each individual parameter group is set during PF_Cmd_PARAM_SETUP, by setting the PF_ParamFlag_START_COLLAPSED flag in PF_ParamFlags. but those individual settings will not be honored unless the effect sets this bit. Otherwise, all parameter groups will be collapsed by default. Remember to set this flag in both the PiPL and here during PF_Cmd_GLOBAL_SETUP.
`PF_OutFlag2_I_AM_THREADSAFE`	Currently this does nothing. If this sounds interesting to you, you may be interested in `PF_OutFlag2_PPRO_DO_NOT_CLONE_SEQUENCE_DATA_FOR_RENDER`, described below.
`PF_OutFlag2_CAN_COMBINE_WITH_DESTINATION`	Originally added for Premiere usage, but no longer used.
`PF_OutFlag2_DOESNT_NEED_EMPTY_PIXELS`	Added for render optimizations; shrinks the input buffer passed to the effect to exclude any empty pixels (where empty means “zero alpha” unless `PF_OutFlag2_REVEALS_ZERO_ALPHA` is set, in which case RGB must be zero as well). Set during PF_Cmd_GLOBAL_SETUP or PF_Cmd_QUERY_DYNAMIC_FLAGS. The origin of the trimmed buffer can be found in `in_data>pre_effect_source_origin`. Effects with both this flag and `PF_OutFlag_I_EXPAND_BUFFER` set may get called with a null input buffer if their input is completely empty, and must be able to handle this case without crashing. Note: this flag can cause the size of the output buffer to change. Note: Obsolete for SmartFX.
`PF_OutFlag2_REVEALS_ZERO_ALPHA`	This is the one flag implementors need to pay most attention to since it represents a change in the default behavior. Set this flag if the effect can take pixels with zero alpha and reveal the RGB data in them (like our Set Channels effect). This tells After Effects not to trim such pixels when determining the input for the effect. This flag can be changed during PF_Cmd_QUERY_DYNAMIC_FLAGS. Note that, while this flag can cause changes to the size of the `extent_hint`, it will not change the image buffer size. As of 6.0, pixels outside the mask’s bounding box are zeroed. If your effect can reveal such pixels, tell AE not to throw away these RGB values by setting this flag. If your effect does not always reveal such pixels, set this bit dynamically. To see if your effect needs this bit set, apply a mask significantly smaller than the layer to a solid, then apply the effect and set it to its alpha-modifying state. If the rectangular bounding box of the mask becomes visible, this bit needs to be set.
`PF_OutFlag2_PRESERVES_FULLY_OPAQUE_PIXELS`	Preserve those pixels!
`PF_OutFlag2_SUPPORTS_SMART_RENDER`	The effect uses the SmartFX API.
`PF_OutFlag2_FLOAT_COLOR_AWARE`	The effect supports 32-bpc floating point color representation. NOTE: `PF_OutFlag2_SUPPORTS_SMART_RENDER` must also be set.
`PF_OutFlag2_I_USE_COLORSPACE_ENUMERATION`	This is for effects which optimized for different color spaces in Premiere Pro. See the Premiere Pro SDK for more details.
`PF_OutFlag2_I_AM_DEPRECATED`	Setting this during PF_Cmd_GLOBAL_SETUP puts the effect in the localized “Obsolete” folder in the Effects panel. Compare to `PF_OutFlag_I_AM_OBSOLETE`.
`PF_OutFlag2_PPRO_DO_NOT_CLONE_SEQUENCE_DATA_FOR_RENDER`	Supported in Premiere Pro, and not in After Effects. This affects how Premiere Pro drives the plug-in using Multithreading.
`PF_OutFlag2_AUTOMATIC_WIDE_TIME_INPUT`	Set during PF_Cmd_GLOBAL_SETUP. Requires setting of `PF_OutFlag_WIDE_TIME_INPUT` (which allows you to support old hosts), but effectively overrides that flag. When set, all parameter checkouts are tracked so over-time dependencies are known by the host, and much more efficient. For example, if you set only the old `PF_OutFlag_WIDE_TIME_INPUT`, anytime anything changes at any time upstream from your effect, you will be called to re-render. With this flag set, if a given frame 17 has checked out things from times 0-17, AE will know that any changes at frames 18+ will not affect that cached frame. Note that if you use this new flag, you must not cache any time-dependent data in your sequence data (or anywhere else), unless you also validate that cache using `PF_GetCurrentState()` / `PF_AreStatesIdentical()` from PF_ParamUtilSuite3 before using the time-dependent data. This only works for SmartFX (those that set `PF_OutFlag2_SUPPORTS_SMART_RENDER`). If you haven’t set that, After Effects will silently treat this as `PF_OutFlag_WIDE_TIME_INPUT` instead.
`PF_OutFlag2_I_USE_COMP_TIMECODE`	Set during PF_Cmd_GLOBAL_SETUP. This lets AE know it should rerender an effect if the composition start time and/ or drop-frame setting has been modified.
`PF_OutFlag2_DEPENDS_ON_UNREFERENCED_MASKS`	New in CS6. Set this if you are going to look at paths that aren’t directly referenced by a path param, e.g. if you are going to draw a stroke on all masks. This is needed so After Effects knows to invalidate your output when a mask is modified that doesn’t appear to be referenced by your effect. Set during PF_Cmd_GLOBAL_SETUP or PF_Cmd_QUERY_DYNAMIC_FLAGS.
`PF_OutFlag2_OUTPUT_IS_WATERMARKED`	New in CS6. Set this during PF_Cmd_GLOBAL_SETUP if your output is going to be watermarked in some way that makes it unsuitable for final use, probably because the user is using an unlicensed demo version. It is ok to change this state during the course of app session during PF_Cmd_QUERY_DYNAMIC_FLAGS, if e.g. a floating license status changes. Plug-in authors that actually do have this state changing asynchronously must be careful to have the next render match the last state returned from PF_Cmd_QUERY_DYNAMIC_FLAGS otherwise race conditions could cause incorrect frames to be cached. (This is a non-issue if you only change this in response to `DO_DIALOG`.)
`PF_OutFlag2_SUPPORTS_GPU_RENDER_F32`	New in 16.0 Set during PF_Cmd_GLOBAL_SETUP, this indicates GPU support. The effect will be called with GPU selectors, and will be badged as GPU-supporting in the GUI. At `PF_Cmd_GPU_DEVICE_SETUP` time, these flags indicate rendering capabilities for a specific device and framework.
`PF_OutFlag2_SUPPORTS_THREADED_RENDERING`	Available in After Effects Beta builds starting June 2020, After Effects 2022. Set during `PF_Cmd_GLOBAL_SETUP`, this indicates the effect supports rendering on multiple threads at the same time. Single or multiple applications of this effect on a layer can be called to render at the same time on multiple threads. This flag indicates the effect supports rendering on multiple threads at the same time. Single or multiple applications of this effect on a layer can be called to render at the same time on multiple threads. If you are using the `PF_OutFlag_SEQUENCE_DATA_NEEDS_FLATTENING` flag, remember to also set the `PF_OutFlag2_SUPPORTS_GET_FLATTENED_SEQUENCE_DATA` flag. See Sequence Data in Multi-Frame rendering for more information. Note This flag should only be set on plugins that have been tested to be thread-safe with multi-frame rendering enabled in AE. For more information on how to use this flag, please see Multi-Frame Rendering in AE under Effect Details.
`PF_OutFlag2_MUTABLE_RENDER_SEQUENCE_DATA_SLOWER`	Available in After Effects Beta builds starting March 2021, After Effects 2022. Indicates the effect needs sequence_data replicated for each render thread, thus allowing each render to have sequence_data which can be written to. Note that changes to sequence_data will be discarded regularly, currently after each span of frames is rendered such as single RAM Preview or Render Queue export. Note This flag should only be set on plugins that have been tested to be thread-safe with multi-frame rendering enabled in AE. For more information on how to use this flag, please see Multi-Frame Rendering in AE under Effect Details.