diff options
Diffstat (limited to 'docs/SkPicture_Reference.bmh')
| -rw-r--r-- | docs/SkPicture_Reference.bmh | 106 |
1 files changed, 69 insertions, 37 deletions
diff --git a/docs/SkPicture_Reference.bmh b/docs/SkPicture_Reference.bmh index 64561de50e..8ad642aa73 100644 --- a/docs/SkPicture_Reference.bmh +++ b/docs/SkPicture_Reference.bmh @@ -4,8 +4,16 @@ #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. +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 @@ -33,13 +41,11 @@ This base class handles serialization and a few other miscellany. }; ## -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. +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. # ------------------------------------------------------------------------------ @@ -78,8 +84,14 @@ Has no effect. #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. +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 ## @@ -224,10 +236,11 @@ Recreates a picture that was serialized into data. #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. +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 ## @@ -253,8 +266,12 @@ canvas the option of just taking a ref. #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. +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 ## @@ -286,7 +303,7 @@ bounds may be drawn, and are drawn in this example. #In Property #Line # returns identifier for Picture ## -Returns a non-zero value unique among all pictures. +Returns a non-zero value unique among Pictures in Skia process. #Return identifier for Picture ## @@ -312,7 +329,8 @@ placeholder id = 2 #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. +Returns storage containing data describing Picture, using optional custom +encoders. #Param procs custom serial data encoders; may be nullptr ## @@ -368,9 +386,12 @@ Writes picture to stream, using optional custom encoders. #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. +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 ## @@ -378,20 +399,31 @@ This placeholder does not draw anything itself. It has a distinct uniqueID() #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} +#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 +#SeeAlso MakeFromStream MakeFromData uniqueID #Method ## @@ -401,9 +433,9 @@ id:2 bounds:{10, 40, 80, 110} #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 +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 ## @@ -432,7 +464,7 @@ calls may be optimized away. #Line # returns approximate size ## Returns the approximate byte size of Picture. Does not include large objects -referenced Picture. +referenced by Picture. #Return approximate size ## |