第二章 Effects基础

其他文章链接

• 序
• 第一章 介绍
  • 上
  • 下
• 第二章 Effects基础
  • 1
  • 2

本章将提供您需要了解的所有信息，以了解基本效果插件是如何工作的。这些细节是每个效果插件的基础。当你完成这一章时，你将为有趣的东西做好准备——修改像素!

入口点

After Effects和效果插件之间的所有通信都是由After Effects发起的，所有这些都是由主机(After Effects)调用单个入口点函数来完成的。对于所有的效果插件，入口点函数必须有以下签名:

PF_Err main (
    PF_Cmd cmd,
    PF_InData *in_data,
    PF_OutData *out_data,
    PF_ParamDef *params[],
    PF_LayerDef *output,
    void *extra)

上面的入口点函数的名称是“main”，但是它可以是在 PiPL资源 中指定的任何东西。

在每次调用入口点函数之前，After Effects更新PF_InData和插件的参数数组 PF_ParamDef[] (注意到的除外)。插件从它的调用返回后，After Effects检查 PF_OutData 的更改，并在适当的时候使用 PF_LayerDef 效果已经呈现。

表3：入口方法参数

参数	目的
cmd	After Effects设置 命令选择器(COMMAND SELECTORS) 来告诉插件该做什么。
in_data	关于应用程序状态的信息，以及告知插件操作的数据。还提供了指向众多界面和图像处理函数的指针。
out_data	通过在 out_data 中设置字段，将信息传递回After Effects。
params	in_data>current_time 中提供的插件参数的数组。参数[0] 是应该应用效果的输入图像(PF_EffectWorld)。这些值只在某些选择器中有效(这在选择器描述中有说明)。这里详细讨论了参数。
output	输出图像，由效果插件渲染并传递回After Effects。仅在某些选择器中有效。
extra	附加参数随所发送的命令或事件类型(PF_Cmd_EVENT)而变化。主要用于事件管理和参数监控。

命令选择器(COMMAND SELECTORS)

命令，简单地说，就是After Effects想要你的效果去做的。某些选择器的响应是必需的;大多数都是可选的，尽管我们添加它们是有原因的……

在发送每个命令选择器后，效果接收 PF_InData 中的After effects信息，PF_ParamDef[] 中的输入和参数值(包含输入层的参数描述数组)，以及访问回调和函数套件。它们将信息发送回 PF_OutData 中的After Effects，并(在适当的时候)将输出渲染到 PF_LayerDef ，也称为 PF_EffectWorld。在事件期间，它们额外接收特定于事件的信息。

调用序列

只有前几个命令选择器是可预测的;调用序列的其余部分由用户操作决定。

第一次应用时，插件将接收 PF_Cmd_GLOBAL_SETUP，然后是 PF_Cmd_PARAM_SETUP。每当用户将效果添加到一个层时，就会发送 PF_Cmd_SEQUENCE_SETUP。

对于基本的非smartfx效果渲染的每一帧，After Effects发送 PF_Cmd_FRAME_SETUP，然后 PF_Cmd_RENDER，然后 PF_Cmd_FRAME_SETDOWN。所有效果插件必须响应 PF_Cmd_RENDER。

对于SmartFX, PF_Cmd_SMART_PRE_RENDER 可以在发送单个 PF_Cmd_SMART_RENDER 之前发送任意次数。

PF_Cmd_SEQUENCE_SETDOWN 在退出时发送，当用户删除效果或关闭项目时。PF_Cmd_SEQUENCE_RESETUP 在项目被加载或它被应用的层发生变化时发送。PF_Cmd_SEQUENCE_FLATTEN 在After Effects项目写入磁盘时发送。

PF_Cmd_ABOUT 在用户从效果控制窗口(ECW)中选择About时发送。

PF_Cmd_GLOBAL_SETDOWN 将在After Effects关闭时发送，或者当最后一个实例的效果被移除时发送。不要依赖此消息来确定插件何时从内存中删除;使用os特定的入口点。

表4：命令选择器(COMMAND SELECTORS)

