libcaca developer documentation

0.9

Introduction

libcaca is a graphics library that outputs text instead of pixels, so that it can work on older video cards or text terminals. It is not unlike the famous AAlib library. libcaca can use almost any virtual terminal to work, thus it should work on all Unix systems (including Mac OS X) using either the slang library or the ncurses library, on DOS using the conio library, and on Windows systems using either slang or ncurses (through Cygwin emulation) or conio. There is also a native X11 driver that does not require a text terminal.

libcaca is free software, released under the GNU Lesser General Public License. This ensures that libcaca will always remain free software.

The libcaca API

The complete libcaca programming interface is available from the caca.h header.

Environment variables

Some environment variables can be used to change the behaviour of libcaca without having to modify the program which uses it. These variables are:

• CACA_DRIVER: set the backend video driver. In order of preference:
  • conio uses the DOS conio.h interface.
  • ncurses uses the ncurses library.
  • slang uses the S-Lang library.
  • x11 uses the native X11 driver.

• CACA_GEOMETRY: set the video display size. The format of this variable must be XxY, with X and Y being integer values. This option currently only works with the X11 driver.

• CACA_FONT: set the rendered font. The format of this variable is implementation dependent, but since it currently only works with the X11 driver, an X11 font name such as "fixed" or "5x7" is expected.

• CACA_BACKGROUND: set the background type.
  • solid uses solid coloured backgrounds for all characters. This feature does not work with all terminal emulators. This is the default choice.
  • black uses only black backgrounds to render characters.

• CACA_ANTIALIASING: set the antialiasing mode. Antialiasing smoothens the rendered image and avoids the commonly seen staircase effect.
  • none disables antialiasing.
  • prefilter uses a simple prefilter antialiasing method. This is the default choice.

• CACA_DITHERING: set the dithering mode. Dithering is necessary when rendering a picture that has more colours than the usually available palette.
  • none disables dithering.
  • ordered2 uses a 2x2 Bayer matrix for dithering.
  • ordered4 uses a 4x4 Bayer matrix for dithering. This is the default choice.
  • ordered8 uses a 8x8 Bayer matrix for dithering.
  • random uses random dithering.