SkTextBlob: Begin implementing Extended TextBlob API

include/core/SkTextBlob.h

 /*
  * Copyright 2014 Google Inc.
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkTextBlob_DEFINED
 #define SkTextBlob_DEFINED
 
 #include "../private/SkTemplates.h"
 #include "SkPaint.h"
+#include "SkString.h"
 #include "SkRefCnt.h"
 
 class SkReadBuffer;
 class SkWriteBuffer;
 
 /** \class SkTextBlob
 
     SkTextBlob combines multiple text runs into an immutable, ref-counted structure.
 */
 class SK_API SkTextBlob : public SkRefCnt {
@@ skipping 15 matching lines @@
 
     /**
      *  Recreate an SkTextBlob that was serialized into a buffer.
      *
      *  @param  SkReadBuffer Serialized blob data.
      *  @return A new SkTextBlob representing the serialized data, or NULL if the buffer is
      *          invalid.
      */
     static const SkTextBlob* CreateFromBuffer(SkReadBuffer&);
 
-    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.
     };
 
 private:
     class RunRecord;
 
     SkTextBlob(int runCount, const SkRect& bounds);
 
@@ skipping 22 matching lines @@
     // The actual payload resides in externally-managed storage, following the object.
     // (see the .cpp for more details)
 
     typedef SkRefCnt INHERITED;
 };
 
 /** \class SkTextBlobBuilder
 
     Helper class for constructing SkTextBlobs.
  */
 class SK_API SkTextBlobBuilder {

[tomhudson, 2016/06/21 14:51:28]

Tangent not for this CL: do we really have to have a helper class that does
direct allocation via public methods in the public include/ directories?

[hal.canary, 2016/06/22 17:59:57]

How else will a client construct aSkTextBlob?

 public:
     SkTextBlobBuilder();
 
     ~SkTextBlobBuilder();
 
     /**
      *  Returns an immutable SkTextBlob for the current runs/glyphs. The builder is reset and
      *  can be reused.
      */
     const SkTextBlob* build();
 
     /**
      *  Glyph and position buffers associated with a run.
      *
      *  A run is a sequence of glyphs sharing the same font metrics and positioning mode.
+     *
+     *  If textByteCount is 0, utf8text and clusters will be NUL.

[Rik, 2016/06/20 23:05:16]

It's unclear where textByteCount comes from.
Maybe better to say "if there is no original unicode mapping"

[tomhudson, 2016/06/21 14:51:28]

nit: NULL?

[hal.canary, 2016/06/22 17:59:57]

Done.

[hal.canary, 2016/06/22 17:59:57]

Acknowledged.

+     *
+     *  utf8text will point to a buffer of size textByteCount bytes.
+     *
+     *  clusters (if not NULL) will point to an array of size count.

[Rik, 2016/06/20 23:05:16]

Could be more descriptive.

[hal.canary, 2016/06/22 17:59:57]

Done.

+     *  For each glyph, give the byte-offset into the text for the
+     *  first character in that glyph's cluster.
      */
     struct RunBuffer {
         uint16_t* glyphs;
         SkScalar* pos;
+        char* utf8text;
+        uint32_t* clusters;
     };
 
     /**
      *  Allocates a new default-positioned run and returns its writable glyph buffer
      *  for direct manipulation.
      *
      *  @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 be unkown.

[tomhudson, 2016/06/21 14:51:28]

nit: unknown?

[hal.canary, 2016/06/22 17:59:57]

Done.

+     *  @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,

[Rik, 2016/06/20 23:05:16]

Why not pass the UTF-8 buffer here?

[hal.canary, 2016/06/22 17:59:57]

Let's pass the text and glyphs the same way.

+                                  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
      *  buffers for direct manipulation.
      *
      *  @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 be unkown.
+     *  @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
      *  buffers for direct manipulation.
      *
      *  @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 be unkown.
+     *  @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 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 testSize, SkPoint offset, const SkRect* bounds);

[reed1, 2016/06/20 19:56:24]

size_t?
testSize -> textSize?
is this a byte count?

[hal.canary, 2016/06/22 17:59:57]

I don't know.  int, unsigned, or size_t would all be fine to me.  count is an
int, so I kept it uniform.
Done.

     bool mergeRun(const SkPaint& font, SkTextBlob::GlyphPositioning positioning,
                   int count, SkPoint offset);
     void updateDeferredBounds();
 
     static SkRect ConservativeRunBounds(const SkTextBlob::RunRecord&);
     static SkRect TightRunBounds(const SkTextBlob::RunRecord&);
 
     SkAutoTMalloc<uint8_t> fStorage;
     size_t                 fStorageSize;
     size_t                 fStorageUsed;
 
     SkRect                 fBounds;
     int                    fRunCount;
     bool                   fDeferredBounds;
     size_t                 fLastRun; // index into fStorage
 
     RunBuffer              fCurrentRunBuffer;
 };
 
 #endif // SkTextBlob_DEFINED