Getting Started

SDK API Reference

SDK API Features

Other Documentation

Frequently Asked Questions

Table of Contents

1 Introduction

These are the frequently asked questions, FAQ, for the Photoshop Software Development Kit.

2 SDK

2.1 What is an SDK?

SDK stands for Software Development Kit. An SDK contains documentation and example source code used to develop code modules (called plug-ins) that extend the capabilities of Adobe products.

2.2 Where can I get an SDK?

All the Graphics and Publishing SDKs are free of charge (and free of support) for downloading from the Adobe Solutions Network (ASN) web site, at http://partners.adobe.com/public/developer/photoshop/devcenter.html. This site also contains information on joining the ASN and purchasing support.

2.3 What is an API?

An API is an Application Programming Interface, which is the layer of functionality exported by a host application to external applications, such as plug-ins.

2.4 What is a plug-in?

A plug-in is a dynamic link library, DLL, which adds functionality to a host application, e.g. Photoshop. The host application is responsible for loading your plug-in into memory, calling the functions in the plug-in, and unloading your plug-in.

2.5 Why should I write a plug-in?

Often plug-ins serve vertical markets and other markets that are not normally considered when trying to determine features that best serve the average user's needs.

2.6 How do I make a plug-in?

You will need to have a development environment for the OS that you are developing for. Microsoft Visual Studio and Apple Xcode are the development environments that the sample projects in the SDK use. You can build all of the sample projects using the master projects found in the SampleCode\MasterProjects directory.

2.7 How do I make a plug-in using XCode?

XCode does not support PEF binaries. Photoshop CS and earlier will only load PEF binary plug-ins. Photoshop CS2 is a MachO application. Photoshop CS2 will load both PEF and MachO binaries. Even though Photoshop CS2 is a Mach0 application XCode is not a supported build system.

2.8 Where is the Photoshop File Formats documentation?

http://www.adobe.com/devnet-apps/photoshop/fileformatashtml/

3 Photoshop SDK

3.1 Photoshop API

3.1.1 What is the Photoshop API?

The Photoshop Application Programming Interface (API) is the set of functions exported by the Photoshop application to allow third-party plug-ins to interact with the application and supply solutions to diverse needs not necessarily covered by the application.

3.1.2 What can I do with the Photoshop API?

The Photoshop API supports seven different types of public plug-in modules. Import, Export, File Format, Filter, Selection, Color Picker, and Automation.

3.1.2.1 What are Import plug-in modules?

Import plug-in modules are used to capture images from add-on hardware, such as scanners or video cameras, and put these images into new Photoshop document windows.

3.1.2.2 What are Export plug-in modules?

Export plug-in modules are designed to output information from an open Photoshop document. This is the opposite of an Import plug-in. Examples of usage include exporting to proprietary equipment or displays, and exporting specific data such as paths or resources.

3.1.2.3 What are File Format plug-in modules?

File Format plug-in modules are designed to read and write files that are not supported out-of-the-box by Photoshop. File format plug-in modueles are integrated into the Photoshop Open and Save as... dialogs.

3.1.2.4 What are Filter plug-in modules?

Filter plug-in modules are the most common of Photoshop plug-in modules. They allow editing of pixel data, such as special image effects.

3.1.2.5 What are Selection plug-in modules?

Selection plug-in modules are like "smart magic wands" that can iterate through pixel data and return a selection based on that data, or return a path.

3.1.2.6 What are Color Picker plug-in modules?

Color Picker plug-in modules are selected from the File>Preferences>General preferences panel, and allow a plug-in to display its own UI for the user to pick a color with.

3.1.2.7 What are Automation plug-in modules?

Automation plug-in modules are extensions to the actions system and the actions panel introduced in version 4. Automation plug-in modules were introduced in version 5. They allow you to play events programmatically. They are found in the File>Automate or Help menus. The wizards that shipped with version 5 are Automation plug-ins.

3.1.3 What can I not do with the Photoshop API?

No non-modal plug-ins.

No plug-in tools.

No plug-in floating windows.

No plug-in panels. (See the CS SDK for Flash based panels)

No plug-in brushes.

No adding or changing menus.

No threading, the Photoshop API is NOT thread safe.

3.1.4 Why does my plug-in not show up?

3.1.4.1 Your plug-in is not in the proper place.

Make sure that your plug-in module is located where Photoshop is looking for plugins to load. This has changed over the course of different versions, and is now userconfigurable.In version 6, look under Edit>Preferences>Plug Ins & Scratch Disks to see the current settings.

