cairo 1.2.0 release available
From: Carl Worth <cworth@cworth.org>
Date: 1 Jul 2006
To: cairo-announce@cairographics.org
CC: gnome-announce-list@gnome.org
Subject: cairo release 1.2.0 now available

A new cairo release 1.2.0 is now available from:

        http://cairographics.org/releases/cairo-1.2.0.tar.gz

    which can be verified with:

        http://cairographics.org/releases/cairo-1.2.0.tar.gz.sha1
        c5da7f89cdd3782102357f99a47f516d11661e92  cairo-1.2.0.tar.gz

        http://cairographics.org/releases/cairo-1.2.0.tar.gz.sha1.asc
        (signed by Carl Worth)

  Additionally, a git clone of the source tree:

        git clone git://git.cairographics.org/git/cairo

    will include a signed 1.2.0 tag which points to a commit named:
        61404bd5022b913f58ecda8dc9e8922b4fc6f80b

    which can be verified with:
        git verify-tag 1.2.0

    and can be checked out with a command such as:
        git checkout -b build 1.2.0

We are very pleased to announce this release, the first major update
to cairo since the original 1.0 release 10 months ago. Compared to
cairo 1.0, the 1.2 release doubles the number of supported backends,
adding PDF, PostScript, and SVG backends to the previous xlib, win32
and image backends.

As with all of cairo's major releases, cairo 1.2 retains both source
and binary compatibility with the cairo 1.0 series. Programs compiled
for cairo 1.0 should run with cairo 1.2 without requiring any
modification.

I want to personally express my congratulations and admiration to
everyone on the cairo team. This includes authors of code,
contributors on the cairo mailing list, and users who have submitted
bug reports and suggestions. This release has been a huge effort, and
its high quality is due to the contributions of dozens of
people---many more than are mentioned below. So thank you!

I would also like to thank everyone for their patience during this
long and uncertain release process. I imagine some people may have
thought cairo 1.2 would never appear as date after projected date
slipped by. I should express particular thanks to Behdad Esfahbod
without whom the release still wouldn't be done, nor would it be
nearly as good, (many documentation updates, good catches of bad
mistakes that almost got frozen in the release, etc). Thanks Behdad!

-Carl

What's new in cairo 1.2 compared to 1.0
=======================================
New, supported backends (PDF, PostScript, and SVG)
--------------------------------------------------
The major theme of the 1.2 release is new PDF, PostScript and SVG
backends for cairo. Unlike the 1.0 series, in the 1.2 series these
backends are not marked as experimental and are now fully supported,
(that is, they will now have the same API stability guarantees as the
rest of the library).

These new backends form an integral part of the new printing support
that will soon be released as part of GTK+ 2.10.

Earlier, experimental versions of the PDF and PostScript backends used
image fallbacks exclusively, which was obviously unsatisfactory for
many uses. In contrast, the PDF backend in the cairo 1.2.0 release
will emit vectorized output for all operations drawn with the default
OVER operator, even when the drawing includes translucence. The
PostScript backend emits vectorized output as long as there is no
translucency. The SVG backend can handle basically anything with
vector output, (particularly if the user selects SVG 1.2 output).

And as always, with any supported cairo backend, the backends should
work fine with any possible cairo operations, (through image
fallbacks). In 1.2.0, when a fallback is necessary on any page, it
renders the entire page as a fallback. It is expected that future
releases will fallback more gracefully and use images only for the
minimum region necessary.

Text support in these backends has seen a tremendous amount of
work. At a minimum, text will be rendered as paths in any of the
backends, (assuming no other operations force a fallback). And in the
PDF and PostScript backends, both type1 and TrueType fonts will be
directly embedded in the output file. This results in higher-quality
previews and better performance. Note however, that due to a known bug
in the PDF backend, it is not currently possible to use a PDF viewer
to select text in a PDF file generated by cairo. It is anticipated
that this shortcoming will be addressed shortly in a subsequent
release.

New, experimental backends (beos and directfb)
----------------------------------------------
The 1.2.0 release includes two new backends that did not exist in the
1.0 series:

    * beos backend
    * directfb backend

