Format plug-in modules, sometimes referred to as Image Format, or File Format modules, are used to add new file types to the Open, Save, and Save As commands. More...

Data Structures
struct	FormatRecord
	This structure is passed to the plug-in module through the parameter block. More...
Typedefs
typedef struct FormatRecord	FormatRecord
	This structure is passed to the plug-in module through the parameter block.
typedef struct FormatRecord *	FormatRecordPtr
Format Module Selectors
#define	formatSelectorAbout 0
	Allows the plug-in to display an about box for the Format Module.
#define	formatSelectorReadPrepare 1
	Allows a plug-in module to adjust the Photoshop memory allocation algorithm.
#define	formatSelectorReadStart 2
	Allows the plug-in module to begin its interaction with the host.
#define	formatSelectorReadContinue 3
	Processes a sequence of areas within the image.
#define	formatSelectorReadFinish 4
	Allows the plug-in to cleanup from the read operation just performed.
#define	formatSelectorOptionsPrepare 5
	Allows a plug-in module to adjust the Photoshop memory allocation algorithm.
#define	formatSelectorOptionsStart 6
	Allows a plug-in to determine whether the current document can be saved in the required file format, and if necessary, get any file options from the user.
#define	formatSelectorOptionsContinue 7
	Allows a plug-in to request parts of the image, from which it determines whether it can store the file.
#define	formatSelectorOptionsFinish 8
	Allows the plug-in to perform any necessary clean up.
#define	formatSelectorEstimatePrepare 9
	Allows a plug-in module to adjust the Photoshop memory allocation algorithm.
#define	formatSelectorEstimateStart 10
	Allows a plug-in to calculate the disk space needed to save the file.
#define	formatSelectorEstimateContinue 11
	Allows a plug-in to request parts of the image from which it can compute the minimum and maximum bytes to store the file.
#define	formatSelectorEstimateFinish 12
	Allows the plug-in to perform any necessary clean up.
#define	formatSelectorWritePrepare 13
	Allows a plug-in module to adjust the Photoshop memory allocation algorithm.
#define	formatSelectorWriteStart 14
	Allows a plug-in module to begin writing the file.
#define	formatSelectorWriteContinue 15
	Provides the plug-in module some or all of the image data; the plug-in module should write this data to file.
#define	formatSelectorWriteFinish 16
	Allows the plug-in to cleanup from the write operation just performed.
#define	formatSelectorFilterFile 17
	Determines whether a plug-in can process a given file type.
#define	formatSelectorGetFilePropertyValue 18
	Gets a file property value from the format plug-in.
#define	formatSelectorLosslessRotate 19
	Requests the format plug-in to rotate a file losslessly.
#define	formatSelectorBulkSettings 20
	Sets parameters for multiple files.
#define	formatSelectorXMPRead 21
	Reads the XMP data from your file.
#define	formatSelectorXMPWrite 22
	Writes the XMP data to your file.
#define	formatSelectorBulkOpen 23
#define	formatSelectorLoad 24
#define	formatSelectorUnload 25
#define	formatSelectorPreferences 26
#define	formatSelectorSettingsCopy 27
#define	formatSelectorSettingsPaste 28
#define	formatSelectorSettingsClear 29
#define	formatSelectorSettingsDefault 30
#define	formatSelectorSettingsPrevious 31
#define	formatSelectorSettingsPresetList 32
#define	formatSelectorSettingsChecksum 33
#define	formatSelectorXMPAppend 34
#define	formatSelectorReadLayerStart 35
#define	formatSelectorReadLayerContinue 36
#define	formatSelectorReadLayerFinish 37
#define	formatSelectorWriteLayerStart 38
#define	formatSelectorWriteLayerContinue 39
#define	formatSelectorWriteLayerFinish 40
Format Error Return Values
#define	formatBadParameters -30500
	An error with the interface.
#define	formatCannotRead -30501
	No scanner installed.
#define	formatSkipFile -30502
	The host should skip processing this file.
#define	formatPasswordProtected -30503
	For PDF files.
