首页 > itarticle > AEJoy——AE插件开发中的PF_OutData

AEJoy——AE插件开发中的PF_OutData

admin 12月 03, 2021 0

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

参加该活动的第 45 篇文章

正文

PF_OutData

使用 PF_OutData 将插件所做的更改传递给 After Effects 。注意更改这些字段的有效时间。

PF_OutData 成员

字段名 描述
my_version 将这个标志(使用 PF_VERSION 宏)设置为插件代码的版本。After Effects 使用这个数据来决定加载哪个效果副本。
name 未使用
global_data 将在每次调用都会包含在 PF_InData 中，然后返回给你的句柄。使用 After Effects 的内存分配函数。
num_params After Effects 根据调用 PF_ADD_PARAM 的次数检查这个字段，以及隐式输入层。
sequence_data 这个句柄在接收到 PF_Cmd_SEQUENCE_SETUP 后即可分配，在所有后续调用中，这个句柄将包含在 PF_InData 中传递给你。
flat_sdata_size 未使用(After Effects 知道大小，因为一开始您使用它的分配函数获得内存)。
frame_data 在 PF_Cmd_FRAME_SETUP 期间分配的句柄。这永远不会写入磁盘; 它用于将从您的 PF_Cmd_FRAME_SETUP 响应信息传递到您的 PF_Cmd_RENDER 或 PF_Cmd_FRAME_SETDOWN (如果您调整输出缓冲区的大小，必须这样做)。否则，此内存很少使用。
width, height, origin 如果输出图像大小与输入不同，请在 PF_Cmd_FRAME_SETUP 期间进行设置。宽度和高度是输出缓冲区的大小，而 origin 是输入应该映射到输出中的点。要创建一个 5 像素的上下投影（drop shadow），将 origin 设置为(5,5)。
out_flags 发送消息到 After Effects 。或多个值一起。
return_msg After Effects 会显示你在这里放置的任何 C 字符串(在每个命令选择器之后勾选并清除)。
start_sampL dur_sampL dest_snd 仅用于音频命令
out_flags2 发送消息到 After Effects 。或多个值一起。

PF_OUTFLAGS

这些标志将功能和状态信息传递给 After Effects 。在以前的版本中，它们还用于发送基本消息，例如刷新 UI ，发送错误消息。这些功能已经被功能套件所取代，所有新的消息传递功能都将以这种格式出现。但是，功能标志仍然包含在 PiPL 中。在进行更改时，同时更新 PiPL 和源代码。许多这些标志可以在 After Effects 会话中更改。

