Channel Ports Suite Callbacks (deprecated Standard Suite)

The standard Channel Ports Suite has been deprecated, please use the Channel Ports Suite Callbacks See PIChannelPortsSuite.h. More...

Data Structures
struct	PixelMemoryDesc
	Describes an area of memory as pixels. More...
struct	PSScaling
	Provide a scaling through a rectangle in source space and a corresponding rectangle in destination space. More...
struct	WriteChannelDesc
	The channel to write a selection to. More...
struct	ReadChannelDesc
	A channel to read from. More...
struct	ReadLayerDesc
	A layer to read. More...
struct	ReadImageDocumentDesc
	The document information, used by the Export, Filter, and Selection module parameter blocks. More...
struct	ChannelPortProcs
	The set of routines available for teh Channel Ports Suite. More...
Defines
#define	kCurrentMinVersWriteChannelDesc   0
	Current minimum version of WriteChannelDesc.
#define	kCurrentMaxVersWriteChannelDesc   1
	Current maximum version of WriteChannelDesc.
#define	kCurrentMinVersReadChannelDesc   0
	Current minimum version of ReadChannelDesc.
#define	kCurrentMaxVersReadChannelDesc   5
	Current maximum version of ReadChannelDesc.
#define	kCurrentMinVersReadLayerDesc   0
	Current minimum version of ReadLayerDesc.
#define	kCurrentMaxVersReadLayerDesc   3
	Current maximum version of ReadLayerDesc.
#define	kCurrentMinVersReadImageDocDesc   0
	Current minimum version of the ReadImageDocumentDesc.
#define	kCurrentMaxVersReadImageDocDesc   6
	Current maximum version of the ReadImageDocumentDesc.
#define	kCurrentChannelPortProcsVersion   1
	Current version of the Channel Ports Suite.
#define	kPIChannelPortSuite   "Photoshop Channel Ports Suite for Plug-ins"
#define	kPIChannelPortSuiteVersion   kCurrentChannelPortProcsVersion
#define	kCurrentChannelPortProcsCount   ((sizeof(ChannelPortProcs) - offsetof(ChannelPortProcs, readPixelsProc)) / sizeof(void *))
	Current number of routines in the Channel Ports Suite.
Typedefs
typedef struct PixelMemoryDesc	PixelMemoryDesc
	Describes an area of memory as pixels.
typedef struct PSScaling	PSScaling
	Provide a scaling through a rectangle in source space and a corresponding rectangle in destination space.
typedef struct _PIChannelPortDesc *	PIChannelPort
	Access to internal channels though abstract types.
typedef PIChannelPort	ChannelReadPort
	Channel read port.
typedef PIChannelPort	ChannelWritePort
	Channel write port.
typedef struct WriteChannelDesc	WriteChannelDesc
	The channel to write a selection to.
typedef struct ReadChannelDesc	ReadChannelDesc
	A channel to read from.
typedef struct ReadLayerDesc	ReadLayerDesc
	A layer to read.
typedef struct ReadImageDocumentDesc	ReadImageDocumentDesc
	The document information, used by the Export, Filter, and Selection module parameter blocks.
typedef struct ChannelPortProcs	ChannelPortProcs
	The set of routines available for teh Channel Ports Suite.
Channel Ports Suite Callbacks
typedef MACPASCAL OSErr(*	ReadPixelsProc )(ChannelReadPort port, const PSScaling *scaling, const VRect *writeRect, const PixelMemoryDesc *destination, VRect *wroteRect)
	Reads a rectangular area (tile) of pixels from a read port, and writes them to a destination buffer, based on a scaling and a description of the memory to write.
typedef MACPASCAL OSErr(*	WriteBasePixelsProc )(ChannelWritePort port, const VRect *writeRect, const PixelMemoryDesc *source)
	Writes a rectangular area (tile) of pixels to a given port based on a memory description.
typedef MACPASCAL OSErr(*	ReadPortForWritePortProc )(ChannelReadPort *readPort, ChannelWritePort writePort)
	Returns the read port corresponding to a write port.

---

Detailed Description

The standard Channel Ports Suite has been deprecated, please use the Channel Ports Suite Callbacks See PIChannelPortsSuite.h.

Channel Ports are access points for reading and writing data from Photoshop internal selection data structures. There are two types of ports: read ports and write ports. You can retrieve a read port corresponding to a write port, but you cannot retrieve a write port from a read port. The API does allow for write-only ports, although none exist as of this version of the suite. These structures are used to get at merged pixel information, such as iterating through the merged data of the current layer or entire document, to be able to return a selection or use for a preview proxy.

For more information, please see Selection Module, especially see selectionSelectorExecute.

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

    DLLExport MACPASCAL void PluginMain (const int16 selector,
                                         ExportRecordPtr exportParamBlock,
                                         intptr_t* data,
                                         int16* result)
    {
            ...

            // Get the Channel Ports Suite from the parameter block
            ChannelPortProcs *channelPortsSuite = 
                    exportParamBlock->channelPortProcs;

            // Call the readPixelsProc routine.  
            channelPortsSuite->readPixelsProc(...);
            ...
    }

---

Define Documentation

#define kCurrentMinVersWriteChannelDesc   0

Current minimum version of WriteChannelDesc.

