[cairo-commit] cairo/doc/reference/xml cairo_current_font.xml, 1.2, 1.3 cairo_font_glyph_extents.xml, NONE, 1.1 cairo_font_t.xml, NONE, 1.1 cairo_ft_font_create.xml, NONE, 1.1 cairo_ft_font_create_for_ft_face.xml, NONE, 1.1 cairo_ft_font_get_pattern.xml, NONE, 1.1 cairo_ft_font_lock_face.xml, NONE, 1.1 cairo_ft_font_unlock_face.xml, NONE, 1.1 cairo_glyph_t.xml, NONE, 1.1 cairo_matrix_t.xml, 1.1, 1.2 cairo_set_font.xml, 1.2, 1.3 cairo_show_glyphs.xml, 1.2, 1.3 cairo_text_extents_t.xml, 1.1, 1.2

Owen Taylor commit at pdx.freedesktop.org
Fri Jan 21 14:33:50 PST 2005


Committed by: otaylor

Update of /cvs/cairo/cairo/doc/reference/xml
In directory gabe:/tmp/cvs-serv3974/doc/reference/xml

Modified Files:
	cairo_current_font.xml cairo_matrix_t.xml cairo_set_font.xml 
	cairo_show_glyphs.xml cairo_text_extents_t.xml 
Added Files:
	cairo_font_glyph_extents.xml cairo_font_t.xml 
	cairo_ft_font_create.xml cairo_ft_font_create_for_ft_face.xml 
	cairo_ft_font_get_pattern.xml cairo_ft_font_lock_face.xml 
	cairo_ft_font_unlock_face.xml cairo_glyph_t.xml 
Log Message:
2005-01-16  Owen Taylor  <otaylor at redhat.com>

        Change cairo_font_t to refer to a font scaled to a particular
        output device resolution.

        * src/cairoint.h src/cairo_font.c src/cairo_ft_font.c
        src/cairo_xlib_surface.c src/cairo_pdf_surface.c src/cairo_gstate.c
        src/cairo.c: Switch many internal methods from handling
        cairo_unscaled_font_t and cairo_font_scale_t pairs to handling
        cairo_font_t.

        * src/cairo-ft-private.h src/cairo_ft_fontc: Add some internal
        interfaces for use by the FreeType backend.

        * src/cairo_gstate.c: Clear the gstate's current font when
        the transform or target surface changes.

        * src/cairo.h src/cairo_ft_font.c: Rename cairo_ft_font_pattern
        to cairo_ft_font_get_pattern().

        * src/cairo.h src/cairo_ft_font.c: Make cairo_ft_font_create()
        and cairo_ft_font_create_for_ft_face() take a font scale;
        make the latter take load_flags for FT_Load_Glyph() as well.
        Change cairo_ft_font_face() to Xft-style cairo_ft_font_lock_face,
        cairo_ft_font_unlock_face.

        * src/cairo_font.c: Remove the name/slant/weight=>unscaled font
        cache, it didn't work with the new cairo_font_t setup. If it turns
        out to be needed, it can be added back in some other form.

        * src/cairoint.h src/cairo_font.c: Add a 'flags' field
        to cairo_glyph_cache_key_t, we use it for load flags with
        freetype backend.

        * src/cairo_ft_font.c: Switch the caching to be from
        resolved fontconfig pattern => file; keep only a fixed number
        of FT_Face objects open at once, similar to FreeType.

        * src/cairo_font.c (cairo_font_glyph_extents) src/cairo_gstate.c
        src/cairoint.h: Add public cairo_font_glyph_extents, use it
        to implement _cairo_gstate_glyph_extents().

        * src/cairo_xlib_surface.c (_glyphset_cache_entry_reference):
        Add refcounting for glyph cache elements; there was an
        bug where elements got ejected from the cache and freed before
        they could be used.

        * src/cairoint.h src/cairo_cache.c (_cairo_cache_random_entry())
        New function to return a random entry in the cache matching a predicate;
        reuse the internals for the previous _random_live_entry().

        * src/cairoint.h src/cairo_cache.c (_cairo_cache_lookup()): Add an
        optional created_entry return value.

        * src/cairo_ft_font.c src/cairo_xlib_surface.c: Adapt to
        _cairo_cache_lookup() change.

        * src/cairo_cache.c (_cairo_cache_lookup()): Support max_memory == 0
        to indicate an unbounded cache.

        * src/cairoint.h src/cairo_cache.c (_cairo_cache_remove()): Add a
        function to manually remove entries from the cache.

        * doc/reference: Update for changes, document cairo_matrix_t,
        cairo_glyph_t, etc.

        * src/cairo.h src/cairo-atsui.h src/cairo-ft.h src/cairo-glitz.h
        src/cairo-pdf.h src/cairo-png.h src/cairo-ps.h src/cairo-quartz.h
        src/cairo-xcb.h src/cairo-xlib.h: Add CAIRO_BEGIN/END_DECLS for
        extern "C", use it on all public headers. Move header guards
        outermost.

        * src/cairo_quartz_surface.c: Fix encoding.


