[canvaskit] Clean up readPixels API on Canvas and Image

This makes both APIs have the same arguments with the two
source coordinates first and all the destination params
(image info, optional buffer, optional rowBytes) after.

Bug: skia:10717
Change-Id: I483e4f33f24e226793db6113d5ba5b1955cd892e
Reviewed-on: https://skia-review.googlesource.com/c/skia/+/332622
Reviewed-by: Mike Reed <reed@google.com>

Author: kjlubick

modules/canvaskit/CHANGELOG.md

@@ -17,15 +17,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Breaking
  - `CanvasKit.MakePathFromSVGString` was renamed to `CanvasKit.Path.MakeFromSVGString`
  - `CanvasKit.MakePathFromOp` was renamed to `CanvasKit.Path.MakeFromOp`
+ - The API for `Canvas.readPixels` and `Image.readPixels` has been reworked to more accurately
+   reflect the C++ backend and each other. bytesPerRow is now a required parameter. They take an
+   ImageInfo object to specify the output format. Additionally they take an optional malloc'd
+   object as the last parameter. If provided, the data will be copied into there instead of
+   allocating a new buffer.
 
 ### Changed
  - We now compile CanvasKit with emsdk 2.0.6 when testing and deploying to npm.
  - We no longer compile with rtti on, saving about 1% in code size.
  - `CanvasKit.Shader.Blend`, `...Color`, and `...Lerp` have been renamed to
    `CanvasKit.Shader.MakeBlend`, `...MakeColor` and `...MakeLerp` to align with naming conventions.
    The old names will be removed in an upcoming release.
- - `readPixels` now takes a malloc'd object as the last parameter. If provided, the data will be 
-    copied into there instead of allocating a new buffer.
 
 ### Removed
  - `CanvasKit.MakePathFromCmds`; Was deprecated in favor of `CanvasKit.Path.MakeFromCmds`.

modules/canvaskit/canvaskit/types/canvaskit-wasm-tests.ts

