auto table generation
Replace manually entered summary tables with ones that are populated
and sorted by bookmaker. This introduces a slight regression for
anonymous enums but fixes a lot of bugs and omissions.
The format is
#Topic somethingTopical
#Populate
##
where somethingTopical is one of Subtopics, Constructors, Constants,
Classes_and_Structs, Members, Member_Functions, and Related_Functions.
Fix the bad formatting in SkCanvas reference. The #Error tag was
was corrupting the markdown table. Remove the tag and replace it
with #NoExample.
Next up: revise self-check to know about populated topics.
TBR=caryclark@google.com
Docs-Preview: https://skia.org/?cl=102080
Bug: skia:6898
Change-Id: Idef5d1c14c740c18a81d6a5106182788dd2a09e1
Reviewed-on: https://skia-review.googlesource.com/102080
Commit-Queue: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>
diff --git a/docs/SkCanvas_Reference.bmh b/docs/SkCanvas_Reference.bmh
index 541bb83..2225b20 100644
--- a/docs/SkCanvas_Reference.bmh
+++ b/docs/SkCanvas_Reference.bmh
@@ -1,6 +1,12 @@
#Topic Canvas
#Alias Canvas_Reference
+#Subtopic Overview
+ #Subtopic Subtopics
+ #Populate
+ ##
+##
+
#Class SkCanvas
Canvas provides an interface for drawing, and how the drawing is clipped and transformed.
@@ -24,153 +30,29 @@
Canvas can be constructed to draw to Bitmap without first creating Raster_Surface.
This approach may be deprecated in the future.
-#Topic Overview
-
-#Subtopic Subtopics
-#Table
-#Legend
-# name # description ##
-#Legend ##
-# Classes_and_Structs # embedded struct and class members ##
-# Constants # enum and enum class, const values ##
-# Constructors # functions that construct SkPath ##
-# Member_Functions # static functions and member methods ##
-#Table ##
-#Subtopic ##
+#Subtopic Related_Functions
+#Populate
+##
#Subtopic Constants
-#Table
-#Legend
-# name # description ##
-#Legend ##
-# Lattice::Flags # controls Lattice transparency ##
-# PointMode # sets drawPoints options ##
-# SaveLayerFlags # sets SaveLayerRec options ##
-# SrcRectConstraint # sets drawImageRect options ##
-#Table ##
-#Subtopic ##
+#Populate
+##
#Subtopic Classes_and_Structs
-#Table
-#Legend
-# name # description ##
-#Legend ##
-# Lattice # divides Bitmap, Image into a rectangular grid ##
-# SaveLayerRec # contains state to create Layer ##
-#Table ##
-#Subtopic ##
+#Populate
+##
#Subtopic Constructors
Create the desired type of Surface to obtain its Canvas when possible. Constructors are useful
when no Surface is required, and some helpers implicitly create Raster_Surface.
-#Table
-#Legend
-# name # description ##
-#Legend ##
-# MakeRasterDirect # creates from SkImageInfo and Pixel_Storage ##
-# MakeRasterDirectN32 # creates from image data and Pixel_Storage ##
-# SkCanvas() # creates with no Surface, no dimensions ##
-# SkCanvas(SkBaseDevice* device) # to be deprecated ##
-# SkCanvas(const SkBitmap& bitmap) # uses existing Bitmap ##
-# SkCanvas(const SkBitmap& bitmap, ColorBehavior behavior) # Android framework only ##
-# SkCanvas(const SkBitmap& bitmap, const SkSurfaceProps& props) # uses existing Bitmap and Surface_Properties ##
-# SkCanvas(int width, int height, const SkSurfaceProps* props = nullptr) # no Surface, set dimensions, Surface_Properties ##
-# ~SkCanvas() # draws saved Layers, frees resources ##
-#Table ##
-#Subtopic ##
+#Populate
+##
#Subtopic Member_Functions
-#Table
-#Legend
-# name # description ##
-#Legend ##
-# MakeRasterDirect # creates from SkImageInfo and Pixel_Storage ##
-# MakeRasterDirectN32 # creates from image data and Pixel_Storage ##
-# accessTopLayerPixels # returns writable pixel access if available ##
-# accessTopRasterHandle # returns context that tracks Clip and Matrix ##
-# androidFramework_setDeviceClipRestriction # for use by Android framework ##
-# clear() # fills Clip with Color ##
-# clipPath # combines Clip with Path ##
-# clipRRect # combines Clip with Round_Rect ##
-# clipRect # combines Clip with Rect ##
-# clipRegion # combines Clip with Region ##
-# concat() # multiplies Matrix by Matrix ##
-# discard() # makes Canvas contents undefined ##
-# drawAnnotation # associates a Rect with a key-value pair ##
-# drawArc # draws Arc using Clip, Matrix, and Paint ##
-# drawAtlas # draws sprites using Clip, Matrix, and Paint ##
-# drawBitmap # draws Bitmap at (x, y) position ##
-# drawBitmapLattice # draws proportionally stretched Bitmap ##
-# drawBitmapNine # draws Nine_Patch Bitmap ##
-# drawBitmapRect # draws Bitmap, source Rect to destination Rect ##
-# drawCircle # draws Circle using Clip, Matrix, and Paint ##
-# drawColor # fills Clip with Color and Blend_Mode ##
-# drawDRRect # draws double Round_Rect stroked or filled ##
-# drawDrawable # draws Drawable, encapsulated drawing commands ##
-# drawIRect # draws IRect using Clip, Matrix, and Paint ##
-# drawImage # draws Image at (x, y) position ##
-# drawImageLattice # draws proportionally stretched Image ##
-# drawImageNine # draws Nine_Patch Image ##
-# drawImageRect # draws Image, source Rect to destination Rect ##
-# drawLine # draws line segment between two points ##
-# drawOval # draws Oval using Clip, Matrix, and Paint ##
-# drawPaint # fills Clip with Paint ##
-# drawPatch # draws Coons_Patch ##
-# drawPath # draws Path using Clip, Matrix, and Paint ##
-# drawPicture # draws Picture using Clip and Matrix ##
-# drawPoint # draws point at (x, y) position ##
-# drawPoints # draws array as points, lines, polygon ##
-# drawPosText # draws text at array of (x, y) positions ##
-# drawPosTextH # draws text at x positions with common baseline ##
-# drawRRect # draws Round_Rect using Clip, Matrix, and Paint ##
-# drawRect # draws Rect using Clip, Matrix, and Paint ##
-# drawRegion # draws Region using Clip, Matrix, and Paint ##
-# drawRoundRect # draws Round_Rect using Clip, Matrix, and Paint ##
-# drawString # draws null terminated string at (x, y) using font advance ##
-# drawText # draws text at (x, y), using font advance ##
-# drawTextBlob # draws text with arrays of positions and Paint ##
-# drawTextOnPath # draws text following Path contour ##
-# drawTextOnPathHV # draws text following Path with offsets ##
-# drawTextRSXform # draws text with array of RSXform ##
-# drawVertices # draws Vertices, a triangle mesh ##
-# flush() # triggers execution of all pending draw operations ##
-# getBaseLayerSize # returns size of base Layer in global coordinates ##
-# getDeviceClipBounds # returns IRect bounds of Clip ##
-# getDrawFilter # legacy; to be deprecated ##
-# getGrContext # returns GPU_Context of the GPU_Surface ##
-# getLocalClipBounds # returns Clip bounds in source coordinates ##
-# getMetaData # associates additional data with the canvas ##
-# getProps # copies Surface_Properties if available ##
-# getSaveCount # returns depth of stack containing Clip and Matrix ##
-# getTotalMatrix # returns Matrix ##
-# imageInfo # returns Image_Info for Canvas ##
-# isClipEmpty # returns if Clip is empty ##
-# isClipRect # returns if Clip is Rect and not empty ##
-# makeSurface # creates Surface matching SkImageInfo and SkSurfaceProps ##
-# peekPixels # returns if Canvas has direct access to its pixels ##
-# quickReject # returns if Rect is outside Clip ##
-# readPixels # copies and converts rectangle of pixels from Canvas ##
-# resetMatrix # resets Matrix to identity ##
-# restore() # restores changes to Clip and Matrix, pops save stack ##
-# restoreToCount # restores changes to Clip and Matrix to given depth ##
-# rotate() # rotates Matrix ##
-# save() # saves Clip and Matrix on stack ##
-# saveLayer # saves Clip and Matrix on stack; creates Layer ##
-# saveLayerAlpha # saves Clip and Matrix on stack; creates Layer; sets opacity ##
-# saveLayerPreserveLCDTextRequests # saves Clip and Matrix on stack; creates Layer for LCD text ##
-# scale() # scales Matrix ##
-# setAllowSimplifyClip # experimental ##
-# setDrawFilter # legacy; to be deprecated ##
-# setMatrix # sets Matrix ##
-# skew() # skews Matrix ##
-# translate() # translates Matrix ##
-# writePixels # copies and converts rectangle of pixels to Canvas ##
-#Table ##
-#Subtopic ##
-
-#Topic Overview ##
+#Populate
+##
# ------------------------------------------------------------------------------
@@ -424,10 +306,8 @@
#Return Canvas that can be used to draw into device ##
-#Example
-#Error "Unsure how to create a meaningful example."
- SkPDFCanvas::SkPDFCanvas(const sk_sp<SkPDFDevice>& dev)
- : SkCanvas(dev.get()) {}
+#ToDo unsure how to create a meaningful example ##
+#NoExample
##
#ToDo either remove doc or figure out a way to fiddle it ##
@@ -501,7 +381,7 @@
##
#EnumClass ColorBehavior
-
+#Line # Android framework only ##
#Private
Android framework only.
##
@@ -748,8 +628,8 @@
for posterity: this doesn't show a difference: fiddle.skia.org/c/@flushfail
##
-#Example
-#Error "haven't thought of a useful example to put here"
+#ToDo haven't thought of a useful example to put here ##
+#NoExample
##
#SeeAlso peekPixels SkSurface::flush() GrContext::flush() SkSurface::prepareForExternalIO GrContext::abandonContext()
@@ -1371,7 +1251,8 @@
##
# ------------------------------------------------------------------------------
-#Topic State_Stack
+#Subtopic State_Stack
+#Line # stack of state for hierarchical drawing ##
Canvas maintains a stack of state that allows hierarchical drawing, commonly used
to implement windows and views. The initial state has an identity matrix and and
@@ -1573,13 +1454,14 @@
##
-#Topic State_Stack ##
+#Subtopic State_Stack ##
# ------------------------------------------------------------------------------
-#Topic Layer
+#Subtopic Layer
#Substitute layer
#Alias Layers
+#Line # temporary Bitmap to draw into ##
Layer allocates a temporary Bitmap to draw into. When the drawing is
complete, the Bitmap is drawn into the Canvas.
@@ -1791,8 +1673,13 @@
##
-#Enum
+#ToDo
+add new markup to associate typedef SaveLayerFlags with Enum so that, for
+documentation purposes, this enum is named rather than anonymous
+##
+#Enum
+#Line # sets SaveLayerRec options ##
#Code
enum {
kIsOpaque_SaveLayerFlag = 1 << 0,
@@ -1860,7 +1747,7 @@
##
#Struct SaveLayerRec
-
+#Line # contains the state used to create the Layer ##
#Code
struct SaveLayerRec {
SaveLayerRec*(...
@@ -2096,10 +1983,11 @@
##
-#Topic Layer ##
+#Subtopic Layer ##
# ------------------------------------------------------------------------------
-#Topic Matrix
+#Subtopic Matrix
+#Line # coordinate transformation ##
#Method void translate(SkScalar dx, SkScalar dy)
@@ -2414,10 +2302,11 @@
##
-#Topic Matrix ##
+#Subtopic Matrix ##
# ------------------------------------------------------------------------------
-#Topic Clip
+#Subtopic Clip
+#Line # stack of clipping Paths ##
Clip is built from a stack of clipping paths. Each Path in the
stack can be constructed from one or more Path_Contour elements. The
@@ -3102,7 +2991,7 @@
##
-#Topic Clip ##
+#Subtopic Clip ##
# ------------------------------------------------------------------------------
@@ -3211,6 +3100,7 @@
# ------------------------------------------------------------------------------
#Enum PointMode
+#Line # sets drawPoints options ##
#Code
enum PointMode {
@@ -3933,7 +3823,8 @@
##
# ------------------------------------------------------------------------------
-#Topic Draw_Image
+#Subtopic Draw_Image
+#Line # draws Image to Canvas ##
drawImage, drawImageRect, and drawImageNine can be called with a bare pointer or
a smart pointer as a convenience. The pairs of calls are otherwise identical.
@@ -4020,6 +3911,7 @@
# ------------------------------------------------------------------------------
#Enum SrcRectConstraint
+#Line # sets drawImageRect options ##
#Code
enum SrcRectConstraint {
@@ -4833,7 +4725,7 @@
# ------------------------------------------------------------------------------
#Struct Lattice
-
+#Line # divides Bitmap or Image into a rectangular grid ##
#Code
struct Lattice {
enum RectType ...
@@ -5098,7 +4990,7 @@
##
-#Topic Draw_Image ##
+#Subtopic Draw_Image ##
# ------------------------------------------------------------------------------