#define kCurrentMaxVersWriteChannelDesc   1

Current maximum version of WriteChannelDesc.

#define kCurrentMinVersReadChannelDesc   0

Current minimum version of ReadChannelDesc.

#define kCurrentMaxVersReadChannelDesc   5

Current maximum version of ReadChannelDesc.

#define kCurrentMinVersReadLayerDesc   0

Current minimum version of ReadLayerDesc.

#define kCurrentMaxVersReadLayerDesc   3

Current maximum version of ReadLayerDesc.

#define kCurrentMinVersReadImageDocDesc   0

Current minimum version of the ReadImageDocumentDesc.

#define kCurrentMaxVersReadImageDocDesc   6

Current maximum version of the ReadImageDocumentDesc.

#define kCurrentChannelPortProcsVersion   1

Current version of the Channel Ports Suite.

#define kPIChannelPortSuite   "Photoshop Channel Ports Suite for Plug-ins"

Unique identifier for the Channel Ports Suite.

#define kPIChannelPortSuiteVersion   kCurrentChannelPortProcsVersion

Version number for the Channel Ports Suite.

#define kCurrentChannelPortProcsCount   ((sizeof(ChannelPortProcs) - offsetof(ChannelPortProcs, readPixelsProc)) / sizeof(void *))

Current number of routines in the Channel Ports Suite.

---

Typedef Documentation

typedef struct PixelMemoryDesc PixelMemoryDesc

Describes an area of memory as pixels.

typedef struct PSScaling PSScaling

Provide a scaling through a rectangle in source space and a corresponding rectangle in destination space.

Equal rectangles result in a direct, unscaled, mapping. Unequal rectangles can be used to up- or down-sample.

For example, if sourceRect is a 100-pixel square in source space:

sourceRect.top = 0;  sourceRect.left = 0;
sourceRect.bottom = 100;  sourceRect.right = 100;

and destinationRect is a 50-pixel square in destination space:

destinationRect.top = 0;  destinationRect.left = 0;
destinationRect.bottom = 50;  destinationRect.right = 50;

the scaling indicates to down-sample the image by half.

typedef struct _PIChannelPortDesc* PIChannelPort

Access to internal channels though abstract types.

typedef PIChannelPort ChannelReadPort

Channel read port.

typedef PIChannelPort ChannelWritePort

Channel write port.

typedef struct WriteChannelDesc WriteChannelDesc

The channel to write a selection to.

typedef struct ReadChannelDesc ReadChannelDesc

A channel to read from.

typedef struct ReadLayerDesc ReadLayerDesc

A layer to read.

A layer is a collection of lists of read channels.

typedef struct ReadImageDocumentDesc ReadImageDocumentDesc

The document information, used by the Export, Filter, and Selection module parameter blocks.

Describes the document as a collection of channels and layers. The host provides a read port for each channel, so the pixel data can be read by using ReadPixelsProc in the Channel Ports Suite Callbacks (deprecated Standard Suite).

typedef MACPASCAL OSErr(* ReadPixelsProc)(ChannelReadPort port, const PSScaling *scaling, const VRect *writeRect,const PixelMemoryDesc *destination, VRect *wroteRect)

Reads a rectangular area (tile) of pixels from a read port, and writes them to a destination buffer, based on a scaling and a description of the memory to write.

First, the destination space rectangle, provided in scaling, is projected back to the source space. Then the overlap with the channel read port is copied to a specified memory buffer.

Parameters:

port	The channel port to read from.
scaling	A scaling between source and destination rectangles.
writeRect	The rectangular area (or tile) of the port to read. Usually this is the same as the rectangle specified in scaling.sourceRect.
destination	A description of the memory to write. The pixels read from the port are written into the memory buffer provided by destination.data
wroteRect	[OUT] The rectangular area (tile) in the destination space that was actually written. If the plug-in reads an area that fits entirely within the channel, this matches the scaling.destinationRect. If the plug-in reads an area that doesn't fit entirely within the channel, the destination pixels without corresponding source pixels won't be written to the destination.data buffer, and wroteRect reflects the actual area written.

Returns:

An error upon failure.

typedef struct ChannelPortProcs ChannelPortProcs

The set of routines available for teh Channel Ports Suite.

typedef MACPASCAL OSErr(* WriteBasePixelsProc)(ChannelWritePort port, const VRect *writeRect, const PixelMemoryDesc *source)

Writes a rectangular area (tile) of pixels to a given port based on a memory description.

This callback does not support scaling. If the rectangle maps to any pixels beyond the bounds of the port, they will not be written.

Parameters:

port	The channel write port.
writeRect	[IN/OUT] As input, provides the rectangular area (tile) of source.data the pixels are written from. As output, reflects the area of the port actually written. If the input rectangle maps to pixels beyond the bounds of the port, the output rectangle reflects the area actually written.
source	A description of the memory to write. The actual pixels that are written to the port are provided in source.data.

Returns:

An error upon failure.

typedef MACPASCAL OSErr(* ReadPortForWritePortProc)(ChannelReadPort *readPort, ChannelWritePort writePort)

Returns the read port corresponding to a write port.

Parameters:

readPort	[OUT] The read port.
writePort	The write port for which to retrieve the corresponding read port.

Returns:

An error upon failure.