working on skimage

working on skimage

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

5 files changed, 394 insertions, 274 deletions

diff --git a/docs/SkCanvas_Reference.bmh b/docs/SkCanvas_Reference.bmh
index 55dc86ba35..efbf41f57e 100644
--- a/docs/SkCanvas_Reference.bmh
+++ b/docs/SkCanvas_Reference.bmh
@@ -5316,6 +5316,8 @@ Paint_Text_Align, Paint_Hinting, Anti-alias, Paint_Fake_Bold,
 Font_Embedded_Bitmaps, Full_Hinting_Spacing, LCD_Text, Linear_Text,
 Subpixel_Text, and Paint_Vertical_Text.
 
+Paint_Text_Encoding must be set to SkPaint::kGlyphID_TextEncoding.
+
 Elements of paint: Path_Effect, Rasterizer, Mask_Filter, Shader, Color_Filter, 
 Image_Filter, and Draw_Looper; apply to blob.
 
@@ -5327,25 +5329,26 @@ Image_Filter, and Draw_Looper; apply to blob.
 #Example
 #Height 120
     void draw(SkCanvas* canvas) {
-        SkTextBlobBuilder textBlobBuilder;
-        const char bunny[] = "/(^x^)\\";
-        const int len = sizeof(bunny) - 1;
-        uint16_t glyphs[len];
-        SkPaint paint;
-        paint.textToGlyphs(bunny, len, glyphs);
-        int runs[] = { 3, 1, 3 };
-        SkPoint textPos = { 20, 100 };
-        int glyphIndex = 0;
-        for (auto runLen : runs) {
-            paint.setTextSize(1 == runLen ? 20 : 50);
-            const SkTextBlobBuilder::RunBuffer& run = 
-                    textBlobBuilder.allocRun(paint, runLen, textPos.fX, textPos.fY);
-            memcpy(run.glyphs, &glyphs[glyphIndex], sizeof(glyphs[0]) * runLen);
-            textPos.fX += paint.measureText(&bunny[glyphIndex], runLen, nullptr);
-            glyphIndex += runLen;
-        }
-        sk_sp<const SkTextBlob> blob = textBlobBuilder.make();
-        paint.reset();
+        SkTextBlobBuilder textBlobBuilder;

+        const char bunny[] = "/(^x^)\\";

+        const int len = sizeof(bunny) - 1;

+        uint16_t glyphs[len];

+        SkPaint paint;

+        paint.textToGlyphs(bunny, len, glyphs);

+        paint.setTextEncoding(SkPaint::kGlyphID_TextEncoding);
+        int runs[] = { 3, 1, 3 };

+        SkPoint textPos = { 20, 100 };

+        int glyphIndex = 0;

+        for (auto runLen : runs) {

+            paint.setTextSize(1 == runLen ? 20 : 50);

+            const SkTextBlobBuilder::RunBuffer& run = 

+                    textBlobBuilder.allocRun(paint, runLen, textPos.fX, textPos.fY);

+            memcpy(run.glyphs, &glyphs[glyphIndex], sizeof(glyphs[0]) * runLen);

+            textPos.fX += paint.measureText(&glyphs[glyphIndex], sizeof(glyphs[0]) * runLen, nullptr);

+            glyphIndex += runLen;

+        }

+        sk_sp<const SkTextBlob> blob = textBlobBuilder.make();

+        paint.reset();

         canvas->drawTextBlob(blob.get(), 0, 0, paint);
     }
 ##
@@ -5366,6 +5369,8 @@ Paint_Text_Align, Paint_Hinting, Anti-alias, Paint_Fake_Bold,
 Font_Embedded_Bitmaps, Full_Hinting_Spacing, LCD_Text, Linear_Text,
 Subpixel_Text, and Paint_Vertical_Text.
 
+Paint_Text_Encoding must be set to SkPaint::kGlyphID_TextEncoding.
+
 Elements of paint: Path_Effect, Rasterizer, Mask_Filter, Shader, Color_Filter, 
 Image_Filter, and Draw_Looper; apply to blob.
 
@@ -5385,6 +5390,7 @@ Paint attributes related to text, like text size, have no effect on paint passed
         SkPaint paint;
         paint.setTextSize(50);
         paint.setColor(SK_ColorRED);
+        paint.setTextEncoding(SkPaint::kGlyphID_TextEncoding);

         const SkTextBlobBuilder::RunBuffer& run = 
                 textBlobBuilder.allocRun(paint, 1, 20, 100);
         run.glyphs[0] = 20;
diff --git a/docs/SkImage_Reference.bmh b/docs/SkImage_Reference.bmh
index 05d38ff522..22ba343b64 100644
--- a/docs/SkImage_Reference.bmh
+++ b/docs/SkImage_Reference.bmh
@@ -39,24 +39,23 @@ are zero, then nullptr will be returned.
 #Legend
 # description                      # function ##
 #Legend ##
