x11                package:grDevices                R Documentation

X Window System Graphics

Description:

     'X11' starts a graphics device driver for the X Window System
     (version 11).  This can only be done on machines/accounts that
     have access to an X server.

     'x11' is recognized as a synonym for 'X11'.

Usage:

     X11(display = "", width, height, pointsize, gamma, bg, canvas,
         fonts, xpos, ypos, title, type, antialias)

     X11.options(..., reset = FALSE)

Arguments:

 display: the display on which the graphics window will appear. The
          default is to use the value in the user's environment
          variable 'DISPLAY'.  This is ignored (with a warning) if an
          X11 device is already open on another display.

width, height: the width and height of the plotting window, in inches. 
          If 'NA', taken from the resources and if not specified there
          defaults to '7' inches.  See also 'Resources'.

pointsize: the default pointsize to be used.  Defaults to '12'.

   gamma: the gamma correction factor.  This value is used to help
          ensure that the colours perceived are linearly related to RGB
          values (see 'hsv').  By default 1 (default correction).

      bg: colour, the initial background colour.  Default
          '"transparent"'.

  canvas: colour.  The colour of the canvas, which is visible only when
          the background colour is transparent.  Should be a solid
          colour (and any alpha value will be ignored).  Default
          '"white"'.

   fonts: X11 font description strings into which weight, slant and
          size will be substituted.  There are two, the first for fonts
          1 to 4 and the second for font 5, the symbol font.  See
          section 'Fonts'.

xpos, ypos: integer: initial position of the top left corner of the
          window, in pixels.  Negative values are from the opposite
          corner, e.g. 'xpos=-100' says the top right corner should be
          100 pixels from the right edge of the screen.  If 'NA' (the
          default), successive devices are cascaded in 20 pixel steps
          from the top left. See also 'Resources'.

   title: character string, up to 100 bytes.  With the default, '""', a
          suitable title is created internally.  A C-style format for
          an integer will be substituted by the device number (see the
          'file' argument to 'postscript' for further details).  How
          non-ASCII titles are handled is implementation-dependent.

    type: character string, one of '"Xlib"' (the only type prior to R
          2.7.0) or '"cairo"' or '"nbcairo"'.  The latter two will only
          be available if the system was compiled with support for
          cairo.  Default '"cairo"' where available, otherwise
          '"Xlib"'.

antialias: for cairo types, the type of anti-aliasing (if any) to be
          used.  One of 'c("default", "none", "gray", "subpixel")'.

   reset: logical: should the defaults be reset to their defaults?

     ...: Any of the arguments to 'X11', plus 'colortype' and
          'maxcubesize' (see section 'Colour Rendering').

Details:

     The defaults for all of the arguments of 'X11' are set by
     'X11.options': the 'Arguments' section gives the 'factory-fresh'
     defaults.

     The initial size and position are only hints, and may not be acted
     on by the window manager.  Also, some systems (especially laptops)
     are set up to appear to have a screen of a different size to the
     physical screen.

     Option 'type' selects between two separate devices: R can be built
     with support for neither, 'type = "Xlib"' or both.  Where both are
     available, types '"cairo"' and '"nbcairo"' offer

        *  antialiasing of text and lines.

        *  translucent colours.

        *  scalable text, including to sizes like 4.5 pt.

        *  full support for UTF-8, so on systems with suitable fonts
           you can plot in many languages on a single figure (and this
           will work even in non-UTF-8 locales).  The output should be
           locale-independent.

     'type = "nbcairo"' is the same device as 'type="cairo"' without
     buffering: which is faster will depend on the X11 connection. 
     Both will be slower than 'type = "Xlib"', especially on a slow X11
     connection as all the rendering is done on the machine running R
     rather than in the X server.

     All devices which use an X11 server (including the 'type = "Xlib"'
     versions of bitmap devices such as 'png') share internal
     structures, which means that they must use the same 'display' and
     visual.  If you want to change display, first close all such
     devices.

X11 Fonts:

     This section applies only to 'type = "Xlib"'.

     An initial/default font family for the device can be specified via
     the 'fonts' argument, but if a device-independent R graphics font
     family is specified (e.g., via 'par(family=)' in the graphics
     package), the X11 device makes use of the X11 font database (see
     'X11Fonts') to convert the R graphics font family to an
     X11-specific font family description.

     X11 chooses fonts by matching to a pattern, and it is quite
     possible that it will choose a font in the wrong encoding or which
     does not contain glyphs for your language (particularly common in
     'iso10646-1' fonts).

     The 'fonts' argument is a two-element character vector, and the
     first element will be crucial in successfully using
     non-Western-European fonts.  Settings that have proved useful
     include

     '"-*-mincho-%s-%s-*-*-%d-*-*-*-*-*-*-*"' for CJK languages and
     '"-cronyx-helvetica-%s-%s-*-*-%d-*-*-*-*-*-*-*"' for Russian.

     For UTF-8 locales, the 'XLC_LOCALE' databases provide mappings
     between character encodings, and you may need to add an entry for
     your locale (e.g. Fedora Core 3 lacked one for 'ru_RU.utf8').

