(R-ints.info)Graphics Devices

---

Next: GUI consoles Prev: Files Up: Top

---

Enter node , (file) or (file)node

6 Graphics
**********

R's graphics internals were re-designed to enable multiple graphics
systems to be installed on top on the graphics 'engine' - currently
there are two such systems, one supporting 'base' graphics (based on
that in S and whose R code(1) is in package *graphics*) and one
implemented in package *grid*.

   Some notes on the historical changes can be found at
<https://www.stat.auckland.ac.nz/~paul/R/basegraph.html> and
<https://www.stat.auckland.ac.nz/~paul/R/graphicsChanges.html>.

   At the lowest level is a graphics device, which manages a plotting
surface (a screen window or a representation to be written to a file).
This implements a set of graphics primitives, to 'draw'

   * a circle, optionally filled
   * a rectangle, optionally filled
   * a line
   * a set of connected lines
   * a polygon, optionally filled
   * a paths, optionally filled using a winding rule
   * text
   * a raster image (optional)
   * and to set a clipping rectangle

as well as requests for information such as

   * the width of a string if plotted
   * the metrics (width, ascent, descent) of a single character
   * the current size of the plotting surface

and requests/opportunities to take action such as

   * start a new 'page', possibly after responding to a request to ask
     the user for confirmation.
   * return the position of the device pointer (if any).
   * when a device become the current device or stops being the current
     device (this is usually used to change the window title on a screen
     device).
   * when drawing starts or finishes (e.g.  used to flush graphics to
     the screen when drawing stops).
   * wait for an event, for example a mouse click or keypress.
   * an 'onexit' action, to clean up if plotting is interrupted (by an
     error or by the user).
   * capture the current contents of the device as a raster image.
   * close the device.

   The device also sets a number of variables, mainly Boolean flags
indicating its capabilities.  Devices work entirely in 'device units'
which are up to its developer: they can be in pixels, big points (1/72
inch), twips, ..., and can differ(2) in the 'x' and 'y' directions.

   The next layer up is the graphics 'engine' that is the main interface
to the device (although the graphics subsystems do talk directly to
devices).  This is responsible for clipping lines, rectangles and
polygons, converting the 'pch' values '0...26' to sets of lines/circles,
centring (and otherwise adjusting) text, rendering mathematical
expressions ('plotmath') and mapping colour descriptions such as names
to the internal representation.

   Another function of the engine is to manage display lists and
snapshots.  Some but not all instances of graphics devices maintain
display lists, a 'list' of operations that have been performed on the
device to produce the current plot (since the device was opened or the
plot was last cleared, e.g. by 'plot.new').  Screen devices generally
maintain a display list to handle repaint and resize events whereas
file-based formats do not--display lists are also used to implement
'dev.copy()' and friends.  The display list is a pairlist of '.Internal'
(base graphics) or '.Call.graphics' (grid graphics) calls, which means
that the C code implementing a graphics operation will be re-called when
the display list is replayed: apart from the part which records the
operation if successful.

   Snapshots of the current graphics state are taken by
'GEcreateSnapshot' and replayed later in the session by
'GEplaySnapshot'.  These are used by 'recordPlot()', 'replayPlot()' and
the GUI menus of the 'windows()' device.  The 'state' includes the
display list.

   The top layer comprises the graphics subsystems.  Although there is
provision for 24 subsystems since about 2001, currently still only two
exist, 'base' and 'grid'.  The base subsystem is registered with the
engine when R is initialized, and unregistered (via 'KillAllDevices')
when an R session is shut down.  The grid subsystem is registered in its
'.onLoad' function and unregistered in the '.onUnload' function.  The
graphics subsystem may also have 'state' information saved in a snapshot
(currently base does and grid does not).

   Package *grDevices* was originally created to contain the basic
graphics devices (although 'X11' is in a separate load-on-demand module
because of the volume of external libraries it brings in).  Since then
it has been used for other functionality that was thought desirable for
use with *grid*, and hence has been transferred from package *graphics*
to *grDevices*.  This is principally concerned with the handling of
colours and recording and replaying plots.

Graphics devices

Colours

Base graphics

Grid graphics

   ---------- Footnotes ----------

   (1) The C code is in files 'base.c', 'graphics.c', 'par.c', 'plot.c'
and 'plot3d.c' in directory 'src/main'.

   (2) although that needs to be handled carefully, as for example the
'circle' callback is given a radius (and that should be interpreted as
in the x units).