source: libcaca/trunk/doc/migrating.dox @ 2062

Last change on this file since 2062 was 2062, checked in by Sam Hocevar, 12 years ago
  • Switch to caca_create_display(NULL) in a few places to document the behaviour.
  • Property svn:keywords set to Id
File size: 7.0 KB
Line 
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 */
19int 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 */
46int 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
213gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
214gcc 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*/
Note: See TracBrowser for help on using the repository browser.