FilterRecord Struct Reference
[Filter Module]

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

#include <PIFilter.h>


Data Fields

int32 serialNumber
 DEPRECATED - Formerly the host serial number.
TestAbortProc abortProc
 A pointer to the TestAbortProc callback.
ProgressProc progressProc
 A pointer the the ProgressProc callback.
Handle parameters
 Parameters the plug-in can request from a user.
Point imageSize
 DEPRECATED, use BigDocumentStruct::imageSize32.
int16 planes
 The number of planes in the image.
Rect filterRect
 DEPRECATED, use BigDocumentStruct::filterRect32.
PSRGBColor background
 DEPRECATED: Use backColor.
PSRGBColor foreground
 DEPRECATED: Use foreColor.
int32 maxSpace
 The maximum number of bytes of information the plug-in can expect to be able to access at once (input area size + output area size + mask area size + bufferSpace).
int32 bufferSpace
 Allows the plug-in to specify how much buffer space it needs.
Rect inRect
 DEPRECATED, use BigDocumentStruct::inRect32.
int16 inLoPlane
 The first input plane to process next.
int16 inHiPlane
 The last input plane to process next.
Rect outRect
 DEPRECATED, use BigDocumentStruct::outRect32.
int16 outLoPlane
 The first output plane to process next.
int16 outHiPlane
 The last output plane to process next.
void * inData
 A pointer to the requested input image data.
int32 inRowBytes
 The offset between rows of the input image data.
void * outData
 A pointer to the requested output image data.
int32 outRowBytes
 The offset between rows of the output image data.
Boolean isFloating
 Indicates if the selection is floating.
Boolean haveMask
 Indicates if the selection has a mask.
Boolean autoMask
 Enables or disables auto-masking.
Rect maskRect
 DEPRECATED, use BigDocumentStruct::maskRect32.
void * maskData
 A pointer to the requested mask data.
int32 maskRowBytes
 The offset between rows of the mask data.
FilterColor backColor
 The current background color, in the color space native to the image.
FilterColor foreColor
 The current foreground color, in the color space native to the image.
OSType hostSig
 The signature of the host, provided by the host.
HostProc hostProc
 A pointer to a host-defined callback procedure.
int16 imageMode
 The mode of the image being filtered, for example, Gray Scale, RGB Color, and so forth.
Fixed imageHRes
 The horizontal resolution of the image in terms of pixels per inch.
Fixed imageVRes
 The vertical resolution of the image in terms of pixels per inch.
Point floatCoord
 DEPRECATED, use BigDocumentStruct::floatCoord32.
Point wholeSize
 DEPRECATED, use BigDocumentStruct::wholeSize32.
PlugInMonitor monitor
 Monitor setup information for the host.
void * platformData
 A pointer to platform specific data.
BufferProcsbufferProcs
 A pointer to the Buffer suite if it is supported by the host, otherwise NULL.
ResourceProcsresourceProcs
 A pointer to the Pseudo-Resource suite if it is supported by the host, otherwise NULL.
ProcessEventProc processEvent
 A pointer to the ProcessEventProc callback if it is supported by the host, otherwise NULL.
DisplayPixelsProc displayPixels
 A pointer to the DisplayPixelsProc callback if it is supported by the host, otherwise NULL.
HandleProcshandleProcs
 A pointer to the Handle callback suite if it is supported by the host, otherwise NULL.
New in 3.0.
Boolean supportsDummyChannels
 Indicates whether the host supports the plug-in requesting nonexistent planes.
Boolean supportsAlternateLayouts
 Indicates whether the host support data layouts other than rows of columns of planes.
int16 wantLayout
 The desired layout for the data.
int16 filterCase
 The type of data being filtered.
int16 dummyPlaneValue
 The value to store into any dummy planes.
void * premiereHook
 DEPRECATED.
AdvanceStateProc advanceState
 AdvanceState callback.
Boolean supportsAbsolute
 Indicates whether the host supports absolute channel indexing.