Index: cairo_current_font.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_current_font.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- cairo_current_font.xml	20 Feb 2004 22:23:17 -0000	1.2
+++ cairo_current_font.xml	21 Jan 2005 22:33:47 -0000	1.3
@@ -10,7 +10,7 @@
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
-      cairo_font_t *
+      <link linkend="cairo_font_t">cairo_font_t</link> *
     cairo_current_font (<link linkend="cairo_t">cairo_t</link> *cr)</programlisting>
     <variablelist role="params">
       <varlistentry>
@@ -31,7 +31,7 @@
       <indexterm>
         <primary/>
       </indexterm>
-      returns pointer to the  current cairo_font_t object in the <link linkend="cairo_t">cairo_t</link>
+      returns pointer to the  current <link linkend="cairo_font_t">cairo_font_t</link> object in the <link linkend="cairo_t">cairo_t</link>
     </para>
   </refsect1>
 </refentry>

--- NEW FILE: cairo_font_glyph_extents.xml ---

<refentry id="cairo_font_glyph_extents">
  <refmeta>
    <refentrytitle>cairo_font_glyph_extents</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>cairo_font_glyph_extents</refname>
    <refpurpose>Gets the metrics for a string of glyphs</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <programlisting>
<structname>void </structname> cairo_font_glyph_extents (<link linkend="cairo_font_t">cairo_font_t</link> *font, <link linkend="cairo_matrix_t">cairo_matrix_t</link> *font_matrix, <link linkend="cairo_glyph_t">cairo_glyph_t</link> *glyphs, int num_glyphs, <link linkend="cairo_text_extents_t">cairo_text_extents_t</link> *extents)</programlisting>
    <variablelist role="params">
      <varlistentry>
        <term><parameter>font</parameter> :</term>
        <listitem>
          <simpara>A <link linkend="cairo_font_t">cairo_font_t</link>.
	  </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter>font_matrix</parameter> :</term>
        <listitem>
          <simpara>
	    The font transformation for which this font was
	    created. (See <link linkend="cairo_transform_font">cairo_transform_font</link>.) This is needed
	    properly convert the metrics from the font into user space.
	  </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter>glyphs</parameter> :</term>
        <listitem>
          <simpara>
	    An array of glyph IDs with x and y offsets.
	  </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter>num_glyphs</parameter> :</term>
        <listitem>
          <simpara>
	    The number of glyphs in the <parameter>glyphs</parameter> array.
	  </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter>extents</parameter> :</term>
        <listitem>
          <simpara>
	    A <link linkend="cairo_text_extents_t">cairo_text_extents_t</link> in which to store the retrieved extents.
	  </simpara>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsynopsisdiv>
  <refsect1>
    <title>Description</title>
    <para>
      <indexterm>
        <primary>functions</primary>
        <secondary>cairo_font_glyph_extents</secondary>
      </indexterm>
      <indexterm>
        <primary/>
      </indexterm>
      <function>cairo_font_glyph_extents</function> gets the metrics
      for a string of glyphs. 
    </para>
  </refsect1>
</refentry>

