Selection Module

Selection modules modify which pixels are chosen in an existing image and can return either path or pixel selections. More...

Data Structures
struct	PISelectionParams
	This structure is passed to the plug-in module through the parameter block. More...
Typedefs
typedef struct PISelectionParams	PISelectionParams
	This structure is passed to the plug-in module through the parameter block.
typedef struct PISelectionParams *	SelectionRecordPtr
Selection Module Selectors
#define	selectionSelectorAbout   0
	Allows the plug-in to display an about dialog box.
#define	selectionSelectorExecute   1
	Allows the plug-in to execute the selection handler.
Selection Error Return Values
#define	selectionBadParameters   -30700
	A problem with the selection module interface.
#define	selectionBadMode   -30701
	The selection module does not support <mode> images.

---

Detailed Description

Selection modules modify which pixels are chosen in an existing image and can return either path or pixel selections.

These modules appear under the Select menu.

The file type for selection modules for Mac OS is 8BSM, the extension for Windows is .8BS.

Please also see Writing Selection Plug-ins.

---

Define Documentation

#define selectionSelectorAbout   0

Allows the plug-in to display an about dialog box.

For this selector, the host does not pass the standard parameter block into the plug-in main routine. Instead it passes an AboutRecord.

See About Boxes for more information.

#define selectionBadParameters   -30700

A problem with the selection module interface.

#define selectionSelectorExecute   1

Allows the plug-in to execute the selection handler.

Unlike most other plug-in modules, a Selection plug-in gets a single call from the host, and it is expected to do all the work during that call. However, it is recommended that it follow this order:

1. Prompt for Parameters
   If the plug-in has any parameters that the user can set, it should prompt the user and save the values. For additional information, see Working with Selection Parameters.
2. Allocate Memory
   Use the buffer and handle suites to allocate any extra memory needed for your computations. Please see Memory Management Strategies.
3. Begin the main loop
   The host provides the document to read in PISelectionParams::documentInfo. Using this reference, the plug-in can retrieve the read channels (ReadChannelDesc) in the document. Since this is a selection plug-in, most likely the plug in needs to read documentInfo->selection, which represents the current selection.
   
   From this read channel, the plug-in can determine the read port (ReadChannelDesc::port) associated with the selection. The plug-in should use one of the channel ports suites to request an area (or tile) of the image to read.
   
   With the Channel Ports Suite Callbacks use PSChannelPortsSuite1::ReadPixelsFromLevel(), or PSChannelPortsSuite1::ReadScaledPixels(). With the Channel Ports Suite Callbacks (deprecated Standard Suite), use ChannelPortProcs::readPixelsProc().
   
   If at all possible, the plug-in should process the image in pieces (tiles) to minimize memory requirements. Unless there is a lot of startup/shutdown overhead on each call (for example, communicating with an external DSP), tiling the image with rectangles measuring 64x64 to 128x128 seems to work fairly well.
4. Modify, write the results, continue until done
   Make your adjustments to the image, and write out the pixel data into PISelectionParams::newSelection using one of the channel ports suites. This member points to a WriteChannelDesc, in which the host provides the write port to write to, in WriteChannelDesc::port.
   
   With the Channel Ports Suite Callbacks, use PSChannelPortsSuite1::WritePixelsToBaseLevel(). With the Channel Ports Suite Callbacks (deprecated Standard Suite), use ChannelPortProcs::WriteBasePixelsProc(). The plug-in should continue looping until it has implemented the entire selection or path.
5. Clean up
   Clean up after the operation. Dispose any handles created, etc.
   
   For additional information about using selection selectors, see Writing Selection Plug-ins.

#define selectionBadMode   -30701

The selection module does not support <mode> images.

---

Typedef Documentation

typedef struct PISelectionParams PISelectionParams

This structure is passed to the plug-in module through the parameter block.

See Plug-in Entry Point for an explanation of how the host calls a plug-in.

typedef struct PISelectionParams * SelectionRecordPtr