Struct PF_OutData 

#[repr(C)]
pub struct PF_OutData {

    pub my_version: A_u_long,
    pub name: [A_char; 32],
    pub global_data: PF_Handle,
    pub num_params: A_long,
    pub sequence_data: PF_Handle,
    pub flat_sdata_size: A_long,
    pub frame_data: PF_Handle,
    pub width: A_long,
    pub height: A_long,
    pub origin: PF_Point,
    pub out_flags: PF_OutFlags,
    pub return_msg: [A_char; 256],
    pub start_sampL: A_long,
    pub dur_sampL: A_long,
    pub dest_snd: PF_SoundWorld,
    pub out_flags2: PF_OutFlags2,
}

–––––––––– Effect Parameter Blocks ––––––––––

The effects module itself is invoked with input and output blocks of parameters for various messages that it needs to handle. The output block (values returned from the effect to the program) and the input block (values provided by the program for the edification of the effect) are defined here. Discussion follows.

The Output Block

Most fields of the output block are only examined for changes after certain commands have been sent to the effect module. Each field below describes when it will be checked.

my_version This is the version number of your plug-in effect, not to be confused with the version of the plug-in specification. Please set this at PF_Cmd_GLOBAL_SETUP.

name This lets you override the name of the effect in the Time Layout and in the Effect Controls windows when the effect is applied. The name from the PiPL resource is always used in the Effect menu. This field is checked after PF_Cmd_SEQUENCE_SETUP. You will almost always leave this field empty.

global_data This is a Handle that you can allocate at PF_Cmd_GLOBAL_SETUP time. It will be passed back to you verbatim in the input parameter block for use later on. In PF_Cmd_GLOBAL_SETUP, the global_data field in the Input Block may be set to a flattened version of your global data, in which case you should unflatten it, free the flat version, and set this field to the unflattened new global data.

It will be locked & unlocked for you automatically like sequence_data.

num_params The calling application will sanity check the num_params field vs the times add_param is called. The implicit main layer parameter MUST be included in the parameter count. Use the num_params value in the in_data as a starting value (it will include the implicit layer parameter). Set this field when you get PF_Cmd_PARAMS_SETUP.

sequence_data This is a Handle that you can allocate (using PF_NEW_HANDLE) at PF_Cmd_SEQUENCE_SETUP time. It will be passed back to you in the input parameter block for later use.

WARNING: this handle is always locked for you before your plugin is called, and the lock-state is restored on the way out. If you have arbitrary data, your plugin can be called re-entrantly, so if you have a lock/unlock inside your plugin, the handle will become unlocked prematurely – instead simply depend on the host to lock & unlock your sequence data for you. Of course during PF_Cmd_SEQUENCE_SETUP the handle you allocate will not be locked unless you explicitly lock it at that time.

The contents of this handle will be written out to disk. If other handles hang off this block, you must specify the PF_OutFlag_SEQUENCE_DATA_NEEDS_FLATTENING out flag when you get the PF_Cmd_GLOBAL_SETUP command. You will then receive the PF_Cmd_SEQUENCE_FLATTEN before your handle is written out. At that time, you should create a flat version of the handle contents, free the old unflat handle, and set this field to the flattened version of the handle. Or after disposing, simply set to NULL and nothing will be written to disk.

You will receive a PF_Cmd_SEQUENCE_RESETUP call to unflatten this handle (as well as to adjust the sequence data to altered frame rates, etc). If your sequence data can be flat or unflat, you should store its current state along with the other data, and check that value in Resetup. If the handle is flat, Resetup should unflatten it, free the flat handle, and set this field to the new unflat usable handle.

flat_sdata_size OBSOLETE. Turns out, it was never used. Since the handle set in sequence_data must be allocated using PF_NEW_HANDLE, the host can find out the size of the handle without asking.

frame_data This is a Handle that you can allocated at PF_Cmd_FRAME_SETUP time. It will be passed to you in the input parameters, as with the global_data and the sequence_data. This will not be written out to disk. There is no particular use for this. Set this field in PF_Cmd_FRAME_SETUP, if you must.

It will be locked & unlocked for you like sequence_data.

width height origin You set these fields at PF_Cmd_FRAME_SETUP time to indicate that the output image will be larger than the input image. You should set width and height to the size that you want the output buffer to be. Set origin to the place that the point (0,0) in the input should map to in the new larger output. Thus, if you created a 5 pixel drop shadow up and left, you would set origin to (5, 5).

out_flags out_flags2 This field can be set to an OR-ed combination of the PF_OutFlag and PF_OutFlag2 constants (don’t mix them up!) to communicate things to After Effects. This will be checked after every command, but only certain flags are relevant at given times. Check the PF_OutFlag constants above.

return_msg This is a message string (in C string format) that will be interpreted as either an error message or a useful display message (for instance, for handling PF_Cmd_ABOUT). Fill this string with a message you want After Effects to report to the user for you. It will come up in a simple dialog with an OK button. Set the first byte of this string to ‘\0’ to indicate no string – it is set that way upon entry. This field is examined after every PF_Cmd.

The Input Block

Many parts of the input block are actually structures defined elsewhere in this file, or in the companion file AE_EffectCB.h. See the documentation where those structures are defined to understand their contents. With any given PF_Cmd, only certain fields in the Input Block will have valid values. Each field described below tells when it is valid.