3.1.4.2 Your plug-in does not have the correct extension or type/creator.

Photoshop will only load plug-ins with the correct extension on Windows and correct File Type on Macintosh. See the "Application Programming Interface Guide" for more information.

Windows: .8bp, .8li, .8bc, .8ba, .8be, .8bx, .8bf, .8bi, .8by, .8bs. Macintosh: 8BPI, 8LIZ, 8BCM, 8BAM, 8BEM, 8BXM, 8BFM, 8BIF, 8BYM, 8BSM.

3.1.4.3 Your plug-in does not have a PiPL

After Photoshop decides to load your plug-in, based on the above extension and File Type, it will look for the PiPL resource. The PiPL resource further configures your plug-in for specific type information. See an example plug-in in the Photoshop SDK for details of the PiPL configuration for your plug-in type.

3.1.4.4 Your plug-in does not have an ENTRYPOINT/PluginMain

One item that every plug-in must have is an ENTRYPOINT or PluginMain. This is the "main" routine that gets called when your plug-in is selected.

3.1.4.5 Your plug-in needs a system DLL.

Your plug-in may be dependant on a system DLL that is not installed. Check your C/C++ -> Code Generation panel. If your settings for Run-time library is using a DLL then you will probably need to install MSVCP60D.DLL and MSVCRTD.DLL on your system. You can use the non-DLL versions for the Run-time setting but your plug-in will be larger. This should not be a problem for release builds. The system DLLs are already installed on the system.

3.1.4.6 It still doesn't show up.

If you are on windows and your plug-in doesn't load it is usually an issue with the PiPL resource in the final binary of the plug-in. These instructions are for Windows plug-in developers only. After building the plug-in open up a terminal, command prompt window. Navigate to the directory where the plug-in resides. Substitue the file name with the name of your plug-in.

dumpbin /EXPORTS MyPluginName.8bf

The output will look similar to this. Here is the output from the Shape plug-in.

D:\sdk\public\samplecode\Output\Win\Debug>dumpbin /EXPORTS Shape.8bs 
	Section contains the following exports for Shape.8bs 

		0 characteristics 
	3B7AEEC9 time date stamp Wed Aug 15 16:51:05 2001 
	0.00 version 
	1 ordinal base 
	2 number of functions 
	2 number of names 
	
	ordinal hint RVA 
	summary 
	1000 .data 
	1000 .idata 
	1000 .rdata 
	1000 .reloc 
	2000 .rsrc 
	19000 .text

The two things you are interested in are after the "ordinal hint RVA name" line. These are the two functions that are "exported" for the Shape.8bs plug-in. "PluginMain" for the plug-in entry point and "-SelectionProcQ16" for the UI entry point. Now go to MSDEV and open your plug in making sure you select "Open As" -> Resources before selcted OK. You will get a list of all your plug-in resources. One of them should be a PiPL resource. Open it up, it's binary data, look for MIB868xw for the windows program entry point. Following that should be a string of your progam entry point EXACTLY as the one above, "PluginMain" . The most common error is your plug-in doesn't have a PiPL resource or that Pip1 resource is wrong. Make sure your custom build step for your .r file is correct. cl takes the .r and makes a .rr. cnvtpipl takes the .rr and makes a .pipl. The .rc file includes the .pip1 file.

Make sure your program is exporting the entrypoints

#define DLLExport extern "C" -declspec (dllexport) 

DLLExport MACPASCAL void PluginMain(const intl6 selector,
                                    FilterRecord* filterRecord,
				    int32* data,
				    intl6* result);

DLLExport BOOL WINAPI DissolveProc(HWND hDlg, 
	       	      		   UINT wMsg, 
				   WPARAM wParam, 
				   LPARAM lParam);

Are you using any other DLL's in your plug-in. Make sure the system knows where they are and can load them properly. I don't deal with plug-ins that deal with DLL's but if you put it next to your plug-in or next to the Photoshop application that usually works. Again I don't have a lot of experience with this part of it.

3.1.4.7 I want to have one plug-in for all versions of Photoshop

That is a tricky problem that we have not yet found a great solution to. The main problem is that CS1 only sees PEF, CS2 & CS3 see both PEF & Mach-O on PPC, and of course CS3 on Intel only sees Mach-O. The problem occurs when CS2 or CS3 see both the PEF and Mach-O versions and cant decide which to use. Since you can't even build for CS1 from Xcode I'd suggest you at least keep them as separate installs, even if they are shipped together. How you sell and support of course is up to you.

