第一章 介绍
其他文章链接
工程示例
当前API支持的每种类型的插件至少都有一个示例，以及用于说明特定概念的项目。
在示例项目中，我们尽可能地使代码保持简单。一个花哨的实现方式可能会让我们在编程课上取得好成绩，但不会帮助你理解如何使用API特性。
休息之后，我们将解释如何构建示例项目，所以请继续阅读下面的内容!
表一：示例项目描述
| 项目 | 描述 |
|---|---|
| AEGPs | AEGPs直接挂钩到After Effects的菜单和其他区域的UI。关于AEGP在UI中出现的位置，请参阅下面的详细信息。 |
| Artie | Artie的Artisans接管渲染所有3D层在一个给定的组合。这是我们内部3D渲染器使用的相同API;它非常复杂，并且暴露了大量关于After Effects渲染管道的默认信息。除非你有一个令人信服的理由来替换After Effects处理3D渲染的方式，否则你永远不需要使用这个示例。Artisans会出现在Composition > Composition Settings、Advanced选项卡、Rendering Plug-in下拉菜单中。 |
| Easy Cheese | 一个关键帧(显示在动画>关键帧助理子菜单上)，Easy Cheese显示了如何操作关键帧的各种特性(以一种不可思议的方式，类似于我们的运输插件，Easy Ease…) |
| FBIO | 练习After Effects Input/Output (AEIO) API。类似于IO示例，但支持基于帧的.ffk文件格式。注意，我们现在建议开发一个Premiere Pro Importer代替。 |
| Grabba | 从项目中的任何组合获取帧(作为插件请求格式化)。 |
| IO | 练习After Effects Input/Output (AEIO) API。支持虚构的.fak文件格式，并处理After Effects关于从此类文件中检索数据或向此类文件输出数据的所有请求。注意，我们现在建议开发一个Premiere Pro Importer代替。 |
| Mangler | Mangler是一个演示使用ADM调色板的关键帧制作者，就像我们自己的一样。 |
| Panelator | 创建一个可以与其他标准面板一起停靠的面板。注意:用这种方式创建面板要比使用HTML5面板SDK多得多。我们建议从这个SDK开始。 |
| Persisto | 演示如何从After Effects首选项文件读取和写入信息。 |
| ProjDumper | 创建一个文本文件，表示After Effects项目中的每个元素。 |
| Projector | 导入(虚构的).sdk文件格式，并使用AEGP API调用创建一个项目。当您想知道如何获取或设置项目元素的某些特征时，请首先查看这里。注意:Projector.h中有一些硬编码的路径。如果不将这些设置为引用磁盘上的实际媒体，那么在运行这个插件时将会出现错误。不要怪我们;改变这些路径就可以! |
| QueueBert | 发音“Cue-BARE !”QueueBert操作呈现队列项以及与之相关的输出模块的所有方面。 |
| Streamie | 操作流，包括动态的和固定的。 |
| Sweetie | Sweetie使用PICA(或“Suite Pea”)API提供一个功能套件，供其他插件使用。如果您正在编写多个依赖于同一个图像处理库的插件，那么您可以使用这样的套件来提供库功能。 |
| Text Twiddler | 操作文本层及其内容。 |
| Effects | 所有的效果都会出现在效果和预设面板以及效果菜单中 |
| Checkout | 在指定的时间，检出(After Effects的帧缓存)来自另一层的输入帧。这对于所有带有图层参数的效果来说是一个重要的概念。Premiere Pro兼容 |
| Convolutrix | 练习我们的图像卷积回调。Premiere Pro兼容。 |
| Gamma Table | 展示如何管理序列数据，以及如何使用迭代回调。为了怀旧起见，我们将这个样本保留在C语言中;由于它依赖于版本3，它也与许多第三方插件主机兼容。x的API功能。 |
| GLator | CC 2017新版本。演示了在一个效果插件中正确的OpenGL上下文管理。 |
| Paramarama | 练习其他示例中不使用的任意参数类型。Premiere Pro兼容。 |
| PathMaster | 演示如何从效果中访问路径。 |
| Portable | 演示如何检测和响应几个不同的插件主机。Premiere Pro兼容。 |
| Resizer | Resizer调整输出缓冲区的大小。这对于像发光和阴影这样的效果很有用，如果它们不扩展输出缓冲区，它们将在层的边缘被截断。Premiere Pro兼容。 |
| SDK Backwards | 反转一层的音频，并将其与可关键帧的正弦波混合。 |
| SDK Noise | Premiere Pro兼容，在Premiere Pro里演示32位和YUV渲染 |
| Shifter | 在输出缓冲区中移动图像，并使用transform_world和亚像素采样函数。 |
| SmartyPants | 演示支持浮点像素所需的SmartFX API。 |
| Transformer | 练习我们的图像变换回调。 |
| Effect Template | |
| Skeleton | Skeleton是开发效果的起点。Premiere Pro兼容。 |
| Effects with Custom UI | |
| CCU | 实现了一个自定义的用户界面在组合和层窗口，支持像素宽高比和下采样比。Premiere Pro兼容。 |
| ColorGrid | 演示如何使用任意数据类型参数。也有一个漂亮的自定义UI。Premiere Pro兼容。 |
| Custom ECW UI | 在effects controls窗口中实现了一个非常无聊的自定义用户界面，并展示了如何响应大量的UI事件。 |
| Histogrid | CC 2015(13.5)新增。这个例子展示了自定义UI如何访问异步呈现的上游帧，以便在CC 2015及以后的版本中进行轻量级处理。这个效果从上游帧计算一个采样的10x10颜色网格，并显示该颜色网格的预览。在渲染中，计算出一个更高质量的网格，并用来修改输出图像，创建一个彩色网格与原始图像的混合。 |
| Supervisor | 演示如何基于其他参数的值控制参数(包括值和UI)。Premiere Pro兼容。 |
| BlitHook | |
| EMP | 外部监控预览。以此为起点，添加对从合成面板输出视频到视频硬件的支持。 |
示例工程编译
我们已经将示例项目合并为一个主项目，存储在SDK的Examples文件夹中。对于macOS，它是Buildall.xcodeproj;对于Windows，它是Buildall.sln。
在你的IDE中，需要你修改编译的目标文件夹地址：AE的插件目录，对整个开发环境而言，我们推荐你使用以下路径。对Mac IOS来说：/Library/Application Support/Adobe/Common/Plug-ins/[version]/MediaCore/Version，
版本号在所有CC版本上固定为 7.0，早期版本的话是：CSx。
如：/Library/Application Support/Adobe/Common/Plug-ins/7.0/MediaCore/
或者/Library/Application Support/Adobe/Common/Plug-ins/CS6/MediaCore/
Windows对应的路径如下：[Program Files]\Adobe\Common\Plug-ins\[version]\MediaCore\
如：C:\Program Files\Adobe\Common\Plug-ins\7.0\MediaCore\
或：C:\Program Files\Adobe\Common\Plug-ins\CS6\MediaCore\
注意，此Windows路径仅推荐用于开发目的，Windows安装程序应该遵循后续的指导方针。
在Xcode中，你可以在Xcode首选项>位置>派生数据>高级设置所有项目一次设置此路径。在“构建位置”下选择“自定义”，并填写路径。
在Visual Studio中，为了方便起见，我们使用环境变量AE_PLUGIN_BUILD_DIR为所有示例项目指定了输出路径。您需要将其设置为系统的用户环境变量。在Windows 7操作系统中，右键单击“我的电脑>属性>”，在左侧选择“高级系统设置”。在新的对话框中，点击Environment Variables按钮。在用户变量区域中，创建一个名为AE_PLUGIN_BUILD_DIR的新变量，并使用上面描述的路径。注销窗口并重新登录，以便设置变量。
或者，可以在Visual Studio中分别为每个项目设置输出路径，方法是在“解决方案资源管理器”中右键单击项目，选择“属性”，然后在配置属性>链接器> General中设置输出文件。
在编译插件时，如果你看到一个链接错误，例如:" Cannot open file " [MediaCore插件路径]\plugin。，确保在管理员模式下启动Visual Studio。在Visual Studio安装中，右键单击devvenv .exe，属性>兼容性>权限级别，单击“以管理员身份运行此程序”。
调试插件
了解After Effects和插件之间交互的最好方法是在调试器中运行示例。花些时间在编译器的调试器中，以及一个与插件非常相似的示例项目中，确实会有回报。
一旦你已经像上面解释的那样直接将插件构建到插件文件夹中，下面是如何指定After Effects作为在调试会话中运行的应用程序:
在Windows里：
- 在Visual Studio解决方案中，在“解决方案资源管理器”面板中，选择要调试的项目
- 右键单击它并选择设置为启动项目
- 再次右键单击它并选择Properties
- 在Configuration Properties > Debugging >命令中，提供将运行插件的主机应用程序的可执行文件的路径(这可能是After Effects或Premiere Pro)
- 从那里你可以点击播放按钮，或者你可以启动应用程序，然后在任何点上选择调试>附加到进程
在MacOs里：
- 在Xcode中，在项目导航器中，选择要调试的xcodeproj
- 选择产品>方案>编辑方案…
- 在“运行”下，在“信息”选项卡中，选择可执行程序的主机应用程序，插件将在Adobe After Effects SDK46be中运行(这可能是After Effects或Premiere Pro)
- 您可以点击Play按钮构建并运行当前方案，也可以启动应用程序，然后在任何时候选择Debug > Attach to Process。
删除首选项
在开发插件的过程中，插件可能会将设置信息传递给After Effects，然后将这些信息存储在其首选项文件中。您可以删除首选项，在After Effects启动期间按下Ctrl-Alt-Shift / Cmd-Opt-Shift 可以让AE在重启后是一个干净的状态。
在Windows中，首选项存放在：[user folder]\AppData\Roaming\Adobe\After Effects\[version]\Adobe After Effects [version]-x64 Prefs.txt
在MacOS中，他们存在：~/Library/Preferences/Adobe/After Effects/[version]/Adobe After Effects [version]-x64 Prefs
跨版本兼容性
通常，你应该使用最新的After Effects SDK头文件来编译你的插件。这使得插件可以使用最新的套件和API功能。当After Effects的新版本发布时，你通常不需要提供新版本，除非你想利用通过新的SDK暴露的新功能。但是，在声明与新版本的兼容性之前，您应该总是在After Effects的新版本中测试您的插件。
您应该在插件支持的After Effects的每个版本中彻底测试插件。如果你需要添加一个只在After Effects的特定版本中运行的条件代码块，你可以在PF_InData中检查API版本。或者在EntryPointFunc()中传入您的AEGP的major和minor_versionL中。
为了进行更精确的版本检查，插件可以使用AEGP_ExecuteScript运行脚本，查询以下属性之一:app.version，返回示例 11.0.1x12app.buildNumber，返回示例 12
表二：API版本
| 发行版 | Effect API 版本 | AEGP API 版本 |
|---|---|---|
| 15.0 | 13.15 | |
| CC 2017.1 (14.2) | 13.14 | |
| CC 2017 (14.0) | 13.13 | 114.0 |
| CC 2015.3 (13.8) | 13.11 | 113.8 |
| CC 2015 (13.7) | 13.10 | 113.7 |
| CC 2015 (13.6) | 13.10 | |
| CC 2015 (13.5, 13.5.1) | 13.9 | 113.5 |
| CC 2014 (13.0-13.2) | 13.7 | 113 |
| CC (12.2) | 13.6 | 112.2 |
| CC (12.1) | 13.5 | 112.1 |
| CC (12.0) | 13.4 | 112.0 |
| CS6.0.1 (11.0.1) | 13.3 | 111.0 |
| CS6 (11.0) | 13.2 | 111.0 |
| CS5.5 | 13.1 | 17.0 |
| CS5 (10.0) | 13.0 | 17.0 |
| CS4 (9.0) | 12.14 | 16.24 |
| CS3 (8.0) | 12.14 | 16.24 |
| 7.0 | 12.12 | |
| 6.5, 6.0 | 12.10 如果需要区分6.0和6.5，请检查是否有更新的AEGP套件 |
|
| 5.0 | 12.5 | |
| 4.1 | 12.2 | |
| 3.1 | 11.6 |
第三方插件主机
一些开发人员对使用After Effects版本的新API特性持谨慎态度，以保持与部分实现主机的兼容性。您可以通过检查PF_InData>appl_id 来区分主机应用程序。After Effects使用 appl_id = 'FXTC'。Premiere Pro使用 PrMr 。在撰写本文时，没有第三方主机支持SmartFX或我们的AEGP功能。另外，请参阅Premiere Pro和其他主机的兼容性章节
PIPL资源
插件属性列表(PiPLs)起源于二十多年前的Adobe Photoshop，它提供了有关插件行为的基本信息，而不需要执行插件。PiPLs在很大程度上被After Effects中的 PF_Cmd_GLOBAL_SETUP 和动态outflags所取代。但是，由于历史原因，PF_Cmd_GLOBAL_SETUP 过程中所显示的行为必须与PiPL中的行为一致。
PiPL指定插件的入口点、显示名称以及插件的匹配名称。与插件的显示名不同，匹配名是唯一的常量标识符，可以动态更改。从CC开始，显示名称最长可达47个字符。此前，他们被限制在31个字符。
为了实现跨平台兼容性，请像示例一样，为您的插件的macOS和Windows版本使用单个.r文件。PiPL属性必须始终按照macos特定的字节顺序。在Windows上，PiPLs是通过pipltool.exe处理.r文件来编译的，它将.r文件转换成二进制的.rc文件。Windows示例项目都包含自定义构建步骤，使用跨平台的.r文件和我们的cnvtpipl.exe命令行工具生成.rc文件。基于现有的示例插件进行开发，这样的构建步骤将实现方式才是正确的。
入口
插件的入口点是通过Windows和macOS上的PiPL导出的。如果插件支持多个平台，那么必须在PiPL中定义多个入口点。不需要Windows .def文件或手动导出，除非您还指定了其他特定于操作系统的入口点。
在 entry.h 中定义的宏(在 \SDK\Examples\Headers 目录中)负责导出每个样本的入口点函数。所有示例项目入口点函数对于effects是EffectMain()，对于AEGPs是 EntryPointFunc()。
PiPL 资源和 MicroSoft Visual Studio
要使用Microsoft Visual Studio .NET的资源和 pipltool 生成的资源，#include 自定义构建步骤的输出到Microsoft生成的.rc文件中。
如：
// in file WhizBang.rc, generated by .NET.
#include “WhizBang_PiPL_temp.rc” // pipltool.exe’s output
如果修改一个示例插件，将 pipltool.exe 生成的文件的名称更改为 WhizBang_PiPL_temp.rc，否则每次你建立时它将覆盖微软资源，这样是不好的。
多PiPL
可以(但不推荐)使用多个pipl在同一个文件中包含多个插件(包括AEGPs和effects)。如果在同一个文件中有针对AEGPs和效果的PiPLs，那么AEGPs必须放在第一位!
没有其他主机(甚至连Premiere Pro也不支持)支持多个pip在同一个.dll或代码片段中指向多个效果。另外，如果您需要更新一个插件，您真的想要发布所有插件的新版本吗?我们建议每个代码片段使用一个PiPL和一个插件。
PiPL Bit 绝对机密
对于那些使用c++并且必须一直加载插件的人(为了避免v-tables被丢弃，以及其他危险)，可以将PiPL的 AE_Reserved_Info 成员设置为 8。在过去的几年里，我们一直非常严格地要求插件具有良好的内存管理，并对优雅的卸载插件。我们知道有时候，在没有警告的情况下卸载会真正破坏插件的工作(和v-tables)，因此提供了这个解决方案。好好表现，谨慎地执行内存管理，只把你的能力用在好的地方。
我为什么需要知道这些
你不需要; 但是After Effects需要。如果您遵循我们的建议，并将您的项目建立在SDK示例的基础上，您可以简单地更改包含您的PiPL定义的.r文件，您的插件资源将在下一次构建时自动更新。这会感觉很不错。或者，如果您曾经修改过自定义构建步骤，那么您将感到痛苦。
异常
处理插件代码在插件内生成的所有异常。将那些不是源自插件代码的代码传递给After Effects。After Effects的api是为用C编写的插件设计的，所以不要期望有异常。如果在插件中抛出一个After Effects，它将立即崩溃。效果示例在 main() 函数中使用防火墙围绕switch语句，AEGPs将它们的函数钩子包装在 try/catch 块中。
应该把插件安装在哪里
在公共位置安装你的插件将允许他们被Premiere Pro加载，如果你也安装了 Premiere Pro的话。
在Windows上，common plug-ins文件夹可以在以下注册表项中找到(作为显式路径):HKLM\SOFTWARE\Adobe\After Effects\[version]\CommonPluginInstallPath
在MacOS里， common plu-ins文件夹在：/Library/Application Support/Adobe/Common/Plug-ins/[version]/MediaCore
不要使用 macOS 里的别名，也不要使用 windows 的快捷方式。因为 Premiere Pro 不支持。
是不是一定要把插件安装在公共文件夹？
你可能有很好的理由只安装After Effects插件，比如，你的插件依赖的的套件和功能在Premiere Pro中无法提供。虽然我们强烈建议您尽可能使用common文件夹，但在某些情况下，仍然可以使用ae特定的插件文件夹。
在Windows上，特定于应用程序的插件文件夹(作为显式路径)可以在以下注册表项中找到:\\HKEY_LOCAL_MACHINE\SOFTWARE\Adobe\After Effects\(version)\PluginInstallPath
在MacOS里，特定于应用程序的文件夹在：/Applications/Adobe After Effects [version]/Plug-ins/
当启动后，After Effects递归下降10层深入到它的路径的子目录。macOS别名会被遍历，但Windows快捷方式不会。不扫描以圆括号结尾的目录，或者以符号 “*” (macOS)或 “~” (Windows) 开头的目录。
尽量尝试在AE与Premiere Pro之间构建一个间隔。用户仍然可以找到使用我们可爱的集成优势的方法 —— 你的Effects效果仍然对使用该效果将Permiere Pro和AE合成动态连接的用户可用，并且可以把它放置到 Premiere Pro的序列帧上。
本地化
从CC开始，在 PF App Suite添加了 PF_AppGetLanguage() 来查询当前语言，以便插件可以使用正确的语言字符串。
在将字符串传递给AE时，API的某些部分会接受Unicode。 在其他区域，例如，当在 PF_Cmd_PARAMS_SETUP 期间指定效果参数名称时，您需要在char字符串中传递名称。 对于这些非Unicode字符串，AE使用应用程序的当前语言环境将字符串解释为多字节编码。 要构建这些字符串，在Windows上，可以使用 WideCharToMultiByte() 函数，将CP_OEMCP 指定为第一个参数。 在macOS上，使用 GetApplicationTextEncoding() 返回的编码。
在AE中使用不同的语言进行测试不需要重新安装操作系统，但确实需要重新安装AE：
对于Windows，将系统区域设置更改为目标语言（控制面板>区域和语言>管理选项卡>更改系统区域设置），重新启动计算机，然后以相应的语言安装AE。
对于Mac，在首选语言列表中将目标语言设置为主要语言，然后以相应的语言安装AE。
下一步
现在，您将了解什么是插件，它们可以做什么以及After Effects如何与它们通信。 在下一章中，我们将介绍Effects效果插件的基础。
原文
There is at least one sample of every type of plug-in supported by the current API, as well as projects to illustrate particular concepts.
In the sample projects, we’ve kept the code as simple as possible. A showy implementation might get us good grades in a programming class, but won’t help you understand how to use API features.
After the break, we explain how to build the sample projects, so keep reading below!
We’ve combined the sample projects into a single master project, stored in the Examples folder of the SDK. For macOS, it is
Buildall.xcodeproj; for Windows, it isBuildAll.sln.
In your IDE, you’ll need to change the output folder of your project to build into After Effects’ plug-in folder. For development, we recommend using the following path for macOS:/Library/Application Support/Adobe/Common/Plug-ins/[version]/MediaCore/Version is locked at 7.0 for all CC versions, or CSx for earlier versions.for example: /Library/Application Support/Adobe/Common/Plug-ins/7.0/MediaCore/or: /Library/Application Support/Adobe/Common/Plug-ins/CS6/MediaCore/
Note that this Windows path is only recommended for development purposes, Windows installers should follow the guidelines here.
In Xcode, you can set this path once for all projects in the Xcode Preferences > Locations > Derived Data > Advanced. Under Build Location choose Custom, and fill in the path.
In Visual Studio, for convenience, we have specified the output path for all sample projects using the environment variable AE_PLUGIN_BUILD_DIR. You’ll need to set this as a user environment variable for your system. On Windows 7, right-click My Computer > Properties>and in the left sidebar choose Advanced System Settings. In the new dialog, hit the Environment Variables button. In the User variables area, create a New variable named AE_PLUGIN_BUILD_DIR, and with the path described above. Log out of Windows and log back in so that the variable will be set.
Alternatively, you can set output path for each project individually in Visual Studio by right-clicking a project in the Solution Explorer, choosing Properties, and then in Configuration Properties > Linker > General, set the Output File.
When compiling the plug-ins, if you see a link error such as:“Cannot open file “[MediaCore plug-ins path]\plugin.prm”, make sure to launch Visual Studio in administrator mode. In your Visual Studio installation, right-click devenv.exe, Properties > Compatibility > Privilege Level, click “Run this program as an administrator”.
The best way to learn the interaction(s) between After Effects and plug-ins is running the samples in your debugger. Spending some quality time in your compiler’s debugger, and a sample project that closely resembles your plug-in, can really pay off.
Once you’ve got the plug-in building directly into the plug-ins folder as explained above, here’s how to specify After Effects as the application to run during debug sessions:
During the course of developing a plug-in, your plug-in may pass settings information to After Effects, which is then stored in its preferences file. You may delete the preferences and restart After Effects with a clean slate by holding down Ctrl-Alt-Shift / Cmd-Opt-Shift during launch.
Generally, you should compile your plug-ins with the latest After Effects SDK headers. This makes the latest suites and API functionality available to your plug-ins. When a new version of After Effects is released, you generally will not need to provide a new version unless you wish to take advantage of new functionality exposed through the new SDK. However, you should always test your plug-in in new versions of After Effects before claiming compatibility with new versions.
You should test your plug-in thoroughly in each version of After Effects supported by your plug-in. If you need to add a conditional block of code to be run only in specific versions of After Effects, you can always check the API version in
PF_InData.version for effects, or in themajorandminor_versionLpassed into your AEGP in theEntryPointFunc().
For even more precise version checking, a plug-in can run a script using AEGP_ExecuteScript, querying one of the following attributes:app.version - e.g. 11.0.1x12
Some developers are wary of using each After Effects release’s new API features, to maintain compatibility with hosts with partial implementations. You can distinguish between host applications by checking PF_InData>appl_id. After Effects uses the appl_id‘FXTC’. Premiere Pro uses ‘PrMr’. As of this writing, no third party hosts support SmartFX, or our AEGP functions. Also, see the chapter on compatibility with Premiere Pro and other hosts.
Originating in Adobe Photoshop over two decades ago, Plug-In Property Lists, or PiPLs, are resources which provide basic information about a plug-in’s behavior, without executing the plug-in. PiPLs have been largely supplanted within After Effects by PF_Cmd_GLOBAL_SETUP and dynamic outflags. However, for archaeological reasons, the behaviors indicated during PF_Cmd_GLOBAL_SETUP must agree with those in the PiPL.
A PiPL specifies the entry point of a plug-in, the display name, as well as the plug-in’s match name. The match name is a unique, constant identifier, unlike a plug-in’s display name, which may be changed dynamically. Starting in CC, display names can be up to 47 characters long. Previously, they were limited to 31 characters.
In the interest of cross-platform compatibility, use a single .r file for both macOS and Windows versions of your plug-in, like the samples do. PiPL properties must always be in macOS-specific byte order. On Windows, PiPLs are compiled by processing a .r file through pipltool.exe, which converts the .r file into a binary .rc file. The Windows sample projects all contain custom build steps which generate a .rc file, using a cross-platform .r file and our cnvtpipl.exe command line utility. Base your development on an existing sample plug-in and the build step will be correctly implemented.
Your plug-in’s entry point is exported through the PiPL on Windows and macOS. If the plug-in supports multiple platforms, then multiple entry points must be defined in the PiPL. There is no need for a Windows .def file or manual exports, unless you’re also designating some other OS-specific entry point.
To use resources from Microsoft Visual Studio .NET with pipltool-generated resources, #include the output of the custom build steps into the Microsoft-generated .rc file.
If modifying a sample plug-in, change the name of the file generated by pipltool.exe to something like WhizBang_PiPL_temp.rc, or it will overwrite the Microsoft resources each time you build; not good.
It is possible, but not recommended, to include multiple plug-ins (both AEGPs and effects) in the same file, using multiple PiPLs. If there are PiPLs for both AEGPs and effects in the same file, the AEGPs must come first!
No other hosts (not even Premiere Pro) support multiple PiPLs pointing to multiple effects within the same .dll or code fragment. Also, if you need to update one plug-in, do you really want to ship a new build of all your plug-ins? We recommend one PiPL, and one plug-in, per code fragment.
For those of you who use C++ and simply must keep your plug-ins loaded all the time (to avoid having your v-tables trashed, among other hazards), set the PiPL’s AE_Reserved_Info member to 8. Over the years we’ve been quite stringent, insisting that plug-ins be good memory citizens and respond gracefully to getting unloaded. We know there are cases in which being unloaded with no warning can really ruin a plug-in’s day (and v-tables), and so have provided this work-around. Be nice, perform scrupulous memory management, and only use your powers for good.
You don’t; After Effects does. If you follow our advice and base your projects on the SDK samples, you can simply change the .r file containing your PiPL definition(s), and your plug-in’s resources will be automagically updated the next time you build. Feel the love. Or, if you ever tinker with the custom build steps, feel the pain.
Handle all exceptions generated by your plug-in’s code, within your plug-in. Pass those which didn’t originate in your plug-in’s code to After Effects. After Effects’ APIs are designed for plug-ins written in C, and don’t expect exceptions. After Effects will crash immediately if one is thrown from within a plug-in. The effect samples use a firewall around the switch statement in the main() function, and the AEGPs wrap their function hooks in try/catch blocks.
Installing your plug-ins in the common location will allow them to be loaded by Premiere Pro, if installed.
You may have good reason to install your plug-in for only After Effects, for example, if your plug-in depends on suites and functionality not available in Premiere Pro. We strongly recommend that you use the common folder whenever possible, but for certain cases, the AE-specific plug-in folder is still available.
When launched, After Effects recursively descends 10 levels deep into subdirectories of its path. macOS aliases are traversed, but Windows shortcuts are not. Directories terminated by parentheses or preceded by the symbols ¬ (macOS) or ~ (Windows) are not scanned.
Try as you might to build a fence between AE and Premiere Pro, users will still find ways to get across using our lovely integration goodness - Your effects will still be available to Premiere Pro users who create a dynamically linked AE composition with your effect, and put it in a Premiere Pro sequence.
Starting in CC, PF App Suite adds PF_AppGetLanguage() to query the current language so that a plug-in can use the correct language string.
When passing strings to AE, some parts of the API accept Unicode. In other areas, for example when specifying effect parameter names during PF_Cmd_PARAMS_SETUP, you’ll need to pass the names in a char string. For these non-Unicode strings, AE interprets strings as being multi-byte encoded using the application’s current locale. To build these strings, on Windows you can use the WideCharToMultiByte() function, specifying CP_OEMCP as the first argument. On macOS, use the encoding returned by GetApplicationTextEncoding().
Testing with different languages in AE doesn’t require an OS reinstallation, but it does require a reinstallation of AE:
For Win, change the system locale to the targeted language (control panel > region and language > administrative tab > change system locale), restart machine, and then install AE in the according language.
For Mac, set targeted language to the primary language in the preferred language list, and then install AE in the according language.
You now have an understanding of what plug-ins are, what they can do, and how After Effects communicates with them. We will cover the bascis of effects plug-ins in the next chapter.