[cairo-commit] cairo ChangeLog, 1.608, 1.609 NEWS, 1.15,
1.16 PORTING_GUIDE, NONE, 1.1 configure.in, 1.102, 1.103
Carl Worth
commit at pdx.freedesktop.org
Tue May 17 18:39:58 PDT 2005
Committed by: cworth
Update of /cvs/cairo/cairo
In directory gabe:/tmp/cvs-serv3353
Modified Files:
ChangeLog NEWS configure.in
Added Files:
PORTING_GUIDE
Log Message:
* PORTING_GUIDE: Added porting guide to help with transition to
cairo 0.5 API.
* NEWS: Added notes for snapshot 0.5.0
* configure.in: Increment CAIRO_VERSION to 0.5.0
Index: ChangeLog
===================================================================
RCS file: /cvs/cairo/cairo/ChangeLog,v
retrieving revision 1.608
retrieving revision 1.609
diff -u -d -r1.608 -r1.609
--- ChangeLog 17 May 2005 22:23:53 -0000 1.608
+++ ChangeLog 18 May 2005 01:39:56 -0000 1.609
@@ -1,5 +1,14 @@
2005-05-17 Carl Worth <cworth at cworth.org>
+ * PORTING_GUIDE: Added porting guide to help with transition to
+ cairo 0.5 API.
+
+ * NEWS: Added notes for snapshot 0.5.0
+
+ * configure.in: Increment CAIRO_VERSION to 0.5.0
+
+2005-05-17 Carl Worth <cworth at cworth.org>
+
* src/cairo-xcb-surface.c: (_get_image_surface),
(_cairo_xcb_surface_create_internal): Bring up to date with
Keith's latest improvements to cairo-xlib-surface.c: Add some
Index: NEWS
===================================================================
RCS file: /cvs/cairo/cairo/NEWS,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -d -r1.15 -r1.16
--- NEWS 9 Mar 2005 03:25:39 -0000 1.15
+++ NEWS 18 May 2005 01:39:56 -0000 1.16
@@ -1,3 +1,307 @@
+Snapshot 0.5.0 (2005-05-17 Carl Worth <cworth at cworth.org>)
+==========================================================
+This is a pretty big, and fairly significant snapshot. It represents
+between 2 and 3 months of solid work from a lot of people on improving
+the API as much as possible. I'd like to express my appreciation and
+congratulations to everyone who has worked on the big API Shakeup,
+(whether in email battles over names, or fixing my silly bugs).
+
+This snapshot will require some effort on the part of users, since
+there are a _lot_ of API changes (ie. no cairo program ever written is
+safe --- they're all broken now in at least one way). But, in spite of
+that, we do encourage everyone to move their code to this snapshot as
+soon as possible. And we're doing everything we can think of to make
+the transition as smooth as possible.
+
+The idea behind 0.5 is that we've tried to make every good API change
+we could want now, and get them all done with. That is, between now
+and the 1.0 release of cairo, we expect very few new API changes,
+(though some will certainly sneak in). We will have some significant
+additions, but the pain of moving code from cairo 0.4 to cairo 0.5
+should be a one time experience, and things should be much smoother as
+we continue to move toward cairo 1.0.
+
+And with so many changes coming out for the first time in this 0.5
+release, we really do need a lot of people trying this out to make
+sure the ideas are solid before we freeze the API in preparation for
+the 1.0 release.
+
+OK, enough introduction. Here is a (not-quite-complete) description of
+the API removals, changes and additions in this snapshot, (compared to
+0.4.0)
+
+API removals
+============
+The following public functions have been removed:
+
+- cairo_set_target_*
+
+ This is a big change. See the description of cairo_create in
+ the API changes section for how to deal with this.
+
+- cairo_set_alpha
+
+ Alpha blending hasn't gone away; there's just a much more
+ unified rendering model now. Almost all uses of
+ cairo_set_alpha will be trivially replaced with
+ cairo_set_source_rgba and a few others will be replaced just
+ as easily with cairo_paint_with_alpha.
+
+- cairo_show_surface
+
+ Another useful function that we realized was muddling up the
+ rendering model. The replacement is quite easy:
+ cairo_set_source_surface and cairo_paint.
+
+- cairo_matrix_create
+- cairo_matrix_destroy
+- cairo_matrix_copy
+- cairo_matrix_get_affine
+
+ These functions supported an opaque cairo_matrix_t. We now
+ have an exposed cairo_matrix_t structure, so these can be
+ dropped.
+
+- cairo_surface_set_repeat
+- cairo_surface_set_matrix
+- cairo_surface_set_filter
+
+ These properties don't belong on surfaces. If you were using
+ them, you'll just want to instead use
+ cairo_pattern_create_for_surface and then set these properties
+ on the pattern.
+
+- cairo_copy
+
+ This was a confusing function and hopefully nobody will miss
+ it. But if you really don't find cairo_save/restore adequate,
+ let us know and we have another idea for a potential
+ replacement.
+
+And while we're on the subject of removals, we carefully tightened up
+the cairo header files so they no longer gratuitously include header
+files that are not strictly necessary, (stdio.h, stdint.h, pixman.h,
+Xrender.h, etc. and their dependencies). This may lead to some
+surprising errors, so keep your eyes open for that.
+
+API changes
+===========
+Here are some of the API changes that have occurred:
+
+~ cairo_create(void) -> cairo_create(cairo_surface_t *)
+
+ This is the big change that breaks every program. The ability
+ to re-target a cairo_t was not particularly useful, but it did
+ introduce a lot of muddy semantic questions. To eliminate
+ that, cairo_create now requires its target surface to be
+ passed in at creation time. This isn't too hard to cope with
+ as the typical first operation after cairo_create was often
+ cairo_set_target_foo. So the order of those two swap and the
+ application instead has cairo_foo_surface_create, then
+ cairo_create.
+
+~ cairo_current_* -> cairo_get_*
+
+ We had a strange mixture of cairo_get and cairo_current
+ functions. They've all been standardized on cairo_get, (though
+ note one is cairo_get_current_point).
+
+~ CAIRO_OPERATOR_SRC -> CAIRO_OPERATOR_SOURCE
+~ CAIRO_OPERATOR_OVER_REVERSE -> CAIRO_OPERATOR_DEST_OVER
+
+ Many of the cairo_operator_t symbolic values were renamed to
+ reduce the amount of abbreviation. The confusing "OP_REVERSE"
+ naming was also changed to use "DEST_OP" instead which is
+ easier to read and has wider acceptance in other
+ libraries/languages.
+
+~ cairo_set_pattern -> cairo_set_source
+~ cairo_set_rgb_color -> cairo_set_source_rgb
+
+ All of the various functions that changed the source
+ color/pattern were unified to use cairo_set_source names to
+ make the relation more clear.
+
+~ cairo_transform_point -> cairo_user_to_device
+~ cairo_transform_distance -> cairo_user_to_device_distance
+~ cairo_inverse_transform_point -> cairo_device_to_user
+~ cairo_inverse_transform_distance -> cairo_device_to_user_distance
+
+ These names just seemed a lot more clear.
+
+~ cairo_init_clip -> cairo_reset_clip
+~ cairo_concat_matrix -> cairo_transform
+
+ More abbreviation elimination
+
+~ cairo_current_path -> cairo_copy_path
+~ cairo_current_path_flat -> cairo_copy_path_flat
+
+ The former mechanism for examining the current path was a
+ function that required 3 or 4 callbacks. This was more
+ complexity than warranted in most situations. The new
+ cairo_copy_path function copies the current path into an
+ exposed data structure, and the documentation provides a
+ convenient idiom for navigating the path data.
+
+API additions
+-------------
++ cairo_paint
+
+ A generalized version of the painting operators cairo_stroke
+ and cairo_fill. The cairo_paint call applies the source paint
+ everywhere within the current clip region. Very useful for
+ clearing a surface to a solid color, or painting an image,
+ (see cairo_set_source_surface).
+
++ cairo_paint_with_alpha
+
+ Like cairo_paint but applying some alpha to the source,
+ (making the source paint translucent, eg. to blend an image on
+ top of another).
+
++ cairo_mask
+
+ A more generalized version of cairo_paint_with_alpha which
+ allows a pattern to specify the amount of translucence at each
+ point rather than using a constant value everywhere.
+
++ cairo_mask_surface
+
+ A convenience function on cairo_mask for when the mask pattern
+ is already contained within a surface.
+
++ cairo_surface_set_user_data
++ cairo_surface_get_user_data
++ cairo_font_face_set_user_data
++ cairo_font_face_get_user_data
+
+ Associate arbitrary data with a surface or font face for later
+ retrieval. Get notified when a surface or font face object is
+ destroyed.
+
++ cairo_surface_finish
+
+ Allows the user to instruct cairo to finish all of its
+ operations for a given surface. This provides a safe point for
+ doing things such as flushing and closing files that the
+ surface may have had open for writing.
+
++ cairo_fill_preserve
++ cairo_stroke_preserve
++ cairo_clip_preserve
+
+ One interesting change in cairo is that the path is no longer
+ part of the graphics state managed by
+ cairo_save/restore. This allows functions to construct paths
+ without interfering with the graphics state. But it prevents
+ the traditional idiom for fill-and-stroke:
+
+ cairo_save; cairo_fill; cairo_restore; cairo_stroke
+
+ Instead we know have alternate versions cairo cairo_fill,
+ cairo_stroke, and cairo_clip that preserve the current path
+ rather than consuming it. So the idiom now becomes simply:
+
+ cairo_fill_preserve; cairo_stroke
+
++ cairo_surface_write_to_png
++ cairo_surface_write_to_png_stream
+
+ In place of a single PNG backend, now a surface created
+ through any backend (except PDF currently) can be written out
+ to a PNG image.
+
++ cairo_image_surface_create_from_png
++ cairo_image_surface_create_from_png_stream
+
+ And its just as easy to load a PNG image into a surface as well.
+
++ cairo_append_path
+
+ With the new, exposed path data structure, it's now possible
+ to append bulk path data to the current path, (rather than
+ issuing a long sequence of cairo_move_to/line_to/curve_to
+ function calls).
+
+Xlib and XCB backends
+---------------------
+
+Any cairo_format_t and Colormap arguments have been dropped from
+cairo_xlib_surface_create. There are also two new
+cairo_xlib|xcb_surface_create functions:
+
+ cairo_xlib|xcb_surface_create_for_bitmap
+ (Particular for creating A1 surfaces)
+ cairo_xlib|xcb_surface_create_with_xrender_format
+ (For any other surface types, not described by a Visual*)
+
+All of these surface create functions now accept width and height. In
+addition, there are new cairo_xlib|xcb_surface_set_size functions
+which must be called each time a window that is underlying a surface
+changes size.
+
+Print backends (PS and PDF)
+---------------------------
+The old FILE* based interfaces have been eliminated. In their place we
+have two different functions. One accepts a simple const char
+*filename. The other is a more general function which accepts a
+callback write function and a void* closure. This should allow the
+flexibility needed to hook up with various stream object in many
+languages.
+
+In addition, when specifying the surface size during construction, the
+units are now device-space units (ie. points) rather than inches. This
+provides consistency with all the other surface types and also makes
+it much easier to reason about the size of the surface when drawing to
+it with the default identity matrix.
+
+Finally, the DPI parameters, which are only needed to control the
+quality of fallbacks, have been made optional. Nothing is required
+during surface_create (300 DPI is assumed) and
+cairo_ps|pdf_surface_set_dpi can be used to set alternate values if
+needed.
+
+Font system
+-----------
+Owen very graciously listened to feedback after the big font rework he
+had done for 0.4, and came up with way to improve it even more. In 0.4
+there was a cairo_font_t that was always pre-scaled. Now, there is an
+unscaled cairo_font_face_t which is easier to construct, (eg. no
+scaling matrix required) and work with, (it can be scaled and
+transformed after being set on the graphics state). And the font size
+manipulation functions are much easier. You can set an explicit size
+and read/modify/write the font matrix with:
+
+ cairo_set_font_size
+ cairo_get_font_matrix
+ cairo_set_font_matrix
+
+(Previously you could only multiply in a scale factor or a matrix.) A
+pleasant side effect is that we can (and do) now have a default font
+size that is reasonable, as opposed to the old default height of one
+device-space unit which was useless until scaled.
+
+Of course, the old pre-scaled font had allowed some performance
+benefits when getting many metrics for a font. Those benefits are
+still made available through the new cairo_scaled_font_t. And a
+cairo_font_face_t can be "promoted" to a cairo_scaled_font_t by
+suppling a font_matrix and the desired CTM.
+
+Quartz backend
+--------------
+Tim Rowley put in the work to bring the Quartz backend back after it
+had been disabled in the 0.4.0 snapshot. He was not able to bring back
+the function that allows one to create a cairo_font_t from an ATSUI
+style:
+
+ cairo_font_t *
+ cairo_atsui_font_create (ATSUStyle style);
+
+because he didn't have a test case for it. If you care about this
+function, please provide a fairly minimal test and we'll try to bring
+it back in an upcoming snapshot.
+
Snapshot 0.4.0 (2005-03-08 Carl Worth <cworth at cworth.org>)
==========================================================
New documentation
--- NEW FILE: PORTING_GUIDE ---
...-----=======-----...
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.
Index: configure.in
===================================================================
RCS file: /cvs/cairo/cairo/configure.in,v
retrieving revision 1.102
retrieving revision 1.103
diff -u -d -r1.102 -r1.103
--- configure.in 10 May 2005 21:54:48 -0000 1.102
+++ configure.in 18 May 2005 01:39:56 -0000 1.103
@@ -5,7 +5,7 @@
dnl ===========================================================================
# Package version number, (as distinct from shared library version)
-CAIRO_VERSION=0.4.0-head
+CAIRO_VERSION=0.5.0
# libtool shared library version
More information about the cairo-commit
mailing list