LayerPD_Layer
ObjectPDImage

A PDImage is a sampled image or image mask, and corresponds to a PDF Image resource (see Stencil Masking in Section 4.8, Images, in the PDF Reference). You can use any PDXObject method on a PDImage.



Typedef Summary
 Typedef
 PDCount
A numeric count value for use in PDImageAttrs.
 PDImageAttrs
 PDImageAttrsP
 PDImageScalar
A signed measurement of an image offset, for use in PDImageAttrs.
Structure Summary
 Structure
 _t_PDImageAttrs
A data structure containing information about the attributes of an image. See Section 4.8 in the PDF Reference for more information.
Method Summary
 Method
 
(Obsolete, provided only for backwards compatibility) Gets the lookup table for an indexed color space. The table will contain the number of entries specified by the index size, and there will be 1 byte for each color component for each entry. The number of color components depends on the color space:
 
void PDImageGetAttrs(PDXObject obj, PDImageAttrsP attrsP, ASInt32 attrsLen)
(Obsolete, provided only for backwards compatibility. Use PDEImageGetAttrs and/or Cos-level calls instead.) Gets the attributes of an image (for example, Type, Subtype, Name, Width, Height, BitsPerComponent, ColorSpace, Decode, Interpolate, or ImageMask).
 
void PDImageSelAdjustMatrix(void* callData, ASFixedMatrix newUserMatrix)
This method is obsolete and never called in Acrobat 8.
 
CosObj PDImageSelectAlternate(CosObj image, ASBool print, ASUns32 tickLimit, ASBool* cacheImageP, void* callData)
This method is obsolete and never called in Acrobat 8.
 
void PDImageSelGetDeviceAttr(void* callData, PDColorSpace* colorSpaceP, ASUns32* bitsPerPixelP, ASAtom* deviceTypeP)
This method is obsolete and never called in Acrobat 8.
 
void PDImageSelGetGeoAttr(void* callData, ASFixedRect* updateBBoxP, ASFixedMatrix* imageToDefaultMatrixP, ASFixedMatrix* imageToDevMatrixP)
This method is obsolete and never called in Acrobat 8.

Typedefs Detail
PDCount 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef ASInt32 PDCount;

A numeric count value for use in PDImageAttrs.


File: PDExpT.h
Line: 100
PDImageAttrs 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_PDImageAttrs PDImageAttrs;

File: PDExpT.h
Line: 2589
PDImageAttrsP 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_PDImageAttrs PDImageAttrsP;

File: PDExpT.h
Line: 2589
PDImageScalar 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef ASInt32 PDImageScalar;

A signed measurement of an image offset, for use in PDImageAttrs.


File: PDExpT.h
Line: 81


Structure Detail
_t_PDImageAttrs
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

struct _t_PDImageAttrs {
 PDImageScalar width; 
 
 PDImageScalar height; 
 
 PDCount bitsPerComponent; 
 
 ASBool imageMask; 
 
 ASBool interpolate; 
 
 ASBool haveDecode; 
 
 ASFixed decode[8]; 
 
 ASAtom colorSpaceName; 
 
 ASBool isIndexed; 
 
 PDCount hiVal; 
 
 CosObj colorSpace; 
 
 ASTArraySize dataLen; 
 
 PDCount comps; 
}

A data structure containing information about the attributes of an image. See Section 4.8 in the PDF Reference for more information.

See Also


File: PDExpT.h
Line: 2557

Elements
width  

(Required) The width of the source image in samples.

 
height  

(Required) The height of the source image in samples.

 
bitsPerComponent  

(Required) The number of bits used to represent each color component.

 
imageMask  

(Optional) true if the image should be treated as a mask, false otherwise.

 
interpolate  

(Optional) true if interpolation is performed, false otherwise. Interpolation attempts to smooth transitions between sample values.

 
haveDecode  

true if decode is used, false otherwise.

 
decode  

(Optional) An array of numbers specifying the mapping from sample values in the image to values appropriate for the current color space.

 
colorSpaceName  

An ASAtom representing the color space name.

 
isIndexed  

true if the color space is indexed, false otherwise.

 
hiVal  

(Optional) This is used if isIndexed is true. Colors are specified by integers in the range 0 to hival.

 
colorSpace  

(Required for images, not allowed for image masks) A Cos object of the color space used for the image samples.

 
dataLen  

The length of the sample data in bytes.

 
comps  

The number of components in colorSpace. For instance, comps is 3 for an RGB color space.


