Impl

lib/ui/window.dart

@@ -327,14 +327,21 @@ class FlutterView {
 
   /// Updates the view's rendering on the GPU with the newly provided [Scene].
   ///
-  /// This function must be called within the scope of the
+  /// ## Requirement for calling this method
+  ///
+  /// This method must be called within the synchronous scope of the
   /// [PlatformDispatcher.onBeginFrame] or [PlatformDispatcher.onDrawFrame]
-  /// callbacks being invoked.
+  /// callbacks. Calls out of this scope will be ignored. To use this method,
+  /// create a callback that calls this method instead, and assign it to either
+  /// of the fields above; then schedule a frame, which is done typically with
+  /// [PlatformDispatcher.scheduleFrame]. Also, make sure the callback does not
+  /// have `await` before the `FlutterWindow.render` call.
+  ///
+  /// Additionally, this method can only be called once for each view during a
+  /// single [PlatformDispatcher.onBeginFrame]/[PlatformDispatcher.onDrawFrame]
+  /// callback sequence. Duplicate calls will be ignored in production.
   ///
-  /// If this function is called a second time during a single
-  /// [PlatformDispatcher.onBeginFrame]/[PlatformDispatcher.onDrawFrame]
-  /// callback sequence or called outside the scope of those callbacks, the call
-  /// will be ignored.
+  /// ## How to record a scene
   ///
   /// To record graphical operations, first create a [PictureRecorder], then
   /// construct a [Canvas], passing that [PictureRecorder] to its constructor.

lib/ui/window/platform_configuration_unittests.cc

@@ -505,9 +505,9 @@ TEST_F(PlatformConfigurationTest, OutOfScopeRenderCallsAreIgnored) {
   // Render should not be called.
   EXPECT_CALL(client, Render).Times(0);
 
-  auto message_latch = std::make_shared<fml::AutoResetWaitableEvent>();
-  auto finish = [message_latch](Dart_NativeArguments args) {
-    message_latch->Signal();
+  auto finish_latch = std::make_shared<fml::AutoResetWaitableEvent>();
+  auto finish = [finish_latch](Dart_NativeArguments args) {
+    finish_latch->Signal();
   };
   AddNativeCallback("Finish", CREATE_NATIVE_ENTRY(finish));
 
@@ -526,7 +526,7 @@ TEST_F(PlatformConfigurationTest, OutOfScopeRenderCallsAreIgnored) {
       });
 
   // Wait for the Dart main function to end.
-  message_latch->Wait();
+  finish_latch->Wait();
 }
 
 TEST_F(PlatformConfigurationTest, DuplicateRenderCallsAreIgnored) {
@@ -541,9 +541,9 @@ TEST_F(PlatformConfigurationTest, DuplicateRenderCallsAreIgnored) {
   // Render should only be called once, because the second call is ignored.
   EXPECT_CALL(client, Render).Times(1);
 
-  auto message_latch = std::make_shared<fml::AutoResetWaitableEvent>();
-  auto finish = [message_latch](Dart_NativeArguments args) {
-    message_latch->Signal();
+  auto finish_latch = std::make_shared<fml::AutoResetWaitableEvent>();
+  auto finish = [finish_latch](Dart_NativeArguments args) {
+    finish_latch->Signal();
   };
   AddNativeCallback("Finish", CREATE_NATIVE_ENTRY(finish));
 
@@ -562,12 +562,12 @@ TEST_F(PlatformConfigurationTest, DuplicateRenderCallsAreIgnored) {
       });
 
   // Wait for the Dart main function to end.
-  message_latch->Wait();
+  finish_latch->Wait();
 
+  // This call synchronously calls PlatformDispatcher's handleBeginFrame and
+  // handleDrawFrame. Therefore it doesn't have to wait for latches.
   runtime_controller_context->ControllerTaskSync(
       [](RuntimeController& runtime_controller) {
-        // This BeginFrame calls PlatformDispatcher's handleBeginFrame and
-        // handleDrawFrame synchronously. Therefore don't wait after it.
         runtime_controller.BeginFrame(fml::TimePoint::Now(), 0);
       });
 }

testing/dart/platform_view_test.dart

@@ -10,10 +10,13 @@ void main() {
   test('PlatformView layers do not emit errors from tester', () async {
     final SceneBuilder builder = SceneBuilder();
     builder.addPlatformView(1);
-    final Scene scene = builder.build();
 
-    PlatformDispatcher.instance.implicitView!.render(scene);
-    scene.dispose();
+    PlatformDispatcher.instance.onBeginFrame = (Duration duration) {
+      final Scene scene = builder.build();
+      PlatformDispatcher.instance.implicitView!.render(scene);
+      scene.dispose();
+    };
+    PlatformDispatcher.instance.scheduleFrame();
     // Test harness asserts that this does not emit an error from the shell logs.
   });
 }