Filter Module

Filter plug-in modules modify a selected area of an image, and are accessed under the Filter menu. More...

Data Structures
struct	FilterRecord
	This structure is passed to the plug-in module through the parameter block. More...
Typedefs
typedef struct FilterRecord	FilterRecord
	This structure is passed to the plug-in module through the parameter block.
typedef struct FilterRecord *	FilterRecordPtr
Filter Module Selectors
#define	filterSelectorAbout   0
	Allows the plug-in to display an about box for the Export Module.
#define	filterSelectorParameters   1
	Provides a means for the plug-in to prompt the user for any user-settable parameters.
#define	filterSelectorPrepare   2
	Allows your plug-in module to adjust the Photoshop memory allocation algorithm.
#define	filterSelectorStart   3
	Provides a means for your plug-in to validate the parameters block, update the parameters based on the passed scripting parameters, show its user interface, if requested, and then drop into its processing routine.
#define	filterSelectorContinue   4
	Continually processes plug-in data as long as it is available.
#define	filterSelectorFinish   5
	Allows the plug-in to clean up after a filtering operation.
Error Return Values
#define	filterBadParameters   -30100
	The filter module had a problem with the filter module interface.
#define	filterBadMode   -30101
	The filter module does not support <mode> images.

---

Detailed Description

Filter plug-in modules modify a selected area of an image, and are accessed under the Filter menu.

The file type for filter modules for Mac OS is 8BFM, the extension for Windows is .8BF.

Please also see Writing Filter Plug-ins.

---

Define Documentation

#define filterSelectorAbout   0

Allows the plug-in to display an about box for the Export Module.

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 filterBadParameters   -30100

The filter module had a problem with the filter module interface.

#define filterSelectorParameters   1

Provides a means for the plug-in to prompt the user for any user-settable parameters.

The plug-in should save the parameter values provided by the user in a relocatable memory block whose handle is stored in FilterRecord::parameters.

For further information, see Working with Filter Parameters.

#define filterSelectorPrepare   2

Allows your plug-in module to adjust the Photoshop memory allocation algorithm.

The Last Filter command initially executes this selector call first.

Photoshop sets maxSpace64 to the maximum number of bytes it can allocate to your plug-in. You may want to reduce maxSpace64 for increased efficiency.

If your plug-in filter module plans on allocating any large buffers or tables over 32k, it should set the bufferSpace64 field to the number of bytes it plans to allocate. Photoshop then tries to free up that amount of memory before calling the plug-in’s filterSelectorStart handler.

Alternatively, the plug-in can set this field to zero and use the Buffer Suite Callbacks and Handle Suite Callbacks if they are available. See Memory Management Strategies for a discussion on maxSpace64 and bufferSpace64.

The fields BigDocumentStruct::imageSize32, FilterRecord::planes, and BigDocumentStruct::filterRect32 can be used in computing your buffer size requirements.

#define filterSelectorStart   3

Provides a means for your plug-in to validate the parameters block, update the parameters based on the passed scripting parameters, show its user interface, if requested, and then drop into its processing routine.

The plug-in should set BigDocumentStruct::inRect32 and BigDocumentStruct::outRect32 to request the first areas of the image to work on. It should also set BigDocumentStruct::maskRect32 if it is using the selection mask. See Processing the Image for information about tiling the image.

If the plug-in does not use AdvanceStateProc, then it should initialize processing and set-up the first chunk of image to be manipulated in filterSelectorContinue. See Advance State and Filter Modules for further information.

#define filterSelectorContinue   4

Continually processes plug-in data as long as it is available.

The plug-in is called repeatedly with this selector as long as at least one of the FilterRecord::inRect, BigDocumentStruct::inRect32, FilterRecord::outRect, BigDocumentStruct::outRect32, FilterRecord::maskRect, or BigDocumentStruct::maskRect32 fields is not empty. The handler should process the data and then update the fields to request the next area of the image to process.

Note:

Photoshop might call filterSelectorFinish instead of filterSelectorContinue is it detects a need to terminate while fulfilling a request.

Be careful processing user-cancel events during filterSelectorContinue. Normally the plug-in would be expecting another filterSelectorContinue call. If the user cancels, the next call is filterSelectorFinish, not filterSelectorContinue!

#define filterSelectorFinish   5

Allows the plug-in to clean up after a filtering operation.

This call is made if and only if the filterSelectorStart handler returns without error, even if the filterSelectorContinue routine returns an error. If filterSelectorStart succeeds, Photoshop guarantees that filterSelectorFinish is called.

If Photoshop detects Command-period in the Mac OS or Escape in Windows between calls to the filterSelectorContinue routine, it calls the plug-in with filterSelectorFinish.

#define filterBadMode   -30101

The filter module does not support <mode> images.

---

Typedef Documentation

typedef struct FilterRecord FilterRecord

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 FilterRecord * FilterRecordPtr