Changes the sign of extents->descent to match win32 backend and the conventional convention.

Document cairo_font_extents_t.

3 files changed, 53 insertions, 4 deletions

diff --git a/ChangeLog b/ChangeLog
index 794ebe15..e94c6c76 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2005-05-02  Owen Taylor  <otaylor@redhat.com>
+
+	* src/cairo-ft-font.c (_cairo_ft_scaled_font_font_extents): Changes the
+	sign of extents->descent to match win32 backend and the conventional
+	convention.
+
+	* src/cairo.h: Document cairo_font_extents_t.
+
 2005-04-28  Owen Taylor  <otaylor@redhat.com>
 
 	* src/cairo-surface.c src/cairoint.h: Add _cairo_surface_begin/end
diff --git a/src/cairo-ft-font.c b/src/cairo-ft-font.c
index 5c463e44..15107631 100644
--- a/src/cairo-ft-font.c
+++ b/src/cairo-ft-font.c
@@ -936,7 +936,7 @@ _cairo_ft_scaled_font_font_extents (void		 *abstract_font,
      * user space
      */
     extents->ascent =        DOUBLE_FROM_26_6(metrics->ascender) / scaled_font->unscaled->y_scale;
-    extents->descent =       DOUBLE_FROM_26_6(metrics->descender) / scaled_font->unscaled->y_scale;
+    extents->descent =       DOUBLE_FROM_26_6(- metrics->descender) / scaled_font->unscaled->y_scale;
     extents->height =        DOUBLE_FROM_26_6(metrics->height) / scaled_font->unscaled->y_scale;
     extents->max_x_advance = DOUBLE_FROM_26_6(metrics->max_advance) / scaled_font->unscaled->x_scale;
 
diff --git a/src/cairo.h b/src/cairo.h
index 8f609d48..229a1dcd 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -616,10 +616,10 @@ typedef struct {
  *   after drawing these glyphs. Will typically be zero except
  *   for vertical text layout as found in East-Asian languages.
  *
- * The #cairo_text_extents_t< structure stores the extents of a single
+ * The #cairo_text_extents_t 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
+ * extents are in user-space coordinates, they are mostly, but not
+ * entirely, independent of the current transformation matrix. If you call
  * <literal>cairo_scale(cr, 2.0, 2.0)</literal>, 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
@@ -635,6 +635,47 @@ typedef struct {
     double y_advance;
 } cairo_text_extents_t;
 
+/**
+ * cairo_font_extents_t:
+ * @ascent: the distance that the font extends above the baseline.
+ *          Note that this is not always exactly equal to the maximum
+ *          of the extents of all the glyphs in the font, but rather
+ *          is picked to express the font designer's intent as to
+ *          how the font should align with elements above it.
+ * @descent: the distance that the font extends below the baseline.
+ *           This value is positive for typical fonts that include
+ *           portions below the baseline. Note that this is not always
+ *           exactly equal to the maximum of the extents of all the
+ *           glyphs in the font, but rather is picked to express the
+ *           font designer's intent as to how the the font should
+ *           align with elements below it.
+ * @height: the recommended vertical distance between baselines when
+ *          setting consecutive lines of text with the font. This
+ *          is greater than @ascent+@descent by a
+ *          quantity known as the <firstterm>line spacing</firstterm>
+ *          or <firstterm>external leading</firstterm>. When space
+ *          is at a premium, most fonts can be set with only
+ *          a distance of @ascent+@descent between lines.
+ * @max_x_advance: the maximum distance in the X direction that 
+ *         the the origin is advanced for any glyph in the font.
+ * @max_y_advance: the maximum distance in the Y direction that
+ *         the the origin is advanced for any glyph in the font.
+ *         this will be zero for normal fonts used for horizontal
+ *         writing. (The scripts of East Asia are sometimes written
+ *         vertically.)
+ *
+ * The #cairo_text_extents_t structure stores metric information for
+ * a font. Values are given in the current user-space coordinate
+ * system.
+ *
+ * Because font metrics are in user-space coordinates, they are
+ * mostly, but not entirely, independent of the current transformation
+ * matrix. If you call <literal>cairo_scale(cr, 2.0, 2.0)</literal>,
+ * 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.
+ */
 typedef struct {
     double ascent;
     double descent;