After Effects CC SDK User Guide (4)-Chapter Two Basics of Effects (1)

After Effects CC SDK User Guide (4)-Chapter Two Basics of Effects (1)

Chapter 2 Basics of Effects

Links to other articles

This chapter will provide all the information you need to know to understand how basic effects plugins work. These details are the basis of each effect plug-in. When you finish this chapter, you will be ready for something interesting-modify the pixels!

Entry point

All communication between After Effects and effect plug-ins are initiated by After Effects, and all of these are completed by the host (After Effects) calling a single entry point function. For all effect plug-ins, the entry point function must have the following signature:

PF_Err main ( PF_Cmd cmd, PF_InData *in_data, PF_OutData *out_data, PF_ParamDef *params[], PF_LayerDef *output, void *extra) Copy code

The name of the entry point function above is "main", but it can be anything specified in the PiPL resource .

Before each call to the entry point function, After Effects updates PF_InData and the parameter array of the plug-in

PF_ParamDef[]
(Except for those noted). After the plug-in returns from its call, After Effects checks
PF_OutData
Changes and use when appropriate
PF_LayerDef
The effect has been shown.

Table 3: Entry method parameters

parameterpurpose
cmdAfter Effects settings
Command selector (COMMAND SELECTORS)
To tell the plug-in what to do.
in_dataInformation about the state of the application and data that informs the plug-in operation. It also provides pointers to many interfaces and image processing functions.
out_dataPass in
out_data
Set the fields in and pass the information back to After Effects.
params
in_data>current_time
The array of plugin parameters provided in. The parameter [0] is the input image to which the effect should be applied (
PF_EffectWorld
). These values are only valid in certain selectors (this is explained in the selector description). The parameters are discussed in detail here.
outputThe output image is rendered by the effect plug-in and passed back to After Effects. Only valid in certain selectors.
extraAdditional parameters vary with the type of command or event sent (
PF_Cmd_EVENT
) And change. Mainly used for event management and parameter monitoring.

Command selector (COMMAND SELECTORS)

Commands, to put it simply, are what After Effects wants your effects to do. Certain selector responses are required; most are optional, although we added them for a reason...

After sending each command selector, the effect receives

PF_InData
After effects information in
PF_ParamDef[]
The input and parameter values in the (including the parameter description array of the input layer), as well as access to the callback and function suite. They send information back
PF_OutData
In After Effects, and (when appropriate) render the output to
PF_LayerDef
, Also known as
PF_EffectWorld
. During the event, they additionally receive event-specific information.

Call sequence

Only the first few command selectors are predictable; the rest of the call sequence is determined by user actions.

When applied for the first time, the plug-in will receive

PF_Cmd_GLOBAL_SETUP
,After that
PF_Cmd_PARAM_SETUP
. Whenever the user adds an effect to a layer, it will send
PF_Cmd_SEQUENCE_SETUP
.

For each frame rendered by the basic non-smartfx effect, After Effects sends

PF_Cmd_FRAME_SETUP
,then
PF_Cmd_RENDER
,then
PF_Cmd_FRAME_SETDOWN
. All effect plugins must respond
PF_Cmd_RENDER
.

For SmartFX,

PF_Cmd_SMART_PRE_RENDER
Can send a single
PF_Cmd_SMART_RENDER
Send any number of times before.

PF_Cmd_SEQUENCE_SETDOWN
Sent on exit, when the user deletes the effect or closes the project.
PF_Cmd_SEQUENCE_RESETUP
Sent when the item is loaded or the layer it is applied to changes.
PF_Cmd_SEQUENCE_FLATTEN
Sent when the After Effects project is written to disk.

PF_Cmd_ABOUT
Sent when the user selects About from the effect control window (ECW).

PF_Cmd_GLOBAL_SETDOWN
Will be sent when After Effects is closed, or when the effect of the last instance is removed. Don't rely on this message to determine when the plugin is removed from memory; use os-specific entry points.

Table 4: COMMAND SELECTORS

