DynaPDF Manual - Page 531

Previous Page 530 Index Next Page 532

Function Reference

Page 531 of 750

The variables which make up the graphics state are normally stored in a structure or class so that the

graphics state can be saved and restored if corresponding operators are executed.

If the TSaveGraphicState callback function is executed, the application must create a copy of the

current graphics state and push it onto the graphics state stack. In the corresponding

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

Coordinates in PDF are defined in a device independent coordinate space which is called user space.

The positive x-axis extends horizontally to the right and the positive y-axis vertically upward, as in

standard mathematical practice (subject to alteration by the orientation of the page (see

GetOrientation()).

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

Previous topic: The Graphics State

Next topic: Working with Transformation Matrices