-# MakeFromAHardwareBuffer          # ##
-# MakeBackendTextureFromSkImage    # ##
-# MakeCrossContextFromEncoded      # ##
-# MakeFromAHardwareBuffer          # ##
-# MakeFromAdoptedTexture           # ##
-# MakeFromBitmap                   # ##
-# MakeFromDeferredTextureImageData # ##
-# MakeFromEncoded                  # ##
-# MakeFromGenerator                # ##
-# MakeFromNV12TexturesCopy         # ##
-# MakeFromPicture                  # ##
-# MakeFromRaster                   # ##
-# MakeFromTexture                  # ##
-# MakeFromYUVTexturesCopy          # ##
-# MakeRasterCopy                   # ##
-# MakeRasterData                   # ##
-# alphaType                        # ##
-# asLegacyBitmap                   # ##
+# MakeBackendTextureFromSkImage    # Creates GPU texture from Image. ##
+# MakeCrossContextFromEncoded      # Creates Image from encoded data, and uploads to GPU. ##
+# MakeFromAHardwareBuffer          # Creates Image from Android hardware buffer. ##
+# MakeFromAdoptedTexture           # Creates Image from GPU texture, managed internally. ##
+# MakeFromBitmap                   # Creates Image from Bitmap, sharing or copying pixels. ##
+# MakeFromDeferredTextureImageData # Creates Image from GPU texture data retrieved earlier. ##
+# MakeFromEncoded                  # Creates Image from encoded data. ##
+# MakeFromGenerator                # Creates Image from a stream of data. ##
+# MakeFromNV12TexturesCopy         # Creates Image from YUV_ColorSpace data in two planes. ##
+# MakeFromPicture                  # Creates Image from Picture. ##
+# MakeFromRaster                   # Creates Image from Pixmap, with release. ##
+# MakeFromTexture                  # Creates Image from GPU texture, managed externally. ##
+# MakeFromYUVTexturesCopy          # Creates Image from YUV_ColorSpace data in three planes. ##
+# MakeRasterCopy                   # Creates Image from Pixmap and copied pixels. ##
+# MakeRasterData                   # Creates Image from Image_Info and shared pixels. ##
+# alphaType                        # Returns Alpha_Type ##
+# asLegacyBitmap                   # Returns as raster Bitmap ##
 # bounds                           # ##
 # colorSpace                       # ##
 # dimensions                       # ##
@@ -133,23 +132,28 @@ Drawing parameters for which a deferred texture image data should be optimized.
 
 ##
 
-#Typedef void* ReleaseContext
-
-##
-
 # ------------------------------------------------------------------------------
 
 #Method static sk_sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap)
 
-#Param pixmap  incomplete ##
+Creates Image from Pixmap and copy of pixels.
 
-#Return incomplete ##
+Image is returned if Pixmap is valid. Valid Pixmap parameters include:
+dimensions are greater than zero;
+each dimension fits in 29 bits;
+Color_Type and Alpha_Type are valid, and Color_Type is not kUnknown_SkColorType;
+row bytes are large enough to hold one row of pixels;
+pixel address is not nullptr.
+
+#Param pixmap  Image_Info, pixel address, and row bytes ##
+
+#Return copy of Pixmap pixels, or nullptr  ##
 
 #Example
 // incomplete
 ##
 
-#SeeAlso incomplete
+#SeeAlso MakeRasterData MakeFromGenerator
 
 #Method ##
 
@@ -157,38 +161,66 @@ Drawing parameters for which a deferred texture image data should be optimized.
 
 #Method static sk_sp<SkImage> MakeRasterData(const Info& info, sk_sp<SkData> pixels, size_t rowBytes)
 
-#Param info  incomplete ##
-#Param pixels  incomplete ##
-#Param rowBytes  incomplete ##
+Creates Image from Image_Info, sharing pixels.
 
-#Return incomplete ##
+Image is returned if Image_Info is valid. Valid Image_Info parameters include:
+dimensions are greater than zero;
+each dimension fits in 29 bits;
+Color_Type and Alpha_Type are valid, and Color_Type is not kUnknown_SkColorType;
+rowBytes are large enough to hold one row of pixels;
+pixels is not nullptr, and contains enough data for Image.
+
+#Param info  contains width, height, Alpha_Type, Color_Type, Color_Space ##
+#Param pixels  address or pixel storage ##
+#Param rowBytes  size of pixel row or larger ##
+
+#Return Image sharing pixels, or nullptr ##
 
 #Example
 // incomplete
 ##
 
-#SeeAlso incomplete
+#SeeAlso MakeRasterCopy MakeFromGenerator
 
 #Method ##
 
 # ------------------------------------------------------------------------------
 
+#Typedef void* ReleaseContext
+
+Caller data passed to RasterReleaseProc; may be nullptr.
+
+#SeeAlso MakeFromRaster RasterReleaseProc
+
+##
+
 #Typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext)
 
+Function called when Image no longer shares pixels. ReleaseContext is
+provided by caller when Image is created, and may be nullptr.   
+
+#SeeAlso ReleaseContext MakeFromRaster
+
 ##
 
 #Method static sk_sp<SkImage> MakeFromRaster(const SkPixmap& pixmap,
                                          RasterReleaseProc rasterReleaseProc,
                                          ReleaseContext releaseContext)
 
-Return a new Image referencing the specified pixels. These must remain valid and unchanged
-until the specified release-proc is called, indicating that Skia no longer has a reference
-to the pixels.
-Returns nullptr if the requested pixmap info is unsupported.
+Creates Image from pixmap, sharing pixmap pixels. Pixels must remain valid and
+unchanged until rasterReleaseProc is called. rasterReleaseProc is passed
+releaseContext when Image is deleted or no longer refers to pixmap pixels.
 
