1
...-----=======-----...
2
Cairo 1.0 Porting Guide
3
...-----=======-----...
5
Here are some notes on more easily porting cairo_code from cairo 0.4
6
to cairo 1.0. It is sorted roughly in order of importance, (the items
7
near the top are expected to affect the most people).
9
Automated API renamings
10
=======================
11
There have been a lot of simple renamings where the functionality is
12
the same but the name of the symbol is different. We have provided a
13
script to automate the conversion of these symbols. It can be found
14
within the cairo distribution in:
18
This script is used by installing it somewhere on your PATH, and the
19
running it and providing the names of your source files on the command
22
cairo-api-update *.[ch]
24
The script will first save backup copies of each file (renamed with a
25
.bak extension) and then will perform all of the simple renamings.
27
For your benefit, the script also produces messages giving filenames
28
and line numbers for several of the manual API updates that you will
29
need to perform as described below.
34
This section of the porting guide describes changes you will have to
35
manually make to your source code. In addition to the information in
36
this guide, the cairo-api-update script will notify you of some of
37
these issues as described above.
39
Cairo's deprecation warnings
40
----------------------------
41
Also, if your compiler provides warnings for implicit declarations of
42
functions, (eg. "gcc -Wall"), then simply attempting to compile your
43
program will cause cairo to generate messages intended to guide you
44
through the porting process.
46
For example, if you neglect to update an old call to
47
cairo_set_target_drawable, you might see an error message as follows:
49
foo.c:10: warning: implicit declaration of function
50
‘cairo_set_target_drawable_DEPRECATED_BY_cairo_xlib_surface_create’
52
This message is indicating to you that the deprecatd function
53
cairo_set_target_drawable appears in your program foo.c on line 10,
54
and you should rewrite your program to call cairo_xlib_surface_create
57
The remainder of this porting guide is arranged as a set of common
58
code patterns that appear in old (cairo-0.4) code and how it should be
59
transformed to new (cairo-0.5) code.
63
Was: cr = cairo_create ();
64
cairo_set_target_foo (cr, args);
68
Now: cairo_surface_t *surface;
70
surface = cairo_foo_surface_create (args);
71
cr = cairo_create (surface);
74
cairo_surface_destroy (surface);
76
Or: cairo_surface_t *surface;
78
surface = cairo_foo_surface_create (args);
79
cr = cairo_create (surface);
80
cairo_surface_destroy (surface);
84
NOTE: Many of the cairo_foo_surface_create functions accept the
85
identical arguments as the the old cairo_set_target_foo
86
functions, (minus the cairo_t*), making this transformation
87
quite easy. One notable exception is cairo_set_target_drawable
88
which, when it becomes cairo_xlib_surface_create must pickup new
89
arguments for the Visual*, the width, and the height.
93
Was: cairo_set_rgb_color (cr, red, green, blue);
94
cairo_set_alpha (cr, alpha);
96
Now: cairo_set_source_rgba (cr, red, green, blue, alpha);
100
Was: cairo_show_surface (cr, surface, width, height);
102
Now: cairo_set_source_surface (cr, surface, x, y);
105
NOTE: The type signatures of cairo_show_surface and cairo_set_source
106
are the same, but pay attention that cairo_show_surface required
107
the width and height, while cairo_set_source_surface requires
108
the X,Y location to where the surface will be placed.
112
Was: cairo_set_alpha (cr, alpha);
113
cairo_show_surface (cr, surface, width, height);
115
Now: cairo_set_source_surface (cr, surface, x, y);
116
cairo_paint_with_alpha (cr, alpha);
120
Was: cairo_save (cr);
124
/* set stroke color */
127
Now: /* set fill color */
128
cairo_fill_preserve (cr);
129
/* set stroke color */
132
NOTE: The current path is no longer saved/restored by
133
cairo_save/cairo_restore. This can lead to some subtle
134
surprises, so look out.
138
Was: cairo_matrix_t *matrix;
140
matrix = cairo_matrix_create ();
141
/* Do stuff with matrix */
142
cairo_matrix_destroy (matrix);
144
Now: cairo_matrix_t matrix;
145
cairo_matrix_init_identity (&matrix);
146
/* Do stuff with &matrix */
148
NOTE: If you are really lazy, you can still use a cairo_matrix_t* and
149
avoid putting the &matrix all over by just replacing
150
cairo_matrix_create() with malloc() and cairo_matrix_destroy()
151
with free(). That's not as nice, and you still need to be
152
careful to see if you need to initialize it to an identity
153
matrix as cairo_matrix_create() did for you.
155
Rendering to a temporary surface
156
--------------------------------
157
Was: cairo_save (cr);
159
cairo_set_target_surface (cr, temporary);
160
/* draw through cr onto temporary */
163
/* use temporary as source on cr */
166
cr2 = cairo_create (temporary);
167
/* draw through cr2 onto temporary */
170
/* use temporary as source on cr */
172
NOTE: Having to create another cairo_t is a bit annoying, but having
173
to invent a new name for it is just awful, (imagine a deeply
174
nested version of this code). Fortunately, the style above is
175
just a stop-gap measure until the new group API comes along.
177
Iterating over a path
178
---------------------
179
Was: cairo_current_path (cr,
188
cairo_path_data_t *data;
190
path = cairo_copy_path (cr);
192
for (i=0; i < path->num_data; i += path->data[i].header.length) {
193
data = &path->data[i];
194
switch (data->header.type) {
195
case CAIRO_PATH_MOVE_TO:
196
my_move_to (closure, data[1].point.x, data[1].point.y);
198
case CAIRO_PATH_LINE_TO:
199
my_line_to (closure, data[1].point.x, data[1].point.y);
201
case CAIRO_PATH_CURVE_TO:
202
my_curve_to (closure, data[1].point.x, data[1].point.y,
203
data[2].point.x, data[2].point.y,
204
data[3].point.x, data[3].point.y);
206
case CAIRO_PATH_CLOSE_PATH:
207
my_close_path (closure);
211
cairo_path_destroy (path);
213
NOTE: This version makes it looks like the new form is a _lot_ more
214
verbose than the old version. But realize that the old version
215
required the support of 4 additional functions. The new approach
216
allows great flexibility including the ability to inline the
217
entire operation within the switch statement when appropriate.
219
Erasing a surface to transparent
220
--------------------------------
221
Was: cairo_set_rgb_color (cr, 0., 0., 0.);
222
cairo_set_alpha (cr, 0.)
223
cairo_set_operator (cr, CAIRO_OPERATOR_SRC);
224
cairo_rectangle (cr, 0., 0., surface_width, surface_height);
227
or: cairo_set_rgb_color (cr, 0., 0., 0.);
228
cairo_set_operator (cr, CAIRO_OPERATOR_CLEAR);
229
cairo_rectangle (cr, 0., 0., surface_width, surface_height);
232
Now: cairo_set_source_rgba (cr, 0., 0., 0., 0.);
233
cairo_set_operator (cr, CAIRO_OPERATOR_SOURCE);
236
or: cairo_set_operator (cr, CAIRO_OPERATOR_CLEAR);
239
NOTE: Using cairo_rectangle and fill would still work just fine. It's
240
just a lot more convenient to use cairo_paint now, (particularly
241
as it doesn't require you to even know what the bounds of the
244
Drawing to a PNG file
245
---------------------
246
Was: file = fopen (filename, "w");
247
cr = cairo_create ();
248
cairo_set_target_png (cr, file, format, width, height);
253
Now: surface = cairo_image_surface_create (format, width, height);
254
cr = cairo_create (surface);
256
cairo_surface_write_to_png (surface, filename);
258
cairo_surface_destroy (surface);
260
NOTE: The png backend is gone. So there is no cairo_png_surface_create
261
to take the place of cairo_set_target_png. And notice that we
262
used an image surface here, but it is just as easy to use
263
cairo_surface_write_to_png with an xlib or other surface, (but
264
not PDF at the moment). This is one of the big advantages of
265
this approach as opposed to a PNG surface.
added
removed
PORTING_GUIDE
