Add function restoreToCount to Canvas.

lib/ui/dart_ui.cc

@@ -148,6 +148,7 @@ typedef CanvasPath Path;
   V(Canvas, getSaveCount, 1)                           \
   V(Canvas, getTransform, 2)                           \
   V(Canvas, restore, 1)                                \
+  V(Canvas, restoreToCount, 2)                         \
   V(Canvas, rotate, 2)                                 \
   V(Canvas, save, 1)                                   \
   V(Canvas, saveLayer, 7)                              \

lib/ui/painting.dart

@@ -4691,6 +4691,16 @@ class Canvas extends NativeFieldWrapperClass1 {
   @FfiNative<Void Function(Pointer<Void>)>('Canvas::restore', isLeaf: true)
   external void restore();
 
+  /// Pops the save stack until the count layer, if there is anything to pop.
+  /// Otherwise, does nothing.
+  ///
+  /// Use [save] and [saveLayer] to push state onto the stack.
+  ///
+  /// If the state was pushed with [saveLayer], then this call will also
+  /// cause the new layer to be composited into the previous layer.
+  @FfiNative<Void Function(Pointer<Void>, Int32)>('Canvas::restoreToCount', isLeaf: true)
+  external void restoreToCount(int count);
+
   /// Returns the number of items on the save stack, including the
   /// initial state. This means it returns 1 for a clean canvas, and
   /// that each call to [save] and [saveLayer] increments it, and that

lib/ui/painting/canvas.cc

@@ -117,6 +117,12 @@ int Canvas::getSaveCount() {
   }
 }
 
+void Canvas::restoreToCount(int count) {
+  if (display_list_recorder_) {
+    builder()->restoreToCount(count);
+  }
+}
+
 void Canvas::translate(double dx, double dy) {
   if (display_list_recorder_) {
     builder()->translate(dx, dy);

lib/ui/painting/canvas.h

@@ -48,6 +48,7 @@ class Canvas : public RefCountedDartWrappable<Canvas>, DisplayListOpFlags {
 
   void restore();
   int getSaveCount();
+  void restoreToCount(int count);
 
   void translate(double dx, double dy);
   void scale(double sx, double sy);

lib/web_ui/lib/canvas.dart

@@ -66,6 +66,7 @@ abstract class Canvas {
   void saveLayer(Rect? bounds, Paint paint);
   void restore();
   int getSaveCount();
+  void restoreToCount(int count);
   void translate(double dx, double dy);
   void scale(double sx, [double? sy]);
   void rotate(double radians);

lib/web_ui/lib/src/engine/canvaskit/canvaskit_canvas.dart

@@ -65,6 +65,11 @@ class CanvasKitCanvas implements ui.Canvas {
     _canvas.restore();
   }
 
+  @override
+  void restoreToCount(int count) {
+    _canvas.restoreToCount(count);
+  }
+
   @override
   int getSaveCount() {
     return _canvas.saveCount!;

lib/web_ui/lib/src/engine/html/canvas.dart

@@ -58,6 +58,11 @@ class SurfaceCanvas implements ui.Canvas {
     _canvas.restore();
   }
 
+  @override
+  void restoreToCount(int count) {
+    _canvas.restoreToCount(count);
+  }
+
   @override
   int getSaveCount() => _canvas.saveCount;
 

lib/web_ui/lib/src/engine/html/recording_canvas.dart

@@ -244,6 +244,12 @@ class RecordingCanvas {
     _saveCount--;
   }
 
+  void restoreToCount(int count) {
+    while (count < _saveCount) {
+      restore();
+    }
+  }
+
   void translate(double dx, double dy) {
     assert(!_recordingEnded);
     _paintBounds.translate(dx, dy);

lib/web_ui/test/engine/canvas_test.dart

@@ -276,5 +276,20 @@ void runCanvasTests({required bool deviceClipRoundsOut}) {
       expect(canvas.getLocalClipBounds(), initialLocalBounds);
       expect(canvas.getDestinationClipBounds(), initialDestinationBounds);
     });
+
+    test('RestoreToCount can work', () async {
+      final ui.PictureRecorder recorder = ui.PictureRecorder();
+      final ui.Canvas canvas = ui.Canvas(recorder);
+      canvas.save();
+      canvas.save();
+      canvas.save();
+      canvas.save();
+      canvas.save();
+      expect(canvas.getSaveCount(), 6);
+      canvas.restoreToCount(2);
+      expect(canvas.getSaveCount(), 2);
+      canvas.restore();
+      expect(canvas.getSaveCount(), 1);
+    });
   });
 }

testing/dart/canvas_test.dart

@@ -929,6 +929,21 @@ void main() {
     expect(canvas.getLocalClipBounds(), initialLocalBounds);
     expect(canvas.getDestinationClipBounds(), initialDestinationBounds);
   });
+
+  test('RestoreToCount can work', () async {
+    final PictureRecorder recorder = PictureRecorder();
+    final Canvas canvas = Canvas(recorder);
+    canvas.save();
+    canvas.save();
+    canvas.save();
+    canvas.save();
+    canvas.save();
+    expect(canvas.getSaveCount(), equals(6));
+    canvas.restoreToCount(2);
+    expect(canvas.getSaveCount(), equals(2));
+    canvas.restore();
+    expect(canvas.getSaveCount(), equals(1));
+  });
 }
 
 Matcher listEquals(ByteData expected) => (dynamic v) {