Method Detail
PDImageColorSpaceGetIndexLookup()
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDImageColorSpaceGetIndexLookup(PDXObject xobj, ASUns8* data, ASInt32 dataLen)

(Obsolete, provided only for backwards compatibility) Gets the lookup table for an indexed color space. The table will contain the number of entries specified by the index size, and there will be 1 byte for each color component for each entry. The number of color components depends on the color space:

Color

Number of components

gray

1

RGB

3

CMYK

4

Lab

3

For additional information on indexed color space, see Section 4.5.5 in the PDF Reference. There is also some useful discussion in the PostScript Language Reference Manual under indexed color spaces.

Parameters

xobj — 

The image whose lookup table is obtained.

 
data — 

(Filled by the method) An array for the returned color space information.

 
dataLen — 

The length of data in bytes.

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 3832
PDImageGetAttrs() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDImageGetAttrs(PDXObject obj, PDImageAttrsP attrsP, ASInt32 attrsLen)

(Obsolete, provided only for backwards compatibility. Use PDEImageGetAttrs and/or Cos-level calls instead.) Gets the attributes of an image (for example, Type, Subtype, Name, Width, Height, BitsPerComponent, ColorSpace, Decode, Interpolate, or ImageMask).

Parameters

obj — 

The image whose attributes are obtained.

 
attrsP — 

(Filled by the method) A pointer to a PDImageAttrs structure containing the image attributes.

 
attrsLen — 

It must be sizeof(PDImageAttrs).

See Also

Since

PI_PDMODEL_VERSION >= 0x00020000

File: PDProcs.h
Line: 3802
PDImageSelAdjustMatrix() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDImageSelAdjustMatrix(void* callData, ASFixedMatrix newUserMatrix)

This method is obsolete and never called in Acrobat 8.

(Obsolete, provided only for backwards compatibility) Allows an image selector client to change the region of the page occupied by an image. It must only be used by image selector clients that return data for only the visible part of an image, to set the region of the page that the sub-image occupies. It must not be used otherwise.

This method only has an effect while displaying on the screen. It does nothing when printing.

The matrix set by this call remains in effect only for the current image. The Acrobat viewer automatically replaces it after the image has been drawn.

Parameters

callData — 

The value passed to the image selector as a parameter to PDImageSelectAlternate().

 
newUserMatrix — 

The matrix that will replace the imageToUserMatri (see PDImageSelGetGeoAttr()). The imageToDevMatrix is automatically calculated from newUserMatrix.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 7499
PDImageSelectAlternate() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

CosObj PDImageSelectAlternate(CosObj image, ASBool print, ASUns32 tickLimit, ASBool* cacheImageP, void* callData)

This method is obsolete and never called in Acrobat 8.

(Obsolete, provided only for backwards compatibility) Selects which Alternate image to use.

This method can do one of three things:

This method is called each time the Acrobat viewer draws an XObject image, regardless of whether the image XObject has an Alternates key.

You can replace this method with your own version, using HFTReplaceEntry().

Parameters

image — 