#define	formatUnsupportedRaw -30504
	The file appears to be a raw file from a camera model which is not supported by the installed version of Camera Raw.
#define	formatUnsupportedDNG -30505
	The DNG file is not supported by the installed version of Camera Raw.

Detailed Description

Format plug-in modules, sometimes referred to as Image Format, or File Format modules, are used to add new file types to the Open, Save, and Save As commands.

Adobe Photoshop ships with several file format modules including GIF, MacPaint, and BMP.

The file type for format modules for Mac OS is 8BIF, the extension for Windows is .8BI.

Please also see Writing Format Plug-ins.

Define Documentation

#define formatSelectorAbout 0

Allows the plug-in to display an about box for the Format 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 formatBadParameters -30500

An error with the interface.

See Error Handling for Writing with Format Plug-ins.

#define formatSelectorReadPrepare 1

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

Photoshop sets FormatRecord::maxData to the maximum number of bytes it can allocate to the plug-in. You may want to reduce maxData for increased efficiency. Please see Memory Management Strategies.

#define formatSelectorReadStart 2

Allows the plug-in module to begin its interaction with the host.

If the plug-in supports scripting, it should read any scripting parameters to override any default parameters. The scripting system also returns whether to show the plug-in dialog or not.

The plug-in should initialize FormatRecord::imageMode, FormatRecord::imageSize32, FormatRecord::depth, FormatRecord::planes, FormatRecord::imageHRes and FormatRecord::imageVRes.

If an indexed color image is being opened, the plug-in should also set FormatRecord::redLUT, FormatRecord::greenLUT and FormatRecord::blueLUT.

If the plug-in has a block of image resources to process, it should read the image resources in from the file and set FormatRecord::imageRsrcData to be a handle to the resource data. For more information about Photoshop image resources, see Photoshop File Formats.

The plug-in should allocate and read the first pixel image data buffer as appropriate. The area of the image being returned to the plug-in host is specified by FormatRecord::theRect32, FormatRecord::loPlane, and FormatRecord::hiPlane.

The actual pixel data is pointed by FormatRecord::data. The FormatRecord::colBytes, FormatRecord::rowBytes, FormatRecord::planeBytes, and FormatRecord::planeMap fields must specify the organization of the data.

Photoshop is very flexible about the format in which image data can be read. For example, to read just the red plane of an RGB color image, use the following parameter values:

*Read red plane of RGB*
Parameter	Value
loPlane	0
hiPlane	0
colBytes	1
rowBytes	width of the area being read
planeBytes	ignored, since loPlane=hiPlane

If you wish to read the RGB data in interleaved form (RGBRGB...), use the following values:

*Read RGB values in interleaved form*
Parameter	Value
loPlane	0
hiPlane	2
colBytes	3
rowBytes	3 * width of the area being read
planeBytes	1

#define formatSelectorReadContinue 3

Processes a sequence of areas within the image.

The plug-in handler for this selector should process any incoming data and then, just as with the start call, set up FormatRecord::theRect32, FormatRecord::loPlane, FormatRecord::hiPlane, FormatRecord::planeMap, FormatRecord::data, FormatRecord::colBytes, FormatRecord::rowBytes, and FormatRecord::planeBytes to describe the next chunk of the image being returned.

The host continues calling the plug-in with formatSelectorReadContinue until the plug-in sets data=NULL.

Note:: Be careful processing user-cancel events during formatSelectorReadContinue. Normally your plug-in would be expecting another formatSelectorReadContinue call. If the user cancels, the next call will be formatSelectorReadFinish, not formatSelectorReadContinue!

#define formatSelectorReadFinish 4

Allows the plug-in to cleanup from the read operation just performed.

This call is made by the plug-in host if and only if formatSelectorReadStart returned without error, even if one of the formatSelectorReadContinue calls results in an error.

Most plug-ins will at least need to free the buffer used to return pixel data if this has not been done previously.

If Photoshop detects Command-period in the Mac OS or Escape in Windows while processing the results of a formatSelectorReadContinue call, it calls formatSelectorReadFinish.