These are experimental still, (as are the existing xcb, glitz, and
quartz backends), meaning we don't yet guarantee they are fully
functional, (not yet passing the entire test suite), nor are we
guaranteeing strong API compatibility into the future.

But please feel free to experiment with these backends and give use
feedback, or help us to improve them.

Group rendering API
-------------------
The long-awaited group-rendering support is now available with the
following function calls:

    cairo_push_group
    cairo_push_group_with_content
    cairo_pop_group
    cairo_pop_group_to_source
    cairo_get_group_target

This API provides a much more convenient mechanism for doing rendering
to an intermediate surface without the need to manually create a
temporary cairo_surface_t and a temporary cairo_t and clean them up
afterwards.

Backend-specific pkg-config files
---------------------------------
In addition to the original cairo.pc file, cairo will also now install
a pkg-config files for each configured backend, (for example
cairo-pdf.pc, cairo-svg.pc, cairo-xlib.pc, cairo-win32.pc, etc.) this
also includes optional font backends (such as cairo-ft.pc) and the
optional png functionality (cairo-png.pc).

These new pkg-config files should be very convenient for allowing
cairo-using code to easily check for the existing of optional
functionality in cairo without having to write complex rules to grub
through cairo header files or the compiled library looking for
symbols.

Help for drawing disconnected circles
-------------------------------------
A new path-construction function was added which clears the current
point in preparation for a new sub path. This makes it much easier to
use cairo_arc to draw a circular arc that is not connected to the
current path:

    cairo_new_sub_path

Degenerate paths for easier "dots"
----------------------------------
Degenerate paths are now consistently handled in a manner similar to
the PDF specification. This means that round caps can now be used to
easily draw circles (move_to, close_path, stroke), or dotted lines,
(set_dash with a 0 length for on segments).

The following function been added to complement
cairo_surface_set_device_offset:

    cairo_surface_set_fallback_resolution
    cairo_surface_get_content
    cairo_debug_reset_static_data
    cairo_surface_get_device_offset

Type querying functions
-----------------------
There are new get_type functions for querying sub-types of object:

    cairo_surface_get_type
    cairo_pattern_get_type
    cairo_font_face_get_type
    cairo_scaled_font_get_type

Scaled font query/convenience functions
---------------------------------------
More convenience in working with cairo_scaled_font_t with new getter
functions:

    cairo_scaled_font_get_font_face
    cairo_scaled_font_get_font_matrix
    cairo_scaled_font_get_ctm
    cairo_scaled_font_get_font_options

As well as a convenience function for setting a scaled font into a
cairo context:

    cairo_set_scaled_font

and a function to allow text extents to be queried directly from a
scaled font, (without requiring a cairo_surface_t or a cairo_t):

    cairo_scaled_font_text_extents

These new scaled font functions were motivated by the needs of the
pango library.

image backend
-------------
It is now possible to obtain access to the image data of any image
surface with the following new functions:

    cairo_image_surface_get_data
    cairo_image_surface_get_format
    cairo_image_surface_get_stride

xlib backend
------------
Fix potentially big performance bug by making xlib's create_similar
try harder to create a pixmap of a depth matching that of the screen.

Add the following functions to allow the user to extract all the
details of the underlying Xlib drawable from an xlib surface:

    cairo_xlib_surface_get_display
    cairo_xlib_surface_get_drawable
    cairo_xlib_surface_get_screen
    cairo_xlib_surface_get_visual
    cairo_xlib_surface_get_width
    cairo_xlib_surface_get_height
    cairo_xlib_surface_get_depth

win32 backend
-------------
Performance improvements by preferring GDI over pixman rendering when possible.
Fixes for text rendering.

Add a new function to create a font_face for an HFONT:

    cairo_win32_font_face_create_for_hfont

PostScript backend
------------------
We anticipate that with cairo 1.2, toolkits will begin to use cairo
for printing on systems that use PostScript as the spool format. To
support this use case, we have added 4 new function calls that are
specific to the PostScript backend:

    cairo_ps_surface_set_size
        cairo_ps_surface_dsc_comment
        cairo_ps_surface_dsc_begin_setup
        cairo_ps_surface_dsc_begin_page_setup

