more SkImageInfo docs

fix a couple of fiddles with changed output
rewrite some SkSurface image makers
move towards replacing SkImageInfo.h

R=caryclark@google.com

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

1 files changed, 198 insertions, 98 deletions

diff --git a/docs/SkImageInfo_Reference.bmh b/docs/SkImageInfo_Reference.bmh
index caa54b8731..516de4e35f 100644
--- a/docs/SkImageInfo_Reference.bmh
+++ b/docs/SkImageInfo_Reference.bmh
@@ -192,6 +192,17 @@ in the same order.
 
 #Subtopic Unpremul ##
 
+#Method static inline bool SkAlphaTypeIsOpaque(SkAlphaType at)
+#In Property
+#Line # returns if Alpha_Type equals kOpaque_SkAlphaType ##
+
+#Param at one of: #list_of_alpha_types#
+##
+#Return true if at equals kOpaque_SkAlphaType ##
+#NoExample
+##
+##
+
 #Subtopic Alpha_Type ##
 
 # ------------------------------------------------------------------------------
@@ -216,6 +227,7 @@ kGray_8_SkColorType, kRGBA_F16_SkColorType
 #Line # encoding for pixel color ##
 
 #Code
+###$
     enum SkColorType {
         kUnknown_SkColorType,
         kAlpha_8_SkColorType,
@@ -228,10 +240,18 @@ kGray_8_SkColorType, kRGBA_F16_SkColorType
         kRGB_101010x_SkColorType,
         kGray_8_SkColorType,
         kRGBA_F16_SkColorType,
+
         kLastEnum_SkColorType = kRGBA_F16_SkColorType,
+
+    #if SK_PMCOLOR_BYTE_ORDER(B,G,R,A)
         kN32_SkColorType = kBGRA_8888_SkColorType,
+    #elif SK_PMCOLOR_BYTE_ORDER(R,G,B,A)
         kN32_SkColorType = kRGBA_8888_SkColorType,
+    #else
+        #error "SK_*32_SHIFT values must correspond to BGRA or RGBA byte order"
+    #endif
     };
+$$$#
 ##
 
 Describes how pixel bits encode color. A pixel may be an alpha mask, a
@@ -870,7 +890,7 @@ and return true if alphaType is not kUnknown_SkAlphaType.
 #Subtopic YUV_ColorSpace
 #Alias YUV_ColorSpace
 #Enum SkYUVColorSpace
-#Line # incomplete ##
+#Line # color range of YUV pixels ##
 
 #Code
     enum SkYUVColorSpace {
@@ -881,25 +901,37 @@ and return true if alphaType is not kUnknown_SkAlphaType.
     };
 ##
 
-Describes the color space a YUV pixel.
+Describes color range of YUV pixels. The color mapping from YUV to RGB varies
+depending on the source. YUV pixels may be generated by JPEG images, standard
+video streams, or high definition video streams. Each has its own mapping from
+YUV and RGB.
+
+JPEG YUV values encode the full range of 0 to 255 for all three components.
+Video YUV values range from 16 to 235 for all three components. Details of
+encoding and conversion to RGB are described in 
+#A YCbCr color space # https://en.wikipedia.org/wiki/YCbCr ##
+.
 
 #Const kJPEG_SkYUVColorSpace 0
-Standard JPEG color space.
+Describes standard JPEG color space; 
+#A CCIR 601 # https://en.wikipedia.org/wiki/Rec._601 ##
+with full range of 0 to 255 for components.
 ##
 #Const kRec601_SkYUVColorSpace 1
-SDTV standard Rec. 601 color space. Uses "studio swing" [16, 235] color
-range. See http://en.wikipedia.org/wiki/Rec._601 for details.
+Describes standard used by SDTV;
+#A CCIR 601 # https://en.wikipedia.org/wiki/Rec._601 ##
+with studio range of 16 to 235 range for components.
 ##
 #Const kRec709_SkYUVColorSpace 2
-HDTV standard Rec. 709 color space. Uses "studio swing" [16, 235] color
-range. See http://en.wikipedia.org/wiki/Rec._709 for details.
+Describes standard used by HDTV;
+#A Rec. 709 # http://en.wikipedia.org/wiki/Rec._709 ##
+with studio range of 16 to 235 range for components.
 ##
 
-#Example
-// incomplete
+#NoExample
 ##
 
-#SeeAlso incomplete
+#SeeAlso SkImage::MakeFromYUVTexturesCopy SkImage::MakeFromNV12TexturesCopy
 
 #Enum SkYUVColorSpace ##
 #Subtopic YUV_ColorSpace ##
@@ -934,7 +966,7 @@ and green; and Color_Space, the range and linearity of colors.
 
 #In Constructor
 #Line # creates with zero dimensions, kUnknown_SkColorType, kUnknown_SkAlphaType ##
