Getting Started

SDK API Reference

SDK API Features

Other Documentation
Adobe Photoshop SDK Documentation

New for 2021 ARM - Photoshop 22.0 (BETA) ARM

Photoshop 2021 (BETA) introduces Photoshop running on ARM devices.

Learn how to configure a plugin to work on Apple silicon and Windows ARM devices here.

New for 2021 - Photoshop 22.0

Photoshop 2021 introduces UXP plugins. Learn how to develop UXP plugins here.

A C++ plugin can communicate with a UXP plugin using the new PsUXPSuite1 set of functions.

New for 2020 - Photoshop 21.0

Photoshop 2020 introduces cloud documents. Cloud documents are cloud-native files that you can open and edit in compatible apps. With cloud documents, your work is always updated, across every device, wherever you are. More information here.

See the Listener and Getter examples for usages for these new APIs.

PSAliasSuite2::NewAliasFromCloudPathProc - Makes a new alias from a cloud document path.

PSAliasSuite2::IsCloudFileProc - Used to query whether or not an alias is representing a cloud file.

PSAliasSuite2::CloudReferenceFromAliasProc - Used to get the cloud asset reference for an alias that is related to a cloud file.

PSAliasSuite2::CloudPathFromAliasProc - Used to get the cloud asset reference path for an alias that is related to a cloud file.

PSAliasSuite2::NewAliasFromCloudReferenceProc - Used to create an alias from a cloud asset reference.

PSAliasSuite2::UnicodePathToAliasProc - Used to create an alias from a unicode path.

PSAliasSuite2::AliasToUnicodePathProc - Used to create a unicode path from an alias.

New properties in PIFormat.h. See also PiPL.r

PIFmtSupportsPluginOpeningFile - Plug-in prefers to open and close files itself. The host should not open file.

New items in the FormatRecord - FormatRecord::hostSupportsPluginOpeningFile - Indicates whether the host is letting the plug-in open and close the file for itself. The dataFork, rsrcFork, and posixFileDescriptor fields are undefined.

FormatRecord::hostSupportsSingleOpenToBulkSwitch - Set by host to true before a formatSelectorReadStart call to let plug-in know the pluginWantsSingleOpenToBulkSwitch field is supported.

FormatRecord::pluginWantsSingleOpenToBulkSwitch - Set by plug-in during a formatSelectorReadStart call telling the host to process the results as if the host had called formatSelectorBulkSettings instead.

New properties in PIProperties.h. See the Propetizer example for usage.

propNumberOfScratchVolumes - Number of scratch volumes.

propScratchVolumePath - Photoshop scratch disk volume path at the given index in unicode string.

propIsCloudDocument - Use this to determine if document is a cloud document.

New for Creative Cloud - CC 2019 - Photoshop 20.0

See Details of tools used to build Photoshop and the SDK examples for information about versions of build tools used to make Photoshop and the SDK examples.

New PiPL properties : SupportsPOSIXIO - Plugin can read and write files using POSIX API calls. For the Macintosh only. The File Manager which includes the FSRef type and API is deprecated and Photoshop will require plug-ins to have this key present if and when the FSRef API is missing from the OS. See hostSupportsPOSIXIO, pluginUsingPOSIXIO and posixFileDescriptor in the FormatRecord for more information.

New items in FormatRecord. See PIFormat.h for more information and the SimpleFormat example.

FormatRecord::hostSupportsPOSIXIO - Indicates whether the host supports POSIX file IO plugin API.

FormatRecord::pluginUsingPOSIXIO - Indicates whether the plugin is using the POSIX file IO fields.

FormatRecord::posixFileDescriptor - POSIX file descriptor from an open call by Photoshop.

New properties in PIProperties.h. See the Propetizer example for usage.

propUseMultiUndo - This property can be used to query about the current Undo setting of the host.

propUXPrimaryColor - The primary updated UX color.

propUXSecondaryColor - The secondary updated UX color.

propUXUseUpdatedUX - Flag for whether or not to use updated UX.

propScaleUIToFontZoom - Use this property to tell if the host application is scaling UI to font.

The NewHandle API for the Macintosh has been deprecated. Photoshop will be using the Ptr type to replace most occurrences of the Handle type. This will happen in the future for the Photoshop API. All of the SDK examples have moved away from using the Handle type internally. The Photoshop team recommends you do the same in your plugin. For example, your data being passed into the main callback routine was typically a Handle that your plugin created and Photoshop managed. This can be any type but it is recommended to now use the Ptr type.

New for Creative Cloud - CC 2018 - Photoshop 19.0

New PiPL properties : MonitorScalingAware – Allows the plugin to be set with DPI_AWARENESS level DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2. If this property is set, then it tells Photoshop that the plugin is PerMonitor DPI Aware. See the Dissolve example for more information: DissolveUIWin.cpp. This is for windows only and only for Photoshop Version 19.1 released in January 2018.

This Dissolve example will require the Microsoft SDK version 10.0.15063.0. DPI Awareness constant (DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2) is not defined in lower versions. We would need to define it locally in our code if we want to go to lower SDK.

