Buffer Suite Callbacks (deprecated Standard Suite)

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

Buffer Suite Callbacks
//end defgroup
typedef MACPASCAL OSErr(*	AllocateBufferProc )(int32 size, BufferID *bufferID)
	Sets bufferID to be the ID for a buffer of the requested size.
typedef MACPASCAL OSErr(*	AllocateBufferProc64 )(int64 size, BufferID *bufferID)
	Sets bufferID to be the ID for a buffer of the requested size.
typedef MACPASCAL Ptr(*	LockBufferProc )(BufferID bufferID, Boolean moveHigh)
	Returns a pointer to the beginning of the buffer.
typedef MACPASCAL void(*	UnlockBufferProc )(BufferID bufferID)
	Has no effect.
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.
typedef MACPASCAL int64(*	BufferSpaceProc64 )(void)
	Returns the amount of space available for buffers.
typedef MACPASCAL OSErr(*	ReserveSpaceProc )(int32 size)
	Attempts to insure that the requested amount of space is available as a single contiguous block in the address space.

---

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:

    FilterRecord *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 = 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);
    }

---

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-ins benefit, such as the continue calls to Filter and Export plug-ins.

typedef MACPASCAL OSErr(* AllocateBufferProc64)(int64 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)

Returns a pointer to the beginning of the buffer.

Parameters:

bufferID	The ID of the buffer to lock.
moveHigh	Has no effect.

typedef MACPASCAL void(* UnlockBufferProc)(BufferID bufferID)

Has no effect.

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.

typedef MACPASCAL int64(* BufferSpaceProc64)(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.

typedef MACPASCAL OSErr(* ReserveSpaceProc)(int32 size)

Attempts to insure that the requested amount of space is available as a single contiguous block in the address space.

The very first allocation of any kind after calling this routine can cut the available contiguous space by an arbitrary amount, and it's hard to guarantee that nothing else does any allocations until you do. THIS IS A NOP WHEN CALLED IN THE 64 BIT VERSION because there's always contiguous address space available