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
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 <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:
- •
- 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¶
- •
- 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.
- •
- caca_set_delay(): use
caca_set_display_time().
- •
- caca_get_feature(): deprecated.
- •
- caca_set_feature(): deprecated, see
caca_set_dither_antialias(), caca_set_dither_color() and
caca_set_dither_mode() instead.
- •
- caca_get_feature_name(): deprecated, see
caca_get_dither_mode_list(), caca_get_dither_antialias_list() and
caca_get_dither_color_list() instead.
- •
- caca_get_rendertime(): use
caca_get_display_time().
- •
- caca_get_width(): use
caca_get_canvas_width().
- •
- caca_get_height(): use
caca_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 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¶
- •
- caca_get_event(): unchanged, but
the event information retrieval changed a lot.
- •
- 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 caca_set_color_ansi()
or caca_set_color_argb().
- •
- caca_get_fg_color(): use
caca_get_attr().
- •
- caca_get_bg_color(): use
caca_get_attr().
- •
- caca_get_color_name(): this function is now
deprecated due to major uselessness.
- •
- caca_putchar(): use caca_put_char().
- •
- caca_putstr(): use caca_put_str().
- •
- caca_printf(): unchanged.
- •
- 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.
- •
- caca_draw_line():
unchanged.
- •
- caca_draw_polyline():
unchanged.
- •
- caca_draw_thin_line():
unchanged.
- •
- caca_draw_thin_polyline():
unchanged.
- •
- caca_draw_circle():
unchanged.
- •
- caca_draw_ellipse():
unchanged.
- •
- caca_draw_thin_ellipse():
unchanged.
- •
- caca_fill_ellipse():
unchanged.
- •
- caca_draw_box(): unchanged, but the
argument meaning changed (width and height instead of corner
coordinates).
- •
- 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).
- •
- caca_fill_box(): unchanged, but the
argument meaning changed (width and height instead of corner
coordinates).
- •
- caca_draw_triangle():
unchanged.
- •
- caca_draw_thin_triangle():
unchanged.
- •
- caca_fill_triangle():
unchanged.
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.
- •
- caca_load_sprite(): use caca_import_file().
- •
- caca_get_sprite_frames(): use
caca_get_frame_count().
- •
- caca_get_sprite_width(): use
caca_get_canvas_width().
- •
- caca_get_sprite_height(): use
caca_get_canvas_height().
- •
- caca_get_sprite_dx(): use
caca_get_canvas_handle_x().
- •
- caca_get_sprite_dy(): use
caca_get_canvas_handle_y().
- •
- caca_draw_sprite(): use caca_set_frame() and
caca_blit().
- •
- 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.
- •
- caca_create_bitmap(): use
caca_create_dither().
- •
- caca_set_bitmap_palette(): use
caca_set_dither_palette().
- •
- caca_draw_bitmap(): use
caca_dither_bitmap().
- •
- caca_free_bitmap(): use
caca_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 may be removed in the
future.