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

NAME

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

Overview

12       The most important change in the 1.0 API of libcaca is the object-
13       oriented design. See these two examples for a rough idea of what
14       changed:
15
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
40       #include <caca.h>
41
42       /* libcaca program - 1.0 API */
43       int main(void)
44       {
45           /* Initialise libcaca */
46           caca_canvas_t *cv;
47           caca_display_t *dp;
48           dp = caca_create_display(NULL);
49           cv = caca_get_canvas(dp);
50           /* Set window title */
51           caca_set_display_title(dp, "Window");
52           /* Choose drawing colours */
53           caca_set_color_ansi(cv, CACA_BLACK,
54                                   CACA_WHITE);
55           /* Draw a string at (0, 0) */
56           caca_put_str(cv, 0, 0, "Hello world!");
57           /* Refresh display */
58           caca_refresh_display();
59           /* Wait for a key press event */
60           caca_get_event(dp, CACA_EVENT_KEY_PRESS,
61                          NULL, -1);
62           /* Clean up library */
63           caca_free_display(dp);
64
65           return 0;
66       }
67
68
69       Note the following important things:
70
71       • Most functions now take an object handle as their first argument.
72

Migration strategy

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

Function equivalence list

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

Compilation

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