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 changes in the 1.0 API of libcaca are the libcaca / libcucul split and 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 
    caca_init();
     Set window title 
    caca_set_window_title("Window");
     Choose drawing colours 
    caca_set_color(CACA_COLOR_BLACK,
                   CACA_COLOR_WHITE);
     Draw a string at (0, 0) 
    caca_putstr(0, 0, "Hello world!");
     Refresh display 
    caca_refresh();
     Wait for a key press event 
    caca_wait_event(CACA_EVENT_KEY_PRESS);
     Clean up library 
    caca_end();

    return 0;
}
#include <cucul.h>
#include <caca.h>

 libcaca program - 1.0 API 
int main(void)
{
     Initialise libcaca 
    cucul_canvas_t *cv;
    caca_display_t *dp;
    cv = cucul_create_canvas(0, 0);
    dp = caca_create_display(cv);
     Set window title 
    caca_set_display_title(dp, "Window");
     Choose drawing colours 
    cucul_set_color_ansi(cv, CUCUL_BLACK,
                             CUCUL_WHITE);
     Draw a string at (0, 0) 
    cucul_put_str(cv, 0, 0, "Hello world!");
     Refresh display 
    caca_refresh_display();
     Wait for a key press event 
    caca_get_event(dp, CACA_EVENT_KEY_PRESS,
                   NULL, -1);
     Clean up library 
    caca_free_display(dp);
    cucul_free_canvas(cv);

    return 0;
}

Note the following important things:

Migration strategy

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

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 
...

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

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.