skia2/site/user/api/SkPicture_Reference.md

SkPicture Reference

Picture

Class SkPicture

Constructor

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

Topic	Description
MakeFromData	constructs Picture from data
MakeFromStream	constructs Picture from stream
MakePlaceholder	constructs placeholder with unique identifier

Picture records drawing commands made to Canvas. The command stream may be played in whole or in part at a later time.

Picture is an abstract class. Picture may be generated by Picture Recorder or Drawable, or from Picture previously saved to Data or Stream.

Picture may contain any Canvas drawing command, as well as one or more Canvas Matrix or Canvas Clip. Picture has a cull Rect, which is used as a bounding box hint. To limit Picture bounds, use Canvas Clip when recording or drawing Picture.

Overview

Topic	Description
Class Declarations	embedded class members
Constructors	functions that construct SkPicture
Functions	global and class member functions

Class

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

Topic	Description
AbortCallback	utility to stop picture playback

Member Function

SkPicture member functions read and modify the structure properties.

Topic	Description
MakeFromData	constructs Picture from data
MakeFromStream	constructs Picture from stream
MakePlaceholder	constructs placeholder with unique identifier
approximateBytesUsed	returns approximate size
approximateOpCount	returns approximate operation count
cullRect	returns bounds used to record Picture
playback	replays drawing commands on canvas
serialize	writes Picture to Data
uniqueID	returns identifier for Picture

Class SkPicture::AbortCallback

Constructor

SkPicture::AbortCallback can be constructed or initialized by these functions, including C++ class constructors.

Topic	Description
AbortCallback()	defines default constructor
~AbortCallback()	defines default destructor

Member_Function

SkPicture::AbortCallback member functions read and modify the structure properties.

Topic	Description
AbortCallback()	defines default constructor
abort	aborts playback by callback

    class AbortCallback {
    public:
        AbortCallback() {}
        virtual ~AbortCallback() {}
        virtual bool abort = 0;
    };

AbortCallback is an abstract class. An implementation of AbortCallback may passed as a parameter to SkPicture::playback, to stop it before all drawing commands have been processed.

If AbortCallback::abort returns true, SkPicture::playback is interrupted.

AbortCallback

AbortCallback()

Has no effect.

Return Value

abstract class cannot be instantiated

See Also

playback

---

~AbortCallback

virtual ~AbortCallback()

Has no effect.

See Also

playback

---

abort

virtual bool abort() = 0

Stops Picture playback when some condition is met. A subclass of AbortCallback provides an override for abort that can stop SkPicture::playback.

The part of Picture drawn when aborted is undefined. Picture instantiations are free to stop drawing at different points during playback.

If the abort happens inside one or more calls to SkCanvas::save(), stack of Canvas Matrix and Canvas Clip values is restored to its state before SkPicture::playback was called.

Return Value

true to stop playback

See Also

playback

---

Example

JustOneDraw allows the black rectangle to draw but stops playback before the white rectangle appears.

MakeFromStream

static sk sp<SkPicture> MakeFromStream(SkStream* stream, const SkDeserialProcs* procs = nullptr)

Recreates Picture that was serialized into a stream. Returns constructed Picture if successful; otherwise, returns nullptr. Fails if data does not permit constructing valid Picture.

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

Parameters

stream	container for serial data
procs	custom serial data decoders; may be nullptr

Return Value

Picture constructed from stream data

Example

See Also

MakeFromData^[2] SkPictureRecorder

---

MakeFromData

static sk sp<SkPicture> MakeFromData(const SkData* data, const SkDeserialProcs* procs = nullptr)

Recreates Picture that was serialized into data. Returns constructed Picture if successful; otherwise, returns nullptr. Fails if data does not permit constructing valid Picture.

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

Parameters

data	container for serial data
procs	custom serial data decoders; may be nullptr

Return Value

Picture constructed from data

Example

See Also

MakeFromStream SkPictureRecorder

---

static sk sp<SkPicture> MakeFromData(const void* data, size_t size,
                                     const SkDeserialProcs* procs = nullptr)

Parameters

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

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

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

Return Value

Picture constructed from data

Example

See Also

MakeFromStream SkPictureRecorder

---

playback

virtual void playback(SkCanvas* canvas, AbortCallback* callback = nullptr) const = 0

Replays the drawing commands on the specified canvas. In the case that the commands are recorded, each command in the Picture is sent separately to canvas.

To add a single command to draw Picture to recording canvas, call SkCanvas::drawPicture instead.

Parameters

canvas	receiver of drawing commands
callback	allows interruption of playback

Example

See Also

SkCanvas::drawPicture^[2][3][4]

---

cullRect

virtual SkRect cullRect() const = 0

Returns cull Rect for this picture, passed in when Picture was created. Returned Rect does not specify clipping Rect for Picture; cull is hint of Picture bounds.

Picture is free to discard recorded drawing commands that fall outside cull.

Return Value

bounds passed when Picture was created

Example

Picture recorded bounds are smaller than contents; contents outside recorded bounds may be drawn, and are drawn in this example.

See Also

SkCanvas::clipRect^[2][3]

---

uniqueID

uint32_t uniqueID() const

Returns a non-zero value unique among Pictures in Skia process.

Return Value

identifier for Picture

Example

Example Output

empty picture id = 1
placeholder id = 2

See Also

SkRefCnt

---

serialize

sk sp<SkData> serialize(const SkSerialProcs* procs = nullptr) const

Returns storage containing Data describing Picture, using optional custom encoders.

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

Parameters

procs

custom serial data encoders; may be nullptr

Return Value

storage containing serialized Picture

Example

See Also

MakeFromData^[2] SkData SkSerialProcs

---

void serialize(SkWStream* stream, const SkSerialProcs* procs = nullptr) const

Writes picture to stream, using optional custom encoders.

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

Parameters

stream	writable serial data stream
procs	custom serial data encoders; may be nullptr

Example

See Also

MakeFromStream SkWStream SkSerialProcs

---

MakePlaceholder

static sk sp<SkPicture> MakePlaceholder(SkRect cull)

Returns a placeholder SkPicture. Result does not draw, and contains only cull Rect, a hint of its bounds. Result is immutable; it cannot be changed later. Result identifier is unique.

Returned placeholder can be intercepted during playback to insert other commands into Canvas draw stream.

Parameters

cull	placeholder dimensions

Return Value

placeholder with unique identifier

Example

See Also

MakeFromStream MakeFromData^[2] uniqueID

---

approximateOpCount

virtual int approximateOpCount() const = 0

Returns the approximate number of operations in Picture. Returned value may be greater or less than the number of SkCanvas calls recorded: some calls may be recorded as more than one operation, other calls may be optimized away.

Return Value

approximate operation count

Example

See Also

approximateBytesUsed

---

approximateBytesUsed

virtual size_t approximateBytesUsed() const = 0

Returns the approximate byte size of Picture. Does not include large objects referenced by Picture.

Return Value

approximate size

Example

See Also

approximateOpCount

---