Chapter 15. The graphical library

Table of Contents

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.