Add new functions: pango_layout_iter_get_line_readonly()

2006-12-05  Behdad Esfahbod  <behdad@gnome.org>

        * docs/pango-sections.txt:
        * docs/tmpl/layout.sgml:
        * pango/pango-layout.c (pango_layout_get_lines_readonly),
        (pango_layout_get_line_readonly),
        (pango_layout_iter_get_run_readonly),
        (_pango_layout_iter_get_line), (pango_layout_iter_get_line),
        (pango_layout_iter_get_line_readonly):
        * pango/pango-layout.h:
        * pango/pango-renderer.c (pango_renderer_draw_layout):
        * pango/pango.def:
        Add new functions:
                pango_layout_iter_get_line_readonly()
                pango_layout_get_lines_readonly()
                pango_layout_iter_get_line_readonly()
                pango_layout_iter_get_run_readonly()
        These should be used when you do not intend to modify the run/line,
        which is more than most of the time.  So, update your app, benefit
        from more optimizations (in this case, line extents caching)!

4 files changed, 142 insertions, 9 deletions

diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 9f465468..eed0844b 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -1073,6 +1073,9 @@ pango_layout_get_line_count (PangoLayout   *layout)
  * @layout: a #PangoLayout
  * 
  * Returns the lines of the @layout as a list.
+ *
+ * Use the faster pango_layout_get_lines_readonly() if you do not plan
+ * to modify the contents of the lines (glyphs, glyph widths, etc.).
  * 
  * Return value: a #GSList containing the lines in the layout. This
  * points to internal data of the #PangoLayout and must be used with
@@ -1100,6 +1103,31 @@ pango_layout_get_lines (PangoLayout *layout)
 }
 
 /**
+ * pango_layout_get_lines_readonly:
+ * @layout: a #PangoLayout
+ * 
+ * Returns the lines of the @layout as a list.
+ * 
+ * This is a faster alternative to pango_layout_get_lines(),
+ * but the user is not expected
+ * to modify the contents of the lines (glyphs, glyph widths, etc.).
+ *
+ * Return value: a #GSList containing the lines in the layout. This
+ * points to internal data of the #PangoLayout and must be used with
+ * care. It will become invalid on any change to the layout's
+ * text or properties.  No changes should be made to the lines.
+ *
+ * Since: 1.16
+ **/
+GSList *
+pango_layout_get_lines_readonly (PangoLayout *layout)
+{
+  pango_layout_check_lines (layout);
+
+  return layout->lines;
+}
+
+/**
  * pango_layout_get_line:
  * @layout: a #PangoLayout
  * @line: the index of a line, which must be between 0 and
@@ -1107,6 +1135,9 @@ pango_layout_get_lines (PangoLayout *layout)
  * 
  * Retrieves a particular line from a #PangoLayout.
  * 
+ * Use the faster pango_layout_get_line_readonly() if you do not plan
+ * to modify the contents of the line (glyphs, glyph widths, etc.).
+ *
  * Return value: the requested #PangoLayoutLine, or %NULL if the
  *               index is out of range. This layout line can
  *               be ref'ed and retained, but will become invalid
@@ -1139,6 +1170,50 @@ pango_layout_get_line (PangoLayout *layout,
 }
 
 /**
+ * pango_layout_get_line_readonly:
+ * @layout: a #PangoLayout
+ * @line: the index of a line, which must be between 0 and
+ *        <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive.
+ * 
+ * Retrieves a particular line from a #PangoLayout.
+ * 
+ * This is a faster alternative to pango_layout_get_line(),
+ * but the user is not expected
+ * to modify the contents of the line (glyphs, glyph widths, etc.).
+ *
+ * Return value: the requested #PangoLayoutLine, or %NULL if the
+ *               index is out of range. This layout line can
+ *               be ref'ed and retained, but will become invalid
+ *               if changes are made to the #PangoLayout.
+ *               No changes should be made to the line.
+ *
+ * Since: 1.16
+ **/
+PangoLayoutLine *
+pango_layout_get_line_readonly (PangoLayout *layout,
+				int          line)
+{
+  GSList *list_item;
+  g_return_val_if_fail (layout != NULL, NULL);
+  g_return_val_if_fail (line >= 0, NULL);
+
+  if (line < 0)
+    return NULL;
+
+  pango_layout_check_lines (layout);
+
+  list_item = g_slist_nth (layout->lines, line);
+
+  if (list_item)
+    {
+      PangoLayoutLine *line = list_item->data;
+      return line;
+    }
+
+  return NULL;
+}
+
+/**
  * pango_layout_line_index_to_x:
  * @line:     a #PangoLayoutLine
  * @index_:   byte offset of a grapheme within the layout
@@ -4889,6 +4964,9 @@ pango_layout_iter_get_index (PangoLayoutIter *iter)
  * line, there's a position with a %NULL run, so this function can return
  * %NULL. The %NULL run at the end of each line ensures that all lines have
  * at least one run, even lines consisting of only a newline.
+ *
+ * Use the faster pango_layout_iter_get_run_readonly() if you do not plan
+ * to modify the contents of the run (glyphs, glyph widths, etc.).
  * 
  * Return value: the current run.
  **/