Selectorresponse
Global selectorAll plugins must respond to these selectors.
PF_Cmd_ABOUTA dialog box describing the plug-in is displayed. filling
out_data>return_msg
And After Effects will display it in a simple modal dialog. Include the version information of the plug-in in the dialog box. On macOS, the current resource file will be set as your effects module during this selector.
PF_Cmd_GLOBAL_SETUPSet any required flags and
PF_OutData
Fields (including
out_data>my_version
) To describe the behavior of the plug-in.
PF_Cmd_GLOBAL_SETDOWNRelease all global data (only needed when some data is allocated).
PF_Cmd_PARAM_SETUPDescribe your parameters and use
PF_ADD_PARAM
Register them. In addition, register custom user interface elements. Set up
PF_OutData>num_params
To match your parameter count.
Sequence selectorThese control sequence data processing.
PF_Cmd_SEQUENCE_SETUPAllocate and initialize any sequence-specific data. Sent when the effect is first applied.
PF_InData
It is initialized at this time.
PF_Cmd_SEQUENCE_RESETUPRe-create (usually restore) sequence data. Send after the sequence data is read from the disk, during the pre-combination process, or when the effect is copied; After Effects flattens the copy before the sequence data. During the copy process, the old sequence and the new sequence are sent
PF_Cmd_SEQUENCE_RESETUP
. Don't expect
PF_Cmd_SEQUENCE_RESETUP
between s
PF_Cmd_SEQUENCE_FLATTEN
.
PF_Cmd_SEQUENCE_FLATTENSent when the sequence is saved and copied. Flatten sequence data containing pointers or handles so that it can be written to disk. This will be saved with the project file. Release the unflattened data and
out_data>sequence_data
Set to point to the new flattened data. Flat data must be used for file storage correctly in byte order.
In version 6.0, if the sequence data of an effect has been smoothed out recently, the effect can be used without receiving additional
PF_Cmd_SEQUENCE_SETDOWN
The case is deleted. In this case, After Effects will process your flat sequence data.
PF_Cmd_SEQUENCE_SETDOWNRelease all sequence data
Frame selectorEach frame (or set of audio samples) passed to the plug-in for rendering.
PF_Cmd_FRAME_SETUPAllocate any frame-specific data. This will be sent immediately before each frame is rendered to allow setting data for a specific frame. If the effect changes the size of the output buffer, specify the new output height, width, and relative origin. All parameters except the input layer are valid.
If you put
width
with
height
Set to 0, After Effects will ignore your response to the following PF_Cmd_RENDER.
Note: if set
PF_Outflag_I_EXPAND_BUFFER
, You will receive this selector (and
PF_Cmd_FRAME_SETDOWN
) Twice, not once
PF_Cmd_RENDER
Between them. This is to let us know if a given layer is visible.
The frame data can be traced back to the age when the machine might have 8MB RAM. Given the above call sequence, in
PF_Cmd_RENDER
It is much more efficient to allocate during the period.
PF_Cmd_RENDERThe effect is presented to the output according to the input frame and any parameters. This rendering call can only support 8-bit or 16-bit rendering per channel. Each channel rendering of 32 bits must be processed in PF_Cmd_SMART_RENDER.
PF_InData
All fields in are valid. If your response to this selector is interrupted (for
PF_ABORT
or
PF_PROGRESS
The call returns an error code), your results will not be used. Cannot be deleted during selector
frame_data
; You have to wait
PF_Cmd_FRAME_SETDOWN
.
PF_Cmd_FRAME_SETDOWNfreed
PF_Cmd_FRAME_SETUP
Any frame data allocated during the period
PF_Cmd_AUDIO_SETUPSent before every audio rendering. The time span of the requested audio input. Allocate and initialize any sequence-specific data. If the input time span of your effect is not the output time span, then update
PF_OutData
middle
startsampL
with
endsampL
Field.
PF_Cmd_AUDIO_RENDERUse effective audio padding
PF_OutData.dest_snd
.
PF_InData
All fields in are valid. If your response to this selector is interrupted (for
PF_ABORT
or
PF_PROGRESS
The call returns an error code), your results will not be used.
PF_Cmd_AUDIO_SETDOWNfreed
PF_Cmd_AUDIO_SETUP
The memory allocated during the period.
PF_Cmd_SMART_PRE_RENDEROnly applicable to SmartFX. Determine the input fields required for the effect to produce its output based on any criteria implemented by the effect.
It may be sent twice when MediaCore is hosted. The first one will be at
GetFrameDependencies
During the period to collect input. The source checkout can return the full frame size here. Once the sources are rendered, if their size is different from the first call, then this selector will be sent the actual source size a second time to get the correct output size. Note that MediaCore wants all output, so
PF_PreRenderOutput::max_result_rect
Will be used.
16.0 new content
settings
PF_PreRenderOutput
middle
PF_RenderOutputFlag_GPU_RENDER_POSSIBLE
Render on the GPU. If this flag is not set, the requested rendering is not possible with the requested GPU because of parameters or rendering settings. The host may use another
what_gpu
Options (or
PF_GPU_Framework_None
) Recall PreRender.
See the sample code at the bottom of the table
PF_Cmd_SMART_RENDEROnly applicable to SmartFX. Perform rendering and provide output for areas that require rendering
MessagingThe communication channel between After Effects and the plug-in.
PF_Cmd_EVENTThis selector utilizes additional parameters; the type of event to be processed is determined by
e_type
Field indicates that the field is
extra
The member of the structure pointed to. See
Effect UI and events
.
PF_Cmd_USER_CHANGED_PARAMThe log means that the user modifies the parameter value. Only set up
PF_ParamFlag_SUPERVISE
This command will only be received when marking. You can modify the parameter to the control value, or make the value of one parameter affect other parameters. The parameters can be modified through different operations.
in_data.current_time
Is set to the time of the frame that the user sees in the UI (internally, the current time of comp is converted to the layer time), and they are changing the trigger
PF_Cmd_USER_CHANGED_PARAM
Parameters. This is also the time of an automatically added keyframe (if none of them are already, the stopwatch is enabled).
This is usually followed by
PF_Cmd_RENDER
The passed value is the same (unless the caps lock is turned off), but not necessarily-there may be other comp windows open, resulting in the presentation of the changed parameters at different times.
PF_Cmd_UPDATE_PARAMS_UIThe Effect Control Panel (ECP) needs to be updated. This may happen after opening ECP or moving to a new time in the composition. You can call
PF_UpdateParamUI()
To modify the parameter characteristics (for example, enable or disable them).
Only cosmetic changes can respond to this command. In response
PF_Cmd_UPDATE_PARAMS_UI
Do not change the parameter value when; use
PF_Cmd_USER_CHANGED_PARAM
.
Only set in PiPL
PF_OutFlag_SEND_UPDATE_PARAMS_UI
with
PF_Cmd_GLOBAL_SETUP
During the period, this command will be sent periodically.
Note: Never check out parameters in the selector. The bad result of recursion is almost certain.
PF_Cmd_DO_DIALOGThe options dialog box is displayed. Sent when the option button is clicked (or a menu command is selected). This selector will only be sent when the previous effect indicates that it has a dialog box (by setting the global
PF_OutFlag_I_DO_DIALOG
Sign to respond
PF_Cmd_GLOBAL_SETUP
). In version 3.
PF_Cmd_DO_DIALOG
The passed parameter is invalid. This is no longer the case; plug-ins can access non-layer parameters, check out parameters at other times, and
PF_Cmd_DO_DIALOG
During the UI update is performed. They still may not change the value of the parameter.
PF_Cmd_ARBITRARY_CALLBACKManage any data type. This parameter will only be received when the custom data type parameter is registered. The extra parameter indicates which handler function is being called. Custom data types will be discussed further in the implementation.
PF_Cmd_GET_EXTERNAL_DEPENDENCIESOnly if
PF_Cmd_GLOBAL_SETUP
Set during
PF_OutFlag_I_HAVE_EXTERNAL_DEPENDENCIES
Sent when. Fill a string handle with the description of the plugin dependency (in
PF_ExtDependenciesExtra
In), to ensure that it is terminated
NULL
Character allocation space. If there is no dependency to report, only the string handle is returned
NULL
pointer.
If the inspection type is
PF_DepCheckType_ALL_DEPENDENCIES
, Then report all the content that the plug-in may need to render. If the inspection type is
PF_DepCheckType_MISSING_DEPENDENCIES
, Only the missing items are reported (if there are no missing items, an empty string is reported).
PF_Cmd_COMPLETELY_GENERALRespond to an AEGP. The extra parameters point to any parameters sent by AEGP. aegp can only communicate with effects that respond to this selector.
PF_Cmd_QUERY_DYNAMIC_FLAGSSend only to
PF_OutFlags2
In its PiPL and in
PF_Cmd_GLOBAL_SETUP
Period specified
PF_OutFlag2_SUPPORTS_QUERY_DYNAMIC_FLAGS
Plugins. For all dynamic flags, if you want to make changes during this command, you must
PF_Cmd_GLOBAL_SETUP
Set the flag to
on
.
The selector will be sent at any time. In response, the effect should use
PF_CHECKOUT_PARAM
Access its (non-layer) parameters and decide if any support should be set
PF_Cmd_QUERY_DYNAMIC_FLAGS
Logo, for example:
PF_OutFlag_WIDE_TIME_INPUT