3.1.5 Why does Photoshop crash?

Remember it is very easy for a plug-in to cause problems to the host application. Remove your plug-in and verify that Photoshop is ok. You might want to delete the preferences file. Reinstall your plug-in and see if the problem comes back.

3.1.5.1 Why does Photoshop crash after it unloads my plug-in?

Are you on the Macintosh? Are you using Objective-C code? If yes, certain OS X operating systems have trouble handling unloads of libraries containing Objective-C code. It is recommended that you upgrade the OS X operating system to the latest OS or remove your dependency on the Objective-C library.

3.1.6 Why does my menu look like one of Photoshop's or vice versa?

This is a Macintosh only problem. When defining your custom resources use ID values above 16000. This is especially true for menu ID values. You may also conflict with another plug-in that is always loaded.

3.1.7 Why does my modal dialog show up behind the panels?

This is a Macintosh only problem. Your plug-in is probably using a custom WDEF. On OS X puts these items in the document layer which has a lower z ordering priority than panels. Use the following OS function call. See the Apple documentation for more details. SetWindowGroup(myWindowRef, GetWindowGroupOfClass(kModalWindowClass));

3.2 Windows-specific issues

3.2.1 Cnvtpipl and Resource (Rez) files

3.2.1.1 What is a Resource (Rez) file?

Resource files are human readable text files that describe resources that are used by a plug-in. On the Macintosh, the resource format is automatically precompiled and compiled by a Rez compiler that ships with Xcode. Those files have an extension of ".r", such as "myplugin.r". On Windows, the resource format is not native and a unique utility, Cnvtpipl, is required to parse these files.

3.2.1.2 What is CnvtPiPL?

Cnvtpipl is a utility created by Adobe to parse rez files (.r files) for plug-in specific resources and create valid Windows resource (.rc) files from the human-readable resource text. Cnvtpipl stands for "Convert PiPL".

3.2.1.3 What resource types does Cnvtpipl understand?

PiPL, PiMI, Path, STR , aete, fltD, ANIM, aPAR, and aFLT are all recognized and converted by Cnvtpipl.

3.2.1.4 Do I need a custom build step in my project to make this work?

Yes. All the shipping Photoshop examples on Windows have a custom build step to take the rez file (.r file) and pipe it through Cnvtpipl to create valid resources that are included with the built plug-in. See any of these examples for details on how to add the custom build step to your plug-in.

3.2.1.5 What is the specific custom build process for rez files?

First the standard lexical preprocessor preprocesses the .r file. Then, that output is streamed through Cnvtpipl. Cnvtpipl spits out valid .rc text, which, in the examples, is saved as "<myplugin>.pipl" in the Temp folder. Then that file is included as a compile-time include in the .rc file that is part of the project.

3.2.1.6 How do I see these settings?

In Visual Studio, go into Project Settings, click on the .r file and click the tab for Custom Build step. To see the compile-time include statement, right click on the .rc file and choose the menu-pop up for "Resource includes..."

3.3 Plug-ins and 16 bit data

3.3.1 Why does my 16 bit plug-in only see values of 0 - 32768 and not 0 - 65535?

Photoshop uses an internal representation of 16 bit data of 0 - 32768. When acquiring, importing, reading, or writing files check or set the maxValue in the parameter record. Filters will also see this range for 16 bit data.

3.3.2 Why does Photoshop use such an odd range?

Speed, speed, and more speed. First of all this range keeps more of the math in 32 bits, avoiding heavy use of 64 bit math, which is still slow on todays machines. Second of all you can use shifts instead of costly divide operations, speeding up the 16 bit version of our routines by quite a bit. Another feature of using this range is that there is a true center, unlike 2^N-1 representations, which gives us significant improvements in many of the blending routines.

3.4 How do I debug my plugin?

3.4.1 How do I debug on Windows?

Make sure you are on the Debug target, Build->Set Active Configuration. Set your breakpoints, Right-Click, Insert/Remove Breakpoints or F9. Start Debug, Build->Start Debug->Go or F5. You get a dialog box for executable. Navigate to the Photoshop.exe and press ok.

3.4.2 How do I debug on Macintosh?

Copy your plugin into the Photoshop Plug-Ins folder. Start Photoshop. In Xcode attach to the Photoshop process. In Xcode click the "Pause program execution" button. In Xcode type "breakpoint set -n DissolveRectangle" in the console window. Click the "Continue program execution". Execute your plugin from the Photoshop menu. Your breakpoint should occur.

