Skip to content

Parameter Supervision

Supervision means dynamically changing the values of some parameters based on the values of others. To supervise a parameter, set PF_ParamFlag_SUPERVISE before adding it during PF_Cmd_PARAM_SETUP. Whenever it is changed, you will receive PF_Cmd_USER_CHANGED_PARAM. The index (into the plug-in's parameter array) of the changed parameter is sent in the PF_UserChangedParamExtra (extra) param. During PF_Cmd_USER_CHANGED_PARAM, you may change the values and appearance of any of your parameters.

Updating Parameter UI

If you set PF_ParamFlag_SUPERVISE on any parameter, After Effects will send you PF_Cmd_UPDATE_PARAMS_UI, just as if you had set PF_OutFlag_SEND_UPDATE_PARAMS_UI.

During PF_Cmd_UPDATE_PARAMS_UI, you may only change the appearance and enable state of parameters. Use PF_UpdateParamUI() from PF_ParamUtilSuite3 to update the UI, passing it a copy of the parameter you wish to modify. Do not attempt to modify the original. It is not necessary to set PF_OutFlag_REFRESH_UI; PF_UpdateParamUI() handles that for you.

Note

This is the only way to update the UI of PF_PUI_STD_CONTROL_ONLY parameters.

Updating Parameter Values

A parameter's value (not just UI) can be modified during PF_Cmd_USER_CHANGED_PARAM and during PF_Cmd_EVENT (PF_Event_DO_CLICK, PF_Event_DRAG, & PF_Event_KEYDOWN). After Effects will not honor changes made at other times.

When changing parameter values (and not just the UI), modify the original parameter, and set PF_Paramdef.uu.change_flags to PF_ChangeFlag_CHANGED_VALUE.

This change will be also update the UI, and will be undoable by the user. Note that PF_ChangeFlag_CHANGED_VALUE isn't supported for layer parameters.

This suite is provided to give effect plug-ins some access to their parameter streams, without requiring AEGP suite usage. At least some of these functions are provided by several third-party hosts. These functions are especially handy for effects with supervised parameters.

PF_ParamUtilSuite3

Function

Purpose

PF_UpdateParamUI










 

PF_UpdateParamUI(
  PF_ProgPtr         effect_ref,
  PF_ParamIndex      param_index,
  const PF_ParamDef  *defP);


Force After Effects to refresh the parameter's UI, in the effect controls palette.

Starting in CC 2014, After Effects will now honor a change to a custom UI height. Simply change the ui_height of your custom UI PF_ParamDef and then call PF_UpdateParamUI.

The effect's custom UI height will be updated in the Effect Control Window.

Starting in CS6, when a plug-in disables a parameter, we now save that state in the UI flags so that the plug-in can check that flag in the future to see if it is disabled.

Danger

Never pass param[0] to this function.

PF_GetCurrentState













 

PF_GetCurrentState(
  PF_ProgPtr     effect_ref,
  PF_ParamIndex  param_index,
  const A_Time   *startPT0,
  const A_Time   *durationPT0,
  PF_State       *stateP);


This API, combined with PF_AreStatesIdentical below, lets you determine if a set of inputs (either layers, other properties, or both) are different between when you first called PF_GetCurrentState and a current call, so it can be used for caching. You can specify a range of time to consider or all of time.

Updated in CS6 to add param_index, startPT0, and durationPT0. Pre-defined constants for param_index are as follows:

- PF_ParamIndex_CHECK_ALL - check every parameter, including every layer referred to by a layer parameter.
- PF_ParamIndex_CHECK_ALL_EXCEPT_LAYER_PARAMS - omit all layers. Pass a specific layer parameter index to include that as the only layer parameter tested.
- PF_ParamIndex_CHECK_ALL_HONOR_EXCLUDE - Similar to CHECK_ALL, but honor PF_ParamFlag_EXCLUDE_FROM_HAVE_INPUTS_CHANGED.

Passing in NULL for both start and duration indicates all time.

For effects that do simulation across time and therefore set PF_OutFlag2_AUTOMATIC_WIDE_TIME_INPUT, when you ask about a time range, it will be expanded to include any times needed to produce that range.

Populates a PF_State, an opaque data type used as a receipt for the current state of the effect's parameters (the PF_State is used in our internal frame caching database).

PF_AreStatesIdentical

 

PF_AreStatesIdentical(
  PF_ProgPtr      effect_ref,
  const PF_State  *state1P,
  const PF_State  *state2P,
  A_Boolean       *samePB);


New in CS6. Compare two different states, retrieved using PF_GetCurrentState, above.

PF_HasParamChanged

No longer supported in PFParamUtilsSuite3.

PF_HasParamChanged(
  PF_ProgPtr     effect_ref,
  const          PF_State *stateP,
  PF_ParamIndex  param_index,
  PF_Boolean     *changedPB);


Given a PF_State, passes back true if any of the tested parameters differ from the saved state. Contrary to the name, the call does not provide a way to test a single parameter.

At a minimum, all non-layer parameters will be tested. For finer granularity to test a specific set of parameters, use PF_HaveInputsChangedOverTimeSpan below instead.

Pre-defined constants for param_index are as follows:

- PF_ParamIndex_CHECK_ALL - check every parameter, including every layer referred to by a layer parameter.
- PF_ParamIndex_CHECK_ALL_EXCEPT_LAYER_PARAMS - omit all layers. Pass a specific layer parameter index to include that as the only layer parameter tested.

PF_HaveInputsChangedOverTimeSpan

No longer supported in PFParamUtilsSuite3. Use PF_AreStatesIdentical() instead.

PF_IsIdenticalCheckout

 

PF_IsIdenticalCheckout(
  PF_ProgPtr     effect_ref,
  PF_ParamIndex  param_index,
  A_long         what_time1,
  A_long         time_step1,
  A_u_long       time_scale1,
  A_long         what_time2,
  A_long         time_step2,
  A_u_long       time_scale2,
  PF_Boolean     *identicalPB);


Returns TRUE if a parameter's value is the same at the two passed times. Note: the times need not be contiguous; there could be different intervening values.

PF_FindKeyframeTime

 

PF_FindKeyframeTime(
  PF_ProgPtr     effect_ref,
  PF_ParamIndex  param_index,
  A_long         what_time,
  A_u_long       time_scale,
  PF_TimeDir     time_dir,
  PF_Boolean     *foundPB,
  PF_KeyIndex    *key_indexP0,
  A_long         *key_timeP0,
  A_u_long       *key_timescaleP0);


Searches (in the specified direction) for the next keyframe in the parameter's stream. The last three parameters are optional.

PF_GetKeyframeCount

 

PF_GetKeyframeCount(
  PF_ProgPtr     effect_ref,
  PF_ParamIndex  param_index,
  PF_KeyIndex    *key_countP);


Returns the number of keyframes in the parameter's stream.

PF_CheckoutKeyframe

 

PF_CheckoutKeyframe(
  PF_ProgPtr     effect_ref,
  PF_ParamIndex  param_index,
  PF_KeyIndex    key_index,
  A_long         *key_timeP0,
  A_u_long       *key_timescaleP0,
  PF_ParamDef    *paramP0);


Checks a keyframe for the specified parameter out of our keyframe database. param_index is zero-based. You can request time, timescale, or neither; useful if you're performing your own motion blur.

PF_CheckinKeyframe

 

PF_CheckinKeyframe(
  PF_ProgPtr   effect_ref,
  PF_ParamDef  *paramP);


All calls to PF_CheckoutKeyframe must be balanced with this check-in, or pain will ensue.

PF_KeyIndexToTime

 

PF_KeyIndexToTime(
  PF_ProgPtr     effect_ref,
  PF_ParamIndex  param_index,
  PF_KeyIndex    key_indexP,
  A_long         *key_timeP,
  A_u_long       *key_timescaleP);


Returns the time (and timescale) of the specified keyframe.