@@ -138,12 +138,21 @@ function canvasTests(CK: CanvasKit, canvas?: Canvas, paint?: Paint, path?: Path,
     const matrThree = canvas.getTotalMatrix(); // $ExpectType number[]
     const surface = canvas.makeSurface(imageInfo); // $ExpectType Surface | null
     canvas.markCTM('more ctm');
-    const pixels = canvas.readPixels(0, 1, 2, 3); // $ExpectType Uint8Array
-    const pixelsTwo = canvas.readPixels(4, 5, 6, 7, CK.AlphaType.Opaque, CK.ColorType.RGBA_1010102,
-                                        CK.ColorSpace.DISPLAY_P3, 16);
-    const m = CK.Malloc(Uint8Array, 20);
-    canvas.readPixels(4, 5, 6, 7, CK.AlphaType.Opaque, CK.ColorType.RGBA_1010102,
-                                        CK.ColorSpace.DISPLAY_P3, 16, m);
+    const pixels = canvas.readPixels(85, 1000, {// $Uint8Array | Float32Array | null
+        width: 79,
+        height: 205,
+        colorType: CK.ColorType.RGBA_8888,
+        alphaType: CK.AlphaType.Unpremul,
+        colorSpace: CK.ColorSpace.SRGB,
+    });
+    const m = CK.Malloc(Uint8Array, 10);
+    img.readPixels(85, 1000, {
+        width: 79,
+        height: 205,
+        colorType: CK.ColorType.RGBA_8888,
+        alphaType: CK.AlphaType.Unpremul,
+        colorSpace: CK.ColorSpace.SRGB,
+    }, m, 4 * 85);
     canvas.restore();
     canvas.restoreToCount(2);
     canvas.rotate(1, 2, 3);
@@ -235,21 +244,21 @@ function imageTests(CK: CanvasKit, imgElement?: HTMLImageElement) {
     const h = img.height();
     const w = img.width();
     const shader = img.makeShader(CK.TileMode.Decal, CK.TileMode.Repeat); // $ExpectType Shader
-    const pixels = img.readPixels({
+    const pixels = img.readPixels(85, 1000, {// $Uint8Array | Float32Array | null
         width: 79,
         height: 205,
         colorType: CK.ColorType.RGBA_8888,
         alphaType: CK.AlphaType.Unpremul,
         colorSpace: CK.ColorSpace.SRGB,
-    }, 85, 1000);
+    });
     const m = CK.Malloc(Uint8Array, 10);
-    img.readPixels({
+    img.readPixels(85, 1000, {
         width: 79,
         height: 205,
         colorType: CK.ColorType.RGBA_8888,
         alphaType: CK.AlphaType.Unpremul,
         colorSpace: CK.ColorSpace.SRGB,
-    }, 85, 1000, m);
+    }, m, 4 * 85);
     img.delete();
 }
 

modules/canvaskit/canvaskit/types/index.d.ts

@@ -1232,22 +1232,27 @@ export interface Canvas extends EmbindObject<Canvas> {
     markCTM(marker: string): void;
 
     /**
-     * Copies the given rectangle of pixels into a new Uint8Array and returns it. If alphaType,
-     * colorType, and colorSpace are provided, those will describe the output format.
-     * @param x
-     * @param y
-     * @param w
-     * @param h
-     * @param alphaType - defaults to Unpremul
-     * @param colorType - defaults to RGBA_8888
-     * @param colorSpace - defaults to SRGB
-     * @param dest - If provided, the pixels will be copied into the allocated buffer allowing access to the
-     *               pixels without allocating a new TypedArray.
-     * @param dstRowBytes
+     * Returns a TypedArray containing the pixels reading starting at (srcX, srcY) and does not
+     * exceed the size indicated by imageInfo. See SkCanvas.h for more on the caveats.
+     *
+     * If dest is not provided, we allocate memory equal to the provided height * the provided
+     * bytesPerRow to fill the data with.
+     *
+     * This is generally a very expensive call for the GPU backend.
+     *
+     * @param srcX
+     * @param srcY
+     * @param imageInfo - describes the destination format of the pixels.
+     * @param dest - If provided, the pixels will be copied into the allocated buffer allowing
+     *        access to the pixels without allocating a new TypedArray.
+     * @param bytesPerRow - number of bytes per row. Must be provided if dest is set. This
+     *        depends on destination ColorType. For example, it must be at least 4 * width for
+     *        the 8888 color type.
+     * @returns a TypedArray appropriate for the specified ColorType. Note that 16 bit floats are
+     *          not supported in JS, so that colorType corresponds to raw bytes Uint8Array.
      */
-    readPixels(x: number, y: number, w: number, h: number, alphaType?: AlphaType,
-               colorType?: ColorType, colorSpace?: ColorSpace, dstRowBytes?: number,
-               dest?: MallocObj): Uint8Array;
+    readPixels(srcX: number, srcY: number, imageInfo: ImageInfo, dest?: MallocObj,
+               bytesPerRow?: number): Uint8Array | Float32Array | null;
 
     /**
      * Removes changes to the current matrix and clip since Canvas state was
@@ -1564,18 +1569,24 @@ export interface Image extends EmbindObject<Image> {
 
     /**
      * Returns a TypedArray containing the pixels reading starting at (srcX, srcY) and does not
-     * exceed the size indicated by imageInfo. See Image.h for more on the caveats.
+     * exceed the size indicated by imageInfo. See SkImage.h for more on the caveats.
+     *
+     * If dest is not provided, we allocate memory equal to the provided height * the provided
+     * bytesPerRow to fill the data with.
      *
-     * @param imageInfo - describes the destination format of the pixels.
      * @param srcX
      * @param srcY
-     * @param dest - If provided, the pixels will be copied into the allocated buffer allowing access to the
-     *               pixels without allocating a new TypedArray.
-     * @returns a Uint8Array if RGB_8888 was requested, Float32Array if RGBA_F32 was requested. null will be returned
-     *          on any error.
-     *
-     */
-    readPixels(imageInfo: ImageInfo, srcX: number, srcY: number, dest?: MallocObj): Uint8Array | Float32Array | null;
+     * @param imageInfo - describes the destination format of the pixels.
+     * @param dest - If provided, the pixels will be copied into the allocated buffer allowing
+     *        access to the pixels without allocating a new TypedArray.
+     * @param bytesPerRow - number of bytes per row. Must be provided if dest is set. This
+     *        depends on destination ColorType. For example, it must be at least 4 * width for
+     *        the 8888 color type.
+     * @returns a TypedArray appropriate for the specified ColorType. Note that 16 bit floats are
+     *          not supported in JS, so that colorType corresponds to raw bytes Uint8Array.
+     */
+    readPixels(srcX: number, srcY: number, imageInfo: ImageInfo, dest?: MallocObj,
+               bytesPerRow?: number): Uint8Array | Float32Array | null;
 
     /**
      * Return the width in pixels of the image.