Xojo Conferences
MBSOct2019CologneDE

DynaPDF Manual - Page 543

Previous Page 542   Index   Next Page 544

Function Reference
Page 543 of 767
TRestoreGraphicState callback function, the last element of the graphics state stack must be popped
and copied to the current graphics state.
A correct handling of the graphics state is always required if the application needs to compute
coordinates of graphic objects.
Note also that the graphics state can be saved and restored very often. The maximum allowed
nesting level of save/restore graphics state operators in PDF is 28. The application should not depend
on this limit but it can be used for optimizations, e.g. to create a graphics state cache.
Coordinate Spaces
The coordinates of a page extend from left to right and from bottom to top (subject to alteration by
the orientation of the page (see GetOrientation()). Note that SetPageCoords() does not affect the
coordinates returned by the content parser.
The length of a unit in default user space is 1/72 inch. The visible area of a page is defined by the crop
box of the page, or if absent, by the media box (see GetBBox() for further information). The media
box represents the coordinate system in which the page is defined.
In addition to user space, PDF uses a variety of other coordinate spaces for specialized purposes:
Text coordinates are defined in text space. The transformation from text space to user space is
defined by a text matrix which is provided in the text callback functions. PDF defines also
several text related positioning parameters in the graphics state. However, to make the usage
easier DynaPDF pre-computes the text transformation matrix so that no further calculations
are required to transform the text space to user space. Note that the current leading, which
specifies the distance between two text lines, is already considered in the text matrix. The text
matrix is always provided. To transform text space to user space the text matrix must be
multiplied with the one of the current graphics state.
Images are defined in image space. An image in PDF is always one unit wide and one unit
high in user space, regardless of the number of samples in the image. The mapping to the
visible region in user space is achieved by temporarily altering the current transformation
matrix. The image position, as well as the width and height must be computed from the
current transformation matrix (take a look at the description of the TInsertImage callback
function for further information).
Templates (Form XObjects in PDF terms) are defined in form space. The transformation from
form space to user space is defined by a form matrix that is provided in the TBeginTemplate
callback function. However, the matrix parameter of the callback function is optional and can
be set to NULL. Null means the matrix is set to the identity matrix. To transform form space
to user space the form matrix must be multiplied with the one of the current graphics state.
Patterns are defined in pattern space. The transformation from pattern space to the initial
default user space of the object in which it is used is provided in the TBeginPattern callback
function. However, the matrix parameter of the callback function is optional and can be set to
NULL. Null means the matrix is set to the identity matrix. Note that patterns are treated like
 

Previous topic: Coordinate Spaces

Next topic: Helper Functions