libcaca-migrating(3caca)

NAME

libcaca-migrating - 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 objectoriented 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 <caca.h>
/* libcaca program - 1.0 API */ int main(void) {: /* Initialise libcaca */
caca_canvas_t *cv;
caca_display_t *dp;
dp = caca_create_display(NULL);
cv = caca_get_canvas(dp);
/* Set window title */
caca_set_display_title(dp, 'Window');
/* Choose drawing colours */
caca_set_color_ansi(cv, CACA_BLACK,
CACA_WHITE);; /* Draw a string at (0, 0) */
caca_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);; return 0;
}
Note the following important things:
o 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:

o 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.
o 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: o caca_init(): use caca_create_canvas() to create a libcaca canvas,
followed by caca_create_display() to attach a libcaca display to it. Alternatively, caca_create_display() with a NULL argument will create a canvas automatically.; o caca_set_delay(): use caca_set_display_time().; o caca_get_feature(): deprecated.; o caca_set_feature(): deprecated, see caca_set_dither_antialias(),
caca_set_dither_color() and caca_set_dither_mode() instead.; o caca_get_feature_name(): deprecated, see caca_get_dither_mode_list(),
caca_get_dither_antialias_list() and caca_get_dither_color_list() instead.; o caca_get_rendertime(): use caca_get_display_time().; o caca_get_width(): use caca_get_canvas_width().; o caca_get_height(): use caca_get_canvas_height().; o caca_set_window_title(): use caca_set_display_title().; o caca_get_window_width(): use caca_get_display_width().; o caca_get_window_height(): use caca_get_display_height().; o caca_refresh(): use caca_refresh_display().; o caca_end(): use caca_free_display() to detach the libcaca display,
followed by caca_free_canvas() to free the underlying libcaca canvas. Alternatively, if the canvas was created by caca_create_display(), it will be automatically destroyed by caca_free_display().
Event handling: o caca_get_event(): unchanged, but the event information retrieval
changed a lot.; +o caca_wait_event(): use caca_get_event() with a timeout argument of
-1.; o caca_get_mouse_x(): unchanged.; +o caca_get_mouse_y(): unchanged.
Character printing: o caca_set_color(): use caca_set_color_ansi() or caca_set_color_argb().; o caca_get_fg_color(): use caca_get_attr().; o caca_get_bg_color(): use caca_get_attr().; o caca_get_color_name(): this function is now deprecated due to major
uselessness.; o caca_putchar(): use caca_put_char().; o caca_putstr(): use caca_put_str().; o caca_printf(): unchanged.; +o caca_clear(): use caca_clear_canvas().
Primitives drawing: These functions are almost unchanged, except for Unicode support and
the fact that they now act on a given canvas.; o caca_draw_line(): unchanged.; +o caca_draw_polyline(): unchanged.; +o caca_draw_thin_line(): unchanged.; +o caca_draw_thin_polyline(): unchanged.; o caca_draw_circle(): unchanged.; +o caca_draw_ellipse(): unchanged.; +o caca_draw_thin_ellipse(): unchanged.; +o caca_fill_ellipse(): unchanged.; o caca_draw_box(): unchanged, but the argument meaning changed (width
and height instead of corner coordinates).; +o caca_draw_thin_box(): use caca_draw_thin_box() or
caca_draw_cp437_box(), also the argument meaning changed (width and height instead of corner coordinates).; +o caca_fill_box(): unchanged, but the argument meaning changed (width
and height instead of corner coordinates).; o caca_draw_triangle(): unchanged.; +o caca_draw_thin_triangle(): unchanged.; +o caca_fill_triangle(): unchanged.
Mathematical functions: o caca_rand(): unchanged, but the second argument is different, make
sure you take that into account.; +o 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.; o caca_load_sprite(): use caca_import_file().; o caca_get_sprite_frames(): use caca_get_frame_count().; o caca_get_sprite_width(): use caca_get_canvas_width().; o caca_get_sprite_height(): use caca_get_canvas_height().; o caca_get_sprite_dx(): use caca_get_canvas_handle_x().; o caca_get_sprite_dy(): use caca_get_canvas_handle_y().; o caca_draw_sprite(): use caca_set_frame() and caca_blit().; o caca_free_sprite(): use caca_free_canvas().
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.; o caca_create_bitmap(): use caca_create_dither().; o caca_set_bitmap_palette(): use caca_set_dither_palette().; o caca_draw_bitmap(): use caca_dither_bitmap().; o caca_free_bitmap(): use caca_free_dither().

Compilation

The caca-config utility is deprecated in favour of the standard pkgconfig 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.

docs.sk