libcaca  0.99.beta19
About: libcaca is a graphics library that outputs text instead of pixels, so that it can work on older video cards or text terminals (something like an advanced AAlib library).
  Fossies Dox: libcaca-0.99.beta19.tar.gz  ("inofficial" and yet experimental doxygen-generated source code documentation)  

Migrating from libcaca 0.x to the 1.0 API

This section will guide you through the migration of a libcaca 0.x application to the latest API version.

Overview

The most important change in the 1.0 API of libcaca is the object-oriented design. See these two examples for a rough idea of what changed:

#include <caca.h>
/* libcaca program - 0.x API */
int main(void)
{
/* Initialise libcaca */
/* Set window title */
/* Choose drawing colours */
/* Draw a string at (0, 0) */
caca_putstr(0, 0, "Hello world!");
/* Refresh display */
/* Wait for a key press event */
/* Clean up library */
return 0;
}
#include <caca.h>
/* libcaca program - 1.0 API */
int main(void)
{
/* Initialise libcaca */
/* Set window title */
/* Choose drawing colours */
/* Draw a string at (0, 0) */
caca_put_str(cv, 0, 0, "Hello world!");
/* Refresh display */
/* Wait for a key press event */
NULL, -1);
/* Clean up library */
return 0;
}

Note the following important things:

  • Most functions now take an object handle as their first argument.

Migration strategy

You have two ways to migrate your application to use libcaca 1.x:

  • Port your code using the function equivalence list. This is the preferred way because new functions are thread safe and offer much more features to both the programmer and the end user.
  • Use the legacy compatibility layer.

Using the compatibility layer is as easy as adding the following three lines:

#include <caca.h>
/* libcaca program - 0.x API */
...
#include <caca.h>
#ifdef CACA_API_VERSION_1
# include <caca0.h>
#endif
/* libcaca program - 0.x API */
...

The modified code is guaranteed to build both with libcaca 0.x and libcaca 1.0.

Function equivalence list

Basic functions

Event handling

Character printing

Primitives drawing

These functions are almost unchanged, except for Unicode support and the fact that they now act on a given canvas.

Mathematical functions

  • caca_rand(): unchanged, but the second argument is different, make sure you take that into account.
  • caca_sqrt(): this function is now deprecated, use your system's sqrt() call instead.

Sprite handling

The newly introduced canvases can have several frames. Sprites are hence completely deprecated.

Bitmap handling

Bitmaps have been renamed to dithers, because these objects do not in fact store any pixels, they just have information on how bitmaps will be dithered.

Compilation

The caca-config utility is deprecated in favour of the standard pkg-config interface:

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

caca-config is still provided as a convenience tool but may be removed in the future.

caca
Definition: __init__.py:1
caca_create_display
caca_display_t * caca_create_display(caca_canvas_t *cv)
Attach a caca graphical context to a caca canvas.
Definition: caca.c:68
caca_wait_event
#define caca_wait_event(x)
Definition: caca0.h:137
caca_display
Definition: caca_internals.h:167
caca_set_color
#define caca_set_color(x, y)
Definition: caca0.h:141
CACA_WHITE
Definition: caca.h:86
caca_put_str
int caca_put_str(caca_canvas_t *, int, int, char const *)
Print a string.
Definition: string.c:254
caca_get_canvas
caca_canvas_t * caca_get_canvas(caca_display_t *dp)
Get the canvas attached to a caca graphical context.
Definition: caca.c:259
cv
caca_canvas_t * cv
Definition: cacaview.c:45
caca_refresh
#define caca_refresh()
Definition: caca0.h:133
caca_init
#define caca_init
Definition: caca0.h:122
caca_set_window_title
#define caca_set_window_title(s)
Definition: caca0.h:130
caca_refresh_display
int caca_refresh_display(caca_display_t *)
Flush pending changes and redraw the screen.
Definition: graphics.c:146
caca_free_display
int caca_free_display(caca_display_t *dp)
Detach a caca graphical context from a caca backend context.
Definition: caca.c:238
caca_putstr
#define caca_putstr(x, y, s)
Definition: caca0.h:147
CACA_COLOR_WHITE
#define CACA_COLOR_WHITE
Definition: caca0.h:75
CACA_BLACK
Definition: caca.h:71
caca_set_display_title
int caca_set_display_title(caca_display_t *, char const *)
Set the display title.
Definition: graphics.c:40
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.h
The libcaca public header.
caca_get_event
#define caca_get_event(x)
Definition: caca0.h:136
CACA_EVENT_KEY_PRESS
Definition: caca.h:111
dp
caca_display_t * dp
Definition: cacaview.c:45
caca0.h
caca_canvas
Definition: caca_internals.h:47
caca_end
#define caca_end
Definition: caca0.h:134
CACA_COLOR_BLACK
#define CACA_COLOR_BLACK
Definition: caca0.h:60
main
int main(int argc, char *argv[])
Definition: cxxtest.cpp:39