pango r2548 - in trunk: . docs/tmpl pango

[behdad svn gnome org]

Author: behdad
Date: Tue Jan 22 02:08:36 2008
New Revision: 2548
URL: http://svn.gnome.org/viewvc/pango?rev=2548&view=rev

Log:
2008-01-21  Behdad Esfahbod  <behdad gnome org>

        Bug 508002 â change pango_layout_pixel_extents() to round logical rect
        to be inclusive

        * pango/pango-layout.c (pango_layout_get_pixel_extents),
        (pango_layout_line_get_pixel_extents): Round extents to pixels
        inclusively.  That is, pass both ink_rect and logical_rect as first
        argument to pango_extents_to_pixels().

        * pango/pango-matrix.c (pango_matrix_transform_pixel_rectangle):
        Fix rounding.

        * pango/pango-types.h:
        * docs/tmpl/glyphs.sgml:
        * pango/pango-utils.c (pango_extents_to_pixels):
        Rename pango_extents_to_pixels() function arguments from @ink_rect and
        @logical_rect to @inclusive and @nearest.  Given that this API is a
        fairly new addition and not commonly used, language bindings are
        encouraged to update their argument names accordingly.  Moreover, they
        are encouraged to wrap this function as two different calls:
        extents_to_pixels_inclusive() and extents_to_pixels_nearest(), or
        similar conventions that best reflect their native language.



Modified:
   trunk/ChangeLog
   trunk/docs/tmpl/glyphs.sgml
   trunk/pango/pango-layout.c
   trunk/pango/pango-matrix.c
   trunk/pango/pango-types.h
   trunk/pango/pango-utils.c

Modified: trunk/docs/tmpl/glyphs.sgml
==============================================================================
--- trunk/docs/tmpl/glyphs.sgml	(original)
+++ trunk/docs/tmpl/glyphs.sgml	Tue Jan 22 02:08:36 2008
@@ -156,8 +156,8 @@
 
 </para>
 
- ink_rect: 
- logical_rect: 
+ inclusive: 
+ nearest: 
 
 
 <!-- ##### STRUCT PangoMatrix ##### -->

Modified: trunk/pango/pango-layout.c
==============================================================================
--- trunk/pango/pango-layout.c	(original)
+++ trunk/pango/pango-layout.c	Tue Jan 22 02:08:36 2008
@@ -2576,12 +2576,9 @@
  *
  * Computes the logical and ink extents of @layout in device units.
  * This function just calls pango_layout_get_extents() followed by
- * pango_extents_to_pixels().
- *
- * See pango_extents_to_pixels() for details of how ink and logical rectangles
- * are rounded to pixels.  In certain situations you may want to use
- * pango_layout_get_extents() directly and pass the resulting logical
- * rectangle to pango_extents_to_pixels() as an ink rectangle().
+ * two pango_extents_to_pixels() calls, rounding @ink_rect and @logical_rect
+ * such that the rounded rectangles fully contain the unrounded one (that is,
+ * passes them as first argument to pango_extents_to_pixels()).
  **/
 void
 pango_layout_get_pixel_extents (PangoLayout *layout,
@@ -2591,7 +2588,8 @@
   g_return_if_fail (PANGO_IS_LAYOUT (layout));
 
   pango_layout_get_extents (layout, ink_rect, logical_rect);
-  pango_extents_to_pixels (ink_rect, logical_rect);
+  pango_extents_to_pixels (ink_rect, NULL);
+  pango_extents_to_pixels (logical_rect, NULL);
 }
 
 /**
@@ -4610,7 +4608,9 @@
  *
  * Computes the logical and ink extents of @layout_line in device units.
  * This function just calls pango_layout_line_get_extents() followed by
- * pango_extents_to_pixels().
+ * two pango_extents_to_pixels() calls, rounding @ink_rect and @logical_rect
+ * such that the rounded rectangles fully contain the unrounded one (that is,
+ * passes them as first argument to pango_extents_to_pixels()).
  **/
 void
 pango_layout_line_get_pixel_extents (PangoLayoutLine *layout_line,
@@ -4620,7 +4620,8 @@
   g_return_if_fail (LINE_IS_VALID (layout_line));
 
   pango_layout_line_get_extents (layout_line, ink_rect, logical_rect);
-  pango_extents_to_pixels (ink_rect, logical_rect);
+  pango_extents_to_pixels (ink_rect, NULL);
+  pango_extents_to_pixels (logical_rect, NULL);
 }
 
 /*

Modified: trunk/pango/pango-matrix.c
==============================================================================
--- trunk/pango/pango-matrix.c	(original)
+++ trunk/pango/pango-matrix.c	Tue Jan 22 02:08:36 2008
@@ -332,8 +332,9 @@
  * If you have the rectangle in Pango units and want to convert to
  * transformed pixel bounding box, it is more accurate to transform it first
  * (using this function) and pass the result to pango_extents_to_pixels(),
- * as @ink_rect.  However, there is a reason that you may want to convert
- * to pixels first and then transform, and that is when the transformed
+ * first argument, for an inclusive rounded rectangle.
+ * However, there are valid reasons that you may want to convert
+ * to pixels first and then transform, for example when the transformed
  * coordinates may overflow in Pango units (large matrix translation for
  * example).
  *
@@ -408,7 +409,7 @@
  *
  * For better accuracy, you should use pango_matrix_transform_rectangle() on
  * original rectangle in Pango units and convert to pixels afterward
- * using pango_extents_to_pixels() as @ink_rect.
+ * using pango_extents_to_pixels()'s first argument.
  *
  * Since: 1.16
  **/
