AE效果器（Effect）开发

效果器基础（Effect Basics）

---

入口函数（ENTRY POINT）

---

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

入口函数的名称在PiPL resource文件中定义，这里是main，默认例程中是EntryPointFunc。

在每次调用之前，AE会传送PF_InData和参数数组PF_ParamDef[]给入口函数。插件在回调过程返回之前，AE会检查PF_OutData有没有变化，如果有的话，通过PF_LayerDef来渲染该效果。

参数 用途 cmd AE通过设置command selector来指导插件的行为 in_data 包含了应用的状态和插件被告知要要处理的数据。同时提供了大量接口和图像处理函数指针 out_data 通过设置in_data的值返回给AE相关信息 params 在in_data中给出的时间>current_time时插件的参数数组。params[0]代表效果器应用的图片（PF_EffectWorld）。这些值仅仅在一些特定的选择器期间有效（参看selectors descriptions）。 output 输出图像，由产检渲染并返回给AE。仅仅在某些特定的选择器期间有效 extra extra参数随着发送的指令或者（PF_Cmd_EVENT的情况）事件类型（event type）而改变。主要用来事件管理（event management）和参数监视（parameter supervision）

指令选择器（Command Selectors）

---

AE通过指令告诉效果器（effect）该做什么。一些选择器要求有返回，大多数的是可选的，尽管这样添加进它们却是有原因的…

每发送一个选择器命令，效果器接收到来自AE的PF_InData中的信息，PF_ParamDef[]中的输入和参数数组，和访问回调函数和封装函数（suite）的权限。然后通过PF_OutData返回信息给AE，并且渲染输出到PF_LayerDef（又称PF_EffectWorld）。在这些事件期间，一些特别的时间信息通过extra接收。

调用序列（Calling Sequence）

---

只有最开式的一些指令选择器是可以预知的，其它的调用序列通过用户来指派。

当插件被初始化时，首先会接收PF_Cmd_GLOBAL_SETUP指令，然后是PF_Cmd_PARAM_SETUP。每次用户添加一个效果器到一个图层是，就会发出一个PF_Cmd_SEQUENCE_SETUP指令。

对于每一个由基础的非SmartFX效果器渲染的帧来说，AE都会发送一个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_SEQUECE_SETDOWN在用户移除效果器或者关掉当前项目，退出插件的时候被发送。PF_Cmd_SEQUENCE_RESETUP在项目加载或者当前图层改变时被发送。PF_Cmd_SEQUENCE_FLATTEN在AE项目被写入磁盘时被发送。