选择器	响应
全局选择器	所有插件都必须响应这些选择器。
PF_Cmd_ABOUT	显示描述插件的对话框。填充 out_data>return_msg 和After Effects将在一个简单的模态对话框中显示它。在对话框中包含插件的版本信息。在macOS上，当前的资源文件将在这个选择器期间被设置为你的effects模块。
PF_Cmd_GLOBAL_SETUP	设置任何必需的标志和 PF_OutData 字段(包括 out_data>my_version )来描述插件的行为。
PF_Cmd_GLOBAL_SETDOWN	释放所有全局数据(仅在分配一些数据时需要)。
PF_Cmd_PARAM_SETUP	描述你的参数并使用 PF_ADD_PARAM 注册它们。另外，注册自定义用户界面元素。设置PF_OutData>num_params 以匹配您的参数计数。
序列选择器	这些控制序列数据的处理。
PF_Cmd_SEQUENCE_SETUP	分配和初始化任何特定于序列的数据。第一次应用效果时发送。PF_InData此时被初始化。
PF_Cmd_SEQUENCE_RESETUP	重新创建(通常是还原)序列数据。在序列数据从磁盘读取后发送，在预组合过程中，或在效果被复制时发送;After Effects扁平化序列数据之前的复制。在复制过程中，对旧序列和新序列发送PF_Cmd_SEQUENCE_RESETUP。不要期望 PF_Cmd_SEQUENCE_RESETUPs之间的 PF_Cmd_SEQUENCE_FLATTEN。
PF_Cmd_SEQUENCE_FLATTEN	当保存和复制序列时发送。将包含指针或句柄的序列数据压平，以便将其写入磁盘。这将与项目文件一起保存。释放未平坦化的数据并将 out_data>sequence_data 设置为指向新的平坦化数据。平面数据必须以字节顺序正确地用于文件存储。 在6.0版本中，如果一个效果的序列数据最近已经被抚平，那么该效果可以在不接收额外的 PF_Cmd_SEQUENCE_SETDOWN 的情况下被删除。在这种情况下，After Effects将处理你的平面序列数据。
PF_Cmd_SEQUENCE_SETDOWN	释放所有序列数据
帧选择器	传递给插件渲染的每一帧(或一组音频样本)。
PF_Cmd_FRAME_SETUP	分配任何特定于帧的数据。这将在每一帧渲染前立即发送，以允许特定帧的设置数据。如果效果改变了输出缓冲区的大小，请指定新的输出高度、宽度和相对原点。除输入层外的所有参数都有效。 如果你把 width 和 height 设置为0,After Effects会忽略你对下面PF_Cmd_RENDER的响应。 注意:如果设置了PF_Outflag_I_EXPAND_BUFFER，您将收到这个选择器(和PF_Cmd_FRAME_SETDOWN)两次，一次没有PF_Cmd_RENDER在它们之间。这是为了让我们知道给定的层是否可见。 帧数据可以追溯到机器可能有8MB RAM的年代。给定上述调用序列，在 PF_Cmd_RENDER 期间进行分配要高效得多。
PF_Cmd_RENDER	根据输入帧和任何参数将效果呈现到输出中。这个渲染调用只能支持8位或16位的每个通道渲染。32位的每个通道渲染必须在PF_Cmd_SMART_RENDER中处理。 PF_InData中的所有字段都有效。如果您对这个选择器的响应被中断(对 PF_ABORT 或 PF_PROGRESS 的调用返回一个错误代码)，您的结果将不会被使用。不能在选择器期间删除 frame_data;你必须等待 PF_Cmd_FRAME_SETDOWN。
PF_Cmd_FRAME_SETDOWN	释放 PF_Cmd_FRAME_SETUP 期间分配的任何帧数据
PF_Cmd_AUDIO_SETUP	在每一个音频渲染之前发送。请求输入音频的时间跨度。分配和初始化任何特定于序列的数据。如果您的效果需要输入的时间跨度不是输出时间跨度，那么更新 PF_OutData 中的 startsampL 和 endsampL 字段。
PF_Cmd_AUDIO_RENDER	使用有效的音频填充 PF_OutData.dest_snd。PF_InData 中的所有字段都有效。如果您对这个选择器的响应被中断(对 PF_ABORT 或 PF_PROGRESS 的调用返回一个错误代码)，您的结果将不会被使用。
PF_Cmd_AUDIO_SETDOWN	释放 PF_Cmd_AUDIO_SETUP 期间分配的内存。
PF_Cmd_SMART_PRE_RENDER	只适用于SmartFX。根据效果实施的任何标准，确定效果产生其输出所需的输入领域。 可能在MediaCore托管时发送两次。第一个将在 GetFrameDependencies 期间进行，以收集输入。源签出可以在这里返回完整的帧尺寸。一旦源被渲染，如果它们的大小与第一次调用不同，那么这个选择器将被第二次发送实际的源大小，以获得正确的输出大小。注意，MediaCore想要所有的输出，所以PF_PreRenderOutput::max_result_rect 将被使用。 16.0新增内容 设置 PF_PreRenderOutput 中的 PF_RenderOutputFlag_GPU_RENDER_POSSIBLE 在GPU上渲染。如果这个标志没有设置，请求的渲染是不可能与请求的GPU，因为参数或渲染设置。主机可能会使用另一个 what_gpu 选项(或 PF_GPU_Framework_None )重新调用PreRender。 示例代码见表格底部
PF_Cmd_SMART_RENDER	只适用于SmartFX。执行渲染并为要求渲染效果的区域提供输出
消息传递	After Effects和插件之间的通信通道。
PF_Cmd_EVENT	这个选择器利用了额外的参数;要处理的事件类型由 e_type 字段表示，该字段是 extra 所指向的结构的成员。参见 效果UI和事件。
PF_Cmd_USER_CHANGED_PARAM	日志含义用户修改参数值。只有设置了 PF_ParamFlag_SUPERVISE 标志时，才会收到这个命令。您可以将参数修改为控制值，或者使一个参数的值影响其他参数。可以通过不同的操作修改参数。 in_data.current_time 被设置为用户在UI中看到的帧的时间(内部，comp的当前时间转换为层时间)，而他们正在更改触发 PF_Cmd_USER_CHANGED_PARAM 的参数。这也是一个自动添加的关键帧的时间(如果没有一个已经，秒表被启用)。 这通常与紧随其后的 PF_Cmd_RENDER 传递的值相同(除非大写锁定被关闭)，但不一定-可能有其他comp窗口打开，导致在不同的时间响应改变的参数呈现。
PF_Cmd_UPDATE_PARAMS_UI	效果控制面板(ECP)需要更新。这可能发生在打开ECP或移动到合成中的一个新时间之后。可以通过调用 PF_UpdateParamUI() 来修改参数特征(例如，启用或禁用它们)。 只有装饰性的更改可以响应此命令。在响应 PF_Cmd_UPDATE_PARAMS_UI 时不要改变参数值;改用 PF_Cmd_USER_CHANGED_PARAM。 只有在PiPL中设置了 PF_OutFlag_SEND_UPDATE_PARAMS_UI 和 PF_Cmd_GLOBAL_SETUP 期间，才会定期发送此命令。 注意:千万不要在选择器中检出参数。递归的坏结果几乎是肯定的。
PF_Cmd_DO_DIALOG	显示选项对话框。当选项按钮被点击(或一个菜单命令被选中)时发送。这个选择器只会在之前的效果表明它有一个对话框时被发送(通过设置全局 PF_OutFlag_I_DO_DIALOG 标志来响应PF_Cmd_GLOBAL_SETUP)。在版本3。PF_Cmd_DO_DIALOG 传递的参数无效。现在情况不再是这样了;插件可以访问非层参数，在其他时间检出参数，并在 PF_Cmd_DO_DIALOG 期间执行UI更新。它们仍然可能不会改变参数的值。
PF_Cmd_ARBITRARY_CALLBACK	管理任意数据类型。只有在注册了自定义数据类型参数时才会收到该参数。额外参数指示正在调用哪个处理程序函数。自定义数据类型将在实现中进一步讨论。
PF_Cmd_GET_EXTERNAL_DEPENDENCIES	仅当 PF_Cmd_GLOBAL_SETUP 期间设置了PF_OutFlag_I_HAVE_EXTERNAL_DEPENDENCIES 时发送。用插件依赖项的描述填充一个字符串句柄(在PF_ExtDependenciesExtra 中)，确保为终止 NULL 字符分配空间。如果没有需要报告的依赖项，则只返回字符串句柄的 NULL 指针。 如果检查类型是 PF_DepCheckType_ALL_DEPENDENCIES，则报告插件可能需要呈现的所有内容。如果检查类型为 PF_DepCheckType_MISSING_DEPENDENCIES，则只报告缺失项(如果没有缺失，则报告空字符串)。
PF_Cmd_COMPLETELY_GENERAL	响应一个AEGP。额外的参数指向AEGP发送的任何参数。aegp只能与响应此选择器的效果进行通信。	-PAGE 60
PF_Cmd_QUERY_DYNAMIC_FLAGS	仅发送给在 PF_OutFlags2 中，在其PiPL中以及在 PF_Cmd_GLOBAL_SETUP 期间指定了 PF_OutFlag2_SUPPORTS_QUERY_DYNAMIC_FLAGS 的插件。 对于所有动态标志，如果要在此命令期间进行更改，则必须在 PF_Cmd_GLOBAL_SETUP 期间将标志设置为 on。 该选择器将在任意时间发送。 作为响应，效果应使用 PF_CHECKOUT_PARAM 访问其（非层）参数，并决定是否应设置任何支持 PF_Cmd_QUERY_DYNAMIC_FLAGS 的标志，例如： PF_OutFlag_WIDE_TIME_INPUT PF_OutFlag_NON_PARAM_VARY PF_OutFlag_PIX_INDEPENDENT PF_OutFlag_I_USE_SHUTTER_ANGLE PF_OutFlag2_I_USE_3D_CAMERA PF_OutFlag2_I_USE_3D_LIGHTS PF_OutFlag2_DOESNT_NEED_EMPTY_PIXELS PF_OutFlag2_REVEALS_ZERO_ALPHA PF_OutFlag2_DEPENDS_ON_UNREFERENCED_MASKS PF_OutFlag2_OUTPUT_IS_WATERMARKED After Effects将这些信息用于缓存和优化目的，因此请尝试尽快做出响应。
16.0新增	添加了对GPU效果的支持
PF_Cmd_GPU_DEVICE_SETUP	主机可以随时调用此选择器。 每个GPU设备最多调用一次。 多个GPU设备可能一次处于设置状态。 将在 GlobalSetup 之后和 SequenceSetup 之前调用它。 目的是使效果在必要时进行GPU初始化，并使效果有机会仅基于该设备的属性而不是任何渲染上下文（帧大小等）选择退出该GPU设备。 如果效果拒绝了GPU设备，它将被调用以进行CPU渲染。 应该是 PF_InData::what_gpu = PF_GPU_Framework_None。 如果支持what_gpu 中的设备和框架，则预期效果会设置 PF_OutData :: out_flags2 中的PF_OutFlag2_SUPPORTS_GPU_RENDER_Fxx 标志中的一个或两个。 请注意，只有PF_OutFlag2_SUPPORTS_GPU_RENDER_F32 将在AE 16.0中。 此处未设置标志的效果将不被视为支持这些设备中任何一个的GPU渲染。 PF_GPUDeviceSetupOutput :: gpu_data 是插件拥有的指针，必须与PF_Cmd_GPU_DEVICE_SETDOWN 选择器一起释放。 该指针在渲染时也可用。
PF_Cmd_GPU_DEVICE_SETDOWN	释放与gpu_data相关的所有资源。 在AE中，这将在GPU设备发布之前被调用。
PF_Cmd_GPU_SMART_RENDER_GPU	与现有 PF_Cmd_SMART_RENDER 选择器等效的GPU。 在渲染时，将调用PF_Cmd_SMART_RENDER 或 PF_Cmd_SMART_RENDER_GPU 选择器，具体取决于预期效果是产生CPU还是GPU帧作为输出。 仅当 what_gpu！= PF_GPU_Framework_None 时才调用 PF_Cmd_SMART_RENDER_GPU，并且对任何输入/输出 PF_LayerDef 都有影响。 进行此选择器时，所有帧签入和签出将在GPU帧上进行。 注意PF_Cmd_SMART_RENDER 共享额外的结构 GPU相关选择器的额外输入中的 what_gpu 和 device_index 字段指示用于渲染的GPU框架插件。 输入和输出缓冲区将在此框架和设备上准备。 可以使用 PrSDKGPUDeviceSuite :: GetDeviceInfo 查询设备，上下文，命令队列以及其他相关的GPU状态。 PF_Cmd_SMART_PRE_RENDER 和PF_Cmd_SMART_RENDER_GPU 选择器调用之间的 what_gpu 相同