@@ -460,8 +461,8 @@
 	  max_y = quad_y[i];
   }
 
-  rect->x      = min_x;
-  rect->y      = min_y;
-  rect->width  = max_x - rect->x;
-  rect->height = max_y - rect->y;
+  rect->x      = floor (min_x);
+  rect->y      = floor (min_y);
+  rect->width  = ceil (max_x - rect->x);
+  rect->height = ceil (max_y - rect->y);
 }

Modified: trunk/pango/pango-types.h
==============================================================================
--- trunk/pango/pango-types.h	(original)
+++ trunk/pango/pango-types.h	Tue Jan 22 02:08:36 2008
@@ -84,8 +84,8 @@
 #define PANGO_LBEARING(rect) ((rect).x)
 #define PANGO_RBEARING(rect) ((rect).x + (rect).width)
 
-void pango_extents_to_pixels (PangoRectangle *ink_rect,
-			      PangoRectangle *logical_rect);
+void pango_extents_to_pixels (PangoRectangle *inclusive,
+			      PangoRectangle *nearest);
 
 /**
  * PangoDirection:

Modified: trunk/pango/pango-utils.c
==============================================================================
--- trunk/pango/pango-utils.c	(original)
+++ trunk/pango/pango-utils.c	Tue Jan 22 02:08:36 2008
@@ -1655,52 +1655,53 @@
 
 /**
  * pango_extents_to_pixels:
- * @ink_rect: ink rectangle to convert, or %NULL.
- * @logical_rect: logical rectangle to convert, or %NULL.
+ * @inclusive: rectangle to round to pixels inclusively, or %NULL.
+ * @nearest: rectangle to round to nearest pixels, or %NULL.
  *
  * Converts extents from Pango units to device units, dividing by the
  * %PANGO_SCALE factor and performing rounding.
  *
- * The ink rectangle is converted by flooring the x/y coordinates and extending
+ * The @inclusive rectangle is converted by flooring the x/y coordinates and extending
  * width/height, such that the final rectangle completely includes the original
  * rectangle.
  *
- * The logical rectangle is converted by rounding the coordinates
- * of the rectangle to the nearest device unit.
+ * The @nearest rectangle is converted by rounding the coordinates
+ * of the rectangle to the nearest device unit (pixel).
  *
- * Note that in certain situations you may want pass a logical extents
- * rectangle to this function as @ink_rect.  The rule is: if you want the
- * resulting device-space rectangle to completely contain the original
- * rectangle, pass it in as @ink_rect.
+ * The rule to which argument to use is: if you want the resulting device-space
+ * rectangle to completely contain the original rectangle, pass it in as @inclusive.
+ * If you want two touching-but-not-overlapping rectangles stay
+ * touching-but-not-overlapping after rounding to device units, pass them in
+ * as @nearest.
  *
  * Since: 1.16
  **/
 void
-pango_extents_to_pixels (PangoRectangle *ink_rect,
-			 PangoRectangle *logical_rect)
+pango_extents_to_pixels (PangoRectangle *inclusive,
+			 PangoRectangle *nearest)
 {
-  if (ink_rect)
+  if (inclusive)
     {
-      int orig_x = ink_rect->x;
-      int orig_y = ink_rect->y;
+      int orig_x = inclusive->x;
+      int orig_y = inclusive->y;
 
-      ink_rect->x = PANGO_PIXELS_FLOOR (ink_rect->x);
-      ink_rect->y = PANGO_PIXELS_FLOOR (ink_rect->y);
+      inclusive->x = PANGO_PIXELS_FLOOR (inclusive->x);
+      inclusive->y = PANGO_PIXELS_FLOOR (inclusive->y);
 
-      ink_rect->width  = PANGO_PIXELS_CEIL (orig_x + ink_rect->width ) - ink_rect->x;
-      ink_rect->height = PANGO_PIXELS_CEIL (orig_y + ink_rect->height) - ink_rect->y;
+      inclusive->width  = PANGO_PIXELS_CEIL (orig_x + inclusive->width ) - inclusive->x;
+      inclusive->height = PANGO_PIXELS_CEIL (orig_y + inclusive->height) - inclusive->y;
     }
 
-  if (logical_rect)
+  if (nearest)
     {
-      int orig_x = logical_rect->x;
-      int orig_y = logical_rect->y;
+      int orig_x = nearest->x;
+      int orig_y = nearest->y;
 
-      logical_rect->x = PANGO_PIXELS (logical_rect->x);
-      logical_rect->y = PANGO_PIXELS (logical_rect->y);
+      nearest->x = PANGO_PIXELS (nearest->x);
+      nearest->y = PANGO_PIXELS (nearest->y);
 
-      logical_rect->width  = PANGO_PIXELS (orig_x + logical_rect->width ) - logical_rect->x;
-      logical_rect->height = PANGO_PIXELS (orig_y + logical_rect->height) - logical_rect->y;
+      nearest->width  = PANGO_PIXELS (orig_x + nearest->width ) - nearest->x;
+      nearest->height = PANGO_PIXELS (orig_y + nearest->height) - nearest->y;
     }
 }