libcaca/doc/migrating.dox

/* $Id$ */

/** \page migrating Migrating from libcaca 0.x to the 1.0 API

 This section will guide you through the migration of a \e libcaca 0.x
 application to the latest API version.

 \section foo1 Overview

 The most important changes in the 1.0 API of \e libcaca are the
 \e libcaca / \e libcucul split and the object-oriented design. See these
 two examples for a rough idea of what changed:

<table border="0"><tr><td valign="top">
\code
#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;
}
\endcode
</td><td>
\code
#include <cucul.h>
#include <caca.h>

/* libcaca program - 1.0 API */
int main(void)
{
    /* Initialise libcaca */
    cucul_canvas_t *cv;
    caca_display_t *dp;
    cv = cucul_create_canvas(0, 0);
    dp = caca_create_display(cv);
    /* Set window title */
    caca_set_display_title(dp, "Window");
    /* Choose drawing colours */
    cucul_set_color(cv, CUCUL_COLOR_BLACK,
                        CUCUL_COLOR_WHITE);
    /* Draw a string at (0, 0) */
    cucul_putstr(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);
    cucul_free_canvas(cv);

    return 0;
}
\endcode
</td></tr></table>

 Note the following important things:

 - Functions now take an object handle as their first argument.
 - All input/output functions start with \b caca_ and all
   drawing and text handling functions start with \b cucul_ .

 \section foo2 Function equivalence list

 \subsection bar1 Basic functions

 - \b caca_init(): use cucul_create_canvas() to create a \e libcucul canvas,
   followed by caca_create_display() to attach a \e libcaca display to it.
 - \b caca_set_delay(): unchanged.
 - \b caca_get_feature(): deprecated.
 - \b caca_set_feature(): deprecated, see cucul_set_dither_antialias(),
   cucul_set_dither_color() and cucul_set_dither_mode() instead.
 - \b caca_get_feature_name(): deprecated, see cucul_get_dither_mode_list(),
   cucul_get_dither_antialias_list() and cucul_get_dither_color_list()
   instead.
 - \b caca_get_rendertime(): unchanged.
 - \b caca_get_width(): use cucul_get_canvas_width().
 - \b caca_get_height(): use cucul_get_canvas_height().
 - \b caca_set_window_title(): use caca_set_display_title().
 - \b caca_get_window_width(): use caca_get_display_width().
 - \b caca_get_window_height(): use caca_get_display_height().
 - \b caca_refresh(): use caca_refresh_display().
 - \b caca_end(): use caca_free_display() to detach the \e libcaca display,
   followed by cucul_free_canvas() to free the underlying \e libcucul canvas.

 \subsection bar2 Event handling

 - \b caca_get_event(): unchanged, but the event information retrieval
   changed a lot.
 - \b caca_wait_event(): use caca_get_event() with a \c timeout argument
   of \b -1.
 - \b caca_get_mouse_x(): unchanged.
 - \b caca_get_mouse_y(): unchanged.

 \subsection bar3 Character printing

 - \b caca_set_color(): use cucul_set_color() or cucul_set_truecolor().
 - \b caca_get_fg_color(): deprecated.
 - \b caca_get_bg_color(): deprecated.
 - \b caca_get_color_name(): use cucul_get_color_name().
 - \b caca_putchar(): use cucul_putchar().
 - \b caca_putstr(): use cucul_putstr().
 - \b caca_printf(): use cucul_printf().
 - \b caca_clear(): use cucul_clear_canvas().

 \subsection bar4 Primitives drawing

 These functions are almost unchanged, except for Unicode support and the
 fact that they now act on a given canvas.

 - \b caca_draw_line(): use cucul_draw_line().
 - \b caca_draw_polyline(): use cucul_draw_polyline().
 - \b caca_draw_thin_line(): use cucul_draw_thin_line().
 - \b caca_draw_thin_polyline(): use cucul_draw_thin_polyline().

 - \b caca_draw_circle(): use cucul_draw_circle().
 - \b caca_draw_ellipse(): use cucul_draw_ellipse().
 - \b caca_draw_thin_ellipse(): use cucul_draw_thin_ellipse().
 - \b caca_fill_ellipse(): use cucul_fill_ellipse().

 - \b caca_draw_box(): use cucul_draw_box().
 - \b caca_draw_thin_box(): use cucul_draw_thin_box().
 - \b caca_fill_box(): use cucul_fill_box().

 - \b caca_draw_triangle(): use cucul_draw_triangle().
 - \b caca_draw_thin_triangle(): use cucul_draw_thin_triangle().
 - \b caca_fill_triangle(): use cucul_fill_triangle().

 \subsection bar5 Mathematical functions

 - \b caca_rand(): use cucul_rand(). The second argument is different, make
   sure you take that into account.
 - \b caca_sqrt(): this function is now deprecated, use your system's
   \b sqrt() call instead.

 \subsection bar6 Sprite handling

 The newly introduced canvases can have several frames. Sprites are hence
 completely deprecated.

 - \b caca_load_sprite(): use cucul_import_canvas().
 - \b caca_get_sprite_frames(): use cucul_get_canvas_frame_count().
 - \b caca_get_sprite_width(): use cucul_get_canvas_width().
 - \b caca_get_sprite_height(): use cucul_get_canvas_height().
 - \b caca_get_sprite_dx(): this function is now deprecated.
 - \b caca_get_sprite_dy(): this function is now deprecated.
 - \b caca_draw_sprite(): use cucul_set_canvas_frame() and cucul_blit().
 - \b caca_free_sprite(): use cucul_free_canvas().

 \subsection bar7 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.

 - \b caca_create_bitmap(): use cucul_create_dither().
 - \b caca_set_bitmap_palette(): use cucul_set_dither_palette().
 - \b caca_draw_bitmap(): use cucul_dither_bitmap().
 - \b caca_free_bitmap(): use cucul_free_dither().

 \section foo3 Compilation

 The \c caca-config utility is deprecated in favour of the standard
 \c pkg-config interface:

\code
gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
gcc foobar.o -o foobar `pkg-config --libs caca`
\endcode

 \c caca-config is still provided as a convenience tool but will be removed
 in the future.

*/