After Effects SDK Guide Release 18.2.0 Sep 26, 2021 About 1 About this Document 1 2 Version History 3 3 Introduction 5 4 What Can I Do With This SDK?7 5 Other Integration Possibilities 11 6 SDK Audience 13 7 What’s New 15 8 How To Start Creating Plug-ins 27 9 Sample Projects 29 10 Debugging Plug-ins 33 11 Compatibility Across Multiple Versions? 35 12 Third-party Plug-in Hosts? 37 13 PiPL Resources 39 14 Exceptions 41 15 Where Installers Should Put Plug-ins 43 16 Localization 45 17 Apple Silicon Support 47 18 Exporting Symbols in Effects 51 19 Next Steps 55 20 Effect Basics 57 i 21 Entry Point 59 22 Command Selectors 61 23 PF_InData 67 24 PF_OutData 75 25 Parameters 83 26 PF_ParamDef 87 27 PF_EffectWorld / PF_LayerDef 93 28 Errors 97 29 Multi-Frame Rendering in AE 99 30 Effect Details 111 31 Accessing the After Effects Function Suites 113 32 Memory Allocation 115 33 Image Buffer Management Functions 117 34 Iteration Suites 119 35 Graphics Utility Suites 123 36 Interaction Callback Functions 133 37 Pixel Aspect Ratio 139 38 Parameters & Floating Point Values 141 39 Parameter Supervision 143 40 Global, Sequence, & Frame Data 147 41 Arbitrary Data Parameters 151 42 Useful Utility Functions 155 43 Motion Blur 167 44 Working With Paths 169 45 Accessing Camera & Light Information 173 46 Color Space Conversion 175 47 Changing Parameter Orders, the Nice Way 177 48 Tips & Tricks 179 49 Compute Cache API 185 50 SmartFX 197 ii 51 Effect UI & Events 205 52 PF_EventExtra 207 53 PF_EventUnion 211 54 Custom UI & Drawbot 215 55 UI Callbacks 227 56 Tips & Tricks 229 57 Audio 231 58 Global Outflags 233 59 Audio Data Structures 235 60 Audio-Specific Float Slider Variables 237 61 Accessing Audio Data 239 62 Audio Considerations 241 63 AEGPs 243 64 Overview 245 65 Data Types 247 66 Implementation 251 67 AEGP Suites 255 68 Cheating Effect Usage of AEGP Suites 359 69 AEGP Details 361 70 Artisans 363 71 Artisan Data Types 365 72 AEIOs 387 73 Calling Sequence 391 74 AEIO_ModuleInfo 393 75 New Kids On The Function Block 399 76 Implementation Details 431 77 Premiere Pro & Other Hosts 433 78 Plug-in Installation 435 79 Basic Host Differences 437 80 Multithreading 441 iii 81 Bigger Differences 443 82 Plug-Ins. Reloaded 445 83 Effects Presets 447 84 Custom ECW UI Over A Standard Data Type 449 85 Premiere Elements 451 86 Unsupported Features 453 87 Other Hosts 455 iv CHAPTER 1 About this Document This document has changed much over the years. Part encyclopedia, part how-to guide, with multiple sedimentary layers of accreted information from more than two decades of API development and refinement. Yes, there does need to be one source of information about every last niggling detail of the After Effects APIs. How- ever, since no human in their right mind would ever want to read such a document, we’ve tried to keep it involving and interesting. As opportunity allows, we’ll try to include more diagrams, illustrations, and purdy pickshurs explaining API intrica- cies. As always, your input is valued and appreciated. 1.1 Organization The Introduction provides an overview of the integration possibilities with After Effects. It explains what plug-ins are, and how they work with After Effects. It describes the sample projects, and how to modify them. It explains where to install plug-ins, and what resources they use. The basics of effect plug-ins are discussed in Effect Basics. This overview provides information on the function parameters passed to and from an effect plug-in’s entry point. It describes capability flags, effect parameters, and image buffers. Effect Details dives into the details of developing a complete effect plug-in using the many provided callback functions. It also provides many testing ideas to ensure the plug-in is stabile. SmartFX is the extension to the effect plug-in API to support 32-bit floating point images. Effect UI & Events covers events sent to effect plug-ins, how to incorporate custom user interface elements, parameter supervision, and the reliance of custom data parameter types on Custom UI messaging. Audio effects are covered in. Audio. AEGPs details the After Effects General Plug-in (AEGP) API. Provided callback functions, hooking into internal messaging, manipulating the current contents of open projects and handling menu commands are all covered at length. 1 After Effects SDK Guide, Release 18.2.0 Artisans covers specialized plug-in 3D renderer AEGPs. AEIOs, specialized AEGPs which handle file input and output. Premiere Pro & Other Hosts discusses issues related to compatibility with Premiere Pro and other applications that support a subset of After Effects plug-ins. 1.2 Documentation Conventions Functions, structure names and general C/C++ code are in Courier; MyStruct and MyFunction(); Text in blue is hyperlinked. Command selectors are italicized; PF_Cmd_RENDER. 1.3 A Note About Coding Style Because we use the public APIs for our own plug-ins, our coding guidelines are apparent throughout the SDK. Here’s a description of the pseudo-neo-post-Hungarian notation we use. Of course, you’re welcome to code how- ever you like. If you feel strongly that we should change our internal coding standards, please post your requests at comp.sys.programmer.better.things.to.do.with.your.time, and we’ll carefully consider them before not making any changes. 1.3.1 Coding Conventions Type Suffix Example Handle H fooH pointer (to) P fooP Boolean B visibleB Float F degreesF Long L offsetL unsigned long Lu countLu short S indexS char C digitC unsigned char Cu redCu function pointer _func sample_func time value T durationT char* (NULL-terminated C string) Z nameZ rectangle R boundsR fixed rectangle FiR boundsFiR float rectangle FR boundsFR ratio Rt scale_factorRt void* PV refconPV optional parameter (must be passed, can be NULL) 0 extra_flags0 2 Chapter 1. About this Document CHAPTER 2 Version History Revision Date Documentor Notes 31 March 2021 Sean Jenkin Updated Multi-Frame Rendering documentation for sequence_data changes and Compute Cache system. Added information for supporting Universal Mac binaries for Apple Silicon effect plugins. 1 June 2020 Field Kuang Multi-Frame Rendering is now supported in AE Beta builds. See Multi-Frame Rendering in AE for more details. 1 November 2018 Bruce Bullis 16.0 release 10 November 2017 Zac Lam 15.0 release 12 May 2017 Zac Lam CC 2017.1 (14.2) release 2 November 2016 Zac Lam CC 2017 (14.0) release. 21 July 2015 Zac Lam CC 2015 (13.5) release. 12 June 2014 Zac Lam CC 2014 (13.0) release. Corrections for accuracy. Removed old version references. 15 July 2013 Zac Lam CC (12.0) release. API version changes, misc small clarifications, more details in AEIOs. 26 April 2012 Zac Lam CS6 (11.0) release. Big reorganization of the AEGPs and Artisans. Many additions throughout. 2 May 2011 Zac Lam CS5.5 (10.5) release. 28 April 2010 Zac Lam CS5 (10.0) release. 64-bit porting info. Drawbot. 4 May 2009 Zac Lam CS4 (9.0) release. Complete reorganization of first three chapters. Fleshed out documentation on Premiere Pro. 1 July 2007 Bruce Bullis CS3 (8.0) release. 4 April 2006 Bruce Bullis Updated to reference new development system requirements and Xcode-specific issues. Some editing. 1 December 2005 Bruce Bullis Updated for 7.0. Added SmartFX documentation. Noted current suite version numbers throughout. Numerous editorial changes. Documented many new AEGP suite functions. 4 April 2004 Bruce Bullis Updated for 6.5. Expanded and corrected all documentation. Added documentation of all new AEGP functions. 20 July 2003 Bruce Bullis Major overhauls for After Effects 6.0. Added documentation for all new (and some old) suites, and many supporting details for effects. 4 March 2002 Bruce Bullis Updated Mac OS X details, expanded AEIO and AEGP documentation. 1 December 2001 Bruce Bullis 5.5 release. Added information on new outflags, PiPL changes, and additions and changes to the AEGP API. Numerous clarifications and edits. 2 February 2001 Bruce Bullis 5.0 release. Entire document edited and reformatted. Sections on 16 bit-per-channel color and parameter supervision, as well as the entire AEGP chapter, have all substantially expanded. 9 September 1999 Bruce Bullis Revised for 4.1; added General plug-ins and AEGP information. Added information on new selectors, resize handle. 1 January 1999 Bruce Bullis Version 4.0 SDK Release 1 - Added information on new global flags, custom data types, utilization of PICA suites, CustomUI messaging and parameter supervision, new callbacks. many editorial changes. 1 May 1998 Bruce Bullis Version 3.1 SDK Release 6 - Editorial changes only 17 April 1997 Brian Andrews Version 3.1 SDK Release 3 – First public release (really a pre-release) of the SDK for Windows development. 13 Nov. 1996 Brian Andrews Version 3.1 SDK Release 2 – Minor updates. 21 June 1996 Brian Andrews Version 3.1 – Final 3.x release. 5 March 1996 Brian Andrews Version 3.0 – Preliminary release for the After Effects developer kitchen. Continued on next page 3 After Effects SDK Guide, Release 18.2.0 Table 1 – continued from previous page Revision Date Documentor Notes August 1994 Dave Herbstman Dan Wilk Version 2.0.1 – Added support for PowerPC. January 1994 Dan Wilk Version 2.0 – Updates. January 1993 Russell Belfer Version 1.0 – Initial SDK release. 4 Chapter 2. Version History CHAPTER 3 Introduction Welcome to the Adobe® After Effects® Software Development Kit! This is a living document and is constantly being updated and edited. The latest public version of the SDK is available at: https://www.adobe.io/after-effects/ While we’ve tried to organize this document in a logical order and provide plenty of cross references, your specific needs may vary.