Getting started

Download the SDK

Begin by downloading the UXP Hybrid plugin SDK from Developer Console (here is what to do if you get “Access Denied”). Unpack the contents and make sure you check out the README.md. There are special instructions for building and packaging a hybrid plugins since they are different from a standard UXP plugin.

The concept of a hybrid plugin is very similar to Node.js C++ Addons. The dynamically linked shared objects written in C++ are available to JavaScript. template-dev walks you through a very basic example that illustrates how the two worlds communicate.

Samples

Try the ready-to-use template-plugin provided within the SDK to say a quick ‘Hello world!’. Load the template via UDT, and find it under the Plugins menu.

The binaries in the template-plugin are not code signed. In macOS, please go to ‘Security & Privacy’ in your System Preferences to allow them to load and work properly.

Debug

UXP Hybrid plugin has both - JavaScript and C++. Use the UDT Debug tool for setting breakpoints for JavaScript.

For debugging C++ code, you must attach to the Photoshop.exe process via the IDE. In most IDEs you can find that option under Debug -> Attach to Process.

However, in macOS you have to perform a prior step. Follow the guide to debug in macOS.

Known Issues

While loading your plugin via the UDT, it may not show your plugin in Photoshop automatically. Uncheck and check the plugin name from the ‘Plugin’ menu item to launch it. The fix for this is expected in a future macOS release.

File system access

With the hybrid plugins, we have relaxed the UXP sandbox restrictions. You can access the file system in the following way:

let entry = '/path/to/target.psd';
document.saveAs.psd(entry);
Copied to your clipboard
let entry = '/path/to/target.psd';
document.saveAs.psd(entry);

This is opposed to a standard UXP plugin’s method of accessing the file system:

let entry = await require('uxp').storage.localFileSystem.getFileForSaving("target.psd");
document.saveAs.psd(entry);
Copied to your clipboard
let entry = await require('uxp').storage.localFileSystem.getFileForSaving("target.psd");
document.saveAs.psd(entry);

Photoshop C++ SDK

Photoshop offers a number of C based plugin APIs. These are documented in the downloadable package. A hybrid plugin can get access to these APIs by exposing an additional function entry point.

export SPErr PSDLLMain(const char* selector, SPBasicSuite* basicSuite, PIActionDescriptor descriptor);
Copied to your clipboard
export SPErr PSDLLMain(const char* selector, SPBasicSuite* basicSuite, PIActionDescriptor descriptor);

After Photoshop loads a hybrid addOn, it will invoke this method. The basicSuite argument can be used to obtain Photoshop API suites. See the C++ SDK for information about how to acquire Photoshop suites.

Sample code:

To test this, you can add the following to module.cpp from the hybrid plugin sample:

// Photoshop SDK includes (add path to project)
#include "SPBasic.h"
#include "PIColorSpaceSuite.h"

. . .

// ----------------------------------------------------------------------------------------------------
static const SPBasicSuite* gBasicSuite = nullptr;
static const PSColorSpaceSuite2* gColorSpaceSuite = nullptr;

extern "C" UXP_EXTERN_API_STDCALL(SPErr) PSDLLMain(const char* selector, SPBasicSuite* spBasic, void*)
try {
  do {
    if (spBasic == nullptr)
    break;

    // cache the basic suite so we can use at any time
    gBasicSuite = spBasic;

    SPErr spErr = gBasicSuite->AcquireSuite(kPSColorSpaceSuite, kPSColorSpaceSuiteVersion, reinterpret_cast<const void**>(&gColorSpaceSuite));
    if (spErr != kSPNoError)
    break;

    if (gColorSpaceSuite == nullptr)
    break;

    Color8 colorArray[1] = {11, 30, 201, 0};
    spErr = gColorSpaceSuite->Convert8(plugIncolorServicesRGBSpace, plugIncolorServicesCMYKSpace, colorArray, 1);
    if (spErr != kSPNoError) break;
  } while (false);

  return kSPNoError;
}
  catch(...) {
  return -1;
}
Copied to your clipboard
// Photoshop SDK includes (add path to project)
#include "SPBasic.h"
#include "PIColorSpaceSuite.h"

. . .

// ----------------------------------------------------------------------------------------------------
static const SPBasicSuite* gBasicSuite = nullptr;
static const PSColorSpaceSuite2* gColorSpaceSuite = nullptr;

extern "C" UXP_EXTERN_API_STDCALL(SPErr) PSDLLMain(const char* selector, SPBasicSuite* spBasic, void*)
try {
  do {
    if (spBasic == nullptr)
    break;

    // cache the basic suite so we can use at any time
    gBasicSuite = spBasic;

    SPErr spErr = gBasicSuite->AcquireSuite(kPSColorSpaceSuite, kPSColorSpaceSuiteVersion, reinterpret_cast<const void**>(&gColorSpaceSuite));
    if (spErr != kSPNoError)
    break;

    if (gColorSpaceSuite == nullptr)
    break;

    Color8 colorArray[1] = {11, 30, 201, 0};
    spErr = gColorSpaceSuite->Convert8(plugIncolorServicesRGBSpace, plugIncolorServicesCMYKSpace, colorArray, 1);
    if (spErr != kSPNoError) break;
  } while (false);

  return kSPNoError;
}
  catch(...) {
  return -1;
}