Chapter 15. The graphical library

Basic procedures
Higher-level procedures

The graphical library contains a number of output procedures for creating vector graphics. Currently the graphical procedures output to an SVG file, but in the future more output formats will be added. The graphical library is implemented as a Rax extension (see Chapter 20, Extending Rax), but is a part of the standard Rax distribution.

To be able to use the graphical procedures, include the `GraphicalEngine.rax` file:

```    %include __EXE_PATH__ "rx_GraphicalEngine/GraphicalEngine.rax";
```

Basic procedures

Readers familiar with Postscript, will recognize many of the basic graphical procedures in Rax.

Table 15.1. Basic graphical procedures.

 ``` `setoutputfile filename ``` Set the output file to `filename`. By default Rax outputs the graphics to the standard output. ``` `newpath ``` Start a new path. ``` `moveto x,y ``` Set the current point to `x`, `y`; `x` and `y` are real numbers. ``` `rmoveto x,y ``` Perform relative ``moveto`, i.e. add `x` and `y` to the current point's coordinates; `x` and `y` are real numbers. ``` `lineto x,y ``` Draw a line from the current point to the point with `x`, `y` coordinates; `x` and `y` are real numbers. ``` `lineto x,y ``` Perform a relative ``lineto`, i.e., add `x` and `y` to the current point's coordinates and draw a line to the new current point; `x` and `y` are real numbers. ``` `stroke ``` Draw a line along the current path. ``` `fill ``` Fill current path with current color. ``` `text x,y,text ``` Print `text` at position `x`,`y`. ``` `setrgbcolor r,g,b,a ``` Set the current color to the specified `red`, `green`, `blue` and `alpha` values. ``` `setlinewidth width ``` Set the current line width to the specified `width`; `width` is a real number. ``` `setlinecap linecap ``` Set the line cap to the given value; `linecap` is a string value with one of the values: `"butt"`, `"round"` or `"square"`. If the user submits any other value, the line cap will be set to the default `"butt"` value. ``` `setlinejoin linejoin ``` Set the line join to the given value; `linejoin` is a string value with one of the values: `"miter"`, `"round"` or `"bevel"`. If the user submits any other value, the line join will be set to the default `"miter"` value. ``` `setmiterlimit limit ``` Set the miter length limit. This parameter is only relevant to mitered line joins. To prevent very long spikes when lines meet at an acute angle, the system will switch from mitered joins to beveled joins at the angle specified by this parameter. The default value is `10`. ``` `setlinedash dasharray,offset ``` Set dash pattern for stroking; `dasharray` is a set of numbers, and `dashoffset` is a number. If `dasharray` is an empty set, the resulting line will be solid. If `dasharray` contains non-negative numbers, the numbers alternately represent the length of a dash and the length of the a gap between dashes. The content of the `dasharray` set is used cyclically. The `offset` parameter is a distance into the `dasharray` at which the pattern should be started. ``` `setfontfamily name ``` Set the current font family. The `name` parameter is a string. The default value is `Helvetica`. ``` `setfontweight weight ``` Set the current font weight. The `weight` parameter is a string and has to have one of the values: `"normal"`, `"bold"`, `"100"`, `"200"`, `"300"`, `"400"`, `"500"`, `"600"`, `"700"`, `"800"` or `"900"`. If the user specifies an invalid value, the default `"normal"` value is used. ``` `setfontstyle style ``` Set the current font style. The `style` parameter is a string and has to have one of the following values: `"normal"`, `"italic"` or `"oblique"`. If the user specifies an invalid value, the default `"normal"` value is used. ``` `setfontsize size ``` Set the current font size. The `size` parameter is a real number with the default value of `20.0`. ``` `settextalignment alignment ``` Set the alignment of the text. This parameter controls how the ``text x,y,text` procedure will place the text with respect to the `x` and `y` coordinates. The possible values of the `alignment` parameter are: `"start"`, `"middle"` and `"end"`. If the user specifies and invalid value, the default `"begin"` value is used. ``` `translate x,y ``` Move the origin of the user coordinate space by `x` units horizontally and `y` units vertically. ``` `rotate angle ``` Turn the user space axes about the origin of the coordinate space by the specified `angle`. The angle should be specified in degrees. Not implemented yet. ``` `scale x,y ``` Scale the units of the coordinate system by a factor of `x` along the horizontal axis and by a factor of `y` along the vertical axis. ``` `gsave ``` Save the current graphical state by pushing it onto the stack. ``` `grestore ``` Restore the previously saved graphical state by popping it from the stack. ``` `showpage ``` Output the current drawing to the graphical device (e.g. an SVG file) and clear the current drawing. ``` `copypage ``` Output the current drawing to the graphical device (e.g. an SVG file) without clearing the current drawing. Not implemented yet.