in_flags in_flags2 These are various flags indicating some boolean value to the effect module. This is a combination of PF_InFlag values OR-ed together. This is set for all commands, though most flags make sense only at certain times. Usually this is just a copy of the PiPL global flags. See PF_OutFlags and PF_OutFlags2 above.

inter This is a structure defined above containing callbacks related to user interaction. This has callbacks to add parameters, to check if the user has interrupted the effect, to display a progress bar, and to inquire parameter values outside of the current moment. See the doc above. When each callback can validly be executed is defined above.

utils This is a pointer to a block of useful graphical and mathematical callbacks provided for the effects module. The documentation for this block is in the AE_EffectCB.h file. This is a void *, which can be confusing. See AE_EffectCB.h for macros to use these functions. This pointer will be defined at all times.

effect_ref This is a opaque piece of data that needs to be passed to most of the various callback routines. Don’t worry about it.

quality This is set to one of the PF_Quality constants above to describe the Quality currently chosen by the user. Ideally, your effect should do a faster version with LO quality, and a better, “broadcast”-able version with HI quality. Also, some of the utility callbacks perform differently between LO and HI quality. This is defined for all PF_Cmds related to SEQUENCE and FRAME (obviously, including RENDER).

version This is the version of the effects spec with which you are being invoked. This will not be defined until after GLOBAL_SETUP.

serial_num This is the serial number of the invoking application.

appl_id This is the identifier of the invoking application. It will be the creator A_long of the app.

freq This is an estimate of the frequency with which you should call the abort check callback. You can ignore this.

num_params This is set to the number of input parameters you are receiving.

what_cpu This is set to the return value from Gestalt asking what sort of CPU your machine has. If your effect requires a certain type of CPU it should check this value and return an error indicating that it cannot run. After Effects only runs on 68020s and higher, so don’t sweat it if you require that.

what_fpu This is set to the return value from Gestalt asking what sort of FPU your machine has. If you require a floating point unit, you should return the OutFlag indicating that in GLOBAL_SETUP, and then do not execute your floating point code if this value is set to 0 – just do a PF_COPY of the input to the output when you get the PF_Cmd_RENDER. See OutFlag description above.

current_time This is the time of the current frame. It will be set in RENDER. The number of the current frame is current_time / time_step. All effects sequences start at time 0.

time_step This is the time difference to the next or last frame. This value and current_time and total_time are in units given by time_scale. The time between frames is time_step, not 1. This value will be 0 at SEQUENCE_SETUP if it is not constant for all frames. It will be set correctly in the FRAME calls, even if it’s not constant.

total_time This is the amount of time from the start to the end of the image sequence on which this effect is being invoked. The total number of frames is total_time / time_step.

time_scale These are the units that current_time, time_step, and total_time are in. See QuickTime for an explanation of how these time values work.

width height These are the size of the input image. As Stoney Ballard points out, these are certainly NOT the same as the width and height fields in param[0], but rather reflect the full-resolution dimensions of the input layer.

field Will be set to PF_Field_UPPER or PF_Field_LOWER during field-rendering if certain conditions are met – for example: effect must have PF_OutFlag_PIX_INDEPENDENT set, and the layer to which the effect is applied must not be rotated, scaled nor positioned on a subpixel. You can safely ignore the setting of this field, but might be able to optimize things by only processing the specified field.

extent_hint This is a rectangle that indicates the intersection of the visible portions of the input and output layers. For an effect that does not do a geometric distortion of the image, copying just this rectangle from the source image to the destination image is sufficient to copy all the image data that the user will see. This can speed up effects very much. Just iterate over only this rectangle of pixels.

output_origin_x output_origin_y These fields correspond to the origin returned in the out_data at PF_Cmd_FRAME_SETUP time. They indicate the position of the top left corner of the input buffer in the output buffer.

downsample_x downsample_y For speed, the user may have asked for only every Nth vertical or horizontal pixel to be actually rendered by After Effects. The width and height of all effect parameters (including layers) will be automatically adjusted to compensate, but the effect needs to know the downsampling factors to correctly interpret scalar parameters (ie. sliders) that represent pixel distances in the image. Downsample factors will be in the range 1 to 999+. This is set in SEQUENCE_SETUP or RESETUP as the case may be. As of PF_PLUG_IN_VERSION 2, this factor is a rational quantity.

global_data sequence_data frame_data These fields are copied from the out data on previous invocations and set here for you to access as you need them. They will only be set if they have been allocated during previous commands.

pre_effect_source_origin_x pre_effect_source_origin_y These fields are the origin of the source image in the input buffer. They are set only during frame calls (PF_Cmd_FRAME_SETUP, PF_Cmd_RENDER, PF_Cmd_FRAME_SETDOWN). They will be non-zero only if one or more effects that preceded this effect on the same layer resized the output buffer (i.e. specified that the output image will be larger or smaller than the input image).

Fields

my_version: A_u_long

name: [A_char; 32]

global_data: PF_Handle

num_params: A_long

sequence_data: PF_Handle

flat_sdata_size: A_long

frame_data: PF_Handle

width: A_long

height: A_long

origin: PF_Point

out_flags: PF_OutFlags

return_msg: [A_char; 256]

start_sampL: A_long

dur_sampL: A_long

dest_snd: PF_SoundWorld

out_flags2: PF_OutFlags2

Trait Implementations

impl Clone for PF_OutData

fn clone(&self) -> PF_OutData

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for PF_OutData