Software Development Kit Adobe After Effects 6.0 Software Development Kit. Copyright © 1992–2003 Adobe Systems Incorporated. All rights reserved. The information in this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. The software described in this document is furnished under license and may only be used or copied in accordance with the terms of such license. Adobe, Adobe After Effects, Adobe Premiere, Adobe Photoshop, Adobe Illustrator, Adobe Type Manager, ATM and PostScript are trademarks of Adobe Systems Incorporated that may be registered in certain jurisdictions. Macintosh and Apple are registered trademarks, and Mac OS are trademarks of Apple Computer, Inc. Microsoft, Excel, and Windows are registered trademarks of Microsoft Corporation. All other products or name brands are trademarks of their respective holders. The material in this document is supplied by the Adobe Digital Video API Engineering team. Version History January 1993 Russell Belfer Version 1.0 – Initial SDK release. January 1994 Dan Wilk Version 2.0 – Updates. August 1994 Dave Herbstman Version 2.0.1 – Added support for PowerPC. Dan Wilk 5 March 1996 Brian Andrews Version 3.0 – Preliminary release for the After Effects developer kitchen. 21 June 1996 Brian Andrews Version 3.1 – Final 3.x release. 13 Nov. 1996 Brian Andrews Version 3.1 SDK Release 2 – Minor updates. 17 April 1997 Brian Andrews Version 3.1 SDK Release 3 – First public release (really a pre-release) of the SDK for Windows development. 1 May 1998 Bruce Bullis Version 3.1 SDK Release 6 - Editorial changes only 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. 9 September 1999 Bruce Bullis Revised for 4.1; added General plug-ins and AEGP information. Added information on new selectors, resize handle. Adobe After Effects SDK 2 Version History 2 February 2001 Bruce Bullis Initial 5.0 release. Entire document edited and reformatted. Sections on 16bit-per-channel color and parameter supervision, as well as the entire AEGP chapter, have all substantially expanded. 1 December 2001 Bruce Bullis Initial 5.5 release. Added information on new outflags, PiPL changes, and additions and changes to the AEGP API. Numerous clarifications and edits. 4 March 2002 Bruce Bullis Updated MacOS X details, expanded AEIO and AEGP documentation. 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. About this document This document covers the design and theory behind the APIs, and serves as a companion to the sample projects, which exercise the APIs. Organization The Introduction explains what plug-ins are, and how After Effects communicates with them. It describes attributes common to all effect plug- ins; where they’re located, how they’re invoked, and the commands they receive. Parameters are thoroughly discussed in chapter 2. Chapter 3 dives into the details of modifying pixels. The structures passed to (and from) effects are detailed here, as well as the many provided callback functions. Chapter4 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 Chapter 5. Adobe After Effects SDK 3 Chapter 6 provides an overview of the After Effects General Plug-in (AEGP) API. Provided callback functions, intercepting After Effects’ internal messages, obtaining the current contents of the composition and handling menu commands are all covered at length. Artisans, specialized plug-in renderer AEGPs, are covered in chapter 7. Chapter 8 documents AEIOs, specialized AEGPs which handle file input and output. Chapter 9 contains concluding remarks. 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. Coding Conventions Because we use the public APIs for our own plug-ins, our coding guidelines are apparent throughout the SDK. Here’s a description of some of the neo- post-Hungarian notation we use. Of course, you’re welcome to code however you like. If you feel strongly that we should change our internal coding standards, please send your requests to the comp.sys.programmer.better.things.to.do.with.your.time, and we’ll carefully consider them before not making any changes. 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 Adobe After Effects SDK 4 Type Suffix Example 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 param 0 extra_flags0 Adobe After Effects SDK 5 About this document . 3 Organization . 3 Documentation Conventions . 4 Coding Conventions . 4 Chapter 1: Introduction ............................................20 Why develop After Effects plug-ins? . 20 Developers matter! . 20 SDK Audience . 21 What’s in the SDK? . 21 Where’d the HTML go? . 21 Sample projects . 22 Table 1: Sample Project Descriptions . 22 What’s new in 6.0? . 24 The new cruelty . 24 Dynamic streams . 24 Rendering and render queue management . 25 Palette controls . 25 What was new in 5.x? . 25 16-bit-per-channel color . 25 Improved messaging . 25 Access to camera and light data . 25 AEGPs . 25 Artisans . 26 Keyframers . 26 AEIO . 26 Should I update my plug-ins for 6.0? . 26 What about third-party plug-in hosts? . 26 What plug-ins are... 27 ...according to the OS . 27 ...according to After Effects . 27 User System Requirements . 27 Adobe After Effects SDK 6 PiPLs . 27 Multiple PiPLs are possible... 28 Using DevStudio-generated resources too . 28 Super Secret PiPL bit . 29 Why do I need to know all this? . 29 API Specification Version . 29 Entry Point . 29 Where plug-ins are . 30 Windows . 30 MacOS . 31 Where plug-ins appear within After Effects . 31 Localization . 31 C++ . 32 What plug-ins do . 32 Debugging plug-ins . 32 Slick Trick . 34 How After Effects communicates with plug-ins . 35 Many commands, one entry point . 35 Table 2: Plug-in entry point . 35 Command Selectors . 36 Table 3: Command Selectors . 36 Who am I? Where am I? What day is this? . 41 Calling sequence . 42 PF_InData . 42 Table 4: PF_InData Structure . 43 Using the provided information . 46 extent_hint usage . 46 Now with 20% more pixels! . 47 PF_OutData . 47 Table 5: PF_OutData . 47 PF_OutFlags . 48 Table 6: PF_OutFlags . 49 Adobe After Effects SDK 7 A note about PF_OutFlag_PIX_INDEPENDENT . 52 PF_Outflags2 . 53 Table 7: PF_OutFlags2 . 53 Parameters . ..