@@ -4903,16 +4981,37 @@ pango_layout_iter_get_run (PangoLayoutIter *iter)
   return iter->run;
 }
 
-/* an inline-able version for local use */
-static PangoLayoutLine*
-_pango_layout_iter_get_line (PangoLayoutIter *iter)
+/**
+ * pango_layout_iter_get_run_readonly:
+ * @iter: a #PangoLayoutIter
+ * 
+ * Gets the current run. When iterating by run, at the end of each
+ * line, there's a position with a %NULL run, so this function can return
+ * %NULL. The %NULL run at the end of each line ensures that all lines have
+ * at least one run, even lines consisting of only a newline.
+ * 
+ * This is a faster alternative to pango_layout_iter_get_run(),
+ * but the user is not expected
+ * to modify the contents of the run (glyphs, glyph widths, etc.).
+ * 
+ * Return value: the current run, that should not be modified.
+ *
+ * Since: 1.16
+ **/
+PangoLayoutRun*
+pango_layout_iter_get_run_readonly (PangoLayoutIter *iter)
 {
-  return iter->line;
+  if (ITER_IS_INVALID (iter))
+    return NULL;
+
+  pango_layout_line_leaked (iter->line);
+
+  return iter->run;
 }
 
-/* a private one for pango-renderer.c use */
-PangoLayoutLine*
-_pango_layout_iter_get_line_readonly (PangoLayoutIter *iter)
+/* an inline-able version for local use */
+static PangoLayoutLine*
+_pango_layout_iter_get_line (PangoLayoutIter *iter)
 {
   return iter->line;
 }
@@ -4922,6 +5021,9 @@ _pango_layout_iter_get_line_readonly (PangoLayoutIter *iter)
  * @iter: a #PangoLayoutIter
  * 
  * Gets the current line.
+ *
+ * Use the faster pango_layout_iter_get_line_readonly() if you do not plan
+ * to modify the contents of the line (glyphs, glyph widths, etc.).
  * 
  * Return value: the current line.
  **/
