Plug-in Basics

Sections on this Page

• Plug-in modules and plug-in hosts
• A short history lesson
• Macintosh and Windows development
• Version Information

This section describes what plug-in modules are and provides information common to all plug-in modules. You should understand this material before proceeding to the chapters detailing the specific types of plug-in modules.

This chapter also contains information about compiling and testing plug-in modules under the Mac OS and Microsoft Windows. Additional compiler-specific information is available in the toolkit header files.

Plug-in modules and plug-in hosts

Adobe Photoshop plug-in modules are software programs developed by Adobe Systems and third-party vendors with Adobe Systems to extend the standard Adobe Photoshop program. 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. Adobe Photoshop is a plug-in host.

These Adobe applications function as plug-in hosts: Adobe After Effects, Adobe Premiere, Adobe Illustrator, Adobe PageMaker, and Adobe PhotoDeluxe. 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 toolkit and guide are 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.

Unless otherwise stated, Adobe Photoshop is assumed to be the plug-in host throughout this manual. Other hosts may or may not support all the callbacks, properties and functionality described in this guide.

A short history lesson

Plug-ins are not unique to Photoshop. Many Macintosh and Windows applications support some form of plug-in extensions. Perhaps the best known example of an application that supports a plug-in architecture is Apple’s HyperCard, with its support for XCMDs and XFCNs. One of the first companies to incorporate plug-in modules into their products was Silicon Beach, in its Digital Darkroom and SuperPaint products.

Silicon Beach spent a lot of time developing a newer, better designed plug-in implementation. In HyperCard, developers have to paste their plug-ins into the host application using ResEdit. Silicon Beach’s design for plug-in modules has the code residing in individual files. This allows the plug-in files to be placed anywhere, not just in the System Folder. Silicon Beach’s design also incorporated the concept of version numbering, which allowed for smooth migration as new functionality was added to the interface.

Adobe Photoshop’s implementation of plug-in modules loosely resembles that used by Silicon Beach. It uses a similar calling sequence, and the same version number scheme.

However, the similarity ends there. As Photoshop’s plug-in architecture evolved, the detailed interface for Photoshop’s plug-in modules became completely different from that used by Silicon Beach. The differences were required primarily to support color images and Adobe Photoshop’s virtual memory scheme.

A great overview of Macintosh programming with code fragments is provided in A Fragment of Your Imagination, by Joe Zobkiw (1995, Addison-Wesley, NY, ISBN 0-201-483358-0). Chapter ten of Zobkiw’s book is solely about writing Photoshop filters.

Macintosh and Windows development

The original plug-in interface was designed when Adobe Photoshop was a Macintosh-only product. This heritage is still apparent today, and affects Windows developers building plug-ins. While you can build plug-in modules for Windows without needing a Macintosh, there are a number of data structures and Mac toolbox-like calls that will appear in your Windows code. The good news is that this makes building plug-ins that work across both Mac OS and Windows easier. The bad news is that if you’re developing only for the Windows platform, some of the terminology may be unfamiliar.

Another important difference between the Macintosh and Windows is byte ordering. Motorola and PowerPC processors store pointers, 16-, and 32- bit numbers in big endian format, while Intel processors use little endian format. An example of this is the number 65298, which would disassemble as hex word $FF 12 on a Motorola or PowerPC processor, and $12 FF on an Intel processor. $12 FF on the Intel could be mistaken by beginning Macintosh programmers as 4863, when it in fact is 65298.

Because many Photoshop files are designed to work across both platforms, the Photoshop engineering team chose to standardize on big endian format (Photoshop’s heritage shows through again). When programming under Windows, you must be careful to handle byte ordering properly.

Version Information

2.5 & 3.0
The plug-in interface changed significantly with the release of Adobe Photoshop 3.0. The main difference is the use of 'PiPL' resources to describe plug-in module information. This replaces the older 'PiMI' resources, although Photoshop still fully supports PiMI based plug-in modules. PiPL and PiMI resources are discussed in the document Cross Application Plug-in Development Resource Guide.

The other significant change in version 3.0 is the introduction of the AdvanceStateProc callback function. This callback provides improved performance for plug-in modules that handle large images.

