46
186
Chapter 7: API Reference for PDFlib, PDI, and PPS
so deprecated) it contains a file name on the viewing system, and not a local file name.
Only 8-bit characters are supported in the image file name; Unicode or embedded null
characters are not supported.
reserved (C language binding only.) Reserved, must be 0.
optlist An option list (see Section 3.1.4, »Option Lists«, page 44) specifying image-relat-
ed properties according to Table 7.22.
Returns An image handle which can be used in subsequent image-related calls. The return value
must be checked for -1 (in PHP: 0) which signals an error. In order to get more detailed
information about the nature of an image-related problem (wrong image file name, un-
supported format, bad image data, etc.), set the imagewarning parameter or option to
true (see Table 7.21 and Table 7.22). The returned image handle can not be reused across
multiple PDF documents.
Details This function opens and analyzes a raster graphics file in one of the supported formats
as determined by the imagetype parameter. PDFlib will open the image file with the pro-
vided filename, process the contents, and close the file before returning from this call.
Although images can be placed multiply within a document (see PDF_fit_image( )), the
actual image file will not be kept open after this call.
If imagetype = raw or ccitt, the width, height, components, and bpc options must be sup-
plied since PDFlib cannot deduce those from the image data. The user is responsible for
supplying option values which actually match the image. Otherwise corrupt PDF out-
put may be generated, and Acrobat may respond with the message Insufficient data for
an Image.
If imagetype = raw, the length of the supplied image data must be equal to [width x
components x bpc / 8] x height bytes, with the bracketed term adjusted upwards to the
next integer. The image samples are expected in the standard PostScript/PDF ordering,
i.e., top to bottom and left to right (assuming no coordinate transformations have been
applied). The polarity of the pixel values is as discussed in Section 3.3.1, »Color and Color
Spaces«, page 59. Even if bpc is not 8, each pixel row begins on a byte boundary, and col-
or values must be packed from left to right within a byte. Image samples are always in-
terleaved, i.e., all color values for the first pixel are supplied first, followed by all color
values for the second pixel, and so on.
Scope If the inline option is not provided, the scope is document, page, font, and this function
must always be paired with a matching PDF_close_image( ) call. Loading images in
document or font scope instead of page scope offers slight output size advantages.
If the inline option is provided, the scope is page, pattern, template, glyph, and PDF_close_
image( ) must not be called.
PDF/X All PDF/X conformance levels: GIF and LZW-compressed TIFF images are not allowed.
PDF/X-1 and PDF/X-1a: RGB images are not allowed.
PDF/X-3: Grayscale images require that the defaultgray parameter must have been set
before unless the PDF/X output intent is a grayscale or CMYK device. RGB images
require that the defaultrgb parameter must have been set before unless the PDF/X
output intent is an RGB device. CMYK images require that the defaultcmyk parameter
must have been set before unless the PDF/X output intent is a CMYK device.
Params imagewidth, imageheight, resx, resy, imagewarning
89
7.6 Image and Template Functions 187
Table 7.22 Options for PDF_load_image( )
key
type
explanation
bitreverse
boolean
(Only for imagetype = ccitt) If true, do a bitwise reversal of all bytes in the
compressed data. Default: false.
bpc
integer
(Only for imagetype = raw, and required in this case) The number of bits per
component; must be 1, 2, 4, or 8.
colorize
spot color
handle
Colorize the image with a spot color handle, which must have been retrieved with
PDF_makespotcolor( ). The image must be a grayscale image with 1, 2, 4, or 8 bits
color depth.
components
integer
(Only for imagetype=raw, and required in this case) The number of image
components (channels); must be 1, 3, or 4.
height
integer
(Only for imagetype = raw and ccitt, and required in this case) The height of the
image in pixels.
honor-
iccprofile
boolean
(Only for imagetype = jpeg, png, and tiff) Read an embedded ICC profile (if any)
and apply it to the image. Default: the value of the global honoriccprofile
parameter.
iccprofile
icc handle
(Only for imagetype = jpeg, png, and tiff) Handle of the ICC profile which will be
applied to the image. Default: the value of the global image:iccprofile parameter.
ignoremask
boolean
Ignore any transparency information which may be present in the image. Default:
false.
image-
warning
boolean
Enable exceptions when the image cannot be opened. Default: the value of the
global imagewarning parameter.
inline
boolean
(Only for imagetype = ccitt, jpeg, and raw) If true, the image will be written
directly into the content stream of the page, pattern, template, or glyph
description (see Section 5.1.1, »Basic Image Handling«, page 109).
interpolate
boolean
Enable image interpolation in Acrobat to improve the appearance on screen and
paper. This is especially useful for bitmap images to be used as glyph descriptions
in Type 3 fonts. Default: false.
invert
boolean
Invert the image (swap light and dark colors). This can be used as a workaround
for certain images which are interpreted differently by different applications.
Default: false.
K
integer
(Only for imagetype = ccitt) CCITT compression parameter for encoding scheme
selection. -1 indicates G4 compression; 0 indicates one-dimensional G3
compression (G3-1D); 1 indicates mixed one- and two-dimensional compression
(G3, 2-D) as supported by PDF. Default: 0.
mask
boolean
The image is going to be used as a mask (see Section 5.1.3, »Image Masks and
Transparency«, page 112). This is required for 1-bit masks, but optional for masks
with more than 1 bit per pixel. However, masks with more than 1 bit require
PDF 1.4. Default is false. There are two uses for masks:
Masking another image: the returned image handle may be used in subsequent
calls for opening another image and can be supplied for the »masked« option.
Placing a colorized transparent image: treat the 0-bit pixels in the image as
transparent, and colorize the 1-bit pixels with the current fill color.
masked
image
handle
An image handle for an image which will be applied as a mask to the current
image. The integer is an image handle which has been returned by a previous call
to PDF_load_image( ) (with the »mask« option if it is a 1-bit mask), and has not
yet been closed. In PDF 1.3 compatibility mode the image handle must refer to a 1-
bit image since soft masks are only supported in PDF 1.4.
page
integer
(Only for imagetype = gif and tiff) Extract the image with the given number from
a multi-page image file. The first image has the number 1. Default: 1.
49
188
Chapter 7: API Reference for PDFlib, PDI, and PPS
void PDF_close_image(PDF *p, int image)
Close an image.
image A valid image handle retrieved with PDF_load_image( ).
Details This function only affects PDFlib’s associated internal image structure. If the image has
been opened from file, the actual image file is not affected by this call since it has al-
ready been closed at the end of the corresponding PDF_load_image( ) call. An image han-
dle cannot be used any more after it has been closed with this function, since it breaks
PDFlib’s internal association with the image.
Scope document, page, font; must always be paired with a matching call to PDF_load_image( )
unless the inline option has been used.
void PDF_fit_image(PDF *p, int im, float x, float y, const char *optlist)
Place an image or template at (x, y) with various options.
image A valid image or template handle retrieved with one of the PDF_load_image*( )
or PDF_begin_template( ) functions.
x, y The coordinates of the reference point in the user coordinate system where the
image or template will be located, subject to various options.
optlist An option list (see Section 3.1.4, »Option Lists«, page 44) specifying placement
details according to Table 7.23.
Details The image or template (collectively referred to as an object below) will be placed relative
to the reference point (x, y). By default, the lower left corner of the object will be placed
at the reference point. However, the orientate, boxsize, position, and fitmethod options
can modify this behavior. By default, an image will be scaled according to its resolution
value(s). This behavior can be modified with the dpi, scale, and fitmethod options.
Scope page, pattern, template, glyph (only if the Type 3 font’s colorized option is true, or if the
image is a mask); this function can be called an arbitrary number of times on arbitrary
pages, as long as the image handle has not been closed with PDF_close_image( ).
rendering-
intent
keyword
The rendering intent for the image. See Table 3.8 for a list of possible keywords
and their meaning. Default: the value of the global renderingintent parameter.
reftype
keyword
(Deprecated; only for imagetype = ccitt, jpeg, and raw) One of direct (for image
data to be read from a file), fileref or url to specify image data via a reference to a
file on the viewing system or an URL. The following options are required for
reftype=url or fileref: width, height, components, bpc; the following options will
be ignored for reftype=url or fileref: bitreverse, honoriccprofile, inline. Default:
direct.
width
integer
(Only for imagetype = raw and ccitt, and required in this case) The width of the
image in pixels.
Table 7.22 Options for PDF_load_image( )
key
type
explanation
79
7.6 Image and Template Functions 189
Table 7.23 Options for PDF_fit_image( ) and PDF_fit_pdi_page( )
key
type
explanation
adjustpage
boolean
Adjust the dimensions of the current page to the object such that the upper right
corner of the page coincides with the upper right corner of the object plus (x, y).
With the value 0 for the position option the following useful cases shall be noted:
x >= 0 and y >= 0: the object is surrounded by a white margin. This margin has
thickness y in horizontal direction and thickness x in vertical direction.
x < 0 and y < 0: horizontal and vertical strips will be cropped from the image.
This option is only effective in scope page, and must not be used when the
topdown parameter has been set to true. Default: false.
blind
boolean
If true, all positioning and scaling calculations will be done, but the object will not
be placed on the output page. This is useful for processing the blocks on a page
without actually using the page’s contents. Default: false.
boxsize
float list
Two values specifying the width and height of a box, relative to which the object
will be placed and possibly scaled. The lower left corner of the box coincides with
the reference point (x, y). Placing the image and fitting it into the box is controlled
by the position and fitmethod options. If width = 0, only the height is considered;
If height = 0, only the width is considered. In these cases the object will be placed
relative to the vertical line from (x, y) to (x, y+height), or the horizontal line from
(x, y) to (x+width, y), respectively. Default: {0 0}.
dpi
float list
One or two values specifying the desired image resolution in pixels per inch in
horizontal and vertical direction. If a single value is supplied it will be used for
both directions. With the value o the image’s internal resolution will be used if
available, or 72 dpi otherwise. As an alternative to the value 0, the keyword
internal can be supplied. This option will be ignored for templates and PDF pages,
or if the fitmethod option has been supplied with one of the keywords meet, slice,
or entire. Default: internal.
fitmethod
keyword
Specifies the method used to fit the object into the specified box. This option will
be ignored if no box has been specified. Default: nofit.
nofit
Position the object only, without any scaling or clipping.
clip
Position the object, and clip it at the edges of the box.
meet
Position the object according to the position option, and scale it such
that it entirely fits into the box while preserving its aspect ratio.
Generally at least two edges of the object will meet the corresponding
edges of the box. The dpi and scale options are ignored.
auto
This method tries to fit the object into the box automatically. In detail:
Same as nofit if the object fits into the box. Otherwise a scaling factor is
calculated such that the object fits into the box. If this factor is larger
than 0.75 the object is distorted to fit intothe box, otherwise the meet
method is applied.
slice
Position the object according to the position option, and scale it such
that it entirely covers the box, while preserving the aspect ratio and
making sure that at least one dimension of the object is fully contained
in the box. Generally parts of the object’s other dimension will extend
beyond the box, and will therefore be clipped. The dpi and scale options
are ignored.
entire
Position the object according to the position option, and scale it such
that it entirely covers the box. Generally this method will distort the
object. The dpi and scale options are ignored.
orientate
keyword
Specifies the desired orientation of the object when it is placed. Default: north.
north
upright
east
pointing to the right
south
upside down
west
pointing to the left
46
190
Chapter 7: API Reference for PDFlib, PDI, and PPS
7.6.2 Templates
int PDF_begin_template(PDF *p, float width, float height)
Start a template definition.
width, height The dimensions of the template’s bounding box in points.
Returns A template handle which can be used in subsequent image-related calls, especially PDF_
fit_image( ). There is no error return.
Details Hypertext functions and functions for opening images must not be used during a
template definition, but all text, graphics, and color functions can be used.
Scope document; this function starts template scope, and must always be paired with a
matching PDF_end_template( ) call.
void PDF_end_template(PDF *p)
Finish a template definition.
Scope template; this function terminates template scope, and must always be paired with a
matching PDF_begin_template( ) call.
7.6.3 Deprecated Functions
int PDF_open_image_file(PDF *p,
const char *imagetype, const char *filename, const char *stringparam, int intparam)
Deprecated, use PDF_load_image( ) with the colorize, ignoremask, invert, mask, masked, and
page options instead.
position
float list
One or two values specifying the position of the reference point (x, y) within the
object with {0 0} being the lower left corner of the object, and {100 100} the upper
right corner. If the boxsize option has been specified, the position option also
specifies the positioning of the box. The values are expressed as percentages of the
object’s width and height. If both percentages are equal it is sufficient to specify a
single float value. Some examples: 0 or {0 0} means lower left corner; {50 100}
means middle of the top edge; 50 or {50 50} means the center of the object.
Default: 0.
rotate
float
Rotate the coordinate system, using the reference point as center and the speci-
fied value as rotation angle in degrees. This results in the box and the object being
rotated. The rotation will be reset when the object has been placed. Default: 0.
scale
float list
Scale the object in horizontal and vertical direction by the specified scaling factors
(not percentages). If both factors are equal it is sufficient to specify a single float
value. This option will be ignored if the fitmethod option has been supplied with
one of the keywords meet, slice, or entire. Default: 1
Table 7.23 Options for PDF_fit_image( ) and PDF_fit_pdi_page( )
key
type
explanation
Documents you may be interested
Documents you may be interested
