dev2                package:grDevices                R Documentation

_C_o_p_y _G_r_a_p_h_i_c_s _B_e_t_w_e_e_n _M_u_l_t_i_p_l_e _D_e_v_i_c_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     'dev.copy' copies the graphics contents of the current device to
     the device specified by 'which' or to a new device which has been
     created by the function specified by 'device' (it is an error to
     specify both 'which' and 'device').  (If recording is off on the
     current device, there are no contents to copy: this will result in
     no plot or an empty plot.) The device copied to becomes the
     current device.

     'dev.print' copies the graphics contents of the current device to
     a new device which has been created by the function specified by
     'device' and then shuts the new device.

     'dev.copy2eps' is similar to 'dev.print' but produces an EPSF
     output file in portrait orientation ('horizontal = FALSE').
     'dev.copy2pdf' is the analogue for PDF output.

     'dev.control' allows the user to control the recording of graphics
     operations in a device.  If 'displaylist' is '"inhibit"'
     ('"enable")' then recording is turned off (on). It is only safe to
     change this at the beginning of a plot (just before or just after
     a new page).  Initially recording is on for screen devices, and
     off for print devices.

_U_s_a_g_e:

     dev.copy(device, ..., which = dev.next())
     dev.print(device = postscript, ...)
     dev.copy2eps(...)
     dev.copy2pdf(..., out.type = "pdf")
     dev.control(displaylist = c("inhibit", "enable"))

_A_r_g_u_m_e_n_t_s:

  device: A device function (e.g., 'x11', 'postscript', ...)

     ...: Arguments to the 'device' function above: for 'dev.copy2eps'
          arguments to 'postscript' and for 'dev.copy2pdf', arguments
          to 'pdf'. For 'dev.print', this includes 'which' and by
          default any 'postscript' arguments.

   which: A device number specifying the device to copy to.

out.type: The name of the output device: can be '"pdf"', or '"quartz"'
          (some Mac OS X builds) or '"cairo"' (some Unix-alikes, see
          'cairo_pdf').

displaylist: A character string: the only valid values are '"inhibit"'
          and '"enable"'.

_D_e_t_a_i_l_s:

     Note that these functions copy the _device region_ and not a plot:
     the background colour of the device surface is part of what is
     copied.  Most screen devices default to a transparent background,
     which is probably not what is needed when copying to a device such
     as 'png'.

     For 'dev.copy2eps' and 'dev.copy2pdf', 'width' and 'height' are
     taken from the current device unless otherwise specified.  If just
     one of 'width' and 'height' is specified, the other is adjusted to
     preserve the aspect ratio of the device being copied.  The default
     file name is 'Rplot.eps' or 'Rplot.pdf', and can be overridden by
     specifying a 'file' argument.

     Copying to devices such as 'postscript' and 'pdf' which need font
     families pre-specified needs extra care - R is unaware of which
     families were used in a plot and so they will need to manually
     specified by the 'fonts' argument passed as part of '...'. 
     Similarly, if the device to be copied from was opened with a
     'family' argument, a suitable 'family' argument will need to be
     included in '...'.

     The default for 'dev.print' is to produce and print a postscript
     copy, if 'options("printcmd")' is set suitably.

     'dev.print' is most useful for producing a postscript print (its
     default) when the following applies.  Unless 'file' is specified,
     the plot will be printed.  Unless 'width', 'height' and
     'pointsize' are specified the plot dimensions will be taken from
     the current device, shrunk if necessary to fit on the paper.
     ('pointsize' is rescaled if the plot is shrunk.)  If 'horizontal'
     is not specified and the plot can be printed at full size by
     switching its value this is done instead of shrinking the plot
     region.

     If 'dev.print' is used with a specified 'device' (even
     'postscript') it sets the width and height in the same way as
     'dev.copy2eps'.  This will not be appropriate unless the device
     specifies dimensions in inches, in particular not for 'png' and
     'jpeg'.

_V_a_l_u_e:

     'dev.copy' returns the name and number of the device which has
     been copied to.

     'dev.print', 'dev.copy2eps' and 'dev.copy2pdf' return the name and
     number of the device which has been copied from.

_N_o_t_e:

     Most devices (including all screen devices) have a display list
     which records all of the graphics operations that occur in the
     device. 'dev.copy' copies graphics contents by copying the display
     list from one device to another device.  Also, automatic redrawing
     of graphics contents following the resizing of a device depends on
     the contents of the display list.

     After the command 'dev.control("inhibit")', graphics operations
     are not recorded in the display list so that 'dev.copy' and
     'dev.print' will not copy anything and the contents of a device
     will not be redrawn automatically if the device is resized.

     The recording of graphics operations is relatively expensive in
     terms of memory so the command 'dev.control("inhibit")' can be
     useful if memory usage is an issue.

_S_e_e _A_l_s_o:

     'dev.cur' and other 'dev.xxx' functions.

_E_x_a_m_p_l_e_s:

     ## Not run: 
     x11()
     plot(rnorm(10), main="Plot 1")
     dev.copy(device=x11)
     mtext("Copy 1", 3)
     dev.print(width=6, height=6, horizontal=FALSE) # prints it
     dev.off(dev.prev())
     dev.off()
     ## End(Not run)