.TH "libcaca-migrating" 3caca "Sat Apr 6 2019" "Version 0.99.beta19" "libcaca" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libcaca-migratingMigrating from libcaca 0\&.x to the 1\&.0 API 
 \- This section will guide you through the migration of a \fIlibcaca\fP 0\&.x application to the latest API version\&.
.SH "Overview"
.PP
The most important change in the 1\&.0 API of \fIlibcaca\fP is the object-oriented design\&. See these two examples for a rough idea of what changed:
.PP
.PP
.nf
#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;
}
.fi
.PP
 
.PP
.nf
#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;
}

.fi
.PP
 
.PP
Note the following important things:
.PP
.IP "\(bu" 2
Most functions now take an object handle as their first argument\&.
.PP
.SH "Migration strategy"
.PP
You have two ways to migrate your application to use \fIlibcaca\fP 1\&.x:
.PP
.IP "\(bu" 2
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\&.
.IP "\(bu" 2
Use the legacy compatibility layer\&.
.PP
.PP
Using the compatibility layer is as easy as adding the following three lines:
.PP
.PP
.nf
#include <caca\&.h>

/* libcaca program - 0\&.x API */
\&.\&.\&.
.fi
.PP
 
.PP
.nf
#include <caca\&.h>
#ifdef CACA_API_VERSION_1
#   include <caca0\&.h>
#endif

/* libcaca program - 0\&.x API */
\&.\&.\&.

.fi
.PP
 
