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 */ |
---|
19 | int 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 */ |
---|
45 | int 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 |
---|
221 | gcc -c foobar.c -o foobar.o `pkg-config --cflags caca` |
---|
222 | gcc 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 | */ |
---|