Added porting guide to help with transition to cairo 0.5 API.

Added notes for snapshot 0.5.0
Increment CAIRO_VERSION to 0.5.0

1 files changed, 257 insertions, 0 deletions

diff --git a/PORTING_GUIDE b/PORTING_GUIDE
new file mode 100644
index 000000000..b8bdd37b6
--- /dev/null
+++ b/PORTING_GUIDE
@@ -0,0 +1,257 @@
+		    ...-----=======-----...
+		    Cairo 0.5 Porting Guide
+		    ...-----=======-----...
+
+Here are some notes on more easily porting cairo_code from cairo 0.4
+to cairo 0.5. 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);
+
+Now:	cairo_set_source_rgba (cr, 0., 0., 0., 0.);
+	cairo_set_operator (cr, CAIRO_OPERATOR_SOURCE);
+	cairo_paint (cr);
+
+NOTE: Using cairo_rectanlgle 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.