Sixel

Sixel ("six pixels") does not appear to have any true, up-to-date "standard" (Thomas Dickey's XTerm Control Sequences document is probably the closest thing). It seems to have been introduced on DEC printers, and made its first glass appearance on the VT125, though the VT3xx documentation gets the most play (the VT340 appears to have been the first terminal which could sensibly scroll pixel graphics). A single sixel combines a set of programmable color registers with a vertical stack of six pixels; a sixel sprite (sprixel?) is MxN pixels where N is a multiple of 6. It is probably the most widely implemented method of pixel graphics for terminal emulators (kitty has its own protocol, as does ITerm2). ReGIS is a similar method for vector graphics. A single horizontal strip of sixels is a "band"; a sprixel has one or more bands.

Sixels are specified using only printable ASCII characters, and are thus 7-bit clean.

A sprixel must typically be emitted as a single unit to be rendered as a coherent whole (i.e. without gaps between bands). Sprixels do not annihilate entire cells, but only the pixels covered. A glyph emitted atop a sixel will annihilate all pixels contained within the cell.

Syntax

Before emitting a sprixel, the terminal must first be put into the appropriate mode via "\ePq" (FIXME details on 8-bit, start params). Properly exit the mode with "\e\\" (FIXME again 8-bit). FIXME what about \e[?80h?

The mode switch may be followed by an optional quartet of parameters, separated by semicolons:

AspectX;AspectY;LenX;LenY

I'm not yet completely sure of the effect of these parameters FIXME.

Color registers precede the band data en bloc. Each color register takes the form "#N;T;a;b;c" where N is the register and T is the type (see below).

Bands are separated by hyphens ('-'). Return to the start of a band without moving to the next one (i.e. to draw another color) with '$'. The same number of sixels ought be provided for each color used in a band (but they may of course be the empty sixel). For each sixel, determine which of the six pixels 0..5 (0 on the top, 5 on the bottom) match the color, and and for each pixel N, add 2ⁿ. The result will be between 0 and 63, inclusive. Add 63 to this total; the sixel is the corresponding ASCII character (between 63 and 126, inclusive). When a sixel is repeated four or more times in a row, use "!n" to runlength encode the series.

If a given pixel is unspecified (i.e. no band includes the pixel), the behavior is dependent on whether the Set Raster Attributes control sequence has been emitted. If it has, unspecified pixels are drawn with Color Register 0. If it has not, they are not touched. For transparency with regards to existing material, then, Set Raster Attributes must not be used.

Color registers

A terminal supports some number of color registers for each sprixel. For xterm, this is controlled by the numColorRegisters resource (set to a (low) value based off decTerminalID if not explicitly provided):

XTerm*numColorRegisters: 1024

Each register is specified with a type ("1" for HSL, "2" for RGB) and three components, each between 0 and 100 inclusive. Assuming 8bpc RGB, every 2.6 bits of component get squashed to 1.

The privateColorRegisters resource (default: "true") determines whether each sixel escape sequence controls its own distinct color registers, or whether they're shared by all sprixels.

Complexifiers

• At least on xterm (this does not appear to happen with mlterm), when a sprixel is emitted to the alternate screen, it will be redrawn upon the next entry to the alternate screen.

scrolling, scrollback, terminal resize, zoom (font change), overlapping, is the color register limit per-sprixel or per-terminal, geometry arguments, background, maximum size FIXME

Detecting support

Send Device Attributes can be used to detect Sixel support. Send CSI Ps c. If the VT220-level reply contains a '4', sixel graphics are supported.

Detecting details

XTSMGRAPHICS can be used to set and retrieve Sixel-related configuration, if Sixel is supported. Send CSI ? Pi ; Pa ; Pv S where

• Pi == 1, color registers
• Pi == 2, maximum geometry
• Pa == 1, read
• Pa == 2, reset to default
• Pa == 3, set to Pv
• Pa == 4, read maximum value

For color registers, the maximum value is the absolute maximum supported by the application. For geometry, the current value is affected by current window geometry in addition to configuration.

Known support

• xterm supports scrolling sprixels when compiled with --enable-sixel-graphics
  • and launched with at least a vt340 decGraphicsID (or decTerminalID)
• mlterm works
• alacritty has a patch outstanding to add support, but it is not yet merged as of 0.8.0-dev
• VTE supports sprixels when built with -Dsixel=true
• Microsoft's Windows Terminal is said to support sixel

See also

• Notcurses supports sixel intermingled with standard TUI elements
• libsixel is pretty complete