Parameters

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_PARAM_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.


Parameter Types

Parameter Type Parameter Type PF_ParamDefUnion Member Param Value Data Type Description
PF_Param_LAYER PF_LayerDef ld A_long

Image and audio layers in the composition. All effects automatically have at least 1 layer parameter, param[0], the layer to which they are applied.

When used as effect parameters, these appear as a pull-down menu with which the user selects a layer within the current composition.

The pull-down menu contents are generated by After Effects.

NOTE: This is a reference to a layer which contains pixels and audio samples, not actual pixels and audio samples.

PF_Param_SLIDER PF_SliderDef sd long No longer used.
PF_Param_FIX_SLIDER PF_FixedSliderDef fd PF_Fixed

Deprecated. For many years, we promoted fixed sliders. We now recommend PF_Param_FLOAT_SLIDERs.

The additional precision helps in many situations, and isn’t as expensive as it once was. Plus, we’re just tired of low byte / high byte silliness.

FIX_SLIDERs provide higher precision than PF_Param_SLIDER. Specify the UI decimal places independently. Ignore the low word of the PF_Fixed to get integral results.

PF_Param_FLOAT_SLIDER PF_FloatSliderDef fs_d PF_FPLong

Sliders represent numerical values. FLOAT_SLIDERs contain values for phase, precision, and curve tolerance for use by audio filters.

Specify a minimum and maximum value, and the user can move a slider or types a number to specify the setting.

PF_Param_FLOAT_SLIDERs also respond to slider flags discussed in Audio Filters.

PF_Param_ANGLE PF_AngleDef ad PF_Fixed

Angles in (fixed point) degrees, accurate to small fractions of a degree.

Users can specify multiple revolutions, resulting in values greater than 360.

PF_Param_CHECKBOX PF_CheckBoxDef bd PF_Boolean PF_ParamFlag_CANNOT_INTERP is forced on for all checkboxes.
PF_Param_COLOR PF_ColorDef cd PF_Pixel

RGB value (alpha is not used) that the user can choose either with the standard color picker or with an eye dropper tool.

For floating point accuracy, use PF_ColorParamSuite1 to retrieve the values.

PF_Param_POINT PF_PointDef td PF_Fixed

A two-dimensional point. The point provides x and y values in destination layer space.

The origin of the layer is the upper-left hand corner, with x increasing to the right, y increasing down.

Starting in CS5.5, for floating point accuracy, use PF_PointParamSuite1 to retrieve the values.

Dusty history lesson to follow: Prior to API specification version 12.1 (After Effects 4.0), the default value for the point was between 0 and 100 in fixed point with the radix point at bit 16 (i.e. standard fixed point).

Specifying (50,50) in fixed point yields the center of the image. The value you are returned for a point control is in absolute pixels with some number of bits of fixed point accuracy.

Thus, if you gave (50,50) as the default position and the user applied the effect to a 640 by 480 layer, the default value you would be sent would be (320, 240) in Fixed point.

Plug-ins which specify API versions before 12.1 will still get the old behavior.

PF_Param_POPUP PF_PopupDef pd A_long

List of choices. Build a string in namesptr containing a list of (read-only) pop-up entries (“Entry1 / Entry2 / Entry3”).

After Effects copies the data and creates a pop-up menu.

These entries cannot be modified once the parameter is added.

An entry of “(-” will result in a separator being drawn between previous and subsequent entries.

PF_Param_ARBITRARY_DATA PF_ArbitraryDef arb_d ???

Custom data type.

Arbitrary Data Parameters contain an ID (you can use more than one custom data type in a given effect), a default value (so After Effects knows what your data type should start as), and a handle to your actual parameter.

In AE, must specify either PF_PUI_TOPIC / PF_PUI_CONTROL or PF_PUI_NO_ECW.

In PPro 8.0 and later, it’s okay to set none of those flags, which allows you to see the parameter’s keyframe track on the right side of Effect Controls without creating a custom control.

PF_Param_PATH PF_PathDef path_d PF_PathID

Path parameters are references to masks applied to the same layer as the effect.

Path parameter data cannot be accessed directly; use PF_PathQuerySuite1 and PF_PathDataSuite to manage and inquire about paths.

PF_PathDef.path_id contains the index of the mask selected by the user.

A corresponding AEGP_MaskRefH can be obtained using AEGP_GetLayerMaskByIndex from AEGP_MaskSuite6.

PF_Param_GROUP_START PF_Param_GROUP_END (none) (none)    

Parameter groups (topics) organize parameters into sets.

Each group receives its own twirly and will be indented in the ECP relative to the neighboring parameters or groups.

One group can be nested within another.

Each twirly can be spun open or closed by the user, or programatically by the effect.

The effect may choose to have certain groups initialized with the twirly spun open, and others with the twirly spun closed.

PF_Param_BUTTON PF_Button button_d (no value)

A simple push button. Use Parameter Supervision to detect when the button is pressed.

New in CS5.5 to After Effects.

PF_Param_POINT_3D PF_Point3D point3d_d PF_FpLong (3)

A three-dimensional point.

New in CS5.5. Unsupported in Premiere Pro.


Slider Range Issues?

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.


Point Parameter Origin

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.