[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