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

Last change on this file since 845 was 845, checked in by Sam Hocevar, 14 years ago
  • Updated the migration guide.
  • Property svn:keywords set to Id
File size: 6.2 KB
Line 
1/* $Id: migrating.dox 845 2006-04-22 19:14:49Z sam $ */
2
3/** \page 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. Where
12 you used to do:
13
14<table border="0"><tr><td valign="top">
15\code
16#include <caca.h>
17
18int 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\endcode
39</td><td>
40\code
41#include <cucul.h>
42#include <caca.h>
43
44int main(void)
45{
46    /* Initialise libcaca */
47    cucul_canvas_t *cv;
48    caca_display_t *dp; caca_event_t ev;
49    cv = cucul_create_canvas(0, 0);
50    dp = caca_create_display(cv);
51    /* Set window title */
52    caca_set_display_title(dp, "Window");
53    /* Choose drawing colours */
54    cucul_set_color(cv, CUCUL_COLOR_BLACK,
55                        CUCUL_COLOR_WHITE);
56    /* Draw a string at (0, 0) */
57    cucul_putstr(cv, 0, 0, "Hello world!");
58    /* Refresh display */
59    caca_refresh_display();
60    /* Wait for a key press event */
61    caca_get_event(dp, CACA_EVENT_KEY_PRESS,
62                   &ev, -1);
63    /* Clean up library */
64    caca_free_display(dp);
65    cucul_free_canvas(cv);
66
67    return 0;
68}
69\endcode
70</td></tr></table>
71
72 Note the following important things:
73
74 - Functions now take an object handle as their first argument.
75 - All input/output functions start with \b caca_ and all
76   drawing and text handling functions start with \b cucul_ .
77
78 \section foo2 Function equivalence list
79
80 \subsection bar1 Basic functions
81
82 - \b caca_init(): use cucul_create_canvas() to create a \e libcucul canvas,
83   followed by caca_create_display() to attach a \e libcaca display to it.
84 - \b caca_set_delay(): unchanged.
85 - \b caca_get_feature(): deprecated.
86 - \b caca_set_feature(): deprecated, see cucul_set_dither_antialias(),
87   cucul_set_dither_color() and cucul_set_dither_mode() instead.
88 - \b caca_get_feature_name(): deprecated, see cucul_get_dither_mode_list(),
89   cucul_get_dither_antialias_list() and cucul_get_dither_color_list()
90   instead.
91 - \b caca_get_rendertime(): unchanged.
92 - \b caca_get_width(): use cucul_get_canvas_width().
93 - \b caca_get_height(): use cucul_get_canvas_height().
94 - \b caca_set_window_title(): use caca_set_display_title().
95 - \b caca_get_window_width(): use caca_get_display_width().
96 - \b caca_get_window_height(): use caca_get_display_height().
97 - \b caca_refresh(): use caca_refresh_display().
98 - \b caca_end(): use caca_free_display() to detach the \e libcaca display,
99   followed by cucul_free_canvas() to free the underlying \e libcucul canvas.
100
101 \subsection bar2 Event handling
102
103 - \b caca_get_event(): unchanged, but the event information retrieval
104   changed a lot.
105 - \b caca_wait_event(): use caca_get_event() with a \c timeout argument
106   of \b -1.
107 - \b caca_get_mouse_x(): unchanged.
108 - \b caca_get_mouse_y(): unchanged.
109
110 \subsection bar3 Character printing
111
112 - \b caca_set_color(): use cucul_set_color() or cucul_set_truecolor().
113 - \b caca_get_fg_color(): deprecated.
114 - \b caca_get_bg_color(): deprecated.
115 - \b caca_get_color_name(): use cucul_get_color_name().
116 - \b caca_putchar(): use cucul_putchar().
117 - \b caca_putstr(): use cucul_putstr().
118 - \b caca_printf(): use cucul_printf().
119 - \b caca_clear(): use cucul_clear_canvas().
120
121 \subsection bar4 Primitives drawing
122
123 These functions are almost unchanged, except for Unicode support and the
124 fact that they now act on a given canvas.
125
126 - \b caca_draw_line(): use cucul_draw_line().
127 - \b caca_draw_polyline(): use cucul_draw_polyline().
128 - \b caca_draw_thin_line(): use cucul_draw_thin_line().
129 - \b caca_draw_thin_polyline(): use cucul_draw_thin_polyline().
130
131 - \b caca_draw_circle(): use cucul_draw_circle().
132 - \b caca_draw_ellipse(): use cucul_draw_ellipse().
133 - \b caca_draw_thin_ellipse(): use cucul_draw_thin_ellipse().
134 - \b caca_fill_ellipse(): use cucul_fill_ellipse().
135
136 - \b caca_draw_box(): use cucul_draw_box().
137 - \b caca_draw_thin_box(): use cucul_draw_thin_box().
138 - \b caca_fill_box(): use cucul_fill_box().
139
140 - \b caca_draw_triangle(): use cucul_draw_triangle().
141 - \b caca_draw_thin_triangle(): use cucul_draw_thin_triangle().
142 - \b caca_fill_triangle(): use cucul_fill_triangle().
143
144 \subsection bar5 Mathematical functions
145
146 - \b caca_rand(): use cucul_rand(). The second argument is different, make
147   sure you take that into account.
148 - \b caca_sqrt(): this function is now deprecated, use your system's
149   \b sqrt() call instead.
150
151 \subsection bar6 Sprite handling
152
153 The newly introduced canvases can have several frames. Sprites are hence
154 completely deprecated.
155
156 - \b caca_load_sprite(): use cucul_import_canvas().
157 - \b caca_get_sprite_frames(): use cucul_get_canvas_frame_count().
158 - \b caca_get_sprite_width(): use cucul_get_canvas_width().
159 - \b caca_get_sprite_height(): use cucul_get_canvas_height().
160 - \b caca_get_sprite_dx(): this function is now deprecated.
161 - \b caca_get_sprite_dy(): this function is now deprecated.
162 - \b caca_draw_sprite(): use cucul_set_canvas_frame() and cucul_blit().
163 - \b caca_free_sprite(): use cucul_free_canvas().
164
165 \subsection bar7 Bitmap handling
166
167 Bitmaps have been renamed to dithers, because these objects do not in fact
168 store any pixels, they just have information on how bitmaps will be dithered.
169
170 - \b caca_create_bitmap(): use cucul_create_dither().
171 - \b caca_set_bitmap_palette(): use cucul_set_dither_palette().
172 - \b caca_draw_bitmap(): use cucul_dither_bitmap().
173 - \b caca_free_bitmap(): use cucul_free_dither().
174
175 \section foo3 Compilation
176
177 The \c caca-config utility is deprecated in favour of the standard
178 \c pkg-config interface:
179
180\code
181gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
182gcc foobar.o -o foobar `pkg-config --libs caca`
183\endcode
184
185 \c caca-config is still provided as a convenience tool but will be removed
186 in the future.
187
188*/
Note: See TracBrowser for help on using the repository browser.