-#Param pixmap  incomplete ##
-#Param rasterReleaseProc  incomplete ##
-#Param releaseContext  incomplete ##
+Image is returned if pixmap is valid. Valid Pixmap parameters include:
+dimensions are greater than zero;
+each dimension fits in 29 bits;
+Color_Type and Alpha_Type are valid, and Color_Type is not kUnknown_SkColorType;
+row bytes are large enough to hold one row of pixels;
+pixel address is not nullptr.
+
+#Param pixmap  Image_Info, pixel address, and row bytes ##
+#Param rasterReleaseProc  function called when pixels can be released ##
+#Param releaseContext  state passed to rasterReleaseProc ##
 
 #Return incomplete ##
 
@@ -196,7 +228,7 @@ Returns nullptr if the requested pixmap info is unsupported.
 // incomplete
 ##
 
-#SeeAlso incomplete
+#SeeAlso MakeRasterCopy MakeRasterData MakeFromGenerator RasterReleaseProc ReleaseContext
 
 #Method ##
 
@@ -204,18 +236,26 @@ Returns nullptr if the requested pixmap info is unsupported.
 
 #Method static sk_sp<SkImage> MakeFromBitmap(const SkBitmap& bitmap)
 
-Construct a new image from the specified bitmap. If the bitmap is marked immutable, and
-its pixel memory is shareable, it may be shared instead of copied.
+Creates Image from bitmap, sharing or copying bitmap pixels. If the bitmap 
+is marked immutable, and its pixel memory is shareable, it may be shared
+instead of copied.
 
-#Param bitmap  incomplete ##
+Image is returned if bitmap is valid. Valid Bitmap parameters include:
+dimensions are greater than zero;
+each dimension fits in 29 bits;
+Color_Type and Alpha_Type are valid, and Color_Type is not kUnknown_SkColorType;
+row bytes are large enough to hold one row of pixels;
+pixel address is not nullptr.
 
-#Return incomplete ##
+#Param bitmap  Image_Info, row bytes, and pixels ##
+
+#Return created Image, or nullptr ##
 
 #Example
 // incomplete
 ##
 
-#SeeAlso incomplete
+#SeeAlso MakeFromRaster MakeRasterCopy MakeFromGenerator MakeRasterData
 
 #Method ##
 
@@ -224,20 +264,25 @@ its pixel memory is shareable, it may be shared instead of copied.
 #Method static sk_sp<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator,
                                             const SkIRect* subset = nullptr)
 
-Construct a new SkImage based on the given ImageGenerator. Returns nullptr on error.
-This function will always take ownership of the passed generator.
-If a subset is specified, it must be contained within the generator's bounds.
+Creates Image based from imageGenerator.
+Takes ownership of imageGenerator; it may not be used elsewhere.
+If subset is not nullptr, it must be contained within imageGenerator data bounds.
 
-#Param imageGenerator  incomplete ##
-#Param subset  incomplete ##
+Image is returned if generator data is valid. Valid data parameters vary
+by type of data and platform.
 
-#Return incomplete ##
+imageGenerator may wrap Picture data, codec data, or custom data.
+
+#Param imageGenerator  stock or custom routines to retrieve Image ##
+#Param subset  bounds of returned Image; may be nullptr ##
+
+#Return created Image, or nullptr ##
 
 #Example
 // incomplete
 ##
 
-#SeeAlso incomplete
+#SeeAlso MakeFromEncoded
 
 #Method ##
 
@@ -245,20 +290,22 @@ If a subset is specified, it must be contained within the generator's bounds.
 
 #Method static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded, const SkIRect* subset = nullptr)
 
-Construct a new SkImage based on the specified encoded data. Returns nullptr on failure,
-which can mean that the format of the encoded data was not recognized/supported.
-If a subset is specified, it must be contained within the encoded data's bounds.
+Creates Image from encoded data. 
+If a subset is not nullptr, it must be contained within encoded data bounds.
 
-#Param encoded  incomplete ##
-#Param subset  incomplete ##
+Image is returned if format of the encoded data is recognized and supported.
+Recognized formats vary by platfrom.
 
-#Return incomplete ##
+#Param encoded  data of Image to decode ##
+#Param subset  bounds of returned Image; may be nullptr ##
+
+#Return created Image, or nullptr ##
 
 #Example
 // incomplete
 ##
 
-#SeeAlso incomplete
+#SeeAlso MakeFromGenerator
 
 #Method ##
 
@@ -274,23 +321,27 @@ If a subset is specified, it must be contained within the encoded data's bounds.
                                           SkAlphaType alphaType,
                                           sk_sp<SkColorSpace> colorSpace)
 
-Create a new image from the specified descriptor. Note - the caller is responsible for
-managing the lifetime of the underlying platform texture.
-Will return nullptr if the specified back-end texture is unsupported.
+Creates Image from GPU texture associated with context. Caller is responsible for
+managing the lifetime of GPU texture.
 
-#Param context  incomplete ##
-#Param backendTexture  incomplete ##
-#Param origin  incomplete ##
-#Param alphaType  incomplete ##
-#Param colorSpace  incomplete ##
+Image is returned if format of backendTexture is recognized and supported.
+Recognized formats vary by GPU back-end.
 
-#Return incomplete ##
+#Param context  GPU_Context ##
+#Param backendTexture  texture residing on GPU ##
+#Param origin  one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
+#Param alphaType  one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
+                          kPremul_SkAlphaType, kUnpremul_SkAlphaType
+##
+#Param colorSpace  range of colors ##
+
+#Return created Image, or nullptr ##
 
 #Example
 // incomplete
 ##
 
-#SeeAlso incomplete
+#SeeAlso MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture
 
 #Method ##
 