New for Creative Cloud - CC 2017 - Photoshop 18.0

New items in FilterRecord. See PIFilter.h for more information.

FilterRecord::maxSpace64 and FilterRecord::bufferSpace64 - 64 bit values for getting and setting memory requirements.

New properties in PIProperties.h. See the Propetizer example for usage.

propHighlightColor - Use this property to tell the current highlight color

New functions found in PIActions.h. See the Listener and Getter examples for usage of notifiers.

Allows the plug-in to provide a notification routine for specific events at any playLevel. Any one event can only dispatch to one universal notifier routine per plug-in, but one notifier routine can receive multiple events. Use eventAll to dispatch all events to a single notifier routine. Universal notifiers are distinct from other notifiers and they must be removed by calling RemoveUniversalNotifier. See PIActions.h for more information.

PSActionControlProcs::AddUniversalNotifier (SPPluginRef ref, DescriptorEventID event, PIEventNotifier notifier, void* data, uint32 options);

Removes a universal notifier for an event. Use eventAll to remove notifiers for all events. See PIActions.h for more information.

PSActionControlProcs::RemoveUniversalNotifier (SPPluginRef ref, DescriptorEventID event);

New for Creative Cloud - CC 2015.5 - Photoshop 17.0

Photoshop is on a fast pace, releasing to our customers on a regular basis. This means that users of your plug-ins have to reinstall each time we release a major version of the Photoshop CC application.

We encourage you to include the Component property into your PiPL. This gives Photoshop the ability to determine the newer version of your plug-in if it finds more than one. This is a numbered property and the example SDK is going to use the Major Minor Dot of the host application when the SDK was shipped. You might come up with your own versioning scheme of course. The key is to make sure the number in Component is greater each time you create a public version of your plug-in.

#define plugInName1     "Shape"
#define VersionNumber   17
#define VersionMinor    0
#define VersionDot      0
#define ComponentNumber (VersionNumber << 16) | (VersionMinor << 8) | VersionDot

      Component { ComponentNumber, plugInName1 },

The new version of Photoshop will only load one plug-in with the same menu name. That means that two Shape plug-ins from the example SDK will result in only one menu item for Shape no matter how many plug-ins we find with a name of "Shape" of type selection plug-in. This will be true for all plug-in types. We search recursively into each of these folders:

  1. C:\Program Files\Adobe\Adobe Photoshop CC 2015.5\Required\Plug-Ins
  2. C:\Program Files\Adobe\Adobe Photoshop CC 2015.5\Plug-ins
  3. C:\Program Files\Common Files\Adobe\Plug-Ins\CC

And for the Macintosh 

  1. /Applications/Adobe Photoshop CC 2015.5/Adobe Photoshop CC 2015.app/Contents/Required/Plug-Ins
  2. /Applications/Adobe Photoshop CC 2015.5/Plug-Ins
  3. /Library/Application Support/Adobe/Plug-Ins/CC

The rules for which plug-in will get loaded when we find duplicates is the following:

  1. Highest version inside of Component
  2. Newest file if two or more have same version inside of Component
  3. Any Component vs one without a Component
  4. Newest file if two or more do not have Component property
  5. All ties go to first one we find in the search order.

The 10.8 SDK from Apple deprecated many functions. Photoshop and the plug-in examples are still using many of those functions. This release is our first step in removing some of those deprecated functions. The main focus of this release is the addition of Bookmark support in PIActions.h with PutBookmark, GetBookmark, ConvertAliasHandleToBookmark and ConvertBookmarkToAliasHandle. Use those routines in place of PutAlias and GetAlias and any usage of the Alias functions from the OS.

See the Outbound example for more details on how to use the new suite and functions.

The Selection example has also removed all the OS X Resource Manager API's from the example. The resource use was minimal in that example so the resources were moved into the C code. See the Bundle Programming Guide for a replacement.

propLargeTabs - Use this property to tell if the host application has large tabs

propCheckerboardColor1 - The color of checkerboard 1.

propCheckerboardColor2 - The color of checkerboard 2.

propCheckerboardSize - The size of the checkerboard.

propUseCheckerboard - Use checkerboard or default white

The 3D examples have been removed and marked deprecated. The examples build from the CC 2015 SDK are still supported in CC 2015.5.

New for Creative Cloud - CC 2015 - Photoshop 16.0

propGuideColor - The color of a guide line. All guides have the same color.

propGuideCount - The number of guide lines in the document.

propGuideDirIsHoriz - Is the guide with the given index horizontal.

propGuideCoordinate - The horizontal or vertical coordinate (as a double) of the guide by index.

New function in Progress Suite - Progress_DoForcedProgress - Performs the task defined by proc within a new progress scope. Forces the progress bar to display always and immediately, ignoring the normal heuristics that keep it from showing unnecessarily (e.g. during very short tasks). Call the task APIs to control progression of the progress bar.

