source: libcaca/trunk/doc/migrating.dox @ 3605

Last change on this file since 3605 was 3605, checked in by Sam Hocevar, 11 years ago

Add a note about autoreleased canvases in the documentation.

  • Property svn:keywords set to Id
File size: 7.3 KB
Line 
1/* $Id: migrating.dox 3605 2009-08-02 11:09:29Z sam $ */
2
3/** \page libcaca-migrating Migrating from libcaca 0.x to the 1.0 API
4
5 This section will guide you through the migration of a \e libcaca 0.x
6 application to the latest API version.
7
8 \section foo1 Overview
9
10 The most important change in the 1.0 API of \e libcaca is the
11 object-oriented design. See these two examples for a rough idea of
12 what changed:
13
14<table border="0"><tr><td valign="top">
15\code
16#include <caca.h>
17
18/* libcaca program - 0.x API */
19int main(void)
20{
21    /* Initialise libcaca */
22    caca_init();
23    /* Set window title */
24    caca_set_window_title("Window");
25    /* Choose drawing colours */
26    caca_set_color(CACA_COLOR_BLACK,
27                   CACA_COLOR_WHITE);
28    /* Draw a string at (0, 0) */
29    caca_putstr(0, 0, "Hello world!");
30    /* Refresh display */
31    caca_refresh();
32    /* Wait for a key press event */
33    caca_wait_event(CACA_EVENT_KEY_PRESS);
34    /* Clean up library */
35    caca_end();
36
37    return 0;
38}
39\endcode
40</td><td>
41\code
42#include <caca.h>
43
44/* libcaca program - 1.0 API */
45int main(void)
46{
47    /* Initialise libcaca */
48    caca_canvas_t *cv;
49    caca_display_t *dp;
50    dp = caca_create_display(NULL);
51    cv = caca_get_canvas(dp);
52    /* Set window title */
53    caca_set_display_title(dp, "Window");
54    /* Choose drawing colours */
55    caca_set_color_ansi(cv, CACA_BLACK,
56                            CACA_WHITE);
57    /* Draw a string at (0, 0) */
58    caca_put_str(cv, 0, 0, "Hello world!");
59    /* Refresh display */
60    caca_refresh_display();
61    /* Wait for a key press event */
62    caca_get_event(dp, CACA_EVENT_KEY_PRESS,
63                   NULL, -1);
64    /* Clean up library */
65    caca_free_display(dp);
66
67    return 0;
68}
69\endcode
70</td></tr></table>
71
72 Note the following important things:
73
74 - Most functions now take an object handle as their first argument.
75
76 \section foo2 Migration strategy
77
78 You have two ways to migrate your application to use \e libcaca 1.x:
79
80 - Port your code using the function equivalence list. This is the preferred
81   way because new functions are thread safe and offer much more features
82   to both the programmer and the end user.
83 - Use the legacy compatibility layer.
84
85 Using the compatibility layer is as easy as adding the following three lines:
86
87<table border="0"><tr><td valign="top">
88\code
89#include <caca.h>
90
91/* libcaca program - 0.x API */
92...
93\endcode
94</td><td>
95\code
96#include <caca.h>
97#ifdef CACA_API_VERSION_1
98#   include <caca0.h>
99#endif
100
101/* libcaca program - 0.x API */
102...
103\endcode
104</td></tr></table>
105
106 The modified code is guaranteed to build both with \e libcaca 0.x and
107 \e libcaca 1.0.
108
109 \section foo3 Function equivalence list
110
111 \subsection bar1 Basic functions
112
113 - \b caca_init(): use caca_create_canvas() to create a \e libcaca canvas,
114   followed by caca_create_display() to attach a \e libcaca display to it.
115   Alternatively, caca_create_display() with a NULL argument will create a
116   canvas automatically.
117 - \b caca_set_delay(): use caca_set_display_time().
118 - \b caca_get_feature(): deprecated.
119 - \b caca_set_feature(): deprecated, see caca_set_dither_antialias(),
120   caca_set_dither_color() and caca_set_dither_mode() instead.
121 - \b caca_get_feature_name(): deprecated, see caca_get_dither_mode_list(),
122   caca_get_dither_antialias_list() and caca_get_dither_color_list()
123   instead.
124 - \b caca_get_rendertime(): use caca_get_display_time().
125 - \b caca_get_width(): use caca_get_canvas_width().
126 - \b caca_get_height(): use caca_get_canvas_height().
127 - \b caca_set_window_title(): use caca_set_display_title().
128 - \b caca_get_window_width(): use caca_get_display_width().
129 - \b caca_get_window_height(): use caca_get_display_height().
130 - \b caca_refresh(): use caca_refresh_display().
131 - \b caca_end(): use caca_free_display() to detach the \e libcaca display,
132   followed by caca_free_canvas() to free the underlying \e libcaca canvas.
133   Alternatively, if the canvas was created by caca_create_display(), it
134   will be automatically destroyed by caca_free_display().
135
136 \subsection bar2 Event handling
137
138 - \b caca_get_event(): unchanged, but the event information retrieval
139   changed a lot.
140 - \b caca_wait_event(): use caca_get_event() with a \c timeout argument
141   of \b -1.
142 - \b caca_get_mouse_x(): unchanged.
143 - \b caca_get_mouse_y(): unchanged.
144
145 \subsection bar3 Character printing
146
147 - \b caca_set_color(): use caca_set_color_ansi() or caca_set_color_argb().
148 - \b caca_get_fg_color(): use caca_get_attr().
149 - \b caca_get_bg_color(): use caca_get_attr().
150 - \b caca_get_color_name(): this function is now deprecated due to major
151   uselessness.
152 - \b caca_putchar(): use caca_put_char().
153 - \b caca_putstr(): use caca_put_str().
154 - \b caca_printf(): unchanged.
155 - \b caca_clear(): use caca_clear_canvas().
156
157 \subsection bar4 Primitives drawing
158
159 These functions are almost unchanged, except for Unicode support and the
160 fact that they now act on a given canvas.
161
162 - \b caca_draw_line(): unchanged.
163 - \b caca_draw_polyline(): unchanged.
164 - \b caca_draw_thin_line(): unchanged.
165 - \b caca_draw_thin_polyline(): unchanged.
166
167 - \b caca_draw_circle(): unchanged.
168 - \b caca_draw_ellipse(): unchanged.
169 - \b caca_draw_thin_ellipse(): unchanged.
170 - \b caca_fill_ellipse(): unchanged.
171
172 - \b caca_draw_box(): unchanged, but the argument meaning changed (width
173                       and height instead of corner coordinates).
174 - \b caca_draw_thin_box(): use caca_draw_thin_box() or caca_draw_cp437_box(),
175                            also the argument meaning changed (width
176                            and height instead of corner coordinates).
177 - \b caca_fill_box(): unchanged, but the argument meaning changed (width
178                       and height instead of corner coordinates).
179
180 - \b caca_draw_triangle(): unchanged.
181 - \b caca_draw_thin_triangle(): unchanged.
182 - \b caca_fill_triangle(): unchanged.
183
184 \subsection bar5 Mathematical functions
185
186 - \b caca_rand(): unchanged, but the second argument is different, make
187   sure you take that into account.
188 - \b caca_sqrt(): this function is now deprecated, use your system's
189   \b sqrt() call instead.
190
191 \subsection bar6 Sprite handling
192
193 The newly introduced canvases can have several frames. Sprites are hence
194 completely deprecated.
195
196 - \b caca_load_sprite(): use caca_import_file().
197 - \b caca_get_sprite_frames(): use caca_get_frame_count().
198 - \b caca_get_sprite_width(): use caca_get_canvas_width().
199 - \b caca_get_sprite_height(): use caca_get_canvas_height().
200 - \b caca_get_sprite_dx(): use caca_get_canvas_handle_x().
201 - \b caca_get_sprite_dy(): use caca_get_canvas_handle_y().
202 - \b caca_draw_sprite(): use caca_set_frame() and caca_blit().
203 - \b caca_free_sprite(): use caca_free_canvas().
204
205 \subsection bar7 Bitmap handling
206
207 Bitmaps have been renamed to dithers, because these objects do not in fact
208 store any pixels, they just have information on how bitmaps will be dithered.
209
210 - \b caca_create_bitmap(): use caca_create_dither().
211 - \b caca_set_bitmap_palette(): use caca_set_dither_palette().
212 - \b caca_draw_bitmap(): use caca_dither_bitmap().
213 - \b caca_free_bitmap(): use caca_free_dither().
214
215 \section foo4 Compilation
216
217 The \c caca-config utility is deprecated in favour of the standard
218 \c pkg-config interface:
219
220\code
221gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
222gcc foobar.o -o foobar `pkg-config --libs caca`
223\endcode
224
225 \c caca-config is still provided as a convenience tool but may be removed
226 in the future.
227
228*/
Note: See TracBrowser for help on using the repository browser.