skia2/site/user/api/SkTextBlobBuilder_Reference.md

SkTextBlobBuilder Reference

---

class SkTextBlobBuilder {
public:
    SkTextBlobBuilder();
    ~SkTextBlobBuilder();
    sk_sp<SkTextBlob> make();

    struct RunBuffer {
        SkGlyphID* glyphs;
        SkScalar* pos;
        char* utf8text;
        uint32_t* clusters;
    };

    const RunBuffer& allocRun(const SkFont& font, int count, SkScalar x, SkScalar y,
                              const SkRect* bounds = nullptr);
    const RunBuffer& allocRunPosH(const SkFont& font, int count, SkScalar y,
                                  const SkRect* bounds = nullptr);
    const RunBuffer& allocRunPos(const SkFont& font, int count,
                                 const SkRect* bounds = nullptr);
    const RunBuffer& allocRun(const SkPaint& font, int count, SkScalar x, SkScalar y,
                              const SkRect* bounds = nullptr);
    const RunBuffer& allocRunPosH(const SkPaint& font, int count, SkScalar y,
                                  const SkRect* bounds = nullptr);
    const RunBuffer& allocRunPos(const SkPaint& font, int count,
                                 const SkRect* bounds = nullptr);
};

Helper class for constructing SkTextBlob.

---

    struct RunBuffer {
        SkGlyphID* glyphs;
        SkScalar* pos;
        char* utf8text;
        uint32_t* clusters;
    };

RunBuffer supplies storage for Glyphs and positions within a run.

A run is a sequence of Glyphs sharing Paint_Font_Metrics and positioning. Each run may position its Glyphs in one of three ways: by specifying where the first Glyph is drawn, and allowing Paint_Font_Metrics to determine the advance to subsequent Glyphs; by specifying a baseline, and the position on that baseline for each Glyph in run; or by providing Point array, one per Glyph.

Type	Member	Description
SkGlyphID*	glyphs	glyphs points to memory for one or more Glyphs. glyphs memory must be written to by the caller.
SkScalar*	pos	pos points to memory for Glyph positions. Depending on how RunBuffer is allocated, pos may point to zero bytes per Glyph, one Scalar per Glyph, or one Point per Glyph.
char*	utf8text	Reserved for future use. utf8text should not be read or written.
uint32_t*	clusters	Reserved for future use. clusters should not be read or written.

See Also

allocRun allocRunPos allocRunPosH

---

SkTextBlobBuilder()

Constructs empty SkTextBlobBuilder. By default, SkTextBlobBuilder has no runs.

Return Value

empty SkTextBlobBuilder

Example

Example Output

blob equals nullptr

See Also

make SkTextBlob::MakeFromText

---

~SkTextBlobBuilder()

Deletes data allocated internally by SkTextBlobBuilder.

See Also

SkTextBlobBuilder()

---

sk_sp<SkTextBlob> make()

Returns SkTextBlob built from runs of glyphs added by builder. Returned SkTextBlob is immutable; it may be copied, but its contents may not be altered. Returns nullptr if no runs of glyphs were added by builder.

Resets SkTextBlobBuilder to its initial empty state, allowing it to be reused to build a new set of runs.

Return Value

SkTextBlob or nullptr

Example

Example Output

blob equals nullptr
blob does not equal nullptr
blob equals nullptr

See Also

SkTextBlob::MakeFromText

---

const RunBuffer& allocRun(const SkFont& font, int count, SkScalar x, SkScalar y,
                          const SkRect* bounds = nullptr)

Returns run with storage for glyphs. Caller must write count glyphs to RunBuffer::glyphs before next call to SkTextBlobBuilder.

RunBuffer::utf8text, and RunBuffer::clusters should be ignored.

Glyphs share metrics in font.

Glyphs are positioned on a baseline at (x, y), using font metrics to determine their relative placement.

bounds defines an optional bounding box, used to suppress drawing when SkTextBlob bounds does not intersect SkSurface bounds. If bounds is nullptr, SkTextBlob bounds is computed from (x, y) and RunBuffer::glyphs metrics.

Parameters

font	SkFont used for this run
count	number of glyphs
x	horizontal offset within the blob
y	vertical offset within the blob
bounds	optional run bounding box

Return Value

writable glyph buffer

Example

See Also

allocRunPosH allocRunPos

---

const RunBuffer& allocRunPosH(const SkFont& font, int count, SkScalar y,
                              const SkRect* bounds = nullptr)

Returns run with storage for glyphs and positions along baseline. Caller must write count glyphs to RunBuffer::glyphs, and count scalars to RunBuffer::pos; before next call to SkTextBlobBuilder.

RunBuffer::utf8text, and RunBuffer::clusters should be ignored.

Glyphs share metrics in font.

Glyphs are positioned on a baseline at y, using x-axis positions written by caller to RunBuffer::pos.

bounds defines an optional bounding box, used to suppress drawing when SkTextBlob bounds does not intersect SkSurface bounds. If bounds is nullptr, SkTextBlob bounds is computed from y, RunBuffer::pos, and RunBuffer::glyphs metrics.

Parameters

font	SkFont used for this run
count	number of glyphs
y	vertical offset within the blob
bounds	optional run bounding box

Return Value

writable glyph buffer and x-axis position buffer

Example

See Also

allocRunPos allocRun

---

const RunBuffer& allocRunPos(const SkFont& font, int count, const SkRect* bounds = nullptr)

Returns run with storage for glyphs and SkPoint positions. Caller must write count glyphs to RunBuffer::glyphs, and count SkPoint to RunBuffer::pos; before next call to SkTextBlobBuilder.

RunBuffer::utf8text, and RunBuffer::clusters should be ignored.

Glyphs share metrics in font.

Glyphs are positioned using SkPoint written by caller to RunBuffer::pos, using two scalar values for each SkPoint.

bounds defines an optional bounding box, used to suppress drawing when SkTextBlob bounds does not intersect SkSurface bounds. If bounds is nullptr, SkTextBlob bounds is computed from RunBuffer::pos, and RunBuffer::glyphs metrics.

Parameters

font	SkFont used for this run
count	number of glyphs
bounds	optional run bounding box

Return Value

writable glyph buffer and SkPoint buffer

Example

See Also

allocRunPosH allocRun

---

const RunBuffer& allocRun(const SkPaint& font, int count, SkScalar x, SkScalar y,
                          const SkRect* bounds = nullptr)

Deprecated.

---

const RunBuffer& allocRunPosH(const SkPaint& font, int count, SkScalar y,
                              const SkRect* bounds = nullptr)

Deprecated.

---

const RunBuffer& allocRunPos(const SkPaint& font, int count, const SkRect* bounds = nullptr)

Deprecated.