Build and render a scene — vl

vl_scene() creates an empty scene. push() adds a viewport (and descends into it), draw() adds a grob, pop() ascends. The builder is a linear pipe; a rendered or edited scene is an immutable value (edit_node() copies on modify). render() compiles the scene and writes the output.

Usage

vl_scene(
  width = 6,
  height = 4,
  dpi = 96,
  bg = "white",
  gp = vl_gpar(),
  xscale = c(0, 1),
  yscale = c(0, 1),
  clip = FALSE,
  title = NULL,
  desc = NULL
)

push(scene, vp)

draw(scene, grob)

pop(scene, n = 1)

render(
  scene,
  path,
  text = c("native", "outline"),
  debug = FALSE,
  scale = 1,
  cvd = "none"
)

Arguments

width, height: Page size (vl_unit() or numeric inches).
dpi: Resolution in dots per inch.
bg: Background colour (or NA for transparent).
gp: Page-level graphical parameters (vl_gpar()) carried by the root viewport; inherited by everything drawn (e.g. a default col/fontsize).
xscale, yscale: Native coordinate range of the root viewport, so "native" units work at the page level without an explicit push().
clip: Clip drawing to the page rectangle?
title, desc: Accessibility: an accessible name (a short title) and a longer description (alt text) for the scene. When either is set, the SVG backend emits role="img" + <title>/<desc> (referenced by aria-labelledby) and the PDF backend tags the page as a Figure with the description as Alt text. NULL (default) emits no accessibility markup, so output is unchanged. See describe() to set them on an existing scene.
scene: A vl_scene().
vp: A vl_viewport().
grob: A grob (see grob).
n: Number of viewport levels to ascend.
path: Output file path; the format is taken from the extension (.png, .svg, or .pdf).
text: For SVG output, how text is written: "native" (default) emits selectable <text> referencing system fonts, "outline" emits glyph outlines (pixel-faithful, identical to the raster/PDF backends, but not selectable). Ignored for PNG/PDF.
debug: If TRUE, overlay a layout-debug skeleton on the output: each viewport region (outlined and labelled by name), its layout track boundaries, and its clip region. Built from the resolved scene with why_size(); useful for understanding why elements land where they do. Default FALSE.
scale: Resolution multiplier (default 1). scale = 2 renders at twice the device pixels while keeping the same physical size — the retina / ggsave(scaling=) idiom. It multiplies dpi, so absolute units (mm, pt, in) cover proportionally more pixels and nothing about the layout changes; text does not get relatively bigger or smaller. Only raster output gains anything: a PDF's page size in points and an SVG's physical size are unchanged by construction.
cvd: Simulate a colour-vision deficiency: "none" (default), "protanopia" (red-blind), "deuteranopia" (green-blind, the common one that breaks red/green encodings), "tritanopia" (blue-blind), or "achromatopsia" (total, and a fair proxy for greyscale printing). The simulation is a post-pass over the finished raster using the Machado et al. (2009) matrices applied in linear light, so it turns an accessibility check into a one-line change instead of an export-and-upload round trip. Raster output only — a vector format has no pixels to transform, and render() warns if you ask for one.

Value

vl_scene(), push(), draw(), pop(): a vellum_scene.

render(): path, invisibly.

Examples

s <- vl_scene(width = 4, height = 3) |>
  push(vl_viewport(xscale = c(0, 10), yscale = c(0, 10))) |>
  draw(rect_grob(gp = vl_gpar(fill = "grey95", col = "grey50"))) |>
  draw(lines_grob(x = vl_unit(0:10, "native"), y = vl_unit(0:10, "native"),
                  gp = vl_gpar(col = "steelblue", lwd = 2)))