#605 Advanced text mode driver using libcaca


This patch implements a new advanced text mode driver using libcaca. As the developers of this library, I am perfectly aware that this terminal driver "is the waste of time it looks to be. No need to tell me about that." (http://caca.zoy.org/wiki/libcaca). Still, it was fun implementing it.

In contrast to the dumb terminal, this is a full-fledged terminal and includes support for (RGB) colors, box fill, images, enhanced, rotated text, filled polygons and mouse interaction. It supports display on screen and export to a file. See `set term caca driver list` for a list of supported backend drivers on your platform.

Restrictions: Note that the number of colors supported by different libcaca backends differs. Most backends support 16 foreground and 16 background colors only, whereas e.g. the "x11" backend supports truecolor. Some backends only offer 8 different background colors and interpret the most significant bit of the background color as indicator for blinking text. If supported by the backend, the canvas size will be automatically adjusted to the current window/terminal size.

The caca terminal supports mouse interaction. Please beware that some backends of libcaca (e.g. slang, ncurses) only update the mouse position on mouse clicks. Modifier keys (ctrl, alt, shift) are not supported by libcaca and are thus unavailable.

So far, this terminal has been tested on Windows using MinGW (windowed and console mode), Ubuntu 12.04 and CentOS 6.

In the course of the development of this terminal, the Windows libcaca backend `win32` was extended considerably. A patch will be submitted to libcaca developers.

Current limitations/bugs I am aware of:
- rotated enhanced text not yet implemented
- alignment (right/center) of enhanced text is wrong
- alignment of rotated center|right aligned text is wrong
- hypertext not implemented
- size option is not considered for on-screen display
- key entry of filled polygons drawn at wrong position
- (sometimes) no blinking text cursor in wgnuplot text window
- endless loop in libcaca in case of illegal utf8 characters (bug in caca_put_str)
- Ctrl-C not working for CACA_DRIVER=slang


  • Bastian Märkisch

    • summary: Advanced text mode driver using libaca --> Advanced text mode driver using libcaca
  • Ethan Merritt

    Ethan Merritt - 2012-11-13

    This is a conceptual breakthrough in terminal diversity, reaching almost to the heights of the proposed "set term anthem"

    I compiled it without much trouble, but I must admit I'm having trouble understanding what I am seeing. I had expected it to produce output in the text terminal I was typing from, similar to the "dumb" terminal. But instead it pops up an X window of some sort in which it displays character cell data. But it's mouseable!. I highly recommend "set term caca; load 'rgb_variable.dem'". Mouse rotation of the RGB and HSV surfaces is a kick. I don't see a separate process controlling this display window - how does it work?

    </me> pokes around in the code a bit.
    Aha. The output options are not documented.

    Bug reports:
    (1) Please add a note
    set term caca driver list # prints a list of supported output modes
    and make sure that the listed options appear with quotes around them, since this seems to be required.

    (2) set term caca driver "ncurses"
    This works, but it is stuck in BLINK mode, which puts the poor gnuplot user at risk for photo-induced epileptic fits.
    Most point types (all but 2? hard to count while it's blinking) are rendered as '?'

    (3) UTF8 works in x11 mode, but not in ncurses mode.

    (4) set term caca driver "slang"
    What the heck is "slang"?
    All point and line elements are rendered as '?'

    (5) Interactive mode is fine, modulo the bugs listed above, but the process dies if running from a script. E.g.
    chauvet [86] ./gnuplot -e "set term caca driver 'ncurses'; load 'simple.dem'" < /bin/true
    Hit return to continue
    "simple.dem", line 32: y range must be greater than 0 for log scale

    The same demo runs fine if loaded interactively
    Update: It's only the "ncurses" mode that suffers from this. "x11" and "slang" work OK.


  • Bastian Märkisch

    Ethan, thanks for your enthusiasm!

    The revised patch includes scripts to create a full demo set for the web page, so that everybody can easily appreciate the beauty of this terminal's output. ;))

    Libcaca is a powerful library which offers numerous backend drivers. The x11 driver e.g. opens a x11 window and draws character cell data into it. Other drivers (e.g. ncurses, slang, win32) actually support "real" text mode output. To get pure text output on an utf8 aware linux console, you could use `set driver caca format "utf8"`. Btw. you can find information about the "S-Lang Library" at http://www.jedsoft.org/slang/. This library implements -amongst many other things- "screen management functions".

    Here are some comments to your bug reports:

    (1) Documented "set term caca driver list".

    (2),(3),(4): These are limitations of specific combinations of terminal (xterm etc.) and font and libcaca backend driver. You can manually change the character set used via the `charset blocks|ascii` option and background color via e.g. `background rgb "gray"`. Not much that could be done about this other than to choose more conservative defaults and provide additional options for point symbols etc. Instead, I added some comments to the docs.

    (5) No idea so far as to why you get that crash. I could not reproduce this on CentOS 5 using libcaca 0.99 beta 17 nor on Ubuntu 12.04 using libcaca 0.99 beta 18. Which versions of libcaca and *nix are you using?

    I could not resist and extended the patch slightly by implementing the following new features:

    Demo set for web page using SVG ouput.
    Terminal option for "inverted" (white on black) colors.
    Palette and RGB colour mapping for backends which cannot do truecolour.

    ... and bug fixes:

    Empirically fix size and placement of filled boxes.
    Fix rounding error in calculating the size of filled polygons.
    Count of available point symbols was off by one.
    Avoid endless loop for illegal utf8 characters in rotated text.
    Fix generic alignment of right- or center-justified text.
    Fix pause command in windows console mode.
    Extended help text.

    To make this terminal available to a wider audience, I would now like to submit it to CVS.

    Before doing that, I'd like to move some of the more generic support routines to some other modules.
    I propose to move the following routines, but I am unsure about proper destinations:

    static int gp_kbhit(void);
    Generic test for keyboard hit -> standard.c|h

    static unsigned long gp_time(void);
    Get time in musec for time stamps of events. -> util.c|h

    static void gp_raise_console(void);
    Raise the console. Could be used to replace code in wxt, win, pm and x11 terminals.
    Could also be used to be "bound" to space key. -> util.c|h ??

    static void gp_exec_event_immediate(char type, int mx, int my, int par1, int par2, int winid);
    Immediately execute event. Similar code found in vgagl.trm -> gpexecute.c|h

    static void WindowsMessageLoop(void);
    As it says: Windows message loop. Actually this is the same as TextMessage() which is unavailable in a console build. -> winmain.c


  • Ethan Merritt

    Ethan Merritt - 2012-11-27

    Darn it. I took some notes somewhere while testing this, but I seem to have misplaced them. The main thing I recall is that it doesn't autoconfigure or compile correctly without manual intervention, because
    - The configure script defines HAVE_LIB_CACA if it finds the library
    - But TERMLIBS is modified by adding $caca, which hasn't been defined so it fails at link time
    - The symbol HAVA_CACA_H is defined but not used anywhere, which means that compilation fails if caca.h is not found on the default path. (Configure should issue a warning if caca.h in this case, as other terminals do)

    After repairing the Makefile by hand, I get this error:
    In file included from term.h:438,
    from term.c:1440:
    ../term/caca.trm:1418: error: conflicting types for ‘CACA_process_events’
    ../term/caca.trm:681: note: previous implicit declaration of ‘CACA_process_events’ was here

    It needs a prototype at the top of the file, since the call site comes before the definition.

    The ncurses output is still blinking, which makes it unusable. Setting the backgound to black stops the blink (suggestion found on the web), but clearly something is wrong with the default setting.



    > static void gp_exec_event_immediate();
    > Immediately execute event. Similar code found in vgagl.trm -> gpexecute.c|h
    vgagl doesn't work for me, and I have a niggling worry that you may have found the cause. I'll look at this when I find time. From the name, it sounds similar to a distinction that is made by the wxt and Qt terminals also: some events are executed by the main thread ("immediate") and some are passed to the daughter thread for execution there instead.

  • Ethan Merritt

    Ethan Merritt - 2012-11-27

    Oh, and one comment on increasing the beauty (I'm assuming that comments on utility are pointless): I think the one thing that would make the most dramatic difference would be to maintain the background color of a cell when a symbol is placed on top of it. For example, have a look at the grid lines in the fillcrvs demo. Each cell that contains a grid line reverts to background color rather than keeping the filled curve color. It's clear from screen shots on the libcaca web page that the library itself is capable of setting both the foreground and background colors in a character cell so that an ascii character is printed on a colored background. Can characters be printed with some kind of overlay mode - that is, print character into cell (x,y) but keep the existing background color of that cell?

  • Bastian Märkisch

    caca terminal patch - 2012-11-20 - with "transparent" text and line drawing

  • Bastian Märkisch

    Brilliant idea! Transparent drawing as you describe it isn't currently supported by libcaca though (as far as I know anyway). So I hat to add 9 extra functions, which are mostly slightly modified copies of libcaca routines. In order not to overwrite filled polygons and boxes, fill patterns are now drawn with background and foreground colors exchanged.
    (I agree that this terminal is utterly useless. But see the recent feature request #3575055)

  • Ethan Merritt

    Ethan Merritt - 2012-11-28

    But something seems to have broken.
    When I tested the original version, the default output "x11" worked well, and I could choose "slang" instead for output into the current terminal.
    In the current version of the patch the default is "ncurses" (which still has problems). I can set it to "slang", which works, but setting it to "x11" causes the program to burn CPU in some infinite loop that never actually produces a plot.

    If I attach to the spinning process via gdb, I see it is stuck in
    (gdb) where
    #0 0x0811d8ba in CACA_process_events ()
    #1 0x0811bb36 in CACA_text ()
    #2 0x0810a65e in term_end_plot ()
    #3 0x08090d87 in do_plot ()

    Since it was working before, this probably indicates an inadvertent typo introduced after the first version of the patch.

  • Bastian Märkisch

    • assigned_to: Bastian Märkisch
    • Group: -->
  • Bastian Märkisch

    A revised version is now in CVS. It includes (as far as I remember) the following changes:

    • Interactive toggling of plots (uses replot),
      including modify_plots() interface
    • Hypertext
    • Boxed text
    • Transparent drawing of ruler
    • Attempt to combine box drawing characters when overdrawing
    • More fill characters / symbols
    • Fix of configure.in
    • Fix infinite loop in X11
    • Fix Ctrl-C when using slang driver
    • Fix disappearing cursor in wgnuplot
    • Many more checks for invalid parameters
    • Add a comment on "blinking" to help text.

    The terminal has still the following limitations (other than being character mode ;)):

    • Unicode support depends on driver, terminal and font used. Use charset option in case of problems.
    • Bright background colors may cause blinking. Use background rgb "gray" or invert options in that case.
    • Mousing does not support modifier keys.
    • Need to use set key width 1 height 1 to get correct key boxes.

    The terminal still has (at least) the following bugs:

    • Resizing x11 windows does not work on some systems.
    • Alignment of enhanced text is off if the string contains utf8 characters.
    • Win: Focus change when htting "space" doesn't work reliably.
    • Driver ncurses crashes when input is redirected from a pipe.

    Demo output using the svg driver of the caca terminal can be found at:
    The scripts needed to generate theses plot are derived from Ethan's webify scripts for the svg terminal and are attached here.

    Windows testing binaries are available at

  • Bastian Märkisch

    • status: open --> pending-accepted
  • Ethan Merritt

    Ethan Merritt - 2014-02-17
    • status: pending-accepted --> closed-accepted

Log in to post a comment.