#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 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 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 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 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 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 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 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. 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 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 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 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. 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 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. 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 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. 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 placeholder = SkPicture::MakePlaceholder({10, 40, 80, 110}); pictureCanvas->drawPicture(placeholder); sk_sp 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 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 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 ##