DOCSEARCHbyAlgolia
Submit Docs

psd_sdk

repository·master·Indexed 20 days ago

https://github.com/molecularmatters/psd_sdk

A C++ library for reading and partially writing Adobe Photoshop PSD files. It supports advanced features including smart objects, nested layers, groups, and various masking types (user, vector, transparency). The SDK handles 8-bit, 16-bit, and 32-bit data in grayscale and RGB modes, supports all Adobe Photoshop compression types, and provides an asynchronous I/O interface via the File class for Windows, macOS, and Linux.

Tokens
3.4K
Snippets
7
Records
17
Agent score
69%

What's inside psd_sdk

  1. Overview of psd_sdk capabilities

    master

    psd_sdk is a C++ library designed for directly reading Photoshop PSD files. It provides support for complex PSD features including:

    • Layering: Groups, nested layers, and Smart Objects.
    • Masking: User masks, vector masks, transparency masks, and additional alpha channels.
    • Color & Bit Depth: 8-bit, 16-bit, and 32-bit data in both grayscale and RGB color modes.
    • Compression: All compression types used by Adobe Photoshop.
    • Export: Limited functionality for exporting PSD data.

    For detailed product information, visit: https://molecular-matters.com/products_psd_sdk.html

  2. Project directory structure

    master

    The repository is organized into the following directories:

    • bin/: Contains a sample Photoshop PSD file used for testing and sample code.
    • build/: Contains Visual Studio project files and solutions for versions 2008 through 2019.
    • src/: Contains the core library source code and a sample application demonstrating how to read and write PSD files.

  3. Build and debug PsdSamples on macOS

    master

    When using Xcode to build and debug the PsdSamples command line utility, you must configure the working directory so the application can find the sample PSD file.

    1. In Xcode: Edit the current scheme's working directory and set it to the build/Xcode directory within your checked-out psd_sdk source code.
    2. Via Command Line: To run the binary directly from the terminal, copy the compiled binary to the build/Xcode directory before execution.

  4. Supported platforms and porting guidance

    master

    The SDK currently supports Windows, macOS, and Linux.

    Approximately 98% of the codebase is platform-independent. If you are porting the SDK to a new platform, you must address the following specific files:

    • PsdNativeFile.cpp: Implements the PsdFile interface; currently uses native Windows functions for asynchronous operations.
    • PsdEndianConversion.inl: Handles byte swapping using _byteswap_* or __builtin_bswap*. You may need to provide alternatives for compilers that do not support these intrinsic functions.
    • PsdCompilerMacros.h: Provides abstractions for compiler/preprocessor features (currently supports MSVC, Clang, and GCC).

  5. Use the File class for asynchronous I/O operations

    master

    The File class is the base interface for all file I/O operations in the psd_sdk. It is designed to provide full control over I/O, enabling the use of native platform-specific functions (such as asynchronous I/O).

    Key characteristics:

    • Asynchronous Design: The interface provides asynchronous Read and Write methods. This allows for parallelizing file accesses.
    • Resource Management: When performing asynchronous operations, the returned ReadOperation or WriteOperation handles must be passed to WaitForRead() or WaitForWrite() respectively to ensure resources are properly freed and the operation is completed.
    • File Access: Files must be opened using OpenRead or OpenWrite before performing operations like GetSize or reading/writing.

  6. Perform asynchronous reads and writes with the File class

    master

    To perform asynchronous I/O, use the Read and Write methods. You must subsequently call the corresponding WaitFor... method to synchronize and clean up resources.

    Read Operation

    1. Call Read(void* buffer, uint32_t count, uint64_t position).
    2. Capture the returned ReadOperation.
    3. Call WaitForRead(ReadOperation& operation) to wait for completion and release internal resources.

    Write Operation

    1. Call Write(const void* buffer, uint32_t count, uint64_t position).
    2. Capture the returned WriteOperation.
    3. Call WaitForWrite(WriteOperation& operation) to wait for completion and release internal resources.
    // Example of asynchronous read pattern