--- NEW FILE: cairo_font_t.xml ---
<refentry id="cairo_font_t">
  <refmeta>
    <refentrytitle>cairo_font_t</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>
  
  <refnamediv>
    <refname>cairo_font_t</refname>
    <refpurpose>scaled font object</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Description</title>
    <para><indexterm><primary>types</primary><secondary>cairo_font_t</secondary></indexterm>
      A <structname>cairo_font_t</structname> is a font scaled to a
      particular size and device resolution. A font can be set on a
      <link linkend="cairo_t">cairo_t</link> by using <link linkend="cairo_set_font">cairo_set_font</link>, assuming that the
      current transformation and target surface of the
      <structname><link linkend="cairo_t">cairo_t</link></structname> match that for which the
      <structname>cairo_font_t</structname> was created. The effect of
      using a mismatched <structname>cairo_font_t</structname> will be
      incorrect font metrics. 
    </para>
  </refsect1>
</refentry>

--- NEW FILE: cairo_ft_font_create.xml ---

<refentry id="cairo_ft_font_create">
  <refmeta>
    <refentrytitle>cairo_ft_font_create</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>cairo_ft_font_create</refname>
    <refpurpose>creates a font for the FreeType font backend</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <programlisting>
<link linkend="cairo_font_t">cairo_font_t</link> *cairo_ft_font_create (FcPattern *pattern, <link linkend="cairo_matrix_t">cairo_matrix_t</link> *scale)</programlisting>
    <variablelist role="params">
      <varlistentry>
        <term><parameter>pattern</parameter> :</term>
        <listitem>
          <simpara>A fully resolved fontconfig pattern. A pattern can
	    be resolved, by, among other things, calling <function>FcConfigSubstitute</function>,
	    <function>FcDefaultSubstitute</function>, then
	    <function>FcFontMatch</function>. Cairo will call
	    <function>FcPatternReference</function> on this pattern, so you should not
	    further modify the pattern, but you can release your
	    reference to the pattern with <function>FcPatternDestroy</function> if you
	    no longer need to access it.
	  </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter>scale</parameter> :</term>
        <listitem>
          <simpara>The scale at which this font will be used. The
	    scale is given by multiplying the font matrix (see
	    <link linkend="cairo_transform_font">cairo_transform_font</link>)
	    by the current transformation matrix. The translation
	    elements of the resulting matrix are ignored.
	  </simpara>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsynopsisdiv>
  <refsect1>
    <title>Description</title>
    <para>
      <indexterm>
        <primary>functions</primary>
        <secondary>cairo_ft_font_create</secondary>
      </indexterm>
      <indexterm>
        <primary/>
      </indexterm>
      <function>cairo_ft_font_create</function> creates a new font for
      the FreeType font backend based on a fontconfig pattern. This
      font can then be used with <link linkend="cairo_set_font">cairo_set_font</link>,
      <link linkend="cairo_font_glyph_extents">cairo_font_glyph_extents</link>, or FreeType backend specific functions
      like <link linkend="cairo_ft_font_lock_face">cairo_ft_font_lock_face</link>.
    </para>
  </refsect1>
</refentry>

--- NEW FILE: cairo_ft_font_create_for_ft_face.xml ---

<refentry id="cairo_ft_font_create_for_ft_face">
  <refmeta>
    <refentrytitle>cairo_ft_font_create_for_ft_face</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>cairo_ft_font_create_for_ft_face</refname>
    <refpurpose>creates a font for the FreeType font backend from a
      pre-opened FreeType face</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <programlisting>