PF_OutFlag_NON_PARAM_VARY

PF_OutFlag_PIX_INDEPENDENT

PF_OutFlag_I_USE_SHUTTER_ANGLE

PF_OutFlag2_I_USE_3D_CAMERA

PF_OutFlag2_I_USE_3D_LIGHTS

PF_OutFlag2_DOESNT_NEED_EMPTY_PIXELS

PF_OutFlag2_REVEALS_ZERO_ALPHA

PF_OutFlag2_DEPENDS_ON_UNREFERENCED_MASKS

PF_OutFlag2_OUTPUT_IS_WATERMARKED

After Effects uses this information for caching and optimization purposes, so please try to respond as quickly as possible.
16.0 newAdded support for GPU effects
PF_Cmd_GPU_DEVICE_SETUPThe host can call this selector at any time. It is called at most once per GPU device. Multiple GPU devices may be in the setup state at once. will be
GlobalSetup
After and
SequenceSetup
Call it before. The purpose is to make the effect GPU initialization when necessary, and give the effect the opportunity to opt out of the GPU device based only on the properties of the device instead of any rendering context (frame size, etc.). If the effect rejects the GPU device, it will be called for CPU rendering. should be
PF_InData::what_gpu = PF_GPU_Framework_None
. If supported
what_gpu
Devices and frameworks in the system, the expected effect will be set
PF_OutData:: out_flags2
middle
PF_OutFlag2_SUPPORTS_GPU_RENDER_Fxx
One or two of the signs. Please note that only
PF_OutFlag2_SUPPORTS_GPU_RENDER_F32
Will be in AE 16.0. The effects that are not set here will not be considered to support GPU rendering on any of these devices.
PF_GPUDeviceSetupOutput::gpu_data
Is a pointer owned by the plug-in and must be related to
PF_Cmd_GPU_DEVICE_SETDOWN
The selector is released together. This pointer is also available during rendering.
PF_Cmd_GPU_DEVICE_SETDOWNRelease all resources related to gpu_data. In AE, this will be called before the GPU device is released.
PF_Cmd_GPU_SMART_RENDER_GPUWith existing
PF_Cmd_SMART_RENDER
The GPU equivalent to the selector. When rendering, will call
PF_Cmd_SMART_RENDER
or
PF_Cmd_SMART_RENDER_GPU
The selector, depending on whether the desired effect is to produce CPU or GPU frames as output. Only if
what_gpu! = PF_GPU_Framework_None
Called when
PF_Cmd_SMART_RENDER_GPU
And for any input/output
PF_LayerDef
All have an impact. When doing this selector, all frame check-in and check-out will be done on the GPU frame. note
PF_Cmd_SMART_RENDER
Share the extra structure
of the extra input of the GPU-related selector
what_gpu
with
device_index
The field indicates the GPU framework plug-in used for rendering. Input and output buffers will be prepared on this frame and device. can use
PrSDKGPUDeviceSuite :: GetDeviceInfo
Query device, context, command queue and other related GPU status.
PF_Cmd_SMART_PRE_RENDER
with
PF_Cmd_SMART_RENDER_GPU
Between selector calls
what_gpu
the same

