add helper to create fancy underlines

include/core/SkPaint.h

 /*
  * Copyright 2006 The Android Open Source Project
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkPaint_DEFINED
 #define SkPaint_DEFINED
 
@@ skipping 865 matching lines @@
      *                      the glyphs. If not NULL, must be at least a large
      *                      as the number of unichars in the specified text.
      *  @param bounds       If not null, returns the bounds for each of
      *                      character, relative to (0, 0)
      *  @return the number of unichars in the specified text.
      */
     int getTextWidths(const void* text, size_t byteLength, SkScalar widths[],
                       SkRect bounds[] = NULL) const;
 
     /** Return the path (outline) for the specified text.
-        Note: just like SkCanvas::drawText, this will respect the Align setting
-              in the paint.
-    */
+     *  Note: just like SkCanvas::drawText, this will respect the Align setting
+     *        in the paint.
+     *
+     *  @param text         the text
+     *  @param length       number of bytes of text
+     *  @param x            The x-coordinate of the origin of the text.
+     *  @param y            The y-coordinate of the origin of the text.
+     *  @param path         The outline of the text.
+     */
     void getTextPath(const void* text, size_t length, SkScalar x, SkScalar y,
                      SkPath* path) const;
 
+    /** Return the path (outline) for the specified text.
+     *  Note: just like SkCanvas::drawText, this will respect the Align setting
+     *        in the paint.
+     *
+     *  @param text         the text
+     *  @param length       number of bytes of text
+     *  @param pos          array of positions, used to position each character
+     *  @param path         The outline of the text.
+     */
     void getPosTextPath(const void* text, size_t length,
                         const SkPoint pos[], SkPath* path) const;
 
+    /** Return the number of intervals that intersect the intercept along the axis of the advance.
+     *  This permits constructing an underline that skips the descenders. 
+     *
+     *  @param text         the text
+     *  @param length       number of bytes of text
+     *  @param x            The x-coordinate of the origin of the text.
+     *  @param y            The y-coordinate of the origin of the text.
+     *  @param bounds       The lower and upper line parallel to the advance.
+     *  @param array        If not null, the found intersections.
+     *
+     *  @return             The number of intersections.
+     */
+    int getTextIntercepts(const void* text, size_t length, SkScalar x, SkScalar y,
+                          const SkScalar bounds[2], SkScalar* array) const;

[f(malita), 2016/02/08 14:20:27]

It's a bit unclear how to size 'array' effectively: should clients call this
method twice (once with a nullptr to count the intercepts and the second time
with an allocated array - assumed to be sufficiently large to hold all
intercepts)?  Maybe you can clarify with more comments.

[caryclark, 2016/02/09 19:10:57]

Done.

+
+    /** Return the number of intervals that intersect the intercept along the axis of the advance.
+     *  This permits constructing an underline that skips the descenders. 
+     *
+     *  @param text         the text
+     *  @param length       number of bytes of text
+     *  @param pos          array of positions, used to position each character
+     *  @param bounds       The lower and upper line parallel to the advance.
+     *  @param array        If not null, the glyph bounds contained by the advance parallel lines.
+     *
+     *  @return             The number of glyph bounds.
+     */
+    int getPosTextIntercepts(const void* text, size_t length, const SkPoint pos[],
+                             const SkScalar bounds[2], SkScalar* array) const;
+
     /**
      *  Return a rectangle that represents the union of the bounds of all
      *  of the glyphs, but each one positioned at (0,0). This may be conservatively large, and
      *  will not take into account any hinting, but will respect any text-scale-x or text-skew-x
      *  on this paint.
      */
     SkRect getFontBounds() const;
 
     // returns true if the paint's settings (e.g. xfermode + alpha) resolve to
     // mean that we need not draw at all (e.g. SrcOver + 0-alpha)
@@ skipping 177 matching lines @@
     friend class SkCanvas;
     friend class SkDraw;
     friend class SkPDFDevice;
     friend class GrAtlasTextBlob;
     friend class GrAtlasTextContext;
     friend class GrStencilAndCoverTextContext;
     friend class GrPathRendering;
     friend class GrTextUtils;
     friend class GrGLPathRendering;
     friend class SkScalerContext;
-    friend class SkTextToPathIter;
+    friend class SkTextBaseIter;
     friend class SkCanonicalizePaint;
 };
 
 #endif