The R Project SVN R

% File src/library/grDevices/man/cairo.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2021 R Core Team
% Distributed under GPL 2 or later

\name{cairo}
\alias{svg}
\alias{cairo_pdf}
\alias{cairo_ps}
\title{Cairographics-based SVG, PDF and PostScript Graphics Devices}
\description{
  Graphics devices for SVG, PDF and PostScript graphics files using
  the cairo graphics API.
}
\usage{
svg(filename = if(onefile) "Rplots.svg" else "Rplot\%03d.svg",
    width = 7, height = 7, pointsize = 12,
    onefile = FALSE, family = "sans", bg = "white",
    antialias = c("default", "none", "gray", "subpixel"),
    symbolfamily)

cairo_pdf(filename = if(onefile) "Rplots.pdf" else "Rplot\%03d.pdf",
          width = 7, height = 7, pointsize = 12,
          onefile = FALSE, family = "sans", bg = "white",
          antialias = c("default", "none", "gray", "subpixel"),
          fallback_resolution = 300, symbolfamily)

cairo_ps(filename = if(onefile) "Rplots.ps" else "Rplot\%03d.ps",
         width = 7, height = 7, pointsize = 12,
         onefile = FALSE, family = "sans", bg = "white",
         antialias = c("default", "none", "gray", "subpixel"),
         fallback_resolution = 300, symbolfamily)
}
\arguments{
  \item{filename}{the name of the output file.
    The page number is substituted if a C integer format is included in
    the character string, as in the default.  (The result must be less
    than \code{PATH_MAX} characters long, and may be truncated if not.
    See \code{\link{postscript}} for further details.)  Tilde expansion
    is performed where supported by the platform.}
  \item{width}{the width of the device in inches.}
  \item{height}{the height of the device in inches.}
  \item{pointsize}{the default pointsize of plotted text (in big points).}
  \item{onefile}{should all plots appear in one file or in separate files?}
  \item{family}{one of the device-independent font families,
    \code{"sans"}, \code{"serif"} and \code{"mono"}, or a character
    string specify a font family to be searched for in a
    system-dependent way.

    On unix-alikes (incl.\ Mac), see
    the \sQuote{Cairo fonts} section in the help for \code{\link{X11}}.
  }
  \item{bg}{the initial background colour: can be overridden by setting
    par("bg").}
  \item{antialias}{string, the type of anti-aliasing (if any) to be used;
    defaults to \code{"default"}.}
  \item{fallback_resolution}{numeric: the resolution in dpi used when
    falling back to bitmap output.  Prior to \R 3.3.0 this depended on
    the cairo implementation but was commonly 300.}
  \item{symbolfamily}{
      a length-one character string that specifies the font family to
      be used as the "symbol" font (e.g., for \link{plotmath} output).}
}
\details{
  SVG (Scalar Vector Graphics) is a W3C standard for vector graphics.
  See \url{https://www.w3.org/Graphics/SVG/}.  The output from \code{svg}
  is SVG version 1.1 for \code{onefile = FALSE} (the default), otherwise
  SVG 1.2.  (Few SVG viewers are capable of displaying multi-page SVG
  files.)

  Note that unlike \code{\link{postscript}} and \code{\link{pdf}},
  \code{cairo_pdf} and \code{cairo_ps} sometimes record \emph{bitmaps}
  and not vector graphics.  On the other hand, they can
  (on suitable platforms) include a much wider range of UTF-8 glyphs,
  and embed the fonts used.

  The output produced by \code{cairo_ps(onefile = FALSE)} will be
  encapsulated postscript on a platform with cairo >= 1.6.

  \R can be compiled without support for any of these devices: this will
  be reported if you attempt to use them on a system where they are not
  supported.  They all require cairo version 1.2 or later.

  If you plot more than one page on one of these devices and do not
  include something like \code{\%d} for the sequence number in
  \code{file} (or set \code{onefile = TRUE}) the file will contain the
  last page plotted.

  There is full support of semi-transparency, but using this is one of
  the things liable to trigger bitmap output (and will always do so for
  \code{cairo_ps}).
}

\note{
  In principle these devices are independent of X11 (as is seen by their
  presence on Windows).  But on a Unix-alike the cairo libraries may be
  distributed as part of the X11 system and hence that (for example, on
  \code{x86_64} macOS, XQuartz) may need to be installed.
}

\value{
  A plot device is opened: nothing is returned to the \R interpreter.
}

\section{Anti-aliasing}{
  Anti-aliasing is applied to both graphics and fonts.  It is generally
  preferable for lines and text, but can lead to undesirable effects for
  fills, e.g.\sspace{}for \code{\link{image}} plots, and so is never used for
  fills.

  \code{antialias = "default"} is in principle platform-dependent, but
  seems most often equivalent to \code{antialias = "gray"}.
}

\section{Conventions}{
  This section describes the implementation of the conventions for
  graphics devices set out in the \sQuote{R Internals} manual.

  \itemize{
    \item The default device size is in pixels (\code{svg}) or inches.
    \item Font sizes are in big points.
    \item The default font family is Helvetica.
    \item Line widths are multiples of 1/96 inch.
    \item Circle radii have a minimum of 1/72 inch.
    \item Colours are interpreted by the viewing application.
  }
}

\section{Warning}{
  Support for all these devices are optional, so in packages they should
  be used conditionally after checking \code{\link{capabilities}("cairo")}.
}

\seealso{
  \code{\link{Devices}}, \code{\link{dev.print}}, \code{\link{pdf}},
  \code{\link{postscript}}

  \code{\link{capabilities}} to see if cairo is supported.
}

\keyword{device}