R: X Window System Graphics

x11 {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` (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 http://web.mit.edu/answers/xwindows/xwindows_resources.html and perhaps man X (or 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)

[Package grDevices version 2.8.1 Index]