d2ca79c271
new batch of docs Docs-Preview: https://skia.org/?cl=141244 Bug: skia: Change-Id: I5a285778baaee2734495374adeb7359d524e47e3 Reviewed-on: https://skia-review.googlesource.com/141244 Reviewed-by: Cary Clark <caryclark@skia.org> Commit-Queue: Cary Clark <caryclark@skia.org> Auto-Submit: Cary Clark <caryclark@skia.org>
522 lines
17 KiB
Plaintext
522 lines
17 KiB
Plaintext
#Topic Picture
|
|
#Alias Pictures ##
|
|
#Alias Picture_Reference ##
|
|
|
|
#Class SkPicture
|
|
|
|
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.
|
|
|
|
#Subtopic Overview
|
|
#Populate
|
|
##
|
|
|
|
#Subtopic Class
|
|
#Populate
|
|
##
|
|
|
|
#Subtopic Member_Function
|
|
#Populate
|
|
##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Class AbortCallback
|
|
#Line # utility to stop picture playback ##
|
|
|
|
#Code
|
|
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.
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method AbortCallback()
|
|
#In Constructor
|
|
#Line # defines default constructor ##
|
|
Has no effect.
|
|
|
|
#Return abstract class cannot be instantiated ##
|
|
|
|
#NoExample
|
|
##
|
|
|
|
#SeeAlso playback
|
|
|
|
#Method ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method virtual ~AbortCallback()
|
|
#In Constructor
|
|
#Line # defines default destructor ##
|
|
Has no effect.
|
|
|
|
#NoExample
|
|
##
|
|
|
|
#SeeAlso playback
|
|
|
|
#Method ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method virtual bool abort() = 0
|
|
#In Utility
|
|
#Line # aborts playback by callback ##
|
|
|
|
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 true to stop playback ##
|
|
|
|
#NoExample
|
|
##
|
|
|
|
#SeeAlso playback
|
|
|
|
#Method ##
|
|
|
|
#Example
|
|
#Description
|
|
JustOneDraw allows the black rectangle to draw but stops playback before the
|
|
white rectangle appears.
|
|
##
|
|
#Function
|
|
class JustOneDraw : public SkPicture::AbortCallback {
|
|
public:
|
|
bool abort() override { return fCalls++ > 0; }
|
|
private:
|
|
int fCalls = 0;
|
|
};
|
|
##
|
|
|
|
void draw(SkCanvas* canvas) {
|
|
SkPictureRecorder recorder;
|
|
SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});
|
|
SkPaint paint;
|
|
pictureCanvas->drawRect(SkRect::MakeWH(200, 200), paint);
|
|
paint.setColor(SK_ColorWHITE);
|
|
pictureCanvas->drawRect(SkRect::MakeLTRB(20, 20, 180, 180), paint);
|
|
sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
|
|
JustOneDraw callback;
|
|
picture->playback(canvas, &callback);
|
|
}
|
|
|
|
##
|
|
|
|
#Class AbortCallback ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method static sk_sp<SkPicture> MakeFromStream(SkStream* stream,
|
|
const SkDeserialProcs* procs = nullptr)
|
|
#In Constructor
|
|
#Line # constructs Picture from stream ##
|
|
|
|
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.
|
|
|
|
#Param stream container for serial data ##
|
|
#Param procs custom serial data decoders; may be nullptr ##
|
|
|
|
#Return Picture constructed from stream data ##
|
|
|
|
#Example
|
|
SkPictureRecorder recorder;
|
|
SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});
|
|
SkPaint paint;
|
|
pictureCanvas->drawRect(SkRect::MakeWH(200, 200), paint);
|
|
paint.setColor(SK_ColorWHITE);
|
|
pictureCanvas->drawRect(SkRect::MakeLTRB(20, 20, 180, 180), paint);
|
|
sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
|
|
SkDynamicMemoryWStream writableStream;
|
|
picture->serialize(&writableStream);
|
|
std::unique_ptr<SkStreamAsset> readableStream = writableStream.detachAsStream();
|
|
sk_sp<SkPicture> copy = SkPicture::MakeFromStream(readableStream.get());
|
|
copy->playback(canvas);
|
|
##
|
|
|
|
#SeeAlso MakeFromData SkPictureRecorder
|
|
|
|
#Method ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method static sk_sp<SkPicture> MakeFromData(const SkData* data,
|
|
const SkDeserialProcs* procs = nullptr)
|
|
#In Constructor
|
|
#Line # constructs Picture from data ##
|
|
|
|
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.
|
|
|
|
#Param data container for serial data ##
|
|
#Param procs custom serial data decoders; may be nullptr ##
|
|
|
|
#Return Picture constructed from data ##
|
|
|
|
#Example
|
|
SkPictureRecorder recorder;
|
|
SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});
|
|
SkPaint paint;
|
|
pictureCanvas->drawRect(SkRect::MakeWH(200, 200), paint);
|
|
paint.setColor(SK_ColorWHITE);
|
|
pictureCanvas->drawRect(SkRect::MakeLTRB(20, 20, 180, 180), paint);
|
|
sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
|
|
SkDynamicMemoryWStream writableStream;
|
|
picture->serialize(&writableStream);
|
|
sk_sp<SkData> readableData = writableStream.detachAsData();
|
|
sk_sp<SkPicture> copy = SkPicture::MakeFromData(readableData.get());
|
|
copy->playback(canvas);
|
|
##
|
|
|
|
#SeeAlso MakeFromStream SkPictureRecorder
|
|
|
|
#Method ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method static sk_sp<SkPicture> MakeFromData(const void* data, size_t size,
|
|
const SkDeserialProcs* procs = nullptr)
|
|
|
|
#Param data pointer to serial data ##
|
|
#Param size size of data ##
|
|
#Param 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 Picture constructed from data ##
|
|
|
|
#Example
|
|
SkPictureRecorder recorder;
|
|
SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});
|
|
SkPaint paint;
|
|
pictureCanvas->drawRect(SkRect::MakeWH(200, 200), paint);
|
|
paint.setColor(SK_ColorWHITE);
|
|
pictureCanvas->drawRect(SkRect::MakeLTRB(20, 20, 180, 180), paint);
|
|
sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
|
|
SkDynamicMemoryWStream writableStream;
|
|
picture->serialize(&writableStream);
|
|
sk_sp<SkData> readableData = writableStream.detachAsData();
|
|
sk_sp<SkPicture> copy = SkPicture::MakeFromData(readableData->data(), readableData->size());
|
|
copy->playback(canvas);
|
|
##
|
|
|
|
#SeeAlso MakeFromStream SkPictureRecorder
|
|
|
|
#Method ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method virtual void playback(SkCanvas* canvas, AbortCallback* callback = nullptr) const = 0
|
|
#In Action
|
|
#Line # replays drawing commands on canvas ##
|
|
|
|
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.
|
|
|
|
#Param canvas receiver of drawing commands ##
|
|
#Param callback allows interruption of playback ##
|
|
|
|
#Example
|
|
SkPictureRecorder recorder;
|
|
SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});
|
|
SkPaint paint;
|
|
pictureCanvas->drawRect(SkRect::MakeWH(200, 200), paint);
|
|
paint.setColor(SK_ColorWHITE);
|
|
pictureCanvas->drawRect(SkRect::MakeLTRB(20, 20, 180, 180), paint);
|
|
sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
|
|
picture->playback(canvas);
|
|
##
|
|
|
|
#SeeAlso SkCanvas::drawPicture
|
|
|
|
#Method ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method virtual SkRect cullRect() const = 0
|
|
#In Property
|
|
#Line # returns bounds used to record Picture ##
|
|
|
|
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 bounds passed when Picture was created ##
|
|
|
|
#Example
|
|
#Description
|
|
Picture recorded bounds are smaller than contents; contents outside recorded
|
|
bounds may be drawn, and are drawn in this example.
|
|
##
|
|
SkPictureRecorder recorder;
|
|
SkCanvas* pictureCanvas = recorder.beginRecording({64, 64, 192, 192});
|
|
SkPaint paint;
|
|
pictureCanvas->drawRect(SkRect::MakeWH(200, 200), paint);
|
|
paint.setColor(SK_ColorWHITE);
|
|
pictureCanvas->drawRect(SkRect::MakeLTRB(20, 20, 180, 180), paint);
|
|
sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
|
|
picture->playback(canvas);
|
|
paint.setBlendMode(SkBlendMode::kModulate);
|
|
paint.setColor(0x40404040);
|
|
canvas->drawRect(picture->cullRect(), paint);
|
|
##
|
|
|
|
#SeeAlso SkCanvas::clipRect
|
|
|
|
#Method ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method uint32_t uniqueID() const
|
|
#In Property
|
|
#Line # returns identifier for Picture ##
|
|
|
|
Returns a non-zero value unique among Pictures in Skia process.
|
|
|
|
#Return identifier for Picture ##
|
|
|
|
#Example
|
|
SkPictureRecorder recorder;
|
|
recorder.beginRecording({0, 0, 0, 0});
|
|
sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
|
|
SkDebugf("empty picture id = %d\n", picture->uniqueID());
|
|
sk_sp<SkPicture> placeholder = SkPicture::MakePlaceholder({0, 0, 0, 0});
|
|
SkDebugf("placeholder id = %d\n", placeholder->uniqueID());
|
|
#StdOut
|
|
empty picture id = 1
|
|
placeholder id = 2
|
|
##
|
|
##
|
|
|
|
#SeeAlso SkRefCnt
|
|
|
|
#Method ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method sk_sp<SkData> serialize(const SkSerialProcs* procs = nullptr) const
|
|
#In Utility
|
|
#Line # writes Picture to Data ##
|
|
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.
|
|
|
|
#Param procs custom serial data encoders; may be nullptr ##
|
|
|
|
#Return storage containing serialized Picture ##
|
|
|
|
#Example
|
|
SkPictureRecorder recorder;
|
|
SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});
|
|
SkPaint paint;
|
|
pictureCanvas->drawRect(SkRect::MakeWH(200, 200), paint);
|
|
paint.setColor(SK_ColorWHITE);
|
|
pictureCanvas->drawRect(SkRect::MakeLTRB(20, 20, 180, 180), paint);
|
|
sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
|
|
sk_sp<SkData> readableData = picture->serialize();
|
|
sk_sp<SkPicture> copy = SkPicture::MakeFromData(readableData->data(), readableData->size());
|
|
copy->playback(canvas);
|
|
##
|
|
|
|
#SeeAlso MakeFromData SkData SkSerialProcs
|
|
|
|
#Method ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method 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.
|
|
|
|
#Param stream writable serial data stream ##
|
|
#Param procs custom serial data encoders; may be nullptr ##
|
|
|
|
#Example
|
|
SkPictureRecorder recorder;
|
|
SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});
|
|
SkPaint paint;
|
|
pictureCanvas->drawRect(SkRect::MakeWH(200, 200), paint);
|
|
paint.setColor(SK_ColorWHITE);
|
|
pictureCanvas->drawRect(SkRect::MakeLTRB(20, 20, 180, 180), paint);
|
|
sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
|
|
SkDynamicMemoryWStream writableStream;
|
|
picture->serialize(&writableStream);
|
|
sk_sp<SkData> readableData = writableStream.detachAsData();
|
|
sk_sp<SkPicture> copy = SkPicture::MakeFromData(readableData->data(), readableData->size());
|
|
copy->playback(canvas);
|
|
##
|
|
|
|
#SeeAlso MakeFromStream SkWStream SkSerialProcs
|
|
|
|
#Method ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method static sk_sp<SkPicture> MakePlaceholder(SkRect cull)
|
|
#In Constructor
|
|
#Line # constructs placeholder with unique identifier ##
|
|
|
|
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.
|
|
|
|
#Param cull placeholder dimensions
|
|
##
|
|
|
|
#Return placeholder with unique identifier ##
|
|
|
|
#Example
|
|
#Function
|
|
class MyCanvas : public SkCanvas {
|
|
public:
|
|
MyCanvas(SkCanvas* c) : canvas(c) {}
|
|
void onDrawPicture(const SkPicture* picture, const SkMatrix* ,
|
|
const SkPaint* ) override {
|
|
const SkRect rect = picture->cullRect();
|
|
SkPaint redPaint;
|
|
redPaint.setColor(SK_ColorRED);
|
|
canvas->drawRect(rect, redPaint);
|
|
}
|
|
|
|
SkCanvas* canvas;
|
|
};
|
|
##
|
|
SkPictureRecorder recorder;
|
|
SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});
|
|
sk_sp<SkPicture> placeholder = SkPicture::MakePlaceholder({10, 40, 80, 110});
|
|
pictureCanvas->drawPicture(placeholder);
|
|
sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
|
|
MyCanvas myCanvas(canvas);
|
|
myCanvas.drawPicture(picture);
|
|
##
|
|
|
|
#SeeAlso MakeFromStream MakeFromData uniqueID
|
|
|
|
#Method ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method virtual int approximateOpCount() const = 0
|
|
#In Property
|
|
#Line # returns approximate operation count ##
|
|
|
|
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 approximate operation count ##
|
|
|
|
#Example
|
|
SkPictureRecorder recorder;
|
|
SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});
|
|
SkPaint paint;
|
|
pictureCanvas->drawRect(SkRect::MakeWH(200, 200), paint);
|
|
paint.setColor(SK_ColorWHITE);
|
|
pictureCanvas->drawRect(SkRect::MakeLTRB(20, 20, 180, 180), paint);
|
|
sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
|
|
picture->playback(canvas);
|
|
std::string opCount = "approximate op count: " + std::to_string(picture->approximateOpCount());
|
|
canvas->drawString(opCount.c_str(), 50, 220, SkPaint());
|
|
##
|
|
|
|
#SeeAlso approximateBytesUsed
|
|
|
|
#Method ##
|
|
|
|
# ------------------------------------------------------------------------------
|
|
|
|
#Method virtual size_t approximateBytesUsed() const = 0
|
|
#In Property
|
|
#Line # returns approximate size ##
|
|
|
|
Returns the approximate byte size of Picture. Does not include large objects
|
|
referenced by Picture.
|
|
|
|
#Return approximate size ##
|
|
|
|
#Example
|
|
SkPictureRecorder recorder;
|
|
SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});
|
|
SkPaint paint;
|
|
pictureCanvas->drawRect(SkRect::MakeWH(200, 200), paint);
|
|
paint.setColor(SK_ColorWHITE);
|
|
pictureCanvas->drawRect(SkRect::MakeLTRB(20, 20, 180, 180), paint);
|
|
sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();
|
|
picture->playback(canvas);
|
|
std::string opCount = "approximate bytes used: " + std::to_string(picture->approximateBytesUsed());
|
|
canvas->drawString(opCount.c_str(), 20, 220, SkPaint());
|
|
##
|
|
|
|
#SeeAlso approximateOpCount
|
|
|
|
#Method ##
|
|
|
|
#Class SkPicture ##
|
|
|
|
#Topic Picture ##
|