1libcaca-migrating(3caca)            libcaca           libcaca-migrating(3caca)
2
3
4

NAME

6       libcaca-migrating - Migrating from libcaca 0.x to the 1.0 API This
7       section will guide you through the migration of a libcaca 0.x
8       application to the latest API version.
9

Overview

11       The most important change in the 1.0 API of libcaca is the object-
12       oriented design. See these two examples for a rough idea of what
13       changed:
14
15       #include <caca.h>
16
17       /* libcaca program - 0.x API */
18       int main(void)
19       {
20           /* Initialise libcaca */
21           caca_init();
22           /* Set window title */
23           caca_set_window_title('Window');
24           /* Choose drawing colours */
25           caca_set_color(CACA_COLOR_BLACK,
26                          CACA_COLOR_WHITE);
27           /* Draw a string at (0, 0) */
28           caca_putstr(0, 0, 'Hello world!');
29           /* Refresh display */
30           caca_refresh();
31           /* Wait for a key press event */
32           caca_wait_event(CACA_EVENT_KEY_PRESS);
33           /* Clean up library */
34           caca_end();
35
36           return 0;
37       }
38
39       #include <caca.h>
40
41       /* libcaca program - 1.0 API */
42       int main(void)
43       {
44           /* Initialise libcaca */
45           caca_canvas_t *cv;
46           caca_display_t *dp;
47           dp = caca_create_display(NULL);
48           cv = caca_get_canvas(dp);
49           /* Set window title */
50           caca_set_display_title(dp, 'Window');
51           /* Choose drawing colours */
52           caca_set_color_ansi(cv, CACA_BLACK,
53                                   CACA_WHITE);
54           /* Draw a string at (0, 0) */
55           caca_put_str(cv, 0, 0, 'Hello world!');
56           /* Refresh display */
57           caca_refresh_display();
58           /* Wait for a key press event */
59           caca_get_event(dp, CACA_EVENT_KEY_PRESS,
60                          NULL, -1);
61           /* Clean up library */
62           caca_free_display(dp);
63
64           return 0;
65       }
66
67
68       Note the following important things:
69
70       · Most functions now take an object handle as their first argument.
71

Migration strategy

73       You have two ways to migrate your application to use libcaca 1.x:
74
75       · Port your code using the function equivalence list. This is the
76         preferred way because new functions are thread safe and offer much
77         more features to both the programmer and the end user.
78
79       · Use the legacy compatibility layer.
80
81       Using the compatibility layer is as easy as adding the following three
82       lines:
83
84       #include <caca.h>
85
86       /* libcaca program - 0.x API */
87
88       #include <caca.h>
89       #ifdef CACA_API_VERSION_1
90       #   include <caca0.h>
91       #endif
92
93       /* libcaca program - 0.x API */
94
95
96       The modified code is guaranteed to build both with libcaca 0.x and
97       libcaca 1.0.
98

Function equivalence list

