...-----=======-----...
Cairo 1.0 Porting Guide
...-----=======-----...
Here are some notes on more easily porting cairo_code from cairo 0.4
to cairo 1.0. It is sorted roughly in order of importance, (the items
near the top are expected to affect the most people).
Automated API renamings
=======================
There have been a lot of simple renamings where the functionality is
the same but the name of the symbol is different. We have provided a
script to automate the conversion of these symbols. It can be found
within the cairo distribution in:
util/cairo-api-update
This script is used by installing it somewhere on your PATH, and the
running it and providing the names of your source files on the command
line. For example:
cairo-api-update *.[ch]
The script will first save backup copies of each file (renamed with a
.bak extension) and then will perform all of the simple renamings.
For your benefit, the script also produces messages giving filenames
and line numbers for several of the manual API updates that you will
need to perform as described below.
Manual API changes
==================
This section of the porting guide describes changes you will have to
manually make to your source code. In addition to the information in
this guide, the cairo-api-update script will notify you of some of
these issues as described above.
Cairo's deprecation warnings
----------------------------
Also, if your compiler provides warnings for implicit declarations of
functions, (eg. "gcc -Wall"), then simply attempting to compile your
program will cause cairo to generate messages intended to guide you
through the porting process.
For example, if you neglect to update an old call to
cairo_set_target_drawable, you might see an error message as follows:
foo.c:10: warning: implicit declaration of function
‘cairo_set_target_drawable_DEPRECATED_BY_cairo_xlib_surface_create’
This message is indicating to you that the deprecatd function
cairo_set_target_drawable appears in your program foo.c on line 10,
and you should rewrite your program to call cairo_xlib_surface_create
instead.
The remainder of this porting guide is arranged as a set of common
code patterns that appear in old (cairo-0.4) code and how it should be
transformed to new (cairo-0.5) code.
cairo_create
------------
Was: cr = cairo_create ();
cairo_set_target_foo (cr, args);
/* draw */
cairo_destroy (cr);
Now: cairo_surface_t *surface;
surface = cairo_foo_surface_create (args);
cr = cairo_create (surface);
/* draw */
cairo_destroy (cr);
cairo_surface_destroy (surface);
Or: cairo_surface_t *surface;
surface = cairo_foo_surface_create (args);
cr = cairo_create (surface);
cairo_surface_destroy (surface);
/* draw */
cairo_destroy (cr);
NOTE: Many of the cairo_foo_surface_create functions accept the
identical arguments as the the old cairo_set_target_foo
functions, (minus the cairo_t*), making this transformation
quite easy. One notable exception is cairo_set_target_drawable
which, when it becomes cairo_xlib_surface_create must pickup new
arguments for the Visual*, the width, and the height.
cairo_set_alpha (1)
-------------------
Was: cairo_set_rgb_color (cr, red, green, blue);
cairo_set_alpha (cr, alpha);
Now: cairo_set_source_rgba (cr, red, green, blue, alpha);
cairo_show_surface
------------------
Was: cairo_show_surface (cr, surface, width, height);
Now: cairo_set_source_surface (cr, surface, x, y);
cairo_paint (cr);
NOTE: The type signatures of cairo_show_surface and cairo_set_source
are the same, but pay attention that cairo_show_surface required
the width and height, while cairo_set_source_surface requires
the X,Y location to where the surface will be placed.
cairo_set_alpha (2)
-------------------
Was: cairo_set_alpha (cr, alpha);
cairo_show_surface (cr, surface, width, height);
Now: cairo_set_source_surface (cr, surface, x, y);
cairo_paint_with_alpha (cr, alpha);
filling and stroking
--------------------
Was: cairo_save (cr);
/* set fill color */
cairo_fiill (cr);
cairo_restore (cr);
/* set stroke color */
cairo_stroke (cr);
Now: /* set fill color */
cairo_fill_preserve (cr);
/* set stroke color */
cairo_stroke (cr);
NOTE: The current path is no longer saved/restored by
cairo_save/cairo_restore. This can lead to some subtle
surprises, so look out.
cairo_matrix_t
--------------
Was: cairo_matrix_t *matrix;
matrix = cairo_matrix_create ();
/* Do stuff with matrix */
cairo_matrix_destroy (matrix);
Now: cairo_matrix_t matrix;
cairo_matrix_init_identity (&matrix);
/* Do stuff with &matrix */
NOTE: If you are really lazy, you can still use a cairo_matrix_t* and
avoid putting the &matrix all over by just replacing
cairo_matrix_create() with malloc() and cairo_matrix_destroy()
with free(). That's not as nice, and you still need to be
careful to see if you need to initialize it to an identity
matrix as cairo_matrix_create() did for you.
Rendering to a temporary surface
--------------------------------
Was: cairo_save (cr);
{
cairo_set_target_surface (cr, temporary);
/* draw through cr onto temporary */
}
cairo_restore (cr);
/* use temporary as source on cr */
Now: {
cr2 = cairo_create (temporary);
/* draw through cr2 onto temporary */
cairo_destory (cr2);
}
/* use temporary as source on cr */
NOTE: Having to create another cairo_t is a bit annoying, but having
to invent a new name for it is just awful, (imagine a deeply
nested version of this code). Fortunately, the style above is
just a stop-gap measure until the new group API comes along.
Iterating over a path
---------------------
Was: cairo_current_path (cr,
my_move_to,
my_line_to,
my_curve_to,
my_close_path,
closure);
Now: int i;
cairo_path_t *path;
cairo_path_data_t *data;
path = cairo_copy_path (cr);
for (i=0; i < path->num_data; i += path->data[i].header.length) {
data = &path->data[i];
switch (data->header.type) {
case CAIRO_PATH_MOVE_TO:
my_move_to (closure, data[1].point.x, data[1].point.y);
break;
case CAIRO_PATH_LINE_TO:
my_line_to (closure, data[1].point.x, data[1].point.y);
break;
case CAIRO_PATH_CURVE_TO:
my_curve_to (closure, data[1].point.x, data[1].point.y,
data[2].point.x, data[2].point.y,
data[3].point.x, data[3].point.y);
break;
case CAIRO_PATH_CLOSE_PATH:
my_close_path (closure);
break;
}
}
cairo_path_destroy (path);
NOTE: This version makes it looks like the new form is a _lot_ more
verbose than the old version. But realize that the old version
required the support of 4 additional functions. The new approach
allows great flexibility including the ability to inline the
entire operation within the switch statement when appropriate.
Erasing a surface to transparent
--------------------------------
Was: cairo_set_rgb_color (cr, 0., 0., 0.);
cairo_set_alpha (cr, 0.)
cairo_set_operator (cr, CAIRO_OPERATOR_SRC);
cairo_rectangle (cr, 0., 0., surface_width, surface_height);
cairo_fill (cr);
or: cairo_set_rgb_color (cr, 0., 0., 0.);
cairo_set_operator (cr, CAIRO_OPERATOR_CLEAR);
cairo_rectangle (cr, 0., 0., surface_width, surface_height);
cairo_fill (cr);
Now: cairo_set_source_rgba (cr, 0., 0., 0., 0.);
cairo_set_operator (cr, CAIRO_OPERATOR_SOURCE);
cairo_paint (cr);
or: cairo_set_operator (cr, CAIRO_OPERATOR_CLEAR);
cairo_paint (cr);
NOTE: Using cairo_rectangle and fill would still work just fine. It's
just a lot more convenient to use cairo_paint now, (particularly
as it doesn't require you to even know what the bounds of the
target surface are).
Drawing to a PNG file
---------------------
Was: file = fopen (filename, "w");
cr = cairo_create ();
cairo_set_target_png (cr, file, format, width, height);
/* draw image */
cairo_destroy (cr);
fclose (file);
Now: surface = cairo_image_surface_create (format, width, height);
cr = cairo_create (surface);
/* draw image */
cairo_surface_write_to_png (surface, filename);
cairo_destroy (cr);
cairo_surface_destroy (surface);
NOTE: The png backend is gone. So there is no cairo_png_surface_create
to take the place of cairo_set_target_png. And notice that we
used an image surface here, but it is just as easy to use
cairo_surface_write_to_png with an xlib or other surface, (but
not PDF at the moment). This is one of the big advantages of
this approach as opposed to a PNG surface.