\HeaderA{quartz}{MacOS X Quartz Device}{quartz}
\methaliasA{quartz.options}{quartz}{quartz.options}
\keyword{device}{quartz}
\begin{Description}\relax
\code{quartz} starts a graphics device driver for the Mac OS X System.
It supports plotting both to the screen (the default) and to various
graphics file formats.
\end{Description}
\begin{Usage}
\begin{verbatim}
quartz(title, width, height, pointsize, family, fontsmooth, antialias,
       type, file = NULL, bg, canvas, dpi)

quartz.options(..., reset = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{title}] title for the Quartz window (applies to on-screen output
only), default \code{"Quartz \%d"}.  A C-style format for an integer
will be substituted by the device number (see the \code{file}
argument to \code{\LinkA{postscript}{postscript}} for further details).
\item[\code{width}] the width of the plotting area in inches.  Default \code{7}.
\item[\code{height}] the height of the plotting area in inches.  Default \code{7}.
\item[\code{pointsize}] the default pointsize to be used.  Default \code{12}.
\item[\code{family}] this is the family name of the font
that will be used by the device.  Default \code{"Helvetica"}.
\item[\code{fontsmooth}] logical specifying if fonts should be
smoothed. Default \code{TRUE}.  Currently unused.
\item[\code{antialias}] whether to use antialiasing.  Default \code{TRUE}.
\item[\code{type}] the type of output to use.  See \sQuote{Details} for
more information.  Default \code{"native"}.
\item[\code{file}] an optional target for the graphics device. The default,
\code{NULL}, selects a default name where one is needed.  See
\sQuote{Details} for more information.
\item[\code{bg}] the initial background colour to use for the device.  Default
\code{"transparent"}.  An opaque colour such as \code{"white"} will
normally be required on off-screen types that support transparency
such as \code{"png}" and \code{"tiff"}.
\item[\code{canvas}] canvas colour to use for an on-screen device.  Default
\code{"white"}, and will be forced to be an opaque colour.
\item[\code{dpi}] resolution of the output.  The default (\code{NA\_real\_})
for an on-screen display defaults to the resolution of
the main screen, and to 72 dpi otherwise.  See \sQuote{Details}.
\item[\code{...}] Any of the arguments to \code{quartz} except \code{file}.
\item[\code{reset}] logical: should the defaults be reset to their defaults?
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The defaults for all but one of the arguments of \code{quartz} are set
by \code{quartz.options}: the \sQuote{Arguments} section gives the
\sQuote{factory-fresh} defaults.

The Quartz graphics device supports a variety of output types.
On-screen output types are \code{""} or \code{"native"} (picks the best
possible on-screen output), \code{"Cocoa"} (Mac OS X 10.4 and later)
and \code{"Carbon"} (not currently implemented -- potentially
Mac OS X 10.3 and earlier).   Off-screen output
types produce output files and utilize the \code{file} argument.
\code{type = "pdf"} gives PDF output. The following bitmap formats may
be supported (on OS X 10.4 and later): \code{"png"}, \code{"jpeg"},
\code{"jpg"}, \code{"jpeg2000"}, \code{"tif"}, \code{"tiff"},
\code{"gif"}, \code{"psd"} (Adobe Photoshop), \code{"bmp"} (Windows
bitmap), \code{"sgi"} and \code{"pict"}.  (The availability of some
formats is OS-version-dependent.)

To reproduce the default of older Quartz devices on-screen, set
\code{dpi = 72} (for a permanent solution set
\code{quartz.options(dpi = 72)}).

The \code{file} argument is used for off-screen drawing.  The actual
file is only created when the device is closed (e.g. using
\code{dev.off()}).  For the bitmap devices, the page number is
substituted if a C integer format is included in the character string,
e.g. \code{Rplot\%03d.png}.  (The result must be less than
\code{PATH\_MAX} characters long, and may be truncated if not. See
\code{\LinkA{postscript}{postscript}} for further details.)  If a \code{file}
argument is not supplied, the default is \code{Rplots.pdf} or
\code{Rplot\%03d.\var{type}}.

If a device-independent \R{} graphics font family is specified
(e.g., via \code{par(family=)} in the graphics package),
the Quartz device makes use of the Quartz font database
(see \code{quartzFonts}) to convert the R graphics font family
to a Quartz-specific font family description.

On-screen devices are launched with a semi-transparent canvas.  Once a
new plot is created, the canvas is first painted with the
\code{canvas} colour and then the current background colour (which can
be transparent or semi-transparent).  Off-screen devices have no
canvas colour, and so start with a transparent background where
possible (e.g. \code{type="png"} and \code{type="tiff"}) -- otherwise
it appears that a solid white canvas is assumed in the Quartz code.

\code{title} can be used for on-screen output.  It must be a single
character string with an optional integer printf-style format that
will be substituted by the device number.  It is also optionally used
(without a format) to give a title to a PDF file.

Calling \code{quartz()} sets \code{\LinkA{.Device}{.Device}} to \code{"quartz"}
for on-scren devices and to \code{"quartz\_off\_screen"} otherwise.
\end{Details}
\begin{Section}{Conventions}
This section describes the implementation of the conventions for
graphics devices set out in the \dQuote{R Internals Manual}.

\Itemize{
\item The default device size is 7 inches square.
\item Font sizes are in big points.
\item The default font family is Arial.
\item Line widths are a multiple of 1/96 inch with no minimum set by \R.
\item Circle radii are real-valued with no minimum set by \R.
\item Colour interpretation is by the viewer, including the screen
display.
}
\end{Section}
\begin{SeeAlso}\relax
\code{\LinkA{quartzFonts}{quartzFonts}}, \code{\LinkA{Devices}{Devices}}.

\code{\LinkA{png}{png}} for way to access the bitmap types of this device
via \R's standard bitmap devices.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}## Not run: 
## put something this is your .Rprofile to customize the defaults
setHook(packageEvent("grDevices", "onLoad"),
        function(...) grDevices::quartz.options(width=8, height=6,
                                                pointsize=10))
## End(Not run)\end{ExampleCode}
\end{Examples}

