[cairo-commit] 6 commits - configure.in src/cairo.h src/cairo-user-font.c

Behdad Esfahbod behdad at kemper.freedesktop.org
Thu Jun 5 20:09:56 PDT 2008


 configure.in          |   10 +--
 src/cairo-user-font.c |   59 ++++++++++---------
 src/cairo.h           |  155 ++++++++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 182 insertions(+), 42 deletions(-)

New commits:
commit 06b15d2f2da2ffd841a6a88c9713424d416d7388
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Thu Jun 5 22:58:57 2008 -0400

    [doc] Document user-font callback types

diff --git a/src/cairo.h b/src/cairo.h
index ff84968..b00420c 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -1290,19 +1290,152 @@ cairo_user_font_face_create (void);
 
 /* User-font method signatures */
 
+/**
+ * cairo_user_scaled_font_init_func_t:
+ * @scaled_font: the scaled-font being created
+ * @extents: font extents to fill in, in font space
+ *
+ * #cairo_user_scaled_font_init_func_t is the type of function which is
+ * called when a scaled-font needs to be created for a user font-face.
+ *
+ * The @extents argument is where the user font sets the font extents for
+ * @scaled_font.  It is in font space, which means that for most cases its
+ * ascent and descent members should add to 1.0.  @extents is preset to
+ * hold a value of 1.0 for ascent, height, and max_x_advance, and 0.0 for
+ * descent and max_y_advance members.
+ *
+ * The callback is optional.  If not set, default font extents as described
+ * in the previous paragraph will be used.
+ *
+ * Note that @scaled_font is not fully initialized at this
+ * point and trying to use it for text operations in the callback will result
+ * in deadlock.
+ *
+ * Returns: %CAIRO_STATUS_SUCCESS upon success, or
+ * %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
+ *
+ * Returns: the status code of the operation
+ *
+ * Since: 1.8
+ **/
 typedef cairo_status_t (*cairo_user_scaled_font_init_func_t) (cairo_scaled_font_t  *scaled_font,
 							      cairo_font_extents_t *extents);
 
+/**
+ * cairo_user_scaled_font_render_glyph_func_t:
+ * @scaled_font: user scaled-font
+ * @glyph: glyph code to render
+ * @cr: cairo context to draw to, in font space
+ * @extents: glyph extents to fill in, in font space
+ *
+ * #cairo_user_scaled_font_render_glyph_func_t is the type of function which
+ * is called when a user scaled-font needs to render a glyph.
+ *
+ * The callback is mandatory, and expected to draw the glyph with code @glyph to
+ * the cairo context @cr.  @cr is prepared such that the glyph drawing is done in
+ * font space.  That is, the matrix set on @cr is the scale matrix of @scaled_font,
+ * The @extents argument is where the user font sets the font extents for
+ * @scaled_font.  However, if user prefers to draw in user space, they can
+ * achieve that by changing the matrix on @cr.  All cairo rendering operations
+ * to @cr are permitted, however, the result is undefined if any source other
+ * than the default source on @cr is used.  That means, glyph bitmaps should
+ * be rendered using cairo_mask() instead of cairo_paint().
+ *
+ * Other non-default settings on @cr include a font size of 1.0 (given that
+ * it is set up to be in font space), and font options corresponding to
+ * @scaled_font.
+ *
+ * The @extents argument is preset to have <literal>x_bearing</literal>,
+ * <literal>width</literal>, and <literal>y_advance</literal> of zero,
+ * <literal>y_bearing</literal> set to <literal>-font_extents.ascent</literal>,
+ * <literal>height</literal> to <literal>font_extents.ascent+font_extents.descent</literal>,
+ * and <literal>x_advance</literal> to <literal>font_extents.max_x_advance</literal>.
+ * The only field user needs to set in majority of cases is
+ * <literal>x_advance</literal>.
+ * If the <literal>width</literal> field is zero upon the callback returning
+ * (which is its preset value), the glyph extents are automatically computed
+ * based on the drawings done to @cr.  This is in most cases exactly what the
+ * desired behavior is.  However, if for any reason the callback sets the
+ * extents, it must be ink extents, and include the extents of all drawing
+ * done to @cr in the callback.
+ *
+ * Returns: %CAIRO_STATUS_SUCCESS upon success, or
+ * %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
+ *
+ * Since: 1.8
+ **/
 typedef cairo_status_t (*cairo_user_scaled_font_render_glyph_func_t) (cairo_scaled_font_t  *scaled_font,
 								      unsigned long         glyph,
 								      cairo_t              *cr,
 								      cairo_text_extents_t *extents);
 