<link linkend="cairo_font_t">cairo_font_t</link> *cairo_ft_font_create_for_ft_face (FT_Face face, int load_flags, <link linkend="cairo_matrix_t">cairo_matrix_t</link> *scale)</programlisting>
    <variablelist role="params">
      <varlistentry>
        <term><parameter>face</parameter> :</term>
        <listitem>
          <simpara>A FreeType face object, already opened. This must
          be kept around until the font object's refcount drops to
          zero and it is freed. The font object can be kept alive by
          internal caching, so it's safest to keep the face object
          around forever.
	  </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter>load_flags</parameter> :</term>
        <listitem>
          <simpara>The flags to pass to <function>FT_Load_Glyph</function> when loading
          glyphs from the font. These flags control aspects of
          rendering such as hinting and antialiasing. See the FreeType
          docs for full information.
	  </simpara>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><parameter>scale</parameter> :</term>
        <listitem>
          <simpara>The scale at which this font will be used. The
	    scale is given by multiplying the font matrix (see
	    <link linkend="cairo_transform_font">cairo_transform_font</link>)
	    by the current transformation matrix.  The translation
	    elements of the resulting transformation are ignored.</simpara>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsynopsisdiv>
  <refsect1>
    <title>Description</title>
    <para>
      <indexterm>
        <primary>functions</primary>
        <secondary>cairo_ft_font_create_for_ft_face</secondary>
      </indexterm>
      <indexterm>
        <primary/>
      </indexterm>
      <function>cairo_ft_font_create_for_ft_face</function> creates a new font for
      the FreeType font backend from a pre-opened FreeType face. This
      font can then be used with <link linkend="cairo_set_font">cairo_set_font</link>,
      <link linkend="cairo_font_glyph_extents">cairo_font_glyph_extents</link>, or FreeType backend specific functions
      like <link linkend="cairo_ft_font_lock_face">cairo_ft_font_lock_face</link>. Cairo will determine the pixel
      size and transformation from the <parameter>scale</parameter> parameter
      and call <function>FT_Set_Transform</function> and
      <function>FT_Set_Pixel_Sizes</function>.
    </para>
  </refsect1>
</refentry>

--- NEW FILE: cairo_ft_font_get_pattern.xml ---

<refentry id="cairo_ft_font_get_pattern">
  <refmeta>
    <refentrytitle>cairo_ft_font_get_pattern</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>cairo_ft_font_get_pattern</refname>
    <refpurpose>Gets the <structname>FcPattern</structname> for a FreeType
      backend font</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <programlisting>
<structname>FcPattern *</structname> cairo_ft_font_get_pattern
      (<link linkend="cairo_font_t">cairo_font_t</link> *font)</programlisting>
    <variablelist role="params">
      <varlistentry>
        <term><parameter>font</parameter> :</term>
        <listitem>
          <simpara>A <link linkend="cairo_font_t">cairo_font_t</link> from the FreeType font backend. Such
	    an object can be created with <link linkend="cairo_ft_font_create">cairo_ft_font_create</link> or
	    <link linkend="cairo_ft_font_create_for_ft_face">cairo_ft_font_create_for_ft_face</link>. On some platforms the font
	    from <link linkend="cairo_current_font">cairo_current_font</link> will also be a FreeType font, but
	    using this functionality with fonts you don't create
	    yourself is not recommended.
	  </simpara>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsynopsisdiv>
  <refsect1>
    <title>Description</title>
    <para>
      <indexterm>
        <primary>functions</primary>
        <secondary>cairo_ft_font_get_pattern</secondary>
      </indexterm>
      <indexterm>
        <primary/>
      </indexterm>
      <function>cairo_ft_font_get_pattern</function> gets the <structname>FcPattern</structname>
      for a FreeType backend font. The return value is owned
      by the font, so you must not modify it, and must call
      <function>FcPatternReference</function> to keep a persistant
      reference to the pattern. If the font was created with
      <link linkend="cairo_ft_font_create_for_ft_face">cairo_ft_font_create_for_ft_face</link> the result will be NULL.
    </para>
  </refsect1>
</refentry>

--- NEW FILE: cairo_ft_font_lock_face.xml ---

<refentry id="cairo_ft_font_lock_face">
  <refmeta>
    <refentrytitle>cairo_ft_font_lock_face</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>cairo_ft_font_lock_face</refname>
    <refpurpose>Gets the <structname>FT_Face</structname> from a FreeType
      backend font</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <programlisting>
