skia2/site/user/api/SkTextBlobBuilder_Reference.md

SkTextBlobBuilder Reference

Text Blob Builder

Class SkTextBlobBuilder

Struct

SkTextBlobBuilder uses C++ structs to declare the public data structures and interfaces.

Topic	Description
RunBuffer	storage for Glyphs and Glyph positions

Helper class for constructing SkTextBlob.

Overview

Topic	Description
Constructors	functions that construct SkTextBlobBuilder
Functions	global and class member functions
Struct Declarations	embedded struct members

Class

SkTextBlobBuilder uses C++ classes to declare the public data structures and interfaces.

Topic	Description

Constructor

SkTextBlobBuilder can be constructed or initialized by these functions, including C++ class constructors.

Topic	Description
SkTextBlobBuilder()	constructs with default values
make	constructs Text Blob from bulider
~SkTextBlobBuilder()	deletes storage

Member Function

SkTextBlobBuilder member functions read and modify the structure properties.

Topic	Description
allocRun	returns writable glyph buffer at Point
allocRunPos	returns writable glyph and Point buffers
allocRunPosH	returns writable glyph and x-axis position buffers
make	constructs Text Blob from bulider

Struct SkTextBlobBuilder::RunBuffer

    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.

Member

SkTextBlobBuilder::RunBuffer members may be read and written directly without using a member function.

Topic	Description
clusters	reserved for future use
glyphs	storage for Glyphs in run
pos	storage for positions in run
utf8text	reserved for future use

Members

Type	Name	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

SkTextBlobBuilder()

Constructs empty Text Blob Builder. By default, Text Blob Builder has no runs.

Return Value

empty Text Blob Builder

Example

Example Output

blob equals nullptr

See Also

make SkTextBlob::MakeFromText

---

~SkTextBlobBuilder

~SkTextBlobBuilder()

Deletes data allocated internally by Text Blob Builder.

See Also

SkTextBlobBuilder()

---

make

sk sp<SkTextBlob> make()

Returns Text Blob built from runs of Glyphs added by builder. Returned Text Blob 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 Text Blob Builder to its initial empty state, allowing it to be reused to build a new set of runs.

Return Value

Text Blob or nullptr

Example

Example Output

blob equals nullptr
blob does not equal nullptr
blob equals nullptr

See Also

SkTextBlob::MakeFromText

---

allocRun

const RunBuffer& allocRun(const SkPaint& 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 FontBlobBuilder.

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

Glyphs share Paint Font Metrics in font, including: Typeface, Paint Text Size, Paint Text Scale X, Paint Text Skew X, Paint Text Align, Paint Hinting, Anti Alias, Paint Fake Bold, Font Embedded Bitmaps, Full Hinting Spacing, LCD Text, Linear Text, and Subpixel Text.

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

bounds defines an optional bounding box, used to suppress drawing when Text Blob bounds does not intersect Surface bounds. If bounds is nullptr, Text Blob bounds is computed from (x, y) and RunBuffer.glyphs Paint Font Metrics.

Parameters

font	Paint 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

---

allocRunPosH

const RunBuffer& allocRunPosH(const SkPaint& 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 FontBlobBuilder.

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

Glyphs share Paint Font Metrics in font, including: Typeface, Paint Text Size, Paint Text Scale X, Paint Text Skew X, Paint Text Align, Paint Hinting, Anti Alias, Paint Fake Bold, Font Embedded Bitmaps, Full Hinting Spacing, LCD Text, Linear Text, and Subpixel Text.

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 Text Blob bounds does not intersect Surface bounds. If bounds is nullptr, Text Blob bounds is computed from y, RunBuffer.pos, and RunBuffer.glyphs Paint Font Metrics.

Parameters

font	Paint 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

---

allocRunPos

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

Returns run with storage for Glyphs and Point positions. Caller must write count Glyphs to RunBuffer.glyphs, and count Points to RunBuffer.pos; before next call to FontBlobBuilder.

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

Glyphs share Paint Font Metrics in font, including: Typeface, Paint Text Size, Paint Text Scale X, Paint Text Skew X, Paint Text Align, Paint Hinting, Anti Alias, Paint Fake Bold, Font Embedded Bitmaps, Full Hinting Spacing, LCD Text, Linear Text, and Subpixel Text.

Glyphs are positioned using Points written by caller to RunBuffer.pos, using two Scalar values for each Point.

bounds defines an optional bounding box, used to suppress drawing when Text Blob bounds does not intersect Surface bounds. If bounds is nullptr, Text Blob bounds is computed from RunBuffer.pos, and RunBuffer.glyphs Paint Font Metrics.

Parameters

font	Paint used for this run
count	number of Glyphs
bounds	optional run bounding box

Return Value

writable glyph buffer and Point buffer

Example

See Also

allocRunPosH allocRun

---