Image Services Suite Callbacks

The Image Services Suite provides access to some image procession routines inside Photoshop. More...

Data Structures
struct	ImageServicesProcs
	The set of routines available in the Image Services suite. More...
Defines
#define	kCurrentImageServicesProcsVersion   1
	Current version for the Image Services Suite.
#define	kCurrentImageServicesProcsCount   ((sizeof(ImageServicesProcs) - offsetof(ImageServicesProcs, interpolate1DProc)) / sizeof(void *))
	Current number of routines in the Images Services Suite.
Typedefs
typedef struct ImageServicesProcs	ImageServicesProcs
	The set of routines available in the Image Services suite.
Image Services Suite Callbacks
typedef MACPASCAL OSErr(*	PIResampleProc )(PSImagePlane *source, PSImagePlane *destination, Rect *area, Fixed *coords, int16 method)
	Provides 1D or 2D image interpolation, depending on the value passed in the coords parameter.
typedef MACPASCAL OSErr(*	PIResampleMultiProc )(PSImageMultiPlane *source, PSImageMultiPlane *destination, Rect *area, Fixed *coords, int16 method)
typedef MACPASCAL OSErr(*	PIResampleMulti32Proc )(PSImageMultiPlane32 *source, PSImageMultiPlane32 *destination, VRect *area, int64 *coords, int16 method)

---

Detailed Description

The Image Services Suite provides access to some image procession routines inside Photoshop.

The Image Services Suite provides 1D and 2D versions for each of the defined callbacks. See the ImageServicesProcs data structure.

The Image Services suite is available in Adobe Photoshop version 3.0.4 and later. These routines are used in the distortion filters that ship with Adobe Photoshop 5.0.

The standard Image Services Suite is found as a pointer in the parameter blocks of the plug-in modules. You can access the routines within the Image Services Suite in the following manner:

    ImageServicesProc *imageServicesSuite;

    DLLExport MACPASCAL void PluginMain (const int16 selector,
                                         ExportRecordPtr exportParamBlock,
                                         intptr_t* data,
                                         int16* result)
    {
            ...

            // Get the Image Services Suite from the parameter block
            imageServicesSuite = exportParamBlock->imageServicesProc;

            // Call the interpolate1DProc, which uses PIResampleProc.
            imageServicesSuite->interpolate1DProc(...);
            ...
        }

---

Define Documentation

#define kCurrentImageServicesProcsVersion   1

Current version for the Image Services Suite.

#define kCurrentImageServicesProcsCount   ((sizeof(ImageServicesProcs) - offsetof(ImageServicesProcs, interpolate1DProc)) / sizeof(void *))

Current number of routines in the Images Services Suite.

---

Typedef Documentation

typedef MACPASCAL OSErr(* PIResampleProc)(PSImagePlane *source, PSImagePlane *destination, Rect *area, Fixed *coords, int16 method)

Provides 1D or 2D image interpolation, depending on the value passed in the coords parameter.

For a source coordinate <fv, fh>, Photoshop writes to the destination plane if and only if:

 source->bounds.top <= fv <= source.bounds.bottom - 1

and

 source->bounds.left <= fh <= source.bounds.right - 1

The two PIResampleProc callback functions differ in how they generate the sample coordinates for each pixel in the target area.

When calling this function through the interpolate1DProc() callback, use an array that contains one fixed point number for each pixel. This callback forms a sample coordinate by taking the vertical coordinate of the destination pixel and the horizontal coordinate from the list. Thus

	SampleLoc1D(v, h) = <v, coords[(h - area->left) +
		(v - area->top) * (area->right - area->left)]>
	

When calling through the interpolate2DProc() callback, use an array that contains two fixed point numbers for each pixel. The sample coordinate is formed as follows:

	SampleLoc2D(v, h) = 
		<coords[2*((h - area->left) +
			(v - area->top) * (area->right - area->left))],
	 	coords[2*((h - area->left) +
			(v - area->top) * (area->right - area->left)) + 1]>
	

You can build a destination image using relatively small input buffers by passing in a series of input buffers, since these callbacks leave any pixels whose sample coordinates are out of bounds untouched.

Make sure that you have appropriate overlap between the source buffers so that sample coordinates do not "fall through the cracks." This matters even when point sampling, since the coordinate test is applied without regard to the method parameter. This allows you to get consistent results when switching between point sampling and linear interpolation. If Photoshop did not do this, a plug-in could end up modifying pixels using point sampling that would not get modified when using linear interpolation.

You also want to pin coordinates to the overall source bounds so that you manage to write everything in the destination.

Note:

To determine whether you should use point sampling or linear interpolation, you might want to check what the user has set in their Photoshop preferences. This is set in the General Preferences dialog, under the Interpolation pop-up menu. You can retrieve this value using the Property Suite Callbacks GetPropertyProc function with the propInterpolationMethod key.

Parameters:

source	A pointer to the source image.
destination	[OUT] A pointer to the destination image.
area	A pointer to an area in the destination image plane that you wish to modify. The area rectangle must be contained within destination->bounds.
coords	A pointer to an array you create that controls the image resampling. When calling interpolate1DPRoc(), the array contains one fixed point number for each pixel in the area rectangle, in top to bottom, left to right order. When calling interpolate2DPRoc(), the array contains two fixed point numbers for each pixel in the area containing the vertical and horizontal sample coordinate.
method	The sampling method to use. If 0, uses point sampling. If 1, uses linear interpolation. If source coordinates are not integers, Photoshop rounds to the nearest integer for the point sampling method. The linear interpolation method performs the appropriate bilinear interpolation using up to four source pixels. The bicubic interpolation method is not currently supported.

Returns:

Non-zero error upon failure.

typedef MACPASCAL OSErr(* PIResampleMultiProc)(PSImageMultiPlane *source, PSImageMultiPlane *destination, Rect *area, Fixed *coords, int16 method)

typedef MACPASCAL OSErr(* PIResampleMulti32Proc)(PSImageMultiPlane32 *source, PSImageMultiPlane32 *destination, VRect *area, int64 *coords,int16 method)

typedef struct ImageServicesProcs ImageServicesProcs

The set of routines available in the Image Services suite.