pub type _bindgen_ty_33 = c_uint;Expand description
–––––––––– Command Selectors ––––––––––
The first parameter to the effect routine is one of t hese command selectors. The commands are described here.
PF_Cmd_ABOUT This command should display an information dialog box about the effect module. The easiest thing to do is PF_SPRINTF the info into the out_data->return_msg field. After Effects will bring up a simple undecorated modal dialog with your text proudly displayed. This command can be sent at any time, so don’t count on having any global data or anything else set. (Except, as always, the current resource file will be set to your effects module.)
PF_Cmd_GLOBAL_SETUP When you get this command, you should check the version of the effect protocol with which you are being invoked, and set any of the necessary out flags (described above) or out data fields (described below). If your global data was flattened, the flat data will be passed here and you should unflatten it, free the flat global data, and set the OutData global_data to the new un-flat data. Alternatively, the global data may come in NULL and you can allocate new global data at this time.
PF_Cmd_GLOBAL_SETDOWN You should free any global data you have allocated when you get this command.
PF_Cmd_PARAMS_SETUP Here you should add any params your effect wants using the PF_ADD_PARAM callback described below. This is called after global setup – see the add_param callback described below.
PF_Cmd_SEQUENCE_SETUP This is called when the effect is first applied to a layer. A sequence is a series of images that will usually be all be of the same size and in the same context. You can allocate sequence data at this time – many more input fields are defined at this time. See the PF_InData description below.
As of 13.5 this only happens on the UI thread. Except for legacy (no GET_FLATTENED_SEQUENCE_DATA) effects that do I_DO_DIALOG which can still hit this in render.
PF_Cmd_SEQUENCE_RESETUP This call is made to unflatten flattened sequence data. There are at least three cases when this can happen:
- after the sequence data is written to disk, 2) after the sequence data is read in from disk, 3) after a duplicate is made (called on both original and the new sequence).
This can happen in UI or Render thread (13.5), the effect must handle initialization of a NULL sequence_data input if needed. See also PF_InFlag_PROJECT_IS_RENDER_ONLY.
PF_Cmd_SEQUENCE_FLATTEN This call is made to flatten unflat sequence data so it can be cached to disk. After the data is flattened, free the un-flat data and set the out_data->sequence_data to the new flat data. If you don’t want your sequence handle written to disk, you can set it to NULL (after disposing it) at this time. Presumably you would then reallocate it at another time.
This command will be sent when saving and when duplicating the sequence.
PF_Cmd_GET_FLATTENED_SEQUENCE_DATA (new in 13.5) Returns an independent allocation of the sequence data which can be written to disk or used to initialise or update other instances of the effect plug-in.
The host calls this command to serialize the sequence data without having to flatten and resetup the UI plug-in as was legacy practice. (However, at present effects still may need flattening in render if the sequence_data is about to be assigned.)
An effect that implements GET_FLATTENED_SEQUENCE_DATA will only receive SEQUENCE_SETUP on the UI thread. SEQUENCE_RESETUP can happen on either thread. Make sure you handle a NULL sequence_data in RESETUP. (Without GET_FLATTENED, a legacy effect may still get SEQUENCE_SETUP in render but DO_DIALOG will not be called.)
Also when enabled, this means that the effect is guaranteed to get a SEQUENCE_SETDOWN cmd to dispose the effect’s sequence_data (previously it was possible for AE to bypass this if the sequence_data was flat, but that lead to SEQUENCE_SETUP/SETDOWN imbalances for some plugins. The imbalance should not happen when using this flag, but the plugin must handle being called on SETDOWN with possibly flat data. For example, try copy and pasting an effect onto itself.
Support for this command is indicated by setting PF_OutFlag2_SUPPORTS_GET_FLATTENED_SEQUENCE_DATA
The ownership of the returned handle is transferred to the host.
PF_Cmd_SEQUENCE_SETDOWN You should free any sequence data you have allocated when you get this command.
PF_Cmd_DO_DIALOG This command indicated that the Options button or command has been selected and the effect should bring up its options dialog. This command will only be sent it the effect has indicated that it has an options dialog with PF_OutFlag_I_DO_DIALOG. This command will automatically be sent once upon applying the filter if PF_OutFlag_SEND_DO_DIALOG is set in SEQUENCE_SETUP.
PF_Cmd_FRAME_SETUP This is called immediately before each frame is invoked. You can allocate frame data at this time, if you wish, or you can just wait for the RENDER which will immediately follow.
PF_Cmd_RENDER This is the call to render the frame. All fields in the in_data will be valid at this time and you can inquire parameters or what-have-you. This should set the output frame with the new image data. This is the main action command.
PF_Cmd_FRAME_SETDOWN If you allocated data in PF_Cmd_FRAME_SETUP, this is the time to free it and clean up after rendering the frame.
PF_Cmd_USER_CHANGED_PARAM This command will be sent if you set the PF_ParamFlag_SUPERVISE flag for a param. This allows you to modify the params array contents to control values or make one control affect others, including arbitrary data. This command will be sent whenever the user interacts with a standard param controller that has PF_ParamFlag_SUPERVISE set.
The “extra” field will be a pointer to a PF_UserChangedParamExtra structure which contains the param_index of the changed parameter.
You can return PF_ChangeFlag_CHANGED_VALUE and/or call PF_UpdateParamUI() for any param.
PF_Cmd_UPDATE_PARAMS_UI This command will be sent when the Effect Controls Window (ECW) needs to updated (e.g. after opening the ECW or moving the comp to a new time) if you have set PF_OutFlag_SEND_UPDATE_PARAMS_UI at global setup time.
This gives you a chance to call PF_UpdateParamUI() to modify certain ui fields for the params. See the doc for PF_UpdateParamUI() to see which fields can be modified.
WARNING: When handling PF_Cmd_UPDATE_PARAMS_UI, you can call PF_UpdateParamUI() for any param(s), but not PF_ChangeFlag_CHANGED_VALUE – only cosmetic changes can be made in response to this command.
PF_Cmd_QUERY_DYNAMIC_FLAGS This command will be sent at arbitrary times if PF_OutFlag2_SUPPORTS_QUERY_DYNAMIC_FLAGS is set during global setup. During this call the effect may examine the values of its parameters at the current time (except layer parameters) by checking them out, and decide whether any of the flags that support PF_Cmd_QUERY_DYNAMIC_FLAGS should be set.
The appropriate flags must be set in out_data->out_flags and out_data->out_flags2 before returning. The effect must decide what information is necessary to render a frame at the current time, given only the values of parameters at that time. Clearing the appropriate bits when possible can result in great performance improvements, but incorrectly clearing bits will result in caching bugs, and you won’t like that. Nope.
Important Reminder*** Before you add a new PF_Cmd, evaluate whether it should allow new Sequence Data allocations! If so, remember to add it to CmdCanChangeSequenceData() in FLT_Host.cpp!