Boolean wantsAbsolute
 Enables absolute channel indexing for the input.
GetPropertyProc getPropertyObsolete
 The GetProperty callback.
Boolean cannotUndo
 Indicates whether a filter plug-in makes changes that the user cannot undo.
Boolean supportsPadding
 Indicates whether the host supports requests outside the image area.
int16 inputPadding
 Instructions for padding the input.
int16 outputPadding
 Instructions for padding the output.
int16 maskPadding
 Padding instructions for the mask.
char samplingSupport
 Indicates whether the host support non- 1:1 sampling of the input and mask.
char reservedByte
 For alignment.
Fixed inputRate
 The sampling rate for the input.
Fixed maskRate
 Like inputRate, but as applied to the mask data.
ColorServicesProc colorServices
 Function pointer to access color services routine.
int16 inLayerPlanes
 The number of target layer planes for the input data.
int16 inTransparencyMask
 The number of transparency masks for the input target layer data.
int16 inLayerMasks
 The number of layer mask channels for the input target layer.
int16 inInvertedLayerMasks
 The number of inverted layer mask channels for the input target layer.
int16 inNonLayerPlanes
 The number of non-layer channels for the input data.
int16 outLayerPlanes
 The number of target layer planes for the output data.
int16 outTransparencyMask
 The number of transparency masks for the output data.
int16 outLayerMasks
 The number of layer mask channels for the output data.
int16 outInvertedLayerMasks
 The number of inverted layer mask channels for the output data.
int16 outNonLayerPlanes
 The number of non-layer channels for the output data.
int16 absLayerPlanes
 The number of target layer planes for the input data, used for the structure of the input data when wantsAbsolute is TRUE.
int16 absTransparencyMask
 The number of transparency masks for the input data, used for the structure of the input data when wantsAbsolute is TRUE.
int16 absLayerMasks
 The number of layer mask channels for the input data, used for the structure of the input data when wantsAbsolute is TRUE.
int16 absInvertedLayerMasks
 The number of inverted layer mask channels for the input data, used for the structure of the input data when wantsAbsolute is TRUE.
int16 absNonLayerPlanes
 The number of target layer planes for the input data, used for the structure of the input data when wantsAbsolute is TRUE.
int16 inPreDummyPlanes
 The number of extra planes before the input data.
int16 inPostDummyPlanes
 The number of extra planes after the input data.
int16 outPreDummyPlanes
 The number of extra planes before the output data.
int16 outPostDummyPlanes
 The number of extra planes after the output data.
int32 inColumnBytes
 The step from column to column in the input.
int32 inPlaneBytes
 The step from plane to plane in the input.
int32 outColumnBytes
 The output equivalent of inColumnBytes.
int32 outPlaneBytes
 The output equivalent of inPlaneBytes.
New in 3.0.4
ImageServicesProcsimageServicesProcs
 Image Services callback suite.
PropertyProcspropertyProcs
 Property callback suite.
int16 inTileHeight
 Tiling height for the input, set by host.
int16 inTileWidth
 Tiling width for the input, set by host.
Point inTileOrigin
 Tiling origin for the input, set by host.
int16 absTileHeight
 Tiling height the absolute data, set by host.
int16 absTileWidth
 Tiling width the absolute data, set by host.
Point absTileOrigin
 Tiling origin the absolute data, set by host.
int16 outTileHeight
 Tiling height for the output, set by host.
int16 outTileWidth
 Tiling width for the output, set by host.
Point outTileOrigin
 Tiling origin for the output, set by host.
int16 maskTileHeight
 Tiling height for the mask, set by host.
int16 maskTileWidth
 Tiling width for the mask, set by host.
Point maskTileOrigin
 Tiling origin for the mask, set by host.
New in 4.0
PIDescriptorParametersdescriptorParameters
 Descriptor callback suite.
Str255 * errorString
 An error reporting string to return to Photoshop.
