Getting Started

SDK API Reference

SDK API Features

Other Documentation

Buffer Suite Callbacks (DEPRECATED Standard Suite)

Detailed Description

The standard Buffer Suite is DEPRECATED, please use the Buffer Suite Callbacks defined with the Adobe Plug-in Component Architecture (PICA).

The Buffer suite provides an alternative to the memory management functions available in previous versions of the Photoshop plug-in specification. It provides a set of routines to request that the host allocate and dispose of memory out of a pool which it manages.

For most types of plug-ins, buffer allocations can be delayed until they are actually needed. Unfortunately, Export modules must track the buffer for the data requested from the host even though the host allocates the buffer. This means that the Buffer suite routines do not provide much help for Export modules.

For more information, please see Memory Management Strategies.

The standard Buffer Suite is found as a pointer in the parameter blocks of the plug-in modules. You can access the routines within the Buffer Suite in the following manner: 

    FilterRecordPtr gFilterRecord = NULL;   

    DLLExport MACPASCAL void PluginMain(const int16 selector,
                                        FilterRecordPtr filterRecord,
                                        intptr_t * data,
                                        int16 * result)
    {
      // The parameter block that contains the suite is found in filterRecord. 
      gFilterRecord = (FilterRecordPtr)filterRecord;
      ...
    }

    // This function uses two of the Buffer Suite routines
    void CreateDissolveBuffer(const int32 width, const int32 height)
    {
        // Get the Buffer Suite from the parameter block
        BufferProcs *bufferProcs = gFilterRecord->bufferProcs;

        // Call the allocateProc routine from the Buffer Suite to allocate
        // the space needed for the buffer (gdata->dissolveBufferID)
        bufferProcs->allocateProc(width * height, &gData->dissolveBufferID);

        // Call the lockProc routine to lock the memory
        gData->dissolveBuffer = bufferProcs->lockProc(gData->dissolveBufferID, true);
    }


Data Structures

struct  BufferProcs
 The set of routines available in the Buffer Suite. More...

Buffer Suite Callbacks

typedef MACPASCAL OSErr(*) AllocateBufferProc (int32 size, BufferID *bufferID)
 Sets bufferID to be the ID for a buffer of the requested size.
typedef MACPASCAL Ptr(*) LockBufferProc (BufferID bufferID, Boolean moveHigh)
 Locks the buffer to a particular memory location and returns a pointer to the beginning of the buffer.
typedef MACPASCAL void(*) UnlockBufferProc (BufferID bufferID)
 Unlocks a buffer.
typedef MACPASCAL void(*) FreeBufferProc (BufferID bufferID)
 Releases the storage associated with a buffer.
typedef MACPASCAL int32(*) BufferSpaceProc (void)
 Returns the amount of space available for buffers.

Defines

#define kCurrentBufferProcsVersion   2
 Current version of the Buffer Suite.
#define kCurrentBufferProcsCount   ((sizeof(BufferProcs) - offsetof(BufferProcs, allocateProc)) / sizeof(void *))
 Current number of routines in the Buffer Suite.

Define Documentation

#define kCurrentBufferProcsVersion   2

Current version of the Buffer Suite.

#define kCurrentBufferProcsCount   ((sizeof(BufferProcs) - offsetof(BufferProcs, allocateProc)) / sizeof(void *))

Current number of routines in the Buffer Suite.

Typedef Documentation

typedef MACPASCAL OSErr(*) AllocateBufferProc(int32 size, BufferID *bufferID)

Sets bufferID to be the ID for a buffer of the requested size.

Parameters:
size The size of the buffer to allocate.
bufferID [OUT] The allocated buffer.
Returns:
noErr if allocation is successful; an error code if allocation is unsuccessful.
Note:
Buffers are identified by pointers to an opaque type called BufferID. Buffer allocation is more likely to fail during phases where other blocks of memory are locked down for the plug-in’s benefit, such as the continue calls to Filter and Export plug-ins.

typedef MACPASCAL Ptr(*) LockBufferProc(BufferID bufferID, Boolean moveHigh)

Locks the buffer to a particular memory location and returns a pointer to the beginning of the buffer.

Parameters:
bufferID The ID of the buffer to lock.
moveHigh On Mac OS, indicates whether you want the memory block moved to the high end of memory to avoid fragmentation. Has no effect with Photoshop for Windows.

typedef MACPASCAL void(*) UnlockBufferProc(BufferID bufferID)

Unlocks a buffer.

Buffer locking uses a reference counting scheme; a buffer may be locked multiple times, and only with the final balancing unlock call does it actually unlock.

Parameters:
bufferID The ID of the buffer to unlock.

typedef MACPASCAL void(*) FreeBufferProc(BufferID bufferID)

Releases the storage associated with a buffer.

Using bufferID after calling FreeBufferProc may cause Photoshop to crash.

Parameters:
bufferID The buffer to free.

typedef MACPASCAL int32(*) BufferSpaceProc(void)

Returns the amount of space available for buffers.

This space may be fragmented, so an attempt to allocate all of the space as a single buffer may fail.

Returns:
Available buffer space.