字段名 含义
PF_OutFlag_KEEP_RESOURCE_OPEN 插件的资源必须在所有命令执行期间可用。在 PF_Cmd_GLOBAL_SETUP 期间，插件的资源总是打开的，但是在其他任何时候都不可用( PF_Cmd_ABOUT 和 PF_Cmd_DO_DIALOG 期间除外)，除非设置了这个标志。如果您需要在 PF_Cmd_GLOBAL_SETUP 期间以外的任何时间访问资源，请进行设置。注意:我们建议插件在全局数据中加载和存储必要的资源，而不是保持文件的资源打开
PF_OutFlag_WIDE_TIME_INPUT 该效果在除 current_time 以外的时间检出一个参数。如果你使用另一个时间的参数(包括层参数)，设置这个标志。否则，After Effects 不会正确地使你效果所使用的缓存帧无效。在 PF_Cmd_GLOBAL_SETUP 期间设置。 如果您设置了这个标志，我们强烈建议您也设置PF_OutFlag2_AUTOMATIC_WIDE_TIME_INPUT 以获得更好的性能。
PF_OutFlag_NON_PARAM_VARY 设置了这个标志后，当效果应用到静态效果时，After Effects 将不会缓存输出。否则，如果可能的话，After Effects 将缓存你的输出以用于渲染其他帧。 如果输出基于参数值以外的内容而变化，则设置此标志。当应用到静止的图像，如果效果产生变化帧，并且所有参数都是恒定的，这是一个确定信号，必须设置该标志位(如 Wave Warp)。例如，粒子效果就需要这个。 在 PF_Cmd_GLOBAL_SETUP 期间设置。如果需要，可以在PF_Cmd_QUERY_DYNAMIC_FLAGS 期间动态重写。在可能的情况下关闭此功能以提高性能。
PF_OutFlag_RESERVED6 未使用。 以前是 PF_OutFlag_SEND_PARAMS_UPDATE。被 PF_OutFlag_REFRESH_UI 取代。
PF_OutFlag_SEQUENCE_DATA_NEEDS_FLATTENING After Effects 和 Premiere Pro 都假定设置了这个标志。当序列数据包含引用项(指针、句柄)时，平展化是必要的，这些引用项必须平展化以便存储，而非平展化以便使用。参考 PF_Cmd_SEQUENCE_RESETUP。
PF_OutFlag_I_DO_DIALOG 效果会显示对话框来响应 PF_Cmd_DO_DIALOG。在 PF_Cmd_GLOBAL_SETUP 期间设置，在 PF_Cmd_SEQUENCE_SETUP 期间检查。 注意: 效果对 PF_OutFlag_I_DO_DIALOG 的响应是不可撤销的。您可以在自定义 UI 中使用任意数据，如果这样的更改有必要的话。
PF_OutFlag_USE_OUTPUT_EXTENT 效果会重视 extent_rect 的输出。在 PF_Cmd_GLOBAL_SETUP 期间设置。详细信息请参见本章末尾的正确用法。 注意:在 SmartFX 里不再使用
PF_OutFlag_SEND_DO_DIALOG 效果必须给功能显示对话框(为兼容 Photoshop 插件而添加)。After Effects 在 PF_Cmd_SEQUENCE_SETUP 之后发送 PF_Cmd_DO_DIALOG 。在 PF_Cmd_SEQUENCE_RESETUP 期间设置，而不是在 PF_Cmd_GLOBAL_SETUP 期间设置。
PF_OutFlag_DISPLAY_ERROR_MESSAGE 在错误对话框中显示 return_msg 的内容。每当 return_msg 为非 NULL 时，After Effects 会在一个对话框中显示内容，如果设置了这个标志，则出现的是一个错误对话框。在任何命令之后设置，并且可以在调试过程中使用。这也是为试用版本实现 nag 消息的好方法。
PF_OutFlag_I_EXPAND_BUFFER 效果扩展输出缓冲区。在 PF_Cmd_GLOBAL_SETUP 期间设置。设置这个标志和 PF_OutFlag_USE_OUTPUT_EXTENT ，以在 PF_Cmd_FRAME_SETUP 期间使用输出 extent_rect 和新的缓冲区大小的交集。使用 pre_effect_source_origin 字段来检测其他转换。 注意:只有在需要时才设置这个标志;它大大降低了缓存效率 注意:在 SmartFX 里不再使用
PF_OutFlag_PIX_INDEPENDENT 一个给定的像素独立于其周围的像素。在 PF_Cmd_GLOBAL_SETUP 或PF_Cmd_QUERY_DYNAMIC_FLAGS 期间设置。例如，颜色校正效果通常是像素独立的，而畸变则不是。 注意: 如果你的效果不使用一个像素的颜色值来影响相邻像素的颜色值，设置这个标志! 它可以提供显著的性能改进。
PF_OutFlag_I_WRITE_INPUT_BUFFER 效果写入输入缓冲区。这是受限使用的; 在保存分配时，它会使一些管线缓存失效。在 PF_Cmd_GLOBAL_SETUP 期间设置。
PF_OutFlag_I_SHRINK_BUFFER 这种效果会基于 extent_rect 收缩其缓冲区，以获得更高的内存效率。在 PF_Cmd_GLOBAL_SETUP 期间尽可能进行设置。 注意: 在 SmartFX 里不再使用
PF_OutFlag_WORKS_IN_PLACE 未使用
PF_OutFlag_SQUARE_PIX_ONLY 未使用
PF_OutFlag_CUSTOM_UI 该效果有一个自定义用户界面，需要 PF_Cmd_EVENT 消息。在 PF_Cmd_GLOBAL_SETUP 设置。
PF_OutFlag_RESERVED5 未使用
PF_OutFlag_REFRESH_UI 刷新整个效果控件、合成和图层窗口。在 PF_Cmd_EVENT , PF_Cmd_RENDER 和 PF_Cmd_DO_DIALOG 期间设置。如果在 PF_Cmd_EVENT 期间刷新自定义 UI ，我们建议使用更细粒度的新重绘机制。
PF_OutFlag_NOP_RENDER 在 PF_Cmd_FRAME_SETUP 期间设置此标志以使当前渲染无效。
PF_OutFlag_I_USE_SHUTTER_ANGLE 表示渲染的图像取决于 shutter_angle 的值。
PF_OutFlag_I_USE_AUDIO 效果的参数依赖于音频数据，使用 PF_CHECKOUT_LAYER_AUDIO 获得。
PF_OutFlag_I_AM_OBSOLETE 效果可以在使用它最初应用的旧项目时使用，但不会出现在效果菜单中。
PF_OutFlag_FORCE_RERENDER 效果进行了更改，需要重新渲染。PF_ChangeFlag_CHANGED_VALUE 也强制重新渲染。
PF_OutFlag_PiPL_OVERRIDES_OUTDATA_OUTFLAGS After Effects 将使用 PiPL outflags，并忽略那些在 PF_Cmd_GLOBAL_SETUP 期间设置的。
PF_OutFlag_I_HAVE_EXTERNAL_DEPENDENCIES 效果取决于外部文件(或外部字体)。如果设置的话，After Effects 会发送 PF_Cmd_GET_EXTERNAL_DEPENDENCIES。
PF_OutFlag_DEEP_COLOR_AWARE 效果处理 16 bpc 颜色
PF_OutFlag_SEND_UPDATE_PARAMS_UI 在 PF_Cmd_GLOBAL_SETUP 期间设置这个标志来接收 PF_Cmd_UPDATE_PARAMS_UI。
PF_OutFlag_AUDIO_FLOAT_ONLY 效果需要 PF_SIGNED_FLOAT 格式的音频数据。After Effects 将执行任何所需的格式转换。你也必须设置 PF_OutFlag_AUDIO_EFFECT_TOO 或 PF_OutFlag_AUDIO_EFFECT_ONLY。
PF_OutFlag_AUDIO_IIR 如果(音频)效果是无限脉冲响应（Infinite Impulse Response，IIR）滤波器，在 PF_Cmd_GLOBAL_SETUP 期间设置。如果给定时间的输出依赖于以前时间的输出，则为真。当 IIR 滤波器接收到 PF_Cmd_AUDIO_RENDER 时，输入音频时间跨度与输出音频时间跨度相同(当它们与 PF_Cmd_AUDIO_SETUP 中请求的输出时间跨度相交时)。为了响应 PF_Cmd_AUDIO_SETUP ，滤波器可以请求更早时间的音频(比如，延迟效果)。滤波器可以访问早期的参数，并且应该将它们(连同临时音频)缓存在序列数据中。如果生成的音频与请求输出音频的时间不一致，则输出音频的持续时间应设置为零。该滤波器可以利用参数和输入音频更新其延迟线（delay line）。缓存了它的延迟线后，在 PF_Cmd_AUDIO_SETUP 期间根据最后缓存的延迟线请求更多的输入音频。使用 PF_HasParamChanged 来确定缓存是否有效。
PF_OutFlag_I_SYNTHESIZE_AUDIO 如果效果产生音频，则在 PF_Cmd_GLOBAL_SETUP 时间内设置，即使是默默通过。你也必须设置 PF_OutFlag_AUDIO_EFFECT_TOO 或 PF_OutFlag_AUDIO_EFFECT_ONLY。
PF_OutFlag_AUDIO_EFFECT_TOO 如果效果改变了音频，请在 PF_Cmd_GLOBAL_SETUP 期间设置。
PF_OutFlag_AUDIO_EFFECT_ONLY 如果效果只改变音频输出，请在 PF_Cmd_GLOBAL_SETUP 期间进行设置。

