Skip to content

[Flutter GPU] ☂️ Compute shaders #188474

Open
4 of 5 issues completed
Open

Description

@bdero

Goal

A Flutter GPU user can write a compute shader, dispatch it over a 1D, 2D, or 3D workgroup grid, read and write storage buffers and storage textures from it, feed its output to a render pass or read it back on the CPU, and detect at runtime whether the device supports any of this. Runs on Metal and Vulkan first, then OpenGL ES 3.1. Where compute is unavailable the app checks supportsCompute and takes its own non-compute path.

This is a tracker for the whole roadmap, linking the work items that have to land together for compute to be usable end to end from Dart. Supersedes the earlier stub #161098.

Where things stand

Audited against main at 53d381d (2026-10-03).

Already in place

Gaps

  1. Not reachable from Dart. The bundle does not serialize workgroup size or storage buffers. lib/gpu has no compute pass and no storage slot, and it registers no storage-buffer descriptor layouts, so a Vulkan compute pipeline built from a bundle would have a malformed layout.
  2. No readback. DeviceBuffer has no read API, the HAL has no buffer-to-buffer copy, lib/gpu never sets the descriptor's readback flag, and on Intel Macs host-visible buffers are Managed with no synchronizeResource, so GPU writes are not guaranteed visible to the CPU.
  3. Synchronization. The Metal compute encoder is created with MTLDispatchTypeConcurrent, so dependent dispatches in one pass race without explicit barriers. Metal resources are tracked, so hazards across encoders are already handled. On Vulkan the only automatic barrier is at the end of a compute pass, and it targets vertex and index input only. Fragment, uniform, sampled-texture, transfer, host and indirect consumers are not covered, and neither are render to compute or blit to compute.
  4. Pass lifetime. lib/gpu creates the HAL pass when the Dart pass is created and ends it at submit. Metal allows one active encoder per command buffer and Vulkan does not allow a dispatch inside a render pass, so a compute pass cannot be open at the same time as another pass. The same limit already applies to render passes: on Metal a command buffer can hold only one.
  5. Gating. CapabilitiesVK::SupportsCompute() returns true unconditionally, before any of the above works through lib/gpu. GLES returns false, with a comment saying compute is unsupported "until GLES 3.2", which is wrong (compute is core in GLES 3.1).
  6. Workgroup size. Vulkan overrides constant_id = 0 with maxComputeWorkGroupSize[0] on every compute pipeline, which silently clobbers any user specialization constant 0. A size of 0 in a dimension (the spec-constant sentinel) resolves to different sizes on Metal and Vulkan. Vulkan validates no limits, and Dart can see none.
  7. Storage textures. There is no storage-image descriptor type, no reflection of image access, no binder overload without a sampler, no descriptor-pool entry, no layout transitions, and no format capability query (supportsTextureFormat(shaderWrite:) returns true for every uncompressed format).
  8. Storage in render stages. A vertex or fragment shader that uses a storage buffer still compiles at the bundle-wide GLES version, which defaults to 100, and impellerc aborts inside SPIRV-Cross without naming the shader.
  9. Hot reload. Re-registering a dirty compute shader calls RemovePipelinesWithEntryPoint, which dereferences the null compute entry point of every render pipeline. Compute pipelines are never evicted.
  10. GLES. There is no compute infrastructure: no compute-only program link, none of glDispatchCompute, glMemoryBarrier, glBindBufferBase, glMapBufferRange or glBindImageTexture in the proc table, buffers are CPU shadow copies that go stale after GPU writes, textures are allocated mutable, and the submit callback fires when the reactor drains rather than when the GPU finishes.

Platform reach

Platform Backend Flutter ships Compute
iOS, macOS Metal Wave 1
Android, Vulkan devices Vulkan Wave 1
Android, GLES fallback devices (Adreno 650 and older, Huawei Maleoon, early Samsung Xclipse, older PowerVR) OpenGL ES 3.x Wave 3
Linux EGL, OpenGL ES Wave 3, once the embedder requests an ES 3.1 context
Custom embedders on desktop GL 4.3 OpenGL Wave 3, if the runtime learns to load the opengl_desktop variant
Windows ANGLE on D3D11, ES 3.0 context Not planned. Needs ANGLE on Vulkan or a native backend
Web none, Flutter GPU is dart:ffi Not planned

An earlier version of this plan targeted desktop GL 4.3 for Windows and Linux and deprioritized mobile GLES 3.1 as redundant with Vulkan. Neither holds: no in-tree embedder creates a desktop GL context, Flutter GPU only ever loads the opengl_es variant, and Android deliberately falls back to GLES on a large population of ES 3.1-capable devices. ES 3.1 is the GL tier that matters, and desktop GL comes almost for free with it.