If your plug-in is scripting-aware and you have changed any initial parameters, you should pass a complete descriptor back to the scripting system in the PIDescriptorParameters structure.

#define formatSelectorOptionsPrepare 5

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

Photoshop sets FormatRecord::maxData to the maximum number of bytes it can allocate to the plug-in. You may want to reduce maxData for increased efficiency. Please see Memory Management Strategies.

#define formatSelectorOptionsStart 6

Allows a plug-in to determine whether the current document can be saved in the required file format, and if necessary, get any file options from the user.

If the plug-in supports scripting, read any scripting parameters at this point, to override any default parameters. The scripting system also returns whether to show the plug-in dialog or not.

If the plug-in needs to examine the image to compute the file size, it can iterate through the image data in formatSelectorOptionsContinue in the same fashion as is done when writing the file to request sections of the image.

#define formatSelectorOptionsContinue 7

Allows a plug-in to request parts of the image, from which it determines whether it can store the file.

Refer to formatSelectorWriteStart and formatSelectorWriteContinue for details. You can also use the AdvanceStateProc to iterate through the image.

Note:: If the FormatRecord::data is set to NULL in the formatSelectorOptionsStart call, this selector will not be called at all.

#define formatSelectorOptionsFinish 8

Allows the plug-in to perform any necessary clean up.

#define formatSelectorEstimatePrepare 9

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

Photoshop sets FormatRecord::maxData to the maximum number of bytes it can allocate to the plug-in. You may want to reduce maxData for increased efficiency. Please see Memory Management Strategies.

#define formatSelectorEstimateStart 10

Allows a plug-in to calculate the disk space needed to save the file.

If the plug-in can calculate the file size without examining the image data, you can set the FormatRecord::minDataBytes and FormatRecord::maxDataBytes fields to the approximate size of your file (due to compression, you may not be able to exactly calculate the final size), and set FormatRecord::data=NULL.

If the plug-in needs to examine the image to compute the file size, it can iterate through the image data in formatSelectorEstimateContinue in the same fashion as is done when writing the file to request sections of the image.

#define formatSelectorEstimateContinue 11

Allows a plug-in to request parts of the image from which it can compute the minimum and maximum bytes to store the file.

Refer to formatSelectorWriteStart and formatSelectorWriteContinue for details.

You can also use the AdvanceStateProc to iterate through the image.

Note:: If FormatRecord::data field is set to NULL in the formatSelectorEstimateStart call, this selector is not be called at all.

#define formatSelectorEstimateFinish 12

Allows the plug-in to perform any necessary clean up.

#define formatSelectorWritePrepare 13

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

Photoshop sets FormatRecord::maxData to the maximum number of bytes it can allocate to the plug-in. You may want to reduce maxData for increased efficiency. Please see Memory Management Strategies.

#define formatSelectorWriteStart 14

Allows a plug-in module to begin writing the file.

On entry, the file to be written is open, and the file pointer is positioned at the start of the file. The plug-in should write any file header information, such as image resources, to the file.

The plug-in should then indicate which portion of the image data to provide for the first formatSelectorWriteContinue call.

The area of the image requested from the plug-in host is specified by FormatRecord::theRect32, FormatRecord::loPlane, and FormatRecord::hiPlane. The actual pixel data is pointed to by FormatRecord::data. The plug-in must also specify the organization of the data to be returned by the plug-in host in the FormatRecord::colBytes, FormatRecord::rowBytes, FormatRecord::planeBytes, and FormatRecord::planeMap fields.

Photoshop is very flexible in the format in which image data can be delivered to the plug-in. For example, to return just the red plane of an RGB color image, use the following parameter values:

*Return red plane of RGB*
Parameter	Value
loPlane	0
hiPlane	0
colBytes	1
rowBytes	width of the area being returned
planeBytes	ignored, since loPlane=hiPlane

If you wish to return the RGB data in interleaved form (RGBRGB...), use the following values:. Return RGB data in interleaved form

