polish picture and rrect docs

TBR=caryclark@google.com

Docs-Preview: https://skia.org/?cl=141263
Bug: skia:6818
Change-Id: I33a197892b3dd5788499dda9dd9e95ddab861388
Reviewed-on: https://skia-review.googlesource.com/141263
Commit-Queue: Cary Clark <caryclark@skia.org>
Auto-Submit: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>

2 files changed, 73 insertions, 41 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 ##
 
diff --git a/docs/SkRRect_Reference.bmh b/docs/SkRRect_Reference.bmh
index 4b1a403e14..633239adde 100644
--- a/docs/SkRRect_Reference.bmh
+++ b/docs/SkRRect_Reference.bmh
@@ -5,15 +5,15 @@
 #Class SkRRect
 
 SkRRect describes a rounded rectangle with a bounds and a pair of radii for each corner.
-The bounds and radii can be set so that SkRRect describes a rectangle with sharp corners,
-a Circle, an Oval, or a rectangle with one or more rounded corners.
+The bounds and radii can be set so that SkRRect describes: a rectangle with sharp corners;
+a Circle; an Oval; or a rectangle with one or more rounded corners.
 
 SkRRect allows implementing CSS properties that describe rounded corners.
 SkRRect may have up to eight different radii, one for each axis on each of its four
 corners.
 
 SkRRect may modify the provided parameters when initializing bounds and radii.
-If either axis radii is zero or less, radii are stored as zero; corner is square.
+If either axis radii is zero or less: radii are stored as zero; corner is square.
 If corner curves overlap, radii are proportionally reduced to fit within bounds.
 
 #Subtopic Overview
@@ -170,7 +170,7 @@ less than half the height, or both.
 #Line # non-zero width and height with axis-aligned radii ##
 Round_Rect has width and height. Left x-radii are equal, top
 y-radii are equal, right x-radii are equal, and bottom y-radii
-are equal. The radii do not describe a rect, oval, or simple type.
+are equal. The radii do not describe Rect, Oval, or simple type.
 
 The centers of the corner ellipses form an axis-aligned rectangle
 that divides the Round_Rect into nine rectangular patches; an