[cairo-announce] cairo snapshot 0.5.0 now available

Carl Worth cworth at cworth.org
Tue May 17 18:47:07 PDT 2005

A new cairo snapshot 0.5.0 is now available from:

        cf39f429026498128fd4711cf4b824bf  cairo-0.5.0.tar.gz

This includes all the big API Shakeup stuff we've been working on over
the past couple of months. I'll send a porting guide in a separate mail
to help people with the process of getting their code running.

There are (long) release notes below. Not too interesting, although I
did try to capture the rationale for a lot of the changes for anyone
that might be interested.


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

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

- 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

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_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).


	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

~ 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

+ 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:

		(Particular for creating A1 surfaces)
		(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

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

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:


(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

	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.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo-announce/attachments/20050517/1271bf1d/attachment.pgp

More information about the cairo-announce mailing list