<structname>FT_Face</structname> cairo_ft_font_lock_face (<link linkend="cairo_font_t">cairo_font_t</link> *font)</programlisting>
    <variablelist role="params">
      <varlistentry>
        <term><parameter>font</parameter> :</term>
        <listitem>
          <simpara>A <link linkend="cairo_font_t">cairo_font_t</link> from the FreeType font backend. Such
	    an object can be created with <link linkend="cairo_ft_font_create">cairo_ft_font_create</link> or
	    <link linkend="cairo_ft_font_create_for_ft_face">cairo_ft_font_create_for_ft_face</link>. On some platforms the font
	    from <link linkend="cairo_current_font">cairo_current_font</link> will also be a FreeType font, but
	    using this functionality with fonts you don't create
	    yourself is not recommended.
	  </simpara>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsynopsisdiv>
  <refsect1>
    <title>Description</title>
    <para>
      <indexterm>
        <primary>functions</primary>
        <secondary>cairo_ft_font_lock_face</secondary>
      </indexterm>
      <indexterm>
        <primary/>
      </indexterm>
      <function>cairo_ft_font_lock_face</function> gets the <structname>FT_Face</structname>
      object from a FreeType backend font and scales it appropriately
      for the font. You must release the face with
      <link linkend="cairo_ft_font_unlock_face">cairo_ft_font_unlock_face</link> when you are done using it.
      Since the <structname>FT_Face</structname> object can be shared
      between multiple <link linkend="cairo_font_t">cairo_font_t</link> objects, you must not lock any
      other font objects until you unlock this one. A count is kept of
      the number of times <function>cairo_ft_font_lock_face</function>
      is called. <link linkend="cairo_ft_font_unlock_face">cairo_ft_font_unlock_face</link> must be called the same
      number of times.
    </para>
    <para>
      You must be careful when using this function in a library or in
      a threaded application, because other threads may lock faces
      that share the same <structname>FT_Face</structname> object. For
      this reason, you must call cairo_ft_lock before locking any face
      objects, and cairo_ft_unlock after you are done. (These
      functions are not yet implemented, so this function cannot be
      currently safely used in a threaded application.)
    </para>
  </refsect1>
</refentry>

--- NEW FILE: cairo_ft_font_unlock_face.xml ---

<refentry id="cairo_ft_font_unlock_face">
  <refmeta>
    <refentrytitle>cairo_ft_font_unlock_face</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>cairo_ft_font_unlock_face</refname>
    <refpurpose>Releases the <structname>FT_Face</structname> from a FreeType
      backend font</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <programlisting>
      void cairo_ft_font_unlock_face (<link linkend="cairo_font_t">cairo_font_t</link> *font)</programlisting>
    <variablelist role="params">
      <varlistentry>
        <term><parameter>font</parameter> :</term>
        <listitem>
          <simpara>A <link linkend="cairo_font_t">cairo_font_t</link> from the FreeType font backend. Such
	    an object can be created with <link linkend="cairo_ft_font_create">cairo_ft_font_create</link> or
	    <link linkend="cairo_ft_font_create_for_ft_face">cairo_ft_font_create_for_ft_face</link>. On some platforms the font
	    from <link linkend="cairo_current_font">cairo_current_font</link> will also be a FreeType font, but
	    using this functionality with fonts you don't create
	    yourself is not recommended.
	  </simpara>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsynopsisdiv>
  <refsect1>
    <title>Description</title>
    <para>
      <indexterm>
        <primary>functions</primary>
        <secondary>cairo_ft_font_unlock_face</secondary>
      </indexterm>
      <indexterm>
        <primary/>
      </indexterm>
      Releases a face obtained with <link linkend="cairo_ft_font_lock_face">cairo_ft_font_lock_face</link>. See the
      documentation for that function for full details.
    </para>
  </refsect1>
</refentry>

--- NEW FILE: cairo_glyph_t.xml ---

