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
89       #include <caca.h>
90       #ifdef CACA_API_VERSION_1
91       #   include <caca0.h>
92       #endif
93
94       /* libcaca program - 0.x API */
95       ...
96
97
98       The modified code is guaranteed to build both with libcaca 0.x and
99       libcaca 1.0.
100

Function equivalence list

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

Compilation

244       The caca-config utility is deprecated in favour of the standard pkg-
245       config interface:
246
247       gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
248       gcc foobar.o -o foobar `pkg-config --libs caca`
249
250       caca-config is still provided as a convenience tool but may be removed
251       in the future.
252
253
254
255Version 0.99.beta19             Thu Jul 22 2021       libcaca-migrating(3caca)