1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
#' Sets the null graphics device
#'
#' The function [as_grob()] needs to open a graphics device to render ggplot objects into
#' grid graphics objects. Unfortunately, there is no universally reliable graphics device available
#' in R that always works. Therefore, this function allows you to switch out the null device.
#'
#' You need to be aware that some graphics devices cause side effects when used as null devices.
#' If you use an interactive device as null device, you may see an empty plot window pop up. Similarly,
#' if you use a graphics device that writes a file, then you may find temporary files associated
#' with the device. The default null device, `pdf(NULL)`, does not cause these side effects. However, it has
#' has other limitations. For example, on OS X, it cannot use all the fonts that are available on the
#' system. The ragg device can use all fonts, but it will create temporary files.
#'
#' @param null_device Either a string that defines the null device ("pdf", "png", "cairo", "agg")
#' or a function that returns a new graphics device.
#'
#' @examples
#' set_null_device("png") # set the png null device
#'
#' # create a jpeg null device
#' jpeg_null_device <- function(width, height) {
#' jpeg(
#' filename = tempfile(pattern = "jpeg_null_plot", fileext = ".jpg"),
#' width = width, height = height, units = "in", res = 96
#' )
#' dev.control("enable")
#'}
#' set_null_device(jpeg_null_device)
#' @seealso
#' Available null devices are: [`pdf_null_device()`], [`png_null_device()`],
#' [`cairo_null_device()`], [`agg_null_device()`]
#' @export
set_null_device <- function(null_device) {
old <- null_dev_env$current
if (methods::is(null_device, "function")) {
null_dev_env$current <- null_device
} else {
null_dev_env$current <- switch(null_device,
pdf = pdf_null_device,
png = png_null_device,
cairo = cairo_null_device,
Cairo = cairo_null_device,
agg = agg_null_device,
{
warning("Null device ", null_device, " not recognized. Substituting grDevices::pdf().", call. = FALSE);
pdf_null_device
}
)
}
invisible(old)
}
#' Null devices
#'
#' Null devices to be used when rendering graphics in the background. See
#' [`set_null_device()`] for details.
#'
#' @param width Device width in inch
#' @param height Device height in inch
#' @export
png_null_device <- function(width, height) {
grDevices::png(
filename = tempfile(pattern = "cowplot_null_plot", fileext = ".png"),
width = width, height = height,
units = "in", res = 96
)
grDevices::dev.control("enable")
}
#' @rdname png_null_device
#' @export
pdf_null_device <- function(width, height) {
grDevices::pdf(NULL, width = width, height = height)
grDevices::dev.control("enable")
}
#' @rdname png_null_device
#' @export
cairo_null_device <- function(width, height) {
if (requireNamespace("Cairo", quietly = TRUE)) {
Cairo::Cairo(
type = "raster",
width = width, height = height,
units = "in", dpi = 300
)
grDevices::dev.control("enable")
} else {
warning("Package `Cairo` is required to use the Cairo null device. Substituting grDevices::pdf(NULL).", call. = FALSE)
pdf_null_device(width, height)
}
}
#' @rdname png_null_device
#' @export
agg_null_device <- function(width, height) {
if (requireNamespace("ragg", quietly = TRUE)) {
ragg::agg_png(
filename = tempfile(pattern = "cowplot_null_plot", fileext = ".png"),
width = width, height = height,
units = "in", res = 300
)
grDevices::dev.control("enable")
} else {
warning("Package `ragg` is required to use the agg null device. Substituting grDevices::pdf(NULL).", call. = FALSE)
pdf_null_device(width, height)
}
}
# the null device is stored in an environment
# default upon start up is pdf null device
null_dev_env <- new.env(parent = emptyenv())
null_dev_env$current <- pdf_null_device
|
