Date: 07 May 93 16:12 GMT
From: ABRAHAM@AppleLink.Apple.COM (Ohlendorf Research,PAS) Subject: filter module ohlendorf
To: WAYNE@helix.nih.gov

Filter Module Interface for Adobe Photoshop(tm) 

(c)1990-91 Thomas Knoll

Introduction

This document describes version 4 of Adobe Photoshop's filter module interface. Plug-ins based on the following specifications should contain a 4 in their `PiMI' resource.

If the plug-in does not use the fields after the version 4 fields comment, it may choose to label itself a version 3.1 plug-in, to remain compatible with older versions of host software.

The code resource and file type for filter modules is `8BFM'. 

The resource name of the `PiMI' resource is uses at the filter category name by Photoshop. If this resource has no name, the filter is placed in the "Other" filter category.

Record Structure

The stuff parameter contains a pointer to a structure of the following type: 

FilterRecord = RECORD

serialNumber: LONGINT;
abortProc: ProcPtr;
progressProc: ProcPtr;
parameters: Handle;
imageSize: Point;
planes: INTEGER;
filterRect: Rect;
background: RGBColor;
foreground: RGBColor;
maxSpace: LONGINT;
bufferSpace:LONGINT;
inRect: Rect;
inLoPlane: INTEGER;
inHiPlane: INTEGER;
outRect:Rect;
outLoPlane: INTEGER;
outHiPlane: INTEGER;
inData: Ptr;
inRowBytes: LONGINT;
outData:Ptr;
outRowBytes:LONGINT;
isFloating: BOOLEAN;
haveMask: BOOLEAN;
autoMask: BOOLEAN;
maskRect: Rect;
maskData: Ptr;
maskRowBytes: LONGINT;

{ Version 4 fields }

backColor: FilterColor;
foreColor: FilterColor;
hostSig:OSType; hostProc: ProcPtr;imageMode: INTEGER;imageHRes: Fixed; imageVRes: Fixed;
floatCoord: Point; wholeSize: Point; monitor:FilterMonitor; 

reserved: PACKED ARRAY [0..255] OF CHAR; 

END;

FilterColor = PACKED ARRAY [0..3] OF CHAR; 

FilterMonitor = RECORD
gamma: Fixed; redX: Fixed; redY: Fixed;
greenX: Fixed; greenY: Fixed; blueX: Fixed; blueY: Fixed; whiteX: Fixe whiteY:Fixed;
ambient:Fixed; END;

Calling Order

When the user invokes the plug-in by selecting its name from the Filter submenu, Photoshop loads the plug-in's resource into memory and calls it with the following sequence of selector values (see the header file for their actual values):

(1) filterSelectorParameters

If the plug-in filter has any user set-able parameters, it should prompt the user and save the parameters in a relocatable memory block whose handle is stored in the parameters field. Photoshop initializes the parameters field to NIL when starting up.

This routine may or may not be called depending on how the user invokes the filter. Photoshop has a feature the repeats the most recent filtering operation using the current parameters, in which case this call is skipped. 

Since the same parameters can be used on different size images, the parameters should not depend on the size or mode of the image, or the size of the filtered area (these fields are not even defined at this point). 

A future version of Photoshop may have a macro processor which would save the block pointed to by the parameters field when recording, so that it can operate the filter without user input during play back. To be compatible with this possible feature, all parameters must be saved in a relocatable block whose handle is stored in the parameters field. 

(2) filterSelectorPrepare

If the plug-in is planning on allocating any large (>= about 32K) buffers or tables, it should set the bufferSpace field to the number of bytes it is planning to allocate. Photoshop will then try to free up that amount of memory before calling the plug-in's filterSelectorStart routine. 

The fields such as imageSize, planes, filterRect, etc. have now been defined, and can be used in computing the buffer size requirements. 

(3) filterSelectorStart

The plug-in should set inRect and outRect (and maskRect, if it is using the selection mask) to request the first areas of the image to work on. 

If at all possible, the plug-in should process the image in strips, to minimize memory requirements. The ideal case is to to process a single row at a time. 

(4) filterSelectorContinue

This routine is repeatedly called as long as at least one of the inRect , outRect, or maskRect
fields is non-empty.

This routine should processes the data pointed by inData and outData (as possibly maskData), and the update the inRect and outRect (and maskRect, if using the selection mask) to request the next area of the image to process. 

(5) filterSelectorFinish

This call allows the plug-in to clean up after a filtering operation. This call is made if and only if the filterSelectorStart routine returns without error (even if the filterSelectorContinue routine returns an error). 

If Photoshop detects a command-period between calls to the filterSelectorContinue routine, it will call the filterSelectorFinish routine (be careful here, since normally the plug-in would be expecting another filterSelectorContinue call).

Record Fields

(1) serialNumber

Contains Adobe Photoshop's serial number. Plug-in modules can use this value for copy protection, if desired.

(2) abortProc

Contains a pointer to a function with the following Pascal calling conventions: 

FUNCTION TestAbort: BOOLEAN;

The plug-in may call this function several times a second during long operations to allow the user to abort the operation. If the function returns TRUE, the operations should be aborted. As a side effect, this changes to cursor to a watch, and moves the watch hands periodically. 

(3) progressProc

Contains a pointer to a procedure with the following Pascal calling conventions:

PROCEDURE UpdateProgress (done, total: LONGINT); 

The plug-in may call this two-argument procedure periodically to update a progress indicator. The first parameter is the number of operations completed; the second is the total number of operations. 

This procedure should only be called during the actual main operation of the plug-in, not during long operations during the preliminary user interface. 

