Add drawOnce() API to SkSurface.

The existing |SkSurface.requestAnimationFrame| API provides a convenient way of
drawing Skia animations using the same idiom as the well known
|Window.requestAnimationFrame|.  It gracefully handles providing the caller with
access to the right canvas, as well as flushing after the user-supplied
callback.

The new |SkSurface.drawOnce| API added in this change provides the same
conveniences around access to the right canvas and flushing, but for the
use-case where the user wishes to draw a single frame only.  Importantly, this
new API disposes of the SkSurface upon completion, i.e. frees the memory
associated with the underlying pixel storage an surface.  This avoids memory
leaks that occur when |SkSurface.requestAnimationFrame| is used for single-frame
purposes.

Bug: NONE
Change-Id: Ic4e48e65dffc4809513ceaf72260ac0432b98952
Reviewed-on: https://skia-review.googlesource.com/c/skia/+/265604
Reviewed-by: Kevin Lubick <kjlubick@google.com>

Author: Bryce Thomas

modules/canvaskit/canvaskit/example.html

@@ -231,9 +231,9 @@ <h2> CanvasKit can allow for text shaping (e.g. breaking, kerning)</h2>
       path.delete();
       rrect.delete();
       paint.delete();
-      // Intentionally just draw frame once
     }
-    surface.requestAnimationFrame(drawFrame);
+    // Intentionally just draw frame once
+    surface.drawOnce(drawFrame);
   }
 
   function preventScrolling(canvas) {

modules/canvaskit/canvaskit/extra.html

@@ -419,8 +419,8 @@ <h2> CanvasKit can serialize/deserialize .skp files</h2>
     function drawFrame(canvas) {
       canvas.clear(CanvasKit.TRANSPARENT);
       canvas.drawPicture(pic);
-      // Intentionally just draw frame once
     }
-    surface.requestAnimationFrame(drawFrame);
+    // Intentionally just draw frame once
+    surface.drawOnce(drawFrame);
   }
 </script>

modules/canvaskit/externs.js

@@ -776,6 +776,7 @@ CanvasKit.SkPicture.prototype.saveAsFile = function() {};
 CanvasKit.SkSurface.prototype.dispose = function() {};
 CanvasKit.SkSurface.prototype.flush = function() {};
 CanvasKit.SkSurface.prototype.requestAnimationFrame = function() {};
+CanvasKit.SkSurface.prototype.drawOnce = function() {};
 CanvasKit.SkSurface.prototype.captureFrameAsSkPicture = function() {};
 
 /** @return {CanvasKit.SkVertices} */

modules/canvaskit/interface.js

@@ -755,10 +755,28 @@ CanvasKit.onRuntimeInitialized = function() {
 
       callback(this._cached_canvas);
 
+      // We do not dispose() of the SkSurface here, as the client will typically
+      // call requestAnimationFrame again from within the supplied callback.
+      // For drawing a single frame, prefer drawOnce().
       this.flush();
     }.bind(this));
   }
 
+  CanvasKit.SkSurface.prototype.drawOnce = function(callback, dirtyRect) {
+    if (!this._cached_canvas) {
+      this._cached_canvas = this.getCanvas();
+    }
+    window.requestAnimationFrame(function() {
+      if (this._context !== undefined) {
+        CanvasKit.setCurrentContext(this._context);
+      }
+      callback(this._cached_canvas);
+
+      this.flush();
+      this.dispose();
+    }.bind(this));
+  }
+
   // Run through the JS files that are added at compile time.
   if (CanvasKit._extraInitializations) {
     CanvasKit._extraInitializations.forEach(function(init) {

modules/canvaskit/tests/core.spec.js

@@ -369,6 +369,36 @@ describe('Core canvas behavior', function() {
         });
     });
 
+    it('can draw once using drawOnce utility method', function(done) {
+        LoadCanvasKit.then(catchException(done, () => {
+            const surface = CanvasKit.MakeCanvasSurface('test');
+            expect(surface).toBeTruthy('Could not make surface');
+            if (!surface) {
+                done();
+                return;
+            }
+
+            function drawFrame(canvas) {
+                const paint = new CanvasKit.SkPaint();
+                paint.setStrokeWidth(1.0);
+                paint.setAntiAlias(true);
+                paint.setColor(CanvasKit.Color(0, 0, 0, 1.0));
+                paint.setStyle(CanvasKit.PaintStyle.Stroke);
+                const path = new CanvasKit.SkPath();
+                path.moveTo(20, 5);
+                path.lineTo(30, 20);
+                path.lineTo(40, 10);
+                canvas.drawPath(path, paint);
+
+                path.delete();
+                paint.delete();
+            }
+            surface.drawOnce(drawFrame);
+
+            reportSurface(surface, 'drawOnce', done);
+        }));
+    });
+
     it('can use DecodeCache APIs', function(done) {
         LoadCanvasKit.then(catchException(done, () => {
             const initialLimit = CanvasKit.getDecodeCacheLimitBytes();