1 | /* $Id: migrating.dox 2062 2007-11-25 17:13:10Z 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 changes in the 1.0 API of \e libcaca are the |
---|
11 | \e libcaca / \e libcucul split and the object-oriented design. See these |
---|
12 | two examples for a rough idea of 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 <cucul.h> |
---|
43 | #include <caca.h> |
---|
44 | |
---|
45 | /* libcaca program - 1.0 API */ |
---|
46 | int main(void) |
---|
47 | { |
---|
48 | /* Initialise libcaca */ |
---|
49 | cucul_canvas_t *cv; |
---|
50 | caca_display_t *dp; |
---|
51 | dp = caca_create_display(cv); |
---|
52 | cv = caca_get_canvas(dp); |
---|
53 | /* Set window title */ |
---|
54 | caca_set_display_title(dp, "Window"); |
---|
55 | /* Choose drawing colours */ |
---|
56 | cucul_set_color_ansi(cv, CUCUL_BLACK, |
---|
57 | CUCUL_WHITE); |
---|
58 | /* Draw a string at (0, 0) */ |
---|
59 | cucul_put_str(cv, 0, 0, "Hello world!"); |
---|
60 | /* Refresh display */ |
---|
61 | caca_refresh_display(); |
---|
62 | /* Wait for a key press event */ |
---|
63 | caca_get_event(dp, CACA_EVENT_KEY_PRESS, |
---|
64 | NULL, -1); |
---|
65 | /* Clean up library */ |
---|
66 | caca_free_display(dp); |
---|
67 | |
---|
68 | return 0; |
---|
69 | } |
---|
70 | \endcode |
---|
71 | </td></tr></table> |
---|
72 | |
---|
73 | Note the following important things: |
---|
74 | |
---|
75 | - Functions now take an object handle as their first argument. |
---|
76 | - All input/output functions start with \b caca_ and all |
---|
77 | drawing and text handling functions start with \b cucul_ . |
---|
78 | |
---|
79 | \section foo2 Migration strategy |
---|
80 | |
---|
81 | You have two ways to migrate your application to use \e libcaca 1.x: |
---|
82 | |
---|
83 | - Port your code using the function equivalence list. This is the preferred |
---|
84 | way because new functions are thread safe and offer much more features |
---|
85 | to both the programmer and the end user. |
---|
86 | - Use the legacy compatibility layer. |
---|
87 | |
---|
88 | Using the compatibility layer is as easy as adding the following three lines: |
---|
89 | |
---|
90 | <table border="0"><tr><td valign="top"> |
---|
91 | \code |
---|
92 | #include <caca.h> |
---|
93 | |
---|
94 | /* libcaca program - 0.x API */ |
---|
95 | ... |
---|
96 | \endcode |
---|
97 | </td><td> |
---|
98 | \code |
---|
99 | #include <caca.h> |
---|
100 | #ifdef CACA_API_VERSION_1 |
---|
101 | # include <caca0.h> |
---|
102 | #endif |
---|
103 | |
---|
104 | /* libcaca program - 0.x API */ |
---|
105 | ... |
---|
106 | \endcode |
---|
107 | </td></tr></table> |
---|
108 | |
---|
109 | \section foo3 Function equivalence list |
---|
110 | |
---|
111 | \subsection bar1 Basic functions |
---|
112 | |
---|
113 | - \b caca_init(): use cucul_create_canvas() to create a \e libcucul canvas, |
---|
114 | followed by caca_create_display() to attach a \e libcaca display to it. |
---|
115 | - \b caca_set_delay(): use caca_set_display_time(). |
---|
116 | - \b caca_get_feature(): deprecated. |
---|
117 | - \b caca_set_feature(): deprecated, see cucul_set_dither_antialias(), |
---|
118 | cucul_set_dither_color() and cucul_set_dither_mode() instead. |
---|
119 | - \b caca_get_feature_name(): deprecated, see cucul_get_dither_mode_list(), |
---|
120 | cucul_get_dither_antialias_list() and cucul_get_dither_color_list() |
---|
121 | instead. |
---|
122 | - \b caca_get_rendertime(): use caca_get_display_time(). |
---|
123 | - \b caca_get_width(): use cucul_get_canvas_width(). |
---|
124 | - \b caca_get_height(): use cucul_get_canvas_height(). |
---|
125 | - \b caca_set_window_title(): use caca_set_display_title(). |
---|
126 | - \b caca_get_window_width(): use caca_get_display_width(). |
---|
127 | - \b caca_get_window_height(): use caca_get_display_height(). |
---|
128 | - \b caca_refresh(): use caca_refresh_display(). |
---|
129 | - \b caca_end(): use caca_free_display() to detach the \e libcaca display, |
---|
130 | followed by cucul_free_canvas() to free the underlying \e libcucul canvas. |
---|
131 | |
---|
132 | \subsection bar2 Event handling |
---|
133 | |
---|
134 | - \b caca_get_event(): unchanged, but the event information retrieval |
---|
135 | changed a lot. |
---|
136 | - \b caca_wait_event(): use caca_get_event() with a \c timeout argument |
---|
137 | of \b -1. |
---|
138 | - \b caca_get_mouse_x(): unchanged. |
---|
139 | - \b caca_get_mouse_y(): unchanged. |
---|
140 | |
---|
141 | \subsection bar3 Character printing |
---|
142 | |
---|
143 | - \b caca_set_color(): use cucul_set_color_ansi() or cucul_set_color_argb(). |
---|
144 | - \b caca_get_fg_color(): use cucul_get_attr(). |
---|
145 | - \b caca_get_bg_color(): use cucul_get_attr(). |
---|
146 | - \b caca_get_color_name(): this function is now deprecated due to major |
---|
147 | uselessness. |
---|
148 | - \b caca_putchar(): use cucul_put_char(). |
---|
149 | - \b caca_putstr(): use cucul_put_str(). |
---|
150 | - \b caca_printf(): use cucul_printf(). |
---|
151 | - \b caca_clear(): use cucul_clear_canvas(). |
---|
152 | |
---|
153 | \subsection bar4 Primitives drawing |
---|
154 | |
---|
155 | These functions are almost unchanged, except for Unicode support and the |
---|
156 | fact that they now act on a given canvas. |
---|
157 | |
---|
158 | - \b caca_draw_line(): use cucul_draw_line(). |
---|
159 | - \b caca_draw_polyline(): use cucul_draw_polyline(). |
---|
160 | - \b caca_draw_thin_line(): use cucul_draw_thin_line(). |
---|
161 | - \b caca_draw_thin_polyline(): use cucul_draw_thin_polyline(). |
---|
162 | |
---|
163 | - \b caca_draw_circle(): use cucul_draw_circle(). |
---|
164 | - \b caca_draw_ellipse(): use cucul_draw_ellipse(). |
---|
165 | - \b caca_draw_thin_ellipse(): use cucul_draw_thin_ellipse(). |
---|
166 | - \b caca_fill_ellipse(): use cucul_fill_ellipse(). |
---|
167 | |
---|
168 | - \b caca_draw_box(): use cucul_draw_box(). |
---|
169 | - \b caca_draw_thin_box(): use cucul_draw_thin_box() or cucul_draw_cp437_box(). |
---|
170 | - \b caca_fill_box(): use cucul_fill_box(). |
---|
171 | |
---|
172 | - \b caca_draw_triangle(): use cucul_draw_triangle(). |
---|
173 | - \b caca_draw_thin_triangle(): use cucul_draw_thin_triangle(). |
---|
174 | - \b caca_fill_triangle(): use cucul_fill_triangle(). |
---|
175 | |
---|
176 | \subsection bar5 Mathematical functions |
---|
177 | |
---|
178 | - \b caca_rand(): use cucul_rand(). The second argument is different, make |
---|
179 | sure you take that into account. |
---|
180 | - \b caca_sqrt(): this function is now deprecated, use your system's |
---|
181 | \b sqrt() call instead. |
---|
182 | |
---|
183 | \subsection bar6 Sprite handling |
---|
184 | |
---|
185 | The newly introduced canvases can have several frames. Sprites are hence |
---|
186 | completely deprecated. |
---|
187 | |
---|
188 | - \b caca_load_sprite(): use cucul_import_file(). |
---|
189 | - \b caca_get_sprite_frames(): use cucul_get_frame_count(). |
---|
190 | - \b caca_get_sprite_width(): use cucul_get_canvas_width(). |
---|
191 | - \b caca_get_sprite_height(): use cucul_get_canvas_height(). |
---|
192 | - \b caca_get_sprite_dx(): use cucul_get_canvas_handle_x(). |
---|
193 | - \b caca_get_sprite_dy(): use cucul_get_canvas_handle_y(). |
---|
194 | - \b caca_draw_sprite(): use cucul_set_frame() and cucul_blit(). |
---|
195 | - \b caca_free_sprite(): use cucul_free_canvas(). |
---|
196 | |
---|
197 | \subsection bar7 Bitmap handling |
---|
198 | |
---|
199 | Bitmaps have been renamed to dithers, because these objects do not in fact |
---|
200 | store any pixels, they just have information on how bitmaps will be dithered. |
---|
201 | |
---|
202 | - \b caca_create_bitmap(): use cucul_create_dither(). |
---|
203 | - \b caca_set_bitmap_palette(): use cucul_set_dither_palette(). |
---|
204 | - \b caca_draw_bitmap(): use cucul_dither_bitmap(). |
---|
205 | - \b caca_free_bitmap(): use cucul_free_dither(). |
---|
206 | |
---|
207 | \section foo4 Compilation |
---|
208 | |
---|
209 | The \c caca-config utility is deprecated in favour of the standard |
---|
210 | \c pkg-config interface: |
---|
211 | |
---|
212 | \code |
---|
213 | gcc -c foobar.c -o foobar.o `pkg-config --cflags caca` |
---|
214 | gcc foobar.o -o foobar `pkg-config --libs caca` |
---|
215 | \endcode |
---|
216 | |
---|
217 | \c caca-config is still provided as a convenience tool but may be removed |
---|
218 | in the future. |
---|
219 | |
---|
220 | */ |
---|