Photoshop automatically suppresses display of the progress graph during short operations.

(4) parameters

Photoshop initializes this handle to NIL at startup. If plug-in filter has any user set-able parameters, it should allocate a relocatable block in the filterSelectorParameters routine, store the parameters in the block, and store the block's handle in this field.

(5) imageSize

The image's width (imageSize.h) and height (imageSize.v) in pixels. If the selection is floating, this field instead holds the size of the floating selection.

(6) planes

For version 4 filters, this field contains the total number of active planes in the image, in including alpha channels. The image mode should be determined by looking at the imageMode field.

For pre-version 4 filters, this field will be equal to 3 if filtering the RGB "channel" of an RGB color image, or 4 if filtering the CMYK "channel" of a CMYK color image. Otherwise it will be equal to 1. 

(7) filterRect

The area of the image to be filtered. This is the bounding box of the selection, or if there is no selection, the bounding box of the image. If the selection is not a perfect rectangle, Photoshop automatically masks the changes to the area actually selected (unless the plug-in turns off this feature using the autoMask field). This allows most filters to ignore the selection mask, and still operate correctly.

(8) background and foreground

The current background and foreground colors. If planes is equal to 1, these will have already been converted to monochrome. (Obsolete: Use the backColor and foreColor fields.)

(9) maxSpace

This lets the plug-in know the maximum number of bytes of information it can expect to be able to access at once (input area size + output area size + mask area size + bufferSpace).

(10) bufferSpace

If the plug-in is planning on allocating any large internal buffers or tables, it should set this field during the filterSelectorPrepare call to the number of bytes it is planning to allocate. Photoshop will then try to free up the requested amount of space before calling the filterSelectorStart routine. 

(11) inRect

The plug-in should set this field in its filterSelectorStart and filterSelectorContinue routines to request access to an area of the input image. The area requested must be a subset of the image's bounding rectangle. 

After the entire filterRect has been filtered, this field should be set to an empty rectangle.

(12) inLoPlane and inHiPlane

The filterSelectorStart and filterSelectorContinue routines should set these fields to the first and last input planes to process next. 

(13) outRect

The plug-in should set this field in its filterSelectorStart and filterSelectorContinue routines to request access to an area of the output image. The area requested must be a subset of filterRect. 

After the entire filterRect has been filtered, this field should be set to an empty rectangle.

(14) outLoPlane and outHiPlane

The filterSelectorStart and filterSelectorContinue routines should set these fields to the first and last output planes to process next. 

(15) inData

This field contains a pointer to the requested input image data. If more than one plane has been requested (inLoPlane - inHiPlane), the data is interleaved. 

(16) inRowBytes

The offset between rows of the input image data. (There may or may not be pad bytes at the end of each row.)

(17) outData

This field contains a pointer to the requested output image data. If more than one plane has been requested (outLoPlane - outHiPlane), the data is interleaved.

(18) outRowBytes

The offset between rows of the output image data. (There may or may not be pad bytes at the end of each row.)

(19) isFloating

This field is set true if and only if the selection is floating. 

(20) haveMask

This field is set true if and only if a non-rectangular area has been selected. 

(21) autoMask

By default, Photoshop automatically masks any changes to the area actually selected. If isFloating is false, and haveMask is true, the plug-in can turn off this feature by setting this field to false. It can then perform its own masking.

(22) maskRect

If haveMask is true, and the plug-in needs access to the selection mask, it should set this field in its filterSelectorStart and filterSelectorContinue routines to request access to an area of the selection mask. The requested area must be a subset of filterRect. This field is ignored if there is no selection mask.

(23) maskData

A pointer to the requested mask data.

(24) maskRowBytes

The offset between rows of the mask data. 

(25) backColor and foreColor

The current background and foreground colors, in the color space native to the image.

(26) hostSig

The host program's signature. Photoshop's signature is `8BIM'. 

(27) hostProc

A host-defined callback procedure that can do anything the host wishes. Plug-ins should verify the hostSig before calling this procedure. This provides a mechanism for hosts to extend the plug-in interface to support application specific features.

(28) imageMode

The mode of the image being filtered (Gray Scale, RGB Color, etc.). See the header file for possible values. The filterSelectorStart should return an filterBadMode error if it is unable to process this mode of image. 

(29) imageHRes and imageVRes

The image's horizontal and vertical resolution in terms of pixels per inch. These are fixed point numbers (16 binary digits). 

(30) floatCoord

If the isFloating is true, the coordinate of the top-left corner of the floating selection in the main image's coordinate space. 

(31) wholeSize

If the isFloating is true, the size in pixels of the entire main image. 

(32) monitor

Information on the current monitor. The gamma field contains the monitor's gamma value, or zero if the entire monitor record is undefined. The redX, redY, greenX, greenY, blueX, blueY fields specify the chromaticity coordinates of the monitor's phosphors. The whiteX and whiteY fields specify the chromaticity coordinates of the monitor's white point. The ambient value specifies the relative amount of ambient light in the room. Zero means a relatively dark room, 0.5 means an average room, and 1.0 means a bright room. 

(33) reserved

Set to zero by the host for future expansion of the plug-in standard. Must not be used by plug-ins.

Supporting Older Plug-in Versions

This section describes how hosts can be compatible with older versions of the plug-in specification. It is of interest only to authors of host software. 

(1) If the version is less than 3.1, do not call the filter with CMYK mode images.

(2) If the version is less than 4, the plug-in are required to guess the imageMode based on the planes field, so alpha channels should not be included in the planes field, nor should HSB or HSL color images be filtered. 

All other changes are backward compatible.