Getting Started

SDK API Reference

SDK API Features

Other Documentation

What is new in CS4?

Photoshop is now running native on 64 bit processors. See more information about making 64 bit plug-ins here.

What is new in CS3?

A large portion of the documentation has moved to an HTML format produced from doxygen. You are reading that right now. This gives a better overall picture of the SDK and easier navigation between topics. The sections to the left are the primary navigation for the SDK documentation.

Adobe Photoshop CS3 is now a Universal binary. Your plug-in needs to be a Universal binary as well to support the MacTel operating system. Apple's Xcode development environment is the recommended way to create a Universal binary. See the Making Xcode Projects for Mac OS section to learn how to move your plug-in to the Xcode environment.

All shipping plug-ins are using the bundle method. You see one file that looks like a plug-in but it is actually a bundle with all the parts inside. See the section below Bundling Plug-Ins.

Two new plug-in types for this version.

  • Stack Renderer plug-ins
  • Measurement plug-ins

3D support

  • Connect your 3D engine for rendering images in Photoshop
  • Manipulate the 3D scene from a filter plug-in
  • Read and Write 3D data using the file format plug-in

File Format plug-ins can now open multi-layered files.

Smart filters for non-destructive editing. See Dissolve example.

  • Add PiPL property, FilterLayerSupport {doesSupportFilterLayers}
  • Do not pop a dialog, use the descriptor params playInfo (gFilterRecord->descriptorParameters->playInfo)
  • - plugInDialogDontDisplay--Display dialog only if necessary due to missing parameters or error.
  • - plugInDialogDisplay--Present the plug-in dialog using descriptor information.
  • - plugInDialogSilent--Never present a dialog; use only descriptor information; if the information is insufficient to run the plug-in, the plug-in should return anerror in theerrorString field of the plug-ins parameter block.
  • Support action parameters
  • - watch out for algorithms that use random numbers

Bundling Plug-Ins

Plug-ins that ship with Adobe Photoshop CS3 and CS4 are now inside bundles. Below is the directory layout for the Dissolve plug-in. The Xcode project settings are given below.

Dissolve.plugin/Contents/MacOS/Dissolve
Dissolve.plugin/Contents/Info.plist
Dissolve.plugin/Contents/PkgInfo
Dissolve.plugin/Contents/Resources/Dissolve.rsrc

The first item is the actual plug-in, the binary executable. The second item is the package info created by Xcode containing the creator and type information to make the package icon for Finder. The third item is the resources for the plug-in in binary form.

The Dissolve example is the only example that shows a Universal binary configuration. The Dissolve example actually shows 6 different build configurations. Debug_PPC, Debug_i386, Release_PPC, Release_i386, Debug_Universal and Release_Universal.

Apple Xcode debugging

  • Insert Debugger() or DebugStr() in places that you want to break
  • Select the "build configuration" you want to debug with - since Universal debug is not properly configured, I choose Debug_PPC (since they are essentially the same - my goal is to debug into the plug-in on PPC)
  • Add a new “Executables” ==> ie. select “Executables” from Groups & Files section, control + click or right click and choose Add... -> New Custom Executable... Name the Executable something meaningful, I call it Photoshop CS3 (ie you can have multiple entries pointing to CS2, CS3, etc). Browse (faster) for CS2 .app folder (to fill for Executable Path) -- after that, click Finish
  • It will show you what it did with a config/info dialog — make sure build products directory is pointing to the right place. (in your case, the Debug PPC path, which it should auto select. If not, go and make that the Active Build Configuration and change the working directory radio button to project then back to Build Products dir, it should select the right stuff)
  • Don’t forget to put a shortcut/symlink of your debug binary into Plug-Ins dir (if it doesn’t exist, build it)
  • You should be set at this point — choose Debug Executable from the Debug menu (or if you activate it on your tool bar, click on the debug button)
  • Use your plug-in — and it should break into your code (it will show you assembly code first — since it’s probably breaking into plug-in API — if so, tell it to step out and you’re in business!

To install

Un-zip the archive. Be sure to keep the folder structure intact. The project settings use relative paths to locate common files for all projects.

On Windows, ignore the __MACOSX folder contents. The zip file is created on a Macintosh for both platforms and there is an extra folder present after the un-zipping.

The documentation included on this kit requires Acrobat Reader to view it. To download a copy of Acrobat Reader free of charge, go to http://www.adobe.com/.

Apple Xcode

All the Macintosh projects in this SDK were tested using Apple Xcode environment, Version 2.4.1. This is the recommended version for building a plug-in for Photoshop.

Microsoft Visual Studio

All the Windows projects in this SDK were tested using Microsoft Visual Studio 2005 Version 8.0.50727.42 (RTM.050727-4200) This is the recommended version for building a plug-in for Photoshop.

Memory

Always ask Photoshop for large amounts of memory. See Memory Management for more information.

C++ exceptions

If you turn on C++ exceptions in your plug-in project make sure you wrap all of your call backs with try/catch blocks. You do not want to throw back into Photoshop. This will cause Photoshop to disappear without a warning to the user. Make sure your try/catch blocks are around your PluginMain routine and any OS proc, say for your Dialog routine.

Clean Up

The SDK has gone through some clean up for this version. The C++ wrapper classes for plug-in types have been removed. Along with some of the sample projects. This is around an effort to consolidate the examples. The goal is to have one example for each plug-in type that exposes the key features of the API. There is little value added in wrapping an API in an API and it makes maintenance very difficult. The following projects have been removed: shape and selectorama examples have combined into the selectoramashape example.