#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 picture = recorder.finishRecordingAsPicture(); JustOneDraw callback; picture->playback(canvas, &callback); } ## #Class AbortCallback ## # ------------------------------------------------------------------------------ #Method static sk_sp 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 picture = recorder.finishRecordingAsPicture(); SkDynamicMemoryWStream writableStream; picture->serialize(&writableStream); std::unique_ptr readableStream = writableStream.detachAsStream(); sk_sp copy = SkPicture::MakeFromStream(readableStream.get()); copy->playback(canvas); ## #SeeAlso MakeFromData SkPictureRecorder #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp 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 picture = recorder.finishRecordingAsPicture(); SkDynamicMemoryWStream writableStream; picture->serialize(&writableStream); sk_sp readableData = writableStream.detachAsData(); sk_sp copy = SkPicture::MakeFromData(readableData.get()); copy->playback(canvas); ## #SeeAlso MakeFromStream SkPictureRecorder #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp 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 picture = recorder.finishRecordingAsPicture(); SkDynamicMemoryWStream writableStream; picture->serialize(&writableStream); sk_sp readableData = writableStream.detachAsData(); sk_sp 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 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 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 picture = recorder.finishRecordingAsPicture(); SkDebugf("empty picture id = %d\n", picture->uniqueID()); sk_sp 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 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 picture = recorder.finishRecordingAsPicture(); sk_sp readableData = picture->serialize(); sk_sp 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 picture = recorder.finishRecordingAsPicture(); SkDynamicMemoryWStream writableStream; picture->serialize(&writableStream); sk_sp readableData = writableStream.detachAsData(); sk_sp copy = SkPicture::MakeFromData(readableData->data(), readableData->size()); copy->playback(canvas); ## #SeeAlso MakeFromStream SkWStream SkSerialProcs #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp 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 pict1 = SkPicture::MakePlaceholder({10, 40, 80, 110}); sk_sp 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 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 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 ##