1 | /* $Id: migrating.dox 824 2006-04-21 18:03:22Z sam $ */ |
---|
2 | |
---|
3 | /** \page migrating Migrating from libcaca 0.9 to the 1.0 API |
---|
4 | |
---|
5 | This section will guide you through the migration of a \e libcaca 0.9 |
---|
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 | \code |
---|
15 | #include <caca.h> |
---|
16 | |
---|
17 | int main(void) |
---|
18 | { |
---|
19 | /* Initialise libcaca */ |
---|
20 | caca_init(); |
---|
21 | /* Set window title */ |
---|
22 | caca_set_window_title("Hello!"); |
---|
23 | /* Choose drawing colours */ |
---|
24 | caca_set_color(CACA_COLOR_BLACK, CACA_COLOR_WHITE); |
---|
25 | /* Draw a string at coordinates (0, 0) */ |
---|
26 | caca_putstr(0, 0, "This is a message"); |
---|
27 | /* Refresh display */ |
---|
28 | caca_refresh(); |
---|
29 | /* Wait for a key press event */ |
---|
30 | caca_wait_event(CACA_EVENT_KEY_PRESS); |
---|
31 | /* Clean up library */ |
---|
32 | caca_end(); |
---|
33 | |
---|
34 | return 0; |
---|
35 | } |
---|
36 | \endcode |
---|
37 | |
---|
38 | You now do: |
---|
39 | |
---|
40 | \code |
---|
41 | #include <cucul.h> |
---|
42 | #include <caca.h> |
---|
43 | |
---|
44 | int main(void) |
---|
45 | { |
---|
46 | /* Initialise libcaca */ |
---|
47 | cucul_canvas_t *cv; caca_display_t *dp; caca_event_t ev; |
---|
48 | cv = cucul_create_canvas(0, 0); |
---|
49 | dp = caca_create_display(cv); |
---|
50 | /* Set window title */ |
---|
51 | caca_set_display_title(dp, "Hello!"); |
---|
52 | /* Choose drawing colours */ |
---|
53 | cucul_set_color(cv, CUCUL_COLOR_BLACK, CUCUL_COLOR_WHITE); |
---|
54 | /* Draw a string at coordinates (0, 0) */ |
---|
55 | cucul_putstr(cv, 0, 0, "This is a message"); |
---|
56 | /* Refresh display */ |
---|
57 | caca_refresh_display(); |
---|
58 | /* Wait for a key press event */ |
---|
59 | caca_get_event(dp, CACA_EVENT_KEY_PRESS, &ev, -1); |
---|
60 | /* Clean up library */ |
---|
61 | caca_free_display(dp); |
---|
62 | cucul_free_canvas(cv); |
---|
63 | |
---|
64 | return 0; |
---|
65 | } |
---|
66 | \endcode |
---|
67 | |
---|
68 | Note the following important things: |
---|
69 | |
---|
70 | - Functions now take an object handle as their first argument. |
---|
71 | - All input/output functions start with \b caca_ and all |
---|
72 | drawing and text handling functions start with \b cucul_ . |
---|
73 | |
---|
74 | \section foo2 Function equivalence list |
---|
75 | |
---|
76 | \subsection bar1 Basic functions |
---|
77 | |
---|
78 | - \b caca_init(): use cucul_create_canvas() to create a \e libcucul canvas, |
---|
79 | followed by caca_create_display() to attach a \e libcaca display to it. |
---|
80 | - \b caca_set_delay(): unchanged. |
---|
81 | - \b caca_get_feature(): deprecated. |
---|
82 | - \b caca_set_feature(): deprecated, see cucul_set_dither_antialias(), |
---|
83 | cucul_set_dither_color() and cucul_set_dither_mode() instead. |
---|
84 | - \b caca_get_feature_name(): deprecated, see cucul_get_dither_mode_list(), |
---|
85 | cucul_get_dither_antialias_list() and cucul_get_dither_color_list() |
---|
86 | instead. |
---|
87 | - \b caca_get_rendertime(): unchanged. |
---|
88 | - \b caca_get_width(): use cucul_get_canvas_width(). |
---|
89 | - \b caca_get_height(): use cucul_get_canvas_height(). |
---|
90 | - \b caca_set_window_title(): use caca_set_display_title(). |
---|
91 | - \b caca_get_window_width(): use caca_get_display_width(). |
---|
92 | - \b caca_get_window_height(): use caca_get_display_height(). |
---|
93 | - \b caca_refresh(): use caca_refresh_display(). |
---|
94 | - \b caca_end(): use caca_free_display() to detach the \e libcaca display, |
---|
95 | followed by cucul_free_canvas() to free the underlying \e libcucul canvas. |
---|
96 | |
---|
97 | \subsection bar2 Event handling |
---|
98 | |
---|
99 | - \b caca_get_event(): unchanged. |
---|
100 | - \b caca_wait_event(): use caca_get_event() with a \c timeout argument |
---|
101 | of \b -1. |
---|
102 | - \b caca_get_mouse_x(): unchanged. |
---|
103 | - \b caca_get_mouse_y(): unchanged. |
---|
104 | |
---|
105 | \subsection bar3 Character printing |
---|
106 | |
---|
107 | - \b caca_set_color(): use cucul_set_color() or cucul_set_truecolor(). |
---|
108 | - \b caca_get_fg_color(): deprecated. |
---|
109 | - \b caca_get_bg_color(): deprecated. |
---|
110 | - \b caca_get_color_name(): use cucul_get_color_name(). |
---|
111 | - \b caca_putchar(): use cucul_putchar(). |
---|
112 | - \b caca_putstr(): use cucul_putstr(). |
---|
113 | - \b caca_printf(): use cucul_printf(). |
---|
114 | - \b caca_clear(): use cucul_clear_canvas(). |
---|
115 | |
---|
116 | \subsection bar4 Primitives drawing |
---|
117 | |
---|
118 | - \b caca_draw_line(): use cucul_draw_line(). |
---|
119 | - \b caca_draw_polyline(): use cucul_draw_polyline(). |
---|
120 | - \b caca_draw_thin_line(): use cucul_draw_thin_line(). |
---|
121 | - \b caca_draw_thin_polyline(): use cucul_draw_thin_polyline(). |
---|
122 | |
---|
123 | - \b caca_draw_circle(): use cucul_draw_circle(). |
---|
124 | - \b caca_draw_ellipse(): use cucul_draw_ellipse(). |
---|
125 | - \b caca_draw_thin_ellipse(): use cucul_draw_thin_ellipse(). |
---|
126 | - \b caca_fill_ellipse(): use cucul_fill_ellipse(). |
---|
127 | |
---|
128 | - \b caca_draw_box(): use cucul_draw_box(). |
---|
129 | - \b caca_draw_thin_box(): use cucul_draw_thin_box(). |
---|
130 | - \b caca_fill_box(): use cucul_fill_box(). |
---|
131 | |
---|
132 | - \b caca_draw_triangle(): use cucul_draw_triangle(). |
---|
133 | - \b caca_draw_thin_triangle(): use cucul_draw_thin_triangle(). |
---|
134 | - \b caca_fill_triangle(): use cucul_fill_triangle(). |
---|
135 | |
---|
136 | \subsection bar5 Mathematical functions |
---|
137 | |
---|
138 | - \b caca_rand(): use cucul_rand() |
---|
139 | - \b caca_sqrt(): this function is now deprecated |
---|
140 | |
---|
141 | \subsection bar6 Sprite handling |
---|
142 | |
---|
143 | The sprite handling functions are currently being reworked. |
---|
144 | |
---|
145 | \subsection bar7 Bitmap handling |
---|
146 | |
---|
147 | - \b caca_create_bitmap(): use cucul_create_dither(). |
---|
148 | - \b caca_set_bitmap_palette(): use cucul_set_dither_palette(). |
---|
149 | - \b caca_draw_bitmap(): use cucul_dither_bitmap(). |
---|
150 | - \b caca_free_bitmap(): use cucul_free_dither(). |
---|
151 | |
---|
152 | \section foo3 Compilation |
---|
153 | |
---|
154 | The \c caca-config utility is deprecated in favour of the standard |
---|
155 | \c pkg-config interface: |
---|
156 | |
---|
157 | \code |
---|
158 | gcc -c foobar.c -o foobar.o `pkg-config --cflags caca` |
---|
159 | gcc foobar.o -o foobar `pkg-config --libs caca` |
---|
160 | \endcode |
---|
161 | |
---|
162 | \c caca-config is still provided as a convenience tool but will be removed |
---|
163 | in the future. |
---|
164 | |
---|
165 | */ |
---|