libcaca documentation

A libcaca tutorial

First, a very simple working program, to check for basic libcaca functionalities.

#include <caca.h>
int main(void)
{
caca_canvas_t *cv; caca_display_t *dp; caca_event_t ev;
dp = caca_create_display(NULL);
if(!dp) return 1;
cv = caca_get_canvas(dp);
caca_set_display_title(dp, "Hello!");
caca_set_color_ansi(cv, CACA_BLACK, CACA_WHITE);
caca_put_str(cv, 0, 0, "This is a message");
caca_refresh_display(dp);
caca_get_event(dp, CACA_EVENT_KEY_PRESS, &ev, -1);
caca_free_display(dp);
return 0;
}
caca.h
The libcaca public header.
caca_canvas_t
struct caca_canvas caca_canvas_t
Definition caca.h:51
caca_display_t
struct caca_display caca_display_t
Definition caca.h:61
CACA_EVENT_KEY_PRESS
@ CACA_EVENT_KEY_PRESS
Definition caca.h:113
CACA_WHITE
@ CACA_WHITE
Definition caca.h:88
CACA_BLACK
@ CACA_BLACK
Definition caca.h:73
caca_set_color_ansi
int caca_set_color_ansi(caca_canvas_t *cv, uint8_t fg, uint8_t bg)
Set the default colour pair for text (ANSI version).
Definition attr.c:234
caca_put_str
__extern int caca_put_str(caca_canvas_t *, int, int, char const *)
Print a string.
Definition string.c:258
caca_create_display
caca_display_t * caca_create_display(caca_canvas_t *cv)
Attach a caca graphical context to a caca canvas.
Definition caca/caca.c:74
caca_refresh_display
__extern int caca_refresh_display(caca_display_t *)
Flush pending changes and redraw the screen.
Definition graphics.c:146
caca_get_canvas
caca_canvas_t * caca_get_canvas(caca_display_t *dp)
Get the canvas attached to a caca graphical context.
Definition caca/caca.c:265
caca_free_display
int caca_free_display(caca_display_t *dp)
Detach a caca graphical context from a caca backend context.
Definition caca/caca.c:244
caca_set_display_title
__extern int caca_set_display_title(caca_display_t *, char const *)
Set the display title.
Definition graphics.c:40
caca_get_event
__extern int caca_get_event(caca_display_t *, int, caca_event_t *, int)
Get the next mouse or keyboard input event.
Definition event.c:63
caca_event
Handling of user events.
Definition caca.h:132

What does it do?

- Create a display. Physically, the display is either a window or a context in a terminal (ncurses, slang) or even the whole screen (VGA).
- Get the display's associated canvas. A canvas is the surface where everything happens: writing characters, sprites, strings, images... It is unavoidable. Here the size of the canvas is set by the display.
- Set the display's window name (only available in windowed displays, does nothing otherwise).
- Set the current canvas colours to black background and white foreground.
- Write the string `"This is a message"` onto the canvas, using the current colour pair.
- Refresh the display, causing the text to be effectively displayed.
- Wait for an event of type `CACA_EVENT_KEY_PRESS`.
- Free the display (release memory). Since it was created together with the display, the canvas will be automatically freed as well.

You can then compile this code on an UNIX-like system using the following commans (requiring `pkg-config` and `gcc`):

gcc `pkg-config --libs --cflags caca` example.c -o example