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

Last change on this file since 824 was 824, checked in by Sam Hocevar, 14 years ago
  • Documentation improvements. Wrote a small migration guide and added the skeleton of a tutorial for Jylam.
  • Property svn:keywords set to Id
File size: 5.2 KB
RevLine 
[824]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
17int 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
44int 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
158gcc -c foobar.c -o foobar.o `pkg-config --cflags caca`
159gcc 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*/
Note: See TracBrowser for help on using the repository browser.