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>

7 files changed, 248 insertions, 136 deletions

diff --git a/docs/SkBitmap_Reference.bmh b/docs/SkBitmap_Reference.bmh
index 598b9e904f..584672af3f 100644
--- a/docs/SkBitmap_Reference.bmh
+++ b/docs/SkBitmap_Reference.bmh
@@ -3433,7 +3433,7 @@ SK_DEBUG is defined at compile time.
 #NoExample
 ##
 
-#SeeAlso SkImageInfo::validate() 
+#SeeAlso SkImageInfo::validate
 
 ##
 
diff --git a/docs/SkIRect_Reference.bmh b/docs/SkIRect_Reference.bmh
index 7c79c552b1..1ad4044cce 100644
--- a/docs/SkIRect_Reference.bmh
+++ b/docs/SkIRect_Reference.bmh
@@ -573,7 +573,7 @@ Result is rounded down.
    SkDebugf("left: %d right: %d centerX: %d ", rect.left(), rect.right(), rect.centerX());
    SkDebugf("safe mid x: %d\n", rect.left() / 2 + rect.right() / 2);
 #StdOut
-left: 1073741824 right: 1073741826 centerX: -1073741823 safe mid x: 1073741825
+left: 1073741824 right: 1073741826 centerX: 1073741825 safe mid x: 1073741825
 ##
 ##
 
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 ##
 
diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh
index 6ab52bdddc..5c03452103 100644
--- a/docs/SkPaint_Reference.bmh
+++ b/docs/SkPaint_Reference.bmh
@@ -326,7 +326,7 @@ After the call, paint is undefined, and can be safely destructed.
             paint1 != paint2
         ##
     ##
-
+#SeeAlso operator!=(const SkPaint& a, const SkPaint& b)
 ##
 
 # ------------------------------------------------------------------------------
@@ -356,7 +356,7 @@ After the call, paint is undefined, and can be safely destructed.
         paint1 == paint2
     ##
 ##
-
+#SeeAlso operator==(const SkPaint& a, const SkPaint& b)
 ##
 
 # ------------------------------------------------------------------------------
diff --git a/docs/SkPath_Reference.bmh b/docs/SkPath_Reference.bmh
index 790dd5a6bd..869e72e5fd 100644
--- a/docs/SkPath_Reference.bmh
+++ b/docs/SkPath_Reference.bmh
@@ -5235,8 +5235,8 @@ void draw(SkCanvas* canvas) {
     SkDebugf("length = %u; returned by readFromMemory = %u\n", largerSize, bytesRead);
 }
 #StdOut
-length = 60; returned by readFromMemory = 0
-length = 68; returned by readFromMemory = 64
+length = 32; returned by readFromMemory = 0

+length = 40; returned by readFromMemory = 36
 ##
 ##
 
diff --git a/docs/SkSurface_Reference.bmh b/docs/SkSurface_Reference.bmh
index e634ad5dd9..c579ec49af 100644
--- a/docs/SkSurface_Reference.bmh
+++ b/docs/SkSurface_Reference.bmh
@@ -352,6 +352,8 @@ void draw(SkCanvas* ) {
                                                    SkColorType colorType,
                                                    sk_sp<SkColorSpace> colorSpace,
                                                    const SkSurfaceProps* surfaceProps)
+#In Constructor
+#Line # creates Surface from GPU texture ##
 
 Wraps a GPU-backed texture into Surface. Caller must ensure the texture is
 valid for the lifetime of returned Surface. If sampleCnt greater than zero,
@@ -372,7 +374,7 @@ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
 #Param sampleCnt  samples per pixel, or 0 to disable full scene anti-aliasing ##
 #Param colorType  one of: #list_of_color_types#
 ##
-#Param colorSpace  range of colors ##
+#Param colorSpace  range of colors; may be nullptr ##
 #Param surfaceProps  LCD striping orientation and setting for device independent
                      fonts; may be nullptr
 ##
@@ -380,8 +382,8 @@ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
 #Return Surface if all parameters are valid; otherwise, nullptr ##
 
 #Example
-#ToDo  remove !fiddle below once backEndTextureRenderTarget is available ##
-#Platform !fiddle gpu cpu
+#Platform gpu cpu
+#Image 3
     SkPaint paint;
     paint.setTextSize(32);
     GrContext* context = canvas->getGrContext();
@@ -390,10 +392,9 @@ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
          return;
     }
     sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendTexture(context,
-            backEndTextureRenderTarget, kTopLeft_GrSurfaceOrigin,
-            kRGBA_8888_SkColorType, 0, nullptr, nullptr);
+            backEndTexture, kTopLeft_GrSurfaceOrigin, 0,
+            kRGBA_8888_SkColorType, nullptr, nullptr);
     auto surfaceCanvas = gpuSurface->getCanvas();
-    surfaceCanvas->clear(SK_ColorWHITE);
     surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
     sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
     canvas->drawImage(image, 0, 0);
@@ -448,7 +449,6 @@ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
     sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendRenderTarget(context,
             backEndRenderTarget, kTopLeft_GrSurfaceOrigin, nullptr, nullptr);
     auto surfaceCanvas = gpuSurface->getCanvas();