ChannelPortProcschannelPortProcs
 Channel Ports callback suite.
ReadImageDocumentDescdocumentInfo
 The Channel Ports document information for the document being filtered.
New in 5.0
SPBasicSuite * sSPBasic
 PICA basic suite.
void * plugInRef
 Plug-in reference used by PICA.
int32 depth
 Bit depth per channel (1,8,16,32).
New in 6.0
Handle iCCprofileData
 Handle containing the ICC profile for the image.
int32 iCCprofileSize
 Size of profile.
int32 canUseICCProfiles
 Indicates if the host uses ICC Profiles.
New in 7.0
int32 hasImageScrap
 Indicates if Photoshop has image scrap; non-zero if it does.
New in 8.0
BigDocumentStructbigDocumentData
 Support for documents larger than 30,000 pixels.
New in 10.0
PIDescriptorParametersinput3DScene
 support for 3d scene data to be sent into the plugin
PIDescriptorParametersoutput3DScene
 support for 3d scene to come out of the plugin
Boolean createNewLayer
 set by plugin this only works for 3D layers
New in 13.0
Handle iCCWorkingProfileData
 Handle containing the ICC profile for the working profile set via color settings dialog.
int32 iCCWorkingProfileSize
 Size of working profile.
Reserved Space for Expansion
char reserved [29]
 Reserved for future use.

Detailed Description

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.


Field Documentation

DEPRECATED - Formerly the host serial number.

The host now reports zero for the serialNumber. Plug-ins should use the Property Suite Callbacks by using the propertyProcs callback, specifying the property propSerialString2 to get the serial string.

A pointer to the TestAbortProc callback.

A pointer the the ProgressProc callback.

Parameters the plug-in can request from a user.

Photoshop initializes this handle to NULL at startup. If the plug-in filter has any parameters that the user can set, it should allocate a relocatable block in the filterSelectorParameters handler, store the parameters in the block, and store the block’s handle in this field.

DEPRECATED, use BigDocumentStruct::imageSize32.

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

The number of planes in the image.

For version 4+ filters, this field contains the total number of active planes in the image, including alpha channels. The image mode should be determined by looking at imageMode. For version 0-3 filters, this field is 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 is equal to 1.

DEPRECATED, use BigDocumentStruct::filterRect32.

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 autoMask). This allows most filters to ignore the selection mask, and still operate correctly.

DEPRECATED: Use backColor.

DEPRECATED: Use foreColor.

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

Set by Photoshop.

Allows the plug-in to specify how much buffer space it needs.

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 plans to allocate. Photoshop then tries to free up the requested amount of space before calling the filterSelectorStart routine. Relocatable blocks should be used if possible.

DEPRECATED, use BigDocumentStruct::inRect32.

The area of the input image to access. The plug-in should set this field in the filterSelectorStart and filterSelectorContinue handlers 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.

The first input plane to process next.

The filterSelectorStart and filterSelectorContinue handlers should set this field.

The last input plane to process next.

The filterSelectorStart and filterSelectorContinue handlers should set this field.

DEPRECATED, use BigDocumentStruct::outRect32.

The area of the output image to access. The plug-in should set this field in its filterSelectorStart and filterSelectorContinue handlers 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.

The first output plane to process next.

The filterSelectorStart and filterSelectorContinue handlers should set this field.

The last output plane to process next.

The filterSelectorStart and filterSelectorContinue handlers should set this field.

A pointer to the requested input image data.

If more than one plane has been requested (inLoPlane¦inHiPlane), the data is interleaved.

The offset between rows of the input image data.

The end of each row may or may not include pad bytes.

A pointer to the requested output image data.

If more than one plane has been requested (outLoPlane¦outHiPlane), the data is interleaved.

The offset between rows of the output image data.

The end of each row may or may not include pad bytes.

Indicates if the selection is floating.

Set to TRUE if and only if the selection is floating.

Indicates if the selection has a mask.

Set to true if and only if non-rectangular area has been selected.

