libcaca-migrating.3caca - Man Page


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.


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 */
    /* Set window title */
    /* Choose drawing colours */
    /* Draw a string at (0, 0) */
    caca_putstr(0, 0, "Hello world!");
    /* Refresh display */
    /* Wait for a key press event */
    /* Clean up library */

    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,
    /* Draw a string at (0, 0) */
    caca_put_str(cv, 0, 0, "Hello world!");
    /* Refresh display */
    /* Wait for a key press event */
    caca_get_event(dp, CACA_EVENT_KEY_PRESS,
                   NULL, -1);
    /* Clean up library */

    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>
#   include <caca0.h>

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


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.


Fri Jan 20 2023 Version 0.99.beta20 libcaca