PF_Cmd_SMART_PRE_RENDER

typedef struct {
      PF_RenderRequest output_request; // what the effectis being asked to render
      short bitdepth; // bitdepth the effect is being driven in (in bpc)
      const void *gpu_data; // (new AE 16.0)
      PF_GPU_Framework what_gpu; // (new AE 16.0)
      A_u_long device_index; // (new AE 16.0) For use in conjunction with PrSDKGPUDeviceSuite
 } PF_PreRenderInput; 

PF_Cmd_GPU_DEVICE_SETDOWN

typedef struct {
    void *gpu_data; // effect must dispose.
    PF_GPU_Framework what_gpu;
    A_u_long device_index; // For use in conjunction with PrSDKGPUDeviceSuite
} PF_GPUDeviceSetdownInput;

typedef struct {
    PF_GPUDeviceSetdownInput input;
} PF_GPUDeviceSetdownExtra;

PF_Cmd_GPU_SMART_RENDER_GPU

typedef struct {
    PF_RenderRequest output_request; // what the effect is being asked to render
    short bitdepth; // bitdepth the effect is being driven in (in bpc)
    void *pre_render_data; // passed back from value placed in extra->output->pre_render_data during PF_Cmd_PRE_RENDER 
    const void *gpu_data; // (new AE 16.0)
    PF_GPU_Framework what_gpu; // (new AE 16.0)
    A_u_long device_index; // (new AE 16.0)
} PF_SmartRenderInput;