-Creates an empty Image_Info with kUnknown_SkColorType,  kUnknown_SkAlphaType,
+Creates an empty Image_Info with kUnknown_SkColorType, kUnknown_SkAlphaType,
 a width and height of zero, and no Color_Space.
 
 #Return empty Image_Info ##
@@ -1122,6 +1154,7 @@ combination is supported.
 #Return created Image_Info ##
 
 #Example
+#Height 128
     SkBitmap bitmap;
     bitmap.allocPixels(SkImageInfo::MakeN32Premul(18, 18));
     SkCanvas offscreen(bitmap);
@@ -1157,6 +1190,7 @@ combination is supported.
 #Return created Image_Info ##
 
 #Example
+#Height 128
     SkBitmap bitmap;
     bitmap.allocPixels(SkImageInfo::MakeN32Premul({18, 18}));
     SkCanvas offscreen(bitmap);
@@ -1855,7 +1889,7 @@ color: kRGBA_F16_SkColorType      shiftPerPixel: 3
 ##
 ##
 
-#SeeAlso incomplete
+#SeeAlso bytesPerPixel minRowBytes SkBitmap::shiftPerPixel SkPixmap::shiftPerPixel
 
 #Method ##
 
@@ -1953,6 +1987,7 @@ rowBytes is smaller than minRowBytes, even though result may be incorrect.
 #Return offset within pixel array ##
 
 #Example
