[Flutter GPU] Add surface API for framework presentation by bdero · Pull Request #187358 · flutter/flutter

bdero · 2026-05-31T07:43:55Z

Adds a Flutter GPU surface API for rendering into a presentable color texture and drawing the latest presented image through Flutter. The surface owns the backing texture pool, tracks acquired frames, keeps the current image out of reuse, and waits for producer command buffer completion before a presented texture can be reused.

The API is shaped as a small family so later destinations (a Flutter canvas, and eventually the window swapchain) can share one per-frame contract. GpuSurface and GpuSurfaceFrame are the destination-agnostic base types. This PR ships the first concrete destination, GpuImageSurface, which Flutter draws as a ui.Image.

Two parts of the contract are uniform across all future destinations, even though the image destination never exercises them. acquireNextFrame is nullable, because a window swapchain can skip a frame. present returns a GpuPresentStatus, because a window swapchain can report that it needs reconfiguring. For an image surface, acquire always returns a frame and present always reports success, and the published image is read from GpuImageSurface.currentImage.

The API keeps depth, stencil, MSAA, and intermediate attachments renderer-owned. GpuSurfaceFrame.colorTexture is only the final color target handed back to Flutter as a ui.Image.

A minimal example.

final surface = gpu.gpuContext.createImageSurface(width, height);
final frame = surface.acquireNextFrame();

final commandBuffer = gpu.gpuContext.createCommandBuffer();
commandBuffer.createRenderPass(
  gpu.RenderTarget.singleColor(
    gpu.ColorAttachment(texture: frame.colorTexture),
  ),
);

// Bind a pipeline, bind resources, and draw.

frame.present(commandBuffer);
commandBuffer.submit();
canvas.drawImageRect(surface.currentImage!, src, dst, paint);

Depth and stencil remain normal renderer-owned attachments.

final frame = surface.acquireNextFrame();
final depthStencil = gpu.gpuContext.createTexture(
  gpu.StorageMode.deviceTransient,
  width,
  height,
  format: gpu.gpuContext.defaultDepthStencilFormat,
  enableRenderTargetUsage: true,
  enableShaderReadUsage: false,
);

final commandBuffer = gpu.gpuContext.createCommandBuffer();
commandBuffer.createRenderPass(
  gpu.RenderTarget.singleColor(
    gpu.ColorAttachment(texture: frame.colorTexture),
    depthStencilAttachment: gpu.DepthStencilAttachment(texture: depthStencil),
  ),
);

Tests cover surface acquisition, presentation, current image behavior, discard, resize, and rendering a clear color into a surface.

Pre-launch Checklist

gemini-code-assist

Code Review

This pull request introduces GpuSurface and SurfaceFrame to the Flutter GPU library, allowing applications to manage a pool of presentable render targets. It also adds completion callback support to CommandBuffer and includes comprehensive unit tests. The review feedback suggests invalidating the colorTexture when a frame is presented or discarded to prevent accidental post-lease usage, and pruning inactive, old-sized texture records during a surface resize to avoid a potential GPU memory leak.

gaaclarke · 2026-06-01T22:58:01Z

final image = frame.present(commandBuffer);
commandBuffer.submit();

Is there a reason that present() does not imply submit()?

gaaclarke · 2026-06-01T23:03:08Z