PF_OUTFLAGS2

我们在 After Effects 5.0 中添加了第二组输出标记; 一方面是为了未来的扩张空间，另一方面是为了打破我们对现有标记进行再利用的坏习惯。与 PF_OutFlags 一样，许多这些标志可以在 After Effects 会话期间更改。在进行更改时，不要忘记同时更新 PiPL 和源代码。

字段名 含义
PF_OutFlag2_NONE 无
PF_OutFlag2_SUPPORTS_QUERY_DYNAMIC_FLAGS 效果响应 PF_Cmd_QUERY_DYNAMIC_FLAGS 。必须在 PiPL 和 PF_Cmd_GLOBAL_SETUP 期间设置。
PF_OutFlag2_I_USE_3D_CAMERA 该效果可以访问 3D 摄像机信息
PF_OutFlag2_I_USE_3D_LIGHTS 该效果可以访问 3D 灯光层信息
PF_OutFlag2_PARAM_GROUP_START_COLLAPSED_FLAG 这个标志本身并不控制参数组旋转的状态。每个单独参数组的初始折叠状态是在 PF_Cmd_PARAM_SETUP 期间通过在 PF_ParamFlags 中设置 PF_ParamFlag_START_COLLAPSED 标志来设置的。但这些单独设置将不会被重视，除非效果设置这个标志位。否则，所有参数组将都默认折叠。记住在 PiPL 和 PF_Cmd_GLOBAL_SETUP 期间设置这个标志。
PF_OutFlag2_I_AM_THREADSAFE 目前这没有任何作用。如果您对此感兴趣，那么您可能对下面描述的 PF_OutFlag2_PPRO_DO_NOT_CLONE_SEQUENCE_DATA_FOR_RENDER 感兴趣。
PF_OutFlag2_CAN_COMBINE_WITH_DESTINATION 最初为 Premiere 使用而添加，但不再使用。
PF_OutFlag2_DOESNT_NEED_EMPTY_PIXELS 为渲染优化而添加;收缩传递给效果的输入缓冲区以排除任何空像素(其中空意味着 “alpha 为 0” 除非设置了 PF_OutFlag2_REVEALS_ZERO_ALPHA，在这种情况下 RGB 也必须为零)。 在 PF_Cmd_GLOBAL_SETUP 或 PF_Cmd_QUERY_DYNAMIC_FLAGS 期间设置。被修剪缓冲区的原点可以在 in_data>pre_effect_source_origin 中找到。这个标志和 PF_OutFlag_I_EXPAND_BUFFER 都设置了的效果可能会在输入缓冲区为空时被调用，并且必须能够在不崩溃的情况下处理这种情况。 注意: 这个标志会导致输出缓冲区的大小发生改变。 注意：在 SmartFX 里不再使用
PF_OutFlag2_REVEALS_ZERO_ALPHA 这是标志实现者最需要注意的一点，因为它表示默认行为中的一个更改。如果效果可以采用 零 alpha 像素并显示其中的 RGB 数据，则设置此标志(就像我们的 Set Channels 效果)。这告诉 After Effects 在确定输入效果时不要修剪这些像素。这个标志可以在 PF_Cmd_QUERY_DYNAMIC_FLAGS 期间更改。请注意，虽然这个标志会导致 extent_hint 的大小发生变化，但它不会改变图像缓冲区的大小。 在 6.0 版本中，遮罩边界框外的像素被置零。如果你的效果可以显示这样的像素，通过设置这个标志告诉 AE 不要丢弃这些 RGB 值。如果你的效果并不总是显示这样的像素，动态设置这个标记位。 要看看你的效果是否需要设置这个标记位的话，应用一个明显小于该层的遮罩到一个纯色层，然后应用效果并设置它的 alpha 正在修改（alpha-modifying）状态。如果遮罩的矩形边界框变得可见，则需要将此标记为需要设置。
PF_OutFlag2_PRESERVES_FULLY_OPAQUE_PIXELS 保留那些像素!
PF_OutFlag2_SUPPORTS_SMART_RENDER 该效果使用 SmartFX API。
PF_OutFlag2_FLOAT_COLOR_AWARE 该效果支持 32-bpc 浮点颜色表示。 注意: PF_OutFlag2_SUPPORTS_SMART_RENDER 也必须设置。
PF_OutFlag2_I_USE_COLORSPACE_ENUMERATION 这是用于在 Premiere Pro 中优化不同颜色空间的效果。更多细节请参见 Premiere Pro SDK。
PF_OutFlag2_I_AM_DEPRECATED 在 PF_Cmd_GLOBAL_SETUP 期间设置这个效果，将其放在本地化的在效果面板中的 “Obsolete” 文件夹内。比较 PF_OutFlag_I_AM_OBSOLETE。
PF_OutFlag2_PPRO_DO_NOT_CLONE_SEQUENCE_DATA_FOR_RENDER 在 Premiere Pro 内支持，而不是在 After Effects 。这将影响 Premiere Pro 如何使用多线程驱动插件。
PF_OutFlag2_AUTOMATIC_WIDE_-TIME_INPUT 在 PF_Cmd_GLOBAL_SETUP 期间设置。需要设置 PF_OutFlag_WIDE_TIME_INPUT (这允许您支持旧主机)，但实际上会覆盖该标志。 设置后，将跟踪所有参数签出，以便主机了解超时依赖关系，从而更加高效。例如，如果您只设置了旧的 PF_OutFlag_WIDE_TIME_INPUT，那么任何时候任何东西发生变化，都将被调用来重新渲染。有了这个标志的话，如果给定的第 17 帧已经检出了 0-17 的内容，AE 将知道在第 18 帧以上的任何更改都不会影响缓存的帧。 注意，如果你使用这个新标志，你一定不能在你的序列数据中缓存任何时间依赖的数据(或任何其他地方)，除非，在使用时间依赖的数据之前，你也从 PF_ParamUtilSuite3 中使用 PF_GetCurrentState() / PF_AreStatesIdentical() 验证了缓存。 这只适用于 SmartFX (那些设置了 PF_OutFlag2_SUPPORTS_SMART_RENDER )。如果你没有设置，After Effects 将会默默地将 PF_OutFlag_WIDE_TIME_INPUT 作为代替。
PF_OutFlag2_I_USE_COMP_TIMECODE 在 PF_Cmd_GLOBAL_SETUP 设置。这让 AE 知道，如果合成开始时间和/或丢帧设置已经被修改的话，它应该渲染一个效果。
PF_OutFlag2_DEPENDS_ON_UNREFERENCED_MASKS CS6 新增。如果你要查看路径参数中没有直接引用的路径，那么就设置这个标记，例如，你要在所有遮罩上画一个描边。这是需要的，所以 After Effects 知道，当一个遮罩被修改时，似乎没有被你的效果所引用，则你的输出无效。在 PF_Cmd_GLOBAL_SETUP 或 PF_Cmd_QUERY_DYNAMIC_FLAGS 中设置。
PF_OutFlag2_OUTPUT_IS_WATERMARKED CS6 新增。在 PF_Cmd_GLOBAL_SETUP 期间设置此值，如果您的输出将以某种方式加上水印，使其不适合最终使用，可能是因为用户使用的是未授权的演示版本。在 PF_Cmd_QUERY_DYNAMIC_FLAGS 的应用会话过程中改变这种状态是可以的，例如浮动的许可证状态发生了变化。 实际上异步改变这个状态的插件作者必须小心让下一个渲染与从 PF_Cmd_QUERY_DYNAMIC_FLAGS 返回的上一个状态相匹配，否则竞争条件可能会导致不正确的帧被缓存。(如果你只在响应 DO_DIALOG 时修改这个，这就不是问题了。)
PF_OutFlag2_SUPPORTS_GPU_RENDER_F32 16.0 新增。在 PF_Cmd_GLOBAL_SETUP 中设置，这表示 GPU 支持。该效果将在 GPU 选择器中被调用，并将在 GUI 中标记为 GPU 支持。在 PF_Cmd_GPU_DEVICE_SETUP 时，这些标志表示特定设备和框架的渲染能力。