@@ -304,26 +355,30 @@ Will return nullptr if the specified back-end texture is unsupported.
                                           TextureReleaseProc textureReleaseProc,
                                           ReleaseContext releaseContext)
 
-Create a new image from the GrBackendTexture. The underlying platform texture must stay
-valid and unaltered until the specified release-proc is invoked, indicating that Skia
-no longer is holding a reference to it.
-Will return nullptr if the specified back-end texture is unsupported.
+Creates Image from GPU texture associated with context. GPU texture must stay
+valid and unchanged until textureReleaseProc is called. textureReleaseProc is
+passed releaseContext when Image is deleted or no longer refers to texture.
 
-#Param context  incomplete ##
-#Param backendTexture  incomplete ##
-#Param origin  incomplete ##
-#Param alphaType  incomplete ##
-#Param colorSpace  incomplete ##
-#Param textureReleaseProc  incomplete ##
-#Param releaseContext  incomplete ##
+Image is returned if format of backendTexture is recognized and supported.
+Recognized formats vary by GPU back-end.
 
-#Return incomplete ##
+#Param context  GPU_Context ##
+#Param backendTexture  texture residing on GPU ##
+#Param origin  one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
+#Param alphaType  one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
+                          kPremul_SkAlphaType, kUnpremul_SkAlphaType
+##
+#Param colorSpace  range of colors ##
+#Param textureReleaseProc  function called when texture can be released ##
+#Param releaseContext  state passed to textureReleaseProc ##
+
+#Return created Image, or nullptr ##
 
 #Example
 // incomplete
 ##
 
-#SeeAlso incomplete
+#SeeAlso MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture
 
 #Method ##
 
@@ -333,28 +388,71 @@ Will return nullptr if the specified back-end texture is unsupported.
                                                       bool buildMips,
                                                       SkColorSpace* dstColorSpace)
 
-Decodes and uploads the encoded data to a GPU backed image using the supplied GrContext.
-That image can be safely used by other GrContexts, across thread boundaries. The GrContext
-used here, and the ones used to draw this image later must be in the same OpenGL share group,
-or otherwise be able to share resources.
-When the image's ref count reaches zero, the original GrContext will destroy the texture,
+Creates Image from encoded data. Image is uploaded to GPU back-end using context. 
+
+Created Image is available to other GPU contexts, and is available across thread
+boundaries. All contexts must be in the same GPU_Share_Group, or otherwise 
+share resources.
+
+When Image is no longer referenced, context releases texture memory
 asynchronously.
-The texture will be decoded and uploaded to be suitable for use with surfaces that have the
-supplied destination color space. The color space of the image itself will be determined
-from the encoded data.
 
-#Param context  incomplete ##
-#Param data  incomplete ##
-#Param buildMips  incomplete ##
-#Param dstColorSpace  incomplete ##
+Texture decoded from data is uploaded to match Surface created with
+dstColorSpace. Color_Space of Image is determined by encoded data.
 
-#Return incomplete ##
+Image is returned if format of data is recognized and supported, and if context
+supports moving resources. Recognized formats vary by platform and GPU back-end.
+
+#Param context  GPU_Context ##
+#Param data  Image to decode ##
+#Param buildMips  create Image as Mip_Map if true ##
+#Param dstColorSpace  range of colors of matching Surface on GPU ##
+
+#Return created Image, or nullptr ##
 
 #Example
 // incomplete
 ##
 
-#SeeAlso incomplete
+#SeeAlso MakeCrossContextFromPixmap
+
+#Method ##
+
+# ------------------------------------------------------------------------------
+
+#Method static sk_sp<SkImage> MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap,
+                                                      bool buildMips,
+                                                      SkColorSpace* dstColorSpace)
+
+Creates Image from pixmap. Image is uploaded to GPU back-end using context. 
+
+Created Image is available to other GPU contexts, and is available across thread
+boundaries. All contexts must be in the same GPU_Share_Group, or otherwise 
+share resources.
+
+When Image is no longer referenced, context releases texture memory
+asynchronously.
+
+Texture created from pixmap is uploaded to match Surface created with
+dstColorSpace. Color_Space of Image is determined by pixmap.colorSpace().
+
+Image is returned referring to GPU back-end if format of data is recognized and 
+supported, and if context supports moving resources. Otherwise, pixmap pixel
+data is copied and Image as returned in raster format if possible; nullptr may
+be returned. Recognized GPU formats vary by platform and GPU back-end.
+
+#Param context  GPU_Context ##
+#Param pixmap  Image_Info, pixel address, and row bytes ##
+#Param buildMips  create Image as Mip_Map if true ##
+#Param dstColorSpace  range of colors of matching Surface on GPU ##
+
+#Return created Image, or nullptr ##
+
+#Example
+// incomplete
+##
+
+#SeeAlso MakeCrossContextFromEncoded
 
 #Method ##
 
@@ -366,17 +464,21 @@ from the encoded data.
                                                  SkAlphaType alphaType = kPremul_SkAlphaType,
                                                  sk_sp<SkColorSpace> colorSpace = nullptr)
 
-Create a new image from the specified descriptor. Note - Skia will delete or recycle the
-texture when the image is released.
-Will return nullptr if the specified back-end texture is unsupported.
+Creates Image from backendTexture associated with context. backendTexture and
+returned Image are managed internally, and are released when no longer needed.
 
