Color Documentation

- treat Color, ARGB, etc as things not requiring definitions
- fix links to Anti-alias, RGB-565
- finish everything marked incomplete, color and elsewhere
- add #Code blocks for #Typedef

R=caryclark@google.com
Docs-Preview: https://skia.org/?cl=128547
Bug: skia:6898
Change-Id: Icf12fe70bc2bf1a8b1a5b31380b2454610949f23
Reviewed-on: https://skia-review.googlesource.com/128547
Reviewed-by: Cary Clark <caryclark@skia.org>
Commit-Queue: Cary Clark <caryclark@skia.org>
Auto-Submit: Cary Clark <caryclark@skia.org>

1 files changed, 159 insertions, 51 deletions

diff --git a/docs/SkColor4f_Reference.bmh b/docs/SkColor4f_Reference.bmh
index eaf762d2e3..a2c3b0ea2d 100644
--- a/docs/SkColor4f_Reference.bmh
+++ b/docs/SkColor4f_Reference.bmh
@@ -3,7 +3,14 @@
 
 #Struct SkColor4f
 
-The float values are 0...1 Unpremultiplied
+Each component is stored as a 32-bit single precision floating point float value.
+All values are allowed, but only the range from zero to one is meaningful.
+
+Each component is independent of the others; fA Alpha is not Premultiplied
+with fG green, fB blue, or fR red.
+
+Values smaller than zero or larger than one are allowed. Values out of range
+may be used with Blend_Mode so that the final component is in range.
 
 #Subtopic Overview
 #Populate
@@ -18,36 +25,47 @@ The float values are 0...1 Unpremultiplied
 ##
 
 #Member float  fR
-#Line # incomplete ##
+#Line # red component ##
+Single precision float for red ranges from no red (0.0) to full red (1.0).
 ##
 
 #Member float  fG
-#Line # incomplete ##
+#Line # green component ##
+Single precision float for green ranges from no green (0.0) to full green (1.0).
 ##
 
 #Member float  fB
-#Line # incomplete ##
+#Line # blue component ##
+Single precision float for blue ranges from no blue (0.0) to full blue (1.0).
 ##
 
 #Member float  fA
-#Line # incomplete ##
+#Line # alpha component ##
+Single precision float for Alpha ranges from no Alpha (0.0) to full Alpha (1.0).
 ##
 
 # ------------------------------------------------------------------------------
 
 #Method bool operator==(const SkColor4f& other)_const
 #In Operator
-#Line # incomplete ##
+#Line # compares Color4f for equality ##
 
-#Param other  incomplete ##
+Compares Color4f with other, and returns true if all components are equivalent.
 
-#Return incomplete ##
+#Param other  Color4f to compare ##
+
+#Return true if Color4f equals other ##
 
 #Example
-// incomplete
+    SkColor4f colorRed = { 1, 0, 0, 1 };

+    SkColor4f colorNamedRed = SkColor4f::FromColor(SK_ColorRED);

+    SkDebugf("colorRed %c= colorNamedRed", colorRed == colorNamedRed ? '=' : '!');

+#StdOut
+colorRed == colorNamedRed
+##
 ##
 
-#SeeAlso incomplete
+#SeeAlso operator!=(const SkColor4f& other)_const
 
 #Method ##
 
@@ -55,122 +73,212 @@ The float values are 0...1 Unpremultiplied
 
 #Method bool operator!=(const SkColor4f& other)_const
 #In Operator
-#Line # incomplete ##
+#Line # compares colors for inequality ##
 
-#Param other  incomplete ##
+Compares Color4f with other, and returns true if all components are not
+equivalent.
 
-#Return incomplete ##
+#Param other  Color4f to compare ##
+
+#Return true if Color4f is not equal to other ##
 
 #Example
-// incomplete
+    SkColor4f colorGray = { .5, .5, .5, 1 };

+    SkColor4f colorNamedGray = SkColor4f::FromColor(SK_ColorGRAY);

+    SkDebugf("colorGray %c= colorNamedGray ", colorGray != colorNamedGray ? '!' : '=');

