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
## Constructor
SkTextBlob can be constructed or initialized by these functions, including C++ class constructors.
## Member Function
SkTextBlob member functions read and modify the structure properties.
# Class SkTextBlob
## Constructor
SkTextBlob can be constructed or initialized by these functions, including C++ class constructors.
## Member_Function
SkTextBlob member functions read and modify the structure properties.
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
### 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
### 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
### 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!".