@@ -4937,6 +5039,29 @@ pango_layout_iter_get_line (PangoLayoutIter *iter)
 }
 
 /**
+ * pango_layout_iter_get_line_readonly:
+ * @iter: a #PangoLayoutIter
+ * 
+ * Gets the current line for read-only access.
+ *
+ * This is a faster alternative to pango_layout_iter_get_line(),
+ * but the user is not expected
+ * to modify the contents of the line (glyphs, glyph widths, etc.).
+ * 
+ * Return value: the current line, that should not be modified.
+ *
+ * Since: 1.16
+ **/
+PangoLayoutLine*
+pango_layout_iter_get_line_readonly (PangoLayoutIter *iter)
+{
+  if (ITER_IS_INVALID (iter))
+    return NULL;
+
+  return iter->line;
+}
+
+/**
  * pango_layout_iter_at_last_line:
  * @iter: a #PangoLayoutIter
  * 
diff --git a/pango/pango-layout.h b/pango/pango-layout.h
index 563c6839..df1851c9 100644
--- a/pango/pango-layout.h
+++ b/pango/pango-layout.h
@@ -200,7 +200,10 @@ void     pango_layout_get_pixel_size       (PangoLayout    *layout,
 int              pango_layout_get_line_count       (PangoLayout    *layout);
 PangoLayoutLine *pango_layout_get_line             (PangoLayout    *layout,
 						    int             line);
+PangoLayoutLine *pango_layout_get_line_readonly    (PangoLayout    *layout,
+						    int             line);
 GSList *         pango_layout_get_lines            (PangoLayout    *layout);
+GSList *         pango_layout_get_lines_readonly   (PangoLayout    *layout);
 
 #define PANGO_TYPE_LAYOUT_LINE (pango_layout_line_get_type ())
 
@@ -240,7 +243,9 @@ void             pango_layout_iter_free (PangoLayoutIter *iter);
 
 int              pango_layout_iter_get_index (PangoLayoutIter *iter);
 PangoLayoutRun  *pango_layout_iter_get_run   (PangoLayoutIter *iter);
+PangoLayoutRun  *pango_layout_iter_get_run_readonly   (PangoLayoutIter *iter);
 PangoLayoutLine *pango_layout_iter_get_line  (PangoLayoutIter *iter);
+PangoLayoutLine *pango_layout_iter_get_line_readonly  (PangoLayoutIter *iter);
 gboolean         pango_layout_iter_at_last_line (PangoLayoutIter *iter);
 
 gboolean pango_layout_iter_next_char    (PangoLayoutIter *iter);
diff --git a/pango/pango-renderer.c b/pango/pango-renderer.c
index 4169c3b5..337917b0 100644
--- a/pango/pango-renderer.c
+++ b/pango/pango-renderer.c
@@ -23,7 +23,6 @@
 #include <stdlib.h>
 
 #include "pango-renderer.h"
-#include "pango-layout-private.h"
 
 #define N_RENDER_PARTS 4
 
@@ -177,7 +176,7 @@ pango_renderer_draw_layout (PangoRenderer    *renderer,
       PangoLayoutLine *line;
       int              baseline;
       
-      line = _pango_layout_iter_get_line_readonly (iter);
+      line = pango_layout_iter_get_line_readonly (iter);
       
       pango_layout_iter_get_line_extents (iter, NULL, &logical_rect);
       baseline = pango_layout_iter_get_baseline (iter);
diff --git a/pango/pango.def b/pango/pango.def
index 0f3ebe65..c3815182 100644
--- a/pango/pango.def
+++ b/pango/pango.def
@@ -212,7 +212,9 @@ EXPORTS
 	pango_layout_get_justify
 	pango_layout_get_line
 	pango_layout_get_line_count
+	pango_layout_get_line_readonly
 	pango_layout_get_lines
+	pango_layout_get_lines_readonly
 	pango_layout_get_log_attrs
 	pango_layout_get_pixel_extents
 	pango_layout_get_pixel_size
@@ -235,9 +237,11 @@ EXPORTS
 	pango_layout_iter_get_layout_extents
 	pango_layout_iter_get_line
 	pango_layout_iter_get_line_extents
+	pango_layout_iter_get_line_readonly
 	pango_layout_iter_get_line_yrange
 	pango_layout_iter_get_run
 	pango_layout_iter_get_run_extents
+	pango_layout_iter_get_run_readonly
 	pango_layout_iter_get_type
 	pango_layout_iter_next_char
 	pango_layout_iter_next_cluster