File file(allocator);
if (file.OpenRead(L"example.psd")) {
    void* buffer = /* allocated buffer */;
    uint32_t size = 1024;
    uint64_t pos = 0;

    File::ReadOperation op = file.Read(buffer, size, pos);
    
    // Do other work...

    if (file.WaitForRead(op)) {
        // Read successful
    }
    file.Close();
}

  7. File class API reference

    master

    The File class provides the following public interface for managing file access and I/O:

    MethodSignatureDescription
    Constructorexplicit File(Allocator* allocator)Initializes the file object with a provided allocator.
    Open Readbool OpenRead(const wchar_t* filename)Attempts to open a file for reading. Returns true if successful.
    Open Writebool OpenWrite(const wchar_t* filename)Attempts to open a file for writing. Returns true if successful.
    Closebool Close(void)Closes the file. Returns true if successful.
    ReadReadOperation Read(void* buffer, uint32_t count, uint64_t position)Asynchronously loads count bytes into buffer from position. Returns a ReadOperation handle.
    Wait for Readbool WaitForRead(ReadOperation& operation)Waits for the read operation to finish and deletes internal resources.
    WriteWriteOperation Write(const void* buffer, uint32_t count, uint64_t position)Asynchronously writes count bytes from buffer to position. Returns a WriteOperation handle.
    Wait for Writebool WaitForWrite(WriteOperation& operation)Waits for the write operation to finish and deletes internal resources.
    Get Sizeuint64_t GetSize(void) constReturns the file size in bytes. Returns 0 if the file is not open or the call fails.

    Types:

    • ReadOperation: A void* representing an object associated with a read operation.
    • WriteOperation: A void* representing an object associated with a write operation.

  8. Add and update metadata in a PSD document

    master

    You can attach metadata to a PSD document using AddMetaData and UpdateMetaData.

    • AddMetaData: Copies the provided name and value into the document. It returns an unsigned int index representing the metadata entry.
    • UpdateMetaData: Uses the index returned by AddMetaData to modify the existing name or value of a metadata entry.
    unsigned int metaIndex = AddMetaData(doc, allocator, "Author", "Molecular Matters");
UpdateMetaData(doc, allocator, metaIndex, "Author", "New Author Name");

  9. Add and update alpha channels

    master

    Alpha channels can be added to a document using AddAlphaChannel. This returns an index used to update the channel's data via UpdateChannel.

    AddAlphaChannel parameters:

    • name: Name of the channel.
    • r, g, b, a: Color components (16-bit).
    • opacity: Opacity value (16-bit).
    • mode: The alpha mode using AlphaChannel::Mode::Enum.

    UpdateChannel bit depths:

    • 8-bit: const uint8_t* data (size: width * height).
    • 16-bit: const uint16_t* data (size: width * height * 2).
    • 32-bit: const float32_t* data (size: width * height * 4).

    Note: UpdateChannel takes ownership of the data buffer.

    unsigned int alphaIdx = AddAlphaChannel(doc, allocator, "Mask", 0, 0, 0, 65535, 65535, AlphaChannel::Mode::None);
UpdateChannel(doc, allocator, alphaIdx, data8bit);

  10. Use SyncFileWriter for synchronous sequential writes

    master

    The SyncFileWriter class provides a synchronous wrapper around an existing File implementation. It is designed to simplify sequential write operations, such as writing file headers, by managing an internal write position and incrementing it automatically after each write.

    Requirements:

    • The File object passed to the constructor must already be open.
    • This class is intended for sequential writes where managing asynchronous operations would add unnecessary complexity.
    // Assuming 'file' is a pointer to an already open File object
SyncFileWriter writer(file);

// Write data synchronously
writer.Write(buffer, count);

// Check current write position
uint64_t pos = writer.GetPosition();

  11. Update merged image data

    master

    The UpdateMergedImage function allows you to set the flattened/merged view of the document. This is useful for ensuring the preview or the composite view is correct. The function takes ownership of the provided planar buffers.

    Supported Bit Depths:

    • 8-bit: const uint8_t* planarDataR, planarDataG, planarDataB (size: width * height per channel).
    • 16-bit: const uint16_t* planarDataR, planarDataG, planarDataB (size: width * height * 2 per channel).
    • 32-bit: const float32_t* planarDataR, planarDataG, planarDataB (size: width * height * 4 per channel).

  12. Set ICC profile, EXIF, and JPEG thumbnail data

    master

    To include embedded assets in the PSD, use the following functions:

    • SetICCProfile: Sets the ICC profile using rawProfileData and its size.
    • SetEXIFData: Sets the EXIF metadata using rawExifData and its size.
    • SetJpegThumbnail: Sets a JPEG thumbnail. Requires width, height, rawJpegData, and size.