Migrating from libcaca 0.9 to the 1.0 API

This section will guide you through the migration of a libcaca 0.9 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. Where you used to do:

#include <caca.h>

int main(void)
{
    /* Initialise libcaca */
    caca_init();
    /* Set window title */
    caca_set_window_title("Hello!");
    /* Choose drawing colours */
    caca_set_color(CACA_COLOR_BLACK, CACA_COLOR_WHITE);
    /* Draw a string at coordinates (0, 0) */
    caca_putstr(0, 0, "This is a message");
    /* Refresh display */
    caca_refresh();
    /* Wait for a key press event */
    caca_wait_event(CACA_EVENT_KEY_PRESS);
    /* Clean up library */
    caca_end();

    return 0;
}

You now do:

#include <cucul.h>
#include <caca.h>

int main(void)
{
    /* Initialise libcaca */
    cucul_canvas_t *cv; caca_display_t *dp; caca_event_t ev;
    cv = cucul_create_canvas(0, 0);
    dp = caca_create_display(cv);
    /* Set window title */
    caca_set_display_title(dp, "Hello!");
    /* Choose drawing colours */
    cucul_set_color(cv, CUCUL_COLOR_BLACK, CUCUL_COLOR_WHITE);
    /* Draw a string at coordinates (0, 0) */
    cucul_putstr(cv, 0, 0, "This is a message");
    /* Refresh display */
    caca_refresh_display();
    /* Wait for a key press event */
    caca_get_event(dp, CACA_EVENT_KEY_PRESS, &ev, -1);
    /* Clean up library */
    caca_free_display(dp);
    cucul_free_canvas(cv);

    return 0;
}

Note the following important things:

• Functions now take an object handle as their first argument.
• All input/output functions start with caca_ and all drawing and text handling functions start with cucul_ .

Function equivalence list

Basic functions

• caca_init(): use cucul_create_canvas() to create a libcucul canvas, followed by caca_create_display() to attach a libcaca display to it.
• caca_set_delay(): unchanged.
• caca_get_feature(): deprecated.
• caca_set_feature(): deprecated, see cucul_set_dither_antialias(), cucul_set_dither_color() and cucul_set_dither_mode() instead.
• caca_get_feature_name(): deprecated, see cucul_get_dither_mode_list(), cucul_get_dither_antialias_list() and cucul_get_dither_color_list() instead.
• caca_get_rendertime(): unchanged.
• caca_get_width(): use cucul_get_canvas_width().
• caca_get_height(): use cucul_get_canvas_height().
• caca_set_window_title(): use caca_set_display_title().
• caca_get_window_width(): use caca_get_display_width().
• caca_get_window_height(): use caca_get_display_height().
• caca_refresh(): use caca_refresh_display().
• caca_end(): use caca_free_display() to detach the libcaca display, followed by cucul_free_canvas() to free the underlying libcucul canvas.

Event handling

• caca_get_event(): unchanged.
• caca_wait_event(): use caca_get_event() with a timeout argument of -1.
• caca_get_mouse_x(): unchanged.
• caca_get_mouse_y(): unchanged.

Character printing

• caca_set_color(): use cucul_set_color() or cucul_set_truecolor().
• caca_get_fg_color(): deprecated.
• caca_get_bg_color(): deprecated.
• caca_get_color_name(): use cucul_get_color_name().
• caca_putchar(): use cucul_putchar().
• caca_putstr(): use cucul_putstr().
• caca_printf(): use cucul_printf().
• caca_clear(): use cucul_clear_canvas().

Primitives drawing

• caca_draw_line(): use cucul_draw_line().
• caca_draw_polyline(): use cucul_draw_polyline().
• caca_draw_thin_line(): use cucul_draw_thin_line().
• caca_draw_thin_polyline(): use cucul_draw_thin_polyline().

• caca_draw_circle(): use cucul_draw_circle().
• caca_draw_ellipse(): use cucul_draw_ellipse().
• caca_draw_thin_ellipse(): use cucul_draw_thin_ellipse().
• caca_fill_ellipse(): use cucul_fill_ellipse().

• caca_draw_box(): use cucul_draw_box().
• caca_draw_thin_box(): use cucul_draw_thin_box().
• caca_fill_box(): use cucul_fill_box().

• caca_draw_triangle(): use cucul_draw_triangle().
• caca_draw_thin_triangle(): use cucul_draw_thin_triangle().
• caca_fill_triangle(): use cucul_fill_triangle().

Mathematical functions

• caca_rand(): use cucul_rand()
• caca_sqrt(): this function is now deprecated

Sprite handling

The sprite handling functions are currently being reworked.

Bitmap handling

• caca_create_bitmap(): use cucul_create_dither().
• caca_set_bitmap_palette(): use cucul_set_dither_palette().
• caca_draw_bitmap(): use cucul_dither_bitmap().
• caca_free_bitmap(): use cucul_free_dither().

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 will be removed in the future.