<refentry id="cairo_glyph_t">
  <refmeta>
    <refentrytitle>cairo_glyph_t</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>cairo_glyph_t</refname>
    <refpurpose>struct holding information about a glyph</refpurpose>
  </refnamediv>
  <refsect1>
    <title>Description</title>
    <para><indexterm><primary>types</primary><secondary>cairo_glyph_t</secondary></indexterm><indexterm><primary/></indexterm>
    <programlisting>
      typedef struct {
      double index;
      double x;
      double y;
      } cairo_glyph_t;
    </programlisting>
    </para>
    <para>
      The <structname>cairo_glyph_t</structname> structure holds
      information about a single glyph when drawing or measuring
      text. A font is (in simple terms) a collection of shapes used to
      draw text. A glyph is one of these shapes. There can be multiple
      glyphs for a single character (alternates to be used in
      different contexts, for example), or a glyph can be a
      <firstterm>ligature</firstterm> of multiple characters. Cairo
      doesn't expose any way of converting input text into glyphs, so
      in order to use the Cairo interfaces that take arrays of glyphs,
      you must directly access the appropriate underlying font system.
    </para>
    <variablelist role="struct">
      <varlistentry>
	<term><structfield>index</structfield></term>
	<listitem><simpara>glyph index in the font. The exact
	    interpretation of the glyph index depends on the font
	    technology being used.
	  </simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><structfield>x</structfield></term>
	<listitem><simpara>the offset in the x direction between the
	    origin used for drawing or measuring the string and the
	    origin of this glyph. These offsets are not cumulative; each
	    glyph is indiviually positioned with respect to the
	    overall origin.
	  </simpara></listitem>
      </varlistentry>
      <varlistentry>
	<term><structfield>y</structfield></term>
	<listitem><simpara>the offset in the y direction between the
	    origin used for drawing or measuring the string and the
	    origin of this glyph. These offsets are not cumulative; each
	    glyph is indiviually positioned with respect to the
	    overall origin.
	  </simpara></listitem>
      </varlistentry>
    </variablelist>      
  </refsect1>
</refentry>

Index: cairo_matrix_t.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_matrix_t.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- cairo_matrix_t.xml	19 Oct 2003 15:46:21 -0000	1.1
+++ cairo_matrix_t.xml	21 Jan 2005 22:33:47 -0000	1.2
@@ -11,13 +11,23 @@
   <refsect1>
     <title>Description</title>
     <para><indexterm><primary>types</primary><secondary>cairo_matrix</secondary></indexterm><indexterm><primary/></indexterm>
-      A <varname>cairo_matrix</varname> contains the current state of the rendering device, 
-      including coordinates of yet to be drawn shapes.  
-      <varname>cairo_matrix</varname>'s can be pushed to a stack via 
-      <link linkend="cairo_save">cairo_save</link>. 
-      They may then savely be changed, without loosing the current state. 
-      Use <link linkend="cairo_restore">cairo_restore</link> to 
-      restore to the saved state.
+      <structname>cairo_matrix_t</structname>  is used throughout
+      Cairo to represents between different coordinates spaces.
+      A <structname>cairo_matrix</structname> holds an affine
+      transformation, such as a scale, rotation, or shear, or a
+      combination of those. Mathematically, the effect of an affine
+      transformation on a point (<literal>x</literal>,<literal>y</literal>) is given by:
+    </para>
+    <programlisting>
+      x_new = x * a + y * c + tx;
+      y_new = x * b + y * d + ty;
+    </programlisting>
+    <para>
+      The paramaters <literal>a</literal>, <literal>b</literal>,
+      <literal>c</literal>, <literal>d</literal>,
+      <literal>tx</literal>, <literal>ty</literal> can be retrieved
+      with cairo_matrix_get_affine and set with
+      cairo_matrix_get_affine.
     </para>
   </refsect1>
 </refentry>

Index: cairo_set_font.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_set_font.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- cairo_set_font.xml	20 Feb 2004 22:23:17 -0000	1.2
+++ cairo_set_font.xml	21 Jan 2005 22:33:47 -0000	1.3
@@ -9,7 +9,7 @@
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
-void cairo_set_font (<link linkend="cairo_t">cairo_t</link> *cr, cairo_font_t *font)</programlisting>
+void cairo_set_font (<link linkend="cairo_t">cairo_t</link> *cr, <link linkend="cairo_font_t">cairo_font_t</link> *font)</programlisting>
     <variablelist role="params">
       <varlistentry>
         <term><parameter>cr</parameter> :</term>
@@ -20,7 +20,7 @@
       <varlistentry>
         <term><parameter>font</parameter> :</term>
         <listitem>
-          <simpara>replaces the current cairo_font_t object in the <link linkend="cairo_t">cairo_t</link> with font. The replaced font in the <link linkend="cairo_t">cairo_t</link> will be destroyed if there are no other references to it.</simpara>
+          <simpara>a <link linkend="cairo_font_t">cairo_font_t</link></simpara>
         </listitem>
       </varlistentry>
     </variablelist>
@@ -35,6 +35,18 @@
       <indexterm>
         <primary/>
       </indexterm>
