Add checks for Cairo

Sat Jan  8 16:46:37 2005  Owen Taylor  <otaylor@redhat.com>

        * configure.in: Add checks for Cairo

        * pango/Makefile.am: Add libpangocairo.

        * pango/pangocairo-font.c pango/pangocairo-fontmap.c
        pango/pangocairo.h pango/pangocairo-private.h
        pango/pangocairo-fcfont.c pango/pangocairo-fcfontmap.c
        pango/pangocairo-fc.h: Start of a Cairo/FreeType backend.

        * pango/pangofc-fontmap.[ch]: Add a "get_render_key"
        virtual function to allow subclasses to specialize the
        details of how caching works. Add a default implementation
        that's a little more sophisticated than what was there
        before.

        * pango/pangoft2-private.h pangofc-font.c pangoft2.c:
        Move default implementations of has_char(), get_glyph()
        to the base class.

        * pango/pangofc-private.h pango/pangoft2-private.h:
        Move PANGO_UNITS_26_6 and friends to pango/pangofc-private.h.

        * examples/renderdemo.[ch] examples/pangoft2topgm.c
        examples/xftview.c: Allow passing in a custom function
        to transform drawing.

        * examples/Makefile.am examples/cairoview.c: Add a
        Cairo/Xlib example program.

        * examples/cairosimple.c: Simple Cairo example with
        output to a PNG.

        * pango/pango-layout.c (pango_layout_line_get_extents): Fix
        bug where line ink rect was always including 0, 0.

5 files changed, 263 insertions, 6 deletions

diff --git a/docs/tmpl/pango-renderer.sgml b/docs/tmpl/pango-renderer.sgml
index adb8f555..f88a679b 100644
--- a/docs/tmpl/pango-renderer.sgml
+++ b/docs/tmpl/pango-renderer.sgml
@@ -124,12 +124,14 @@ destinations can be created.
 
 @renderer: 
 @part: 
-@y1: 
+@y1_: 
 @x11: 
 @x21: 
 @y2: 
 @x12: 
 @x22: 
+<!-- # Unused Parameters # -->
+@y1: 
 
 
 <!-- ##### FUNCTION pango_renderer_draw_glyph ##### -->
diff --git a/docs/tmpl/pangocairo.sgml b/docs/tmpl/pangocairo.sgml
new file mode 100644
index 00000000..723a4a09
--- /dev/null
+++ b/docs/tmpl/pangocairo.sgml
@@ -0,0 +1,248 @@
+<!-- ##### SECTION Title ##### -->
+Cairo Rendering
+
+<!-- ##### SECTION Short_Description ##### -->
+Rendering with the Cairo backend
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+The <ulink url="http://cairographics.org">Cairo library</ulink> is a
+vector graphics library with a powerful rendering model. It has such
+features as anti-aliased primitives, alpha-compositing, and
+gradients. Multiple backends for Cairo are available, to allow
+rendering to images, to PDF files, and to the screen on X and on other
+windowing systems. The functions in this section allow using Pango
+to render to Cairo surfaces.
+</para>
+<para>
+Using Pango with Cairo is straightforward. A #PangoContext created
+with pango_cairo_font_map_create_context() can be used on any
+Cairo context (cairo_t), but needs to be updated to match the
+current transformation matrix and target surface of the Cairo context
+using pango_cairo_update_context(). The convenience functions
+pango_cairo_create_layout() and pango_cairo_update_layout() handle
+the common case where the program doesn't need to manipulate the
+properties of the #PangoContext.
+</para>
+<para>
+When you get the metrics of a layout or of a piece of a layout using
+functions such as pango_layout_get_extents(), the reported metrics
+are in user-space coordinates. If a piece of text is 10 units long,
+and you call cairo_scale (cr, 2.0), it still is more-or-less 10
+units long. However, the results will be affected by hinting
+(that is, the process of adjusting the text to look good on the
+pixel grid), so you shouldn't assume they are completely independent
+of the current transformation matrix. Note that the basic metrics
+functions in Pango report results in integer Pango units. To get
+to the floating point units used in Cairo divide by %PANGO_SCALE.
+</para>
+<example id="rotated-example">
+<title>Using Pango with Cairo</title>
+<programlisting>
+#include &lt;math.h>
+#include &lt;pango/pangocairo.h>
+
+static void
+draw_text (cairo_t *cr)
+{
+#define RADIUS 150
+#define N_WORDS 10
+#define FONT "Sans Bold 27"
+
+  PangoLayout *layout;
+  PangoFontDescription *desc;
+  int i;
+
+  /* Center coordinates on the middle of the region we are drawing
+   */
+  cairo_translate (cr, RADIUS, RADIUS);
+
+  /* Create a PangoLayout, set the font and text */
+  layout = pango_cairo_create_layout (cr);
+  
+  pango_layout_set_text (layout, "Text", -1);
+  desc = pango_font_description_from_string (FONT);
+  pango_layout_set_font_description (layout, desc);
+  pango_font_description_free (desc);
+
+  /* Draw the layout N_WORDS times in a circle */
+  for (i = 0; i &lt; N_WORDS; i++)
+    {
+      int width, height;
+      double angle = (360. * i) / N_WORDS;
+      double red;
+
+      cairo_save (cr);
+
+      /* Gradient from red at angle == 60 to blue at angle == 300 */
+      red   = (1 + cos ((angle - 60) * G_PI / 180.)) / 2;
+      cairo_set_rgb_color (cr, red, 0, 1.0 - red);
+
+      cairo_rotate (cr, angle * G_PI / 180.);
+    
+      /* Inform Pango to re-layout the text with the new transformation */
+      pango_cairo_update_layout (cr, layout);
+    
+      pango_layout_get_size (layout, &amp;width, &amp;height);
+      cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS);
+      pango_cairo_show_layout (cr, layout);
+
+      cairo_restore (cr);
+    }
+
+  /* free the layout object */
+  g_object_unref (layout);
+}
+
+int main (int argc, char **argv)
+{
+  cairo_t *cr;
+  FILE *f;
+
+  if (argc != 2)
+    {
+      g_printerr ("Usage: cairo-example OUTPUT_FILENAME\n");
+      return 1;
+    }
+
+  f = fopen (argv[1], "w");
+  if (!f)
+    {
+      g_printerr ("Usage: cannot open '%s'\n", argv[1]);
+      return 1;
+    }
+
+  cr = cairo_create();
+  cairo_set_target_png (cr, f,
+			 CAIRO_FORMAT_ARGB32,
+			 2 * RADIUS, 2 * RADIUS);
+
+  cairo_set_rgb_color (cr, 1.0, 1.0, 1.0);
+  cairo_rectangle (cr, 0, 0, 2 * RADIUS, 2 * RADIUS);
+  cairo_fill (cr);
+  draw_text (cr);
+  
+  cairo_destroy (cr);
+  fclose (f);
+
+  return 0;
+}
+</programlisting>
+</example>
+<figure>
+  <title>Output of <xref linkend="rotated-example"/></title>
+  <graphic fileref="rotated-text.png" format="PNG"/>
+</figure>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT PangoCairoFontMap ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION pango_cairo_font_map_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_cairo_font_map_get_default ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_cairo_font_map_set_resolution ##### -->
+<para>
+
+</para>
+
+@fontmap: 
+@dpi: 
+<!-- # Unused Parameters # -->
+@dpi_x: 
+@dpi_y: 
+
+
+<!-- ##### FUNCTION pango_cairo_font_map_get_resolution ##### -->
+<para>
+
+</para>
+
+@fontmap: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_cairo_font_map_create_context ##### -->
+<para>
+
+</para>
+
+@fontmap: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_cairo_update_context ##### -->
+<para>
+
+</para>
+
+@cr: 
+@context: 
+
+
+<!-- ##### FUNCTION pango_cairo_create_layout ##### -->
+<para>
+
+</para>
+
+@cr: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_cairo_update_layout ##### -->
+<para>
+
+</para>
+
+@cr: 
+@layout: 
+
+
+<!-- ##### FUNCTION pango_cairo_show_glyphs ##### -->
+<para>
+
+</para>
+
+@cr: 
+@font: 
+@glyphs: 
+
+
+<!-- ##### FUNCTION pango_cairo_show_layout_line ##### -->
+<para>
+
+</para>
+
+@cr: 
+@line: 
+
+
+<!-- ##### FUNCTION pango_cairo_show_layout ##### -->
+<para>
+
+</para>
+
+@cr: 
+@layout: 
+
+
diff --git a/docs/tmpl/pangofc-fontmap.sgml b/docs/tmpl/pangofc-fontmap.sgml
index db72b732..4f919ca3 100644
--- a/docs/tmpl/pangofc-fontmap.sgml
+++ b/docs/tmpl/pangofc-fontmap.sgml
@@ -44,6 +44,7 @@ Fontconfig-based backend involves deriving from both
 
 @default_substitute: 
 @new_font: 