+#Height 128
     uint8_t pixels[][12] = { { 0x00, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00, 0x00},
                              { 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0xFF, 0x00, 0x00},
                              { 0x00, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x00},
@@ -1975,7 +2010,7 @@ rowBytes is smaller than minRowBytes, even though result may be incorrect.
     canvas->drawBitmapRect(bitmap, SkRect::MakeWH(8, 8), SkRect::MakeWH(128, 128), &paint);
 ##
 
-#SeeAlso incomplete
+#SeeAlso height width minRowBytes computeByteSize
 
 #Method ##
 
@@ -1985,64 +2020,68 @@ rowBytes is smaller than minRowBytes, even though result may be incorrect.
 ##
 
 #Method bool operator==(const SkImageInfo& other)_const
+#Line # compares Image_Info for equality ##
 
-#Line # incomplete ##
-#Param other  incomplete ##
-
-#Return incomplete ##
-
-#Example
-// incomplete
-##
-
-#SeeAlso incomplete
-
-#Method ##
-
-# ------------------------------------------------------------------------------
-
-#Method bool operator!=(const SkImageInfo& other)_const
+Compares Image_Info with other, and returns true if width, height, Color_Type,
+Alpha_Type, and Color_Space are equivalent.
 
-#Line # incomplete ##
-#Param other  incomplete ##
+#Param other  Image_Info to compare ##
 
-#Return incomplete ##
+#Return true if Image_Info equals other ##
 
 #Example
-// incomplete
-##
-
-#SeeAlso incomplete
+    SkImageInfo info1 = SkImageInfo::Make(10, 20, kGray_8_SkColorType, kPremul_SkAlphaType);

+    SkImageInfo info2 = SkImageInfo::Make(20, 10, kAlpha_8_SkColorType, kUnpremul_SkAlphaType);

+    SkDebugf("info1 %c= info2\n", info1 == info2 ? '=' : '!');

+    info2 = info2.makeWH(10, 20);

+    SkDebugf("info1 %c= info2\n", info1 == info2 ? '=' : '!');

+    info2 = info2.makeColorType(kGray_8_SkColorType);

+    SkDebugf("info1 %c= info2\n", info1 == info2 ? '=' : '!');

+    info2 = info2.makeAlphaType(kPremul_SkAlphaType);

+    SkDebugf("info1 %c= info2\n", info1 == info2 ? '=' : '!');

+#StdOut

+info1 != info2

+info1 != info2

+info1 != info2

+info1 == info2

+##

+##
+
+#SeeAlso operator!=(const SkImageInfo& other)_const SkColorSpace::Equals
 
 #Method ##
 
 # ------------------------------------------------------------------------------
 
-#Method void unflatten(SkReadBuffer& buffer)
-#In Utility
-#Line # incomplete ##
-#Param buffer  incomplete ##
-
-#Example
-// incomplete
-##
-
-#SeeAlso incomplete
+#Method bool operator!=(const SkImageInfo& other)_const
+#Line # compares Image_Info for inequality ##
 
-#Method ##
+Compares Image_Info with other, and returns true if width, height, Color_Type,
+Alpha_Type, and Color_Space are equivalent.
 
-# ------------------------------------------------------------------------------
+#Param other  Image_Info to compare ##
 
-#Method void flatten(SkWriteBuffer& buffer) const
-#In Utility
-#Line # incomplete ##
-#Param buffer  incomplete ##
+#Return true if Image_Info is not equal to other ##
 
 #Example
-// incomplete
-##
-
-#SeeAlso incomplete
+    SkImageInfo info1 = SkImageInfo::Make(10, 20, kGray_8_SkColorType, kPremul_SkAlphaType);

+    SkImageInfo info2 = SkImageInfo::Make(20, 10, kAlpha_8_SkColorType, kUnpremul_SkAlphaType);

+    SkDebugf("info1 %c= info2\n", info1 != info2 ? '!' : '=');

+    info2 = info2.makeWH(10, 20);

+    SkDebugf("info1 %c= info2\n", info1 != info2 ? '!' : '=');

+    info2 = info2.makeColorType(kGray_8_SkColorType);

+    SkDebugf("info1 %c= info2\n", info1 != info2 ? '!' : '=');

+    info2 = info2.makeAlphaType(kPremul_SkAlphaType);

+    SkDebugf("info1 %c= info2\n", info1 != info2 ? '!' : '=');

+#StdOut

+info1 != info2

+info1 != info2

+info1 != info2

+info1 == info2

+##

+##
+
+#SeeAlso operator==(const SkImageInfo& other)_const SkColorSpace::Equals
 
 #Method ##
 
@@ -2050,25 +2089,33 @@ rowBytes is smaller than minRowBytes, even though result may be incorrect.
 
 #Method size_t computeByteSize(size_t rowBytes) const
 #In Utility
-#Line # incomplete ##
-Returns the size (in bytes) of the image buffer that this info needs, given the specified
-rowBytes. The rowBytes must be >= this->minRowBytes().
-if (height == 0) {
-return 0;
-} else {
-return (height - 1) * rowBytes + width * bytes_per_pixel.
+#Line # memory required by pixel buffer with given row bytes ##
+Returns storage required by pixel array, given Image_Info dimensions, Color_Type,
+and rowBytes. rowBytes is assumed to be at least as large as minRowBytes().
 
-If the calculation overflows this returns SK_MaxSizeT.
+Returns zero if height is zero.
+Returns SK_MaxSizeT if answer exceeds the range of size_t.
 
-#Param rowBytes  incomplete ##
+#Param rowBytes  size of pixel row or larger ##
 
-#Return incomplete ##
+#Return memory required by pixel buffer ##
 
 #Example
-// incomplete
-##
-
-#SeeAlso incomplete
+#Height 130
+    SkImageInfo info = SkImageInfo::MakeN32Premul(2, 2);

+    const size_t size = info.computeByteSize(100000);

+    SkAutoTMalloc<SkPMColor> storage(size);

+    SkPMColor* pixels = storage.get();

+    SkBitmap bitmap;

+    bitmap.setInfo(info);

+    bitmap.setPixels(pixels);

+    bitmap.eraseColor(SK_ColorRED);

+    canvas->scale(50, 50);

+    canvas->rotate(8);

+    canvas->drawBitmap(bitmap, 2, 0);
+##
+
+#SeeAlso computeMinByteSize validRowBytes
 
 #Method ##
 
@@ -2076,17 +2123,31 @@ If the calculation overflows this returns SK_MaxSizeT.
 
 #Method size_t computeMinByteSize() const
 #In Utility
-#Line # incomplete ##
-Returns the minimum size (in bytes) of the image buffer that this info needs.
-If the calculation overflows, or if the height is 0, this returns 0.
+#Line # least memory required by pixel buffer ##
+Returns storage required by pixel array, given Image_Info dimensions, and 
+Color_Type. Uses minRowBytes() to compute bytes for pixel row.
 
-#Return incomplete ##
+Returns zero if height is zero.
+Returns SK_MaxSizeT if answer exceeds the range of size_t.
 
-#Example
-// incomplete
-##
+#Return least memory required by pixel buffer ##
 
-#SeeAlso incomplete
+#Example
+#Height 130
+    SkImageInfo info = SkImageInfo::MakeN32Premul(2, 2);

+    const size_t size = info.computeMinByteSize();

+    SkAutoTMalloc<SkPMColor> storage(size);

+    SkPMColor* pixels = storage.get();

+    SkBitmap bitmap;

+    bitmap.setInfo(info);

+    bitmap.setPixels(pixels);

+    bitmap.eraseColor(SK_ColorRED);

+    canvas->scale(50, 50);

+    canvas->rotate(8);

+    canvas->drawBitmap(bitmap, 2, 0);
+##
+
+#SeeAlso computeByteSize validRowBytes
 
 #Method ##
 
@@ -2094,18 +2155,31 @@ If the calculation overflows, or if the height is 0, this returns 0.
 
 #Method static bool ByteSizeOverflowed(size_t byteSize)
 #In Utility
-#Line # incomplete ##
-Returns true if the result of computeByteSize (or computeMinByteSize) overflowed
+#Line # checks result of computeByteSize and computeMinByteSize ##
+Returns true if byteSize equals SK_MaxSizeT. computeByteSize and
+computeMinByteSize return SK_MaxSizeT if size_t can not hold buffer size.
 
-#Param byteSize  incomplete ##
+#Param byteSize  result of computeByteSize or computeMinByteSize ##
 
-#Return incomplete ##
+#Return true if computeByteSize or computeMinByteSize result exceeds size_t ##
 
 #Example
-// incomplete
-##
-
-#SeeAlso incomplete
+    SkImageInfo info = SkImageInfo::MakeN32Premul(2, 1000000000);

+    for (size_t rowBytes = 100000000; rowBytes < 10000000000000LL; rowBytes *= 10) {

+        const size_t size = info.computeByteSize(rowBytes);

+        SkDebugf("rowBytes:%llu size:%llu overflowed:%s\n", rowBytes, size,

+                 SkImageInfo::ByteSizeOverflowed(size) ? "true" : "false");

+    }

+#StdOut

+rowBytes:100000000 size:99999999900000008 overflowed:false

+rowBytes:1000000000 size:999999999000000008 overflowed:false

+rowBytes:10000000000 size:9999999990000000008 overflowed:false

+rowBytes:100000000000 size:18446744073709551615 overflowed:true

+rowBytes:1000000000000 size:18446744073709551615 overflowed:true

+##

+##
+
+#SeeAlso computeByteSize computeMinByteSize validRowBytes
 
 #Method ##
 
@@ -2113,16 +2187,27 @@ Returns true if the result of computeByteSize (or computeMinByteSize) overflowed
 
 #Method bool validRowBytes(size_t rowBytes) const
 #In Utility
-#Line # incomplete ##
-#Param rowBytes  incomplete ##
+#Line # checks if row bytes is large enough to contain pixel row ##
+Returns true if rowBytes is smaller than width times pixel size.
 
-#Return incomplete ##
+#Param rowBytes  size of pixel row or larger ##
+
+#Return true if rowBytes is large enough to contain pixel row ##
 
 #Example
-// incomplete
+    SkImageInfo info = SkImageInfo::MakeN32Premul(16, 8);

+    for (size_t rowBytes = 60; rowBytes < 72; rowBytes += sizeof(SkPMColor)) {

+        SkDebugf("validRowBytes(%llu): %s\n", rowBytes, info.validRowBytes(rowBytes) ?

+                 "true" : "false");

+    }

+#StdOut

+validRowBytes(60): false

+validRowBytes(64): true

+validRowBytes(68): true

+##

 ##
 
-#SeeAlso incomplete
+#SeeAlso ByteSizeOverflowed computeByteSize computeMinByteSize
 
 #Method ##
 
@@ -2130,12 +2215,25 @@ Returns true if the result of computeByteSize (or computeMinByteSize) overflowed
 
 #Method void reset()
 #In Constructor
-#Line # incomplete ##
+#Line # sets zero dimensions, kUnknown_SkColorType, kUnknown_SkAlphaType ##
+Creates an empty Image_Info with kUnknown_SkColorType, kUnknown_SkAlphaType,
+a width and height of zero, and no Color_Space.
+
 #Example
-// incomplete
+    SkImageInfo info = SkImageInfo::MakeN32Premul(16, 8);

+    SkImageInfo copy = info;

+    SkDebugf("info %c= copy\n", info == copy ? '=' : '!');

+    copy.reset();

+    SkDebugf("info %c= reset copy\n", info == copy ? '=' : '!');

+    SkDebugf("SkImageInfo() %c= reset copy\n", SkImageInfo() == copy ? '=' : '!');

+#StdOut

+info == copy

+info != reset copy

+SkImageInfo() == reset copy

+##

 ##
 
-#SeeAlso incomplete
+#SeeAlso SkImageInfo()
 
 #Method ##
 
@@ -2147,12 +2245,14 @@ Returns true if the result of computeByteSize (or computeMinByteSize) overflowed
 
 #Method void validate() const
 #In Utility
-#Line # incomplete ##
-#Example
-// incomplete
+#Line # asserts if Image_Info is invalid (debug only) ##
+Asserts if internal values are illegal or inconsistent. Only available if 
+SK_DEBUG is defined at compile time.
+
+#NoExample
 ##
 
-#SeeAlso incomplete
+#SeeAlso validRowBytes SkBitmap::validate
 
 #Method ##