How other systems approach this

System Dispatch units Access declaration Sync model GL / GLES compute
WebGPU / wgpu workgroup counts per-binding read / read_write automatic (usage scopes) gated at GLES 3.1, none on WebGL2, one artifact plus capability flags
SDL_GPU workgroup counts writable set at pass begin automatic at pass boundary no GL backend at all
sokol_gfx workgroup counts reflected from shader readonly automatic (bounded per-pass tracker) GL 4.3 / GLES 3.1, none on WebGL2
bgfx workgroup counts access enum at bind time manual via view ordering GL 4.3 / GLES 3.1
Unity workgroup counts HLSL type plus RenderGraph access flags automatic in RenderGraph gated by supportsComputeShaders, none on WebGL
Godot RenderingDevice workgroup counts uniform sets explicit barriers GL renderer has no compute
Impeller today workgroup counts (#188601) none explicit within a pass; Vulkan pass-exit barrier to vertex input only disabled

Workgroup-count dispatch is universal. The friendlier APIs declare resource access and insert barriers automatically. The GLES compute floor is GLES 3.1 / desktop GL 4.3 everywhere, WebGL2 has no compute anywhere, and the missing-capability fallback is always the app author's responsibility, never synthesized by the engine.

Contract

These are the guarantees the Dart API makes. They are settled in this issue before more implementation lands, because Wave 1 freezes them for every later backend.

  • Dispatch. ComputePass.dispatch(x, y, z) takes workgroup counts. The workgroup size is the shader's literal local_size, reflected and recorded in the bundle. impellerc rejects local_size_*_id, and the Vulkan override of constant_id = 0 is removed. A zero count is a no-op, matching a draw with zero vertices. A workgroup size above a device limit is an error at pipeline creation, on every backend.
  • Limits. gpuContext exposes max workgroup invocations, max workgroup size, max workgroup count, max shared memory and the minimum storage-buffer offset alignment. The docs state the portable floor: 128 invocations, 128 x 128 x 64 size, 16 KB shared memory.
  • Binding. Storage buffers bind by slot on the pass, like uniforms: Shader.getStorageBufferSlot(name) and ComputePass.bindStorageBuffer(slot, view), and through binding sets ([Flutter GPU] Reusable binding sets #190400). Uniform buffers and sampled textures bind in compute passes the same way they do in render passes. Bindings persist across dispatches within a pass on every backend.
  • Access. Declared in the shader, through readonly on storage blocks and the access qualifier on storage images. It is reflected into the bundle per binding and drives barriers.
  • Pass lifecycle. A command buffer records one pass at a time, and passes execute in the order they are created. Creating the next pass, or recording a copy or readback on the command buffer, ends the current pass, and submit() ends the last one. end() ends a pass explicitly and is harmless to call twice. Any call on an ended pass throws a StateError naming what ended it. This applies to render passes as well, so one command buffer can hold several render passes on every backend. Other APIs avoid a manual end() through deterministic scope (Rust Drop in wgpu, C# using in Unity), which Dart does not have; ending on the next command keeps that convenience without reordering anything, since execution follows creation order and any late use of a pass throws.
  • Synchronization. Within a command buffer and across command buffers on the queue, a write by an earlier dispatch or pass is visible to every later dispatch, draw, blit and readback without user action. Impeller implements this with a serial Metal compute encoder (or barriers driven by the write set), Vulkan barriers at compute pass exit covering every consumer and render and blit pass exits that include the compute stage, and glMemoryBarrier(GL_ALL_BARRIER_BITS) on GL. A pass can opt out of automatic tracking and use the explicit AddBufferMemoryBarrier and AddTextureMemoryBarrier.
  • Readback. CommandBuffer.readBuffer(view) and CommandBuffer.readTexture(texture, {region, mipLevel, slice}) return Future<ByteData>. A read is recorded as a command, so it sees exactly the writes recorded before it. The Future completes on the isolate when that command buffer finishes on the GPU, including when the app renders no further frames, and completes with an error if the submit fails, the device is lost, or the command buffer is discarded without being submitted. The bytes are owned by Dart and tightly packed. Staging buffers, row alignment, Vulkan host barriers and invalidation, and synchronizeResource on Managed storage are internal. There is no synchronous read and no mapping API.
  • Gating. gpuContext.supportsCompute is true only where this whole contract is implemented, independent of the HAL's SupportsCompute(). When it is false, createComputePass throws. A shader name the library does not contain returns null as today; a shader the library contains but the device cannot run throws, naming the shader, the tier it needs and the tier the device has.
  • GL tiering. Each shader compiles to the lowest GLES version that supports the features it uses. Compute shaders already compile to 310 es; vertex and fragment shaders that use storage buffers or images do too; everything else is unchanged. impellerc detects storage use before invoking SPIRV-Cross so a failure names the shader. The bundle records each shader's minimum tier and its per-stage storage use, and the runtime checks per-stage limits, because GLES 3.1 allows zero storage blocks in vertex and fragment shaders. There is no per-shader multi-variant packaging.
  • Bundle format. Workgroup size, storage-buffer descriptors with access, and the minimum GLES tier are added and the format version is bumped, in coordination with the push-constant bump in [Flutter GPU] Push constants for small per-draw uniform data #190406 so the format changes once.
  • Hot reload. Compute shaders hot reload like render shaders.

Work items

Wave 1, Metal and Vulkan end to end

Wave 2, HAL completeness (to file)

  • Storage textures: descriptor type, reflected access, a binder overload without a sampler, descriptor-pool entries, layout transitions, and a real per-format answer from supportsTextureFormat(shaderWrite:).
  • Indirect dispatch, landed together with indirect draw: indirect buffer usage and the matching barriers.
  • Push constants in compute passes, following [Flutter GPU] Push constants for small per-draw uniform data #190406.

Wave 3, OpenGL ES 3.1 (to file)

  • impellerc feature tiering for render stages that use storage, detected before SPIRV-Cross, with the minimum tier and per-stage storage use recorded in the bundle.
  • GLES compute backend: compute-only program link, glDispatchCompute, storage-buffer and image bindings, immutable texture storage, glMemoryBarrier at pass boundaries, readback through glMapBufferRange after a fence, shadow copies invalidated by GPU writes, completion when the GPU finishes. The capability check becomes GLES 3.1 / GL 4.3 plus per-stage limits.
  • The Linux embedder requests an ES 3.1 context when available (it requests client version 2 today).
  • Coverage on an Android GLES fallback device.
  • The runtime loads the opengl_desktop variant on desktop GL contexts, for custom embedders. Low priority.

Wave 4, docs (to file)

  • flutter_gpu_shaders docs for compute: the manifest's "type": "compute", tiers, limits and fallback guidance.

Out of scope

Windows (ANGLE on D3D11 exposes an ES 3.0 context), web, async compute queues, and specialization constants for workgroup size.

Sequencing

  1. Agree the contract above in this issue.

  2. Wave 1 lands as three PRs:

    Metal and Vulkan land together: Vulkan is the Android default, holds most of the synchronization work, and already runs in CI through MoltenVK, and an API shaped against Metal alone would have to change once Vulkan's constraints show up.

  3. Storage slots are designed into binding sets ([Flutter GPU] Reusable binding sets #190400, landed), and the bundle format changes once alongside push constants ([Flutter GPU] Push constants for small per-draw uniform data #190406).

  4. Wave 2, then Wave 3, then Wave 4.

Open questions

  • Storage image access: expose write-only, which matters on Metal, or normalize to read and read_write as for buffers.

Resolved: the pass lifecycle and readback shape in the contract above, after comparing WebGPU, Dawn, wgpu, Bevy, SDL_GPU, sokol_gfx, bgfx, Unity, Godot, Filament, three.js, Metal, Vulkan and D3D12.

Activity

  1. added
    c: new featureNothing broken; request for a new capability
    engineflutter/engine related. See also e: labels.
    e: impellerImpeller rendering backend issues and features requests
    on Jun 24, 2026
  2. moved this to 🤔 Needs Triage in Flutter GPUon Jun 24, 2026
  3. moved this from 🤔 Needs Triage to 💡 Features in Flutter GPUon Jun 24, 2026
  4. chinmay-garde-ai commented on Jun 25, 2026

    @chinmay-garde-ai

    Wholeheartedly endorse this proposal.

    Some notes:

    • Workgroup counts on dispatch makes sense.
    • I think just implicit synchronization is fine to start. We can add explicit escape hatches later.
    • GLES 3.1 as the capability floor seems fine to me. I am not sure what the GLES shader variants point was (the section on "One GLES variant per shader"). There should just be one compute capable shader right?
  5. bdero commented on Jun 26, 2026

    @bdero
    MemberAuthor

    @chinmay-garde-ai

    I am not sure what the GLES shader variants point was (the section on "One GLES variant per shader"). There should just be one compute capable shader right?

    Yeah that note's redundant and I removed it. I don't see why we'd ever pack multiple different GLSL version targets simultaneously for a given shader for any kind of stage. We should just have the shader compiler target the lowest GLSL ES version it can get away with given the used feature set.

  6. self-assigned this
    on Oct 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

c: new featureNothing broken; request for a new capabilitye: impellerImpeller rendering backend issues and features requestsengineflutter/engine related. See also e: labels.flutter-gputeam-fluttergpuOwned by Flutter GPU team

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions