PF_InData

After Effects communicates system, project, layer and audio information using PF_InData. This structure is updated before each command selector is sent to a plug-in.

Fields valid only during specific PF_Cmds are noted.

Also, don’t worry; although PF_InData is dauntingly large, you need not memorize each member’s purpose; you’ll use some of the fields some of the time.


PF_InData Members

Name Description
inter

Callbacks used for user interaction, adding parameters, checking whether the user has interrupted the effect, displaying a progress bar, and obtaining source frames and parameter values at times other than the current time being rendered.

This very useful function suite is described in Interaction Callback Functions.

utils Graphical and mathematical callbacks. This pointer is defined at all times.
effect_ref

Opaque data that must be passed to most of the various callback routines.

After Effects uses this to identify your plug-in.

quality

The current quality setting, either PF_Quality_HI or PF_Quality_LO.

Effects should perform faster in LO, and more accurately in HI.

The graphics utility callbacks perform differently between LO and HI quality; so should your effect!

This field is defined during all frame and sequence selectors.

version Effects specification version, Indicate the version you need to run successfully during PF_Cmd_GLOBAL_SETUP.
serial_num The serial number of the invoking application.
appl_id

The identifier of the invoking application.

If your plug-in is running in After Effects, appl_id contains the application creator code ‘FXTC’.

If it is running in Premiere Pro & Other Hosts it will be ‘PrMr’.

Use this to test whether your plug-in, licensed for use with one application, is being used with another.

num_params Input parameter count.
what_cpu Under macOS this contains the Gestalt value for CPU type (see Inside Macintosh, volume 6). Undefined on Windows.
what_fpu

Under macOS this contains the Gestalt value for FPU type.

Undefined on Windows.

current_time

The time of the current frame being rendered, valid during PF_Cmd_RENDER. This is the current time in the layer, not in any composition. If a layer starts at other than time 0 or is time-stretched, layer time and composition time are distinct.

The current frame number is current_time divided by time_step. The current time in seconds is current_time divided by time_scale.

To handle time stretching, composition frame rate changes, and time remapping, After Effects may ask effects to render at non-integral times (between two frames).

Be prepared for this; don’t assume that you’ll only be asked for frames on frame boundaries.

NOTE: As of CS3 (8.0), effects may be asked to render at negative current times. Deal!

time_step

The duration of the current source frame being rendered.

In several situations with nested compositions, this source frame duration may be different than the time span between frames in the layer (local_time_step).

This value can be converted to seconds by dividing by time_scale.

When calculating other source frame times, such as for PF_CHECKOUT_PARAM, use this value rather than local_time_step.

Can be negative if the layer is time-reversed. Can vary from one frame to the next if time remapping is applied on a nested composition.

Can differ from local_time_step when source material is stretched or remapped in a nested composition.

For example, this could occur when an inner composition is nested within an outer composition with a different frame rate, or time remapping is applied to the outer composition.

This value will be 0 during PF_Cmd_SEQUENCE_SETUP if it is not constant for all frames.

It will be set correctly during PF_Cmd_FRAME_SETUP and PF_Cmd_FRAME_SETDOWN selectors.

WARNING: This can be zero, so check it before you divide.

total_time

Duration of the layer.

If the layer is time-stretched longer than 100%, the value will be adjusted accordingly; but if the layer is time-stretched shorter, the value will not be affected.

If time remapping is enabled, this value will be the duration of the composition.

This value can be converted to seconds by dividing by time_scale.

local_time_step

Time difference between frames in the layer.

Affected by any time stretch applied to a layer.

Can be negative if the layer is time-reversed.

Unlike time_step, this value is constant from one frame to the next.

This value can be converted to seconds by dividing by time_scale.

For a step value that is constant over the entire frame range of the layer, use local_time_step, which is based on the composition’s framerate and layer stretch.

time_scale

The units per second that current_time, time_step, local_time_step and total_time are in.

If time_scale is 30, then the units of current_time, time_step, local_time_step and total_time are in 30ths of a second.

The time_step might then be 3, indicating that the sequence is actually being rendered at 10 frames per second. total_time might be 105, indicating that the sequence is 3.5 seconds long.

field

Valid only if PF_OutFlag_PIX_INDEPENDENT was set during PF_Cmd_GLOBAL_SETUP.

Check this field to see if you can process just the upper or lower field.

shutter_angle

Motion blur shutter angle. Values range from 0 to 1, which represents 360 degrees.

Will be zero unless motion blur is enabled and checked for the target layer.

shutter_angle == 180 means the time interval between current_time and current_time + 1/2 time_step.

Valid only if PF_OutFlag_I_USE_SHUTTER_ANGLE was set during PF_Cmd_GLOBAL_SETUP.

See the section on Motion Blur for details on how to implement motion blur in your effect.

width

Dimensions of the source layer, which are not necessarily the same as the width and height fields in the input image parameter.