100   Basic functions
101       · caca_init(): use caca_create_canvas() to create a libcaca canvas,
102         followed by caca_create_display() to attach a libcaca display to it.
103         Alternatively, caca_create_display() with a NULL argument will create
104         a canvas automatically.
105
106       · caca_set_delay(): use caca_set_display_time().
107
108       · caca_get_feature(): deprecated.
109
110       · caca_set_feature(): deprecated, see caca_set_dither_antialias(),
111         caca_set_dither_color() and caca_set_dither_mode() instead.
112
113       · caca_get_feature_name(): deprecated, see caca_get_dither_mode_list(),
114         caca_get_dither_antialias_list() and caca_get_dither_color_list()
115         instead.
116
117       · caca_get_rendertime(): use caca_get_display_time().
118
119       · caca_get_width(): use caca_get_canvas_width().
120
121       · caca_get_height(): use caca_get_canvas_height().
122
123       · caca_set_window_title(): use caca_set_display_title().
124
125       · caca_get_window_width(): use caca_get_display_width().
126
127       · caca_get_window_height(): use caca_get_display_height().
128
129       · caca_refresh(): use caca_refresh_display().
130
131       · caca_end(): use caca_free_display() to detach the libcaca display,
132         followed by caca_free_canvas() to free the underlying 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   Event handling
137       · caca_get_event(): unchanged, but the event information retrieval
138         changed a lot.
139
140       · caca_wait_event(): use caca_get_event() with a timeout argument of
141         -1.
142
143       · caca_get_mouse_x(): unchanged.
144
145       · caca_get_mouse_y(): unchanged.
146
147   Character printing
148       · caca_set_color(): use caca_set_color_ansi() or caca_set_color_argb().
149
150       · caca_get_fg_color(): use caca_get_attr().
151
152       · caca_get_bg_color(): use caca_get_attr().
153
154       · caca_get_color_name(): this function is now deprecated due to major
155         uselessness.
156
157       · caca_putchar(): use caca_put_char().
158
159       · caca_putstr(): use caca_put_str().
160
161       · caca_printf(): unchanged.
162
163       · caca_clear(): use caca_clear_canvas().
164
165   Primitives drawing
166       These functions are almost unchanged, except for Unicode support and
167       the fact that they now act on a given canvas.
168
169       · caca_draw_line(): unchanged.
170
171       · caca_draw_polyline(): unchanged.
172
173       · caca_draw_thin_line(): unchanged.
174
175       · caca_draw_thin_polyline(): unchanged.
176
177       · caca_draw_circle(): unchanged.
178
179       · caca_draw_ellipse(): unchanged.
180
181       · caca_draw_thin_ellipse(): unchanged.
182
183       · caca_fill_ellipse(): unchanged.
184
185       · caca_draw_box(): unchanged, but the argument meaning changed (width
186         and height instead of corner coordinates).
187
188       · caca_draw_thin_box(): use caca_draw_thin_box() or
189         caca_draw_cp437_box(), also the argument meaning changed (width and
190         height instead of corner coordinates).
191
192       · caca_fill_box(): unchanged, but the argument meaning changed (width
193         and height instead of corner coordinates).
194
195       · caca_draw_triangle(): unchanged.
196
197       · caca_draw_thin_triangle(): unchanged.
198
199       · caca_fill_triangle(): unchanged.
200
201   Mathematical functions
202       · caca_rand(): unchanged, but the second argument is different, make
203         sure you take that into account.
204
205       · caca_sqrt(): this function is now deprecated, use your system's
206         sqrt() call instead.
207
208   Sprite handling
209       The newly introduced canvases can have several frames. Sprites are
210       hence completely deprecated.
211
212       · caca_load_sprite(): use caca_import_file().
213
214       · caca_get_sprite_frames(): use caca_get_frame_count().
215
216       · caca_get_sprite_width(): use caca_get_canvas_width().
217
218       · caca_get_sprite_height(): use caca_get_canvas_height().
219
220       · caca_get_sprite_dx(): use caca_get_canvas_handle_x().
221
222       · caca_get_sprite_dy(): use caca_get_canvas_handle_y().
223
224       · caca_draw_sprite(): use caca_set_frame() and caca_blit().
225
226       · caca_free_sprite(): use caca_free_canvas().
227
228   Bitmap handling
229       Bitmaps have been renamed to dithers, because these objects do not in
230       fact store any pixels, they just have information on how bitmaps will
231       be dithered.
232
233       · caca_create_bitmap(): use caca_create_dither().
234
235       · caca_set_bitmap_palette(): use caca_set_dither_palette().
236
237       · caca_draw_bitmap(): use caca_dither_bitmap().
238
239       · caca_free_bitmap(): use caca_free_dither().
240

Compilation

242       The caca-config utility is deprecated in favour of the standard pkg-
243       config interface:
244
245       gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
246       gcc foobar.o -o foobar `pkg-config --libs caca`
247
248       caca-config is still provided as a convenience tool but may be removed
249       in the future.
250
251
252
253Version 0.99.beta17               29 Apr 2010         libcaca-migrating(3caca)