skia2/site/user/api/SkTextBlob_Reference.md
skia-bookmaker fe47c2a60c Update markdown files
Automatic commit by the Housekeeper-Nightly-Bookmaker bot.

TBR=rmistry@google.com
NO_MERGE_BUILDS

Change-Id: I5cbd493c883fb1d65212edc22c1b5258d90a2d3f
Reviewed-on: https://skia-review.googlesource.com/c/174165
Commit-Queue: <skia-bookmaker@skia-swarming-bots.iam.gserviceaccount.com>
Reviewed-by: <skia-bookmaker@skia-swarming-bots.iam.gserviceaccount.com>
2018-12-04 06:38:29 +00:00

17 KiB

SkTextBlob Reference


class SkTextBlob final : public SkNVRefCnt<SkTextBlob> {

    const SkRect& bounds() const;
    uint32_t uniqueID() const;
    static sk_sp<SkTextBlob> MakeFromText(const void* text, size_t byteLength, const SkFont& font,
                                      SkTextEncoding encoding = kUTF8_SkTextEncoding);
    static sk_sp<SkTextBlob> MakeFromString(const char* string, const SkFont& font,
                                    SkTextEncoding encoding = kUTF8_SkTextEncoding);
    size_t serialize(const SkSerialProcs& procs, void* memory, size_t memory_size) const;
    sk_sp<SkData> serialize(const SkSerialProcs& procs) const;
    static sk_sp<SkTextBlob> Deserialize(const void* data, size_t size,
                                         const SkDeserialProcs& procs);
};

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.


const SkRect& bounds()const

Returns conservative bounding box. Uses SkPaint 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


uint32_t uniqueID()const

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

Return Value

identifier for SkTextBlob

Example

See Also

SkRefCnt


static sk_sp<SkTextBlob> MakeFromText(const void* text, size_t byteLength, const SkFont& font,
                                      SkTextEncoding encoding = kUTF8_SkTextEncoding)

Creates Text_Blob with a single run. text meaning depends on Paint_Text_Encoding; by default, text is encoded as UTF-8.

font contains attributes used to define the run text: Typeface, Paint_Text_Size, Paint_Text_Scale_X, Paint_Text_Skew_X, 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
font text size, typeface, text scale, and so on, used to draw
encoding one of: kUTF8_SkTextEncoding, kUTF16_SkTextEncoding, kUTF32_SkTextEncoding, kGlyphID_SkTextEncoding

Return Value

Text_Blob constructed from one run

Example

See Also

MakeFromString SkTextBlobBuilder


static sk_sp<SkTextBlob> MakeFromString(const char* string, const SkFont& font,
                                        SkTextEncoding encoding = kUTF8_SkTextEncoding)

Creates Text_Blob with a single run. string meaning depends on Paint_Text_Encoding; by default, string is encoded as UTF-8.

font contains Paint_Font_Metrics used to define the run text: Typeface, Paint_Text_Size, Paint_Text_Scale_X, Paint_Text_Skew_X, 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
font text size, typeface, text scale, and so on, used to draw
encoding one of: kUTF8_SkTextEncoding, kUTF16_SkTextEncoding, kUTF32_SkTextEncoding, kGlyphID_SkTextEncoding

Return Value

Text_Blob constructed from one run

Example

See Also

MakeFromText SkTextBlobBuilder


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

Writes data to allow later reconstruction of SkTextBlob. 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 SkTypeface. 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 SkTypeface and user context.

Parameters

procs custom serial data encoders; may be nullptr
memory storage for data
memory_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 SkData describing SkTextBlob, using optional custom encoders.

procs.fTypefaceProc permits supplying a custom function to encode SkTypeface. 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 SkTypeface and user context.

Parameters

procs custom serial data encoders; may be nullptr

Return Value

storage containing serialized SkTextBlob

Example

See Also

Deserialize SkData SkSerialProcs


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

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

procs.fTypefaceProc permits supplying a custom function to decode SkTypeface. 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 SkTypeface 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

SkTextBlob constructed from data in memory

Example

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

See Also

serialize SkDeserialProcs