typedef struct {
    PF_SmartRenderInput *input;
    PF_SmartRenderCallbacks *cb;
} PF_SmartRenderExtra;

不同点

PF_Cmd_USER_CHANGED_PARAM 和 PF_Cmd_UPDATE_PARAMS_UI 之间有细微的差别。 效果需要区分用户实际上是在更改参数值（PF_Cmd_USER_CHANGED_PARAM），还是只是在时间轴上滑动（PF_Cmd_UPDATE_PARAMS_UI，这在首次加载插件时也会发送）。

PF_INDATA

After Effects使用PF_InData传达系统、项目、图层和音频信息。 在将每个命令选择器发送到插件之前，将更新此结构。 记录仅在特定PF_Cmds期间有效的字段。 另外，不用担心； 尽管PF_InData很大，但您不必记住每个成员的目的； 您有时会使用某些字段。

表5：PF_INDATA

字段名	描述
inter	用于用户交互，添加参数，检查用户是否已中断效果，显示进度条以及在非当前渲染时间的其他时间获取源帧和参数值的回调。 此非常有用的功能套件在“交互回调函数”中进行了描述。
utils	图形和数学回调。 始终定义此指针。
effect_ref	必须传递给大多数各种回调例程的不透明数据。 After Effects使用此来识别您的插件。
quality	当前质量设置，即 PF_Quality_HI 或 PF_Quality_LO。 效果在 LO 中的执行速度应更快，而在 HI 中的效果则应更准确。 图形实用程序回调在 LO 和 HI 质量之间的执行方式有所不同。 你的效果也应该如此！ 在所有帧和序列选择器中都定义了该字段。
version	效果规范版本，指示在 PF_Cmd_GLOBAL_SETUP 期间成功运行所需的版本。
serial_num	调用应用程序的序列号。
appl_id	调用应用程序的标识符。 如果您的插件在After Effects中运行，则appl_id包含应用程序创建者代码 “FXTC”。 如果它在Premiere Pro中运行，它将是“PrMr”。 使用它来测试是否许可将您的插件与一种应用程序一起使用，并将其与另一种应用程序一起使用。
num_params	输入参数计数。
what_cpu	在macOS下，它包含CPU类型的格式塔值（请参阅Macintosh内部，第6卷）。 在Windows上未定义。
what_fpu	在macOS下，它包含FPU类型的格式塔值。 在Windows上未定义。
current_time	当前帧的渲染时间，在 PF_Cmd_RENDER 期间有效。 这是图层中的当前时间，而不是任何组成。 如果图层在时间0以外的地方开始或经过时间拉伸，则图层时间和合成时间会不同。 当前帧号是current_time 除以 time_step。 当前时间（以秒为单位）是 current_time 除以 time_scale。 为了处理时间延长，合成帧速率更改和时间重新映射，After Effects可能会要求效果在非整数时间（两个帧之间）进行渲染。 为此做好准备； 不要假设只要求您提供帧边界上的帧。 注意：从CS3（8.0）开始，可能需要在时间为负值时调用。
time_step	正在渲染的当前源帧的持续时间。 在具有嵌套构图的几种情况下，此源帧持续时间可能不同于该层中帧之间的时间跨度（local_time_step）。 可以通过除以 time_scale 将该值转换为秒。 在计算其他源帧时间时（例如对于 PF_CHECKOUT_PARAM ），请使用此值，而不要使用 local_time_step。 如果该层是时间反转的，则可以为负。 如果将时间重新映射应用于嵌套的合成，则可能在一帧与下一帧之间变化。 当源材料在嵌套合成中拉伸或重新映射时，可能与 local_time_step 不同。 例如，当内部构图嵌套在具有不同帧速率的外部构图内或对外部构图应用时间重新映射时，可能会发生这种情况。 如果在所有帧中该值都不恒定，则在PF_Cmd_SEQUENCE_SETUP 期间该值将为0。 将在 PF_Cmd_FRAME_SETUP和PF_Cmd_FRAME_SETDOWN 选择器中正确设置。 警告：这可以是零，因此在除法之前请检查它。
total_time	图层的持续时间。 如果该层的时间拉伸长于100％，则将相应地调整该值； 但是如果该层在时间上更短，则该值将不会受到影响。 如果启用了时间重新映射，则此值为合成的持续时间。 可以通过除以 time_scale 将该值转换为秒。
local_time_step	图层中帧之间的时间差。 受到应用于图层的任何时间拉伸的影响。 如果该层是时间反转的，则可以为负。 与 time_step 不同，此值从一帧到下一帧是恒定的。 可以通过除以 time_scale 将该值转换为秒。 对于在图层的整个帧范围内恒定的步长值，请使用 local_time_step，它基于合成的帧频和图层拉伸。
time_scale	current_time，time_step，local_time_step 和 total_time 的每秒单位。如果time_scale 为30，则 current_time，time_step，local_time_step 和 total_time 一秒的单位为30。 然后 time_step 可能为3，表示该序列实际上以每秒10帧的速度呈现。 total_time 可能是105，表示该序列长3.5秒。
field	仅当在 PF_Cmd_GLOBAL_SETUP 期间设置了 PF_OutFlag_PIX_INDEPENDENT 时有效。 检查此字段以查看您是否只能处理上方或下方的字段。
shutter_angle	运动模糊快门角度。 值的范围是0到1，代表360度。 除非启用运动模糊并检查目标层，否则它将为零。 shutter_angle == 180 表示 current_time 和 current_time 之间的时间间隔 + 1/2 time_step。 仅在 PF_Cmd_GLOBAL_SETUP 期间设置了 PF_OutFlag_I_USE_SHUTTER_ANGLE 时有效。 有关如何在效果中实现运动模糊的详细信息，请参见“运动模糊”部分。
width height	源图层的尺寸，不一定与输入图像参数中的宽度和高度字段相同。 缓冲区大小调整效果可能导致这种差异。 不受下采样的影响。
extent_hint	输入和输出层的可见部分的交点； 包含转换为图层坐标的合成矩形。 仅在此矩形像素上进行迭代可以显着加快效果。 有关正确用法，请参见本章后面的注释。
output_origin_x output_origin_y	输入缓冲区中输出缓冲区的原点。 仅当效果更改原点时才为非零。
downsample_x downsample_y	点控制参数和图层参数尺寸会自动调整，以补偿用户告诉After Effects仅渲染第n个像素的情况。 效果需要下采样因子来解释代表图像中像素距离的标量参数（如滑块）。 例如，如果在每个方向上的下采样因子为1/2（下采样因子表示为比率），则4像素的模糊应解释为2像素的模糊 PF_Cmd_SEQUENCE_SETUP， PF_Cmd_SEQUENCE_RESETUP， PF_Cmd_FRAME_SETUP， PF_Cmd_FRAME_RENDER。
pixel_aspect_ratio	像素长宽比（宽高比）。
in_flags	没用过。
global_data sequence_data frame_data	插件在其他选择器期间存储的数据。 在调用插件前后，由After Effects锁定和解锁。
start_sampL	起始样本编号，相对于音频层的起始位置。
dur_sampL	音频的持续时间，表示为样本数。 特定于音频。
total_sampL	音频层中的样本； 等效于样本中表示的total_time。
src_snd	PF_SoundWorld描述输入声音。 特定于音频。
pica_basicP	指向PICA Basic套件的指针，用于获取其他套件。
pre_effect_source_origin_x pre_effect_source_origin_y	输入缓冲区中源图像的原点。 仅在与帧选择器一起发送时有效。 仅当在同一层上此效果之前的一个或多个效果调整了输出缓冲区的大小并移动了原点时，才为非零。 检查调整大小和新原点，以确定输出区域。 这对于具有隐式空间操作（点控件除外）的效果很有用，例如围绕图像中心翻转文件。 注意：检出点参数针对当前时间（而不是检出时间）的预效果原点进行调整。
shutter_phase	从帧时间到快门打开时间的偏移量（以帧持续时间的百分比表示）