The Cos object for this image XObject's base image. Under some circumstances, PDImageSelectAlternate() can be called with an XObject type other than an image; for example, a form. Because of this, your code must check the XObject's subtype (you can use CosDictGet() to read the value of the XObject's Subtype key). If the subtype is not Image, your code must not modify the XObject, but simply return the CosObj that was passed to you.

 
print — 

true if printing, false if displaying.

 
tickLimit — 

The amount of time, in ticks, before the image selector must return control to the Acrobat viewer. This parameter is not relevant for image selectors that simply choose an existing alternate or create a new image XObject using Cos methods, but it is relevant for image selectors that create a new image XObject by calculating or reading data from a network or a slow device.

  • If tickLimit is zero, the image selector must not return control to the Acrobat viewer until the selector can provide the alternate image to use.

  • If tickLimit is nonzero, the image selector does not have to provide the image XObject within tickLimit, but it must raise the fileErrBytesNotReady exception if it cannot. This returns control to the Acrobat viewer and informs it that the data is not ready. The Acrobat viewer then calls the image selector periodically until the image selector returns the selected image XObject.

 
cacheImageP — 

If true, the image data returned to the Acrobat viewer is cached for future use. If false, it is not. Pass true if you expect your image data to remain valid for at least several calls to your client. Pass false if you expect your image data to change on the next call to your client. If you create and return a Cos stream object with an external file system and the stream's data will not always be the same, you must set cacheImageP to false. If you fail to do this, the Acrobat viewer may use cached image data when it should not.

 
callData — 

An opaque pointer containing data that must be passed in other image selector calls.

Returns

The image XObject to use. Returning a NULL Cos object (obtained using CosNewNull) tells the Acrobat viewer to skip this XObject entirely.

See Also

Exceptions

fileErrBytesNotReady

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 7345
PDImageSelGetDeviceAttr() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDImageSelGetDeviceAttr(void* callData, PDColorSpace* colorSpaceP, ASUns32* bitsPerPixelP, ASAtom* deviceTypeP)

This method is obsolete and never called in Acrobat 8.

(Obsolete, provided only for backwards compatibility) Gets device-related attributes for a particular image XObject. It must only be used from within an image selector client, since it returns information that is only valid in that context. This method can be used by an image selector client to obtain additional information to help the selector determine which alternate image to choose.

If an image is displayed on two devices simultaneously (for example, if the window containing the image is split across two monitors in a multi-monitor system), the values returned for colorSpaceP and bitsPerPixelP are each the maximum for the devices on which the image is currently displayed. For example, if the image is currently split across the following devices:

colorSpaceP would be DeviceRGB, because that is the highest color space on which the image is currently displayed.

bitsPerPixelP would be 8, because that is the highest bit depth on which the image is currently displayed.

Parameters

callData — 

(Filled by the method) The value passed to the image selector as a parameter to PDImageSelectAlternate().

 
colorSpaceP — 

(Filled by the method) The destination device's color space. It will be one of the following:

Value

Description

PDDeviceGray

Grayscale device

PDDeviceRGB

RGB device

PDDeviceCMYK

CMYK device

If the device has some other color space or its color space cannot be determined, PDDeviceRGB is returned.

 
bitsPerPixelP — 

(Filled by the method) The number of bits used for each pixel. For example, a device with 8 bits red, 8 bits green, and 8 bits blue would have a bitsPerPixel of 24. If bitsPerPixelP has a value of 0 (instead of the more standard 1, 8, or 24), the number of bits per pixel on the output device could not be determined.

 
deviceTypeP — 

(Filled by the method) The output device type. It will be one of the following:

Value

Description

Display

A display device such as a monitor

PostScript

A PostScript printer or PostScript file

nonPostScriptPrinter

A non-PostScript printer

See Also

PDImageSelAdjustMatrix (obsolete)
PDImageSelGetDeviceAttr (obsolete)
PDImageSelectAlternate (obsolete)

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 7470
PDImageSelGetGeoAttr() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDImageSelGetGeoAttr(void* callData, ASFixedRect* updateBBoxP, ASFixedMatrix* imageToDefaultMatrixP, ASFixedMatrix* imageToDevMatrixP)

This method is obsolete and never called in Acrobat 8.

(Obsolete, provided only for backwards compatibility) Requests geometry-related attributes of an image XObject. This method can be used by an image selector client to obtain additional information to help the selector determine which alternate image to choose.

Parameters

callData — 

(Filled by the method) The value passed to the image selector as a parameter to PDImageSelectAlternate().

 
updateBBoxP — 

(Filled by the method) The rectangle bounding the region of the page to update. This is the intersection of the visible portion of the page, any update regions, and any clipping paths that have been explicitly set in the PDF file. Its coordinates are specified in default user space.

 
imageToDefaultMatrixP — 

(Filled by the method) A matrix specifying the transformation from image space (the space in which all images are 1x1 units) to default user space (the space with 72 units per inch). It contains sufficient information for the image selector plug-in to determine the image's size and location on the page. For a normal page and image (an upright image on a non-rotated page), the following is true:

  • imageToDefaultMatrixP->a is equal to the image horizontal size in 1/72 of an inch units.

  • imageToDefaultMatrixP->b = 0

  • imageToDefaultMatrixP->c = 0

  • imageToDefaultMatrixP->d is equal to the image vertical size in 1/72 of an inch units.

  • imageToDefaultMatrixP->h is equal to the left edge of image.

  • imageToDefaultMatrixP->v is equal to the bottom edge of the image.

In other words, this matrix provides the image's height, width, and position on the page, all in units of points (compare to imageToDefaultMatrixP). The intersection of the rectangle obtained by transforming a 1x1 unit rectangle (the image) through imageToDeviceMatrixP and the updateBBoxP rectangle is the region of the image that is actually drawn. This is the region of the image for which data is required.

 
imageToDevMatrixP — 

(Filled by the method) A matrix specifying the transformation from image space (the space in which all images are 1x1 unit) to device space (the space in which one unit is one pixel). This matrix provides the image's height, width, and position on the page, all in pixels (compare to imageToDefaultMatrixP).

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 7401