check_device {ggplot2}R Documentation

Check graphics device capabilities

Description

This function makes an attempt to estimate whether the graphics device is able to render newer graphics features.

Usage

check_device(
  feature,
  action = "warn",
  op = NULL,
  maybe = FALSE,
  call = caller_env()
)

Arguments

feature

A string naming a graphics device feature. One of: "clippingPaths", "alpha_masks", "lumi_masks", "compositing", "blending", "transformations", "gradients", "patterns", "paths" or "glyphs". See the 'Features' section below for an explanation of these terms.

action

A string for what action to take. One of:

  • "test" returns TRUE or FALSE indicating support of the feature.

  • "warn" also returns a logical, but throws an informative warning when FALSE.

  • "abort" throws an error when the device is estimated to not support the feature.

op

A string for a specific operation to test for when feature is either "blending" or "compositing". If NULL (default), support for all known blending or compositing operations is queried.

maybe

A logical of length 1 determining what the return value should be in case the device capabilities cannot be assessed. When the current device is the 'null device', maybe is returned.

call

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in warnings and error messages as the source of the warning or error. See the call argument of abort() for more information.

Details

The procedure for testing is as follows:

Value

TRUE when the feature is thought to be supported and FALSE otherwise.

Features

"clippingPaths"

While most devices support rectangular clipping regions, this feature is about the support for clipping to arbitrary paths. It can be used to only display a part of a drawing.

"alpha_masks"

Like clipping regions and paths, alpha masks can also be used to only display a part of a drawing. In particular a semi-transparent mask can be used to display a drawing in the opaque parts of the mask and hide a drawing in transparent part of a mask.

⁠"lumi_masks⁠

Similar to alpha masks, but using the mask's luminance (greyscale value) to determine what is drawn. Light values are opaque and dark values are transparent.

"compositing"

Compositing allows one to control how to drawings are drawn in relation to one another. By default, one drawing is drawn 'over' the previous one, but other operators are possible, like 'clear', 'in' and 'out'.

"blending"

When placing one drawing atop of another, the blend mode determines how the colours of the drawings relate to one another.

"transformations"

Performing an affine transformation on a group can be used to translate, rotate, scale, shear and flip the drawing.

"gradients"

Gradients can be used to show a transition between two or more colours as a fill in a drawing. The checks expects both linear and radial gradients to be supported.

"patterns"

Patterns can be used to display a repeated, tiled drawing as a fill in another drawing.

"paths"

Contrary to 'paths' as polyline or polygon drawings, "paths" refers to the ability to fill and stroke collections of drawings.

"glyphs"

Refers to the advanced typesetting feature for controlling the appearance of individual glyphs.

Limitations

Examples

# Typically you'd run `check_device()` inside a function that might produce
# advanced graphics.
# The check is designed for use in control flow statements in the test mode
if (check_device("patterns", action = "test")) {
  print("Yay")
} else {
  print("Nay")
}

# Automatically throw a warning when unavailable
if (check_device("compositing", action = "warn")) {
  print("Yay")
} else {
  print("Nay")
}

# Possibly throw an error
try(check_device("glyphs", action = "abort"))

[Package ggplot2 version 3.5.2 Index]