EXTENT_HINT用法

（注意：提示矩形对于SmartFX更加有效...而且更复杂...）

使用 extent_hint 只处理那些需要输出的像素； 这是您可以进行的最简单的优化之一。 通过在PF_Cmd_GLOBAL_SETUP（和您的PiPL）中在 PF_OutData 中设置 PF_OutFlag_USE_OUTPUT_EXTENT，来告诉After Effects您使用 in_data> extent_hint。

在测试 extent_hint 代码之前，请从首选项菜单中禁用缓存，因此，只要合成中的任何内容发生变化，After Effects都将呈现您的效果。 否则，缓存机制会使您的插件的输出（可能不正确）模糊不清。

在合成中移动图层，以便对其进行裁剪。 output>extent_hint 是图层中在合成中可见的部分。 在您的图层上添加一个遮罩并四处移动。 这会更改一下 range_hint，它会包围图像的所有非零alpha区域。
in_data> extent_hint是这两个矩形（构图和蒙版）的交集，并且每当它们发生变化就改变。

在调整大小和原点偏移之前，会在原始输入层的坐标空间中计算范围矩形，以简化设置 PF_OutFlag_PIX_INDEPENDENT 的效果的输入和输出范围之间的矩形相交。 要在输出缓冲区的坐标系中获取输出范围，请通过 PF_InData>output_origin_x 和 y 字段将 tent_hint 偏移。