+/**
+ * cairo_user_scaled_font_text_to_glyphs_func_t:
+ * @scaled_font: the scaled-font being created
+ * @utf8: input string of text, encoded in UTF-8
+ * @glyphs: output array of glyphs, in font space
+ * @num_glyphs: number of output glyphs
+ *
+ * #cairo_user_scaled_font_text_to_glyphs_func_t is the type of function which
+ * is called to convert input text to an array of glyphs.  This is used by the
+ * cairo_show_text() operation.
+ *
+ * Using this callback the user font has full control on glyphs and their
+ * positions.  That means, it allows for features like ligatures and kerning,
+ * as well as complex <firstterm>shaping</firstterm> required for scripts like
+ * Arabic and Indic.
+ *
+ * The @num_glyphs argument is preset to -1.  The callback should allocate an
+ * array for the resulting glyphs (using malloc()), and populate the glyph indices and
+ * positions (in font space) assuming that the text is to be shown at the
+ * origin.  Cairo will free the glyph array when done with it, no matter what
+ * the return value of the callback is.
+ *
+ * The callback is optional.  If not set, or if @num_glyphs is negative upon
+ * the callback returning (which by default is), the unicode_to_glyph callback
+ * is tried.  See #cairo_user_scaled_font_unicode_to_glyph_func_t.
+ *
+ * Note: The signature and details of this callback is expected to change
+ * before cairo 1.8.0 is released.
+ *
+ * Returns: %CAIRO_STATUS_SUCCESS upon success, or
+ * %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
+ *
+ * Since: 1.8
+ **/
 typedef cairo_status_t (*cairo_user_scaled_font_text_to_glyphs_func_t) (cairo_scaled_font_t   *scaled_font,
 									const char            *utf8,
 									cairo_glyph_t        **glyphs,
 									int                   *num_glyphs);
 
+/**
+ * cairo_user_scaled_font_unicode_to_glyph_func_t:
+ * @scaled_font: the scaled-font being created
+ * @unicode: input unicode character code-point
+ * @glyph_index: output glyph index
+ *
+ * #cairo_user_scaled_font_unicode_to_glyph_func_t is the type of function which
+ * is called to convert an input Unicode character to a single glyph.
+ * This is used by the cairo_show_text() operation.
+ *
+ * This callback is used to provide the same functionality as the
+ * text_to_glyphs callback does (see #cairo_user_scaled_font_text_to_glyphs_func_t)
+ * but has much less control on the output,
+ * in exchange for increased ease of use.  The inherent assumption to using
+ * this callback is that each character maps to one glyph, and that the
+ * mapping is context independent.  It also assumes that glyphs are positioned
+ * according to their advance width.  These mean no ligatures, kerning, or
+ * complex scripts can be implemented using this callback.
+ *
+ * The callback is optional, and only used if text_to_glyphs callback is not
+ * set or fails to return glyphs.  If this callback is not set, an identity
+ * mapping from Unicode code-points to glyph indices is assumed.
+ *
+ * Returns: %CAIRO_STATUS_SUCCESS upon success, or
+ * %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
+ *
+ * Since: 1.8
+ **/
 typedef cairo_status_t (*cairo_user_scaled_font_unicode_to_glyph_func_t) (cairo_scaled_font_t *scaled_font,
 									  unsigned long        unicode,
 									  unsigned long       *glyph_index);
commit 4c17a5ee1155cf2f1465d9b14b625a309bd108a2
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Thu Jun 5 22:58:33 2008 -0400

    [configure.in] Change version to 1.7.1
    
    We branched weeks ago.

diff --git a/configure.in b/configure.in
index b3383a5..2596876 100644
--- a/configure.in
+++ b/configure.in
@@ -6,8 +6,8 @@ dnl			  even => stable series
 dnl For the micro number: odd => in-progress development (from git)
 dnl			  even => tar-file snapshot or release
 m4_define(cairo_version_major, 1)
