diff options
Diffstat (limited to 'PORTING_GUIDE')
| -rwxr-xr-x | PORTING_GUIDE | 265 |
1 files changed, 265 insertions, 0 deletions
diff --git a/PORTING_GUIDE b/PORTING_GUIDE new file mode 100755 index 000000000..7488173c4 --- /dev/null +++ b/PORTING_GUIDE @@ -0,0 +1,265 @@ + ...-----=======-----... + 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. |