计算输出大小时考虑下采样； 用户必须能够以全分辨率进行渲染。 如果输出缓冲区超过30,000 x 30,000，请将其限制为该大小，并考虑显示警报对话框。

代码正确运行后，启用缓存并查看效果需要多长时间重新渲染一次。 考虑一个阴影； 用户经常将静态阴影应用于静止图像。 output> extent_hint 被忽略，因此更频繁地使用缓存。

要获得缓冲区扩展效果，请将 output> extent_hint 与插件的转换范围相交，并在 PF_Cmd_FRAME_SETUP 期间相应地设置大小。

现在多了20％的像素！

从6.0版开始，传递的 extent_hints 比图层本身大20％，以帮助我们进行预测性渲染决策。 许多效果仅通过触摸即可扩展缓冲区，After Effects以后经常使用提示矩形。

点控制和缓冲区扩展

通过在 PF_Cmd_FRAME_SETUP 期间在 PF_InData 中设置 set output_origin_x / y 来扩展输出缓冲区的效果位于原始图层的左上角。 在 pre_effect_source_origin_x / y 中报告了此偏移对后续效果的影响。 点参数会针对该移位自动进行调整。

在效果生效之前，应用缓冲扩展器，例如高斯模糊或Resizer SDK示例，并使用较大的调整大小值。 如果您的效果未正确处理 pre_effect_source_origin_x / y，则打开和关闭模糊将改变输出的位置。