PF_Cmd_SMART_PRE_RENDER

typedef struct { PF_RenderRequest output_request; //what the effect is being asked to render short bitdepth; //bitdepth the effect is being driven in (in bpc) const void *gpu_data; //(new AE 16.0) PF_GPU_Framework what_gpu; //(new AE 16.0) A_u_long device_index; //(new AE 16.0) For use in conjunction with PrSDKGPUDeviceSuite } PF_PreRenderInput; Copy code

PF_Cmd_GPU_DEVICE_SETDOWN

typedef struct { void *gpu_data; //effect must dispose. PF_GPU_Framework what_gpu; A_u_long device_index; //For use in conjunction with PrSDKGPUDeviceSuite } PF_GPUDeviceSetdownInput; typedef struct { PF_GPUDeviceSetdownInput input; } PF_GPUDeviceSetdownExtra; Copy code

PF_Cmd_GPU_SMART_RENDER_GPU

typedef struct { PF_RenderRequest output_request; //what the effect is being asked to render short bitdepth; //bitdepth the effect is being driven in (in bpc) void *pre_render_data; //passed back from value placed in extra->output-> pre_render_data during PF_Cmd_PRE_RENDER const void *gpu_data; //(new AE 16.0) PF_GPU_Framework what_gpu; //(new AE 16.0) A_u_long device_index; //(new AE 16.0) } PF_SmartRenderInput; typedef struct { PF_SmartRenderInput *input; PF_SmartRenderCallbacks *cb; } PF_SmartRenderExtra; Copy code

difference

PF_Cmd_USER_CHANGED_PARAM
with
PF_Cmd_UPDATE_PARAMS_UI
There are subtle differences between them. The effect needs to distinguish that the user is actually changing the parameter value (
PF_Cmd_USER_CHANGED_PARAM
), or just sliding on the timeline (
PF_Cmd_UPDATE_PARAMS_UI
, This will also be sent when the plugin is first loaded).

PF_INDATA

After Effects uses PF_InData to convey system, project, layer and audio information. This structure will be updated before each command selector is sent to the plug-in. Record the fields that are valid only during a specific PF_Cmds period. Also, don't worry; although PF_InData is large, you don't have to remember the purpose of each member; you sometimes use certain fields.

Table 5: PF_INDATA

Field namedescription
interUsed for user interaction, add parameters, check whether the user has interrupted the effect, display the progress bar, and get the source frame and parameter value callback at other times than the current rendering time. This very useful feature suite is described in "Interactive Callback Functions".
utilsGraphics and math callbacks. This pointer is always defined.
effect_refOpaque data that must be passed to most of the various callback routines. After Effects uses this to recognize your plug-in.
qualityThe current quality setting, i.e.
PF_Quality_HI
or
PF_Quality_LO
. The effect is
LO
The execution speed in should be faster, while in
HI
The effect in should be more accurate. The graphics utility callback is in
LO
with
HI
The way of execution differs between quality. Your effect should be the same! This field is defined in all frame and sequence selectors.
versionThe effect specification version, indicated in
PF_Cmd_GLOBAL_SETUP
The version required to run successfully during the period.
serial_numThe serial number of the calling application.
appl_idThe identifier of the calling application. If your plug-in runs in After Effects, appl_id contains the application creator code "
FXTC
". If it runs in Premiere Pro, it will be "
PrMr
". Use it to test whether you are permitted to use your plug-in with one application and use it with another.
num_paramsEnter the parameter count.
what_cpuUnder macOS, it contains the Gestalt value of the CPU type (see Inside Macintosh, Volume 6). Undefined on Windows.
what_fpuUnder macOS, it contains Gestalt values of FPU type. Undefined on Windows.
current_timeThe rendering time of the current frame, in
PF_Cmd_RENDER
Valid during the period. This is the current time in the layer, not any composition. If the layer starts or stretches in time outside of time 0, the layer time and composition time will be different.
The current frame number is
current_time
Divide by
time_step
. The current time (in seconds) is
current_time
Divide by
time_scale
.
In order to deal with time extensions, composition frame rate changes and time remapping, After Effects may require effects to be rendered in non-integer time (between two frames). Be prepared for this; don't assume that you are only asked to provide frames on frame boundaries.
Note: Starting from CS3 (8.0), it may need to be called when the time is negative.
time_stepThe duration of the current source frame being rendered. In several cases with nested composition, the source frame duration may be different from the time span between frames in the layer (
local_time_step
). Can be divided by
time_scale
Convert this value to seconds.
When calculating other source frame times (for example, for
PF_CHECKOUT_PARAM
), use this value instead of
local_time_step
.
If the layer is time-reversed, it can be negative. If time remapping is applied to a nested composition, it may vary from one frame to the next.
When the source material is stretched or remapped in a nested composition, it may differ from
local_time_step
different. For example, this can happen when internal compositions are nested within external compositions with different frame rates or when time remapping is applied to external compositions.
If the value is not constant in all frames, then
PF_Cmd_SEQUENCE_SETUP
During this time, the value will be 0. will be
PF_Cmd_FRAME_SETUP and PF_Cmd_FRAME_SETDOWN
Correctly set in the selector.
Warning: this can be zero, so check it before dividing.
total_timeThe duration of the layer. If the time stretch of the layer is longer than 100%, the value will be adjusted accordingly; but if the layer is shorter in time, the value will not be affected. If time remapping is enabled, this value is the duration of the composition. Can be divided by
time_scale
Convert this value to seconds.
local_time_stepThe time difference between frames in the layer. Affected by any temporal stretch applied to the layer. If the layer is time-reversed, it can be negative. versus
time_step
Different, this value is constant from one frame to the next. Can be divided by
time_scale
Convert this value to seconds.
For a step value that is constant throughout the entire frame of the layer, use
local_time_step
, It is based on the composite frame rate and layer stretching.
time_scale
current_time
,
time_step
,
local_time_step
with
total_time
The unit per second. in case
time_scale
Is 30, then
current_time
,
time_step
,
local_time_step
with
total_time
The unit of one second is 30. then
time_step
It may be 3, which means that the sequence is actually rendered at 10 frames per second.
total_time
It may be 105, which means that the sequence is 3.5 seconds long.
fieldOnly when
PF_Cmd_GLOBAL_SETUP
Set during
PF_OutFlag_PIX_INDEPENDENT
Time effective. Check this field to see if you can only process the fields above or below.
shutter_angleMotion blur shutter angle. The value range is 0 to 1, representing 360 degrees. Unless motion blur is enabled and the target layer is checked, it will be zero.
shutter_angle == 180
Means
current_time
with
current_time
Time interval between
+ 1/2 time_step
. only at
PF_Cmd_GLOBAL_SETUP
Set during
PF_OutFlag_I_USE_SHUTTER_ANGLE
Time effective.
For details on how to achieve motion blur in the effect, see the "Motion Blur" section.
width
height
The size of the source layer is not necessarily the same as the width and height fields in the input image parameters. The buffer size adjustment effect may cause this difference. Not affected by downsampling.
extent_hintThe intersection of the visible parts of the input and output layers; contains the composite rectangle converted to layer coordinates. Iterating on only this rectangular pixel can speed up the effect significantly. For correct usage, see the notes at the end of this chapter.
output_origin_x
output_origin_y
The origin of the output buffer in the input buffer. It is non-zero only when the effect changes the origin.
downsample_x
downsample_y
The point control parameters and layer parameter sizes are automatically adjusted to compensate for the situation where the user tells After Effects to render only the nth pixel. The effect requires a downsampling factor to explain the scalar parameter (such as a slider) that represents the distance between pixels in the image. For example, if the downsampling factor in each direction is 1/2 (the downsampling factor is expressed as a ratio), a 4 pixel blur should be interpreted as a 2 pixel blur
PF_Cmd_SEQUENCE_SETUP
,
PF_Cmd_SEQUENCE_RESETUP
,
PF_Cmd_FRAME_SETUP
,
PF_Cmd_FRAME_RENDER
.
pixel_aspect_ratioPixel aspect ratio (aspect ratio).
in_flagsNot used.
global_data
sequence_data
frame_data
Data stored by the plugin during other selectors. Before and after calling the plug-in, it is locked and unlocked by After Effects.
start_sampLThe starting sample number, relative to the starting position of the audio layer.
dur_sampLThe duration of the audio, expressed as the number of samples. Specific to audio.
total_sampLThe sample in the audio layer; equivalent to the total_time represented in the sample.
src_sndPF_SoundWorld describes the input sound. Specific to audio.
pica_basicPPointer to PICA Basic kit, used to get other kits.
pre_effect_source_origin_x
pre_effect_source_origin_y
The origin of the source image in the input buffer. It is valid only when sending with the frame selector. It is only non-zero if one or more effects before this effect on the same layer have adjusted the size of the output buffer and moved the origin. Check the resize and new origin to determine the output area. This is useful for effects with implicit spatial operations (except point controls), such as flipping a file around the center of the image.
Note: The detection point parameters are adjusted for the pre-effect origin of the current time (not the detection time).
shutter_phaseThe offset from the frame time to the shutter opening time (expressed as a percentage of the frame duration)

EXTENT_HINT usage

(Note: The prompt rectangle is more effective for SmartFX... and more complicated...)

use

extent_hint
Only process those pixels that need to be output; this is one of the simplest optimizations you can make. Pass in
PF_Cmd_GLOBAL_SETUP
(And your PiPL) in
PF_OutData
Middle setting
PF_OutFlag_USE_OUTPUT_EXTENT
To tell After Effects that you use
in_data> extent_hint
.

Under test

extent_hint
Before you code, please disable caching from the preferences menu, so as long as anything in the composition changes, After Effects will render your effect. Otherwise, the caching mechanism will obscure the (possibly incorrect) output of your plugin.

Move the layer in the composition so that it can be cropped.

output>extent_hint
It is the part of the layer that is visible in the composition. Add a mask on your layer and move it around. This will change
range_hint
, It will surround all non-zero alpha areas of the image.
in_data> extent_hint
It is the intersection of these two rectangles (composition and mask), and they change whenever they change.

Before resizing and origin offset, the range rectangle will be calculated in the coordinate space of the original input layer to simplify the setting

PF_OutFlag_PIX_INDEPENDENT
The rectangles between the input and output ranges of the effect intersect. To get the output range in the coordinate system of the output buffer, please pass
PF_InData>output_origin_x
with
y
Field will
tent_hint
Offset.

Consider downsampling when calculating the output size; the user must be able to render at full resolution. If the output buffer exceeds 30,000 x 30,000, limit it to that size and consider displaying an alert dialog.

After the code runs correctly, enable caching and see how long it takes to re-render the effect. Consider a shadow; users often apply static shadows to still images.

output> extent_hint
Ignored, so the cache is used more frequently.

To get the buffer expansion effect, please

output> extent_hint
Intersect with the conversion range of the plug-in, and
PF_Cmd_FRAME_SETUP
Set the size accordingly during the period.

Now there are 20% more pixels!

Starting from version 6.0, delivered

extent_hints
It is 20% larger than the layer itself to help us make predictive rendering decisions. Many effects can expand the buffer just by touching, and After Effects will often use the prompt rectangle in the future.

Point control and buffer expansion

Pass in

PF_Cmd_FRAME_SETUP
During
PF_InData
Middle setting
set output_origin_x/y
The effect to expand the output buffer is located in the upper left corner of the original layer. in
pre_effect_source_origin_x/y
The impact of this shift on subsequent performance is reported in. The point parameters are automatically adjusted for the shift.

Before the effect takes effect, apply a buffer extender, such as Gaussian Blur or the Resizer SDK sample, and use a larger resize value. If your effect is not handled properly

pre_effect_source_origin_x/y
, Then turning the blur on and off will change the position of the output.

All point parameter values (at any time) have

pre_effect_source_origin_x/y
The offset value of the description. For most effects, this is transparent. However, if the buffer expansion changes over time (like the amount of animation blur), the origin offset will move the non-animated point. Please take this into consideration when designing the effect of buffering point parameter values between frames.

original

This chapter will provide all the information you need to know to understand how a basic effect plug-in works. These details are fundamental to every effect plug-in. By the time you finish this chapter, you'll be ready for the fun stuff ; modifying pixels!

All communication between After Effects and an effect plug-in is initiated by After Effects, and it all happens by the host (After Effects) calling a single entry point function. For all effect plug-ins, the entry point function must have the following signature:

PF_Err main ( PF_Cmd cmd, PF_InData *in_data, PF_OutData *out_data, PF_ParamDef *params[], PF_LayerDef *output, void *extra) Copy code

The name of the entry point function above is main , but it can be whatever is specified in the PiPL resource.

Before each call to the entry point function, After Effects updates PF_InData and the plugin's parameter array PF_ParamDef[] (except as noted). After the plug-in returns from its call, After Effects checks PF_OutData for changes and, when appropriate, uses the PF_LayerDef the effect has rendered.

Commands are, simply, what After Effects wants your effect to do. Responses to some selectors are required; most are optional, though recall that we did add them for a reason...

With each command selector sent, effects receive information from After Effects in PF_InData, input and parameter values in PF_ParamDef[] (an array of parameter descriptions including the input layer), and access to callbacks and function suites. They send information back to After Effects in PF_OutData, and (when appropriate) render output to a PF_LayerDef, also called a PF_EffectWorld. During events, they receive event-specific information in extra.

Only the first few command selectors are predictable; the rest of the calling sequence is dictated by user action.

When first applied, a plug-in receives PF_Cmd_GLOBAL_SETUP, then PF_Cmd_PARAM_SETUP. Each time the user adds the effect to a layer, PF_Cmd_SEQUENCE_SETUP is sent.

For each frame rendered by a basic non-SmartFX effect, After Effects sends PF_Cmd_FRAME_SETUP, then PF_Cmd_RENDER, then PF_Cmd_FRAME_SETDOWN. All effect plug-ins must respond to PF_Cmd_RENDER.

For SmartFX, PF_Cmd_SMART_PRE_RENDER may be sent any number of times, before a single PF_Cmd_SMART_RENDER is sent.

PF_Cmd_SEQUENCE_SETDOWN is sent on exit, when the user removes an effect or closes the project. PF_Cmd_SEQUENCE_RESETUP is sent when a project is loaded or when the layer to which it's applied changes. PF_Cmd_SEQUENCE_FLATTEN is sent when the After Effects project is written out to disk.

PF_Cmd_ABOUT is sent when the user chooses About from the Effect Controls Window (ECW).

PF_Cmd_GLOBAL_SETDOWN is sent when After Effects closes, or when the last instance of the effect is removed. Do not rely on this message to determine when your plug-in is being removed from memory; use OS-specific entry points.

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.

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.

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.