SkSimpleShaper.hpp

/*
Idea:  put all of the primitive-shaping functions in a single place in our API.
This will make clear that the NONE of these functions do what you expect them
to do.
*/

// Copyright 2019 Google LLC.
// Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
#ifndef SkSimpleShaper_DEFINED
#define SkSimpleShaper_DEFINED

#include "SkFontTypes.h"

class SkTypeface;
class SkFont;
class SkPaint;
class SkTextBlob;
template <typename T> class sk_sp;

namespace SkSimpleShaper {

/** Creates SkTextBlob with a single run.

    font contains attributes used to define the run text.

    When encoding is SkTextEncoding::kUTF8, SkTextEncoding::kUTF16, or
    SkTextEncoding::kUTF32, this function uses the default
    character-to-glyph mapping from the SkTypeface in font.  It does not
    perform typeface fallback for characters not found in the SkTypeface.
    It does not perform kerning or other complex shaping; glyphs are
    positioned based on their default advances.

    @param text        character code points or glyphs drawn
    @param byteLength  byte length of text array
    @param font        text size, typeface, text scale, and so on, used to draw
    @param encoding    text encoding used in the text array
    @return            SkTextBlob constructed from one run
*/
sk_sp<SkTextBlob> MakeBlob(const void* text, size_t byteLength, const SkFont& font,
                           SkTextEncoding encoding);

/** Creates SkTextBlob with a single run. string meaning depends on SkTextEncoding;
    by default, string is encoded as UTF-8.

    font contains attributes used to define the run text.

    This function uses the default character-to-glyph mapping from the
    SkTypeface in font.  It does not perform typeface fallback for characters
    not found in the SkTypeface.  It does not perform kerning or other complex
    shaping; glyphs are positioned based on their default advances.

    @param string   character code points or glyphs drawn
    @param font     text size, typeface, text scale, and so on, used to draw
    @return         SkTextBlob constructed from one run
*/
static inline sk_sp<SkTextBlob> MakeBlobFromString(const char* string, const SkFont& font) {
    return SkSimpleShaper::MakeBlob(string, strlen(string), font, kUTF8_SkTextEncoding);
}

/** Converts text into glyph indices.
    Returns the number of glyph indices represented by text.  SkTextEncoding
    specifies how text represents characters or glyphs.  glyphs may be nullptr,
    to compute the glyph count.

    Does not check text for valid character codes or valid glyph indices.

    If byteLength equals zero, returns zero.  If byteLength includes a partial
    character, the partial character is ignored.

    If encoding is kUTF8_SkTextEncoding and text contains an invalid UTF-8
    sequence, zero is returned.

    When encoding is SkTextEncoding::kUTF8, SkTextEncoding::kUTF16, or
    SkTextEncoding::kUTF32; then each Unicode codepoint is mapped to a single
    glyph.  This function uses the default character-to-glyph mapping from the
    SkTypeface and maps characters not found in the SkTypeface to zero.

    If maxGlyphCount is not sufficient to store all the glyphs, no glyphs are
    copied.  The total glyph count is returned for subsequent buffer
    reallocation.

    @param typeface      FIXME, may be nullptr for the default typeface
    @param text          character storage encoded with SkTextEncoding
    @param byteLength    length of character storage in bytes
    @param encoding      one of: kUTF8_SkTextEncoding, kUTF16_SkTextEncoding,
                         kUTF32_SkTextEncoding, kGlyphID_SkTextEncoding
    @param glyphs        storage for glyph indices; may be nullptr
    @param maxGlyphCount storage capacity
    @return              number of glyphs represented by text of length byteLength
*/
int TextToGlyphs(const SkTypeface* typeface, const void* text, size_t byteLength,
                 SkTextEncoding encoding, SkGlyphID glyphs[], int maxGlyphCount);

/** Returns number of glyphs represented by text.

    If encoding is kUTF8_SkTextEncoding, kUTF16_SkTextEncoding, or
    kUTF32_SkTextEncoding; then each Unicode codepoint is mapped to a
    single glyph.

    @param typeface      FIXME, may be nullptr for the default typeface
    @param text          character storage encoded with SkTextEncoding
    @param byteLength    length of character storage in bytes
    @param encoding      one of: kUTF8_SkTextEncoding, kUTF16_SkTextEncoding,
                         kUTF32_SkTextEncoding, kGlyphID_SkTextEncoding
    @return              number of glyphs represented by text of length byteLength
*/
static inline int CountText(const SkTypeface* typeface, const void* text, size_t byteLength,
                            SkTextEncoding encoding) {
    return SkSimpleShaper::TextToGlyphs(typeface, text, byteLength, encoding, nullptr, 0);
}

/** Returns true if all text corresponds to a non-zero glyph index.
    Returns false if any characters in text are not supported in
    SkTypeface.

    If SkTextEncoding is kGlyphID_SkTextEncoding,
    returns true if all glyph indices in text are non-zero;
    does not check to see if text contains valid glyph indices for SkTypeface.

    Returns true if byteLength is zero.

    @param typeface    FIXME, may be nullptr for the default typeface
    @param text        array of characters or glyphs
    @param byteLength  number of bytes in text array
    @param encoding    text encoding
    @return            true if all text corresponds to a non-zero glyph index
 */
bool ContainsText(const SkTypeface* typeface, const void* text, size_t byteLength,
                  SkTextEncoding encoding);

/** Returns the bytes of text that fit within maxWidth.
    The text fragment fits if its advance width is less than or equal to maxWidth.
    Measures only while the advance is less than or equal to maxWidth.
    Returns the advance or the text fragment in measuredWidth if it not nullptr.
    Uses encoding to decode text, SkTypeface to get the font metrics,
    and text size to scale the metrics.
    Does not scale the advance or bounds by fake bold.

    @param font           FIXME
    @param text           character codes or glyph indices to be measured
    @param length         number of bytes of text to measure
    @param encoding       text encoding
    @param maxWidth       advance limit; text is measured while advance is less than maxWidth
    @param measuredWidth  returns the width of the text less than or equal to maxWidth
    @return               bytes of text that fit, always less than or equal to length
*/
size_t BreakText(const SkFont& font, const void* text, size_t length, SkTextEncoding encoding,
                 SkScalar maxWidth, SkScalar* measuredWidth = nullptr);

/** Returns the advance width of text.
    The advance is the normal distance to move before drawing additional text.
    Returns the bounding box of text if bounds is not nullptr. paint
    stroke width or SkPathEffect may modify the advance with.

    @param font        FIXME
    @param text        character storage encoded with SkTextEncoding
    @param byteLength  length of character storage in bytes
    @param encoding    one of: kUTF8_SkTextEncoding, kUTF16_SkTextEncoding,
                       kUTF32_SkTextEncoding, kGlyphID_SkTextEncoding
    @param bounds      returns bounding box relative to (0, 0) if not nullptr
    @param paint       optional; may be nullptr
    @return            number of glyphs represented by text of length byteLength
*/
SkScalar MeasureText(const SkFont& font, const void* text, size_t byteLength,
                     SkTextEncoding encoding, SkRect* bounds, const SkPaint* paint);

/** Returns the advance width of text.
    The advance is the normal distance to move before drawing additional text.
    Returns the bounding box of text if bounds is not nullptr.

    @param font           FIXME
    @param text        character storage encoded with SkTextEncoding
    @param byteLength  length of character storage in bytes
    @param encoding    one of: kUTF8_SkTextEncoding, kUTF16_SkTextEncoding,
                       kUTF32_SkTextEncoding, kGlyphID_SkTextEncoding
    @param bounds      returns bounding box relative to (0, 0) if not nullptr
    @return            number of glyphs represented by text of length byteLength
*/
static inline SkScalar MeasureText(const SkFont& font, const void* text, size_t byteLength,
                                   SkTextEncoding encoding, SkRect* bounds = nullptr) {
    return SkSimpleShaper::MeasureText(font, text, byteLength, encoding, bounds, nullptr);
}

/** Retrieves the advance and bounds for each glyph in glyphs.
    Both widths and bounds may be nullptr.
    If widths is not nullptr, widths must be an array of count entries.
    if bounds is not nullptr, bounds must be an array of count entries.

    @param font        FIXME
    @param glyphs      array of glyph indices to be measured
    @param count       number of glyphs
    @param widths      returns text advances for each glyph; may be nullptr
    @param bounds      returns bounds for each glyph relative to (0, 0); may be nullptr
    @param paint       optional, specifies stroking, SkPathEffect and SkMaskFilter
 */
void GetWidthsBounds(const SkFont& font, const uint16_t glyphs[], int count, SkScalar widths[],
                     SkRect bounds[], const SkPaint* paint);

/** Retrieves the advance and bounds for each glyph in glyphs.
    Both widths and bounds may be nullptr.
    If widths is not nullptr, widths must be an array of count entries.
    if bounds is not nullptr, bounds must be an array of count entries.

    @param font        FIXME
    @param glyphs      array of glyph indices to be measured
    @param count       number of glyphs
    @param widths      returns text advances for each glyph
 */
static inline void GetWidths(const SkFont& font, const uint16_t glyphs[], int count,
                             SkScalar widths[]) {
    SkSimpleShaper::GetWidthsBounds(font, glyphs, count, widths, nullptr, nullptr);
}

/** Retrieves the bounds for each glyph in glyphs.
    bounds must be an array of count entries.
    If paint is not nullptr, its stroking, SkPathEffect, and SkMaskFilter fields are respected.

    @param font        FIXME
    @param glyphs      array of glyph indices to be measured
    @param count       number of glyphs
    @param bounds      returns bounds for each glyph relative to (0, 0); may be nullptr
    @param paint       optional, specifies stroking, SkPathEffect, and SkMaskFilter
 */
static inline void GetBounds(const SkFont& font, const uint16_t glyphs[], int count,
                             SkRect bounds[], const SkPaint* paint) {
    SkSimpleShaper::GetWidthsBounds(font, glyphs, count, nullptr, bounds, paint);
}

/** Retrieves the positions for each glyph, beginning at the specified origin. The caller
    must allocated at least count number of elements in the pos[] array.

    @param font     FIXME
    @param glyphs   array of glyph indices to be positioned
    @param count    number of glyphs
    @param pos      returns glyphs positions
    @param origin   location of the first glyph. Defaults to {0, 0}.
 */
void GetPos(const SkFont& font, const uint16_t glyphs[], int count, SkPoint pos[],
            SkPoint origin = {0, 0});

/** Retrieves the x-positions for each glyph, beginning at the specified origin. The caller
    must allocated at least count number of elements in the xpos[] array.

    @param font     FIXME
    @param glyphs   array of glyph indices to be positioned
    @param count    number of glyphs
    @param xpos     returns glyphs x-positions
    @param origin   x-position of the first glyph. Defaults to 0.
 */
void GetXPos(const SkFont& font, const uint16_t glyphs[], int count, SkScalar xpos[],
             SkScalar origin = 0);

}  // namespace SkSimpleShaper
#endif  // SkSimpleShaper_DEFINED