+#StdOut
+colorGray != colorNamedGray
+##
 ##
 
-#SeeAlso incomplete
+#SeeAlso operator==(const SkColor4f& other)_const
 
 #Method ##
 
 # ------------------------------------------------------------------------------
 
 #Method const float* vec() const
-#In incomplete
-#Line # incomplete ##
+#In Property
+#Line # returns array of components ##
+
+Returns Color4f components as a read-only array.
 
-#Return incomplete ##
+#Return components as read-only array ##
 
 #Example
-// incomplete
+    SkColor4f color = SkColor4f::FromColor(0x884488CC);

+    SkDebugf("red=%g green=%g blue=%g alpha=%g\n", color.fR, color.fG, color.fB, color.fA);

+    const float* array = color.vec();

+    SkDebugf("[0]=%g [1]=%g [2]=%g [3]=%g\n", array[0], array[1], array[2], array[3]);

+#StdOut
+red=0.0578054 green=0.246201 blue=0.603827 alpha=0.533333

+[0]=0.0578054 [1]=0.246201 [2]=0.603827 [3]=0.533333
+##
 ##
 
-#SeeAlso incomplete
+#SeeAlso SkColor4f
 
 #Method ##
 
 # ------------------------------------------------------------------------------
 
 #Method float* vec()
-#In incomplete
-#Line # incomplete ##
+#In Property
+#Line # returns array of components ##
+
+Returns Color4f components as a writable array.
 
-#Return incomplete ##
+#Return components as writable array ##
 
 #Example
-// incomplete
+    SkColor4f color = SkColor4f::FromColor(0x884488CC);

+    SkDebugf("red=%g green=%g blue=%g alpha=%g\n", color.fR, color.fG, color.fB, color.fA);

+    float* array = color.vec();

+    array[3] = 1;

+    SkDebugf("[0]=%g [1]=%g [2]=%g [3]=%g\n", array[0], array[1], array[2], array[3]);
+#StdOut
+red=0.0578054 green=0.246201 blue=0.603827 alpha=0.533333

+[0]=0.0578054 [1]=0.246201 [2]=0.603827 [3]=1
+##
 ##
 
-#SeeAlso incomplete
+#SeeAlso SkColor4f
 
 #Method ##
 
 # ------------------------------------------------------------------------------
 
 #Method static SkColor4f Pin(float r, float g, float b, float a)
-#In incomplete
-#Line # incomplete ##
+#In Utility
+#Line # sets components to valid range ##
+
+Constructs and returns Color4f with each component pinned from zero to one.
 
-#Param r  incomplete ##
-#Param g  incomplete ##
-#Param b  incomplete ##
-#Param a  incomplete ##
+#Param r  red component ##
+#Param g  green component ##
+#Param b  blue component ##
+#Param a  Alpha component ##
 
-#Return incomplete ##
+#Return Color4f with valid components ##
 
 #Example
-// incomplete
+#Height 40
+    uint32_t storage[8];
+    SkImageInfo info = SkImageInfo::MakeN32Premul(8, 1);
+    SkPixmap pixmap(info, storage, info.minRowBytes());
+    pixmap.erase(SK_ColorWHITE);
+    SkIRect bounds = {0, 0, 1, 1};
+    SkColor4f colors[] = { SkColor4f::Pin(1.5, 0.45f,  0.0,  1), 
+                           SkColor4f::Pin(1,   0.45f, -0.25, 1),
+                           {1.5, 0.45f,  0.0,  1},
+                           {1,   0.45f, -0.25, 1},
+                         };
+    for (auto color4f : colors) {
+        pixmap.erase(color4f, &bounds);
+        bounds.offset(2, 0);
+    }
+    SkBitmap bitmap;
+    canvas->scale(20, 20);
+    bitmap.installPixels(pixmap);
+    canvas->drawBitmap(bitmap, 0, 0);
 ##
 
-#SeeAlso incomplete
+#SeeAlso pin() FromColor
 
 #Method ##
 
 # ------------------------------------------------------------------------------
 
 #Method static SkColor4f FromColor(SkColor)