当用户从Effect Controls Window(ECW)中选择About时PF_Cmd_ABOUT`被发送…

当AE关闭，或者最后一个效果器的实例被移除时PF_Cmd_GLOBAL_SETDOWN被发送。不要用该信息来判断插件是否从存储器中移除，而应该使用系统特定的入口函数。

选择器（selector） 作用 全局选择器：所有的插件都必须回应这些指令 PF_Cmd_ABOUT 显示一个描述插件的对话框。如果填充信息out_data>return_msg，AE将会在一个模态对话框显示该信息。在该对话框中包含你的插件版本信息。Mac系统上，当前的资源文件会在该命令期间配置到效果器模型上。 PF_Cmd_GLOBAL_SETUP 设置任意需要的标志位和PF_OutData字段（包括Out_data>my_version）来描述你的插件的行为 PF_Cmd_GLOBAL)SETUDOWN 释放所有的全局数据（在你需要释放的时候被触发） PF_Cmd_PARAM_SETUP 通过PF_ADD_PARMA来描述和注册你的参数。同时注册用户自定义的接口元素。设置PF_OutData>参数的数目以匹配参数数目 序列选择器：控制序列的数据操作 PF_Cmd_SEQUENCE_SETUP 释放并初始化任意特定的序列数据。当效果器首次使用时触发。PF_InData在此时得到初始化 PF_Cmd_SEQUENCE_RESETUP 重新创建序列数据。在合成前，当序列数据从磁盘被读取或者效果被复制时触发，AE会在复制前校徽序列数据。在复制期间，PF_Cmd_SEQUENCE_RESETUP同时发送给新旧序列。在PF_Cmd_SEQUENCE_RESETUP命令之间不会有PF_Cmd_SEQUENCE_FLATTEN命令 PF_Cmd_SEQUENCE_FLATTEN 当存储和复制序列时触发。扁平化包含指针或者句柄的序列以便能够写入磁盘。这过程江河项目文件一起保存。释放未扁平化的数据并设置out_data>sequence_data指向新的扁平化数据。必须要正确的按照字节顺序亚平数据以便存储。 PF_Cmd_SEQUENCE_SETDOWN 释放所有的序列数据 帧选择器：传递给每一个待插件渲染的帧 PF_Cmd_FRAME_SETUP 释放任意的特定帧数据。考虑到一些特定帧配置的数据，在每帧数据被渲染的时候被立即发送。 … …

注意

---

PF_Cmd_USER_CHANGED_PARAM和PF_Cmd_UPDATE_PARAMS_UI之间有着很细微的区别。effect需要用户真正的改变了一个参数值（PF_Cmd_USER_CHANGED_PARAM）还是仅仅在时间轴上擦除（PF_Cmd_UPDATE_PARAMS_UI）。

PF_InData

---

AE通过PF_InData传递系统、项目、图层和音频信息。这个结构体在每个指令发送给插件之前更新。注意只有在一些特定的PF_Cmds下字段才是合法的。PF_InData非常大，你不用记住每个成员的作用。有些字段偶尔才会用到。

PF_OutData

---

你的插件通过PF_OutData传递更改给AE。需要注意的是改变这些字段的合法时间。

PF_OutFlags

---

这些标志位传递了容量和状态信息给AE。之前的版本中他们是也被用来发送一些基本信息，比如刷新UI，发送错误信息。后来这些功能被function suite（函数套？）取代了，所有新的message function都将是这种格式。然而，容量标志为仍然包含在PiPL文件中。当你做出了一个更改时，需要同时更新PiPL和源文件。在一个AE活动期间，这些标志位都可能改变。

PF_OutFlags2

---

我们在AE 5.0中加入了第二套outflags，部分原因是为了将来扩展空间，部分是为了阻止我们重定义现有标志位作用的坏习惯。至于PF_OutFlags，这些标志位中的许多都可能在一个AE活动期间改变。别忘了在做出更改的时候同时更新PiPL和源文件。

Parameters

---

Parameters是随时间变化的数据流，包括有源图像，滑块，角度，点，颜色，路径等等任意用户可操作的数据类型。他们都是作为一个PF_ParamDef类型的数组传递的，尽管这些数组中的值仅仅在一些特定的选择器下有效。

AE effect API最棒的一个方面是它的参数插值和管理方面。快门角度在四分之一的29.97fps帧速下应该变化多少？这不是你应该关心的，把它留给AE来处理吧。

在PF_Cmd_PARAMS_SETUP期间描述你插件的参数，使用PF_ADD_PARAM()。你最多可以使用非常大数量的参数，或者在使用时留给用户去筛选。理智的选择。

为了比避免不必要的问题在使用AEFX_CLR_STRUCT（在AE_Macros.h中定义）注册PF_ParamDef前应先清理它们。

PF_ParamDef

---

AE通过每个命令选择器传递给effect一个PF_ParamDef类型的数组，该数组描述了插件当前时间的各项参数。这个参数数组中的值仅仅在某些命令中有效（详见selector description）。

Param ZERO

---

PF_ParamDef的第一个参数，params[0]表示输入图像（一个PF_EffectWorld数据结构），即effect作用对象。

Parameter UI Flags

---

这些标志位用来控制一个参数的用户接口。不要把UI标志位和行为标志位弄混淆了，根据你的参数定义它们存在于不同的字段域中，如果滥用会造成不可预知的后果。

Parameter Flags

---

行为标志位和UI标志位表述了不同特性的参数。PF_Cmd_PARAM_SETUP指令期间，在添加该参数前应该先设置好它们。能够被设置的标志位详见文档。

PF_ValueDisparityFlags

---

在PF_ParamDefUnion、PF_FloatSliderDef和PF_FixedSliderDef中都有一个成员变量，PF_ValueDisparityFlags允许它们回应用户的像素值显示设置（在info palette中设置）。如果设置好了这个，该参数的值将被显示为0-1，0-255，0-32768或者0.0-1.0，具体根据设置而变。你也可以设置第一位（PF_ValueDisparityFlag_PERCEN）来追加一个百分号到参数的显示值上。

我们知道你可能永远不会做这样的事儿，但是如果你创建一个按百分比显示的参数，不要误导用户在任何超出0-100之间操作。百分比表示100以内。

PF_EffectWorld/PF_LayerDef

---

AE使用PF_EffectWorld（又称PF_LayerDef）来表示图像。

Errors

---

main()函数总会必须返回一个PF_Err。插件必须把所有的错误传递给AE。除非你自己处理这些错误，不然你一定要把所有的错误（通过回调函数或者PICA suites）都传递给AE。注意返回的要是正确的错误代码，并且要销毁所有你已经释放了的内存。

Rowbytes In PF_EffectWorlds

---

不要指望你能通过(width*sizeof(current_pixel_type)+4，或者其它任何方式，除了使用PF_EffectWorld的rowbytes，得到下一条扫描线的位置。不要写超出PF_EffectWorld标定的区域之外，这种行为可能破坏不属于你操作的图像缓存区。

为了测试你的effects是否符合PF_EffectWorld>rowbytes，在你的effect应用之后再应用Grow Boundseffect。输出缓存将有比输入更大的rowbytes（尽管它们拥有同样的逻辑大小）。

Byte Alignment

---

不能保证PF_EffectWorld中的像素是16位对齐的。一个effect可能得到一个更大的PF_EffectWorld的子区域。

Deeper Color

---

除了8位单通道色彩，AE还支持16位和32位浮点单通道色彩。effect永远不会接受带有不同比特深度的输入和输出，并且也不接受超出它们规定能够处理的更高比特深度的输入输出。

Effect Details（效果器细节）

---

AE function suites（使用AE函数套件）

---

Memory allocation（内存分配）

---

Image buffer management functions（图像存储管理函数）

---

Iteration suites（迭代套件）

---

Graphic utility suites（图形工具套件）

---

Interaction callback functions（交互回调函数）

---

Pixel aspect ratio（像素宽高比）

---

Parameters and floating point values（参数和浮点值）

---

Parameter supervision（参数管理）

---

Global, sequence, and frame data（全局，序列和帧数据）

---

Arbitrary data parameters（任意数据参数）

---

Useful utility functions（有用的工具函数）

---

Motion blur（运动模糊）

---

Working with paths（使用路径）

---

Accessing camera and light information（访问相机和光照信息）

---

Color space conversion（色彩空间转换）

---

Changing parameter orders, the nice way（改变参数顺序）

---