SkTextBlob: Begin implementing Extended TextBlob API

include/core/SkTextBlob.h

Index: include/core/SkTextBlob.h
diff --git a/include/core/SkTextBlob.h b/include/core/SkTextBlob.h
index 1addb6f9142e11b7252ec3a534f50b571bfee44e..01263af02d6701099efca009be0e02d93ea70d2c 100644
--- a/include/core/SkTextBlob.h
+++ b/include/core/SkTextBlob.h
@@ -10,6 +10,7 @@
 
 #include "../private/SkTemplates.h"
 #include "SkPaint.h"
+#include "SkString.h"
 #include "SkRefCnt.h"
 
 class SkReadBuffer;
@@ -49,7 +50,7 @@ public:
         return MakeFromBuffer(buffer).release();
     }
 
-    enum GlyphPositioning {
+    enum GlyphPositioning : uint8_t {
         kDefault_Positioning      = 0, // Default glyph advances -- zero scalars per glyph.
         kHorizontal_Positioning   = 1, // Horizontal positioning -- one scalar per glyph.
         kFull_Positioning         = 2  // Point positioning -- two scalars per glyph.
@@ -112,11 +113,29 @@ public:
     /**
      *  Glyph and position buffers associated with a run.
      *
-     *  A run is a sequence of glyphs sharing the same font metrics and positioning mode.
+     *  A run is a sequence of glyphs sharing the same font metrics
+     *  and positioning mode.
+     *
+     *  If textByteCount is 0, utf8text and clusters will be NULL (no
+     *  character information will be associated with the glyphs).
+     *
+     *  utf8text will point to a buffer of size textByteCount bytes.
+     *
+     *  clusters (if not NULL) will point to an array of size count.
+     *  For each glyph, give the byte-offset into the text for the
+     *  first byte in the first character in that glyph's cluster.
+     *  Each value in the array should be an integer less than
+     *  textByteCount.  Values in the array should either be
+     *  monotonically increasing (left-to-right text) or monotonically
+     *  decreasing (right-to-left text).  This definiton is conviently
+     *  the same as used by Harfbuzz's hb_glyph_info_t::cluster field,
+     *  except that Harfbuzz interleaves glyphs and clusters.
      */
     struct RunBuffer {
         SkGlyphID* glyphs;
         SkScalar* pos;
+        char* utf8text;
+        uint32_t* clusters;
     };
 
     /**
@@ -126,14 +145,27 @@ public:
      *  @param font    The font to be used for this run.
      *  @param count   Number of glyphs.
      *  @param x,y     Position within the blob.
+     *  @param textByteCount length of the original UTF-8 text that
+     *                 corresponds to this sequence of glyphs.  If 0,
+     *                 text will not be included in the textblob.
+     *  @param lang    Language code, currently unimplemented.
      *  @param bounds  Optional run bounding box. If known in advance (!= NULL), it will
      *                 be used when computing the blob bounds, to avoid re-measuring.
      *
      *  @return        A writable glyph buffer, valid until the next allocRun() or
      *                 build() call. The buffer is guaranteed to hold @count@ glyphs.
      */
+    const RunBuffer& allocRunText(const SkPaint& font,
+                                  int count,
+                                  SkScalar x,
+                                  SkScalar y,
+                                  int textByteCount,
+                                  SkString lang,
+                                  const SkRect* bounds = NULL);
     const RunBuffer& allocRun(const SkPaint& font, int count, SkScalar x, SkScalar y,
-                              const SkRect* bounds = NULL);
+                              const SkRect* bounds = NULL) {
+        return this->allocRunText(font, count, x, y, 0, SkString(), bounds);
+    }
 
     /**
      *  Allocates a new horizontally-positioned run and returns its writable glyph and position
@@ -142,14 +174,23 @@ public:
      *  @param font    The font to be used for this run.
      *  @param count   Number of glyphs.
      *  @param y       Vertical offset within the blob.
+     *  @param textByteCount length of the original UTF-8 text that
+     *                 corresponds to this sequence of glyphs.  If 0,
+     *                 text will not be included in the textblob.
+     *  @param lang    Language code, currently unimplemented.
      *  @param bounds  Optional run bounding box. If known in advance (!= NULL), it will
      *                 be used when computing the blob bounds, to avoid re-measuring.
      *
      *  @return        Writable glyph and position buffers, valid until the next allocRun()
      *                 or build() call. The buffers are guaranteed to hold @count@ elements.
      */
+    const RunBuffer& allocRunTextPosH(const SkPaint& font, int count, SkScalar y,
+                                      int textByteCount, SkString lang,
+                                      const SkRect* bounds = NULL);
     const RunBuffer& allocRunPosH(const SkPaint& font, int count, SkScalar y,
-                                  const SkRect* bounds = NULL);
+                                  const SkRect* bounds = NULL) {
+        return this->allocRunTextPosH(font, count, y, 0, SkString(), bounds);
+    }
 
     /**
      *  Allocates a new fully-positioned run and returns its writable glyph and position
@@ -157,6 +198,10 @@ public:
      *
      *  @param font   The font to be used for this run.
      *  @param count  Number of glyphs.
+     *  @param textByteCount length of the original UTF-8 text that
+     *                 corresponds to this sequence of glyphs.  If 0,
+     *                 text will not be included in the textblob.
+     *  @param lang    Language code, currently unimplemented.
      *  @param bounds Optional run bounding box. If known in advance (!= NULL), it will
      *                be used when computing the blob bounds, to avoid re-measuring.
      *
@@ -164,12 +209,18 @@ public:
      *                or build() call. The glyph buffer and position buffer are
      *                guaranteed to hold @count@ and 2 * @count@ elements, respectively.
      */
-    const RunBuffer& allocRunPos(const SkPaint& font, int count, const SkRect* bounds = NULL);
+    const RunBuffer& allocRunTextPos(const SkPaint& font, int count,
+                                     int textByteCount, SkString lang,
+                                     const SkRect* bounds = NULL);
+    const RunBuffer& allocRunPos(const SkPaint& font, int count,
+                                 const SkRect* bounds = NULL) {
+        return this->allocRunTextPos(font, count, 0, SkString(), bounds);
+    }
 
 private:
     void reserve(size_t size);
     void allocInternal(const SkPaint& font, SkTextBlob::GlyphPositioning positioning,
-                       int count, SkPoint offset, const SkRect* bounds);
+                       int count, int textBytes, SkPoint offset, const SkRect* bounds);
     bool mergeRun(const SkPaint& font, SkTextBlob::GlyphPositioning positioning,
                   int count, SkPoint offset);
     void updateDeferredBounds();