tgp: Terminal Graphics Protocol Device

In terminalgraphics: Graphical Output in Terminals

Terminal Graphics Protocol Device

Description

Terminal Graphics Protocol Device

Usage

tgp(
  width = getOption("term_width", max(480, min(1200, term_width(), term_height()/0.8))),
  height = getOption("term_height", 0.8 * width),
  units = "px",
  res = getOption("term_res", NA),
  ...,
  term_col = getOption("term_col", FALSE),
  term_bg = term_col,
  term_fg = term_col
)

Arguments

width	The width of the image. Passed on to agg_capture.
height	The height of the image. Passed on to agg_capture.
units	The units in which 'height' and 'width' are given. Passed on to agg_capture.
res	The resolution of the image. Passed on to agg_capture.
...	passed on to the underlying agg_capture device.
term_col	Logical value indicating that the foreground and background colors used in the plot should be set to that of the terminal.
term_bg	Logical value indicating that the background color used in the plot should be set to that of the terminal.
term_fg	Logical value indicating that the foreground color used in the plot should be set to that of the terminal.

Details

The function tries to detect whether the terminal supports Terminal Graphics Protocol. If not, it will issue a warning but still output the image to the terminal. Terminals that to not support Terminal Graphics Protocol will ignore the output. The warning is shown only once. Please file an issue when the terminal does support Terminal Graphics Protocol while has_tgp_support returns FALSE. The warning can be disabled using options(warned_tgp_support = TRUE).

Value

tgp is called for its side effect of opening a graphics device. Invisibly returns an list with two functions: plot will plot the current contents of the device in the terminal and update will plot the current contents of the device in the terminal if the contents have changed since the last plot.

term_replot will redraw the content of the device in the terminal. In principle term_replot is called automatically when the contents of the device changed. This function can be used to force plotting.

When term_bg = TRUE the background color of the graphics device ('bg') will be set using par. When term_fg = TRUE the foreground color ('fg', 'col', 'col.axis', 'col.lab', 'col.main', and 'sub') will be set using par.

Examples

if (has_tgp_support()) {
  # Open device
  tgp()
  plot(rnorm(100))
  abline(h = 0, lwd = 2, col = term_palette()[1])
}

terminalgraphics documentation built on Aug. 28, 2025, 9:09 a.m.