[Rd] Notes for writers of graphics devices

[Prof Brian Ripley]

Partly about new features and partly about old features that are not being 
used.

R_exts/GraphicsEngine.h says

/*
  * The current graphics engine (including graphics device) API version
  * MUST be integer
  *
  * This number should be bumped whenever there are changes to
  * GraphicsEngine.h or GraphicsDevice.h so that add-on packages
  * that compile against these headers (graphics systems such as
  * graphics and grid;  graphics devices such as gtkDevice, RSvgDevice)
  * can detect any version mismatch.
  *
  * Version 1:  Introduction of the version number.
  * Version 2:  GEDevDesc *dd dropped from GEcontourLines().
  * Version 3:  R_GE_str2col() added to API.
  * Version 4:  UTF-8 text hooks, useRotatedTextInContour to device interface.
  */

but unfortunately it is unused.  There's a function called
R_GE_checkVersionOrDie to check the API version.  Unfortunately this means 
that devices built under R < 2.7.0 are liable to crash if used under 2.7.0 
(although I've tried to be as defensive as possible).  So please consider 
making use of it. (As the standard devices don't need it, they don't 
provide examples.)

The new features of the device interface are

1) 'useRotatedTextInContour'.  Set this to true if the device can produce 
high-quality rotated text in the standard fonts, which will then be used 
in preference to Hershey fonts for labelling contour lines.  This the new 
default for postscript() and pdf() but not X11().

2) 'hasTextUTF8'  If set, you need to supply functions textUTF8 and 
strWidthUTF8 which are just like text and strWidth but will be passed text 
in UTF-8.  Note that these are alternatives: the graphics engine will only 
use the UTF-8 versions when this avoids re-encoding.

Another thing I see is with metricInfo: in a multibyte locale this is 
passed the Unicode point, and it seems almost all third-party graphics 
devices are ignoring that.  To make things a little simpler, if
hasTextUTF8 is set, Unicode points are sent to metricInfo as negative 
values.  Examples can be seen in e.g. the postcript, pdf and windows 
devices.


-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595