Repository navigation
Description
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
- Impeller has a compute HAL (
ComputePass,ComputePipeline) on Metal and Vulkan. Its only users areimpeller/renderer/compute_unittests.ccand their fixtures. - Dispatch takes 3D workgroup counts and honors the reflected
local_size, which is passed to Metal asthreadsPerThreadgroup([Impeller] Compute dispatch takes 3D workgroup counts and honors the shader local_size #188601, closes [Impeller] Compute dispatch takes 3D workgroup counts and honors the shader local_size #188478). - Explicit compute barriers exist in the HAL ([Impeller] HAL needs barriers for both Metal/Vulkan for compute usage. #140798).
- impellerc compiles
.comp, reflects storage buffers, and already emits#version 310 esand#version 430for compute shaders (Enable unit tests for compilation of compute shaders on non-metal backends #179683). A compute-only shader bundle builds today, GL variants included. - Texture shader-write usage (
enableShaderWriteUsage) already maps toMTLTextureUsageShaderWriteandVK_IMAGE_USAGE_STORAGE_BIT.
Gaps
- 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.
- No readback.
DeviceBufferhas no read API, the HAL has no buffer-to-buffer copy, lib/gpu never sets the descriptor'sreadbackflag, and on Intel Macs host-visible buffers are Managed with nosynchronizeResource, so GPU writes are not guaranteed visible to the CPU. - 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. - 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.
- 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). - Workgroup size. Vulkan overrides
constant_id = 0withmaxComputeWorkGroupSize[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. - 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). - 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.
- 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. - GLES. There is no compute infrastructure: no compute-only program link, none of
glDispatchCompute,glMemoryBarrier,glBindBufferBase,glMapBufferRangeorglBindImageTexturein 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 literallocal_size, reflected and recorded in the bundle. impellerc rejectslocal_size_*_id, and the Vulkan override ofconstant_id = 0is 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.
gpuContextexposes 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)andComputePass.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
readonlyon 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 aStateErrornaming 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 manualend()through deterministic scope (RustDropin wgpu, C#usingin 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 explicitAddBufferMemoryBarrierandAddTextureMemoryBarrier. - Readback.
CommandBuffer.readBuffer(view)andCommandBuffer.readTexture(texture, {region, mipLevel, slice})returnFuture<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, andsynchronizeResourceon Managed storage are internal. There is no synchronous read and no mapping API. - Gating.
gpuContext.supportsComputeis true only where this whole contract is implemented, independent of the HAL'sSupportsCompute(). When it is false,createComputePassthrows. 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
- [Impeller] Compute dispatch takes 3D workgroup counts and honors the shader local_size #188478 compute dispatch takes 3D workgroup counts and honors the shader
local_size([Impeller] Compute dispatch takes 3D workgroup counts and honors the shader local_size #188601) - [Flutter GPU] shader bundle carries compute workgroup size and storage buffer bindings #188477 shader bundle carries workgroup size, storage-buffer descriptors and access. GL variants are kept, since they build today. Format bump coordinated with [Flutter GPU] Push constants for small per-draw uniform data #190406.
- [Impeller] Compute dispatch contract cleanup: literal workgroup sizes, device limits, persistent bindings #193868 Workgroup size policy and dispatch contract: remove the Vulkan
constant_id = 0override, rejectlocal_size_*_idin impellerc, validate against device limits on Metal and Vulkan, expose limits ongpuContext. - [Flutter GPU] Storage buffer bindings #188479 storage-buffer slots and bindings on
ComputePassand in binding sets, with storage-buffer descriptor layouts registered in lib/gpu. Tested from a compute shader; storage in render stages waits for the Wave 3 tiering. - [Flutter GPU] ComputePipeline and ComputePass with dispatch #188480
ComputePipeline,CommandBuffer.createComputePassanddispatch, with the one-pass-at-a-time rule and persistent bindings. - [Impeller] Automatic compute synchronization on Metal and Vulkan #193869 Automatic compute synchronization: serial Metal compute encoder or write-set barriers, Vulkan compute-pass exit barriers for every consumer, render and blit pass exits into compute.
- [Flutter GPU] Pass lifecycle: one recording pass per command buffer, ended by the next command #193867 Pass lifecycle: one pass recording at a time per command buffer, implicit end on the next pass, copy, readback or submit,
end(), aStateErroron any use of an ended pass, and the backend encoder ended at that point so a command buffer can hold several passes. It changes render passes too, so it lands on its own, ahead of [Flutter GPU] ComputePipeline and ComputePass with dispatch #188480. - [Impeller] HAL support for GPU-to-CPU readback #193870 HAL support for readback: a buffer-to-buffer blit, pooled staging buffers, a Vulkan host barrier and invalidate, and
synchronizeResourcefor Managed buffers. - [Impeller] OpenGL ES command buffer completion waits for the GPU #193871 OpenGL ES command buffer completion waits for the GPU, through a fence checked even when no frames are drawn, so a readback Future never completes early.
- Dart readback API (to file):
CommandBuffer.readBufferandCommandBuffer.readTexturereturningFuture<ByteData>, on top of [Flutter GPU] Pass lifecycle: one recording pass per command buffer, ended by the next command #193867, [Impeller] HAL support for GPU-to-CPU readback #193870 and [Impeller] OpenGL ES command buffer completion waits for the GPU #193871. -
supportsComputegate and loud errors for shaders the device cannot run (to file). - [Flutter GPU] Hot reloading a compute shader dereferences a null render pipeline entry point #193872 Compute shader hot reload: fix the null dereference in
RemovePipelinesWithEntryPointand evict compute pipelines. - [Flutter GPU] Compute example and end-to-end tests on Metal and Vulkan #188481 example and end-to-end tests on Metal and Vulkan: a compute pass writing an instance buffer that a render pass consumes, checked by golden; a multi-dispatch dependency test; a readback test. They run in the existing
gpu_test.dartMetal and Vulkan configurations and skip wheresupportsComputeis false.
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,glMemoryBarrierat pass boundaries, readback throughglMapBufferRangeafter 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_desktopvariant 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
-
Agree the contract above in this issue.
-
Wave 1 lands as three PRs:
- [Flutter GPU] Pass lifecycle: one recording pass per command buffer, ended by the next command #193867, the pass lifecycle, first. It changes existing render pass behavior, so it is reviewed on its own.
- [Flutter GPU] Compute shaders on Metal and Vulkan #193805, Flutter GPU compute on Metal and Vulkan: the bundle metadata ([Flutter GPU] shader bundle carries compute workgroup size and storage buffer bindings #188477), storage buffer bindings ([Flutter GPU] Storage buffer bindings #188479), the compute pass API with the
supportsComputegate ([Flutter GPU] ComputePipeline and ComputePass with dispatch #188480), the dispatch contract cleanup ([Impeller] Compute dispatch contract cleanup: literal workgroup sizes, device limits, persistent bindings #193868), automatic synchronization ([Impeller] Automatic compute synchronization on Metal and Vulkan #193869), the compute hot reload fix ([Flutter GPU] Hot reloading a compute shader dereferences a null render pipeline entry point #193872), and end-to-end tests that dispatch a compute shader and draw its output ([Flutter GPU] Compute example and end-to-end tests on Metal and Vulkan #188481). The new feature lands whole, with the tests that show it working. - Readback: [Impeller] HAL support for GPU-to-CPU readback #193870, [Impeller] OpenGL ES command buffer completion waits for the GPU #193871 and the Dart readback API, with the readback test from [Flutter GPU] Compute example and end-to-end tests on Metal and Vulkan #188481.
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.
-
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).
-
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.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fields💡 Features
Activity
chinmay-garde-ai commentedon Jun 25, 2026
Wholeheartedly endorse this proposal.
Some notes:
bdero commentedon Jun 26, 2026
@chinmay-garde-ai
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.
[Impeller] Compute dispatch takes 3D workgroup counts and honors the …
[Flutter GPU] Shader bundles carry compute workgroup size and storage…
[Flutter GPU] Shader bundles carry compute workgroup size and storage…
[Flutter GPU] Shader bundles carry compute workgroup size and storage…
[Flutter GPU] End each pass when the next command is recorded (flutte…
[Flutter GPU] Shader bundles carry compute workgroup size and storage…
[Flutter GPU] Compute shaders on Metal and Vulkan (flutter#193805)
[Flutter GPU] End each pass when the next command is recorded (flutte…
[Flutter GPU] Compute shaders on Metal and Vulkan (flutter#193805)