-#Param context  incomplete ##
-#Param backendTexture  incomplete ##
-#Param surfaceOrigin  incomplete ##
-#Param alphaType  incomplete ##
-#Param colorSpace  incomplete ##
+Image is returned if format of backendTexture is recognized and supported.
+Recognized formats vary by GPU back-end.
 
-#Return incomplete ##
+#Param context  GPU_Context ##
+#Param backendTexture  texture residing on GPU ##
+#Param surfaceOrigin  one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ##
+#Param alphaType  one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
+                          kPremul_SkAlphaType, kUnpremul_SkAlphaType
+##
+#Param colorSpace  range of colors ##
+
+#Return created Image, or nullptr ##
 
 #Example
 // incomplete
@@ -1174,18 +1276,33 @@ must be null.
 #Method static sk_sp<SkImage> MakeFromDeferredTextureImageData(GrContext* context, const void* data,
                                                            SkBudgeted budgeted)
 
-Returns a texture-backed image from data produced in SkImage::getDeferredTextureImageData.
+Returns a texture-backed image from data produced in getDeferredTextureImageData.
 The context must be the context that provided the proxy passed to
 getDeferredTextureImageData.
 
-#Param context  incomplete ##
-#Param data  incomplete ##
-#Param budgeted  incomplete ##
+#Param context  GPU_Context ##
+#Param data  buffer filled by getDeferredTextureImageData ##
+#Param budgeted  one of: SkBudgeted::kNo, SkBudgeted::kYes ##
 
 #Return incomplete ##
 
 #Example
-// incomplete
+#Image 3
+#Platform gpu
+    GrContext* context = canvas->getGrContext();
+    if (!context) {
+        return;
+    }
+    sk_sp<GrContextThreadSafeProxy> proxy = context->threadSafeProxy();
+    SkImage::DeferredTextureImageUsageParams params = {SkMatrix::I(), kNone_SkFilterQuality, 0};
+    size_t size = image->getDeferredTextureImageData(*proxy, &params, 1, nullptr,
+            nullptr, kN32_SkColorType);
+    void* buffer = sk_malloc_throw(size);
+    if (image->getDeferredTextureImageData(*proxy, &params, 1, buffer, nullptr, kN32_SkColorType)) {
+        sk_sp<SkImage> newImage(
+            SkImage::MakeFromDeferredTextureImageData(context, buffer, SkBudgeted::kNo));
+        canvas->drawImage(newImage, 0, 0);
+    }
 ##
 
 #SeeAlso incomplete
@@ -1262,16 +1379,15 @@ Helper functions to convert to SkBitmap
 
 #Method bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode) const
 
-Attempt to create a bitmap with the same pixels as the image. The result will always be
-a raster-backed bitmap (texture-backed bitmaps are DEPRECATED, and not supported here).
-If the mode is kRO_LegacyBitmapMode (read-only), the resulting bitmap will be marked as immutable.
-On success, returns true. On failure, returns false and the bitmap parameter will be reset
-to empty.
+Creates raster Bitmap with same pixels as Image. If legacyBitmapMode is kRO_LegacyBitmapMode,
+returned bitmap is read-only and immutable.
+Returns true if Bitmap is stored in bitmap. Returns false and resets bitmap if Bitmap
+write did not succeed.
 
-#Param bitmap  incomplete ##
-#Param legacyBitmapMode  incomplete ##
+#Param bitmap  storage for legacy Bitmap ##
+#Param legacyBitmapMode  one of: kRO_LegacyBitmapMode, kRW_LegacyBitmapMode ##
 
-#Return incomplete ##
+#Return true if Bitmap was created ##
 
 #Example
 // incomplete
diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh
index 8d3bd604c1..4a5da73ca4 100644
--- a/docs/SkPaint_Reference.bmh
+++ b/docs/SkPaint_Reference.bmh
@@ -591,7 +591,6 @@ can reconstitute the paint at a later time.
         void writeRegion(const SkRegion& region) override {}
         void writePath(const SkPath& path) override {}
         size_t writeStream(SkStream* stream, size_t length) override { return 0; }
-        void writeBitmap(const SkBitmap& bitmap) override {}
         void writeImage(const SkImage*) override {}
         void writeTypeface(SkTypeface* typeface) override {}
         void writePaint(const SkPaint& paint) override {}
