From f960398f331912adceb3455cd10c65e33ce184e0 Mon Sep 17 00:00:00 2001 From: Cary Clark Date: Tue, 17 Jul 2018 08:20:27 -0400 Subject: 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 Auto-Submit: Cary Clark Reviewed-by: Cary Clark --- site/user/api/SkCanvas_Reference.md | 2 +- site/user/api/SkImageInfo_Reference.md | 6 +-- site/user/api/SkImage_Reference.md | 4 +- site/user/api/SkMatrix_Reference.md | 2 +- site/user/api/SkPaint_Reference.md | 6 +-- site/user/api/SkPath_Reference.md | 6 +-- site/user/api/SkPicture_Reference.md | 86 +++++++++++++++++++--------------- site/user/api/SkRRect_Reference.md | 8 ++-- site/user/api/SkRect_Reference.md | 2 +- site/user/api/catalog.htm | 15 +++--- 10 files changed, 75 insertions(+), 62 deletions(-) (limited to 'site') diff --git a/site/user/api/SkCanvas_Reference.md b/site/user/api/SkCanvas_Reference.md index d7da6132c7..75bf7645f8 100644 --- a/site/user/api/SkCanvas_Reference.md +++ b/site/user/api/SkCanvas_Reference.md @@ -4749,7 +4749,7 @@ error at the image edges. ### Example -
redBorder contains a black and white checkerboard bordered by red. +
redBorder contains a black and white checkerboard bordered by red. redBorder is drawn scaled by 16 on the left. The middle and right bitmaps are filtered checkerboards. Drawing the checkerboard with kStrict SrcRectConstraint shows only a blur of black and white. diff --git a/site/user/api/SkImageInfo_Reference.md b/site/user/api/SkImageInfo_Reference.md index 0156143d67..e1642271be 100644 --- a/site/user/api/SkImageInfo_Reference.md +++ b/site/user/api/SkImageInfo_Reference.md @@ -690,7 +690,7 @@ draw all colors possible to a kRGB_101010x_S ### Example -
+
### See Also @@ -1469,7 +1469,7 @@ created Image Info ### Example -
Top gradient is drawn to offScreen without Color Space. It is darker than middle +
Top gradient is drawn to offScreen without Color Space. It is darker than middle gradient, drawn to offScreen with sRGB Color Space. Bottom gradient shares bits with middle, but does not specify the Color Space in noColorSpaceBitmap. A source without Color Space is treated as sRGB; the bottom gradient is identical to the @@ -1870,7 +1870,7 @@ Returns Color Space, the range of colors. ### Example -
SkColorSpace::MakeSRGBLinear creates Color Space with linear gamma +
SkColorSpace::MakeSRGBLinear creates Color Space with linear gamma and an sRGB gamut. This Color Space gamma is not close to sRGB gamma.
diff --git a/site/user/api/SkImage_Reference.md b/site/user/api/SkImage_Reference.md index 16fa9fb6f8..ad21311548 100644 --- a/site/user/api/SkImage_Reference.md +++ b/site/user/api/SkImage_Reference.md @@ -1053,7 +1053,7 @@ created Image, or nullptr ### Example -
+
### See Also @@ -2300,7 +2300,7 @@ partial or full Image, or nullptr ### Example -
+
### See Also diff --git a/site/user/api/SkMatrix_Reference.md b/site/user/api/SkMatrix_Reference.md index 5f5aa11e77..b780eb27e1 100644 --- a/site/user/api/SkMatrix_Reference.md +++ b/site/user/api/SkMatrix_Reference.md @@ -4920,7 +4920,7 @@ true if dst is equivalent to mapped
+
### See Also diff --git a/site/user/api/SkPaint_Reference.md b/site/user/api/SkPaint_Reference.md index 3acb9303d6..342579d231 100644 --- a/site/user/api/SkPaint_Reference.md +++ b/site/user/api/SkPaint_Reference.md @@ -4037,7 +4037,7 @@ Does not alter Typeface Glyphs represented by text ### Example -
Bounds of Glyphs increase for stroked text, but text advance remains the same. +
Bounds of Glyphs increase for stroked text, but text advance remains the same. The underlines show the text advance, spaced to keep them distinct.
diff --git a/site/user/api/SkPath_Reference.md b/site/user/api/SkPath_Reference.md index e03e5c3c3c..9442e4d14a 100644 --- a/site/user/api/SkPath_Reference.md +++ b/site/user/api/SkPath_Reference.md @@ -3698,7 +3698,7 @@ The length of Vector from (Arc sweep is always less than 180 degrees. If radius is zero, or if tangents are nearly parallel, arcTo appends Line from last Path Point to (x1, y1). @@ -5454,7 +5454,7 @@ from output. ### Example -
+
#### Example Output @@ -6035,7 +6035,7 @@ true if last kLine Verb was generated by +
#### Example Output diff --git a/site/user/api/SkPicture_Reference.md b/site/user/api/SkPicture_Reference.md index 0992737b04..1d8c1bbc84 100644 --- a/site/user/api/SkPicture_Reference.md +++ b/site/user/api/SkPicture_Reference.md @@ -26,8 +26,16 @@ SkPicture can be constructed or initialized by these functions, including C++ cl -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. ## Overview @@ -134,13 +142,11 @@ SkPicture member functions read and modify the structure properties. virtual -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. ## AbortCallback @@ -184,8 +190,14 @@ virtual bool abort() = 0 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 Value @@ -312,10 +324,11 @@ Recreates a picture that was serialized into playback(SkCanvas* canvas, AbortCallback* callback = nullptr) const = 0 -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. ### Parameters @@ -344,8 +357,12 @@ this has the effect of unfurling this picture into the destination virtual SkRect cullRect() const = 0 -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 Value @@ -370,7 +387,7 @@ bounds may be drawn, and are drawn in this example. uint32_t uniqueID() const -Returns a non-zero value unique among all pictures. +Returns a non-zero value unique among Pictures in Skia process. ### Return Value @@ -402,7 +419,8 @@ placeholder id = 2 sk sp<SkData> serialize(const SkSerialProcs* procs = nullptr) const -Returns storage containing data describing Picture, using optional custom encoders. +Returns storage containing data describing Picture, using optional custom +encoders. ### Parameters @@ -460,9 +478,12 @@ Writes picture to stream, using opti static sk sp<SkPicture> MakePlaceholder(SkRect cull) -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. ### Parameters @@ -477,20 +498,11 @@ placeholder with unique identifier ### Example -
- -#### Example Output - -~~~~ -id:1 bounds:{10, 40, 80, 110} -id:2 bounds:{10, 40, 80, 110} -~~~~ - -
+
### See Also -MakeFromStream MakeFromData[2] +MakeFromStream MakeFromData[2] uniqueID --- @@ -501,9 +513,9 @@ id:2 bounds:{10, 40, 80, 110} virtual int approximateOpCount() const = 0 -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 Value @@ -528,7 +540,7 @@ virtual size_t approximateBytesUsed Returns the approximate byte size of Picture. Does not include large objects -referenced Picture. +referenced by Picture. ### Return Value diff --git a/site/user/api/SkRRect_Reference.md b/site/user/api/SkRRect_Reference.md index e83c3cfe6b..aa43f16ae5 100644 --- a/site/user/api/SkRRect_Reference.md +++ b/site/user/api/SkRRect_Reference.md @@ -84,15 +84,15 @@ SkRRect global, struct, and class related member funct 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. ## Overview @@ -481,7 +481,7 @@ less than half the height, or both. 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 diff --git a/site/user/api/SkRect_Reference.md b/site/user/api/SkRect_Reference.md index 08364fcb84..e0402bf2f6 100644 --- a/site/user/api/SkRect_Reference.md +++ b/site/user/api/SkRect_Reference.md @@ -2985,7 +2985,7 @@ Has no effect if r is empty. Otherwise, if +
#### Example Output diff --git a/site/user/api/catalog.htm b/site/user/api/catalog.htm index 7ad0dc349d..aede7441de 100644 --- a/site/user/api/catalog.htm +++ b/site/user/api/catalog.htm @@ -2372,13 +2372,6 @@ "file": "SkPath_Reference", "name": "SkPath::writeToMemory", "stdout": "path is equal to copy\\n" - }, - "SkPicture_MakePlaceholder": { - "code": "void draw(SkCanvas* canvas) {\n sk_sp pict1 = SkPicture::MakePlaceholder({10, 40, 80, 110});\n sk_sp pict2 = SkPicture::MakePlaceholder({10, 40, 80, 110});\n for (auto pict : { pict1, pict2 } ) {\n SkRect bounds = pict->cullRect();\n SkDebugf(\"id:%d bounds:{%g, %g, %g, %g}\\n\", pict->uniqueID(), \n bounds.fLeft, bounds.fTop, bounds.fRight, bounds.fBottom);\n }\n}", - "hash": "32f84819483a906ede9c5525801845ef", - "file": "SkPicture_Reference", - "name": "SkPicture::MakePlaceholder", - "stdout": "id:1 bounds:{10, 40, 80, 110}\\nid:2 bounds:{10, 40, 80, 110}\\n" }, "SkPicture_uniqueID": { "code": "void draw(SkCanvas* canvas) {\n SkPictureRecorder recorder;\n recorder.beginRecording({0, 0, 0, 0});\n sk_sp picture = recorder.finishRecordingAsPicture();\n SkDebugf(\"empty picture id = %d\\n\", picture->uniqueID());\n sk_sp placeholder = SkPicture::MakePlaceholder({0, 0, 0, 0});\n SkDebugf(\"placeholder id = %d\\n\", placeholder->uniqueID());\n}", @@ -7198,6 +7191,14 @@ "hash": "404fb42560a289c2004cad1caf3b96de", "file": "SkPicture_Reference", "name": "SkPicture::MakeFromStream" +}, + "SkPicture_MakePlaceholder": { + "code": "class MyCanvas : public SkCanvas {\npublic:\n MyCanvas(SkCanvas* c) : canvas(c) {}\n void onDrawPicture(const SkPicture* picture, const SkMatrix* ,\n const SkPaint* ) override {\n const SkRect rect = picture->cullRect();\n SkPaint redPaint;\n redPaint.setColor(SK_ColorRED);\n canvas->drawRect(rect, redPaint);\n }\n SkCanvas* canvas;\n};\n\nvoid draw(SkCanvas* canvas) {\n SkPictureRecorder recorder;\n SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});\n sk_sp placeholder = SkPicture::MakePlaceholder({10, 40, 80, 110});\n pictureCanvas->drawPicture(placeholder);\n sk_sp picture = recorder.finishRecordingAsPicture();\n MyCanvas myCanvas(canvas);\n myCanvas.drawPicture(picture);\n}", + "width": 256, + "height": 256, + "hash": "0d2cbf82f490ffb180e0b4531afa232c", + "file": "SkPicture_Reference", + "name": "SkPicture::MakePlaceholder" }, "SkPicture_approximateBytesUsed": { "code": "void draw(SkCanvas* canvas) {\n SkPictureRecorder recorder;\n SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});\n SkPaint paint;\n pictureCanvas->drawRect(SkRect::MakeWH(200, 200), paint);\n paint.setColor(SK_ColorWHITE);\n pictureCanvas->drawRect(SkRect::MakeLTRB(20, 20, 180, 180), paint);\n sk_sp picture = recorder.finishRecordingAsPicture();\n picture->playback(canvas);\n std::string opCount = \"approximate bytes used: \" + std::to_string(picture->approximateBytesUsed());\n canvas->drawString(opCount.c_str(), 20, 220, SkPaint());\n}", -- cgit v1.2.3