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

Last change on this file since 3216 was 2824, checked in by Sam Hocevar, 12 years ago

Continuing the libcucul-libcaca merge.

  • Property svn:keywords set to Id
File size: 6.9 KB
Line 
1/* $Id: migrating.dox 2824 2008-09-27 14:29:11Z 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(cv);
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 - Functions now take an object handle as their first argument.
75 - All input/output functions start with \b caca_ and all
76   drawing and text handling functions start with \b caca_ .
77
78 \section foo2 Migration strategy
79
80 You have two ways to migrate your application to use \e libcaca 1.x:
81
82 - Port your code using the function equivalence list. This is the preferred
83   way because new functions are thread safe and offer much more features
84   to both the programmer and the end user.
85 - Use the legacy compatibility layer.
86
87 Using the compatibility layer is as easy as adding the following three lines:
88
89<table border="0"><tr><td valign="top">
90\code
91#include <caca.h>
92
93/* libcaca program - 0.x API */
94...
95\endcode
96</td><td>
97\code
98#include <caca.h>
99#ifdef CACA_API_VERSION_1
100#   include <caca0.h>
101#endif
102
103/* libcaca program - 0.x API */
104...
105\endcode
106</td></tr></table>
107
108 \section foo3 Function equivalence list
109
110 \subsection bar1 Basic functions
111
112 - \b caca_init(): use caca_create_canvas() to create a \e libcaca canvas,
113   followed by caca_create_display() to attach a \e libcaca display to it.
114 - \b caca_set_delay(): use caca_set_display_time().
115 - \b caca_get_feature(): deprecated.
116 - \b caca_set_feature(): deprecated, see caca_set_dither_antialias(),
117   caca_set_dither_color() and caca_set_dither_mode() instead.
118 - \b caca_get_feature_name(): deprecated, see caca_get_dither_mode_list(),
119   caca_get_dither_antialias_list() and caca_get_dither_color_list()
120   instead.
121 - \b caca_get_rendertime(): use caca_get_display_time().
122 - \b caca_get_width(): use caca_get_canvas_width().
123 - \b caca_get_height(): use caca_get_canvas_height().
124 - \b caca_set_window_title(): use caca_set_display_title().
125 - \b caca_get_window_width(): use caca_get_display_width().
126 - \b caca_get_window_height(): use caca_get_display_height().
127 - \b caca_refresh(): use caca_refresh_display().
128 - \b caca_end(): use caca_free_display() to detach the \e libcaca display,
129   followed by caca_free_canvas() to free the underlying \e libcaca canvas.
130
131 \subsection bar2 Event handling
132
133 - \b caca_get_event(): unchanged, but the event information retrieval
134   changed a lot.
135 - \b caca_wait_event(): use caca_get_event() with a \c timeout argument
136   of \b -1.
137 - \b caca_get_mouse_x(): unchanged.
138 - \b caca_get_mouse_y(): unchanged.
139
140 \subsection bar3 Character printing
141
142 - \b caca_set_color(): use caca_set_color_ansi() or caca_set_color_argb().
143 - \b caca_get_fg_color(): use caca_get_attr().
144 - \b caca_get_bg_color(): use caca_get_attr().
145 - \b caca_get_color_name(): this function is now deprecated due to major
146   uselessness.
147 - \b caca_putchar(): use caca_put_char().
148 - \b caca_putstr(): use caca_put_str().
149 - \b caca_printf(): use caca_printf().
150 - \b caca_clear(): use caca_clear_canvas().
151
152 \subsection bar4 Primitives drawing
153
154 These functions are almost unchanged, except for Unicode support and the
155 fact that they now act on a given canvas.
156
157 - \b caca_draw_line(): use caca_draw_line().
158 - \b caca_draw_polyline(): use caca_draw_polyline().
159 - \b caca_draw_thin_line(): use caca_draw_thin_line().
160 - \b caca_draw_thin_polyline(): use caca_draw_thin_polyline().
161
162 - \b caca_draw_circle(): use caca_draw_circle().
163 - \b caca_draw_ellipse(): use caca_draw_ellipse().
164 - \b caca_draw_thin_ellipse(): use caca_draw_thin_ellipse().
165 - \b caca_fill_ellipse(): use caca_fill_ellipse().
166
167 - \b caca_draw_box(): use caca_draw_box().
168 - \b caca_draw_thin_box(): use caca_draw_thin_box() or caca_draw_cp437_box().
169 - \b caca_fill_box(): use caca_fill_box().
170
171 - \b caca_draw_triangle(): use caca_draw_triangle().
172 - \b caca_draw_thin_triangle(): use caca_draw_thin_triangle().
173 - \b caca_fill_triangle(): use caca_fill_triangle().
174
175 \subsection bar5 Mathematical functions
176
177 - \b caca_rand(): use caca_rand(). The second argument is different, make
178   sure you take that into account.
179 - \b caca_sqrt(): this function is now deprecated, use your system's
180   \b sqrt() call instead.
181
182 \subsection bar6 Sprite handling
183
184 The newly introduced canvases can have several frames. Sprites are hence
185 completely deprecated.
186
187 - \b caca_load_sprite(): use caca_import_file().
188 - \b caca_get_sprite_frames(): use caca_get_frame_count().
189 - \b caca_get_sprite_width(): use caca_get_canvas_width().
190 - \b caca_get_sprite_height(): use caca_get_canvas_height().
191 - \b caca_get_sprite_dx(): use caca_get_canvas_handle_x().
192 - \b caca_get_sprite_dy(): use caca_get_canvas_handle_y().
193 - \b caca_draw_sprite(): use caca_set_frame() and caca_blit().
194 - \b caca_free_sprite(): use caca_free_canvas().
195
196 \subsection bar7 Bitmap handling
197
198 Bitmaps have been renamed to dithers, because these objects do not in fact
199 store any pixels, they just have information on how bitmaps will be dithered.
200
201 - \b caca_create_bitmap(): use caca_create_dither().
202 - \b caca_set_bitmap_palette(): use caca_set_dither_palette().
203 - \b caca_draw_bitmap(): use caca_dither_bitmap().
204 - \b caca_free_bitmap(): use caca_free_dither().
205
206 \section foo4 Compilation
207
208 The \c caca-config utility is deprecated in favour of the standard
209 \c pkg-config interface:
210
211\code
212gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
213gcc foobar.o -o foobar `pkg-config --libs caca`
214\endcode
215
216 \c caca-config is still provided as a convenience tool but may be removed
217 in the future.
218
219*/
Note: See TracBrowser for help on using the repository browser.