所有点参数值（在任何时候）都具有 pre_effect_source_origin_x / y 描述的偏移值。 对于大多数效果而言，这是透明的。 但是，如果缓冲区扩展随时间变化（如动画模糊量一样），则原点偏移将移动非动画点。 设计在帧之间缓存点参数值的效果时，请考虑这一点。

原文

This chapter will provide all the information you need to know to understand how a basic effect plug-in works. These details are fundamental to every effect plug-in. By the time you finish this chapter, you’ll be ready for the fun stuff; modifying pixels!

All communication between After Effects and an effect plug-in is initiated by After Effects, and it all happens by the host (After Effects) calling a single entry point function. For all effect plug-ins, the entry point function must have the following signature:

PF_Err main (
    PF_Cmd cmd,
    PF_InData *in_data,
    PF_OutData *out_data,
    PF_ParamDef *params[],
    PF_LayerDef *output,
    void *extra)

The name of the entry point function above is “main”, but it can be whatever is specified in the PiPL resource.

Before each call to the entry point function, After Effects updates PF_InData and the plugin’s parameter array PF_ParamDef[] (except as noted). After the plug-in returns from its call, After Effects checks PF_OutData for changes and, when appropriate, uses the PF_LayerDef the effect has rendered.

Commands are, simply, what After Effects wants your effect to do. Responses to some selectors are required; most are optional, though recall that we did add them for a reason...