+    _checkDimensions(width, height);
+    final String? error = _resize(width, height);
+    if (error != null) {
+      throw Exception(error);


This should be an Error, no?

Done in 7ec7a99, this now throws StateError.

gaaclarke · 2026-06-01T23:06:11Z

+/// [SurfaceFrame.colorTexture], call [SurfaceFrame.present] with the command
+/// buffer that contains the final writes, submit that command buffer, and draw
+/// [currentImage].
+base class GpuSurface extends NativeFieldWrapperClass1 {


Don't you want final for this?

Done in 7ec7a99.

gaaclarke · 2026-06-01T23:06:27Z

+/// [present] to publish the frame as the surface's current image. If the frame
+/// will not be presented, call [discard] so the surface can reuse its backing
+/// texture.
+base class SurfaceFrame {


Done in 7ec7a99.

gaaclarke · 2026-06-01T23:07:08Z

+  /// for future frames.
+  ///
+  /// The returned [ui.Image] is also available from [GpuSurface.currentImage].
+  ui.Image present(CommandBuffer commandBuffer) {


should this submit the command buffer? (mentioned in comment on issue)

I kept submit explicit so one command buffer can produce multiple presented surface frames, for example rendering two GpuSurfaces and then submitting their shared command buffer once.

gaaclarke · 2026-06-01T23:10:08Z


 bool CommandBuffer::Submit(
    const impeller::CommandBuffer::CompletionCallback& completion_callback) {
+  if (submitted_) {


I'd suggest adding a unit test for these c++ level changes.

Done in 7ec7a99.

gaaclarke · 2026-06-01T23:11:41Z

+std::shared_ptr<Surface::TextureRecord> Surface::CreateTextureRecord() const {
+#if !IMPELLER_SUPPORTS_RENDERING
+  FML_LOG(ERROR) << "Flutter GPU surfaces require Impeller rendering support.";
+  return nullptr;


why do we even compile this without impeller?

Agreed, and I filed #187424 to track splitting the Flutter GPU build so most implementation code is compiled only when Impeller rendering is available.

gaaclarke · 2026-06-01T23:17:16Z

+    resizedFrame.discard();
+  }, skip: !(impellerEnabled && flutterGpuEnabled));
+
+  test('Can render clear color into GpuSurface', () async {


seems like a golden test would be good for this as well?

Done in 7ec7a99, the existing surface golden test was renamed to make that coverage explicit.

This reverts commit 8e36788.

bdero · 2026-06-12T02:49:09Z

Resolved new conflicts

auto-submit · 2026-06-12T17:55:25Z

auto label is removed for flutter/flutter/187358, Failed to enqueue flutter/flutter/187358 with HTTP 400: Pull request Required status check "Check Code Freeze" is expected..

bdero · 2026-06-12T18:47:03Z

Any idea why this is happening? Is the action broken? 🤔

flutter-dashboard Bot added the CICD Run CI/CD label May 31, 2026

github-actions Bot added engine flutter/engine related. See also e: labels. flutter-gpu team-fluttergpu Owned by Flutter GPU team labels May 31, 2026

github-project-automation Bot added this to Flutter GPU May 31, 2026

github-project-automation Bot moved this to 🤔 Needs Triage in Flutter GPU May 31, 2026

bdero changed the title ~~[flutter_gpu] Add surface API for framework presentation~~ [Flutter GPU] Add surface API for framework presentation May 31, 2026

bdero force-pushed the bdero/flutter-gpu-surface branch from 81855ad to b9288a4 Compare May 31, 2026 08:43

github-actions Bot removed the CICD Run CI/CD label May 31, 2026

bdero force-pushed the bdero/flutter-gpu-surface branch from b9288a4 to 47f537c Compare May 31, 2026 08:48

flutter-dashboard Bot added the CICD Run CI/CD label May 31, 2026

bdero marked this pull request as ready for review May 31, 2026 08:52

gemini-code-assist Bot reviewed May 31, 2026

View reviewed changes

Comment thread engine/src/flutter/lib/gpu/lib/src/surface.dart Outdated

Comment thread engine/src/flutter/lib/gpu/lib/src/surface.dart

Comment thread engine/src/flutter/lib/gpu/surface.cc

bdero force-pushed the bdero/flutter-gpu-surface branch from 47f537c to 1a9cf59 Compare May 31, 2026 11:13

github-actions Bot removed the CICD Run CI/CD label May 31, 2026

bdero added the CICD Run CI/CD label May 31, 2026

Add Flutter GPU surface API

41527d3

bdero force-pushed the bdero/flutter-gpu-surface branch from 1a9cf59 to 41527d3 Compare June 1, 2026 07:16

github-actions Bot removed the CICD Run CI/CD label Jun 1, 2026

bdero added the CICD Run CI/CD label Jun 1, 2026

bdero requested a review from gaaclarke June 1, 2026 11:03

bdero moved this from 🤔 Needs Triage to ⚙️ In Progress in Flutter GPU Jun 1, 2026

gaaclarke reviewed Jun 1, 2026

View reviewed changes

Address Flutter GPU surface review comments

7ec7a99

github-actions Bot removed the CICD Run CI/CD label Jun 2, 2026

Compile GPU surface only with Impeller rendering

8e36788

flutter-dashboard Bot added the CICD Run CI/CD label Jun 2, 2026

Revert "Compile GPU surface only with Impeller rendering"

93e2999

This reverts commit 8e36788.

github-actions Bot removed the CICD Run CI/CD label Jun 2, 2026

gaaclarke previously approved these changes Jun 11, 2026

View reviewed changes

Merge branch 'master' into bdero/flutter-gpu-surface

feca459

bdero dismissed gaaclarke’s stale review via feca459 June 12, 2026 01:54

Merge branch 'master' into bdero/flutter-gpu-surface

e7a20b8

bdero added CICD Run CI/CD and removed CICD Run CI/CD labels Jun 12, 2026

bdero requested a review from gaaclarke June 12, 2026 02:48

gaaclarke approved these changes Jun 12, 2026

View reviewed changes

bdero added the autosubmit Merge PR when tree becomes green via auto submit App label Jun 12, 2026

auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jun 12, 2026

Merge branch 'master' into bdero/flutter-gpu-surface

4caeea8

github-actions Bot removed the CICD Run CI/CD label Jun 12, 2026

bdero added CICD Run CI/CD autosubmit Merge PR when tree becomes green via auto submit App labels Jun 12, 2026

auto-submit Bot added this pull request to the merge queue Jun 12, 2026

Merged via the queue into flutter:master with commit cc6d732 Jun 13, 2026
205 of 206 checks passed

bdero mentioned this pull request Jun 19, 2026

[Flutter GPU] Add a Surface utility for drawing to the Flutter canvas. #142733

Closed

Uh oh!

Conversation

bdero commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gaaclarke commented Jun 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bdero commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

auto-submit Bot commented Jun 12, 2026

Uh oh!

bdero commented Jun 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bdero commented May 31, 2026 •

edited

Loading

bdero commented Jun 12, 2026 •

edited

Loading