Library/SDK

A reference implementation of the ctx protocol is provided as a single header librare. Interactive Applications written using the C library can run either inside the ctx terminal, or stand-alone using SDL2, fbdev/KMS or in-terminal unicode quads/sextants/ascii as output.

To experiment with ctx, the demo clients included in the source repository is the easiest route, to build the clients as well as the ctx terminal do:

~/src/ $ git clone https://ctx.graphics/.git/
Fetching objects: 10294, done.
~/src$ cd ctx.graphics/
~/src/ctx.graphics$ ./configure.sh
configuration of optional depenencies complete:
    SDL2 yes
    babl yes
    alsa yes
 libcurl yes

Ready to build
~/src/ctx.graphics$ make

When done you should be able to run the ctx terminal with

~/src/ctx.graphics$ ./ctx

The ctx binary is a busybox like binary with many features - and is used as part of the ctx regression tracking by generating unicode braille and grayscale raster tests, it can act as a standalone image viewer and text editor both inside and outside the ctx terminal if you pass it the path to a file.

The clients folder contains demo programs and scripts for the terminal.

Running directly with the SDL2 or framebuffer backends has higher performance than going through the terminal abstraction, reducing this gap through tuning and refactoring is a work in progress, for applications the difference between 12fps and 120fps is smaller and small rather than global updates are done.

HTML5 canvas 2D context
Easily bindable C API and protocol building on this standard, along with extensions from SVG. Compositing and blending is according to compositing and blending level 2; ctx permits all blending modes to be combined with all compositing modes.
backends: ctx, linux/openbsd KMS, linux/netbsd framebuffer, SDL2, braille
ctx comes with 5 interactive backends, the ctx backend renders the ctx protocol to stdout, and reads input, this provides the client interface for interactive vector clients running in the ctx terminal.
DRM and fbdev backend takes take keyboard input from stdin and tries to read mouse events are from /dev/input/mice. The SDL2 backend permits using ctx clients under wayland/X11 and probably other platforms.
RGB and CMYK, 8pc and 32bit floating point
Supporting RGB332, RGB565 and grayscale + 1bit mode render targets. ICC based color management of RGB user/device spaces through babl as an optional dependency. CMYK colors can be generated on the fly from RGB or set and retained in CMYK mode - when set in CMYK mode the colors correspond directly to the device colors in CMYK mode.

deferred rendering
These drawlist representations are used for scanline/chunk-based rendering on microcontrollers where framebuffer is to large to fit in RAM and tiles and threaded rendering on multi-core systems with SDL2 and /dev/fb0 backends and network transparent rendering inside ctx terminal. Another way to drive larger than RAM is to re-render the frame for each segment instead of buffering it, buffering is however useful when doing networked rendering, ctx can be configured and adapted to deal with a wide range of scenarios. .
text rendering
Four font loading backends, harfbuzz, stb_truetype, native-ctx and ctx-fs. The ctx.h header ships with a built-in native-ctx font. The text-shaping is done per-word with harfbuzz when harfbuzz based fonts are used. Otherwise only basic fi fl ff ligatures are applied. Along with horizontal advances and kerning, RTL or vertical glyph advances.
sixels
DEC terminal family standard for raster graphics transfer
kitty graphics
kitty style raster graphics transfer
iterm2 inline images
iterm2 style raster grarphics transfer
atty
audio recording and playback (only raw pcm for now, opus codec NYI)
stb_truetype.h
If the declarations for stb_truetype are included before ctx.h - functions to load fonts from TTF/OTF files become available.
SDL2
Optional backend and support code that that gets build when SDL.h is included before ctx.h
cairo
support code to render to cairo contexts if cairo.h is included before ctx.h, useful for conformance verfication and SVG and PDF output.

The single header and static binaries for download are autogenerated together with this website each time the git repository is synched.

ctx.h1.5mbThe singleheader library ctx, batteries included.
git repo 
$ git clone https://ctx.graphics/.git
The repository contains the sources for examples and tests, and the implementation of 2D vector rasterization and protocl parser and serializer.

Environment variables

CTX_BACKEND
Override the backend used for interactive ctx applications, possible values:
auto (default)
try - in order: ctx, SDL2, kms, fb, term
ctx
use the ctx protocol, takes over the current tab in ctx-terminal as display window.
kms
linux kms
fb
linux framebuffer opening /dev/fb or /dev/fb0
term
output by converting to terminal graphics, with text at default font size mapped to actual text.
CTX_THREADS
The number of rendering threads to use, defaults to number of cores.
CTX_TERM_MODE
Controls the characters used for drawing in CTX_BACKEND=term mode, possible values:
sextant (default)
use teletext sextant mosaic characters
ascii
Use a subset of ascii characters
quarter
Use quarter pixels
braille
Use braille characters varying only foreground color
CTX_TERM_FORCE_FULL
if set to non 0/no always send the full frame instead of optimizing for lower bandwidth usage - should noe be needed apart for debugging.
CTX_DAMAGE_CONTROL
Visualize which cached pixels are pushed to display
CTX_HASH_CACHE
if set to 0 turns off the hash cache - this means that the full frame is rerendered every time, useful to verify if bugs involving non-updating bits of the screen is related to incompleteness of hashing.

Binary protocol encoding

There is a corresponding binary encoding, it is somewhat stable but it is is better to rely on the text format for compatible exchange. In the binary form the commands and their arguments are broken down into 9 byte long chunks, where the first byte is the short-form from the table above and parameters are encoded.

future work

pressing issues

When this list is nearing 0 it is time for a tarball/versioned release of ctx. The single header ctx.h linked from this page is a rolling release.

desirable improvements