-#In incomplete
-#Line # incomplete ##
+#In Utility
+#Line # sets components from Color ##
 
-Convert to SkColor4f, assuming SkColor is sRGB
+Converts to closest Color4f.
 
-#Param SkColor  incomplete ##
+#Param SkColor  Color with Alpha, red, blue, and green components ##
 
-#Return incomplete ##
+#Return Color4f equivalent ##
 
 #Example
-// incomplete
+    uint8_t red = 77, green = 101, blue = 153, alpha = 43;

+    SkColor argb = SkColorSetARGB(alpha, red, green, blue);

+    SkColor4f color4f = SkColor4f::FromColor(argb);

+    SkDebugf("red=%g green=%g blue=%g alpha=%g\n", color4f.fR, color4f.fG, color4f.fB, color4f.fA);

+    SkColor fromColor4f = color4f.toSkColor();

+    SkDebugf("red=%d green=%d blue=%d alpha=%d\n", SkColorGetR(fromColor4f),

+             SkColorGetG(fromColor4f), SkColorGetB(fromColor4f), SkColorGetA(fromColor4f));
+#StdOut
+red=0.0742136 green=0.130136 blue=0.318547 alpha=0.168627

+red=77 green=101 blue=153 alpha=43
+##
 ##
 
-#SeeAlso incomplete
+#SeeAlso toSkColor
 
 #Method ##
 
 # ------------------------------------------------------------------------------
 
 #Method SkColor toSkColor() const
-#In incomplete
-#Line # incomplete ##
+#In Utility
+#Line # returns closest Color ##
+
+Converts to closest SkColor.
 
-#Return incomplete ##
+#Return closest Color ##
 
 #Example
-// incomplete
+    float red = 0.07, green = 0.13, blue = 0.32, alpha = 0.17;

+    SkColor4f color4f = { red, green, blue, alpha };

+    SkColor argb = color4f.toSkColor();

+    SkDebugf("red=%d green=%d blue=%d alpha=%d\n", SkColorGetR(argb),

+             SkColorGetG(argb), SkColorGetB(argb), SkColorGetA(argb));
+    SkColor4f fromSkColor = SkColor4f::FromColor(argb);

+    SkDebugf("red=%g green=%g blue=%g alpha=%g\n", fromSkColor.fR, fromSkColor.fG,

+                                                   fromSkColor.fB, fromSkColor.fA);

+#StdOut

+red=75 green=101 blue=153 alpha=43

+red=0.0703601 green=0.130136 blue=0.318547 alpha=0.168627

+##

 ##
 
-#SeeAlso incomplete
+#SeeAlso FromColor
 
 #Method ##
 
 # ------------------------------------------------------------------------------
 
 #Method SkColor4f pin() const
-#In incomplete
-#Line # incomplete ##
+#In Utility
+#Line # sets components to valid range ##
+
+Returns Color4f with all components in the range from zero to one.
 
-#Return incomplete ##
+#Return Color4f with valid components ##
 
 #Example
-// incomplete
+#Height 40
+    uint32_t storage[8];
+    SkImageInfo info = SkImageInfo::MakeN32Premul(8, 1);
+    SkPixmap pixmap(info, storage, info.minRowBytes());
+    pixmap.erase(SK_ColorWHITE);
+    SkIRect bounds = {0, 0, 1, 1};
+    SkColor4f colors[] = { {1.5, 0.45f,  0.0,  1},
+                           {1,   0.45f, -0.25, 1},
+                         };
+    for (auto color4f : colors) {
+        pixmap.erase(color4f, &bounds);
+        bounds.offset(2, 0);
+        pixmap.erase(color4f.pin(), &bounds);
+        bounds.offset(2, 0);
+    }
+    SkBitmap bitmap;
+    canvas->scale(20, 20);
+    bitmap.installPixels(pixmap);
+    canvas->drawBitmap(bitmap, 0, 0);
 ##
 
-#SeeAlso incomplete
+#SeeAlso Pin
 
 #Method ##