+      Replaces the current <link linkend="cairo_font_t">cairo_font_t</link> object in the <link linkend="cairo_t">cairo_t</link> with font. The replaced font in
+      the <link linkend="cairo_t">cairo_t</link> will be destroyed if
+      there are no other references to it. Since a <link linkend="cairo_font_t">cairo_font_t</link> is
+      specific to a particular output device and size, changing the
+      transformation, font transformation, or target surfaces of a
+      <structname><link linkend="cairo_t">cairo_t</link></structname>
+      will clear any previously set font. Setting the font using
+      <function>cairo_set_font</function> is exclusive with the
+      simple font selection API provided by <link linkend="cairo_select_font">cairo_select_font</link>. The
+      size and transformation set by <link linkend="cairo_scale_font">cairo_scale_font</link>() and
+      <link linkend="cairo_transform_font">cairo_transform_font</link>() are ignored unless they were taken into
+      account when creating <parameter>font</parameter>.
     </para>
   </refsect1>
 </refentry>

Index: cairo_show_glyphs.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_show_glyphs.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- cairo_show_glyphs.xml	20 Feb 2004 22:23:17 -0000	1.2
+++ cairo_show_glyphs.xml	21 Jan 2005 22:33:47 -0000	1.3
@@ -9,7 +9,7 @@
   </refnamediv>
   <refsynopsisdiv>
     <programlisting>
-void cairo_show_glyphs (<link linkend="cairo_t">cairo_t</link> *cr, cairo_glyph_t *glyphs, int num_glyphs);</programlisting>
+void cairo_show_glyphs (<link linkend="cairo_t">cairo_t</link> *cr, <link linkend="cairo_glyph_t">cairo_glyph_t</link> *glyphs, int num_glyphs);</programlisting>
     <variablelist role="params">
       <varlistentry>
         <term><parameter>cr</parameter> :</term>

Index: cairo_text_extents_t.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_text_extents_t.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- cairo_text_extents_t.xml	26 Feb 2004 22:32:12 -0000	1.1
+++ cairo_text_extents_t.xml	21 Jan 2005 22:33:47 -0000	1.2
@@ -23,7 +23,54 @@
     </programlisting>
     </para>
     <para>
-      XXX. not sure what the status is right know.
+      The <structname>cairo_text_extents_t</structname> structure
+      stores the extents of a single glyph or a string of glyphs in
+      user-space coordinates. Because text extents are in user-space
+      coordinates, they don't scale along with the current
+      transformation matrix. If you call <link linkend="cairo_scale">cairo_scale</link>(cr, 2.0, 2.0),
+      text will be drawn twice as big, but the reported text extents
+      will not be doubled. They will change slightly due to hinting
+      (so you can't assume that metrics are independent of the
+      transformation matrix), but otherwise will remain unchanged.
     </para>
+    <variablelist role="struct">
+      <varlistentry>
+	<term><structfield>x_bearing</structfield></term>
+	<listitem><simpara>the horizontal distance from the origin to the
+	    leftmost part of the glyphs as drawn. Positive if the
+	    glyphs lie entirely to the right of the origin.
+	  </simpara></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><structfield>y_bearing</structfield></term>
+	<listitem><simpara>the vertical distance from the origin to the
+	    topmost part of the glyphs as drawn. Positive only if the
+	    glyphs lie completely below the origin; will usually be negative.
+	  </simpara></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><structfield>width</structfield></term>
+	<listitem><simpara>width of the glyphs as drawn.
+	  </simpara></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><structfield>height</structfield></term>
+	<listitem><simpara>height of the glyphs as drawn.
+	  </simpara></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><structfield>x_advance</structfield></term>
+	<listitem><simpara>distance to advance in the X direction
+	    after drawing these glyphs.
+	  </simpara></listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><structfield>y_advance</structfield></term>
+	<listitem><simpara>distance to advance in the Y direction
+	    after drawing these glyphs. Will typically be zero except
+	    for vertical text layout as found in East-Asian languages.
+	  </simpara></listitem>
+      </varlistentry>
+    </variablelist>      
   </refsect1>
 </refentry>




More information about the cairo-commit mailing list