Enables or disables auto-masking.

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

If the plug-in has set the PiPL bit writesOutsideSelection, this will always be FALSE and the plug-in must supply its own mask, if needed.

DEPRECATED, use BigDocumentStruct::maskRect32.

Provides a mask rectangle. If haveMask=TRUE, and the plug-in needs access to the selection mask, the plug-in should set this field in your filterSelectorStart and filterSelectorContinue handlers 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.

A pointer to the requested mask data.

The data is in the form of an array of bytes, one byte per pixel of the selected area. The bytes range from (0...255), where 0=no mask (selected) and 255=masked (not selected). Use maskRowBytes to iterate over the scan lines of the mask.

The offset between rows of the mask data.

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

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

The signature of the host, provided by the host.

The signature for Photoshop is signature is 8BIM.

A pointer to a host-defined callback procedure.

May be NULL.

The mode of the image being filtered, for example, Gray Scale, RGB Color, and so forth.

See Image Modes for values. The filterSelectorStart handler should return filterBadMode if it is unable to process this mode of image.

The horizontal resolution of the image in terms of pixels per inch.

These are fixed point numbers (16.16).

The vertical resolution of the image in terms of pixels per inch.

These are fixed point numbers (16.16).

DEPRECATED, use BigDocumentStruct::floatCoord32.

The coordinate of the top-left corner of the selection in the main image’s coordinate space.

DEPRECATED, use BigDocumentStruct::wholeSize32.

The size in pixels of the entire main image.

Monitor setup information for the host.

A pointer to platform specific data.

Not used under Mac OS. See PlatformData in PITypes.h.

A pointer to the Buffer suite if it is supported by the host, otherwise NULL.

See Buffer Suite Callbacks (DEPRECATED Standard Suite).

A pointer to the Pseudo-Resource suite if it is supported by the host, otherwise NULL.

See chapter Resource Suite Callbacks.

A pointer to the ProcessEventProc callback if it is supported by the host, otherwise NULL.

A pointer to the DisplayPixelsProc callback if it is supported by the host, otherwise NULL.

A pointer to the Handle callback suite if it is supported by the host, otherwise NULL.

See Handle Suite Callbacks (DEPRECATED Standard Suite).

Indicates whether the host supports the plug-in requesting nonexistent planes.

(See dummyPlaneValue, inPreDummyPlanes, inPostDummyPlanes, outPreDummyPlanes, outPostDummyPlanes.)

Indicates whether the host support data layouts other than rows of columns of planes.

This field is set by the plug-in host to indicate whether it respects the wantLayout field.

The desired layout for the data.

The plug-in host only looks at this field if it has also set supportsAlternateLayouts. See Layout Constants for values.

The type of data being filtered.

Flat, floating, layer with editable transparency, layer with preserved transparency, with and without a selection. A zero indicates that the host did not set this field, and the plug-in should look at haveMask and isFloating. See Filter Case Identifiers for values.

The value to store into any dummy planes.

Values from 0 to 255 indicates a specific value. A value of -1 indicates to leave undefined. All other values generate an error.

DEPRECATED.

Indicates whether the host supports absolute channel indexing.

Absolute channel indexing ignores visibility concerns and numbers the channels from zero starting with the first composite channel. If existing, transparency follows, followed by any layer masks, then alpha channels.

Enables absolute channel indexing for the input.

This is only useful if supportsAbsolute=TRUE. Absolute indexing is useful for things like accessing alpha channels.

The GetProperty callback.

This direct callback pointer has been superceded by the Property callback suite, but is maintained here for backwards compatibility. See Property Suite Callbacks.

Indicates whether a filter plug-in makes changes that the user cannot undo.

If the filter makes a change that cannot be undone, then setting this field to TRUE prevents Photoshop from offering undo for the filter. This is rarely needed and usually frustrates users.

Indicates whether the host supports requests outside the image area.

If so, see padding fields below.

Instructions for padding the input.