These functions allow variation of the page size/orientation from one
page to the next in the PostScript output. They also allow the toolkit
to provide per-document and per-page printer control options in a
device-independent way, (for example, by using PPD options and
emitting them as DSC comments into the PostScript output). This should
allow toolkits to provide very fine-grained control of many options
available in printers, (media size, media type, tray selection, etc.).

PDF backend
-----------
The PDF backend also provides capability for per-page size changes,
with the following API:

    cairo_pdf_surface_set_size

There has been a lot of interest in adding additional PDF-specific API
for inserting various kinds of meta-data or other structure into the
PDF output. We have avoided this in 1.2.0 since we don't yet know
exactly what the interface should look like. If you have interest or
knowledge in this area, please share your ideas with us.

SVG backend
-----------
Unlike some earlier, experimental versions of the SVG backend, the SVG
backend in cairo 1.2.0 does not have any dependency on the libxml2
library.

The SVG backend provides flexibility with regard to what version of
SVG it targets. It will target SVG 1.1 by default, which will require
image fallbacks for some of the "fancier" cairo compositing
operators. Or with the following new function calls:

    cairo_svg_surface_restrict_to_version
    cairo_svg_get_versions
    cairo_svg_version_to_string

it can be made to target SVG 1.2 in which there is native support for
these compositing operators.

Optimizations and bug fixes
---------------------------
Shortly after the 1.0 maintenance series branched off the mainline
there was a major rework of the cairo font internals. This should
provide some good performance benefits, but it's also another area
people should look at closely for potential regressions, (thanks to
Federico Mena-Quintero for already pointing out a problem with bitmap
fonts containing a very large number of glyphs).

There has not yet been any widespread, systematic optimization of
cairo, but various performance improvements have been made, (and some
of them are fairly significant). So if some things seem faster than
1.0 then things are good. If there are any performance regressions
compared to 1.0 then there is a real problem and we would like to hear
about that.

Now that 1.2.0 is done, the major focus of the cairo project over the
next few months will be on performance and optimization. We are very
interested in benchmarks demonstrating cairo call sequences that are
of interest to users. Please send your benchmarks to the cairo mailing
list for inclusion in an upcoming automated performance regression
testing environment. Ideally benchmarks should run for a (fairly
short), fixed amount of time, terminate, and print a single number.

There has been a huge number of bug fixes---too many to mention in
detail. Again, things should be better, and never worse compared to
1.0. Please let us know if your testing shows otherwise.

What's new in cairo 1.2.0 compared to 1.1.10
============================================
There has been one API addition since the cairo 1.1.10 snapshot:

    cairo_xlib_surface_get_width
    cairo_xlib_surface_get_height

There's also a new feature without any API change:

    Dots can now be drawn by using CAIRO_LINE_CAP_ROUND with
    degenerate sub-paths, (cairo_move_to() followed by either
    cairo_close_path() or a cairo_line_to() to the same location).

And at least the following bugs have been fixed:

 6759  fontconfig option AntiAlias doesn't work in cairo 1.1.2
 6955  Some characters aren't displayed when using xlib (cache u...
 7268  positive device_offset values don't work as source
 * PDF emit_glyph function needs to support bitmapped glyphs
 * PS emit_glyph function needs to support bitmapped glyphs
 * SVG emit_glyph function needs to support bitmapped glyphs
 * PDF: minefield page one is falling back unnecessarily
 * PS/PDF: Fix broken placement for vertical glyphs
 * PS: Fix to not draw BUTT-capped zero-length dash segments
 * Do device offset before float->fixed conversion
   http://bugzilla.gnome.org/show_bug.cgi?id=332266
 * PS: Fix source surfaces with transformations
 * PS: Fix to not draw BUTT-capped degnerate sub-paths
 * PS: Don't walk off end of array when printing "~>"
 * Fix some memory leaks in the test suite rig
 * SVG: Fix memory leak when using cairo_mask
 * Fix EXTEND_REFLECT and EXTEND_PAD to not crash (though these are
   still not yet fully implemented for surface patterns).