+@get_render_key: 
 
 <!-- ##### FUNCTION pango_fc_font_description_from_pattern ##### -->
 <para>
diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml
index ecbf7d9e..7c5fa9da 100644
--- a/docs/tmpl/text-attributes.sgml
+++ b/docs/tmpl/text-attributes.sgml
@@ -47,6 +47,7 @@ attribute is listed in parentheses after the description.
 @PANGO_ATTR_LETTER_SPACING: 
 @PANGO_ATTR_UNDERLINE_COLOR: 
 @PANGO_ATTR_STRIKETHROUGH_COLOR: 
+@PANGO_ATTR_ABSOLUTE_SIZE: 
 
 <!-- ##### MACRO PANGO_TYPE_ATTR_TYPE ##### -->
 <para>
@@ -151,12 +152,17 @@ impose shape restrictions.
 
 <!-- ##### STRUCT PangoAttrSize ##### -->
 <para>
-
+The #PangoAttrShape structure is used to represent attributes which
+set font size.
 </para>
 
-@attr: 
-@size: 
-@absolute: 
+@attr: the common portion of the attribute
+@size: size of font, in units of 1/PANGO_SCALE of a point (for
+  PANGO_ATTR_SIZE) or of a device uni (for PANGO_ATTR_ABSOLUTE_SIZE)
+@absolute: whether the font size is in device units or points.
+   This field is only present for compatibility with Pango-1.8.0
+   (PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will
+   be %FALSE for PANGO_ATTR_SIZE and %TRUE for PANGO_ATTR_ABSOLUTE_SIZE.
 
 <!-- ##### FUNCTION pango_parse_markup ##### -->
 <para>
diff --git a/docs/tmpl/xft-fonts.sgml b/docs/tmpl/xft-fonts.sgml
index 50a6e02a..fc4d6cae 100644
--- a/docs/tmpl/xft-fonts.sgml
+++ b/docs/tmpl/xft-fonts.sgml
@@ -10,7 +10,7 @@ The Xft library is a library for displaying fonts on the X window
 system; internally it uses the fontconfig library to locate font
 files, and the FreeType library to load and render fonts. The
 Xft backend is the recommended Pango font backend for screen
-display with X.
+display with X. (The <link linkend="pango-Cairo-Rendering">Cairo back end</link> is another possibility.)
 </para>
 <para>
 Using the Xft backend is generally straightforward;