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_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. NOTE: Never pass param[0] to this function. |
|
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:
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_ProgPtr effect_ref,
const PF_State *state1P,
const PF_State *state2P,
A_Boolean *samePB);
New in CS6. Compare two different states, retrieved using |
|
No longer supported in 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:
|
|
No longer supported in |
|
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 |
|
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_ProgPtr effect_ref,
PF_ParamIndex param_index,
PF_KeyIndex *key_countP);
Returns the number of keyframes in the parameter’s stream. |
|
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_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_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. |