9.2.6 Drawing on a physical page

GNU libplot can draw graphics over an entire page of paper, not merely within the graphics display or `viewport' that it normally uses.

The default viewport used by an Illustrator, Postscript, Fig, or PCL Plotter is a square region centered on the page. The size of the default viewport depends on the PAGESIZE parameter, which may be "letter", "a4", etc. See Page and Viewport Sizes. For example, the default viewport on a letter-sized page, which has width 8.5in and height 11in, is a square of side 8in.

However, you may specify different dimensions for the viewport, and a different position as well. In particular, you may specify a viewport that covers the entire page. This would be accomplished by setting PAGESIZE to, for example, "letter,xsize=8.5in,ysize=11in,xorigin=0in,yorigin=0in". "xorigin" and "yorigin" specify the location of the lower left corner of the viewport, relative to the lower left corner of the page.

With this choice for the viewport, the entire page is in principle imageable. For full-page drawing, it is convenient to define a user coordinate system in terms of which the lower left corner of the page is (0,0), and in which the units are physical inches or centimeters. To do so, you would use appropriate arguments when invoking the space operation on the Plotter. The following program shows how the space operation would be invoked.

     #include <stdio.h>
     #include <plot.h>
     
     int main()
     {
       plPlotter *plotter;
       plPlotterParams *plotter_params;
     
       /* set page size parameter, including viewport size and location */
       plotter_params = pl_newplparams ();
       pl_setplparam (plotter_params, "PAGESIZE",
                      "letter,xsize=8.5in,ysize=11in,xorigin=0in,yorigin=0in");
     
       /* create a Postscript Plotter with the specified parameter */
       plotter = pl_newpl_r ("ps", stdin, stdout, stderr, plotter_params);
     
       pl_openpl_r (plotter);                /* begin page of graphics */
       pl_fspace_r (plotter,
                    0.0, 0.0, 8.5, 11.0);   /* set user coor system */
     
       pl_fontname_r (plotter, "Times-Bold");
       pl_ffontsize_r (plotter, 0.5);        /* font size = 0.5in = 36pt */
     
       pl_fmove_r (plotter, 1.0, 10.0);
       pl_alabel_r (plotter, 'l', 'x', "One inch below the top");
       pl_fline_r (plotter, 1.0, 10.0, 7.5, 10.0);
     
       pl_fmove_r (plotter, 7.5, 1.0);
       pl_alabel_r (plotter, 'r', 'x', "One inch above the bottom");
       pl_fline_r (plotter, 1.0, 1.0, 7.5, 1.0);
     
       pl_closepl_r (plotter);               /* end page of graphics */
       pl_deletepl_r (plotter);              /* delete Plotter */
       return 0;
     }

The program will print two strings and draw the baseline for each. The first string will be left-justified at position (1.0,11.0), which is one inch below the top of the page. The second string will be right-justified at position (7.5,1.0), which is one inch above the bottom of the page. For both strings, the 'x' argument of pl_alabel_r specifies the vertical positioning: it requests that the baseline of the string, rather than (say) its top or bottom, be positioned at the current vertical position.

The preceding discussion and sample program dealt with the portrait orientation of the printed page, which is the default. Drawing in landscape orientation is only slightly more complicated. For this, the viewport would be rotated on the page by setting the Plotter parameter ROTATION. Its default value is "0" (or "no"), but any other rotation angle may be specified. To obtain landscape orientation, one would specify "90" (for historical reasons, "yes" is equivalent to "90"). The following program is a modified version of the preceding, showing how a landscape orientation would be produced.

     #include <stdio.h>
     #include <plot.h>
     
     int main()
     {
       plPlotter *plotter;
       plPlotterParams *plotter_params;
     
       /* set Plotter parameters */
       plotter_params = pl_newplparams ();
       pl_setplparam (plotter_params, "PAGESIZE",
                      "letter,xsize=8.5in,ysize=11in,xorigin=0in,yorigin=0in");
       pl_setplparam (plotter_params, "ROTATION", "90");
     
       /* create a Postscript Plotter with the specified parameters */
       plotter = pl_newpl_r ("ps", stdin, stdout, stderr, plotter_params);
     
       pl_openpl_r (plotter);                /* begin page of graphics */
       pl_fspace_r (plotter,
                    0.0, 0.0, 11.0, 8.5);   /* set user coor system */
     
       pl_fontname_r (plotter, "Times-Bold");
       pl_ffontsize_r (plotter, 0.5);        /* font size = 0.5in = 36pt */
     
       pl_fmove_r (plotter, 1.0, 7.5);
       pl_alabel_r (plotter, 'l', 'x', "One inch below the top");
       pl_fline_r (plotter, 1.0, 7.5, 10.0, 7.5);
     
       pl_fmove_r (plotter, 10.0, 1.0);
       pl_alabel_r (plotter, 'r', 'x', "One inch above the bottom");
       pl_fline_r (plotter, 1.0, 1.0, 10.0, 1.0);
     
       pl_closepl_r (plotter);               /* end page of graphics */
       pl_deletepl_r (plotter);              /* delete Plotter */
       return 0;
     }

In this example the viewport is the same centered 8in by 8in square, but it is rotated by 90 degrees counterclockwise; or equivalently, the graphics within it are rotated. As in the preceding example, the call to pl_fspace_r sets up the user coordinate system so that the units are physical inches. The origin of coordinates is now the lower right corner of the page. The x and y coordinates increase upward and to the left, respectively.