Replace a hunk of documentation in docs/*.bmh with #Populate, which instructs bookmaker to retrieve the documentation from include/core. Check spelling for all documentation retrieved from include/core against Skia declarations and a list of words in spelling.txt. TBR=caryclark@google.com Docs-Preview: https://skia.org/?cl=163491 Bug: skia: Change-Id: If057c3a1336e312ad59c084a3a130f0276802496 Reviewed-on: https://skia-review.googlesource.com/c/163491 Commit-Queue: Cary Clark <caryclark@skia.org> Reviewed-by: Cary Clark <caryclark@skia.org> Auto-Submit: Cary Clark <caryclark@skia.org>
23 KiB
SkPicture Reference
class SkPicture : public SkRefCnt { public: static sk_sp<SkPicture> MakeFromStream(SkStream* stream, const SkDeserialProcs* procs = nullptr); static sk_sp<SkPicture> MakeFromData(const SkData* data, const SkDeserialProcs* procs = nullptr); static sk_sp<SkPicture> MakeFromData(const void* data, size_t size, const SkDeserialProcs* procs = nullptr); class AbortCallback { public: AbortCallback(); virtual ~AbortCallback(); virtual bool abort() = 0; }; virtual void playback(SkCanvas* canvas, AbortCallback* callback = nullptr) const = 0; virtual SkRect cullRect() const = 0; uint32_t uniqueID() const; sk_sp<SkData> serialize(const SkSerialProcs* procs = nullptr) const; void serialize(SkWStream* stream, const SkSerialProcs* procs = nullptr) const; static sk_sp<SkPicture> MakePlaceholder(SkRect cull); virtual int approximateOpCount() const = 0; virtual size_t approximateBytesUsed() const = 0; };
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.
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()
Has no effect.
Return Value
abstract class cannot be instantiated
See Also
virtual ~AbortCallback()
Has no effect.
See Also
virtual bool abort() = 0
Stops SkPicture playback when some condition is met. A subclass of AbortCallback provides an override for abort() that can stop SkPicture::playback.
The part of SkPicture drawn when aborted is undefined. SkPicture 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 SkCanvas matrix and SkCanvas clip values is restored to its state before SkPicture::playback was called.
Return Value
true to stop playback
See Also
Example
static sk sp<SkPicture> MakeFromStream(SkStream* stream, const SkDeserialProcs* procs = nullptr)
Recreates SkPicture that was serialized into a stream. Returns constructed SkPicture if successful; otherwise, returns nullptr. Fails if data does not permit constructing valid SkPicture.
procs->fPictureProc permits supplying a custom function to decode SkPicture. 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
SkPicture constructed from stream data
Example
See Also
MakeFromData[2] SkPictureRecorder
static sk sp<SkPicture> MakeFromData(const SkData* data, const SkDeserialProcs* procs = nullptr)
Recreates SkPicture that was serialized into data. Returns constructed SkPicture if successful; otherwise, returns nullptr. Fails if data does not permit constructing valid SkPicture.
procs->fPictureProc permits supplying a custom function to decode SkPicture. 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
SkPicture 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 |
Return Value
SkPicture constructed from data
Example
See Also
MakeFromStream SkPictureRecorder
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 SkPicture is sent separately to canvas.
To add a single command to draw SkPicture 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]
virtual SkRect cullRect() const = 0
Returns cull SkRect for this picture, passed in when SkPicture was created. Returned SkRect does not specify clipping SkRect for SkPicture; cull is hint of SkPicture bounds.
SkPicture is free to discard recorded drawing commands that fall outside cull.
Return Value
bounds passed when SkPicture was created
Example
See Also
uint32_t uniqueID() const
Returns a non-zero value unique among SkPicture in Skia process.
Return Value
identifier for SkPicture
Example
Example Output
empty picture id = 1
placeholder id = 2
See Also
sk sp<SkData> serialize(const SkSerialProcs* procs = nullptr) const
Returns storage containing SkData describing SkPicture, using optional custom encoders.
procs->fPictureProc permits supplying a custom function to encode SkPicture. 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 SkPicture and user context.
Parameters
procs |
custom serial data encoders; may be nullptr |
Return Value
storage containing serialized SkPicture
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 SkPicture. 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 SkPicture and user context.
Parameters
stream |
writable serial data stream |
procs |
custom serial data encoders; may be nullptr |
Example
See Also
MakeFromStream SkWStream SkSerialProcs
static sk sp<SkPicture> MakePlaceholder(SkRect cull)
Returns a placeholder SkPicture. Result does not draw, and contains only cull SkRect, 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 SkCanvas draw stream.
Parameters
cull |
placeholder dimensions |
Return Value
placeholder with unique identifier
Example
See Also
MakeFromStream MakeFromData[2] uniqueID
virtual int approximateOpCount() const = 0
Returns the approximate number of operations in SkPicture. 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
virtual size_t approximateBytesUsed() const = 0
Returns the approximate byte size of SkPicture. Does not include large objects referenced by SkPicture.
Return Value
approximate size