With each command selector sent, effects receive information from After Effects in PF_InData, input and parameter values in PF_ParamDef[] (an array of parameter descriptions including the input layer), and access to callbacks and function suites. They send information back to After Effects in PF_OutData, and (when appropriate) render output to a PF_LayerDef, also called a PF_EffectWorld. During events, they receive event-specific information in extra.

Only the first few command selectors are predictable; the rest of the calling sequence is dictated by user action.

When first applied, a plug-in receives PF_Cmd_GLOBAL_SETUP, then PF_Cmd_PARAM_SETUP. Each time the user adds the effect to a layer, PF_Cmd_SEQUENCE_SETUP is sent.

For each frame rendered by a basic non-SmartFX effect, After Effects sends PF_Cmd_FRAME_SETUP, then PF_Cmd_RENDER, then PF_Cmd_FRAME_SETDOWN. All effect plug-ins must respond to PF_Cmd_RENDER.

For SmartFX, PF_Cmd_SMART_PRE_RENDER may be sent any number of times, before a single PF_Cmd_SMART_RENDER is sent.

PF_Cmd_SEQUENCE_SETDOWN is sent on exit, when the user removes an effect or closes the project. PF_Cmd_SEQUENCE_RESETUP is sent when a project is loaded or when the layer to which it’s applied changes. PF_Cmd_SEQUENCE_FLATTEN is sent when the After Effects project is written out to disk.

PF_Cmd_ABOUT is sent when the user chooses About… from the Effect Controls Window (ECW).

PF_Cmd_GLOBAL_SETDOWN is sent when After Effects closes, or when the last instance of the effect is removed. Do not rely on this message to determine when your plug-in is being removed from memory; use OS-specific entry points.

After Effects communicates system, project, layer and audio information using PF_InData. This structure is updated before each command selector is sent to a plug-in. Fields valid only during specific PF_Cmds are noted. Also, don’t worry; although PF_InData is dauntingly large, you need not memorize each member’s purpose; you’ll use some of the fields some of the time.

Use extent_hint to process only those pixels for which output is required; this is one of the simplest optimizations you can make. Tell After Effects you use in_data>extent_hint by setting PF_OutFlag_USE_OUTPUT_EXTENT in PF_OutData during PF_Cmd_GLOBAL_SETUP (and in your PiPL).

Disable caching from the preferences menu before testing extent_hint code, so After Effects renders your effect whenever anything in your composition changes. Otherwise, the caching mechanism would obscure your plug-in’s (possibly incorrect) output.

Move the layer within the composition so it’s cropped. The output>extent_hint is the portion of the layer which is visible in the composition. Add a mask to your layer and move it around. This changes the extent_hint, which encloses all of the non-zero alpha areas of the image. The in_data>extent_hint is the intersection of these two rectangles (the composition and the mask), and changes whenever they do.

Extent rectangles are computed in the coordinate space of the original input layer, before resizing and origin shifting, to simplify rectangle intersection between the input and output extents for effects which set PF_OutFlag_PIX_INDEPENDENT. To get the output extent in the coordinate system of the output buffer, offset the extent_hint by the PF_InData>output_origin_x and y fields.

Account for downsampling when computing output size; users must be able to render at full resolution. If the output buffer exceeds 30,000 by 30,000, clamp it to that size, and consider displaying an alert dialog.

Once your code behaves correctly, enable the cache and see how frequently the effect needs to re-render. Consider a drop shadow; users frequently apply a static drop shadow to a still image. The output>extent_hint is ignored, so the cache is used more often.

For buffer-expanding effects, intersect the output>extent_hint with your plug-in’s transformed bounds and sets the size accordingly during PF_Cmd_FRAME_SETUP.

Effects which expand the output buffer position the original layer’s upper left corner by setting set output_origin_x/y in PF_InData during PF_Cmd_FRAME_SETUP. This shift is reported to subsequent effects in the pre_effect_source_origin_x/y. Point parameters are adjusted for this shift automatically.

Apply a buffer expander such as Gaussian Blur or the Resizer SDK sample, before your effect, and use a large resize value. If your effect is not handling pre_effect_source_origin_x/y correctly, turning the blur on and off will shift the position of the output.

All point parameter values (at any time) have shift values described by pre_effect_source_origin_x/y. For most effects this works transparently. However, if a buffer expansion changes over time (as with an animated blur amount), the origin shift will move non-animated points. Consider this when designing effects which cache point parameter values between frames.