diff options
Diffstat (limited to 'libs/cairo-1.16.0/PORTING_GUIDE')
| -rw-r--r-- | libs/cairo-1.16.0/PORTING_GUIDE | 265 |
1 files changed, 0 insertions, 265 deletions
diff --git a/libs/cairo-1.16.0/PORTING_GUIDE b/libs/cairo-1.16.0/PORTING_GUIDE deleted file mode 100644 index 7488173..0000000 --- a/libs/cairo-1.16.0/PORTING_GUIDE +++ /dev/null @@ -1,265 +0,0 @@ - ...-----=======-----... - 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. |