@@ -5093,10 +5092,12 @@ void draw(SkCanvas* canvas) {
     bounds describes a pair of lines parallel to the text advance.
     The return count is zero or a multiple of two, and is at most twice the number of Glyphs in
     the string. 
-    Uses Text_Encoding to decode text, Typeface to get the glyph paths,
+    Uses Typeface to get the glyph paths,
     and Text_Size, Fake_Bold, and Path_Effect to scale and modify the glyph paths.
     Uses run array and Text_Align to position intervals.
     
+    Text_Encoding must be set to SkPaint::kGlyphID_TextEncoding.
+
     Pass nullptr for intervals to determine the size of the interval array.
     
     intervals are cached to improve performance for multiple calls.
@@ -5111,6 +5112,7 @@ void draw(SkCanvas* canvas) {
     #Height 143
         void draw(SkCanvas* canvas) {
             SkPaint paint;
+            paint.setTextEncoding(SkPaint::kGlyphID_TextEncoding);
             paint.setTextSize(120);
             SkPoint textPos = { 20, 110 };
             int len = 3;
diff --git a/docs/SkSurface_Reference.bmh b/docs/SkSurface_Reference.bmh
index c6cbbbb7aa..f13134fa46 100644
--- a/docs/SkSurface_Reference.bmh
+++ b/docs/SkSurface_Reference.bmh
@@ -625,6 +625,7 @@ Surface bottom-left corner is pinned to the origin.
 #Return Surface if all parameters are valid; otherwise, nullptr ##
 
 #Example
+#Platform cpu gpu
 #Description
 LCD text takes advantage of raster striping to improve resolution. Only one of
 the four combinations is correct, depending on whether the monitor's LCD is
@@ -644,23 +645,18 @@ void draw(SkCanvas* canvas) {
     };
     GrContext* context = canvas->getGrContext();
     SkImageInfo info = SkImageInfo::MakeN32(128, 64, kOpaque_SkAlphaType);
-    SkAutoTMalloc<SkPMColor> storage(info.computeMinByteSize());
-    SkBitmap bitmap;
-    bitmap.installPixels(info, storage.get(), info.minRowBytes());
     int y = 0;
     for (auto geometry : { kRGB_H_SkPixelGeometry, kBGR_H_SkPixelGeometry,
                            kRGB_V_SkPixelGeometry, kBGR_V_SkPixelGeometry } ) {
         SkSurfaceProps props(0, geometry);
-        std::unique_ptr<SkCanvas> offscreen = SkCanvas::MakeRasterDirect(info, storage.get(),
-                info.minRowBytes(), &props);
         sk_sp<SkSurface> surface = context ? SkSurface::MakeRenderTarget(
                 context, SkBudgeted::kNo, info, 0, &props) : SkSurface::MakeRaster(info, &props);
         test_draw(surface->getCanvas());
         surface->draw(canvas, 0, y, nullptr);
-        surface->draw(offscreen.get(), 0, 0, nullptr);
+        sk_sp<SkImage> image(surface->makeImageSnapshot());
         SkAutoCanvasRestore acr(canvas, true);
         canvas->scale(8, 8);
-        canvas->drawBitmap(bitmap, 12, y / 8);
+        canvas->drawImage(image, 12, y / 8);
         y += 64;
     }
 }
@@ -893,43 +889,43 @@ CAN WE DEPRECATE THIS?
     };
 ##
 
-#Const kFlushRead_BackendHandleAccess
+#Const kFlushRead_BackendHandleAccess 0
 Caller may read from the back-end object.
 ##
-#Const kFlushWrite_BackendHandleAccess
+#Const kFlushWrite_BackendHandleAccess 1
 Caller may write to the back-end object.
 ##
-#Const kDiscardWrite_BackendHandleAccess
+#Const kDiscardWrite_BackendHandleAccess 2
 Caller must overwrite the entire back-end object.
 ##
 
 #Example
 #Platform 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::MakeRenderTarget(

-            context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(10, 10));

-    int y = 20;

-    SkString str;

-    paint.setTextSize(16);

-    for (auto access : { SkSurface::kFlushRead_BackendHandleAccess, 

-                         SkSurface::kFlushWrite_BackendHandleAccess,

-                         SkSurface::kDiscardWrite_BackendHandleAccess } ) {

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

-        str.printf("uniqueID=%d", image->uniqueID());

-        canvas->drawString(str, 20, y += 20, paint);

-        GrBackendObject backendObject = gpuSurface->getTextureHandle(access);

-        str.printf("backendObject %c= 0", backendObject != 0 ? '!' : '=');

-        canvas->drawString(str, 20, y += 20, paint);

-    }

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

-    str.printf("final image uniqueID=%d", image->uniqueID());

-    canvas->drawString(str, 20, y += 20, paint);

+    SkPaint paint;
+    paint.setTextSize(32);
+    GrContext* context = canvas->getGrContext();
+    if (!context) {
+         canvas->drawString("GPU only!", 20, 40, paint);
+         return;
+    }
+    sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(
+            context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(10, 10));
+    int y = 20;
+    SkString str;
+    paint.setTextSize(16);
+    for (auto access : { SkSurface::kFlushRead_BackendHandleAccess, 
+                         SkSurface::kFlushWrite_BackendHandleAccess,
+                         SkSurface::kDiscardWrite_BackendHandleAccess } ) {
+        sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
+        str.printf("uniqueID=%d", image->uniqueID());
+        canvas->drawString(str, 20, y += 20, paint);
+        GrBackendObject backendObject = gpuSurface->getTextureHandle(access);
+        str.printf("backendObject %c= 0", backendObject != 0 ? '!' : '=');
+        canvas->drawString(str, 20, y += 20, paint);
+    }
+    sk_sp<SkImage> image(gpuSurface->makeImageSnapshot());
+    str.printf("final image uniqueID=%d", image->uniqueID());
+    canvas->drawString(str, 20, y += 20, paint);
 ##
 
 #SeeAlso getTextureHandle getRenderTargetHandle
@@ -955,23 +951,23 @@ or when Surface is deleted.
 #Example
 #Platform gpu
 #Height 64
-    SkPaint paint;

-    paint.setTextSize(32);

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

-    if (!context) {

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

-         return;

-    }

-    sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(

-            context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(10, 10));

-    GrBackendObject backendObject = gpuSurface->getTextureHandle(

-            SkSurface::kFlushRead_BackendHandleAccess);

-    if (backendObject) {

-        SkString str;

-        str.printf("backendObject=%08x", backendObject);

-        paint.setTextSize(16);

-        canvas->drawString(str, 20, 40, paint);

-    }

