# 4. Primitives

## 4.1 Introduction

Having selected a view surface and defined the viewport and the window, we are ready to draw the substance of the image that is to appear within the viewport. This chapter describes the most basic routines, called primitives, that can be used for drawing elements of the image. There are four different sorts of primitive: lines, graph-markers, text, and area fill. Chapter 5 explains how to change the attributes of these primitives, e.g., color, line-style, text font; and Chapter 6 describes some higher-level routines that simplify the composition of images that would require a large number of calls to the primitive routines.

The primitive routines can be used in any combination and order after the viewport and window have been defined. They all indicate where the primitive is to appear on the view surface by specifying world coordinates. See the subroutine descriptions in Appendix A for more details.

## 4.2 Clipping

The primitives are ``clipped'' at the edge of the viewport: any parts of the image that would appear outside the viewport are suppressed. The various primitives behave slightly differently. A line is clipped where it crosses the edge of the viewport. A graph marker is plotted if the center (the point marked) lies within or on the edge of the viewport; otherwise it is suppressed. Text, which is usually used for annotation, is not clipped (except at the edge of the view surface. A filled area is clipped at the edge of the viewport.

## 4.3 Lines

The primitive line-drawing routine is `PGLINE`. This draws one or more connected straight-line segments (generally called a polyline in computer graphics). It has three arguments: the number (`N`) of points defining the polyline, and two arrays (`XPTS` and `YPTS`) containing the world x and y-coordinates of the points. The polyline consists of N-1 straight-line segments connecting points 1--2, 2--3, ..., (N-1)--N:
```      CALL PGLINE (N, XPTS, YPTS)
```
The two routines `PGMOVE` and `PGDRAW` are even more primitive than `PGLINE`, in the sense that any line graph can be produced by calling these two routines alone. In general, `PGLINE` should be preferred, as it is more modular. `PGMOVE` and `PGDRAW` are provided for those who are used to Calcomp-style plotting packages. `PGMOVE` moves the plotter ``pen'' to a specified point, without drawing a line (``pen up''). It has two arguments: the world-coordinates of the required new pen position. `PGDRAW` moves the plotter ``pen'' from its current position (defined by the last call of `PGMOVE` or `PGDRAW`) to a new point, drawing a straight line as it goes (``pen down''). The above call to `PGLINE` could be replaced by the following:
```
CALL PGMOVE (XPTS(1), YPTS(1))
DO I=2,N
CALL PGDRAW (XPTS(I), YPTS(I))
END DO
```

## 4.4 Graph Markers

A Graph Marker is a symbol, such as a cross, dot, or circle, drawn on a graph to mark a specific point. Usually the symbol used will be chosen to be symmetrical with a well-defined center. The routine `PGPT` draws one or more graph markers (sometimes called a polymarker). It has four arguments: the number (`N`) of points to mark, two arrays (`XPTS` and `YPTS`) containing the world x and y-coordinates of the points, and a number (`NSYM`) identifying the symbol to use:
```      CALL PGPT (N, XPTS, YPTS, NSYM)
```
The symbol number can be: -1, to draw a dot of the smallest possible size (one pixel); 0--31, to draw any one of the symbols in Figure 4.1; -3 - -8, to draw regular polygon with 3--8 sides; 33--127, to draw the corresponding ASCII character (the character is taken from the currently selected text font); or >127, to draw one of the Hershey symbols from Appendix B. The Fortran `ICHAR` function can be used to obtain the ASCII value; e.g., to use letter F :
```
CALL PGPT (1, 0.5, 0.75, ICHAR('F') )
```

## 4.5 Text

The Text primitive routine is used for writing labels and titles on the image. It converts an internal computer representation of the text (ASCII codes) into readable text. The simplest routine for writing text is `PGTEXT`, which writes a horizontal character string starting at a specific (x,y) world coordinate position, e.g.,
```      CALL PGTEXT (X, Y, 'A text string')
```
`PGTEXT` is actually a simplified interface to the more general primitive routine `PGPTXT`, which allows one to change orientation and justification of the text, e.g.,
```      CALL PGPTXT (X, Y, 45.0, 0.5, 'A text string')
```
writes the text at an angle of 45 degrees to the horizontal, centered at (x,y).

Both `PGTEXT` and `PGPTXT` require the position of the text string to be specified in world coordinates. When annotating a graph, it is usually more convenient to position the text relative to the edge of the viewport, rather than in world-coordinate space. The routine `PGMTXT` is provided for this, and `PGLAB` provides a simple interface to `PGMTXT` for the normal job of annotating an (x,y) graph.

The appearance of text can be altered by specifying a number of attributes, described in the next chapter. In particular, the character size and character font can be changed. Figure 4.2 illustrates some of the possibilities.

To include one of the graph marker symbols (0--32) in a text string, use the Fortran `CHAR` function, e.g.,

```      CALL PGTEXT (X, Y, 'Points marked with '//CHAR(17))
```

### 4.5.1 Escape Sequences

The routine `PGPTXT` (and all the PGPLOT routines which call it, e.g., `PGTEXT`, `PGLAB`) allows one to include escape sequences in the text string to be plotted. These are character-sequences that are not plotted, but are interpreted as instructions to change font, draw superscripts or subscripts, draw non-ASCII characters (e.g., Greek letters), etc. All escape sequences start with a backslash character (`\`). The following escape sequences are defined (the letter following the `\` may be either upper or lower case):

 \u start a superscript, or end a subscript \d start a subscript, or end a superscript (note that \u and \d must always be used in pairs) \b backspace (i.e., do not advance text pointer after plotting the previous character) \fn switch to Normal font (1) \fr switch to Roman font (2) \fi switch to Italic font (3) \fs switch to Script font (4) \\ backslash character (\) \x multiplication sign (×) \. centered dot (·) \A ångström symbol (Å) \gx greek letter corresponding to roman letter x, as indicated in Figure 4.3 \mn\mnn graph marker number n or nn (1-31), as indicated in Figure 4.1 \(nnnn) character number nnnn (1 to 4 decimal digits) from the Hershey character set; the closing parenthesis may be omitted if the next character is neither a digit nor ``)''. This makes a number of special characters (e.g., mathematical, musical, astronomical, and cartographical symbols) available. See Appendix B for a list of available characters.

## 4.6 Area Fill: Polygons, Rectangles, and Circles

The Area Fill primitives allow the programmer to shade the interior of an arbitrary polygonal or circular region. The appearance of the primitive is controlled by attributes fill area style and color index (see Chapter 5). Note that one fill-style option is hollow, i.e., draw the outline only.

The routine `PGPOLY` is used to fill an area defined as a polygon. It has three arguments: the number (`N`) of vertices defining the polygon, and two arrays (`XPTS` and `YPTS`) containing the world x and y-coordinates of the vertices:

```      CALL PGPOLY (N, XPTS, YPTS)
```
If the polygon is not convex, it may not be obvious which points in the image are inside the polygon. PGPLOT assumes that a point is inside the polygon if a straight line drawn from the point to infinity intersects an odd number of the polygon's edges.

For the special case of a rectangle with edges parallel to the coordinate axes, it is better to use routine `PGRECT` instead of `PGPOLY`; this routine will use the hardware rectangle-fill capability if available. `PGRECT` has four arguments: the (x,y) world coordinates of two opposite corners (note the order of the arguments):

```      CALL PGRECT (X1, X2, Y1, Y2)
```
To draw a circle use routine `PGIRC`. This routine has three arguments: the (x,y), world coordinates of the center, and the radius in world coordinates. Note that a circle may appear elliptical if the world-coordinate scaling is not the same in x and y.
```      CALL PGCIRC (X, Y, RADIUS)
```

Next: Chapter 5
PGPLOT
Tim Pearson, California Institute of Technology, tjp·astro.caltech.edu