.PP
The modified code is guaranteed to build both with \fIlibcaca\fP 0\&.x and \fIlibcaca\fP 1\&.0\&.
.SH "Function equivalence list"
.PP
.SS "Basic functions"
.IP "\(bu" 2
\fBcaca_init()\fP: use \fBcaca_create_canvas()\fP to create a \fIlibcaca\fP canvas, followed by \fBcaca_create_display()\fP to attach a \fIlibcaca\fP display to it\&. Alternatively, \fBcaca_create_display()\fP with a NULL argument will create a canvas automatically\&.
.IP "\(bu" 2
\fBcaca_set_delay()\fP: use \fBcaca_set_display_time()\fP\&.
.IP "\(bu" 2
\fBcaca_get_feature()\fP: deprecated\&.
.IP "\(bu" 2
\fBcaca_set_feature()\fP: deprecated, see \fBcaca_set_dither_antialias()\fP, \fBcaca_set_dither_color()\fP and caca_set_dither_mode() instead\&.
.IP "\(bu" 2
\fBcaca_get_feature_name()\fP: deprecated, see caca_get_dither_mode_list(), \fBcaca_get_dither_antialias_list()\fP and \fBcaca_get_dither_color_list()\fP instead\&.
.IP "\(bu" 2
\fBcaca_get_rendertime()\fP: use \fBcaca_get_display_time()\fP\&.
.IP "\(bu" 2
\fBcaca_get_width()\fP: use \fBcaca_get_canvas_width()\fP\&.
.IP "\(bu" 2
\fBcaca_get_height()\fP: use \fBcaca_get_canvas_height()\fP\&.
.IP "\(bu" 2
\fBcaca_set_window_title()\fP: use \fBcaca_set_display_title()\fP\&.
.IP "\(bu" 2
\fBcaca_get_window_width()\fP: use \fBcaca_get_display_width()\fP\&.
.IP "\(bu" 2
\fBcaca_get_window_height()\fP: use \fBcaca_get_display_height()\fP\&.
.IP "\(bu" 2
\fBcaca_refresh()\fP: use \fBcaca_refresh_display()\fP\&.
.IP "\(bu" 2
\fBcaca_end()\fP: use \fBcaca_free_display()\fP to detach the \fIlibcaca\fP display, followed by \fBcaca_free_canvas()\fP to free the underlying \fIlibcaca\fP canvas\&. Alternatively, if the canvas was created by \fBcaca_create_display()\fP, it will be automatically destroyed by \fBcaca_free_display()\fP\&.
.PP
.SS "Event handling"
.IP "\(bu" 2
\fB\fBcaca_get_event()\fP\fP: unchanged, but the event information retrieval changed a lot\&.
.IP "\(bu" 2
\fBcaca_wait_event()\fP: use \fBcaca_get_event()\fP with a \fCtimeout\fP argument of \fB-1\fP\&.
.IP "\(bu" 2
\fB\fBcaca_get_mouse_x()\fP\fP: unchanged\&.
.IP "\(bu" 2
\fB\fBcaca_get_mouse_y()\fP\fP: unchanged\&.
.PP
.SS "Character printing"
.IP "\(bu" 2
\fBcaca_set_color()\fP: use \fBcaca_set_color_ansi()\fP or \fBcaca_set_color_argb()\fP\&.
.IP "\(bu" 2
\fBcaca_get_fg_color()\fP: use \fBcaca_get_attr()\fP\&.
.IP "\(bu" 2
\fBcaca_get_bg_color()\fP: use \fBcaca_get_attr()\fP\&.
.IP "\(bu" 2
\fBcaca_get_color_name()\fP: this function is now deprecated due to major uselessness\&.
.IP "\(bu" 2
\fBcaca_putchar()\fP: use \fBcaca_put_char()\fP\&.
.IP "\(bu" 2
\fBcaca_putstr()\fP: use \fBcaca_put_str()\fP\&.
.IP "\(bu" 2
\fB\fBcaca_printf()\fP\fP: unchanged\&.
.IP "\(bu" 2
\fBcaca_clear()\fP: use \fBcaca_clear_canvas()\fP\&.
.PP
.SS "Primitives drawing"
These functions are almost unchanged, except for Unicode support and the fact that they now act on a given canvas\&.
.PP
.IP "\(bu" 2
\fB\fBcaca_draw_line()\fP\fP: unchanged\&.
.IP "\(bu" 2
\fB\fBcaca_draw_polyline()\fP\fP: unchanged\&.
.IP "\(bu" 2
\fB\fBcaca_draw_thin_line()\fP\fP: unchanged\&.
.IP "\(bu" 2
\fB\fBcaca_draw_thin_polyline()\fP\fP: unchanged\&.
.IP "\(bu" 2
\fB\fBcaca_draw_circle()\fP\fP: unchanged\&.
.IP "\(bu" 2
\fB\fBcaca_draw_ellipse()\fP\fP: unchanged\&.
.IP "\(bu" 2
\fB\fBcaca_draw_thin_ellipse()\fP\fP: unchanged\&.
.IP "\(bu" 2
\fB\fBcaca_fill_ellipse()\fP\fP: unchanged\&.
.IP "\(bu" 2
\fB\fBcaca_draw_box()\fP\fP: unchanged, but the argument meaning changed (width and height instead of corner coordinates)\&.
.IP "\(bu" 2
\fB\fBcaca_draw_thin_box()\fP\fP: use \fBcaca_draw_thin_box()\fP or \fBcaca_draw_cp437_box()\fP, also the argument meaning changed (width and height instead of corner coordinates)\&.
.IP "\(bu" 2
\fB\fBcaca_fill_box()\fP\fP: unchanged, but the argument meaning changed (width and height instead of corner coordinates)\&.
.IP "\(bu" 2
\fB\fBcaca_draw_triangle()\fP\fP: unchanged\&.
.IP "\(bu" 2
\fB\fBcaca_draw_thin_triangle()\fP\fP: unchanged\&.
.IP "\(bu" 2
\fB\fBcaca_fill_triangle()\fP\fP: unchanged\&.
.PP
.SS "Mathematical functions"
.IP "\(bu" 2
\fBcaca_rand()\fP: unchanged, but the second argument is different, make sure you take that into account\&.
.IP "\(bu" 2
\fBcaca_sqrt()\fP: this function is now deprecated, use your system's \fBsqrt()\fP call instead\&.
.PP
.SS "Sprite handling"
The newly introduced canvases can have several frames\&. Sprites are hence completely deprecated\&.
.PP
.IP "\(bu" 2
\fBcaca_load_sprite()\fP: use caca_import_file()\&.
.IP "\(bu" 2
\fBcaca_get_sprite_frames()\fP: use \fBcaca_get_frame_count()\fP\&.
.IP "\(bu" 2
\fBcaca_get_sprite_width()\fP: use \fBcaca_get_canvas_width()\fP\&.
.IP "\(bu" 2
\fBcaca_get_sprite_height()\fP: use \fBcaca_get_canvas_height()\fP\&.
.IP "\(bu" 2
\fBcaca_get_sprite_dx()\fP: use \fBcaca_get_canvas_handle_x()\fP\&.
.IP "\(bu" 2
\fBcaca_get_sprite_dy()\fP: use \fBcaca_get_canvas_handle_y()\fP\&.
.IP "\(bu" 2
\fBcaca_draw_sprite()\fP: use \fBcaca_set_frame()\fP and \fBcaca_blit()\fP\&.
.IP "\(bu" 2
\fBcaca_free_sprite()\fP: use \fBcaca_free_canvas()\fP\&.
.PP
.SS "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\&.
.PP
.IP "\(bu" 2
\fBcaca_create_bitmap()\fP: use \fBcaca_create_dither()\fP\&.
.IP "\(bu" 2
\fBcaca_set_bitmap_palette()\fP: use \fBcaca_set_dither_palette()\fP\&.
.IP "\(bu" 2
\fBcaca_draw_bitmap()\fP: use \fBcaca_dither_bitmap()\fP\&.
.IP "\(bu" 2
\fBcaca_free_bitmap()\fP: use \fBcaca_free_dither()\fP\&.
.PP
.SH "Compilation"
.PP
The \fCcaca-config\fP utility is deprecated in favour of the standard \fCpkg-config\fP interface:
.PP
.PP
.nf
gcc -c foobar\&.c -o foobar\&.o `pkg-config --cflags caca`
gcc foobar\&.o -o foobar `pkg-config --libs caca`
.fi
.PP
.PP
\fCcaca-config\fP is still provided as a convenience tool but may be removed in the future\&.