Buffer resizing effects can cause this difference. Not affected by downsampling.

height  
extent_hint

The intersection of the visible portions of the input and output layers; encloses the composition rectangle transformed into layer coordinates.

Iterating over only this rectangle of pixels can speed your effect dramatically. See extent_hint Usage later in this chapter regarding proper usage.

output_origin_x The origin of the output buffer in the input buffer. Non-zero only when the effect changes the origin.
output_origin_y  
downsample_x

Point control parameters and layer parameter dimensions are automatically adjusted to compensate for a user telling After Effects to render only every nth pixel.

Effects need the downsampling factors to interpret scalar parameters representing pixel distances in the image (like sliders).

For example, a blur of 4 pixels should be interpreted as a blur of 2 pixels if the downsample factor is 1/2 in each direction (downsample factors are represented as ratios.)

Valid only during

downsample_y  
pixel_aspect_ratio Pixel aspect ratio (width over height).
in_flags Unused.
global_data Data stored by your plug-in during other selectors. Locked and unlocked by After Effects before and after calling the plug-in.
sequence_data  
frame_data  
start_sampL Starting sample number, relative to the start of the audio layer.
dur_sampL Duration of audio, expressed as the number of samples. Audio-specific.
total_sampL Samples in the audio layer; equivalent to total_time expressed in samples.
src_snd PF_SoundWorld describing the input sound. Audio-specific.
pica_basicP Pointer to the PICA Basic suite, used to acquire other suites.
pre_effect_source_origin_x

Origin of the source image in the input buffer. Valid only when sent with a frame selector.

Non-zero only if one or more effects that preceded this effect on the same layer resized the output buffer and moved the origin.

Check for both the resize and the new origin to determine output area.

This is useful for effects which have implicit spatial operations (other than point controls), like flipping a file around an image’s center.

NOTE: Checked-out point parameters are adjusted for the pre-effect origin at the current time, not the time being checked out.

pre_effect_source_origin_y  
shutter_phase Offset from frame time to shutter open time as a percentage of a frame duration.

extent_hint Usage

Note

hint rectangles are much more effective…and complicated…for SmartFX.

Use extent_hint to process only those pixels for which output is required; this is one of the simplest optimizations you can make.

Tell After Effects you use in_data>extent_hint by setting PF_OutFlag_USE_OUTPUT_EXTENT in PF_OutData during PF_Cmd_GLOBAL_SETUP (and in your PiPL).

Disable caching from the preferences menu before testing extent_hint code, so After Effects renders your effect whenever anything in your composition changes.

Otherwise, the caching mechanism would obscure your plug-in’s (possibly incorrect) output.

Move the layer within the composition so it’s cropped. The output>extent_hint is the portion of the layer which is visible in the composition.

Add a mask to your layer and move it around.

This changes the extent_hint, which encloses all of the non-zero alpha areas of the image.

The in_data>extent_hint is the intersection of these two rectangles (the composition and the mask), and changes whenever they do.

Extent rectangles are computed in the coordinate space of the original input layer, before resizing and origin shifting, to simplify rectangle intersection between the input and output extents for effects which set PF_OutFlag_PIX_INDEPENDENT.

To get the output extent in the coordinate system of the output buffer, offset the extent_hint by the PF_InData->output_origin_x and y fields.

Account for downsampling when computing output size; users must be able to render at full resolution.

If the output buffer exceeds 30,000 by 30,000, clamp it to that size, and consider displaying an alert dialog.

Once your code behaves correctly, enable the cache and see how frequently the effect needs to re-render.

Consider a drop shadow; users frequently apply a static drop shadow to a still image.

The output>extent_hint is ignored, so the cache is used more often.

For buffer-expanding effects, intersect the output>extent_hint with your plug-in’s transformed bounds and sets the size accordingly during PF_Cmd_FRAME_SETUP.


Now with 20% More Pixels!

As of 6.0, the extent_hints passed are 20% larger than the layer itself, to help with our predictive rendering decisions.

Numerous effects expand the buffer “just a touch”, and After Effects often uses the hint rectangles later.


Point Controls And Buffer Expansion

Effects which expand the output buffer position the original layer’s upper left corner by setting set output_origin_x/y in PF_InData during PF_Cmd_FRAME_SETUP.

This shift is reported to subsequent effects in the pre_effect_source_origin_x/y. Point parameters are adjusted for this shift automatically.

Apply a buffer expander such as Gaussian Blur or the Resizer SDK sample, before your effect, and use a large resize value.

If your effect is not handling pre_effect_source_origin_x/y correctly, turning the blur on and off will shift the position of the output.

All point parameter values (at any time) have shift values described by pre_effect_source_origin_x/y. For most effects this works transparently.

However, if a buffer expansion changes over time (as with an animated blur amount), the origin shift will move non-animated points.

Consider this when designing effects which cache point parameter values between frames.