The input can be padded when loaded. See Filter Padding Constants.

The options for padding include specifying a specific value (0...255), specifying plugInWantsEdgeReplication, specifying that the data be left random (plugInDoesNotWantPadding), or requesting that an error be signaled for an out of bounds request (plugInWantsErrorOnBoundsException). Default value: plugInWantsErrorOnBoundsException.

Instructions for padding the output.

The output can be padded when loaded. See Filter Padding Constants.

The options for padding include specifying a specific value (0...255), specifying plugInWantsEdgeReplication, specifying that the data be left random (plugInDoesNotWantPadding), or requesting that an error be signaled for an out of bounds request (plugInWantsErrorOnBoundsException). Default value: plugInWantsErrorOnBoundsException.

Padding instructions for the mask.

The mask can be padded when loaded. See Filter Padding Constants.

The options for padding include specifying a specific value (0...255), specifying plugInWantsEdgeReplication, specifying that the data be left random (plugInDoesNotWantPadding), or requesting that an error be signaled for an out of bounds request (plugInWantsErrorOnBoundsException). Default value: plugInWantsErrorOnBoundsException.

Indicates whether the host support non- 1:1 sampling of the input and mask.

Photoshop 3.0.1+ supports integral sampling steps (it will round up to get there). This is indicated by the value hostSupportsIntegralSampling. Future versions may support non-integral sampling steps. This will be indicated with hostSupportsFractionalSampling.

For alignment.

The sampling rate for the input.

The effective input rectangle in normal sampling coordinates is inRect * inputRate. For example, (inRect.top * inputRate, inRect.left * inputRate, inRect.bottom * inputRate, inRect.right * inputRate). The value for inputRate is rounded to the nearest integer in Photoshop 3.0.1+. Since the scaled rectangle may exceed the real source data, it is a good idea to set some sort of padding for the input as well.

Like inputRate, but as applied to the mask data.

Function pointer to access color services routine.

The number of target layer planes for the input data.

If all the input plane values are zero, then the plug-in should assume the host has not set them.

Note:
When processing layer data, Photoshop structures its input and output data for plug-ins as follows:
  • target layer channels
  • transparency mask for target layer
  • layer mask channels for target layer
  • inverted layer mask channels for target layer
  • non-layer channels
The output planes are a prefix of the input planes. For example, in the protected transparency case, the input can contain a transparency mask and a layer mask while the output can contain just the layerPlanes.

When processing non-layer data (including running a filter on the layer mask alone), Photoshop structures the data as consisting only of non-layer channels. It indicates this structure through a series of short counts. The transparency count must be either 0 or 1.

The number of transparency masks for the input target layer data.

See inLayerPlanes for additional information.

The number of layer mask channels for the input target layer.

See inLayerPlanes for additional information.

The number of inverted layer mask channels for the input target layer.


With the inverted layer masks, 0 = fully visible and 255 = completely hidden. See inLayerPlanes for additional information.

The number of non-layer channels for the input data.

See inLayerPlanes for additional information.

The number of target layer planes for the output data.

See inLayerPlanes for additional information about the structure of the output data.

The number of transparency masks for the output data.

See inLayerPlanes for additional information about the structure of the output data.

The number of layer mask channels for the output data.

See inLayerPlanes for additional information about the structure of the output data.

The number of inverted layer mask channels for the output data.

See inLayerPlanes for additional information about the structure of the output data.

The number of non-layer channels for the output data.

See inLayerPlanes for additional information about the structure of the output data.

The number of target layer planes for the input data, used for the structure of the input data when wantsAbsolute is TRUE.

See inLayerPlanes for additional information about the structure of the input data.

The number of transparency masks for the input data, used for the structure of the input data when wantsAbsolute is TRUE.

See inLayerPlanes for additional information about the structure of the input data.

The number of layer mask channels for the input data, used for the structure of the input data when wantsAbsolute is TRUE.

See inLayerPlanes for additional information about the structure of the input data.

