Buffer Suite Callbacks

The Buffer suite provides an alternative to the memory management functions available in previous versions of the Photoshop plug-in specification. More...

Data Structures
struct	PSBufferSuite1
	The set of routines available in Pica Buffer Suite Version 1. More...
struct	PSBufferSuite2
	The set of routines available in Pica Buffer Suite Version 1. More...
Defines
#define	kPSBufferSuite   "Photoshop Buffer Suite for Plug-ins"
	Unique identifier for the Buffer Suite.
#define	kPSBufferSuiteVersion1   1
	Current version of the buffer suite.
#define	kPSBufferSuiteVersion2   2
	64 bit version of the buffer suite.
#define	kPSBufferSuiteVersion   kPSBufferSuiteVersion2
	current version of the buffer suite.
Typedefs
typedef SPAPI Ptr(*	BufferNewProc )(unsigned32 *pRequestedSize, unsigned32 minimumSize)
	Attempts to allocate the number of bytes specified with the variable pointed to by the pRequestedSize parameter.
typedef SPAPI Ptr(*	BufferNewProc64 )(unsigned64 *pRequestedSize, unsigned64 minimumSize)
	Attempts to allocate the number of bytes specified with the variable pointed to by the pRequestedSize parameter.
typedef SPAPI void(*	BufferDisposeProc )(Ptr *ppBuffer)
	Disposes of the buffer and sets the variable that refers to it to NULL.
typedef SPAPI unsigned32(*	BufferGetSizeProc )(Ptr pBuffer)
	Gets the size of the buffer.
typedef SPAPI unsigned64(*	BufferGetSizeProc64 )(Ptr pBuffer)
	Gets the size of the buffer.
typedef SPAPI unsigned32(*	BufferGetSpaceProc )(void)
	Gets the amount of space available.
typedef SPAPI unsigned64(*	BufferGetSpaceProc64 )(void)
	Gets the amount of space available.

---

Detailed Description

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.

Accessing the Suite

The Buffer suite is referred to as:

  #define kPSBufferSuite            "Photoshop Buffer Suite for Plug-ins"

The current version of the Buffer suite:

  #define kPSBufferSuiteVersion1        1

The suite is acquired as follows:

  PSBufferSuite1 *sPSBuffer;
  error = sSPBasic->AcquireSuite(kPSBufferSuite,
                                 kPSBufferSuiteVersion1,      
                                 &sPSBuffer);
  if (error) goto . . . //handle error

For PICA errors, see SPErrorCodes.h.

---

Define Documentation

#define kPSBufferSuite   "Photoshop Buffer Suite for Plug-ins"

Unique identifier for the Buffer Suite.

#define kPSBufferSuiteVersion1   1

Current version of the buffer suite.

#define kPSBufferSuiteVersion2   2

64 bit version of the buffer suite.

#define kPSBufferSuiteVersion   kPSBufferSuiteVersion2

current version of the buffer suite.

---

Typedef Documentation

typedef SPAPI Ptr(* BufferNewProc)(unsigned32 *pRequestedSize,unsigned32 minimumSize)

Attempts to allocate the number of bytes specified with the variable pointed to by the pRequestedSize parameter.

If this many bytes cannot be allocated, then the largest possible number (greater than minimumSize) is allocated. Returns the number of bytes actually allocated in the pRequestedSize parameter.

Parameters:

pRequestedSize	[IN/OUT] The requested size for the new buffer. If NULL, minimumSize bytes are allocated. The actual buffer size allocated is also returned in this parameter.
minimumSize	The minimum size allowable for the buffer.

Returns:

A pointer to the new buffer; or NULL if minimumSize of bytes cannot be allocated.

typedef SPAPI Ptr(* BufferNewProc64)(unsigned64 *pRequestedSize,unsigned64 minimumSize)

Attempts to allocate the number of bytes specified with the variable pointed to by the pRequestedSize parameter.

If this many bytes cannot be allocated, then the largest possible number (greater than minimumSize) is allocated. Returns the number of bytes actually allocated in the pRequestedSize parameter.

Parameters:

pRequestedSize	[IN/OUT] The requested size for the new buffer. If NULL, minimumSize bytes are allocated. The actual buffer size allocated is also returned in this parameter.
minimumSize	The minimum size allowable for the buffer.

Returns:

A pointer to the new buffer; or NULL if minimumSize of bytes cannot be allocated.

typedef SPAPI void(* BufferDisposeProc)(Ptr *ppBuffer)

Disposes of the buffer and sets the variable that refers to it to NULL.

Does nothing if the buffer pointer is already NULL.

Parameters:

ppBuffer

The buffer to dispose of.

typedef SPAPI unsigned32(* BufferGetSizeProc)(Ptr pBuffer)

Gets the size of the buffer.

Parameters:

pBuffer

The buffer to get the size of.

Returns:

The size of the buffer; or zero if the buffer pointer is invalid.

typedef SPAPI unsigned64(* BufferGetSizeProc64)(Ptr pBuffer)

Gets the size of the buffer.

Parameters:

pBuffer

The buffer to get the size of.

Returns:

The size of the buffer; or zero if the buffer pointer is invalid.

typedef SPAPI unsigned32(* BufferGetSpaceProc)(void)

Gets the amount of space available.

This space may not be contiguous.

Returns:

The amount of remaining space available.

typedef SPAPI unsigned64(* BufferGetSpaceProc64)(void)

Gets the amount of space available.

This space may not be contiguous.

Returns:

The amount of remaining space available.