cairo/PORTING_GUIDE

   1                     ...-----=======-----...
   2                     Cairo 1.0 Porting Guide
   3                     ...-----=======-----...
   4
   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).
   8
   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:
  15
  16         util/cairo-api-update
  17
  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
  20 line. For example:
  21
  22         cairo-api-update *.[ch]
  23
  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.
  26
  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.
  30
  31
  32 Manual API changes
  33 ==================
  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.
  38
  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.
  45
  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:
  48
  49         foo.c:10: warning: implicit declaration of function
  50         ‘cairo_set_target_drawable_DEPRECATED_BY_cairo_xlib_surface_create’
  51
  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
  55 instead.
  56
  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.
  60
  61 cairo_create
  62 ------------
  63 Was:    cr = cairo_create ();
  64         cairo_set_target_foo (cr, args);
  65         /* draw */
  66         cairo_destroy (cr);
  67
  68 Now:    cairo_surface_t *surface;
  69
  70         surface = cairo_foo_surface_create (args);
  71         cr = cairo_create (surface);
  72         /* draw */
  73         cairo_destroy (cr);
  74         cairo_surface_destroy (surface);
  75
  76 Or:     cairo_surface_t *surface;
  77
  78         surface = cairo_foo_surface_create (args);
  79         cr = cairo_create (surface);
  80         cairo_surface_destroy (surface);
  81         /* draw */
  82         cairo_destroy (cr);
  83
  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.
  90
  91 cairo_set_alpha (1)
  92 -------------------
  93 Was:    cairo_set_rgb_color (cr, red, green, blue);
  94         cairo_set_alpha (cr, alpha);
  95
  96 Now:    cairo_set_source_rgba (cr, red, green, blue, alpha);
  97
  98 cairo_show_surface
  99 ------------------
 100 Was:    cairo_show_surface (cr, surface, width, height);
 101
 102 Now:    cairo_set_source_surface (cr, surface, x, y);
 103         cairo_paint (cr);
 104
 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.
 109
 110 cairo_set_alpha (2)
 111 -------------------
 112 Was:    cairo_set_alpha (cr, alpha);
 113         cairo_show_surface (cr, surface, width, height);
 114
 115 Now:    cairo_set_source_surface (cr, surface, x, y);
 116         cairo_paint_with_alpha (cr, alpha);
 117
 118 filling and stroking
 119 --------------------
 120 Was:    cairo_save (cr);
 121         /* set fill color */
 122         cairo_fiill (cr);
 123         cairo_restore (cr);
 124         /* set stroke color */
 125         cairo_stroke (cr);
 126
 127 Now:    /* set fill color */
 128         cairo_fill_preserve (cr);
 129         /* set stroke color */
 130         cairo_stroke (cr);
 131
 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.
 135
 136 cairo_matrix_t
 137 --------------
 138 Was:    cairo_matrix_t *matrix;
 139
 140         matrix = cairo_matrix_create ();
 141         /* Do stuff with matrix */
 142         cairo_matrix_destroy (matrix);
 143
 144 Now:    cairo_matrix_t matrix;
 145         cairo_matrix_init_identity (&matrix);
 146         /* Do stuff with &matrix */
 147
 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.
 154
 155 Rendering to a temporary surface
 156 --------------------------------
 157 Was:    cairo_save (cr);
 158         {
 159             cairo_set_target_surface (cr, temporary);
 160             /* draw through cr onto temporary */
 161         }
 162         cairo_restore (cr);
 163         /* use temporary as source on cr */
 164
 165 Now:    {
 166             cr2 = cairo_create (temporary);
 167             /* draw through cr2 onto temporary */
 168             cairo_destory (cr2);
 169         }
 170         /* use temporary as source on cr */
 171
 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.
 176
 177 Iterating over a path
 178 ---------------------
 179 Was:    cairo_current_path (cr,
 180                             my_move_to,
 181                             my_line_to,
 182                             my_curve_to,
 183                             my_close_path,
 184                             closure);
 185
 186 Now:    int i;
 187         cairo_path_t *path;
 188         cairo_path_data_t *data;
 189
 190         path = cairo_copy_path (cr);
 191
 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);
 197                 break;
 198             case CAIRO_PATH_LINE_TO:
 199                 my_line_to (closure, data[1].point.x, data[1].point.y);
 200                 break;
 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);
 205                 break;
 206             case CAIRO_PATH_CLOSE_PATH:
 207                 my_close_path (closure);
 208                 break;
 209             }
 210         }
 211         cairo_path_destroy (path);
 212
 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.
 218
 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);
 225         cairo_fill (cr);
 226
 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);
 230         cairo_fill (cr);
 231
 232 Now:    cairo_set_source_rgba (cr, 0., 0., 0., 0.);
 233         cairo_set_operator (cr, CAIRO_OPERATOR_SOURCE);
 234         cairo_paint (cr);
 235
 236     or: cairo_set_operator (cr, CAIRO_OPERATOR_CLEAR);
 237         cairo_paint (cr);
 238
 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
 242       target surface are).
 243
 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);
 249         /* draw image */
 250         cairo_destroy (cr);
 251         fclose (file);
 252
 253 Now:    surface = cairo_image_surface_create (format, width, height);
 254         cr = cairo_create (surface);
 255         /* draw image */
 256         cairo_surface_write_to_png (surface, filename);
 257         cairo_destroy (cr);
 258         cairo_surface_destroy (surface);
 259
 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.