The number of inverted layer mask channels for the input data, used for the structure of the input data when wantsAbsolute is TRUE.

See inLayerPlanes for additional information about the structure of the input data.

The number of target layer planes for the input data, used for the structure of the input data when wantsAbsolute is TRUE.

See inLayerPlanes for additional information about the structure of the input data.

The number of extra planes before the input data.

Only available if supportsDummyChannels=TRUE. Used for things like forcing RGB data to appear as RGBA.

The number of extra planes after the input data.

Only available if supportsDummyChannels=TRUE. Used for things like forcing RGB data to appear as RGBA.

The number of extra planes before the output data.

Only available if supportsDummyChannels=TRUE.

The number of extra planes after the output data.

Only available if supportsDummyChannels=TRUE.

The step from column to column in the input.

If using the layout options, this value may change from being equal to the number of planes. If zero, assume the host has not set it.

The step from plane to plane in the input.

Normally 1, but this changes if the plug-in uses the layout options. If zero, assume the host has not set it.

The output equivalent of inColumnBytes.

The output equivalent of inPlaneBytes.

Image Services callback suite.

Property callback suite.

The plug-in needs to dispose of the handle returned for complex properties (the plug-in also maintains ownership of handles for set properties.

Tiling height for the input, set by host.

Zero if not set. The plug-in should work at this size, if possible.

Tiling width for the input, set by host.

Zero if not set. Best to work at this size, if possible.

Tiling origin for the input, set by host.

Zero if not set.

Tiling height the absolute data, set by host.

The plug-in should work at this size, if possible.

Tiling width the absolute data, set by host.

The plug-in should work at this size, if possible.

Tiling origin the absolute data, set by host.

Tiling height for the output, set by host.

The plug-in should work at this size, if possible.

Tiling width for the output, set by host.

The plug-in should work at this size, if possible.

Tiling origin for the output, set by host.

Tiling height for the mask, set by host.

The plug-in should work at this size, if possible.

Tiling width for the mask, set by host.

The plug-in should work at this size, if possible.

Tiling origin for the mask, set by host.

An error reporting string to return to Photoshop.

If the plug-in returns with result=errReportString then this string is displayed as: "Cannot complete operation because " + errorString.

Channel Ports callback suite.

The Channel Ports document information for the document being filtered.

SPBasicSuite* FilterRecord::sSPBasic

PICA basic suite.

Provides the mechanism to access all PICA suites.

Plug-in reference used by PICA.

Bit depth per channel (1,8,16,32).

Handle containing the ICC profile for the image.

(NULL if none) Photoshop allocates the handle using its handle suite The handle is unlocked while calling the plug-in. The handle is valid from FilterSelectorStart to FilterSelectorFinish Photoshop will free the handle after FilterSelectorFinish.

Size of profile.

Indicates if the host uses ICC Profiles.

Non-zero if the host can accept or export ICC profiles . If this is zero, don't set or dereference iCCprofileData.

Indicates if Photoshop has image scrap; non-zero if it does.

The plug-in can ask for the exporting of image scrap by setting the PiPL resource, PIWantsScrapProperty. The document info for the image scrap is chained right behind the targeted document pointed by the documentInfo field. Photoshop sets hasImageScrap to indicate that an image scrap is available. A plug-in can use it to tell whether Photoshop failed to export the scrap because some unknown reasons or there is no scrap at all.

Support for documents larger than 30,000 pixels.

NULL if host does not support big documents.

support for 3d scene data to be sent into the plugin

support for 3d scene to come out of the plugin

set by plugin this only works for 3D layers

Handle containing the ICC profile for the working profile set via color settings dialog.

(NULL if none) Photoshop allocates the handle using its handle suite The handle is unlocked while calling the plug-in. The handle is valid from FilterSelectorStart to FilterSelectorFinish Photoshop will free the handle after FilterSelectorFinish.

Size of working profile.

Reserved for future use.

Set to zero.


The documentation for this struct was generated from the following file: