Chapter 2 Basics of Effects
Links to other articles
Table 6: PF_OUTDATA
|my_version||Put this flag (using |
PF_VERSIONMacro) is set to the version of the plug-in code. After Effects uses this data to determine which duplicate effect to load.
|global_data||Will be called every time |
PF_InDataThe handle returned to you. Use the memory allocation function of After Effects.
|num_params||After Effects calls |
PF_ADD_PARAMThe number of times to check this field, as well as the implicit input layer.
|sequence_data||This handle is receiving |
PF_Cmd_SEQUENCE_SETUPCan be allocated afterwards, and in all subsequent calls, this handle will be
PF_InDataPass it to you.
|flat_sdata_size||Unused (After Effects knows the size because you use its allocation function to get memory in the first place).|
PF_Cmd_FRAME_SETUPHandle allocated during the period. This is never written to disk; it is used to remove information from your
PF_Cmd_FRAME_SETUPThe response is delivered to your
PF_Cmd_FRAME_SETDOWN(If you adjust the size of the output buffer, you must do this). Otherwise, this memory is rarely used.
|width, height, origin||If the output image size is different from the input, please |
PF_Cmd_FRAME_SETUPSet during the period. The width and height are the size of the output buffer, and the origin is the point where the input should be mapped to the output. To create a 5-pixel up-and-down projection, set the origin to (5,5).
|out_flags||Send a message to After Effects. Or multiple values together.|
|return_msg||After Effects will display any C strings you place here (check and clear after each command selector).|
|Only for audio commands|
|out_flags2||Send a message to After Effects. Or multiple values together.|
These signs convey function and status information to After Effects. In previous versions, they were also used to send basic messages, such as refreshing the UI and sending error messages. These features have been replaced by the feature suite, and all new messaging features will appear in this format. However, the capability flag is still included in PiPL. When making changes, update PiPL and source code at the same time. Many of these flags can be changed in the After Effects session.
Table 7: PF_OUTFLAGS
|PF_OutFlag_KEEP_RESOURCE_OPEN||The resources of the plug-in must be available during the execution of all commands. in|
PF_Cmd_GLOBAL_SETUPDuring the period, the resources of the plug-in are always open, but they are not available at any other time (
PF_Cmd_DO_DIALOGExcept period), unless this flag is set. If you need to
PF_Cmd_GLOBAL_SETUPTo access the resource at any time outside the period, please set it up. Note: We recommend that the plugin load and store the necessary resources in the global data, instead of keeping the resources of the file open
|PF_OutFlag_WIDE_TIME_INPUT||The effect is in addition to |
current_timeA parameter is detected outside of the time. If you use another time parameter (including layer parameters), set this flag. Otherwise, After Effects will not correctly invalidate the effects used by the cached frame. in
If you set this flag, we strongly recommend that you also set
PF_OutFlag2_AUTOMATIC_WIDE_TIME_INPUTFor better performance.
|PF_OutFlag_NON_PARAM_VARY||After setting this flag, when the effect is applied to a static effect, After Effects will not cache the output. Otherwise, if possible, After Effects will cache your output for use in rendering other frames. |
If the output changes based on something other than the parameter value, set this flag. If the effect is applied to the still image and all parameters are constant when the effect produces a changing frame, this is a definite sign, and this should be set (such as wave). For example, particle effects need this.
PF_Cmd_GLOBAL_SETUPSettings. If needed, you can
PF_Cmd_QUERY_DYNAMIC_FLAGSDynamic rewrite during the period. If possible, turn off this feature to improve performance.
|PF_OutFlag_SEQUENCE_DATA_NEEDS_FLATTENING||Both After Effects and Premiere Pro assume this flag is set. When the sequence data contains reference items (pointers, handles), flattening is necessary, and these reference items must be flattened for storage, not flattened for use. reference|
|PF_OutFlag_I_DO_DIALOG||Effect display dialog response |
Note: the effect is right
PF_OutFlag_I_DO_DIALOGThe response is irrevocable. You can use any data in the custom UI, if such changes are required.
|PF_OutFlag_USE_OUTPUT_EXTENT||The effect will be respected |
PF_Cmd_GLOBAL_SETUPSet up. See the correct usage at the end of this chapter for details.
Note: No longer used in SmartFX
|PF_OutFlag_SEND_DO_DIALOG||The effect must display the dialog box function (added as a compatible Photoshop plug-in). After Effects send|
PF_Cmd_SEQUENCE_RESETUPSet during instead of
|PF_OutFlag_DISPLAY_ERROR_MESSAGE||Show in error dialog |
return_msgWhen it is non-null, After Effects will display the content in a dialog box. If this flag is set, an error dialog box will appear. It is set after any command and can be used during debugging. This is also a good way to implement nag messages for the trial version.
|PF_OutFlag_I_EXPAND_BUFFER||Effect expands the output buffer. in|
PF_Cmd_GLOBAL_SETUPSet up. Set this flag and
PF_OutFlag_USE_OUTPUT_EXTENTIn order to
PF_Cmd_FRAME_SETUPUse output during
extent_rectThe intersection with the new buffer size. use
pre_effect_source_originField to detect other conversions.
Note: This flag is only set when needed; it greatly reduces the cache efficiency.
Note: It is no longer used in SmartFX
|PF_OutFlag_PIX_INDEPENDENT||A given pixel is independent of the pixels around it. in|
PF_Cmd_QUERY_DYNAMIC_FLAGSIn the settings. For example, color correction effects are usually pixel-independent, while distortions are not.
Note: If your effect does not use the color value of one pixel to affect the color value of adjacent pixels, set this flag! It can provide significant performance improvements.
|PF_OutFlag_I_WRITE_INPUT_BUFFER||The effect is written to the input buffer. This is of limited use; it invalidates some pipeline caches when saving allocations. in|
|PF_OutFlag_I_SHRINK_BUFFER||This effect will be based on |
extent_rectShrink its buffer to achieve higher memory efficiency. in
PF_Cmd_GLOBAL_SETUPSet as much as possible during the period.
Note: No longer used in SmartFX
|PF_OutFlag_CUSTOM_UI||The effect has a custom user interface and requires |
|PF_OutFlag_REFRESH_UI||Refresh the entire effect controls, composition and layer windows. in|
PF_Cmd_DO_DIALOGIn the settings. If in
PF_Cmd_EVENTDuring the refresh of the custom UI, we recommend using a more fine-grained new redrawing mechanism.
PF_Cmd_FRAME_SETUPSet this flag during the period to invalidate the current rendering.
|PF_OutFlag_I_USE_SHUTTER_ANGLE||Indicates that the rendered image depends on |
|PF_OutFlag_I_USE_AUDIO||The parameters of the effect depend on the audio data, use |
|PF_OutFlag_I_AM_OBSOLETE||The Effect can be used when using the old item it was originally applied to, but it does not appear in the effects menu.|
|PF_OutFlag_FORCE_RERENDER||The effect has been changed and needs to be re-rendered.|
PF_ChangeFlag_CHANGED_VALUEAlso forced to re-render.
|PF_OutFlag_PiPL_OVERRIDES_OUTDATA_OUTFLAGS||After Effects will use PiPL to bid and ignore those in |
PF_Cmd_GLOBAL_SETUPSet during the period.
|PF_OutFlag_I_HAVE_EXTERNAL_DEPENDENCIES||The effect depends on the external file (or external font). If set, After Effects sends|
|PF_OutFlag_DEEP_COLOR_AWARE||Effect processing 16 bpc colors|
PF_Cmd_GLOBAL_SETUPSet this flag during the period to receive
|PF_OutFlag_AUDIO_FLOAT_ONLY||Effect needs |
PF_SIGNED_FLOATFormat audio data. After Effects will perform any required format conversions. You must also set
|PF_OutFlag_AUDIO_IIR||If the (audio) effect is an infinite impulse response filter, in |
PF_Cmd_GLOBAL_SETUPPeriod setting. This is correct if the output at a given time depends on the output at the previous time. When the IIR filter receives
PF_Cmd_AUDIO_RENDER, The input audio time span is the same as the output audio time span (when they are
PF_Cmd_AUDIO_SETUPWhen the requested output time span intersects). In response
PF_Cmd_AUDIO_SETUP, The filter can request early audio (as for the delay effect). The filter can access the earlier parameters and should buffer them (along with temporary audio) in the sequence data. If the generated audio does not match the time of the requested output audio, the duration of the output audio should be set to zero. The filter can update its delay line with parameters and input audio. After buffering its delay line, in
PF_Cmd_AUDIO_SETUPDuring this period, more input audio is requested according to the last buffered delay line. use
PF_HasParamChangedTo determine whether the cache is valid.
|PF_OutFlag_I_SYNTHESIZE_AUDIO||If the effect produces audio, then |
PF_Cmd_GLOBAL_SETUPSet within time, even after silence. You must also set
|PF_OutFlag_AUDIO_EFFECT_TOO||If the effect changes the audio, please |
|PF_OutFlag_AUDIO_EFFECT_ONLY||If the effect only changes the audio output, please |
PF_Cmd_GLOBAL_SETUPSet during the period.
We added a second set of output markers in After Effects 5.0; on the one hand, it is for future expansion, and on the other hand, to break our bad habit of reusing existing flags. Like PF_OutFlags, many of these flags can be changed during an After Effects session. When making changes, don't forget to update PiPL and source code at the same time.
|PF_OutFlag2_SUPPORTS_QUERY_DYNAMIC_FLAGS||Effect response |
PF_Cmd_QUERY_DYNAMIC_FLAGS. Must be set during PiPL and PF_Cmd_GLOBAL_SETUP.
|PF_OutFlag2_I_USE_3D_CAMERA||This effect can access 3D camera information|
|PF_OutFlag2_I_USE_3D_LIGHTS||This effect can access 3D light layer information|
|PF_OutFlag2_PARAM_GROUP_START_COLLAPSED_FLAG||The logo itself does not control |
twirliesstatus. The initial collapsed state of each individual parameter group is in
pf_paramflag_start_collapseThe flag is set. But these personal settings will not be respected unless the effect is set to this. Otherwise, all parameter groups will be collapsed by default. Remember in PiPL and
PF_Cmd_GLOBAL_SETUPSet this flag during the period.
|PF_OutFlag2_I_AM_THREADSAFE||This currently has no effect. If you are interested in this, then you may be interested in the|
|PF_OutFlag2_CAN_COMBINE_WITH_DESTINATION||Premiere was originally added, but it is no longer used.|
|PF_OutFlag2_DOESNT_NEED_EMPTY_PIXELS||Add rendering optimization; shrink the input buffer passed to the effect to exclude any empty pixels (where empty means "zero alpha" unless |
PF_OutFlag2_REVEALS_ZERO_ALPHASetting, RGB must also be zero in this case).
PF_Cmd_QUERY_DYNAMIC_FLAGSIn the settings. The source of the trimmed buffer can be found in
in_data>pre_effect_source_originFound in. This logo and
PF_OutFlag_I_EXPAND_BUFFERThe effect of the collection may be called when the input buffer is empty, and must be able to handle this situation without crashing.
Note: This flag will cause the size of the output buffer to change.
Note: No longer used in SmartFX
|PF_OutFlag2_REVEALS_ZERO_ALPHA||This is the most important thing for logo implementers, because it represents a change in the default behavior. If the effect can use zero alpha pixels and display the RGB data in it, set this flag (just like our Set Channels effect). This tells After Effects not to trim these pixels when determining the input effect. This logo can be in|
PF_Cmd_QUERY_DYNAMIC_FLAGSPeriod change. Please note that although this flag will cause
extent_hintThe size changes, but it does not change the size of the image buffer.
In version 6.0, the pixels outside the bounding box of the mask are set to zero. If your effect can display such pixels, tell AE not to discard these RGB values by setting this flag. If you do not always show the effect of such pixels, a dynamic set this bit
to see if you need to set this bit of effect, significantly less than the application of a layer mask to a solid and then apply effects and set its alpha modification status . If the rectangular bounding box of the mask becomes visible, this bit needs to be set to a set.
|PF_OutFlag2_PRESERVES_FULLY_OPAQUE_PIXELS||Protect those pixels!|
|PF_OutFlag2_SUPPORTS_SMART_RENDER||This effect uses SmartFX API.|
|PF_OutFlag2_FLOAT_COLOR_AWARE||The effect supports 32 bpc floating point color representation. |
PF_OutFlag2_SUPPORTS_SMART_RENDERMust also be set.
|PF_OutFlag2_I_USE_COLORSPACE_ENUMERATION||This is used to optimize the effect of different color spaces in Premiere Pro. For more details, see|
Premiere Pro SDK.
PF_Cmd_GLOBAL_SETUPDuring the setting of this effect, put it in the localized "Obsolete" folder, in the effect panel. Compare
|PF_OutFlag2_PPRO_DO_NOT_CLONE_SEQUENCE_DATA_FOR_RENDER||Support in Premiere Pro, not in After Effects. This will affect how Premiere Pro uses multi-threaded driver plug-ins.|
PF_Cmd_GLOBAL_SETUPSet up. Need to set
PF_OutFlag_WIDE_TIME_INPUT(This allows you to support old hosts), but will actually override the flag.
After setting, all parameters will be tracked and checked out, so that the host can understand the timeout dependency, which is more efficient. For example, if you only set the old
PF_OutFlag_WIDE_TIME_INPUT, Then any time anything changes, it will be called to re-render. With this flag, if the content of a given 17th frame has been detected 0-17 times, AE will know that any changes above the 18th frame will not affect the buffered frames.
Note that if you use this new flag, you must not cache any time-related data (or any other place) in your sequence data, unless you also verify the cache usage
PF_GetCurrentState()/PF_AreStatesIdentical()Previously used time-dependent data.
This only applies to SmartFX (those settings
PF_OutFlag2_SUPPORTS_SMART_RENDER). If you don t set it, After Effects will silently use it as
PF_Cmd_GLOBAL_SETUPSet up. This lets AE know that if the composition start time and/or drop-down box settings are modified, it should render an effect.
|PF_OutFlag2_DEPENDS_ON_UNREFERENCED_MASKS||New in CS6. If you want to view a path that is not directly referenced in the path parameter, set this, for example, if you want to draw a stroke on all masks. This is needed, so After Effects knows that when a mask is modified, it does not appear to be referenced by your effect and your output is invalid. in|
PF_Cmd_QUERY_DYNAMIC_FLAGSIn the settings.
|PF_OutFlag2_OUTPUT_IS_WATERMARKED||New in CS6. in|
PF_Cmd_GLOBAL_SETUPSet this value during the period, if your output will be watermarked in some way, making it unsuitable for final use, it may be because the user is using an unauthorized demo version. in
PF_Cmd_QUERY_DYNAMIC_FLAGSIt is possible to change this status during the application session, for example, the floating license status has changed.
Plug-in authors that truly change this state asynchronously must be careful to let the next rendering match from
PF_Cmd_QUERY_DYNAMIC_FLAGSReturn the last state, otherwise race conditions may cause incorrect frames to be buffered. (If you are only responding
DO_DIALOGWhen modifying this, this is not a problem. )
|PF_OutFlag2_SUPPORTS_GPU_RENDER_F32||New in 16.0. in|
PF_Cmd_GLOBAL_SETUPMedium setting, which means GPU support. This effect will be called by the GPU selector and will be marked as GPU supported in the GUI. in
PF_Cmd_GPU_DEVICE_SETUPAt the time, these signs indicate the rendering capabilities of specific devices and frames.
Parameters are a stream of values that change over time; source image, slider, angle, point, color, path, and any arbitrary data type that the user can manipulate. They are
One of the best aspects of the After Effects Effect API is parameter interpolation and management. How much does the shutter angle change in a quarter of 29.97? It's not your problem; leave it to After Effects.
Table 9: Parameter types
|Parameter Type||Parameter type |
parameter value data type
|The composition of the image and audio layers. All effects automatically have at least one layer parameter, parameter , the layer they are applied to. |
When used as effect parameters, these are displayed as a drop-down menu, and the user selects a layer in the current combination. The content of the drop-down menu is generated by After Effects.
Note: This is a reference to a layer containing pixels and audio samples, not actual pixels and audio samples.
|No longer use|
|Deprecated. For many years, we have been promoting fixed sliders. Now we recommend|
pf_param_float_slider. The extra precision helps in many situations and is not as expensive as it used to be. In addition, we are tired of the stupidity of low byte/high byte.
PF_Param_SLIDERHigher accuracy. Specify the decimal places of the UI independently. ignore
PF_FixedThe low word to get the integral result.
|The slider indicates the value. |
float_sliderContains the phase, accuracy, and curve tolerance values used by the audio filter. Specify the minimum and maximum values, and the user can move the slider or type in a number to specify the settings.
pf_param_float_sliderAlso respond to the slider flag discussed in Audio Filter.
|(Fixed-point) an angle of degree, accurate to a fraction of a degree. The user can specify multiple revolutions, resulting in a value greater than 360.|
PF_ParamFlag_CANNOT_INTERPIt is mandatory for all checkboxes.
|The RGB value (without using the alpha value), the user can use the standard color selector or eyedropper tool to select. For floating point precision, use|
PF_Color_Param_SuiteTo retrieve the value.
|A two-dimensional point. Point provides the target layer space|
yvalue. The origin of the layer is in the upper left corner, with
xIncrease to the right,
yIncrease downward. Starting from CS5.5, for floating-point precision, use
PF_point_Param_SuiteTo retrieve the value.
Follow the dust history lesson: Before the API specification version 12.1 (After Effects 4.0), the default value of the point was a fixed point between 0 and 100, with the decimal point at 16 (that is, the standard fixed point). Specifying a fixed point (50, 50) will generate the center of the image. The value returned by the point control is in absolute pixels and has a certain amount of fixed-point accuracy. Therefore, if you use (50,50) as the default position and the user applies the effect to a 640*480 layer, the default value you will be sent will be (320,240) fixed point. Plugins that specify API versions prior to 12.1 will still get the old behavior.
|Selection list. in|
namesptrConstructs a string containing a (read-only) pop-up list ("
Entry1|Entry2|Entry3"). After Effects copies the data and creates a pop-up menu. Once the parameters are added, these items cannot be modified.
(-"The entry will cause a separator to be drawn between the previous entry and the next entry.
|Custom data type. Any parameter contains an ID (you can use multiple custom data types in a given effect), a default value (so After Effects knows what your data type should start with), and an actual parameter handle. |
Must be specified in AE
PF_PUI_NO_ECW. In pro 8.0 and higher versions, you can not set any of these flags, which allows you to see the key frame track of the parameter on the right side of the effect control without creating a custom control.
|The effect that the mask referenced by the path parameter is applied to the same layer. Cannot directly access path parameter data; use|
PF_PathDataSuiteTo manage and query the path.
PF_PathDef.Path_idContains the index of the mask selected by the user. corresponding
AEGP_MaskRefHable to pass
|-||Parameter groups (topics) organize parameters into sets. Each group receives its own rotation and will be indented relative to the adjacent parameter or group in the ECP. A group can be nested in another group. Each rotation can be turned on or off by the user, or through programmed effects. This effect can choose to initialize some groups to turn on and turn off while other groups are initialized to turn off.|
|In CS5.5 to After Effects. A simple button. Use parameter monitoring to detect when the button is pressed.|
|New in CS5.5. Not supported in Premiere Pro. A three-dimensional point.|
Slider range problem?
If the slider appears to be disabled but not grayed out, please check
The origin of the point parameter
After Effects modifies any point parameter to explain the origin offset, introduced by the "upstream" effect, and modifies the output size. Even if the value of the ECP UI indicator point parameter is (0,0), the offset has been taken into account.
Communicate changes made by your plug-in to After Effects using PF_OutData. Valid times for altering these fields are noted.
These flags communicate capability and status information to After Effects. In previous versions they were also used to send rudimentary messages, eg 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.
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.
Parameters are streams of values that vary with time; the source image, sliders, angles, points, colors, paths, and any arbitrary data types the user can manipulate. They are passed to the plug-in as an array of PF_ParamDefs, though the values in the array are only valid during certain selectors.
One of the best aspects of the After Effects effect API is the parameter interpolation and management. How much does the shutter angle change during one-fourth of a 29.97 fps frame? Not your problem; leave it to After Effects.
Describe your plug-in's parameters during PF_Cmd_PARAMS_SETUP, using PF_ADD_PARAM(). You may have up to (approximately) 38 kajillion parameters, or as many as your users are willing to sift through before demanding a refund. Choose wisely.
Avoid countless problems by clearing PF_ParamDefs with AEFX_CLR_STRUCT (defined in AE_Macros.h) before registering them.
If your slider seems disabled but not grayed out, check the valid_min, slider_min, valid_max and slider_max fields. Is the param a PF_Param_FIX_SLIDER? If so, did you convert your mins and maxs to reasonable fixed values? If you're using the macros provided in AE_Macros.h, they're expecting to receive ints; passing fixed point values won't work.
After Effects modifies any point parameter to account for origin offset, introduced by upstream effects that modify the output dimensions. Even if the ECP UI indicates the value of the point parameter is (0,0), the offset has already been factored in .