*Return RGB values in interleaved form*
Parameter	Value
loPlane	0
hiPlane	2
colBytes	3
rowBytes	3 * width of the area being returned
planeBytes	1

#define formatSelectorWriteContinue 15

Provides the plug-in module some or all of the image data; the plug-in module should write this data to file.

If successful, set up FormatRecord::theRect32, FormatRecord::loPlane, FormatRecord::hiPlane, FormatRecord::planeMap, FormatRecord::data, FormatRecord::colBytes, FormatRecord::rowBytes, and FormatRecord::planeBytes to describe the next chunk of the image being requested. The host keeps calling your formatSelectorReadContinue handler until the plug-in sets FormatRecord::theRect32 to an empty rectangle. Before returning after the last image data has been written, write any file trailer information to the file.

Note:: Be careful processing user-cancel events during formatSelectorWriteContinue. Normally your plug-in would be expecting another formatSelectorWriteContinue call. If the user cancels, the next call will be formatSelectorWriteFinish, not formatSelectorWriteContinue.

#define formatSelectorWriteFinish 16

Allows the plug-in to cleanup from the write operation just performed.

This call is made by the plug-in host if and only if formatSelectorWriteStart returned without error, even if one of the formatSelectorWriteContinue calls results in an error.

Most plug-ins at least need to free the buffer used to hold pixel data if this has not been done previously.

If Photoshop detects Command-period in the Mac OS or Escape in Windows while processing the results of a formatSelectorWriteContinue call, it calls the formatSelectorWriteFinish routine. If the plug-in is scripting-aware and has changed any initial parameters, it should pass a complete descriptor back to the scripting system in the PIDescriptorParameters structure.

#define formatSelectorFilterFile 17

Determines whether a plug-in can process a given file type.

The plug-in module should examine the file to determine whether the file is one that it can process, and indicate this in its result parameter:

 if (module can read this file)
    *result = noErr;
 else
    *result = formatCannotRead;

See File Filtering Sequence for additional information.

#define formatSelectorGetFilePropertyValue 18

Gets a file property value from the format plug-in.

#define formatSelectorLosslessRotate 19

Requests the format plug-in to rotate a file losslessly.

#define formatSelectorBulkSettings 20

Sets parameters for multiple files.

#define formatSelectorXMPRead 21

Reads the XMP data from your file.

#define formatSelectorXMPWrite 22

Writes the XMP data to your file.

#define formatSelectorBulkOpen 23

#define formatSelectorLoad 24

#define formatSelectorUnload 25

#define formatSelectorPreferences 26

#define formatSelectorSettingsCopy 27

#define formatSelectorSettingsPaste 28

#define formatSelectorSettingsClear 29

#define formatSelectorSettingsDefault 30

#define formatSelectorSettingsPrevious 31

#define formatSelectorSettingsPresetList 32

#define formatSelectorSettingsChecksum 33

#define formatSelectorXMPAppend 34

#define formatSelectorReadLayerStart 35

#define formatSelectorReadLayerContinue 36

#define formatSelectorReadLayerFinish 37

#define formatSelectorWriteLayerStart 38

#define formatSelectorWriteLayerContinue 39

#define formatSelectorWriteLayerFinish 40

#define formatCannotRead -30501

No scanner installed.

See Error Handling for Writing with Format Plug-ins.

#define formatSkipFile -30502

The host should skip processing this file.

Used with bulk selectors.

#define formatPasswordProtected -30503

For PDF files.

#define formatUnsupportedRaw -30504

The file appears to be a raw file from a camera model which is not supported by the installed version of Camera Raw.

#define formatUnsupportedDNG -30505

The DNG file is not supported by the installed version of Camera Raw.

Typedef Documentation

typedef struct FormatRecord FormatRecord

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 FormatRecord * FormatRecordPtr

Getting Started

SDK API Reference

SDK API Features

Other Documentation

Data Structures

Typedefs

Format Module Selectors

Format Error Return Values

Detailed Description

Define Documentation

Typedef Documentation