Cairo Fonts:

     The cairo-based device works directly with font family names such
     as '"Helvetica"' which should be selected by 'par' or 'gpar'. 
     There are mappings for the three device-independent font families,
     '"sans"' for a sans-serif font (to '"Helvetica"'), '"serif"' for a
     serif font (to '"Times"') and '"mono"' for a monospaced font (to
     '"Courier"').

     The font selection is handled by 'Pango' (usually) or 'cairo' (on
     Mac OS X and perhaps elsewhere).  Both make use of 'fontconfig'
     (<URL: http://wwww.fontconfig.org>) to select fonts and so the
     results depend on the fonts installed on the system running R -
     setting the environmnent variable 'FC_DEBUG' to 1 allows some
     tracing of the selection process.

     This works best when high-quality scalable fonts are installed,
     usually in Type 1 or TrueType formats: see the "R Installation and
     Administration Manual" for advice on how to obtain and install
     such fonts.

Resources:

     The standard X11 resource 'geometry' can be used to specify the
     window position and/or size, but will be overridden by values
     specified as arguments or non-'NA' defaults set in 'X11.options'. 
     The class looked for is 'R_x11'.  Note that the resource specifies
     the width and height in pixels and not in inches.  See for example
     <URL: http://web.mit.edu/answers/xwindows/xwindows_resources.html>
     and perhaps 'man X' (or <URL:
     http://www.xfree86.org/current/X.7.html>). An example line in
     '~/.Xresources' might be

     R_x11*geometry: 900x900-0+0

     which specifies a 900 x 900 pixel window at the top right of the
     screen.

Colour Rendering:

     X11 supports several 'visual' types, and nowadays almost all
     systems support 'truecolor' which 'X11' will use by default.  This
     uses a direct specification of any RGB colour up to the depth
     supported (usually 8 bits per colour).  Other visuals make use of
     a palette to support fewer colours, only grays or even only
     black/white.  The palette is shared between all X11 clients, so it
     can be necessary to limit the number of colours used by R.

     Cairo-based devices currently support only 'truecolor' visuals.
     (Cairo 1.6 will support other visuals.)

     The default for 'type="Xlib"' is to use the best possible colour
     model for the visual of the X11 server.  This can be overridden by
     the 'colortype' argument of 'X11.options'.  *Note:* All 'X11' and
     'type = "Xlib"' 'bmp', 'jpeg', 'png' and 'tiff' devices share a
     'colortype' which is set when the first device to be opened.  To
     change the 'colortype' you need to close _all_ open such devices,
     and then use 'X11.options(colortype=)'.

     The colortype types are tried in the order '"true"', '"pseudo"',
     '"gray"' and '"mono"' (black or white only).  The values
     '"pseudo"' and '"pseudo.cube"' provide colour strategies for a
     pseudocolor visual.  The first strategy provides on-demand colour
     allocation which produces exact colours until the colour resources
     of the display are exhausted (when plotting will fail).  The
     second allocates (if possible) a standard colour cube, and
     requested colours are approximated by the closest value in the
     cube.

     With 'colortype' equal to '"pseudo.cube"' or '"gray"' successively
     smaller palettes are tried until one is completely allocated.  If
     allocation of the smallest attempt fails the device will revert to
     '"mono"'.  For '"gray"' the search starts at 256 grays for a
     display with depth greater than 8, otherwise with half the
     available colours.  For '"pseudo.cube"' the maximum cube size is
     set by 'X11.options(maxcolorsize=)' and defaults to 256.  With
     that setting the largest cube tried is 4 levels each for RGB,
     using 64 colours in the palette.

Anti-aliasing:

     Anti-aliasing is only supported for cairo-based devices, and
     applies to graphics and to fonts.  It is generally preferable for
     lines and text, but can lead to undesirable effects for fills,
     e.g. for 'image' plots, and so is never used for fills.

     'antialias = "default"' is in principle platform-dependent, but
     seems most often equivalent to 'antialias = "gray"'.

Conventions:

     This section describes the implementation of the conventions for
     graphics devices set out in the "R Internals Manual".


        *  The default device size is 7 inches square.

        *  Font sizes are in big points.

        *  The default font family is Helvetica.

        *  Line widths in 1/96 inch, minimum one pixel for 'type =
           "Xlib"', 0.01 otherwise.

        *  For 'type = "Xlib"' circle radii are in pixels with minimum
           one.

        *  Colours are interpreted by the X11 server, normally in a
           fair approximation to sRGB.

See Also:

     'Devices', 'X11Fonts', 'savePlot'.

Examples:

     ## Not run: 
     ## put something this is your .Rprofile to customize the defaults
     setHook(packageEvent("grDevices", "onLoad"),
             function(...) grDevices::X11.options(width=8, height=6, xpos=0,
                                                  pointsize=10))
     ## End(Not run)