-m4_define(cairo_version_minor, 6)
-m4_define(cairo_version_micro, 5)
+m4_define(cairo_version_minor, 7)
+m4_define(cairo_version_micro, 1)
 
 AC_INIT([cairo],
       cairo_version_major.cairo_version_minor.cairo_version_micro,
@@ -26,16 +26,16 @@ dnl ===========================================================================
 # libtool shared library version
 
 # Increment if the interface has additions, changes, removals.
-LT_CURRENT=19
+LT_CURRENT=20
 
 # Increment any time the source changes; set to
 # 0 if you increment CURRENT
-LT_REVISION=5
+LT_REVISION=0
 
 # Increment if any interfaces have been added; set to 0
 # if any interfaces have been removed. removal has
 # precedence over adding, so set to 0 if both happened.
-LT_AGE=17
+LT_AGE=18
 
 dnl ===========================================================================
 
commit a87c94d24774b79e4bc51fc6814558ed4aa1ab77
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Thu Jun 5 19:29:47 2008 -0400

    [user-font] Add XXX mark for text_to_glyphs memory allocation issue

diff --git a/src/cairo-user-font.c b/src/cairo-user-font.c
index 8d59c38..e4a72c6 100644
--- a/src/cairo-user-font.c
+++ b/src/cairo-user-font.c
@@ -267,6 +267,7 @@ _cairo_user_text_to_glyphs (void           *abstract_font,
 	*glyphs = NULL;
 	*num_glyphs = -1;
 
+	/* XXX currently user allocs glyphs array but cairo frees it */
 	status = face->scaled_font_methods.text_to_glyphs (&scaled_font->base,
 							   utf8, glyphs, num_glyphs);
 
commit adcfe8335629e76f2ad12432d90d94fec12871c0
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Thu Jun 5 19:19:27 2008 -0400

    [user-font] Reorder methods to the order they should appear in docs

diff --git a/src/cairo-user-font.c b/src/cairo-user-font.c
index a09343d..8d59c38 100644
--- a/src/cairo-user-font.c
+++ b/src/cairo-user-font.c
@@ -534,12 +534,12 @@ cairo_user_font_face_set_render_glyph_func (cairo_font_face_t
 }
 
 /**
- * cairo_user_font_face_set_unicode_to_glyph_func:
+ * cairo_user_font_face_set_text_to_glyphs_func:
  * @font_face: A user font face
- * @unicode_to_glyph_func: The unicode_to_glyph callback, or %NULL
+ * @text_to_glyphs_func: The text_to_glyphs callback, or %NULL
  *
- * Sets the unicode-to-glyph conversion function of a user-font.
- * See #cairo_user_scaled_font_unicode_to_glyph_func_t for details of how the callback
+ * Sets th text-to-glyphs conversion function of a user-font.
+ * See #cairo_user_scaled_font_text_to_glyphs_func_t for details of how the callback
  * works.
  *
  * The font-face should not be immutable or a %CAIRO_STATUS_USER_FONT_IMMUTABLE
@@ -549,8 +549,8 @@ cairo_user_font_face_set_render_glyph_func (cairo_font_face_t
  * Since: 1.8
  **/
 void
-cairo_user_font_face_set_unicode_to_glyph_func (cairo_font_face_t                              *font_face,
-						cairo_user_scaled_font_unicode_to_glyph_func_t  unicode_to_glyph_func)
+cairo_user_font_face_set_text_to_glyphs_func (cairo_font_face_t                            *font_face,
+					      cairo_user_scaled_font_text_to_glyphs_func_t  text_to_glyphs_func)
 {
     cairo_user_font_face_t *user_font_face = (cairo_user_font_face_t *) font_face;
     if (! _cairo_font_face_is_user (font_face)) {
@@ -561,16 +561,16 @@ cairo_user_font_face_set_unicode_to_glyph_func (cairo_font_face_t
 	if (_cairo_font_face_set_error (font_face, CAIRO_STATUS_USER_FONT_IMMUTABLE))
 	    return;
     }
-    user_font_face->scaled_font_methods.unicode_to_glyph = unicode_to_glyph_func;
+    user_font_face->scaled_font_methods.text_to_glyphs = text_to_glyphs_func;
 }
 
 /**
- * cairo_user_font_face_set_text_to_glyphs_func:
+ * cairo_user_font_face_set_unicode_to_glyph_func:
  * @font_face: A user font face
- * @text_to_glyphs_func: The text_to_glyphs callback, or %NULL
+ * @unicode_to_glyph_func: The unicode_to_glyph callback, or %NULL
  *
- * Sets th text-to-glyphs conversion function of a user-font.
- * See #cairo_user_scaled_font_text_to_glyphs_func_t for details of how the callback
+ * Sets the unicode-to-glyph conversion function of a user-font.
+ * See #cairo_user_scaled_font_unicode_to_glyph_func_t for details of how the callback
  * works.
  *
  * The font-face should not be immutable or a %CAIRO_STATUS_USER_FONT_IMMUTABLE
@@ -580,8 +580,8 @@ cairo_user_font_face_set_unicode_to_glyph_func (cairo_font_face_t
  * Since: 1.8
  **/
 void
-cairo_user_font_face_set_text_to_glyphs_func (cairo_font_face_t                            *font_face,
-					      cairo_user_scaled_font_text_to_glyphs_func_t  text_to_glyphs_func)
+cairo_user_font_face_set_unicode_to_glyph_func (cairo_font_face_t                              *font_face,
+						cairo_user_scaled_font_unicode_to_glyph_func_t  unicode_to_glyph_func)
 {
     cairo_user_font_face_t *user_font_face = (cairo_user_font_face_t *) font_face;
     if (! _cairo_font_face_is_user (font_face)) {
@@ -592,7 +592,7 @@ cairo_user_font_face_set_text_to_glyphs_func (cairo_font_face_t
 	if (_cairo_font_face_set_error (font_face, CAIRO_STATUS_USER_FONT_IMMUTABLE))
 	    return;
     }
-    user_font_face->scaled_font_methods.text_to_glyphs = text_to_glyphs_func;
+    user_font_face->scaled_font_methods.unicode_to_glyph = unicode_to_glyph_func;
 }
 
 /* User-font method getters */
@@ -642,45 +642,45 @@ cairo_user_font_face_get_render_glyph_func (cairo_font_face_t *font_face)
 }
 
 /**
- * cairo_user_font_face_get_unicode_to_glyph_func:
+ * cairo_user_font_face_get_text_to_glyphs_func:
  * @font_face: A user font face
  *
- * Gets the unicode-to-glyph conversion function of a user-font.
+ * Gets the text-to-glyphs conversion function of a user-font.
  *
- * Return value: The unicode_to_glyph callback of @font_face
+ * Return value: The text_to_glyphs callback of @font_face
  * or %NULL if none set.
  *
  * Since: 1.8
  **/
-cairo_user_scaled_font_unicode_to_glyph_func_t
-cairo_user_font_face_get_unicode_to_glyph_func (cairo_font_face_t *font_face)
+cairo_user_scaled_font_text_to_glyphs_func_t
+cairo_user_font_face_get_text_to_glyphs_func (cairo_font_face_t *font_face)
 {
     cairo_user_font_face_t *user_font_face = (cairo_user_font_face_t *) font_face;
     if (! _cairo_font_face_is_user (font_face)) {
 	if (_cairo_font_face_set_error (font_face, CAIRO_STATUS_FONT_TYPE_MISMATCH))
 	    return NULL;
     }
-    return user_font_face->scaled_font_methods.unicode_to_glyph;
+    return user_font_face->scaled_font_methods.text_to_glyphs;
 }
 
 /**
- * cairo_user_font_face_get_text_to_glyphs_func:
+ * cairo_user_font_face_get_unicode_to_glyph_func:
  * @font_face: A user font face
  *
- * Gets the text-to-glyphs conversion function of a user-font.
+ * Gets the unicode-to-glyph conversion function of a user-font.
  *
- * Return value: The text_to_glyphs callback of @font_face
+ * Return value: The unicode_to_glyph callback of @font_face
  * or %NULL if none set.
  *
  * Since: 1.8
  **/
-cairo_user_scaled_font_text_to_glyphs_func_t
-cairo_user_font_face_get_text_to_glyphs_func (cairo_font_face_t *font_face)
+cairo_user_scaled_font_unicode_to_glyph_func_t
+cairo_user_font_face_get_unicode_to_glyph_func (cairo_font_face_t *font_face)
 {
     cairo_user_font_face_t *user_font_face = (cairo_user_font_face_t *) font_face;
     if (! _cairo_font_face_is_user (font_face)) {
 	if (_cairo_font_face_set_error (font_face, CAIRO_STATUS_FONT_TYPE_MISMATCH))
 	    return NULL;
     }
-    return user_font_face->scaled_font_methods.text_to_glyphs;
+    return user_font_face->scaled_font_methods.unicode_to_glyph;
 }
diff --git a/src/cairo.h b/src/cairo.h
index 762f952..ff84968 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -1298,15 +1298,15 @@ typedef cairo_status_t (*cairo_user_scaled_font_render_glyph_func_t) (cairo_scal
 								      cairo_t              *cr,
 								      cairo_text_extents_t *extents);
 
-typedef cairo_status_t (*cairo_user_scaled_font_unicode_to_glyph_func_t) (cairo_scaled_font_t *scaled_font,
-									  unsigned long        unicode,
-									  unsigned long       *glyph_index);
-
 typedef cairo_status_t (*cairo_user_scaled_font_text_to_glyphs_func_t) (cairo_scaled_font_t   *scaled_font,
 									const char            *utf8,
 									cairo_glyph_t        **glyphs,
 									int                   *num_glyphs);
 
+typedef cairo_status_t (*cairo_user_scaled_font_unicode_to_glyph_func_t) (cairo_scaled_font_t *scaled_font,
+									  unsigned long        unicode,
+									  unsigned long       *glyph_index);
+
 /* User-font method setters */
 
 cairo_public void
@@ -1318,13 +1318,13 @@ cairo_user_font_face_set_render_glyph_func (cairo_font_face_t
 					    cairo_user_scaled_font_render_glyph_func_t  render_glyph_func);
 
 cairo_public void
-cairo_user_font_face_set_unicode_to_glyph_func (cairo_font_face_t                              *font_face,
-					        cairo_user_scaled_font_unicode_to_glyph_func_t  unicode_to_glyph_func);
-
-cairo_public void
 cairo_user_font_face_set_text_to_glyphs_func (cairo_font_face_t                            *font_face,
 					      cairo_user_scaled_font_text_to_glyphs_func_t  text_to_glyphs_func);
 
+cairo_public void
+cairo_user_font_face_set_unicode_to_glyph_func (cairo_font_face_t                              *font_face,
+					        cairo_user_scaled_font_unicode_to_glyph_func_t  unicode_to_glyph_func);
+
 /* User-font method getters */
 
 cairo_public cairo_user_scaled_font_init_func_t
@@ -1333,12 +1333,12 @@ cairo_user_font_face_get_init_func (cairo_font_face_t *font_face);
 cairo_public cairo_user_scaled_font_render_glyph_func_t
 cairo_user_font_face_get_render_glyph_func (cairo_font_face_t *font_face);
 
-cairo_public cairo_user_scaled_font_unicode_to_glyph_func_t
-cairo_user_font_face_get_unicode_to_glyph_func (cairo_font_face_t *font_face);
-
 cairo_public cairo_user_scaled_font_text_to_glyphs_func_t
 cairo_user_font_face_get_text_to_glyphs_func (cairo_font_face_t *font_face);
 
+cairo_public cairo_user_scaled_font_unicode_to_glyph_func_t
+cairo_user_font_face_get_unicode_to_glyph_func (cairo_font_face_t *font_face);
+
 
 /* Query functions */
 
commit 6702c7edc4a6e3e1129d8c6e6b4989ba2410add4
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Thu Jun 5 18:42:50 2008 -0400

    [user-font] Let user decide to fall back to unicode_to_glyph in text_to_glyphs
    
    User does this by not setting *num_glyphs.

diff --git a/src/cairo-user-font.c b/src/cairo-user-font.c
index b29bad1..a09343d 100644
--- a/src/cairo-user-font.c
+++ b/src/cairo-user-font.c
@@ -265,6 +265,7 @@ _cairo_user_text_to_glyphs (void           *abstract_font,
 	int i;
 
 	*glyphs = NULL;
+	*num_glyphs = -1;
 
 	status = face->scaled_font_methods.text_to_glyphs (&scaled_font->base,
 							   utf8, glyphs, num_glyphs);
@@ -278,6 +279,9 @@ _cairo_user_text_to_glyphs (void           *abstract_font,
 	    return status;
 	}
 
+	if (*num_glyphs < 0)
+	    return CAIRO_INT_STATUS_UNSUPPORTED;
+
 	/* Convert from font space to user space and add x,y */
 	for (i = 0; i < *num_glyphs; i++) {
 	    double gx = (*glyphs)[i].x;
commit 3b1b0746959956155dd33cf71989e7bcb63886f5
Author: Behdad Esfahbod <behdad at behdad.org>
Date:   Thu Jun 5 18:32:54 2008 -0400

    [user-font] Add XXX mark about metrics-hinting the font extents

diff --git a/src/cairo-user-font.c b/src/cairo-user-font.c
index 8969100..b29bad1 100644
--- a/src/cairo-user-font.c
+++ b/src/cairo-user-font.c
@@ -336,6 +336,8 @@ _cairo_user_font_face_scaled_font_create (void                        *abstract_
 	return status;
     }
 
+    /* XXX metrics hinting? */
+
     /* compute a normalized version of font scale matrix to compute
      * extents in.  This is to minimize error caused by the cairo_fixed_t
      * representation. */


More information about the cairo-commit mailing list