+    SkPaint paint;
+    paint.setTextSize(32);
+    GrContext* context = canvas->getGrContext();
+    if (!context) {
+         canvas->drawString("GPU only!", 20, 40, paint);
+         return;
+    }
+    sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(
+            context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(10, 10));
+    GrBackendObject backendObject = gpuSurface->getTextureHandle(
+            SkSurface::kFlushRead_BackendHandleAccess);
+    if (backendObject) {
+        SkString str;
+        str.printf("backendObject=%08x", backendObject);
+        paint.setTextSize(16);
+        canvas->drawString(str, 20, 40, paint);
+    }
 ##
 
 #SeeAlso getRenderTargetHandle GrBackendObject BackendHandleAccess
@@ -1004,23 +1000,23 @@ In OpenGL this returns the frame buffer object ID.
 #Example
 #Platform gpu
 #Height 64
-    SkPaint paint;

-    paint.setTextSize(32);

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

-    if (!context) {

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

-         return;

-    }

-    sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(

-            context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(10, 10));

-    GrBackendObject backendObject;

-    if (gpuSurface->getRenderTargetHandle(&backendObject, 

-            SkSurface::kFlushRead_BackendHandleAccess)) {

-        SkString str;

-        str.printf("backendObject=%d", backendObject);

-        paint.setTextSize(16);

-        canvas->drawString(str, 20, 40, paint);

-    }

+    SkPaint paint;
+    paint.setTextSize(32);
+    GrContext* context = canvas->getGrContext();
+    if (!context) {
+         canvas->drawString("GPU only!", 20, 40, paint);
+         return;
+    }
+    sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(
+            context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(10, 10));
+    GrBackendObject backendObject;
+    if (gpuSurface->getRenderTargetHandle(&backendObject, 
+            SkSurface::kFlushRead_BackendHandleAccess)) {
+        SkString str;
+        str.printf("backendObject=%d", backendObject);
+        paint.setTextSize(16);
+        canvas->drawString(str, 20, 40, paint);
+    }
 ##
 
 #SeeAlso getTextureHandle GrBackendObject BackendHandleAccess
@@ -1349,21 +1345,21 @@ Does not copy, and returns false if:
 #Return true if pixels were copied ##
 
 #Example
-    sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64));

-    auto surfCanvas = surf->getCanvas();

-    surfCanvas->clear(SK_ColorGREEN);

-    SkPaint paint;

-    surfCanvas->drawOval({2, 10, 58, 54}, paint);

-    SkImageInfo info = SkImageInfo::Make(64, 64, kBGRA_8888_SkColorType, kPremul_SkAlphaType);

-    SkBitmap bitmap;

-    bitmap.setInfo(info);

-    bitmap.allocPixels();

-    for (int x : { 32, -32 } ) {

-        for (int y : { 32, -32 } ) {

-            surf->readPixels(bitmap, x, y);

-        } 

-    }

-    canvas->drawBitmap(bitmap, 0, 0);

+    sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64));
+    auto surfCanvas = surf->getCanvas();
+    surfCanvas->clear(SK_ColorGREEN);
+    SkPaint paint;
+    surfCanvas->drawOval({2, 10, 58, 54}, paint);
+    SkImageInfo info = SkImageInfo::Make(64, 64, kBGRA_8888_SkColorType, kPremul_SkAlphaType);
+    SkBitmap bitmap;
+    bitmap.setInfo(info);
+    bitmap.allocPixels();
+    for (int x : { 32, -32 } ) {
+        for (int y : { 32, -32 } ) {
+            surf->readPixels(bitmap, x, y);
+        } 
+    }
+    canvas->drawBitmap(bitmap, 0, 0);
 ##
 
 #SeeAlso peekPixels
@@ -1380,7 +1376,7 @@ Returns Surface_Properties for surface.
 
 #Example
     const char* names[] = { "Unknown", "RGB_H", "BGR_H", "RGB_V", "BGR_V" };
-    sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64));

+    sk_sp<SkSurface> surf(SkSurface::MakeRasterN32Premul(64, 64));
     SkDebugf("surf.props(): k%s_SkPixelGeometry\n", names[surf->props().pixelGeometry()]);
 #StdOut
 surf.props(): kRGB_H_SkPixelGeometry
@@ -1480,16 +1476,16 @@ and the client will still own the semaphores.
  ##
 #Platform !fiddle gpu
 #Height 64
-    SkPaint paint;

-    paint.setTextSize(32);

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

-    if (!context) {

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

-         return;

-    }

+    SkPaint paint;
+    paint.setTextSize(32);
+    GrContext* context = canvas->getGrContext();
+    if (!context) {
+         canvas->drawString("GPU only!", 20, 40, paint);
+         return;
+    }
     GrBackendSemaphore semaphore;
-    sk_sp<SkSurface> surface = SkSurface::MakeRenderTarget(

-            context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(64, 64));

+    sk_sp<SkSurface> surface = SkSurface::MakeRenderTarget(
+            context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(64, 64));
     surface->flushAndSignalSemaphores(1, &semaphore);
     sk_sp<SkImage> image = surface->makeImageSnapshot();
     GrBackendObject backendImage = image->getTextureHandle(false); // unused
@@ -1506,7 +1502,7 @@ and the client will still own the semaphores.
     childCanvas->clear(SK_ColorRED);
     childSurface->wait(1, &semaphore);
     childCanvas->drawImage(childImage, 32, 0);
-    childSurface->draw(canvas, 0, 0, nullptr);