新标记位

PF_OutFlag2_SUPPORTS_THREADED_RENDERING

在 2020 年 6 月开始的 After Effects 测试版中可用，以及 After Effects 2022。

在 PF_Cmd_GLOBAL_SETUP 期间设置，这表示效果支持在多个线程上同时渲染。一个层上的单个或多个应用程序可以被调用以在多个线程上同时渲染。

这个标志表明效果支持同时在多个线程上渲染。一个层上的单个或多个应用程序可以被调用以在多个线程上同时渲染。

如果您正在使用 PF_OutFlag_SEQUENCE_DATA_NEEDS_FLATTENING 标志，记住也要设置 PF_OutFlag2_SUPPORTS_GET_FLATTENED_SEQUENCE_DATA 标志。有关更多信息，请参见多帧渲染中的序列数据。

这个标志应该只在那些在 AE 中启用多帧渲染并经过测试为线程安全的插件上设置。

有关如何使用此标志的更多信息，请参阅 效果细节下的 AE 中的多帧渲染。

PF_OutFlag2_MUTABLE_RENDER_SEQUENCE_DATA_SLOWER

在 2021 年 3 月开始的 After Effects 测试版中可用，以及 After Effects 2022。

指示效果需要为每个渲染线程复制序列数据，从而允许每个渲染都有可以写入的序列数据。注意，对序列数据的更改将被定期（目前在渲染帧的每个跨度之后，比如单个 RAM 预览或渲染队列导出）丢弃。

这个标志应该只在那些在 AE 中启用多帧渲染并经过测试为线程安全的插件上设置。

有关如何使用此标志的更多信息，请参阅 效果细节下的 AE 中的多帧渲染。

微海报分享

近期文章

近期评论

标签

热门

文章归档

分类目录

功能