-    surfaceCanvas->clear(SK_ColorWHITE);
     surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
     sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
     canvas->drawImage(image, 0, 0);
@@ -467,8 +467,8 @@ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
                                                 sk_sp<SkColorSpace> colorSpace,
                                                 const SkSurfaceProps* surfaceProps)
 
-Wraps a GPU-backed buffer into Surface. Caller must ensure render target is
-valid for the lifetime of returned Surface.
+Wraps a GPU-backed buffer into Surface. Caller must ensure backendRenderTarget
+is valid for the lifetime of returned Surface.
 
 Surface is returned if all parameters are valid. backendRenderTarget is valid if
 its pixel configuration agrees with colorSpace and context; for instance, if
@@ -505,7 +505,6 @@ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
             backEndRenderTarget, kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType,
             nullptr, nullptr);
     auto surfaceCanvas = gpuSurface->getCanvas();
-    surfaceCanvas->clear(SK_ColorWHITE);
     surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
     sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
     canvas->drawImage(image, 0, 0);
@@ -524,12 +523,21 @@ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
                                                             SkColorType colorType,
                                                             sk_sp<SkColorSpace> colorSpace,
                                                             const SkSurfaceProps* surfaceProps)
+#In Constructor
+#Line # creates Surface from GPU back-end render target ##
+
+Wraps a GPU-backed texture into Surface. Caller must ensure backendTexture is
+valid for the lifetime of returned Surface. If sampleCnt greater than zero,
+creates an intermediate MSAA Surface which is used for drawing backendTexture.
 
-Used to wrap a GPU-backed texture as a SkSurface. Skia will treat the texture as
-a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
-the associated render target objects (but not the provided texture). Skia will not assume
-ownership of the texture and the client must ensure the texture is valid for the lifetime
-of the SkSurface.
+Surface is returned if all parameters are valid. backendTexture is valid if
+its pixel configuration agrees with colorSpace and context; for instance, if
+backendTexture has an sRGB configuration, then context must support sRGB,
+and colorSpace must be present. Further, backendTexture width and height must
+not exceed context capabilities.
+
+Returned Surface is available only for drawing into, and cannot generate an
+Image.
 
 If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
 
@@ -539,7 +547,7 @@ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
 #Param sampleCnt  samples per pixel, or 0 to disable full scene anti-aliasing ##
 #Param colorType  one of: #list_of_color_types#
 ##
-#Param colorSpace  range of colors ##
+#Param colorSpace  range of colors; may be nullptr ##
 #Param surfaceProps  LCD striping orientation and setting for device independent
                      fonts; may be nullptr
 ##
@@ -547,22 +555,23 @@ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
 #Return Surface if all parameters are valid; otherwise, nullptr ##
 
 #Example
-#Platform !fiddle gpu
-    SkPaint paint;
-    paint.setTextSize(32);
-    GrContext* context = canvas->getGrContext();
-    if (!context) {
-         canvas->drawString("GPU only!", 20, 40, paint);
-         return;
-    }
-    sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendTextureAsRenderTarget(
-            context, backEndTextureRenderTarget, kTopLeft_GrSurfaceOrigin, 0,
-            kRGBA_8888_SkColorType, nullptr, nullptr);
-    auto surfaceCanvas = gpuSurface->getCanvas();
-    surfaceCanvas->clear(SK_ColorWHITE);
-    surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);
-    sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
-    canvas->drawImage(image, 0, 0);
+#ToDo example is bogus; gpuSurface should not make image ##
+#Platform gpu
+#Image 3
+    SkPaint paint;

+    paint.setTextSize(32);

+    GrContext* context = canvas->getGrContext();

+    if (!context) {

+         canvas->drawString("GPU only!", 20, 40, paint);

+         return;

+    }

+    sk_sp<SkSurface> gpuSurface = SkSurface::MakeFromBackendTextureAsRenderTarget(

+            context, backEndTexture, kTopLeft_GrSurfaceOrigin, 0,

+            kRGBA_8888_SkColorType, nullptr, nullptr);

+    auto surfaceCanvas = gpuSurface->getCanvas();

+    surfaceCanvas->drawString("GPU rocks!", 20, 40, paint);

+    sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());

+    canvas->drawImage(image, 0, 0);

 ##
 
 #SeeAlso MakeFromBackendRenderTarget MakeRenderTarget
diff --git a/docs/undocumented.bmh b/docs/undocumented.bmh
index 094b5c2b27..da8b9fceee 100644
--- a/docs/undocumented.bmh
+++ b/docs/undocumented.bmh
@@ -33,6 +33,7 @@
  SK_HAS_JPEG_LIBRARY # ditto
  SK_HAS_PNG_LIBRARY # ditto
  SK_HAS_WEBP_LIBRARY # ditto
+ SK_PMCOLOR_BYTE_ORDER # ditto
 
 # FreeType related
 FT_LOAD_TARGET_LIGHT
@@ -169,6 +170,8 @@ FT_Load_Glyph
     ##
     #Method bool gammaCloseToSRGB() const
     ##
+    #Method static bool Equals(const SkColorSpace* src, const SkColorSpace* dst)
+    ##
 ##
 #EnumClass SkTransferFunctionBehavior
 #Const kRespect 0