AEJoy —— AE 插件开发中的 PF_InData 结构体

「这是我参与11月更文挑战的第 27 天，活动详情查看：2021最后一次更文挑战」。

参加该活动的第 44 篇文章

正文

PF_InData

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

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 类型的 Gestalt 值（请参阅 Macintosh 内部，第 6 卷）。 在 Windows 上未定义。
what_fpu	在 macOS 下，它包含 FPU 类型的 Gestalt 值。 在 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 ），请使用 tile_scale，而不要使用 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 的单位为 1/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	输入缓冲区中源图像的原点。 仅在与帧选择器一起发送时有效。 仅当在同一层上此效果之前的一个或多个效果调整了输出缓冲区的大小并移动了原点时，才为非零。 检查调整大小和新原点，以确定输出区域。 这对于具有隐式空间操作（点控件除外）的效果很有用，例如围绕图像中心翻转文件。 注意：检出点参数针对当前时间（而不是检出时间）的 pre-effect 原点进行调整。
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 是图层在合成中可见的部分。 在您的图层上添加一个遮罩并四处移动。 这将改变 extent_hint，它包含图像的所有非零 alpha 区域。

in_data -> extent_hint 是这两个矩形（合成和遮罩）的交集，并且每当它们发生变化就改变。

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

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

代码正确运行后，启用缓存并查看效果需要多长时间重新渲染一次。 考虑一个阴影（drop shadow）； 用户经常将静态阴影应用于静止图像。

output -> extent_hint 被忽略 z 的话，那么将更频繁地使用缓存。

要获得缓冲区扩展（buffer-expanding）效果，请将 output> extent_hint 与插件的变换范围（transformed bound）相交，并在 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 示例，并使用较大的 resize 值。 如果您的效果未正确处理 pre_effect_source_origin_x / y 的话，则打开和关闭模糊将改变输出的位置。

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