path: root/docs/SkPicture_Reference.bmh

#Topic Picture
#Alias Pictures ##
#Alias Picture_Reference ##

#Class SkPicture

An SkPicture records drawing commands made to a canvas to be played back at a later time.
This base class handles serialization and a few other miscellany.

#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;
    };
##

Subclasses of this can be passed to playback(). During the playback
of the picture, this callback will periodically be invoked. If its
abort() returns true, then picture playback will be interrupted.
The resulting drawing is undefined, as there is no guarantee how often the
callback will be invoked. If the abort happens inside some level of nested
calls to save(), restore will automatically be called to return the state
to the same level it was before the playback call was made.

# ------------------------------------------------------------------------------

#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 playback() from
drawing the entire picture.

#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 a picture that was serialized into a stream.

#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 a picture that was serialized into data.

#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 a picture that was serialized into data.

#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. Note that
this has the effect of unfurling this picture into the destination
canvas. Using the SkCanvas::drawPicture entry point gives the destination
canvas the option of just taking a ref.

#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.
Ops recorded into this picture that attempt to draw outside the cull might not be drawn.

#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 all pictures.

#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.

#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.

#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.
This placeholder does not draw anything itself.  It has a distinct uniqueID()
(just like all Pictures) and will always be visible to SkSerialProcs.

#Param cull  placeholder dimensions
##

#Return placeholder with unique identifier ##

#Example
sk_sp<SkPicture> pict1 = SkPicture::MakePlaceholder({10, 40, 80, 110});
sk_sp<SkPicture> pict2 = SkPicture::MakePlaceholder({10, 40, 80, 110});
for (auto pict : { pict1, pict2 } ) {
    SkRect bounds = pict->cullRect();
    SkDebugf("id:%d bounds:{%g, %g, %g, %g}\n", pict->uniqueID(), 
             bounds.fLeft, bounds.fTop, bounds.fRight, bounds.fBottom);
}
#StdOut
id:1 bounds:{10, 40, 80, 110}
id:2 bounds:{10, 40, 80, 110}
##
##

#SeeAlso MakeFromStream MakeFromData

#Method ##

# ------------------------------------------------------------------------------

#Method virtual int approximateOpCount() const = 0
#In Property
#Line # returns approximate operation count ##

Returns the approximate number of operations in this picture.  This
number may be greater or less than the number of SkCanvas calls
recorded: some calls may be recorded as more than one operation, or some
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 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 ##