效果器基础(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 Bounds
effect。输出缓存将有比输入更大的rowbytes
(尽管它们拥有同样的逻辑大小)。
Byte Alignment
不能保证PF_EffectWorld
中的像素是16位对齐的。一个effect可能得到一个更大的PF_EffectWorld
的子区域。
Deeper Color
除了8位单通道色彩,AE还支持16位和32位浮点单通道色彩。effect永远不会接受带有不同比特深度的输入和输出,并且也不接受超出它们规定能够处理的更高比特深度的输入输出。