3.0.4
In Photoshop version 3.0.4, the plug-in architecture was again enhanced. You can now set certain properties of a plug-in host using the SetPropertyProc callback. The GetPropertyProc and SetPropertyProc callbacks were grouped together to form a new callback suite. See Property Suite Callbacks for details.

Version 3.0.4 also adds a new callback suite: the Image Services Suite Callbacks. The two callback functions in this suite allow you to resample image data, and are useful for various types of filter, import, and export modules.

3.0.5
Version 3.0.5 offers bug fixes and compatibility updates for PowerPC Macintoshes and Windows 95. There are no new API changes or additions in 3.0.5.

4.0
Version 4.0 expands the API to include two new plug-in module types: color pickers and selections, and an associated set of callback functions in the new Channel Ports Suite. There is also an added AppleEvent/AppleScript resource, 'aete', which describes your plug-in parameters to the Actions palette. Accompanying that is a set of callback functions in the new Descriptor suite. The parameter blocks for Import, Export, Filter, and Format have grown to include the new callback suites, where appropriate. The module name for "Acquire" modules was renamed "Import" to be consistent with other Adobe products. This change is cosmetic—the code parameter and function names remain the same, such as acquireSelectorContinue.

4.0.1
4.0.1 was mostly a bug fix release, but it does introduce new parameters in PIAcquire.h to allow for importing images with transparency.

5.0
Version 5.0 expands the API to include a new plug-in module type: automation. These plug-ins can call any scriptable Photoshop command and external filter modules, but cannot manipulate pixel data.

See Photoshop Actions Event Guide for detailed information on automation plug-ins.

5.0.2
Version 5.0.2 was mostly a bug fix release. The canUseICCProfiles flag, ICC profiles handed to Photoshop, and file formats writing 16 bit files were fixed in Version 5.0.2.

5.5
Version 5.5 has very few modifications to the API. A lutCount variable was added to the end of the Import, Export, and File Format module paramater blocks. A new ProgressText PiPL property was added for special handling of the progress bar. The File Format modules also got a new Format Flag for transparency information.

6.0
Version 6.0 has very few modifications to the API. A new routine was added to the Color Space Suite. Three new parameters were added to the Filter Paramater block, iccProfileData, iccProfileSize, and canUseICCProfile. More information is found in Filter Module and in the PIFilter.h header file.

7.0
File format plug-ins can now display a thumbnail view in the Open dialog. See the SimpleFormat example fmtCanCreateThumbnail and openForPreview. Photoshop has now gone to a new system for the serial number. Old serial numbers can still be input through the Preferences panel.

The Scripting Support plug-in developed for Illustrator is now available for Photoshop. You can now create JavaScript, AppleScript, and Visual Basic scripts. Scripting Support comes in a separate package and installer. Plug ins now have read access to all the layers in a Photoshop document. See the PoorMansTypeTool example.

Share Data Section must be off in your project settings for Macintosh.

The AutomationFilter automation plug in and Hidden filter plug in work together to access all layers and all channels of a document. This release moves the pixel read and write inside the Hidden plug in. This allows the Hidden filter to work faster and to use tiling.

New properties available, see PIProperties.h and the Propetizer example: propTargetLayerLock, propXMP, propSerialString2, propSelectedSliceID, propSelectedSliceIndex, propVersion, propPlayInProgress, propUnicodeName, propUniStr255Name, and propUnicodeNameWithoutExtension.

If your dialog uses a custom WDEF your dialog will show up behind the Photoshop palettes on OS X. Use the following OS call to fix the problem.

SetWindowGroup(myWindowRef, GetWindowGroupOfClass(kModalWindowClass)); 

See the Apple documentation for more details.

The Project settings for Windows now use Blend for Processor.

CS (8.0)
Documents larger than 30,000 x 30,000 pixels. All records have been updated for 32 bit coordinates for document rects and points. Automation plug-ins can now set a FileBrowseAware flag. Automation plug-ins with this PiPL property will show up in a File Browser menu item as well as the File->Automate menu item. MaxSize and MinSize PiPL properties have been added for setting the max and min size of a document your plug-in will work on. New properties for unicode support. See PIProperties.h

CS2 (9.0)

CS3 (10.0)