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 */
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 */
/* Draw a string at (0, 0) */
caca_put_str(cv, 0, 0, "Hello world!");
/* Refresh display */
/* Wait for a key press event */
NULL, -1);
/* Clean up library */
caca_free_display(dp);
return 0;
}
|
Note the following important things:
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>
#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.
timeout
argument of -1.These functions are almost unchanged, except for Unicode support and the fact that they now act on a given canvas.
The newly introduced canvases can have several frames. Sprites are hence completely deprecated.
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.
The caca-config
utility is deprecated in favour of the standard pkg-config
interface:
caca-config
is still provided as a convenience tool but may be removed in the future.