3.5 How do I enable my plugin?

There are two ways to enable your plugin. SupportedModes and EnableInfo. SupportedModes is the old way. SupportedModes only supports 10 different modes. EnableInfo is the new. EnableInfo allows for future expansion. See the PiPL guide for creating an enable description. Here are the latest image modes: BitmapMode, GrayScaleMode, IndexedMode, RGBMode, CMYKMode, HSLMode, HSBMode, MultichannelMode, DuotoneMode, LabMode, Gray16Mode, RGB48Mode, Lab48Mode, CMYK64Mode, DeepMultichannelMode, Duotone16Mode, RGB96Mode, and Gray32Mode. You can also specify true. See the sample code for more details.

4 Filter Modules

4.1 How do I preview my effect in the original document window?

You cannot. The built-in filters in the filter menu that show the preview on the original document window are not plug-ins. They are not "built-in plug-ins" either. That makes no sense and makes us all here at Adobe giggle when you call them that.

4.2 How do I have a live preview instead of a proxy preview?

I repeat this question only because it is probably the #1 request. Again you cannot preview your plug-in effect in the original document window.

4.3 Can I write/read outside the current selection?

Pre-Photoshop 4 the answer is no. You can only read/write the current selection. Since Photoshop 4.0, you can set the PiPL bit "writesOutsideSelection" and you will always be passed the entire layer, so you can write outside the selection.

4.4 Can I write/read outside the current layer?

Pre-Photoshop 4 the answer is no. Photoshop 4 introduced the "ReadImageDocumentDesc"and the "ChannelPortProcs". Photoshop 4 allowed you to see the composite information, read only, of the entire document. Photoshop 5 added the file specification if any to the "ReadImageDocumentDesc". Photoshop 7 added more items to the "ReadImageDocumentDesc": The ability to read the other layers in the document via a linked list. The ability to read the next "ReadImageDocumentDesc", usually the clipboard.

4.5 Can I get the number of layers of the current image?

Pre Photoshop 7 the answer is no. Photoshop 7 added the layersDescriptor to the "ReadImageDocumentDesc". This is a linked list of all of the layers in the current document.

4.6 Can I generate a new layer?

No. Filter plug-ins cannot create or delete layers in the document.

5 Automation Modules

5.1 How do I construct an event correctly? The "Actions Event Guide" is confusing.

The best way to understand how to put an event together is to use the DEBUG Listener plug-in found in the SDK. This utility plug-in creates a log file, Listener.log, of all the events that occurred while you were using Photoshop.

5.2 What is Listener?

Listener is a utility plug-in that records all of the events while you were using Photoshop. Build the DEBUG version of the plug-in. Place the Listener.8li plug-in into the Photoshop "Plug-Ins" folder and launch Photoshop. Do the things in Photoshop that you want your Automation plug-in to do and quit Photoshop. Check the Listener.log file to see how to build the event(s), descriptor(s), list(s), and reference(s).

5.3 What if it is not in the Listener log file?

Almost all of Photoshop is scriptable. There are some items that are not scripted. The Actions Panel and the layout of panels on the screen are a couple of examples. If the Listener plug-in does not have it in the log file then it is not scriptable. You will need to try another approach.

5.4 How do I get the number of open documents?

You use the Get() command. You need to build a reference to what you are getting. In this case it would be classApplication and keyNumberOfDocuments. See the Getter plug-in for the details. There are utility routines for this in PIUGet.cpp.

5.5 How do I get other information?

See the Getter plug-in example in the automation folder of the SDK. This will make a Getter.log file of all the information currently available to an automation plug-in.

6 Forum Help

6.1 How do I get help with my plugin?

See the Developer Resources section.

7 Adobe Dialog Manager (ADM)

7.1 Where are the ADM (Adobe Dialog Manager) header files?

The ADM header files are no longer part of the Photoshop SDK. The Adobe Dialog Manager has been deprecated and no longer works on the Macintosh platform.

7.2 What should I do as a replacement?

There is currently no direct replacement for the ADM API. Plug-in developers must write their UI using the API's provided by the OS. There are 3rd party UI toolkits available. Many developers have had success with the Qt UI framework.

7.3 Which versions of Photoshop will ADM still work with?

Photoshop CC does not support ADM

Photoshop CS6 on Windows (32 and 64 bit)

Photoshop CS5 on Windows (32 and 64 bit) - Macintosh 32 bit only

Photochop CS4 and previous versions back to Photoshop Version 5.0

01/08/2016