Plug In Resource Guide
Plug-in%20Resource%20Guide
Plug-in%20Resource%20Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 85
| Download | |
| Open PDF In Browser | View PDF |
Title Page
AdobeGraphics and Publishing
Cross-Application Plug-in
Development Resource Guide
Version 1.6 Release 1
July 1999
Adobe Graphic Application Products
Cross-Application Plug-in Development Resource Guide
Copyright © 1991–1999 Adobe Systems Incorporated. All rights reserved.
Portions Copyright © 1990–1991 Thomas Knoll.
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 PhotoDeluxe, Adobe Premiere, Adobe
Photoshop, Adobe Illustrator, Adobe PageMaker, 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 is a trademark of Apple Computer, Inc. Microsoft,
Windows and Windows95 are registered trademarks of Microsoft
Corporation. All other products or name brands are trademarks of their
respective holders.
Some of the material for this document was derived from earlier works by
Thomas Knoll, Mark Hamburg and Zalman Stern. Additional contributions
came from David Corboy, Kevin Johnston, Sean Parent and Seetha
Narayanan. Information regarding specific SDKs, APIs, and product interfaces
has been provided by Matt Foster, George Ishii, Brian Andrews, Paul Norton,
and Paul Ferguson. This document was then compiled and edited by Andrew
Coven.
Version History
Date
Author
Status
February 1996
Andrew Coven
First release
March 1996
Brian Andrews,
Andrew Coven
Version 1.1. Update for Adobe After Effects 3.
November 1996
Andrew Coven
Version 1.2. Update for Adobe Photoshop 4.0.
January 1997
Brian Andrews,
Andrew Coven
Version 1.3. Update for Adobe After Effects Windows 3.
April 1997
Brian Andrews,
Andrew Coven
Version 1.4. Update for PhotoDeluxe. Release 1 of
1.4 for Adobe PhotoDeluxe and Adobe After
Effects Windows and GAP CD Volume 3.
May 1999
Thoms Ruark
Version 1.5. Update for Photoshop 5.5. New file
format flag and ProgressText
June 1999
Bruce Bullis
Version 1.6. Update for After Effects PiPL
Table of Contents
Table of Contents
Title Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Version History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Table of Contents . . . . . . . . . . . . . . . . . . . . . . . . 3
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
How to use this guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Under construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
About this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2. Getting Started . . . . . . . . . . . . . . . . . . . . . . . . 7
Plug–in modules and plug–in hosts . . . . . . . . . . . . . . . . . . . . . . 7
Cross-development paradigm . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Version releases and compatibility issues . . . . . . . . . . . . . . . . . 7
Cross-application plug-in development strategies . . . . . . . . . . 8
3. Adobe After Effects . . . . . . . . . . . . . . . . . . . . . 10
Adobe After Effects and Adobe Photoshop . . . . . . . . . . . . . . . . . . . . 11
4. Adobe After Effects PiPLs . . . . . . . . . . . . . . . . 12
Property structures and property lists . . . . . . . . . . . . . . . . . . . . 12
Creating PiPL resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Loading PiPL resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Plug–in property lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Plug–in properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Adobe After Effects properties in the Mac OS and Windows . 13
Adobe After Effects Basic data types. . . . . . . . . . . . . . . . . . . . . 14
General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Code descriptor properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Filter–specific properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
FilterCaseInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
ANIM-specific properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
'aFLT' property and ANIM_FilterInfo . . . . . . . . . . . . . . . . . . . . . 21
'aPAR' property and ANIM_ParamAtom . . . . . . . . . . . . . . . . . . 22
Effect–specific properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
PF_OutFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Format–specific properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Input/output-specific properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
AEImageFormatExtensionInfo . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Adobe After Effects PiPL syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5. Adobe Illustrator . . . . . . . . . . . . . . . . . . . . . . . 38
Adobe Illustrator and Adobe Photoshop . . . . . . . . . . . . . . . . . . . . . . 39
6. Adobe Illustrator PiPLs . . . . . . . . . . . . . . . . . . 40
Cross-Application Plug-in Development Resource Guide
3
Table of Contents
The Plug-in Propery List Resource . . . . . . . . . . . . . . . . . . . . . . . 40
Adobe Illustrator properties in the Mac OS and Windows . . . 41
Adobe Illustrator basic data types . . . . . . . . . . . . . . . . . . . . . . . 41
General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Code Descriptor Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Import and Export Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Importing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Exporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Dynamically Declared Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Adobe Illustrator SDK information and samples . . . . . . . . . . . . . . . . 47
Working with PiPLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Sample PiPLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
7. Adobe PageMaker . . . . . . . . . . . . . . . . . . . . . . 48
Adobe PageMaker and Adobe Photoshop . . . . . . . . . . . . . . . . . . . . . 49
8. Adobe PhotoDeluxe . . . . . . . . . . . . . . . . . . . . 51
Adobe PhotoDeluxe and Adobe Photoshop . . . . . . . . . . . . . . . . . . . . 52
Adobe PhotoDeluxe PiPL Properties . . . . . . . . . . . . . . . . . . . . . . . . . . 53
9. Adobe Photoshop . . . . . . . . . . . . . . . . . . . . . . 54
Host emulators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
10. Adobe Photoshop PiMIs . . . . . . . . . . . . . . . . 55
11. Adobe Photoshop PiPLs . . . . . . . . . . . . . . . . 57
Property structures and property lists . . . . . . . . . . . . . . . . . . . . 57
Creating PiPL resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Loading PiPL resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Plug–in property lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Plug–in properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
EnableInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Code descriptor properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Color Picker–specific properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Export–specific properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Filter–specific properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
FilterCaseInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Format–specific properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Scripting–specific properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Adobe Photoshop PiPL Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
12. Adobe Premiere . . . . . . . . . . . . . . . . . . . . . . . 78
Adobe Premiere and Adobe Photoshop . . . . . . . . . . . . . . . . . . . . . . . 79
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Cross-Application Plug-in Development Resource Guide
4
1
1. Introduction
Welcome to the Adobe Graphics Applications Plug-in Development Resource
Guide!
This document is a guide to developing plug–in modules that operate in
multiple applications. This includes Adobe After Effects, Adobe Illustrator,
Adobe PageMaker, Adobe PhotoDeluxe, Adobe Photoshop, Adobe Premiere,
and any other Adobe or third-party software that uses similar API structures.
Audience
This guide is for C programmers who have written plug–ins for Adobe After
Effects, Illustrator, PageMaker, Premiere, and Photoshop on Macintosh and
Windows systems and wish to expand those plug-ins to operate in other
applications besides their initial target application. This is called crossapplication plug-in development. An example would be to expand a Photoshop
Filter plug-in to operate in Illustrator, and PageMaker.
This guide assumes you are proficient in the C programming language and
have worked in any or all of these development environments: Apple MPW;
Metrowerks CodeWarrior Mac; Microsoft Visual C++; Windows NT; Windows
95.
You should have a working knowledge of the different Adobe products, and
understand how plug–in modules work from a user’s viewpoint. This guide
assumes you understand terminology such as paths, layers and masks. For more
information, consult the appropriate user’s guide for your target products.
This guide does not contain information on creating plug-in modules for a
specific application. Consult the individual software development kits for stepby-step instructions and example code.
How to use this guide
This documentation is made to provide specific information on
implementation and structuring issues for each major Adobe graphics
application.
The best way to use this guide is to turn to the chapter containing specific
information on the application that you wish to modify your plug–in to
operate with.
If you writing plug–ins is new for you, we recommend you begin with the
software development kit for the initial target application you wish to
program your plug-in for, such as the Adobe Photoshop SDK.
Once you are familiar with plug-in terminology and the examples, consult
this guide for different techniques when making your plug-in crossapplication compatible.
!
Under construction
This is the first release of this guide, and it is a work in progress.
More detailed information about each product will be added as this
document matures. Please report any errors or omissions to the
Adobe Developers Association.
Cross-Application Plug-in Development Resource Guide
5
1. Introduction
GAP SDK tech notes mailing list
The Adobe Developers Association maintains a page on Adobe’s world-wideweb site, http://www.adobe.com, which includes the latest SDK public
releases and technical notes. You can also have the technical notes e-mailed
to you directly by joining the Graphics Application Products SDK tech notes
mailing list. The GAP SDK Tech Notes e-mail list is for Adobe After Effects,
Adobe Illustrator, Adobe PageMaker, Adobe Photoshop and Adobe
Premiere. Send an e-mail to
gap-dse@adobe.com
with the subject:
SUBSCRIBE GAP–SDK–TECH–NOTES
and these fields in your message body:
1.
Your full name
2.
Business name
3.
Address
4.
City
5.
State
6.
Country
7.
Country code or Zip
8.
Area code and phone number (business is fine)
9.
ADA member number. “ N/A” if not a member; “ Info” if want info.
10.
Any other e-mail addresses you want CC:’ed.
About this guide
This programmer’s guide is designed for readability on screen as well as in
printed form. The page dimensions were chosen with this in mind. The
Frutiger and Minion font families are used throughout the manual.
To print this manual from within Adobe Acrobat Reader, select the “Shrink
to Fit” option in the Print dialog.
Cross-Application Plug-in Development Resource Guide
6
2
2. Getting Started
This chapter describes what plug–in modules are and provides information
common to all plug–in modules. It introduces development strategies for
creating plug-ins that are compatible with multiple applications.
Plug–in modules and plug–in hosts
Plug–in modules are software programs developed by Adobe Systems and
third–party vendors with Adobe Systems to extend an application. Plug–in
modules can be added or updated independently by end users to customize
Photoshop to their particular needs.
This guide also frequently refers to plug–in hosts. A plug–in host is responsible
for loading plug–in modules into memory and calling them. The purpose of
this guide is to assist in creating plug-in modules that operate under a
variety of plug-in hosts.
These Adobe applications function as plug-in hosts: Adobe After Effects,
Adobe Premiere, Adobe Illustrator, Adobe PageMaker, Adobe PhotoDeluxe,
and Adobe Photoshop. All these applications support their own forms and
types of plug-ins, which are detailed in their individual SDKs.
Most of these applications support some, but not all, Photoshop plug–in
modules. Many applications from third–party developers support the use of
Photoshop plug–in modules, as well.
Most plug–in hosts are application programs, but this not a requirement. A
plug–in host may itself be a plug–in module. A good example of this is the
“Photoshop Adapter” which allows Adobe Illustrator 6.0 to host Photoshop
Format and Filter modules.
This guide is not designed for developers interested in creating plug–in
hosts; the emphasis and goal for this guide is presenting information
pertinent to creating plug–in modules.
Each plug-in host’s version will be listed when that particular application is
discussed.
Cross-development paradigm
Many developers have created plug-ins in their target application and want
to expand their plug-in’s functionality to other applications. If you are going
to take the time to make your plug-in compatible with one application, why
not make it compatible with all of Adobe’s graphic application products?
Adobe strongly encourages you to take the time to view all the details of
this document, not just one section regarding one application.
An additional investment of 10-20% of your development time can result in
a plug-in that operates in not just one application, but six (not counting
third-party host applications.) We believe this is a lucritive return on your
R&D investment.
Version releases and compatibility issues
Designing your plug-in for multiple applications also makes it necessary to
take into account different compatibility issues. Different hosts emulate
Cross-Application Plug-in Development Resource Guide
7
2. Getting Started
other hosts at different version levels. For instance, Adobe Premiere
emulates Adobe Photoshop filter plug-ins as Photoshop version 2.5, while
Adobe Illustrator emulates Adobe Photoshop filter plug-ins as Photoshop
version 3.0.4.
Backward-compatibility means designing your plug-in to be accessible (and
not just report an error message and quit) in earlier versions of applications.
Table lists the current versions of each piece of software and what version
we recommend you target for backward-compatibility programming.
Table 2-1: Version releases and compatibility chart
Application
Mac OS
version
Mac OS
release
Windows
version
Windows
release
Backward
Mac, Win
Adobe After Effects
3.1
2/1/96
3.1
4/1/97
3.0, 3.1
Adobe Illustrator
6.0
2/6/96
6.0
3/1/97
5.5, 4.1
Adobe PageMaker
6.0
6/1/95
6.0
8/1/95
5.0, 5.0
Adobe PhotoDeluxe
1.0
1/1/96
None
N/A
3.0, N/A
Adobe Photoshop
4.0
11/18/96
4.0
11/18/96
2.5, 2.5
Adobe Premiere
4.2
8/1/95
4.0
5/1/95
4.0, 4.0
Forward-compatibility can be realized by programming your plug-ins with
strict adherence to host signatures and suite version numbers. While it does
require more programming when suites are not available, by religiously
checking for host signatures and suite version numbers you can do a number
of things by simply adding to your plug-in programming, as opposed to rewriting for every new version of a host that is released. Programming for
backward- and forward-compatibility allows you to:
1.
Take advantage of application-specific features
2.
Program for backward- and forward- compatibility
3.
Optimize for and use new suites as they become available.
Cross-application plug-in development strategies
We recommend you follow this process for your cross-application plug-in
development:
1.
Assess and determine the problem your plug-in will solve.
2.
Acquire the primary SDK for your base development.
3.
Examine the examples and read the primary SDK.
4.
Determine your development strategy for your base application.
5.
Read the information in this guide with the needs of your plug-in in
mind.
6.
Reassess your development strategy for your base application.
7.
Determine any host-requirements for the other target applications.
8.
Program and create your plug-in.
9.
Test under your base application.
10.
Program and optimize based on testing results.
11.
Test under the other target applications.
Cross-Application Plug-in Development Resource Guide
8
2. Getting Started
12.
Modify and optimize based on those results.
13.
Implement whatever beta-testing program you have.
14.
Reassess and modify as needed.
15.
Package and release your product.
Cross-Application Plug-in Development Resource Guide
9
3
3. Adobe After Effects
This chapter describes properties and useful resources of Adobe After Effects
for creating plug-ins that work under multiple applications.
Table 3-1: Adobe After Effects version and signature information
Description
Value
Mac OS version
3.1
Mac OS release date
2/1/96
Windows version
3.1
Windows release date
4/1/97
Backward-compatibility targets Mac, Win
3.0, 3.1
Signature
'FXTC'
Cross-Application Plug-in Development Resource Guide
10
3. Adobe After Effects
Adobe After Effects and Adobe Photoshop
Table 3-2: Adobe After Effects emulating Adobe Photoshop host
Description
Value
Signature
'8BIM'
Host version support
3.0, 3.0
Required adaptor
N/A
Resource
'PiPL'
Supported module types
Filter, Format, Parser
Plug-in folder default
Adobe After Effects/Plug-ins/standard/
Photoshop Filters
Plug-in aliases
Automatically resolved by After Effects.
Plug-in load order
Loads references, but not code until execution
request. On the Mac, press control-clear to clear out
the plug-in code cache, forcing the code to be
reloaded.
How to access the different plug-ins while using Adobe After Effects:
Filter modules
Effects» (sub-menu)
“PS
plugInName”=Normal filter
“PS +
plugInName”=Filter with 'ANIM' resource
Format modules
File»Import»“Footage”»“File type:”
Parser modules
Load at startup.
Host version support
Adobe After Effects emulates the Photoshop 3.0 Plug-in API. All of the 3.0
API calls and functions are implemented, except:
1.
Any callbacks related to Acquire or Export modules.
2.
Any 3.0.4 callback services or suites.
!
Note: Because hosts like Adobe After Effects implement a version of
the Photoshop plug-in API that is earlier then the current version, it
is very important you check for validity and existence of suite
versions and their callbacks before you use them.
Creating dynamic resources
After Effects allows Photoshop plug-ins to be controlled over time. This is
achieved through the addition of a simple resource called an 'ANIM'. ANIM
properties are detailed in the next chapter.
Cross-Application Plug-in Development Resource Guide
11
4
4. Adobe After Effects PiPLs
A Plug–In Property List, called a 'PiPL' (pronounced “pipple”) is a flexible,
extensible data structure for representing a plug–in module’s metadata.
PiPLs contain all the information Adobe After Effects needs to identify and
load plug–in modules, as well as flags and other static properties that
control the operation of each plug–in. Your plug–in module should contain
one or more 'PiPL' structures.
Property structures and property lists
Plug–in property structures (or properties) are the basic units of information
stored in a property list. Properties are variable length data structures, which
are uniquely identified by a vendor code, property key, and ID number.
The valid properties and formal grammar are documented later in this
chapter.
Creating PiPL resources
Under the Mac OS, PiPLs are stored as Macintosh resources. Under Windows,
PiPLs are stored as Windows resources.
On the Macintosh, you can create and edit PiPL resources with a text editor
and the Rez compiler, or you can use a graphical resource editor like
Resorcerer. ResEdit cannot edit PiPL resources. If you are unfamiliar with the
format of Rez source code, refer to the appropriate Apple documentation.
Loading PiPL resources
When Photoshop launches, it scans all plug–in files for 'PiPL' resources.
Historically, each type of plug–in had its own file type.
File types are only a matter of convention for 'PiPL' based plug–in modules.
All known plug-in file types are searched for 'PiPL' resources and for those
that are found, the information contained therein is used to determine the
type of plug–in, code location, etc.
Plug–in property lists
The plug–in property list structure has a version number and a count
followed by one or more property structures.
typedef struct PIPropertyList
{
int32
version;
int32
count;
PIProperty
properties[1];
} PIPropertyList;
Table 4-1: PIPropertyList structure
Type
Field
Description
int32
version
Current version is 0.
int32
count
Number of properties in the 'PiPL'. 0=no properties.
PIProperty
properties
A variable length array of property data structures.
Cross-Application Plug-in Development Resource Guide
12
4. Adobe After Effects PiPLs
Plug–in properties
Each property has a vendor code, a key, an ID, and a length field.
typedef struct PIProperty
{
OSType
vendorID;
OSType
propertyKey;
int32
propertyID;
int32
propertyLength;
char
propertyData[1];
/* Implicitly aligned to multiple of 4 bytes. */
} PIProperty;
Table 4-2: PIProperty structure
Type
Field
Description
OSType
vendorID
The vendor defining this property type. This allows other
vendors to define their own properties in a way that does
not conflict with either Adobe or other vendors. It is recommended that a registered application creator code be used
for the vendorID to ensure uniqueness. After Effects creator
code is 'FXTC' but all After Effects plug-ins use Adobe Photoshop’s vendorID '8BIM'.
OSType
propertyKey
Property type, detailed in table 4-4.
int32
propertyID
=0. Used to store more than one property of a given type.
Reserved for future use.
int32
propertyLength
Length of propertyData. Does not include any padding
bytes to achieve four byte alignment. May be zero.
variable
propertyData
Variable length field containing contents of this property.
Any values may be contained.
Adobe After Effects properties in the Mac OS and Windows
Specific properties can be extended in an upwardly compatible fashion by
adding extra data at their end. The length field will allow an application to
determine how much data is present, so optional properties can be omitted
without concern. This is different from a fixed length structure where
omitted fields must be given a default value.
It is intended for PiPLs to collect all plug-in metadata in a single place. this
is useful for cross-platform development, since Windows lacks a resource
management mechanism.
The 'PiPL' format is fairly portable in that everything is four byte aligned.
All OSType and int32 fields are represented in native byte order for a given
platform so bytes of informationally identical PiPLs will differ between bigendian machines that run the Mac OS, and little-endian machines running
Windows. The bytes of the PiPL section of a Windows binary resource are
identical, but reversed, to the same resource in the Mac OS. This should not
be of too much concern. As long as you use the pre-defined plug-in data
types (table 4-3), they will be interpreted and stored correctly.
!
Note: An undefined OSType will not be converted automatically. It is
normally interpreted as a long and you must supply the chars in
reverse order for Windows implementation.
The After Effects API byte order is always big-endian.
Cross-Application Plug-in Development Resource Guide
13
4. Adobe After Effects PiPLs
Adobe After Effects Basic data types
The following types are used to define properties:
Table 4-3: Adobe After Effects Basic data types
Name
Description
int16, int32
16 and 32 bit integers. Stored in native byte order.
long
Same as int32.
short
Same as int16.
OSType
Same as int32. Typically denotes Mac OS 4 character filetypes like
'PiPL'.
PString
Pascal style string where byte 1=length and content bytes follow.
CString
C style string where the content bytes are terminated by NULL.
Structures
Represented as would be in memory on the target platform. Native padding and alignment constraints are observed.
Arrays
Represented as a contiguous set of entries in the 'PiPL' with native padding and alignment constraints observed.
ANIM_Float64
Double. 8-byte IEEE 7 5 4.
Cross-Application Plug-in Development Resource Guide
14
4. Adobe After Effects PiPLs
General properties
These properties are common to all types of plug–in modules. The names of
the properties (such as “PIKindProperty”) are the same as the #define
names for the corresponding property keys.
Table 4-4: Adobe After Effects general property keys
Type
Name
Key
Description
OStype
PIKindProperty
0x6b696e64L
('kind')
Type or kind of plug-in.
'eFST'=Adobe After Effects Accelerator
'eFKT'=Adobe After Effects Effect
'FXIF'=Adobe After Effects I/O Format
'ARPI'=Adobe Illustrator
'8BXM'=Adobe Photoshop Accelerator
'8BAM'=Adobe Photoshop Acquire
'8BEM'=Adobe Photoshop Export
'8BFM'=Adobe Photoshop Filter
'8BIF'=Adobe Photoshop Format
'8BYM'=Adobe Photoshop Parser
PString
PINameProperty
0x6e616d65L
('name')
Plug-in menu name for module in
PICategoryProperty sub-menu.
PString
PICategoryProperty
0x63617467L
('catg')
In the Effects menu, what sub–menu
to list this plug–in.
int32
PIVersionProperty
0x76657273L
('vers')
Major and minor version number indicating which revision of the plug–in
interface this plug–in was written for.
The major version number indicates
incompatible changes while the minor
version number indicates incremental
enhancements. The major version number is encoded in the most significant 16
bits of the 32 bit version number, the
minor version number is encoded in the
least significant 16 bits.
There are separate version numbers for
each kind of plug–in. The current version for a given kind of plug–in is
defined by a preprocessor macro in the
header file defining the interface for
that plug–in type.
int16
PIPriorityProperty
0x70727479L
('prty')
Plug-in load order. Also used to control
the order in which items with the same
name show up in menus.
Lower numbers (including negative
ones) load first. If NULL, the default is
zero.
FlagSet
PIImageModesProperty
0x6d6f6465L
('mode')
Which image modes the plug–in supports. Adobe Photoshop, has 11 modes:
bitmap, grayscale, indexed, RGB,
CMYK, HSL, HSB, multi–channel, duotone, Lab, gray 16, and RGB 48.
This property determines whether your
plug–in will be active (black) or inactive
(gray) in Photoshop’s menus based on
the current document’s image mode.
OSType
PIRequiredHostProperty
0x686f7374L
('host')
Cross-Application Plug-in Development Resource Guide
Creator code of required host, such as
'8BIM' for Adobe Photoshop.
15
4. Adobe After Effects PiPLs
Code descriptor properties
Code descriptors tell Adobe After Effects the type and location of a plug–in’s
code. More than one code descriptor may be included to build a “fat” plug–
in which will run on different types of machines. After Effects will select the
best performing option. After Effects makes sure that the callback structure
is filled in with appropriate functions for the type of code that is loaded. So
for PowerPC code, native function pointers will be provided and routine
descriptor operations are not required either in calling the plug–in or for the
plug–in to invoke callback functions.
Table 4-5: Adobe After Effects code descriptor properties
Type
Name
Key
PI68kCodeDesc
Code68k
0x6d36386bL ('m68k')
This descriptor indicates a 68K code resource. The type for this property is:
typedef struct PI68KCodeDesc
{
OSType resourceType;
int16 resourceID;
} PI68KCodeDesc;
Any resource type may be used, but types of PIKindProperty from table 4-4 are strongly
recommended.
PI68kCodeDesc
Code68kFPU
0x36386670L ('68fp')
This descriptor is just like a PI68KCodeDesc except it will only be used on Macintosh
machines that are equipped with FPU hardware. This allows vendors to easily ship plug–
ins that take advantage of FPU hardware but still run on non–FPU Macs.
PICFMCodeDesc
CodePowerPC
0x70777063L ('pwpc')
This descriptor indicates a PowerPC code fragment in the data fork of the plug-in file. The
type for this property is as follows:
typedef struct PICFMCodeDesc
{
long fContainerOffset;
long fContainerLength;
char fEntryName[1];
} PICFMCodeDesc;
Described in table 4-6.
PIWin32X86CodeDesc
CodeWin32X86
0x77783836L ('wx86')
This code descriptor is used for 32 bit Windows DLLs, and contains the DLL’s entrypoint
name.
typedef struct PIWin32X86CodeDesc
{
char
fEntryName[1];
} PIWin32X86CodeDesc;
The NULL-terminated string may need to be padded with additional NULLs to satisfy the
4–byte alignment requirement.
Cross-Application Plug-in Development Resource Guide
16
4. Adobe After Effects PiPLs
Table 4-6: PICFMCodeDesc structure
Type
Field
Description
long
fContainerOffset
Data fork offset to the code fragment start. This
allows more than one plug-in code fragment per file.
long
fContainerLength
Length of the code fragment. If the fragment extends
to the end of the file or is the only fragment, the container length may be 0.
Pstring
fEntryName
Pascal string used to lookup the address of the function to call within the fragment. In order for the Code
Fragment Manager to find an entrypoint by name,
that name must be an exported symbol of the code
fragment. If NULL, the default entrypoint will be used.
fEntryName allows a single code fragment to contain
more than one plug-in.
Cross-Application Plug-in Development Resource Guide
17
4. Adobe After Effects PiPLs
Filter–specific properties
These properties are applicable to Filter plug–in modules.
Table 4-7: Adobe After Effects filter-specific properties
Length
Name
Key
7 * 4-bytes
PIFilterCaseInfoProperty
0x66696369L ('fici')
This key is for support for dynamically composited layers of image data.
A layer consists of color and transparency information for each pixel it contains. Previous
versions did not have a transparency component. Completely transparent pixels have an
undefined color. Filters will likely affect transparency data as well as color data. This is
especially true for filters which produce spatial distortions.
The filter case info property allows flexibility in how transparency data is presented to filters. It controls the filtering process and presentation of data to the plug–in. This property provides information about what image data cases the plug–in supports. The current
filtering situation is then compared to the supported cases and the best fitting case is
choosen. The image data is then presented in that case. If none of the supported cases
are usable, the filter will be disabled.
The case properties are an array of seven four byte entries, detailed in table 4-9.
Table 4-8: Filter cases
#define name
Description
1=filterCaseFlatImageNoSelection
This is a background layer or a flat image.
There is no transparency data or selection.
2=filterCaseFlatImageWithSelection
No transparency data, but a selection may be
present. The selection will be presented as
mask data.
3=filterCaseFloatingSelection
Image data with an accompanying mask.
4=filterCaseEditableTransparencyNoSelection
Layer with transparency editing enabled and
no selection.
5=filterCaseEditableTransparencyWithSelection
Layer with transparency editing enabled and a
selection.
6=filterCaseProtectedTransparencyNoSelection
Layer with transparency editing disabled and
no selection.
7=filterCaseProtectedTransparencyWithSelection
Layer with transparency editing disabled and a
selection.
Cross-Application Plug-in Development Resource Guide
18
4. Adobe After Effects PiPLs
FilterCaseInfo
Each of the 7 elements of the array contains a 4–byte FilterCaseInfo:
typedef struct FilterCaseInfo
{
char inputHandling;
char outputHandling;
char flags1;
char flags2;
} FilterCaseInfo;
inputHandling & outputHandling
The inputHandling and outputHandling fields specify the pre–processing and
post–processing actions on the image data respectively.
Table 4-9: FilterCaseInfo handling modes
Handling mode
Description
0=inCantFilter = outCantFilter
indicates that this case is not supported by the
plug–in filter
1=inStraightData = outStraightData
indicates that the plug–in filter does not expect the
plug–in host to do anything to the image data.
The next three modes are matting cases, which are useful when performing distortions and blurs.
You can matte the data, process it, and then dematte to remove the added color.
For these cases, the matting is defined as follows:
mattedValue = ((unmattedValue * transparency) + 128) / 255 +
((matConstant * (255 - transparency)) + 128) / 255
Dematting is defined as follows:
unmattedValue = ((mattedValue - matConstant) ./ transparency) + matConstant
with the ./ operator defined as an 8 bit fixed–point divide and the result value=0...255.
2=inBlackMat = outBlackMat
For input, matte the image data with black=0 values
based on the transparency.
For output, dematte the image data using black
(=0) values.
3=inGrayMat = outGrayMat
Matte the image data with gray (=128) values based
on the transparency on input. Dematte the image
data using gray values on output.
4=inWhiteMat = outWhiteMat
Matte the image data with white (=255) values
based on the transparency on input. Dematte the
image data using white values on output.
Input-only related modes
5=inDefringe
Defringe transparent areas filling with the nearest
defined pixels using taxicab distance. Note that this
only applies to fully transparent pixels.
6=inBlackZap
Set color component of totally transparent pixels to
black.
7=inGrayZap
Set color component of totally transparent pixels to
gray.
8=inWhiteZap
Set color component of totally transparent pixels to
white.
10=inBackgroundZap
Set color component of totally transparent pixels to
the current background color.
Cross-Application Plug-in Development Resource Guide
19
4. Adobe After Effects PiPLs
Table 4-9: FilterCaseInfo handling modes (Continued)
Handling mode
Description
11=inForegroundZap
Set color component of totally transparent pixels to
the current foreground color.
Output-only related modes
9=outFillMask
This mode results in the transparency mask automatically being filled with full opacity in the area
affected by the filter. This is only valid for the editable transparency cases. This option is provided to
make it easy to write a plug–in similar to Photoshop’s Clouds plug–in, which fills an area with a
value.
Table 4-10: FilterCaseInfo flags1 parameters
Field
Values
0=PIFilterDontCopyToDestinationBit
0=copySourceToDestination
1=doNotCopySourceToDestination
Normally source data is copied to the destination before filtering. This degrades performance for filters which write all the output pixels. Setting this bit inhibits copying.
1=PIFilterWorksWithBlankDataBit
0=doesNotWorkWithBlankData
1=worksWithBlankData
Determines whether the filter will work on “blank” areas that are completely transparent.
If not, an error message will be given when the filter is invoked on a blank area. This is
only valid for the editable transparency case because that is the only case where you could
create opacity—in the protected transparency case, you would be left with what you
started with: completely blank data.
2=PIFilterFiltersLayerMaskBit
0=doesNotFilterLayerMasks
1=filtersLayerMasks
In cases where transparency is editable, this flag determines if Layer Masks are filtered.
(See the “Add Layer Mask” item in the Layers palette menu to create a layer mask.) Setting this bit adds the layer mask to the set of target channels if: transparency for the layer
is editable (i.e., this is one of the editable transparency cases), the bit is set, and the layer
mask is specified as being positioned relative to the layer rather than the image in Layer
Mask Options. The distinction based on position is based on the assumption that layer relative masks are distorted with the layer; image relative masks are independent of the
layer.
!
Note: This field is not a FlagSet. The first bit,
PIFilterDontCopyToDestinationBit, is in the least–significant bit
of the flag byte.
flags2
The flags2 field of FilterCaseInfo is reserved, and should be zero.
Cross-Application Plug-in Development Resource Guide
20
4. Adobe After Effects PiPLs
ANIM-specific properties
These properties are applicable to filters that are animatable.
Table 4-11: Adobe After Effects ANIM-specific properties
Length
Name
Key
32 bytes
ANIM_FILT_INFO_PROP
0x61464C54L ('aFLT')
After Effects animatable filter description information. This key is for support for After
Effects animatable filters (ANIMs).
Each filter should have one 'aFLT' and an arbitrary number of 'aPAR' properties. The combination of these two keys allows aware hosts to provide to animate the filter. If the filter
shouldn’t be driven, set ANIM_FF_DONT_DRIVE=TRUE. See table 4-12.
variable
ANIM_PARAM_INFO_PROP
0x61464C54L ('aPAR')
After Effects animatable filter parameter information. This key is for support for After
Effects animatable filters (ANIMs).
Each filter should have one 'aFLT' and an arbitrary number of 'aPAR' properties. The combination of these two keys allows aware hosts to provide to animate the filter.
The total number of 'aPAR' properties is included in the 'aFLT'. An 'aPAR' is distinguished
by its PiPL ID, which progresses from 0 to (number of parameters - 1). The order of
the 'aPAR' properties implicitly reflects the order of the params in the filter’s parameter
block. See table 4-14.
The ANIM_FilterDescription struct defines the After Effects animatable filter
description and parameter information:
typedef struct ANIM_FilterDescription
{
ANIM_FilterInfo
info;
ANIM_ParamAtom
params[1];
} ANIM_FilterDescription, *ANIM_FilterDescriptionPtr,
**ANIM_FilterDescriptionH
'aFLT' property and ANIM_FilterInfo
The 'aFLT' property is described by the ANIM_FilterInfo struct:
typedef struct ANIM_FilterInfo
{
long
spec_version_major;
long
spec_version_minor;
long
filter_params_version;
ANIM_FilterFlags flags;
long
num_params;
char
match_name[32];
long
reserved[4];
} ANIM_FilterInfo;
Table 4-12: ANIM_FilterInfo structure
Type
Field
Description
long
ANIM_MAJOR_VERSION
=1. Major version number.
long
ANIM_MINOR_VERSION
=0. Minor version number.
long
filter_params_version
This version will be stored to disk with the
params. The params will be discarded if it’s different then the ANIM version of the existing filter.
Cross-Application Plug-in Development Resource Guide
21
4. Adobe After Effects PiPLs
Table 4-12: ANIM_FilterInfo structure (Continued)
Type
Field
Description
ANIM_FilterFlags
flags
Filter flags. See table 4-13.
long
num_params
Number of parameters.
char
match_name
Cstring. Host will save this name to disk and
use it to match when loading from disk.
long
reserved[4]
Reserved for future use. Set to zero.
Table 4-13: ANIM_FilterFlags structure
Field
Description
0=ANIM_FF_HAS_RANDOMNESS
Same parameters and source does not produce
exact same results.
1=ANIM_FF_NON_GEOMETRIC
Pixel output depends on input pixel, not interpolation, exterpolation, or formula.
2=ANIM_FF_FG_ANIMATABLE
Host should allow animation of foreground color.
3=ANIM_FF_BG_ANIMATABLE
Host should allow animation of background color.
4=ANIM_FF_PARAMS_IN_GLOBALS
Host should store globals according to filter specs.
5=ANIM_FF_DIALOG_IN_RENDER
Filter inquiries user during filterSelectorStart
or filterSelectorContinue instead of
filterSelectorParameters.
6=ANIM_FF_PARAMS_ARE_MAC_HANDLE
Parameters are stored as Macintosh handle.
7=ANIM_FF_PARAMS_ARE_HANDLE
Parameters are stored as ANSI handle.
8=ANIM_FF_PARAMS_ARE_PTR
Parameters are stored as Pointers.
9=ANIM_FF_DOESNT_NEED_DLOG
Dialog doesn’t init anything; host may fill opaque
data with zeros and non-opaque data with reasonable values.
10=ANIM_FF_DONT_DRIVE_ME
Don’t load plug-in.
11=ANIM_FF_RESERVED0
Reserved.
12=ANIM_FF_RESERVED1
Reserved.
13-31=Reserved
Reserved.
!
Note: This field is not a FlagSet. The first bit,
ANIM_FF_HAS_RANDOMNESS, is in the least–significant bit of the flag
byte.
'aPAR' property and ANIM_ParamAtom
The 'aPAR' property is described by the ANIM_ParamAtom struct:
typedef struct ANIM_ParamAtom
{
char
external_name[32];
long
id;
ANIM_DataType
data_type;
ANIM_UIType
ui_type;
ANIM_Float64
valid_min;
ANIM_Float64
valid_max;
ANIM_Float64
ui_min;
ANIM_Float64
ui_max
ANIM_ParamFlags
flags;
long
byte_size;
long
reserved[4];
Cross-Application Plug-in Development Resource Guide
22
4. Adobe After Effects PiPLs
} ANIM_ParamAtom;
Table 4-14: ANIM_ParamAtom structure
Type
Field
Description
char
external_name
Cstring. Can be localized.
long
id
locally unique ID for paramter. Not the PiPL ID.
0=Reserved; <0=Reserved for host use.
The host uses this field to match parameters
stored to disk with those in the parameter handle. You may add or remove parameters to your
plug-in without changing
filter_params_version.
If you change this value in the future and
ANIM_FF_DONT_NEED_DLOG=FALSE, old data
may be discarded.
ANIM_DataType
data_type
If opaque, ignore below except byte_size. See
table 4-15.
ANIM_UIType
ui_type
User interface type. See table 4-16.
ANIM_Float64
valid_min
ANIM_Float64
valid_max
Used for slider. Set valid_min=valid_max=0 for
full range.
ANIM_Float64
ui_min
ANIM_Float64
ui_max
ANIM_ParamFlags
flags
Parameter flags. See table 4-17.
long
byte_size
Byte size of parameter data.
long
reserved[4]
Reserved for future use. Set to zero.
Used for slider. Set ui_min=ui_max=0 for full
range.
Table 4-15: ANIM_DataType structure
Field
Description
0=ANIM_DT_OPAQUE
Opaque.
1=ANIM_DT_CHAR
Character.
2=ANIM_DT_SHORT
Short integer.
3=ANIM_DT_LONG
Long integer.
4=ANIM_DT_UNSIGNED_CHAR
Unsigned character.
5=ANIM_DT_UNSIGNED_SHORT
Unsigned short integer.
6=ANIM_DT_UNISNGED_LONG
Unsigned long integer.
7=ANIM_DT_FIXED
Fixed 16:16.
8=ANIM_DT_UNSIGNED_FIXED
Fixed unsigned 16:16.
9=ANIM_DT_EXTENDED_96
12 byte value. Not recommended.
10=ANIM_DT_DOUBLE_64
8 byte IEEE 7 5 4.
11=ANIM_DT_FLOAT_32
4 byte IEEE 7 5 4.
Table 4-16: ANIM_UIType structure
Size
Field
Description
0
0=ANIM_UI_NO_UI
Still must have name and data type. If
not opaque, will animate.
sizeof(data_type)
1=ANIM_UI_ANGLE
Angle.
sizeof(data_type)
2=ANIM_UI_SLIDER
Slider.
2*sizeof(data_type)
3=ANIM_UI_POINT
(h,v) Point.
Cross-Application Plug-in Development Resource Guide
23
4. Adobe After Effects PiPLs
Table 4-16: ANIM_UIType structure (Continued)
Size
Field
Description
4*sizeof(data_type)
4=ANIM_UI_RECT
(t,l,b,r) Rectangle.
3*sizeof(data_type)
5=ANIM_UI_COLOR_RGB
RGB Color space.
4*sizeof(data_type)
6=ANIM_UI_COLOR_CMYK
CMYK Color space.
3*sizeof(data_type)
7=ANIM_UI_COLOR_LAB
L*a*b Color space.
Table 4-17: ANIM_ParamFlags structure
Field
Description
0=ANIM_PF_IS_RES_DEPENDENT
Boolean. TRUE=your plug-in can adjust parameters
dynamically as host changes resolution.
1=ANIM_PF_SPACE_IS_RELATIVE
For ANIM_UI_POINT and ANIM_UI_RECT only.
TRUE=Relative mode: 0.0=left or top; 1.0=right or bottom.
FALSE=Absolute mode: Value=pixels.
2=ANIM_PF_RESTRICT_BOUNDS
For ANIM_UI_POINT and ANIM_UI_RECT only.
TRUE=Don’t call filter when point or rect is outside
bounds of source.
FALSE=Call filter with any input point or rect.
!
Note: These fields are not FlagSets. For instance, the first bit of the
ANIM_ParamFlags structure, ANIM_PF_IS_RES_DEPENDENT, is in the
least–significant bit of the flag byte.
Cross-Application Plug-in Development Resource Guide
24
4. Adobe After Effects PiPLs
Effect–specific properties
These properties are applicable to Effect plug–in modules.
Table 4-18: Adobe After Effects effect-specific properties
Type
Name
Key
Description
2 * short
AEPiPLVersion
0x65505652L
('ePVR')
Major and sub-version of Adobe
After Effects PiPL. Must be 2 and
0.
2 * short
PF_PLUG_IN_VERSION
0x65535652L
('eSVR')
Major and sub-version of Effect
specification. Must be 11 and 0.
int32
PF_Vers
0x65564552L
('eVER')
Effect version. See table 4-19.
int32
PF_Outflags
0x65474c4fL
('eGLO')
Global flags for effect output.
See table 4-20.
Cstring
AEEffectMatchName
0x654d4e41L
('eMNA')
String with effect name.
Table 4-19: PF_Vers parameters
Field
Description
0...8=PF_Version_BUILD
Build version number.
9...10=PF_Version_STAGE
Stage of build by name.
0=Develop (PF_Stage_DEVELOP)
1=Alpha (PF_Stage_ALPHA)
2=Beta (PF_Stage_BETA)
3=Release (PF_Stage_RELEASE)
11...14=PF_Version_BUGFIX
Version number of bug fix release.
15...18=PF_Version_SUBVERS
Minor/sub-version number.
19...21=PF_Version_VERS
Major version number.
22...31=Reserved
Reserved. Must be zero.
PF_OutFlags
The Effect Global Outflags describe how your effect responds to many of the
PF_Cmd sequence callbacks. Unless otherwise noted, you should set and send
these flags at PF_Cmd_GLOBAL_SETUP.
Table 4-20: PF_Outflags parameters
Field
Description
0=PF_OutFlag_NONE
All flags off.
1=PF_OutFlag_KEEP_RESOURCE_OPEN
Keep plug-in’s resources available during
all commands.
2=PF_OutFlag_WIDE_TIME_INPUT
Effect requests information about a noncurrent time (such as the previous video
frame).
3=PF_OutFlag_NON_PARAM_VARY
Effect output depends on something other
than just the parameter list.
3=PF_OutFlag_RESERVED6
No longer used. Was
PF_OutFlag_SEND_PARAMS_UPDATE.
Cross-Application Plug-in Development Resource Guide
25
4. Adobe After Effects PiPLs
Table 4-20: PF_Outflags parameters (Continued)
Field
Description
5=PF_OutFlag_SEQUENCE_DATA_NEEDS_FLATTENING
Sequence data handle contains other
pointers or handles. For sequence data,
you will be called with
PF_Cmd_SEQUENCE_RESETUP. Store a boolean at a common offset in your unflattened and flattened data indicating
whether it’s flat or not. On
PF_Cmd_SEQUENCE_RESETUP and
flat=TRUE then you should unflatten the
data, free the flattened data handle, and
set sequence_data in PF_OutData.
If you set the data=NULL when you flatten
it, you will not be sent
PF_Cmd_SEQUENCE_RESETUP to unflatten.
Instead, you may get a RENDER call with
data=NULL.
6=PF_OutFlag_I_DO_DIALOG
Effect responds to PF_Cmd_DO_DIALOG.
7=PF_OutFlag_USE_OUTPUT_EXTENT
Effect only process or changes behavior
based on visible-image-area rect; extent
rect change should cause re-render.
8=PF_OutFlag_SEND_DO_DIALOG
Effect requires options dialog box to be
presented at least once. Set during
PF_Cmd_SEQUENCE_SETUP.
PF_Cmd_DO_DIALOG will be sent right
after.
9=PF_OutFlag_DISPLAY_ERROR_MESSAGE
If return_msg in PF_OutData is a string,
the host will display it. TRUE=display string
as error dialog; otherwise display string as
generic dialog.
These fields are new since version 2.0 of Adobe After Effects.
10=PF_OutFlag_I_EXPAND_BUFFER
Set if you expand the effect buffers
beyond the layer dimensions.
11=PF_OutFlag_PIX_INDEPENDENT
Output of a given pixel is not dependent
on the values of surrounding pixels.
12=PF_OutFlag_I_WRITE_INPUT_BUFFER
Effect writes to the input buffer. Use with
discretion: this is useful as a scratch buffer,
but invalidates some host speedups in rendering.
13=PF_OutFlag_I_SHRINK_BUFFER
Your effect can shrink its buffer based on
the extent rect. Use for memory efficiency.
14=PF_OutFlag_WORKS_IN_PLACE
TRUE=effect can use the same buffer for
both input and output; otherwise requires
separate buffers.
15=PF_OutFlag_SQUARE_PIX_ONLY
Supports square pixels. Ignored.
16=PF_OutFlag_CUSTOM_UI
Has custom user interface and wants
PF_Cmd_EVENT messages. See
AE_EffectUI.h.
17=PF_OutFlag_RESERVED5
No longer used. Was
PF_OutFlag_CUSTOM_NTRP.
18=PF_OutFlag_REFRESH_UI
If set, host will call plug-in with update UI
event right before plug-in exits.
19=PF_OutFlag_NOP_RENDER
Not currently implemented (version 4.0).
20=PF_OutFlag_I_USE_SHUTTER_ANGLE
Effect depends on shutter_angle field.
21=PF_OutFlag_I_USE_AUDIO
Effect output is based on audio values. See
audio callbacks in the After Effects SDK.
Cross-Application Plug-in Development Resource Guide
26
4. Adobe After Effects PiPLs
Table 4-20: PF_Outflags parameters (Continued)
Field
Description
22=PF_OutFlag_I_AM_OBSOLETE
Set if you want your plug-in to be available, but not appear in the Effect menu.
23=PF_OutFlag_FORCE_RERENDER
Set to force effect to re-render.
24=PF_OutFlag_PiPL_OVERRIDES_OUTDATA_
OUTFLAGS
Instead of checking code flags against PiPL
flags, After Effects will just rely on the PiPL
flags.
25=PF_OutFlag_I_HAVE_EXTERNAL_DEPENDE
NCIES
Set if plug-in depends on files external to
the project (like fonts).
26=PF_OutFlag_RESERVED4
Reserved. Must be zero.
27=PF_OutFlag_AUDIO_FLOAT_ONLY
(Audio) Plug-in handles only
PF_SIGNED_FLOAT data.
28=PF_OutFlag_AUDIO_IIR
(Audio) Output depends on output at
other times.
29=PF_OutFlag_I_SYNTHESIZE_AUDIO
(Audio) Plug-in creates output, even if
input was silence.
30=PF_OutFlag_AUDIO_EFFECT_TOO
(Audio) Must be set if plug-in alters audio
as well as image data.
31=PF_OutFlag_AUDIO_EFFECT_ONLY
(Audio) Plug-in alters only audio.
!
Note: These fields are not FlagSets. For instance, the first bit of the
PF_Outflags structure, PF_OutFlag_KEEP_RESOURCE_OPEN, is the
least–significant bit of the flag byte.
Cross-Application Plug-in Development Resource Guide
27
4. Adobe After Effects PiPLs
Format–specific properties
These properties are applicable to Format plug–in modules.
Table 4-21: Adobe After Effects format-specific properties
Type
Name
Key
Description
TypeCreatorPair
PIFmtFileTypeProperty
0x666d5443L
('fmTC')
Default type and creator code
used for files newly created with
this format plug–in.
Under Windows, files don’t store
TypeCreator information,
except internally, so this property
is not required; they are always
interpreted as of type 'BINA' and
creator 'mdos'.
All the info regarding what files
can be read and written is
obtained from the
PIReadExtProperty or the
PIFilteredExtProperty.
Under Windows, PiMI extensions
are converted to
PIReadExtPropertys, so use of
PIFilteredExtProperty
requires additional coding if you
are porting a 16–bit plug–in
format module to 32–bit.
Array of
TypeCreatorPair
PIReadTypesProperty
0x52645479L
('RdTy')
List of type and creator pairs
which the format plug–in can
read. Specifying a value of four
spaces (0x20202020L) matches
any type or creator.
Array of
TypeCreatorPair
PIFilteredTypesProperty
0x66667454L
('fftT')
List of type and creator pairs for
which the file format plug–in
should be called to determine if
the file can be read. Specifying a
value of four spaces
(0x20202020L) matches any type
or creator.
Array of
OSTypes
PIReadExtProperty
0x52644578L
('RdEx')
List of extensions which the format plug–in can read. The extension is stored in the first three
characters of the OSType. The
fourth character must be a space.
Array of
OSTypes
PIFilteredExtProperty
0x66667445L
('fftE')
List of extensions for which the
file format plug–in should be
called to determine if the file can
be read.
Cross-Application Plug-in Development Resource Guide
28
4. Adobe After Effects PiPLs
Table 4-21: Adobe After Effects format-specific properties (Continued)
Type
Name
Key
Description
FlagSet
PIFmtFlagsProperty
0x666d7466L
('fmtf')
This property contains a set of
flags which control the operation
of file format plug–ins. The
default value for any flag is
FALSE. See table 4-22.
Point
PIFmtMaxSizeProperty
0x6d78737aL
('mxsz')
The maximum number of rows
and columns that can be in an
image saved in this format. Photoshop will use this field to
screen out ineligible formats.
Array of
int16s
PIFmtMaxChannelsProperty
0x6d786368L
('mxch')
An array of counts of the maximum number of channels which
can/will be saved for a given
image mode.
This array is indexed by the plug–
in mode constants. For example,
if your format plug–in supports a
single alpha channel in RGB
mode, you should set
maxChannels
[plugInModeRGBColor]=4.
A plug–in may still be asked to
save more channels than it
reports it can support. This field
exists primarily so that
Photoshop can warn the user
that alpha channels will be
discarded.
Table 4-22: PIFmtFlagsProperty parameters
Field
Description
0=PIFmtReadsAllTypesFlag
Obsolete.
1=PIFmtSavesImageResourcesFlag
Resources besides image data, such as printing
information, pen tool paths, etc.. are known as
image resources. The plug–in format has the
option of taking responsibility for these resources
by reading and writing a block of data containing
the image resources. If FALSE, Photoshop will add
the image resources to the file’s Mac OS resource
fork but this will not be portable to other platforms.
2=PIFmtCanReadFlag
=TRUE if the file format can read files .
3=PIFmtCanWriteFlag
=TRUE if the file format can write files .
4=PIFmtCanWriteIfReadFlag
Whether plug–in can write the file if the plug–in
originally read the file.
Cross-Application Plug-in Development Resource Guide
29
4. Adobe After Effects PiPLs
Input/output-specific properties
These properties are applicable to Input/Ouput Format plug–in modules.
Table 4-23: Adobe After Effects format-specific properties
Type
Name
Key
Description
int32
AEImageFormatExtensionInfo
0x46584d46L
('FXMF')
Adobe After Effects Imageformat
Extension Information. Describes
dynamic resources of module. See
table 4-24.
AEImageFormatExtensionInfo
typedef struct AEImageFormatExtensionInfo
{
long
majorVersion;
long
minorVersion;
int32
extensionFlags;
long
reserved;
char
signature;
} AEImageFormatExtensionInfo;
Table 4-24: AEImageFormatExtensionInfo structure
Type
Field
Description
long
majorVersion
Major version number.
long
minorVersion
Minor version number.
int32
extensionFlags
Flags describing resource. See table 4-25.
long
Reserved.
Reserved.
char
signature
Cstring. Localizable name of plug-in.
Table 4-25: AEImageFormatExtensionInfo extensionFlags parameters
Field
Description
0=Input
Input module present.
1=Output
Output module present.
2=File
Direct correspondence to filetype in file system.
3=Still
Still image support (Video=FALSE). (PICS file format is an example
of Video).
4=Video
Video support (Still=FALSE)
5=Framestore
Time independent frame store. If TRUE, Still=TRUE.
6=InteractGet
User interaction required for new sequence. Required if
File=FALSE and Input=TRUE.
7=InteractPut
User interaction required for new output. Required if File=FALSE
and Output=TRUE.
8=InteractPutRevert
User interaction required for new output, even if revertInfo is
available.
9=NonSeqAddFrame
Add frame can handle non-sequential times.
10=NoOutputDialog
Has no output options dialog.
11...31=Reserved.
Reserved. Must be zero.
Cross-Application Plug-in Development Resource Guide
30
4. Adobe After Effects PiPLs
Adobe After Effects PiPL syntax
This information is included as reference material. If you use the example
source code and the documentation included on the Adobe After Effects
SDK, you probably won’t need to worry about the specifics of the PiPL
syntax.
# Miscellaneous definitions
:=
# Beginning of real grammar.
:=
:=
"resource" "'PiPL'" "("
")"
:=
|
","
:=
|
","
:=
|
"|"
:=
"{" "{"
"}" "}"
:=
|
","
:=
|
:=
|
|
|
|
|
|
<68k code descriptor property> |
Cross-Application Plug-in Development Resource Guide
31
4. Adobe After Effects PiPLs
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
:= "Kind" "{" "}"
:= |
"Filter" |
"Parser" |
"ImageFormat" |
"Extension" |
"Acquire" |
"Export"
:= "Version" "{" "}"
:= |
"(" "<<" "16" ")" "|"
"(" ")" |
:= "FilterVersion" |
"ParserVersion" |
"ImageFormatVersion" |
"ExtensionVersion" |
"AcquireVersion" |
"ExportVersion"
:= "latestFilterVersion" |
"latestParserVersion" |
"latestImageFormatVersion" |
"latestExtensionVersion" |
"latestAcquireVersion" |
"latestExportVersion"
:= "latestFilterSubVersion" |
"latestParserSubVersion" |
"latestImageFormatSubVersion" |
"latestExtensionSubVersion" |
"latestAcquireSubVersion" |
"latestExportSubVersion"
:= "Priority" "{" "}"
:= "Host" "{" "}"
Cross-Application Plug-in Development Resource Guide
32
4. Adobe After Effects PiPLs
:= "Name" "{" "}"
:= "Category" "{" "}"
<68k code descriptor property> := "Code68k" "{" , "}"
:= "CodePowerPC" "{"
, "}"
:= "CodeWin32X86" "{" "}
:= "noBitmap" | "doesSupportBitmap"
:= "noGrayScale" | "doesSupportGrayScale"
:= "noIndexedColor" | "doesSupportIndexedColor"
:= "noRGBColor" | "doesSupportRGBColor"
:= "noCMYKColor" | "doesSupportCMYKColor"
:= "noHSLColor" | "doesSupportHSLColor"
:= "noHSBColor" | "doesSupportHSBColor"
:= "noMultichannel" | "doesSupportMultichannel"
:= "noDuotone" | "doesSupportDuotone"
:= "noLABColor" | "doesSupportLABColor"
:= "SupportedModes"
"{"
","
","
","
","
","
","
","
","
","
"}"
:= "FilterCaseInfo"
"{"
"{"
# filterCaseFlatImageNoSelection
# filterCaseFlatImageWithSelection
# filterCaseFloatingSelection
# filterCaseEditableTransparencyNoSelection
# filterCaseEditableTransparencyWithSelection
# filterCaseProtectedTransparencyNoSelection
# filterCaseProtectedTransparencyWithSelection
"}"
"}"
:=
","