[Flutter GPU] Add instanced draw support#187359
Conversation
There was a problem hiding this comment.
Code Review
This pull request introduces support for instanced rendering in Flutter GPU by adding a VertexStepMode configuration to vertex buffers and extending the draw and drawIndexed methods to accept an instanceCount parameter. The native C++ layer is updated to handle the instance count, and new test fixtures and unit tests are added to verify the functionality. The reviewer suggests optimizing draw and drawIndexed by early-returning when the vertex, index, or instance count is zero to avoid unnecessary validation overhead, along with adding a corresponding test case to verify these safe no-ops.
|
Golden file changes have been found for this pull request. Click here to view and triage (e.g. because this is an intentional change). If you are still iterating on this change and are not ready to resolve the images on the Flutter Gold dashboard, consider marking this PR as a draft pull request above. You will still be able to view image results on the dashboard, commenting will be silenced, and the check will not try to resolve itself until marked ready for review. For more guidance, visit Writing a golden file test for Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. |
gaaclarke
left a comment
There was a problem hiding this comment.
LGTM, I just have a nit and a question
| state.renderPass.bindVertexBuffer(vertices); | ||
| state.renderPass.bindVertexBuffer(instances, slot: 1); | ||
| state.renderPass.bindUniform(pipeline.vertexShader.getUniformSlot('VertInfo'), vertInfo); | ||
| state.renderPass.draw(3, instanceCount: 4); |
There was a problem hiding this comment.
pull out 3 into a named variable
| /// multiple times while reading a new element from each instance-rate vertex | ||
| /// buffer for each instance. A [vertexCount] or [instanceCount] of 0 is | ||
| /// valid and records no drawing work. | ||
| void draw(int vertexCount, {int instanceCount = 1}) { |
There was a problem hiding this comment.
could we give users a good error if instanceCount is not 1 and their pipeline couldn't reasonable accommodate it?
|
CI had a failure that stopped further tests from running. We need to investigate to determine the root cause. SHA at time of execution: 5285d09. Possible causes:
A blank commit, or merging to head, will be required to resume running CI for this PR. Error Details: Stack trace: |
|
An existing Git SHA, To re-trigger presubmits after closing or re-opeing a PR, or pushing a HEAD commit (i.e. with |
|
autosubmit label was removed for flutter/flutter/187359, because - The status or check suite Linux linux_fuchsia has failed. Please fix the issues identified (or deflake) before re-applying this label. |
|
autosubmit label was removed for flutter/flutter/187359, because - The status or check suite Mac mac_unopt has failed. Please fix the issues identified (or deflake) before re-applying this label.
|
|
Golden file changes are available for triage from new commit, Click here to view. For more guidance, visit Writing a golden file test for Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. |
flutter/flutter@1bdf4af...66aaa9a 2026-06-08 katelovett@google.com Add docs on bumping Dart (flutter/flutter#187540) 2026-06-08 rmacnak@google.com Rename Dart_LoadELF2 back to Dart_LoadELF. (flutter/flutter#187677) 2026-06-08 1063596+reidbaker@users.noreply.github.com Add bare, reidbaker, and android agents (flutter/flutter#187588) 2026-06-08 engine-flutter-autoroll@skia.org Roll Dart SDK from 73ec2745c49a to 39f1c44e294f (3 revisions) (flutter/flutter#187684) 2026-06-08 bdero@google.com [Flutter GPU] Document the formats.dart enums (flutter/flutter#187628) 2026-06-08 engine-flutter-autoroll@skia.org Roll Skia from 0ea3dae686e3 to 43f135735152 (3 revisions) (flutter/flutter#187683) 2026-06-08 bdero@google.com [flutter_tools] Fix `flutter create` crash with SDK packages in bin/cache/pkg (flutter/flutter#187653) 2026-06-08 engine-flutter-autoroll@skia.org Roll Packages from 61bdbb4 to 13b49f4 (1 revision) (flutter/flutter#187678) 2026-06-08 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from fAGotRbStYGA0idum... to KNe93cf5wU4xG2d-m... (flutter/flutter#187675) 2026-06-08 engine-flutter-autoroll@skia.org Roll Skia from d17c51db4ede to 0ea3dae686e3 (1 revision) (flutter/flutter#187674) 2026-06-08 engine-flutter-autoroll@skia.org Roll Skia from 9659a87f500f to d17c51db4ede (2 revisions) (flutter/flutter#187672) 2026-06-08 engine-flutter-autoroll@skia.org Roll Skia from a56d5a4e1120 to 9659a87f500f (1 revision) (flutter/flutter#187667) 2026-06-07 engine-flutter-autoroll@skia.org Roll Skia from 101faf7d9d1f to a56d5a4e1120 (1 revision) (flutter/flutter#187665) 2026-06-07 burak.karahan@mail.ru Remove Material import from navigator replacement tests (flutter/flutter#186674) 2026-06-07 burak.karahan@mail.ru Remove Material import from editable text cursor tests (flutter/flutter#186671) 2026-06-07 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from eIU3QDrxaBPAMY9oi... to fAGotRbStYGA0idum... (flutter/flutter#187656) 2026-06-07 engine-flutter-autoroll@skia.org Roll Skia from 294ac0cb2a7d to 101faf7d9d1f (1 revision) (flutter/flutter#187655) 2026-06-06 engine-flutter-autoroll@skia.org Roll Skia from 91ee612cf552 to 294ac0cb2a7d (2 revisions) (flutter/flutter#187651) 2026-06-06 engine-flutter-autoroll@skia.org Roll Skia from a47a9a2c8ae5 to 91ee612cf552 (4 revisions) (flutter/flutter#187642) 2026-06-06 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from N_LiSaBSUsE2LDZgG... to eIU3QDrxaBPAMY9oi... (flutter/flutter#187641) 2026-06-06 engine-flutter-autoroll@skia.org Roll Dart SDK from 05243f181c21 to 73ec2745c49a (2 revisions) (flutter/flutter#187640) 2026-06-06 engine-flutter-autoroll@skia.org Roll Fuchsia GN SDK from oOAcFhkoE2_-Sy67z... to a87CbQSWEjkPUK1ZY... (flutter/flutter#187632) 2026-06-06 engine-flutter-autoroll@skia.org Roll Dart SDK from 6a9a0efe66eb to 05243f181c21 (1 revision) (flutter/flutter#187634) 2026-06-05 bdero@google.com [Flutter GPU] Add instanced draw support (flutter/flutter#187359) 2026-06-05 30870216+gaaclarke@users.noreply.github.com clears out the android context after the frame on mediatek devices (flutter/flutter#187404) 2026-06-05 kevmoo@users.noreply.github.com fix(tool): initialize asset isModified state on startup to prevent 2x hot restart slowdown (flutter/flutter#187488) 2026-06-05 magder@google.com Remove reference to 'good first issue' in the docs (flutter/flutter#187615) 2026-06-05 stuartmorgan@google.com Remove references to 'good first issue' (flutter/flutter#187617) 2026-06-05 154381524+flutteractionsbot@users.noreply.github.com Revert "Add support for stylus buttons" (flutter/flutter#187581) 2026-06-05 6655696+guidezpl@users.noreply.github.com Always run coverage upload step, even if a single test fails (flutter/flutter#187614) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC louisehsu@google.com,stuartmorgan@google.com on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
…r#11876) flutter/flutter@1bdf4af...66aaa9a 2026-06-08 katelovett@google.com Add docs on bumping Dart (flutter/flutter#187540) 2026-06-08 rmacnak@google.com Rename Dart_LoadELF2 back to Dart_LoadELF. (flutter/flutter#187677) 2026-06-08 1063596+reidbaker@users.noreply.github.com Add bare, reidbaker, and android agents (flutter/flutter#187588) 2026-06-08 engine-flutter-autoroll@skia.org Roll Dart SDK from 73ec2745c49a to 39f1c44e294f (3 revisions) (flutter/flutter#187684) 2026-06-08 bdero@google.com [Flutter GPU] Document the formats.dart enums (flutter/flutter#187628) 2026-06-08 engine-flutter-autoroll@skia.org Roll Skia from 0ea3dae686e3 to 43f135735152 (3 revisions) (flutter/flutter#187683) 2026-06-08 bdero@google.com [flutter_tools] Fix `flutter create` crash with SDK packages in bin/cache/pkg (flutter/flutter#187653) 2026-06-08 engine-flutter-autoroll@skia.org Roll Packages from 61bdbb4 to 13b49f4 (1 revision) (flutter/flutter#187678) 2026-06-08 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from fAGotRbStYGA0idum... to KNe93cf5wU4xG2d-m... (flutter/flutter#187675) 2026-06-08 engine-flutter-autoroll@skia.org Roll Skia from d17c51db4ede to 0ea3dae686e3 (1 revision) (flutter/flutter#187674) 2026-06-08 engine-flutter-autoroll@skia.org Roll Skia from 9659a87f500f to d17c51db4ede (2 revisions) (flutter/flutter#187672) 2026-06-08 engine-flutter-autoroll@skia.org Roll Skia from a56d5a4e1120 to 9659a87f500f (1 revision) (flutter/flutter#187667) 2026-06-07 engine-flutter-autoroll@skia.org Roll Skia from 101faf7d9d1f to a56d5a4e1120 (1 revision) (flutter/flutter#187665) 2026-06-07 burak.karahan@mail.ru Remove Material import from navigator replacement tests (flutter/flutter#186674) 2026-06-07 burak.karahan@mail.ru Remove Material import from editable text cursor tests (flutter/flutter#186671) 2026-06-07 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from eIU3QDrxaBPAMY9oi... to fAGotRbStYGA0idum... (flutter/flutter#187656) 2026-06-07 engine-flutter-autoroll@skia.org Roll Skia from 294ac0cb2a7d to 101faf7d9d1f (1 revision) (flutter/flutter#187655) 2026-06-06 engine-flutter-autoroll@skia.org Roll Skia from 91ee612cf552 to 294ac0cb2a7d (2 revisions) (flutter/flutter#187651) 2026-06-06 engine-flutter-autoroll@skia.org Roll Skia from a47a9a2c8ae5 to 91ee612cf552 (4 revisions) (flutter/flutter#187642) 2026-06-06 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from N_LiSaBSUsE2LDZgG... to eIU3QDrxaBPAMY9oi... (flutter/flutter#187641) 2026-06-06 engine-flutter-autoroll@skia.org Roll Dart SDK from 05243f181c21 to 73ec2745c49a (2 revisions) (flutter/flutter#187640) 2026-06-06 engine-flutter-autoroll@skia.org Roll Fuchsia GN SDK from oOAcFhkoE2_-Sy67z... to a87CbQSWEjkPUK1ZY... (flutter/flutter#187632) 2026-06-06 engine-flutter-autoroll@skia.org Roll Dart SDK from 6a9a0efe66eb to 05243f181c21 (1 revision) (flutter/flutter#187634) 2026-06-05 bdero@google.com [Flutter GPU] Add instanced draw support (flutter/flutter#187359) 2026-06-05 30870216+gaaclarke@users.noreply.github.com clears out the android context after the frame on mediatek devices (flutter/flutter#187404) 2026-06-05 kevmoo@users.noreply.github.com fix(tool): initialize asset isModified state on startup to prevent 2x hot restart slowdown (flutter/flutter#187488) 2026-06-05 magder@google.com Remove reference to 'good first issue' in the docs (flutter/flutter#187615) 2026-06-05 stuartmorgan@google.com Remove references to 'good first issue' (flutter/flutter#187617) 2026-06-05 154381524+flutteractionsbot@users.noreply.github.com Revert "Add support for stylus buttons" (flutter/flutter#187581) 2026-06-05 6655696+guidezpl@users.noreply.github.com Always run coverage upload step, even if a single test fails (flutter/flutter#187614) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC louisehsu@google.com,stuartmorgan@google.com on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
Progress on [flutter#186307](flutter#186307). Related to [flutter#156738](flutter#156738). Related to [flutter#154145](flutter#154145). Adds Flutter GPU support for instanced draws on top of Impeller's instance-rate vertex input support. This adds `VertexStepMode` and `VertexBuffer.stepMode`, allowing a vertex buffer slot to advance once per instance. `RenderPass.draw` and `RenderPass.drawIndexed` now take an optional `instanceCount` named parameter, defaulting to 1. Example usage: ```dart final gpu.RenderPipeline pipeline = gpu.gpuContext.createRenderPipeline( vertexShader, fragmentShader, vertexLayout: const gpu.VertexLayout( buffers: <gpu.VertexBuffer>[ gpu.VertexBuffer( strideInBytes: 8, attributes: <gpu.VertexAttribute>[ gpu.VertexAttribute( name: 'position', format: gpu.VertexFormat.float32x2, ), ], ), gpu.VertexBuffer( strideInBytes: 8, stepMode: gpu.VertexStepMode.instance, attributes: <gpu.VertexAttribute>[ gpu.VertexAttribute( name: 'instance_offset', format: gpu.VertexFormat.float32x2, ), ], ), ], ), ); renderPass ..bindPipeline(pipeline) ..bindVertexBuffer(vertexBuffer) ..bindVertexBuffer(instanceOffsets, slot: 1) ..draw(3, instanceCount: 10); ``` The implementation plumbs step mode through the custom `VertexLayout` packing into Impeller's `VertexInputRate`, forwards instance counts to the native render pass, and adds a Flutter GPU golden test that renders four instances from one geometry buffer plus one instance-rate offset/color buffer. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
Progress on flutter/flutter#186307.
Related to flutter/flutter#156738.
Related to flutter/flutter#154145.
Adds Flutter GPU support for instanced draws on top of Impeller's instance-rate vertex input support.
This adds
VertexStepModeandVertexBuffer.stepMode, allowing a vertex buffer slot to advance once per instance.RenderPass.drawandRenderPass.drawIndexednow take an optionalinstanceCountnamed parameter, defaulting to 1.Example usage:
The implementation plumbs step mode through the custom
VertexLayoutpacking into Impeller'sVertexInputRate, forwards instance counts to the native render pass, and adds a Flutter GPU golden test that renders four instances from one geometry buffer plus one instance-rate offset/color buffer.Pre-launch Checklist
///).