libcaca-migrating.3caca man page

libcaca-migratingMigrating 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:

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

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.

Info

Sat Feb 11 2017 Version 0.99.beta19 libcaca