9.4.4 Mapping functions

The following are the “mapping functions” in libplot. When invoked on a Plotter, they affect the affine transformation it employs to map the user coordinate system to the device coordinate system. That is, they affect the transformation matrix attribute of objects subsequently drawn on the graphics display.

The names of these functions resemble those of the corresponding functions in the Postscript language. For information on how to use them to draw graphics efficiently, consult any good book on Postscript programming, or the Postscript Language Reference Manual.

Each of these functions, if called, terminates and draws the path under construction (if any), as if endpath had been called.

In the current C binding, each of these functions takes a pointer to a plPlotter as its first argument. Also in the current C binding, the name of each function begins with "pl_" and ends with "_r". ("_r" stands for `revised' or `reentrant'.) For information on older C bindings, see Older C APIs. In the C++ binding, these are member functions of the Plotter class and its subclasses, and the prefix and suffix are not used.

int fsetmatrix (double m0, double m1, double m2, double m3, double tx, double ty);

Use the Postscript-style transformation matrix [m0 m1 m2 m3 tx ty] as the transformation matrix from user space to NDC (normalized device coordinate) space. This matrix determines the transformation matrix from user space to unnormalized device space, i.e., sets the transformation matrix attribute that will be used when subsequently drawing objects on the graphics display.

In NDC space, the graphics display (i.e., viewport) has corners (0,0), (1,0), (1,1), and (0,1). For information on the size of the graphics display in physical units, see Page and Viewport Sizes.

The default transformation matrix from user space to NDC space is [1 0 0 1 0 0], which means that by default, user coordinates are the same as NDC coordinates. This transformation matrix is also altered by space, fspace, space2, and fspace2, and by the following functions.

int fconcat (double m0, double m1, double m2, double m3, double tx, double ty);

Modify the transformation matrix from user space to NDC space by pre-multiplying it by the matrix [m0 m1 m2 m3 tx ty]. Equivalently, apply the linear transformation defined by the two-by-two matrix [m0 m1 m2 m3] to the user coordinate system, and then translate by tx units in the x direction and ty units in the y direction.

fconcat is a wrapper around the more fundamental fsetmatrix function. The following three functions (frotate, fscale, ftranslate) are convenience functions that are special cases of fconcat.

int frotate (double theta);

Modify the transformation matrix from user space to NDC space by pre-multiplying it by the matrix [cos(theta) sin(theta) −sin(theta) cos(theta) 0 0]. Equivalently, rotate the user coordinate system axes about their origin by theta degrees counterclockwise, with respect to their former orientation. The position of the user coordinate origin and the size of the x and y units remain unchanged.

int fscale (double sx, double sy);

Modify the transformation matrix from user space to NDC space by pre-multiplying it by the matrix [sx 0 0 sy 0 0]. Equivalently, make the x and y units in the user coordinate system be the size of sx and sy units in the former user coordinate system. The position of the user coordinate origin and the orientation of the coordinate axes are unchanged.

int ftranslate (double tx, double ty);

Modify the transformation matrix from user space to NDC space by pre-multiplying it by the matrix [0 0 0 0 tx ty]. Equivalently, move the origin of the user coordinate system by tx units in the x direction and ty units in the y direction, relative to the former user coordinate system. The size of the x and y units and the orientation of the coordinate axes are unchanged.