SkPicture Reference
===
# Picture
# Class SkPicture
## Constructor
SkPicture can be constructed or initialized by these functions, including C++ class constructors.
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
## Class
SkPicture uses C++ classes to declare the public data structures and interfaces.
## Member Function
SkPicture member functions read and modify the structure properties.
# Class SkPicture::AbortCallback
## Constructor
SkPicture::AbortCallback can be constructed or initialized by these functions, including C++ class constructors.
## Member_Function
SkPicture::AbortCallback member functions read and modify the structure properties.
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
### 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
data |
pointer to serial data |
size |
size of data |
procs |
custom serial data decoders; may be nullptr |
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.
### 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
### 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
---