skia2/site/user/api/SkTextBlob_Reference.md

SkTextBlob Reference

Text Blob

Text Blob holds one or more runs of text. Each run associates a string of Glyphs with a position and Paint. Each Paint contains attributes used to define the run text: 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.

Text Blob runs of text use Glyph ID encoding; each run Paint must set Paint Text Encoding to SkPaint::kGlyphID TextEncoding.

Text Blob is constructed with SkTextBlob::MakeFromText or Text Blob Builder. Once created, Text Blob can not be modified.

Overview

Topic	Description
Constructors	functions that construct SkTextBlob
Functions	global and class member functions

Constructor

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

Topic	Description
Deserialize	constructs Text Blob from memory
MakeFromString	constructs Text Blob with one run
MakeFromText	constructs Text Blob with one run

Member Function

SkTextBlob member functions read and modify the structure properties.

Topic	Description
Deserialize	constructs Text Blob from memory
MakeFromString	constructs Text Blob with one run
MakeFromText	constructs Text Blob with one run
bounds	returns conservative bounding box
serialize	writes Text Blob to memory
uniqueID	returns identifier for Text Blob

Class SkTextBlob

Constructor

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

Topic	Description
Deserialize	constructs Text Blob from memory
MakeFromString	constructs Text Blob with one run
MakeFromText	constructs Text Blob with one run

Member_Function

SkTextBlob member functions read and modify the structure properties.

Topic	Description
Deserialize	constructs Text Blob from memory
MakeFromString	constructs Text Blob with one run
MakeFromText	constructs Text Blob with one run
bounds	returns conservative bounding box
serialize	writes Text Blob to memory
uniqueID	returns identifier for Text Blob

SkTextBlob combines multiple text runs into an immutable container. Each text run consists of Glyphs, Paint, and position. Only parts of Paint related to fonts and text rendering are used by run.

bounds

const SkRect& bounds() const

Returns conservative bounding box. Uses Paint associated with each glyph to determine glyph bounds, and unions all bounds. Returned bounds may be larger than the bounds of all Glyphs in runs.

Return Value

conservative bounding box

Example

See Also

SkPath::getBounds

---

uniqueID

uint32_t uniqueID() const

Returns a non-zero value unique among all text blobs.

Return Value

identifier for Text Blob

Example

See Also

SkRefCnt

---

MakeFromText

static sk sp<SkTextBlob> MakeFromText(
            const void* text, size_t byteLength,
                                      const SkPaint& paint)

Creates Text Blob with a single run. text meaning depends on Paint Text Encoding; by default, text is encoded as UTF-8.

paint contains attributes used to define the run text: 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.

Parameters

text	character code points or Glyphs drawn
byteLength	byte length of text array
paint	text size, typeface, text scale, and so on, used to draw

Return Value

Text Blob constructed from one run

Example

See Also

MakeFromString TextBlobBuilder

---

MakeFromString

static sk sp<SkTextBlob> MakeFromString(const char* string, const SkPaint& paint)

Creates Text Blob with a single run. string meaning depends on Paint Text Encoding; by default, string is encoded as UTF-8.

paint contains Paint Font Metrics used to define the run text: 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.

Parameters

string	character code points or Glyphs drawn
paint	text size, typeface, text scale, and so on, used to draw

Return Value

Text Blob constructed from one run

Example

See Also

MakeFromText TextBlobBuilder

---

serialize

size_t serialize(const SkSerialProcs& procs, void* memory, size_t memory_size) const

Writes data to allow later reconstruction of Text Blob. memory points to storage to receive the encoded data, and memory_size describes the size of storage. Returns bytes used if provided storage is large enough to hold all data; otherwise, returns zero.

procs.fTypefaceProc permits supplying a custom function to encode Typeface. If procs.fTypefaceProc is nullptr, default encoding is used. procs.fTypefaceCtx may be used to provide user context to procs.fTypefaceProc; procs.fTypefaceProc is called with a pointer to Typeface and user context.

Parameters

procs	custom serial data encoders; may be nullptr
memory	storage for data
size	size of storage

Return Value

bytes written, or zero if required storage is larger than memory_size

Example

See Also

Deserialize SkSerialProcs

---

sk sp<SkData> serialize(const SkSerialProcs& procs) const

Returns storage containing Data describing Text Blob, using optional custom encoders.

procs.fTypefaceProc permits supplying a custom function to encode Typeface. If procs.fTypefaceProc is nullptr, default encoding is used. procs.fTypefaceCtx may be used to provide user context to procs.fTypefaceProc; procs.fTypefaceProc is called with a pointer to Typeface and user context.

Parameters

procs

custom serial data encoders; may be nullptr

Return Value

storage containing serialized Text Blob

Example

See Also

Deserialize SkData SkSerialProcs

---

Deserialize

static sk sp<SkTextBlob> Deserialize(const void* data, size_t size, const SkDeserialProcs& procs)

Recreates Text Blob that was serialized into data. Returns constructed Text Blob if successful; otherwise, returns nullptr. Fails if size is smaller than required data length, or if data does not permit constructing valid Text Blob.

procs.fTypefaceProc permits supplying a custom function to decode Typeface. If procs.fTypefaceProc is nullptr, default decoding is used. procs.fTypefaceCtx may be used to provide user context to procs.fTypefaceProc; procs.fTypefaceProc is called with a pointer to Typeface data, data byte length, and user context.

Parameters

data	pointer for serial data
size	size of data
procs	custom serial data decoders; may be nullptr

Return Value

Text Blob constructed from data in memory

Example

Text "" replaces "World!", but does not update its metrics. When drawn, "" uses the spacing computed for "World!".

See Also

serialize^[2] SkDeserialProcs

---