View Surfaces, (Sub-)Pages, Viewports and Windows
Prev | Chapter 3. Advanced Use of PLplot | Next

## View Surfaces, (Sub-)Pages, Viewports and Windows

There is a whole hierarchy of coordinate systems associated with any PLplot graph. At the lowest level a device provides a view surface (coordinates in mm's) which can be a terminal screen or a sheet of paper in the output device. `plinit` or `plstar` (or `plstart`) makes that device view surface accessible as a page or divided up into sub-pages (see `plssub`) which are accessed with `pladv`. Before a graph can be drawn for a subpage, the program must call appropriate routines in PLplot to define the viewport for the subpage and a window for the viewport. A viewport is a rectangular region of the subpage which is specified in normalized subpage coordinates or millimetres. A window is a rectangular region of world-coordinate space which is mapped directly to its viewport. (When drawing a graph, the programmer usually wishes to specify the coordinates of the points to be plotted in terms of the values of the variables involved. These coordinates are called world coordinates, and may have any floating-point value representable by the computer.)

Although the usual choice is to have one viewport per subpage, and one window per viewport, each subpage can have more than one (possibly overlapping) viewport defined, and each viewport can have more than one window (more than one set of world coordinates) defined.

### Defining the Viewport

After defining the view surface and subpage with the appropriate call to `plinit` or `plstar` (or `plstart`) and a call to `pladv` it is necessary to define the portion of this subpage which is to be used for plotting the graph (the viewport). All lines and symbols (except for labels drawn by `plbox`, `plmtex` and `pllab`) are clipped at the viewport boundaries.

Viewports are created within the current subpage. If the division of the output device into equally sized subpages is inappropriate, it is best to specify only a single subpage which occupies the entire output device (by using `plinit` or by setting `nx = 1` and `ny = 1` in `plstar` or `plstart`), and use one of the viewport specification subroutines below to place the plot in the desired position on the page.

The routines `plvpor`, `plsvpa`, `plvasp`, `plvpas`, and `plvsta` may be used to specify the limits of the viewport within the current subpage. The `plvpor` routine specifies the viewport limits in normalized subpage coordinates. The `plsvpa` routine (often used in conjunction with the `plgspa` routine which returns the physical limits of the current subpage) specifies the viewport limits in physical coordinates. The routine `plvasp` specifies the largest viewport with the given aspect ratio that fits in the current subpage while allowing for a standard margins on each side of the viewport. The routine `plvpas` specifies the largest viewport with the given aspect ratio that fits in a region that is specified by normalized subpage coordinates as with `plvpor`. (The routine `plvpas` is functionally equivalent to `plvpor` when the specified aspect ratio is set to zero.) The `plvsta` routine specifies the largest viewport that fits in the current subpage while allowing for a standard margins on each side of the viewport. This standard viewport is that used by `plenv` (See the section called “Setting up a Standard Window”).

### Defining the Window

The routine `plwind` is used to map the world coordinate rectangle into the viewport rectangle. If the order of either the X limits or Y limits is reversed, the corresponding axis will point in the opposite sense, (i.e., right to left for X and top to bottom for Y). The window must be defined before any calls to the routines which actually draw the data points. Note however that `plwind` may also be called to change the window at any time. This will affect the appearance of objects drawn later in the program, and is useful for drawing two or more graphs with different axes on the same viewport.

### Annotating the Viewport

The routine `plbox` is used to specify how much (if any) of the frame is drawn around the viewport and to control the positions of the axis subdivisions and numeric labels. In addition, non-default lengths of major and minor ticks on the axes may be set up by calls to the routines `plsmaj` and `plsmin`.

The routine `pllab` is used to specify text labels for the bottom, left hand side and top of the viewport. These labels are not clipped, even though they lie outside the viewport (but they are clipped at the subpage boundaries). `pllab` actually calls the more general routine `plmtex` which can be used for plotting labels at any point relative to the viewport.

The appearance of axis labels may be further altered by auxiliary calls to `plprec`, `plschr`, `plsxax`, `plsyax`, and `plszax`. The routine `plprec` is used to set the number of decimal places precision for axis labels, while `plschr` modifies the heights of characters used for the axis and graph labels. Routines `plsxax`, `plsyax`, and `plszax` are used to modify the `digmax` setting for each axis, which affects how floating point labels are formatted.

The `digmax` variable represents the maximum field width for the numeric labels on an axis (ignored if less than one). If the numeric labels as generated by PLplot exceed this width, then PLplot automatically switches to floating point representation. In this case the exponent will be placed at the top left for a vertical axis on the left, top right for a vertical axis on the right, and bottom right for a horizontal axis.

For example, let's suppose that we have set `digmax = 5` via `plsyax`, and for our plot a label is generated at `y = 0.0000478`. In this case the actual field width is longer than `digmax`, so PLplot switches to floating point. In this representation, the label is printed as simply 4.78 with the 10-5 exponent placed separately.

The determination of maximum length (i.e. `digmax`) for fixed point quantities is complicated by the fact that long fixed point representations look much worse than the same sized floating point representation. Further, a fixed point number with magnitude much less than one will actually gain in precision when written as floating point. There is some compensation for this effect built into PLplot, thus the internal representation for number of digits kept (`digfix`) may not always match the user's specification (via `digmax`). However, it will always be true that `digfix ≤ digmax`. The PLplot defaults are set up such that good results are usually obtained without user intervention.

Finally, after the call to `plbox`, the user may call routines `plgxax`, `plgyax`, or `plgzax` to obtain information about the window just drawn. This can be helpful when deciding where to put captions. For example, a typical usage would be to call `plgyax` to get the value of `digits`, then offset the y axis caption by that amount (plus a bit more) so that the caption “floats” just to the outside of the numeric labels. Note that the `digits` value for each axis for the current plot is not correct until after the call to `plbox` is complete.

### Setting up a Standard Window

Having to call `pladv`, `plvpor`, `plwind` and `plbox` is cumbersome for drawing simple graphs so as an alternative we have implemented `plenv` that combines all four of these capabilities in one routine using the standard viewport and a limited subset of the capabilities of `plbox`.

Prev | Up | Next
Adding FreeType Library Support to Bitmap Drivers | Home | Setting Line Attributes