New function in PSActionControlProcs - AddNotifyLevel1 - Allows the plug-in to provide a notification routine for specific events at playLevel 1. Notifications requested with AddNotify are delivered only when they occur at the same playLevel at which the notification was requested. Notifications requested with AddNotifyLevel1 are delivered only when they occur at playLevel 1, no matter which playLevel they were requested at. Any one event can only dispatch to one notifier routine per plug-in, but one notifier routine can receive multiple events. Use eventAll to dispatch all events to a single notifier routine.

New suite ASZStringSuite2 in ASZStringSuite.h that adds UTF8 string functions.

New PiPL properties

LoadWithAlteredSearchPath - The following property is used only on Windows. When on, the plug-in loader will load the plug-in dll using the altered search path.

FormatFileSizeLimit - Tells Photoshop the maximum file size the file format can read and write. Photoshop default is 2 gigabytes.

New for Creative Cloud - CC 2014 - Photoshop 15.0

Microsoft Visual Studio 2012, Update 4, 32 and 64 bit builds.

propZoomWithScrollWheel - Preference setting for how the scrool wheel is configured. Zoom with Scroll Wheel, 0 = off, use alt key to zoom, 1 = on, mouse scroll wheel does zoom. Use this to configure proxy preview behavior the same as Photoshop.

propInterpolationMethod - Correction to the meaning of the number when reading this property. 1 = nearest neighbor, 2 = bilinear, 3 = bicubic, 4 = bicubic smoother, 5 = bicubic sharper, 6 = bicubic automatic.

New for Creative Cloud - CC - Photoshop 14.0

propRecordInProgress - This property reflects the current state of the actions panel. Is the application recording at this point.

propHDPIAware - This property reflects the host applications is currently in High DPI and any dialog created by a plug-in should also be High DPI aware.

New for CS6 - Photoshop 13.0

Photoshop is now running native on 64 bit processors ONLY on Macintosh OS X. Photoshop plug-ins built for 32 bit processors will not load in Photoshop CS6. Please see the example projects for 64 bit build settings.

It is recommended that you use the same build settings for your project.

Photoshop CS6 has new API's for accessing large amounts of data. Although it is not recommended to request large amounts of memory, some algorithms require the entire image. Use the following routines:

PIBufferSuite.h
 - New64
 - GetSize64
 - GetSpace64
PIGeneral.h BufferProcs
 - AllocateBufferProc64
 - BufferSpaceProc64

For BufferProcs usage make sure to check the value of numBufferProcs and also check routines for NULL before accessing them. This will allow runtime checks when running on older versions of Photoshop.

ReadImageDocumentDesc has a new property of SPPlatformFileSpecificationW *fileSpecW. This allows for proper access of files with unicode characters. The SPPlatformFileSpecification_t *fileSpec is now deprecated.

FilterRecord has two new properties to access the current working profile information for the document. iCCWorkingProfileData and iCCWorkingProfileSize. Use this information along with iCCprofileData and iCCprofileSize to color convert if a plug-in is not using the displayPixels routine.

Photoshop CS6 now supports background save of documents. A Format plug-in can save a file out on a separate background thread. This property key reflects the SupportsBackgroundSave property in the PiPL resource file. Formats that rely on Globals, Mac resource manager, or show UI after the formatSelectorWriteStart entry should not allow background save. A format plug-in could be called to read a file on main thread while a file is being saved in the background thread. PIFmtSupportsBackgroundSaveProperty

Automation plug-ins that listen to the save event are now going to receive two events when Photoshop is doing a background save. The first event is when the saving starts. The second event is when the saving ends. If a document is in the middle of a background save and the user saves again, the listener plug-in would see two starts and two ends. If a third save is started the second and third save will be consolidated into one and the listener plug-in would see three starts and two ends. Only the user can abort a save in progress. A listener will have to take this into account as you may receive more starts than ends.

Four new properties in PIProperties.h

propScratchVolumeList - Photoshop scratch disk volumes. A list of 4-byte volume index that users have picked as preferred scratch volumes. On windows, this index is 1 based, started from "A:", so "C:" drive will be 3, "G:" will be 7, etc.

propGPUFlags - This property reflects the current state of the GPU card and the users settings in Preferences. Use this to determine the GPU usage in a plug-in.

propVRAM_MB - This returns the available VRAM in units of 1024*1024.

propLayerIsSmart - Use this property to tell if the current layer is a smart object layer.

New for CS5 - Photoshop 12.0

Photoshop is now running native on 64 bit processors on Macintosh OS X. See more information about making 64 bit plug-ins for Macintosh OS X see the example projects for build settings.

New for CS4 - Photoshop 11.0

Photoshop is now running native on 64 bit processors on Windows Vista. See more information about making 64 bit plug-ins for Windows Vista see the example projects for build settings.

New for CS3 - Photoshop 10.0

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

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 later 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.

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

See Details of tools used to build Photoshop and the SDK examples for information about versions of build tools used to make Photoshop and the SDK examples.

Microsoft Visual Studio

See Details of tools used to build Photoshop and the SDK examples for information about versions of build tools used to make Photoshop and the SDK examples.

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.