document SkColor.h

SkColor.h uses #define liberally, and has many global symbols,
two things bookmaker hasn't seen in other includes.

Revised .h -> .bmh converter to work with SkColor.h as well
as updating how .bmh indices are built.

Generated SkColor_Reference.bmh for globals, and
SkColor4f_Reference.bmh for class.

Other than the existing comments, this doesn't update the
documentation or add new examples.

Docs-Preview: https://skia.org/?cl=118985
TBR=caryclark@google.com
Bug: skia:6898
Change-Id: I5978257ee0e51319823efbe8dfc467a08c99ffe0
Reviewed-on: https://skia-review.googlesource.com/118985
Commit-Queue: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>

5 files changed, 935 insertions, 66 deletions

diff --git a/docs/SkColor4f_Reference.bmh b/docs/SkColor4f_Reference.bmh
new file mode 100644
index 0000000000..71bdb76d1c
--- /dev/null
+++ b/docs/SkColor4f_Reference.bmh
@@ -0,0 +1,193 @@
+#Topic Color4f
+#Alias Color4f_Reference
+
+#Struct SkColor4f
+
+The float values are 0...1 unpremultiplied
+
+#Subtopic Overview
+    #Subtopic Subtopic
+        #Populate
+    ##
+##
+
+#Subtopic Operator
+#Populate
+##
+
+#Subtopic Member_Function
+#Populate
+##
+
+#Member float  fR
+##
+
+#Member float  fG
+##
+
+#Member float  fB
+##
+
+#Member float  fA
+##
+
+# ------------------------------------------------------------------------------
+
+#Method bool operator==(const SkColor4f& other)_const
+#In Operator
+#Line # incomplete ##
+
+#Param other  incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method bool operator!=(const SkColor4f& other)_const
+#In Operator
+#Line # incomplete ##
+
+#Param other  incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method const float* vec() const
+#In incomplete
+#Line # incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method float* vec()
+#In incomplete
+#Line # incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method static SkColor4f Pin(float r, float g, float b, float a)
+#In incomplete
+#Line # incomplete ##
+
+#Param r  incomplete ##
+#Param g  incomplete ##
+#Param b  incomplete ##
+#Param a  incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method static SkColor4f FromColor(SkColor)
+#In incomplete
+#Line # incomplete ##
+
+Convert to SkColor4f, assuming SkColor is sRGB
+
+#Param SkColor  incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method SkColor toSkColor() const
+#In incomplete
+#Line # incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method SkColor4f pin() const
+#In incomplete
+#Line # incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method SkPM4f premul() const
+#In incomplete
+#Line # incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+#Struct SkColor4f ##
+
+#Topic Color4f ##
diff --git a/docs/SkColor_Reference.bmh b/docs/SkColor_Reference.bmh
new file mode 100644
index 0000000000..7d174e7fec
--- /dev/null
+++ b/docs/SkColor_Reference.bmh
@@ -0,0 +1,735 @@
+#Topic Color
+#Alias Color_Reference
+
+#Subtopic Overview
+    #Subtopic Subtopic
+        #Populate
+    ##
+##
+
+#Subtopic Define
+#Populate
+##
+
+#Subtopic Function
+#Populate
+##
+
+#Subtopic Typedef
+#Populate
+##
+
+    #Subtopic Alpha
+        #Alias Alpha
+    #Subtopic ##
+
+    #Subtopic RGB
+    #Substitute RGB
+        #Subtopic Red
+            #Alias Red
+        #Subtopic ##
+        #Subtopic Blue
+            #Alias Blue
+        #Subtopic ##
+        #Subtopic Green
+            #Alias Green
+        #Subtopic ##
+    #Subtopic ##
+
+    #Subtopic ARGB
+    #Substitute ARGB
+    #Subtopic ##
+
+    #Subtopic RBG
+    #Substitute RBG
+    #Subtopic ##
+
+    #Subtopic RGB-565
+    #Substitute RGB-565
+    #Alias Color_RGB-565 # quit changing - to _ !
+    #Subtopic ##
+
+    #Subtopic Gray
+    ##
+
+# ------------------------------------------------------------------------------
+
+#Typedef uint8_t SkAlpha
+
+Types and macros for colors
+8-bit type for an alpha value. 0xFF is 100% opaque, 0x00 is 100% transparent.
+
+#Typedef ##
+
+# ------------------------------------------------------------------------------
+
+#Typedef uint32_t SkColor
+
+32 bit ARGB color value, not premultiplied. The color components are always in
+a known order. This is different from SkPMColor, which has its bytes in a configuration
+dependent order, to match the format of kBGRA_8888_SkColorType bitmaps. SkColor
+is the type used to specify colors in SkPaint and in gradients.
+
+#Typedef ##
+
+# ------------------------------------------------------------------------------
+
+#Method static constexpr inline SkColor SkColorSetARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b)
+#In Function
+#Line # incomplete ##
+
+Return a SkColor value from 8 bit component values
+
+#Param a  incomplete ##
+#Param r  incomplete ##
+#Param g  incomplete ##
+#Param b  incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Define SkColorSetARGBInline
+
+#Code
+###$
+    #define SkColorSetARGBInline SkColorSetARGB
+$$$#
+##
+
+Legacy aliases.
+
+#NoExample
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SkColorSetARGBMacro
+
+#Code
+###$
+    #define SkColorSetARGBMacro  SkColorSetARGB
+$$$#
+##
+
+#NoExample
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SkColorSetRGB
+#Line # incomplete ##
+
+#Code
+###$
+    #define SkColorSetRGB(r, g, b)  SkColorSetARGB(0xFF, r, g, b)
+$$$#
+##
+
+Return a SkColor value from 8 bit component values, with an implied value
+of 0xFF for alpha (fully opaque)
+
+#Param r incomplete ##
+#Param g incomplete ##
+#Param b incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SkColorGetA
+#Line # incomplete ##
+
+#Code
+###$
+    #define SkColorGetA(color)      (((color) >> 24) & 0xFF)
+$$$#
+##
+
+return the alpha byte from a SkColor value
+
+#Param color incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SkColorGetR
+#Line # incomplete ##
+
+#Code
+###$
+    #define SkColorGetR(color)      (((color) >> 16) & 0xFF)
+$$$#
+##
+
+return the red byte from a SkColor value
+
+#Param color incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SkColorGetG
+#Line # incomplete ##
+
+#Code
+###$
+    #define SkColorGetG(color)      (((color) >>  8) & 0xFF)
+$$$#
+##
+
+return the green byte from a SkColor value
+
+#Param color incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SkColorGetB
+#Line # incomplete ##
+
+#Code
+###$
+    #define SkColorGetB(color)      (((color) >>  0) & 0xFF)
+$$$#
+##
+
+return the blue byte from a SkColor value
+
+#Param color incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Method static constexpr inline SkColor SkColorSetA(SkColor c, U8CPU a)
+#In Function
+#Line # incomplete ##
+
+#Param c  incomplete ##
+#Param a  incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_AlphaTRANSPARENT
+
+#Code
+###$
+    #define SK_AlphaTRANSPARENT static_cast<SkAlpha>(0x00)
+$$$#
+##
+
+common colors
+transparent SkAlpha value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_AlphaOPAQUE
+
+#Code
+###$
+    #define SK_AlphaOPAQUE      static_cast<SkAlpha>(0xFF)
+$$$#
+##
+
+opaque SkAlpha value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_ColorTRANSPARENT
+
+#Code
+###$
+    #define SK_ColorTRANSPARENT static_cast<SkColor>(0x00000000)
+$$$#
+##
+
+transparent SkColor value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_ColorBLACK
+
+#Code
+###$
+    #define SK_ColorBLACK       static_cast<SkColor>(0xFF000000)
+$$$#
+##
+
+black SkColor value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_ColorDKGRAY
+
+#Code
+###$
+    #define SK_ColorDKGRAY      static_cast<SkColor>(0xFF444444)
+$$$#
+##
+
+dark gray SkColor value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_ColorGRAY
+
+#Code
+###$
+    #define SK_ColorGRAY        static_cast<SkColor>(0xFF888888)
+$$$#
+##
+
+gray SkColor value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_ColorLTGRAY
+
+#Code
+###$
+    #define SK_ColorLTGRAY      static_cast<SkColor>(0xFFCCCCCC)
+$$$#
+##
+
+light gray SkColor value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_ColorWHITE
+
+#Code
+###$
+    #define SK_ColorWHITE       static_cast<SkColor>(0xFFFFFFFF)
+$$$#
+##
+
+white SkColor value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_ColorRED
+
+#Code
+###$
+    #define SK_ColorRED         static_cast<SkColor>(0xFFFF0000)
+$$$#
+##
+
+red SkColor value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_ColorGREEN
+
+#Code
+###$
+    #define SK_ColorGREEN       static_cast<SkColor>(0xFF00FF00)
+$$$#
+##
+
+green SkColor value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_ColorBLUE
+
+#Code
+###$
+    #define SK_ColorBLUE        static_cast<SkColor>(0xFF0000FF)
+$$$#
+##
+
+blue SkColor value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_ColorYELLOW
+
+#Code
+###$
+    #define SK_ColorYELLOW      static_cast<SkColor>(0xFFFFFF00)
+$$$#
+##
+
+yellow SkColor value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_ColorCYAN
+
+#Code
+###$
+    #define SK_ColorCYAN        static_cast<SkColor>(0xFF00FFFF)
+$$$#
+##
+
+cyan SkColor value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Define SK_ColorMAGENTA
+
+#Code
+###$
+    #define SK_ColorMAGENTA     static_cast<SkColor>(0xFFFF00FF)
+$$$#
+##
+
+magenta SkColor value
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Define ##
+
+# ------------------------------------------------------------------------------
+
+#Subtopic HSV
+
+#Subtopic Hue
+Hue represents an angle, in degrees, on a color wheel. Hue has a positive value
+modulo 360, where zero degrees is red.
+##
+
+#Subtopic Saturation
+##
+
+#Subtopic Value
+##
+
+#Method SK_API void SkRGBToHSV(U8CPU red, U8CPU green, U8CPU blue, SkScalar hsv[3])
+#In Function
+#Line # incomplete ##
+
+Convert RGB components to HSV.
+hsv[0] is Hue [0 .. 360)
+hsv[1] is Saturation [0...1]
+hsv[2] is Value [0...1]
+
+#Param red  red component value [0..255]
+##
+#Param green  green component value [0..255]
+##
+#Param blue  blue component value [0..255]
+##
+#Param hsv  3 element array which holds the resulting HSV components.
+##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method static inline void SkColorToHSV(SkColor color, SkScalar hsv[3])
+#In Function
+#Line # incomplete ##
+
+Convert the argb color to its HSV components.
+hsv[0] represents Hue, and is assigned a value from zero to less than 360.
+hsv[1] is Saturation [0...1]
+hsv[2] is Value [0...1]
+
+#Param color  the argb color to convert. Note: the alpha component is ignored.
+##
+#Param hsv  3 element array which holds the resulting HSV components.
+##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method SK_API SkColor SkHSVToColor(U8CPU alpha, const SkScalar hsv[3])
+#In Function
+#Line # incomplete ##
+
+Convert HSV components to an ARGB color. The alpha component is passed through unchanged.
+hsv[0] represents Hue, an angle from zero to less than 360.
+hsv[1] represents Saturation, and varies from zero to one.
+hsv[2] represents Value, and varies from zero to one.
+
+If hsv values are out of range, they are pinned.
+
+#Param alpha  the alpha component of the returned argb color.
+##
+#Param hsv  3 element array which holds the input HSV components.
+##
+
+#Return  the resulting argb color
+##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method static inline SkColor SkHSVToColor(const SkScalar hsv[3])
+#In Function
+#Line # incomplete ##
+
+Convert HSV components to an ARGB color. The alpha component set to 0xFF.
+hsv[0] represents Hue, an angle from zero to less than 360.
+hsv[1] represents Saturation, and varies from zero to one.
+hsv[2] represents Value, and varies from zero to one.
+
+If hsv values are out of range, they are pinned.
+
+#Param hsv  3 element array which holds the input HSV components.
+##
+
+#Return  the resulting argb color
+##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+#Subtopic HSV ##
+
+# ------------------------------------------------------------------------------
+
+#Typedef uint32_t SkPMColor
+
+32 bit ARGB color value, premultiplied. The byte order for this value is
+configuration dependent, matching the format of kBGRA_8888_SkColorType bitmaps.
+This is different from SkColor, which is nonpremultiplied, and is always in the
+same byte order.
+
+#Typedef ##
+
+# ------------------------------------------------------------------------------
+
+#Method SK_API SkPMColor SkPreMultiplyARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b)
+#In Function
+#Line # incomplete ##
+
+Return a SkPMColor value from unpremultiplied 8 bit component values
+
+#Param a  incomplete ##
+#Param r  incomplete ##
+#Param g  incomplete ##
+#Param b  incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method SK_API SkPMColor SkPreMultiplyColor(SkColor c)
+#In Function
+#Line # incomplete ##
+
+Return a SkPMColor value from a SkColor value. This is done by multiplying the color
+components by the color's alpha, and by arranging the bytes in a configuration
+dependent order, to match the format of kBGRA_8888_SkColorType bitmaps.
+
+#Param c  incomplete ##
+
+#Return incomplete ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso incomplete
+
+#Method ##
+
+#Topic Color ##
diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh
index 2070441a5b..162e4791a2 100644
--- a/docs/SkPaint_Reference.bmh
+++ b/docs/SkPaint_Reference.bmh
@@ -791,7 +791,9 @@ at compile time.
 
 Some platform implementations may ignore dithering. Set
 