+    childSurface->draw(canvas, 0, 0, nullptr);
 ##
 
 #SeeAlso flushAndSignalSemaphores GrBackendSemaphore
@@ -1531,29 +1527,29 @@ Return true if Surface supports characterization. Raster_Surface returns false.
 #Example
 #Platform gpu
 #Height 64
-    SkPaint paint;

-    paint.setTextSize(32);

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

-    if (!context) {

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

-         return;

-    }

-    sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(

-            context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(64, 64));

-    SkSurfaceCharacterization characterization;

-    if (!gpuSurface->characterize(&characterization)) {

-         canvas->drawString("characterization unsupported", 20, 40, paint);

-         return;

-    }

-    // start of threadable work 

-    SkDeferredDisplayListRecorder recorder(characterization);

-    SkCanvas* subCanvas = recorder.getCanvas();

-    subCanvas->clear(SK_ColorGREEN);

-    std::unique_ptr<SkDeferredDisplayList> displayList = recorder.detach();

-    // end of threadable work

-    gpuSurface->draw(displayList.get());

-    sk_sp<SkImage> img = gpuSurface->makeImageSnapshot();

-    canvas->drawImage(std::move(img), 0, 0);

+    SkPaint paint;
+    paint.setTextSize(32);
+    GrContext* context = canvas->getGrContext();
+    if (!context) {
+         canvas->drawString("GPU only!", 20, 40, paint);
+         return;
+    }
+    sk_sp<SkSurface> gpuSurface = SkSurface::MakeRenderTarget(
+            context, SkBudgeted::kYes, SkImageInfo::MakeN32Premul(64, 64));
+    SkSurfaceCharacterization characterization;
+    if (!gpuSurface->characterize(&characterization)) {
+         canvas->drawString("characterization unsupported", 20, 40, paint);
+         return;
+    }
+    // start of threadable work 
+    SkDeferredDisplayListRecorder recorder(characterization);
+    SkCanvas* subCanvas = recorder.getCanvas();
+    subCanvas->clear(SK_ColorGREEN);
+    std::unique_ptr<SkDeferredDisplayList> displayList = recorder.detach();
+    // end of threadable work
+    gpuSurface->draw(displayList.get());
+    sk_sp<SkImage> img = gpuSurface->makeImageSnapshot();
+    canvas->drawImage(std::move(img), 0, 0);
 ##
 
 #SeeAlso draw() SkSurfaceCharacterization SkDeferredDisplayList
@@ -1573,23 +1569,23 @@ is not compatible with Surface.
 #Example
 #Height 64
 #Platform gpu cpu
-    SkPaint paint;

-    paint.setTextSize(16);

-    sk_sp<SkSurface> gpuSurface = SkSurface::MakeRasterN32Premul(64, 64);

-    SkSurfaceCharacterization characterization;

-    if (!gpuSurface->characterize(&characterization)) {

-         canvas->drawString("characterization unsupported", 20, 40, paint);

-         return;

-    }

-    // start of threadable work 

-    SkDeferredDisplayListRecorder recorder(characterization);

-    SkCanvas* subCanvas = recorder.getCanvas();

-    subCanvas->clear(SK_ColorGREEN);

-    std::unique_ptr<SkDeferredDisplayList> displayList = recorder.detach();

-    // end of threadable work

-    gpuSurface->draw(displayList.get());

-    sk_sp<SkImage> img = gpuSurface->makeImageSnapshot();

-    canvas->drawImage(std::move(img), 0, 0);

+    SkPaint paint;
+    paint.setTextSize(16);
+    sk_sp<SkSurface> gpuSurface = SkSurface::MakeRasterN32Premul(64, 64);
+    SkSurfaceCharacterization characterization;
+    if (!gpuSurface->characterize(&characterization)) {
+         canvas->drawString("characterization unsupported", 20, 40, paint);
+         return;
+    }
+    // start of threadable work 
+    SkDeferredDisplayListRecorder recorder(characterization);
+    SkCanvas* subCanvas = recorder.getCanvas();
+    subCanvas->clear(SK_ColorGREEN);
+    std::unique_ptr<SkDeferredDisplayList> displayList = recorder.detach();
+    // end of threadable work
+    gpuSurface->draw(displayList.get());
+    sk_sp<SkImage> img = gpuSurface->makeImageSnapshot();
+    canvas->drawImage(std::move(img), 0, 0);
 ##
 
 #SeeAlso characterize() SkSurfaceCharacterization SkDeferredDisplayList
diff --git a/docs/undocumented.bmh b/docs/undocumented.bmh
index 4163b43e89..014251258f 100644
--- a/docs/undocumented.bmh
+++ b/docs/undocumented.bmh
@@ -3,11 +3,11 @@
  DirectWrite TrueType Windows Linux Android iOS __ANDROID_API__
  FreeType FreeType-based Harfbuzz   
  Descenders Kerning Unhinted 
- LCD RGB sRGB
+ LCD RGB sRGB YUV_ColorSpace
  Unicode Unicode5 UTF-8 UTF-16 UTF-32 ASCII Unichar
  API
  CPU
- GPU GPU-backed OpenGL Vulkan I/O MSAA UV_Mapping Multi_Sample_Anti_Aliasing
+ GPU GPU-backed OpenGL Vulkan I/O MSAA UV_Mapping Multi_Sample_Anti_Aliasing GPU_Share_Group
  PDF XPS
  RFC
  NaN NaNs