-#Define SK_IGNORE_GPU_DITHER
+#Formula
+SK_IGNORE_GPU_DITHER
+##
 
 to ignore Dither on GPU_Surface.
 
diff --git a/docs/status.json b/docs/status.json
index fab616efbb..a24da579a5 100644
--- a/docs/status.json
+++ b/docs/status.json
@@ -37,9 +37,12 @@
     "InProgress": {
         "include": {
             "core": [
+                "SkColor.h"
             ]
         },
         "docs": [
+            "SkColor_Reference.bmh",
+            "SkColor4f_Reference.bmh",
             "overview.bmh",
             "usingBookmaker.bmh"
         ]
diff --git a/docs/undocumented.bmh b/docs/undocumented.bmh
index 6d767fc37d..84f4f90d3b 100644
--- a/docs/undocumented.bmh
+++ b/docs/undocumented.bmh
@@ -32,6 +32,7 @@
  SK_HAS_JPEG_LIBRARY # ditto
  SK_HAS_PNG_LIBRARY # ditto
  SK_HAS_WEBP_LIBRARY # ditto
+ SK_IGNORE_GPU_DITHER # ditto
  SK_PMCOLOR_BYTE_ORDER # ditto
 
 # FreeType related
@@ -93,71 +94,6 @@ FT_Load_Glyph
 ##
 ##
 
-#Topic Color
-    #Typedef uint32_t SkColor
-    #Typedef ##
-
-    #Typedef uint32_t SkPMColor
-    #Typedef ##
-
-    # fixme: defines, not methods, need new markup type
-    #Method int SkColorGetA(color)
-    ##
-    #Method int SkColorGetR(color)
-    ##
-    #Method int SkColorGetG(color)
-    ##
-    #Method int SkColorGetB(color)
-    ##
-    #Method int SkColorSetARGB(a, r, g, b)
-    ##
-    #Method SkPMColor SkPreMultiplyARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b)
-    ##
-
-    #Const SK_ColorBLACK 0xFF000000 
-    ##
-    #Const SK_ColorBLUE 0xFF0000FF 
-    ##
-    #Const SK_ColorGREEN 0xFF00FF00 
-    ##
-    #Const SK_ColorRED 0xFFFF0000 
-    ##
-    #Const SK_ColorWHITE 0xFFFFFFFF 
-    ##
-    #Const SK_ColorTRANSPARENT 0x00000000
-    ##
-    #Subtopic Alpha
-        #Alias Alpha
-    #Subtopic ##
-    #Subtopic RGB
-    #Substitute RGB
-        #Subtopic Red
-            #Alias Red
-        #Subtopic ##
-        #Subtopic Blue
-            #Alias Blue
-        #Subtopic ##
-        #Subtopic Green
-            #Alias Green
-        #Subtopic ##
-    #Subtopic ##
-    #Subtopic ARGB
-    #Substitute ARGB
-    #Subtopic ##
-
-    #Subtopic RBG
-    #Substitute RBG
-    #Subtopic ##
-
-    #Subtopic RGB-565
-    #Substitute RGB-565
-    #Alias Color_RGB-565 # quit changing - to _ !
-    #Subtopic ##
-
-    #Subtopic Gray
-    ##
-#Topic ##
-
 #Topic Color_Filter
 #Class SkColorFilter
 #Method void toString(SkString* str) const