impeller: allows access of float uniforms by name #176728

gaaclarke · 2025-10-08T17:13:33Z

This fixes the linked issue in so far as it is possible today. This opts for the runtime lookup of bindings since it avoids all sort of messy issues when dealing with codegen. This doesn't stop us from doing codegen in the future.

This also adds tests for hot reload cases that would fail in the past, like inserting new uniforms.

Limitations

It doesn't handle component names like ".r" or ".x". This is possible if we want.
It doesn't handle nested structs. This isn't possible with the current shader metadata and may be a limitation with glsl?

Features

Slots can be cached to amortize the cost of looking up the bindings
Works with hot reload (tested inserting a uniform before one accessed by name)

Followup work

I plan on filing the following issues:

Map postfixes like ".r" ".z" to offsets so a uniform can be "foo.z"
Support nested structs so a uniform name can be "foo.bar"
Support codegen for uniforms to get compile-time uniform name support

Example

ShaderBuilder(
  assetKey: 'shaders/grayscale.frag',
  (context, shader, _) {
    Color color = Colors.red;
    shader.getUniformFloat('uColor', 0).set(color.r);
    shader.getUniformFloat('uColor', 1).set(color.g);
    shader.getUniformFloat('uColor', 2).set(color.b);
    return BackdropFilter(
      filter: ImageFilter.shader(shader),
      child: Container(
        color: Colors.transparent,
      ),
    );
  },
),

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

gaaclarke · 2025-10-08T18:25:06Z

I forgot to stub this in for the web backend, I'll just throw if this is called there for now and file an issue for it.

flar · 2025-10-08T19:26:49Z

A general question - it looks like this only solves the issue for floats. What about ImageSampler uniforms?

Also, Colors and Vec2 are handled by having the developer manually index all of the components. It would be fairly trivial to add getUniformColor(name) and getUniformVec2(name) just based on the existing support already being added for floats which would also alleviate the need to know how the color components and x,y coordinate values are laid out in the uniforms.

(assuming I got the relative offsets of the color components right in the example below)

base class UniformColorSlot {
  UniformColorSlot._(this._shader, this.name, this._index);

  /// Set the Color value of the bound uniform.
  void set(Color c) {
    _shader.setFloat(_index, c.a);
    _shader.setFloat(_index + 1, c.r);
    _shader.setFloat(_index + 2, c.g);
    _shader.setFloat(_index + 3, c.b);
  }

  /// VisibleForTesting: This is the index one would use with
  /// [FragmentShader.setFloat] for the base alpha component of this uniform.
  int get index {
    return _index;
  }

  final FragmentShader _shader;
  final int _index;

  /// The name of the bound uniform.
  final String name;
}

...

class FragmentShader {
  UniformColorSlot getUniformColor(String name) {
    return UniformColorSlot(this, name, _getBaseIndexForName(name));
  }
}

flar

Some API and performance notes.

engine/src/flutter/lib/ui/painting.dart

gaaclarke · 2025-10-08T20:33:59Z

A general question - it looks like this only solves the issue for floats. What about ImageSampler uniforms?

Correct, that will be handled in a different PR.

Also, Colors and Vec2 are handled by having the developer manually index all of the components. It would be fairly trivial to add getUniformColor(name) and getUniformVec2(name) just based on the existing support already being added for floats which would also alleviate the need to know how the color components and x,y coordinate values are laid out in the uniforms.

(assuming I got the relative offsets of the color components right in the example below)
base class UniformColorSlot {
  UniformColorSlot._(this._shader, this.name, this._index);

  /// Set the Color value of the bound uniform.
  void set(Color c) {
    _shader.setFloat(_index, c.a);
    _shader.setFloat(_index + 1, c.r);
    _shader.setFloat(_index + 2, c.g);
    _shader.setFloat(_index + 3, c.b);
  }

Yep, I thought about that. I think that's a good idea but I don't think it should live in dart:ui. This provides the fundamental tools for someone to make that library.

flar · 2025-10-08T20:56:50Z

A general question - it looks like this only solves the issue for floats. What about ImageSampler uniforms?

Correct, that will be handled in a different PR.
add getUniformColor(name) and getUniformVec2(name)
base class UniformColorSlot {
}
Yep, I thought about that. I think that's a good idea but I don't think it should live in dart:ui. This provides the fundamental tools for someone to make that library.

Someone could do any of this as a separate library, though. Why even have these new classes when all you need is "getOffsetForName(String)" and let them do their library.

One of the advantages of doing the Color and Vec2 (and Matrix) slot objects is that in returning them we could do some type checking (might require some extra info from native for explicit types, or at least it could check that a Color name is associated with 4 floats). Or, just expose the type/count info via methods and let the external library do that checking as well:

(optional) name-to-type
name-to-count
name-to-offset

are all that is needed to enable an external library. The (optional) type would be restricted to only the standard types and need to have a "custom" type for when someone makes up their own struct in the program.

gaaclarke · 2025-10-08T21:12:08Z

Someone could do any of this as a separate library, though. Why even have these new classes when all you need is "getOffsetForName(String)" and let them do their library.

I would be open to something like that. I was thinking I'd have to do more to make sure that hot reload would work, but happily it seems to work fine like this. I was worried I'd have to keep weak references around to slots so that when we hot reload we could invalidate the slots to get them to rebind. There are symbols that seem related to hot reloading that we definitely wouldn't want to make public. We'll see if chinmay sees something I didn't with regard to hot reloading.

There's definitely an art to drawing the line and there are tradeoffs for every place we could decide to draw it. Having the most fundamental entity being useful and guaranteed to work with hot reload seems like a good place to draw it though.

gaaclarke · 2025-10-08T23:17:47Z

draft posted for image samplers: #176749

gaaclarke · 2025-10-09T15:58:01Z

I just tried hot reload again to show @flar and it doesn't work. I may have accidentally tested this with hot restart. I'll update update this. I figured I'd have to account for this, that's why there is a slot class. I'm dropping back to draft until it's fixed. I don't think there is a mechanism to do automated tests for this unfortunately.

flutter-dashboard · 2025-10-09T16:02:07Z

This pull request has been changed to a draft. The currently pending flutter-gold status will not be able to resolve until a new commit is pushed or the change is marked ready for review again.

For more guidance, visit Writing a golden file test for package:flutter.

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing.

auto-submit · 2025-10-13T23:42:30Z

autosubmit label was removed for flutter/flutter/176728, because - The status or check suite Mac_arm64 build_tests_4_4 has failed. Please fix the issues identified (or deflake) before re-applying this label.

…flutter#176728)

…10229) Manual roll Flutter from e11e2c11288b to 7cd821c21093 (73 revisions) Manual roll requested by [email protected] flutter/flutter@e11e2c1...7cd821c 2025-10-14 [email protected] Fix computeDistanceToActualBaseline throws when accessing child size (flutter/flutter#176906) 2025-10-14 [email protected] iOS can set application locale before view controller is set (flutter/flutter#176592) 2025-10-14 [email protected] Roll ANGLE to a branch based on d9fa255a5c22 (flutter/flutter#176747) 2025-10-14 [email protected] Relands "Fixes keyboard selects disabled radio" (flutter/flutter#176977) 2025-10-14 [email protected] Fix expansion tile is missing state announcement on non-Apple platforms (flutter/flutter#175480) 2025-10-14 [email protected] impeller: allows access of float uniforms by name (flutter/flutter#176728) 2025-10-14 [email protected] Roll dart sdk to 3.11.0-17.0.dev (flutter/flutter#176947) 2025-10-13 [email protected] Move iOS integration tests (flutter/flutter#176940) 2025-10-13 [email protected] Make sure that an InputDatePickerFormField doesn't crash in 0x0 envir… (flutter/flutter#176047) 2025-10-13 [email protected] [web] Match the behavior of other platforms in Web Locale.toString if the country code is an empty string (flutter/flutter#176862) 2025-10-13 98614782+auto-submit[bot]@users.noreply.github.com Reverts "Fixes keyboard selects disabled radio (#176727)" (flutter/flutter#176958) 2025-10-13 [email protected] Fixes keyboard selects disabled radio (flutter/flutter#176727) 2025-10-13 [email protected] Roll Packages from e319c40 to d062181 (2 revisions) (flutter/flutter#176916) 2025-10-13 [email protected] Roll SwiftShader to 794b0cfce1d8 (flutter/flutter#176806) 2025-10-13 [email protected] Make DropdownMenu generic type non nullable (flutter/flutter#176711) 2025-10-12 [email protected] Roll Fuchsia Linux SDK from BWGpRvpdQh-HJpq1c... to _dd0Jv50H0oUI2Ad8... (flutter/flutter#176895) 2025-10-11 [email protected] Roll Fuchsia Linux SDK from JpiUsek1hU5r9QVKP... to BWGpRvpdQh-HJpq1c... (flutter/flutter#176880) 2025-10-11 [email protected] fix: content hash check for LUCI_CONTEXT (flutter/flutter#176867) 2025-10-11 [email protected] Feat: make tooltip position customizeable (flutter/flutter#175047) 2025-10-11 [email protected] Roll Dart SDK from d88d8bf2b53c to 65b171958c93 (3 revisions) (flutter/flutter#176871) 2025-10-11 [email protected] feat: apply radioGroup role to segmented control widgets (flutter/flutter#176157) 2025-10-10 [email protected] Make sure that a CheckboxMenuButton doesn't crash in 0x0 environment (flutter/flutter#176450) 2025-10-10 [email protected] [WebParagraph] Support for more styles, placeholders, decorations, etc (flutter/flutter#172853) 2025-10-10 [email protected] Set up a version of build_ios_framework_module_test that only runs on x64 machines and extend its timeout (flutter/flutter#176811) 2025-10-10 [email protected] Roll Packages from 0b41de3 to e319c40 (1 revision) (flutter/flutter#176833) 2025-10-10 [email protected] [tool/dap] Forward app.warning events from Flutter to DAP client (flutter/flutter#176827) 2025-10-10 [email protected] Roll Dart SDK from 70c00d3ceb3a to d88d8bf2b53c (1 revision) (flutter/flutter#176830) 2025-10-10 [email protected] Remove unnecessary nullable types in examples. (flutter/flutter#176713) 2025-10-10 [email protected] Roll Fuchsia Linux SDK from xArtL4DH0FsdwSqG_... to JpiUsek1hU5r9QVKP... (flutter/flutter#176822) 2025-10-10 [email protected] Cleanup OutlinedButton.icon documentation and implementation (flutter/flutter#176630) 2025-10-10 [email protected] [HCPP] Properly remove hcpp views that are no longer visible (flutter/flutter#176742) 2025-10-10 [email protected] Make sure that an InputChip doesn't crash in 0x0 environment (flutter/flutter#175930) 2025-10-10 [email protected] Update Flutter templates' Dart style (flutter/flutter#175963) 2025-10-10 [email protected] Make sure that a DropdownButtonFormField doesn't crash in 0x0 environ… (flutter/flutter#174958) 2025-10-10 [email protected] Make sure that an InkWell doesn't crash in 0x0 environment (flutter/flutter#175871) 2025-10-10 [email protected] Handle#6537 end drawer button (flutter/flutter#173026) 2025-10-10 [email protected] Roll Dart SDK from a9b7bd4b0b32 to 70c00d3ceb3a (4 revisions) (flutter/flutter#176815) 2025-10-10 [email protected] Change default Linux thread policy to merge platform and UI threads. (flutter/flutter#176759) 2025-10-09 [email protected] [ Tool ] Roll package:dwds to 26.0.0 (flutter/flutter#176808) 2025-10-09 [email protected] Update `CHANGELOG` to include 3.35.6 notes (flutter/flutter#176803) 2025-10-09 [email protected] Announce text and button together when DropdownMenu is treated as a button (flutter/flutter#176428) 2025-10-09 [email protected] [native_assets] create macOS CCompilerConfig via xcrun --find (flutter/flutter#175717) 2025-10-09 [email protected] [Impeller] Fix broken links in README. (flutter/flutter#176770) 2025-10-09 [email protected] Fix links to Custom Flutter Engine Embedders in README. (flutter/flutter#175807) ...

fixes flutter#176417 This fixes the linked issue in so far as it is possible today. This opts for the runtime lookup of bindings since it avoids all sort of messy issues when dealing with codegen. This doesn't stop us from doing codegen in the future. This also adds tests for hot reload cases that would fail in the past, like inserting new uniforms. ## Limitations 1) It doesn't handle component names like ".r" or ".x". This is possible if we want. 1) It doesn't handle nested structs. This isn't possible with the current shader metadata and may be a limitation with glsl? ## Features 1) Slots can be cached to amortize the cost of looking up the bindings 1) Works with hot reload (tested inserting a uniform before one accessed by name) ## Followup work I plan on filing the following issues: 1) Map postfixes like ".r" ".z" to offsets so a uniform can be "foo.z" 1) Support nested structs so a uniform name can be "foo.bar" 1) Support codegen for uniforms to get compile-time uniform name support ## Example ```dart ShaderBuilder( assetKey: 'shaders/grayscale.frag', (context, shader, _) { Color color = Colors.red; shader.getUniformFloat('uColor', 0).set(color.r); shader.getUniformFloat('uColor', 1).set(color.g); shader.getUniformFloat('uColor', 2).set(color.b); return BackdropFilter( filter: ImageFilter.shader(shader), child: Container( color: Colors.transparent, ), ); }, ), ``` ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [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. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.  [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [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

started allowing uniforms to be set by name

51128ef

github-actions bot added the engine flutter/engine related. See also e: labels. label Oct 8, 2025

gaaclarke added 4 commits October 8, 2025 10:47

added tests

3cb3580

started handling underflow for indexes too

37eb22c

docstrings

18bc4dd

format

6b74b65

gaaclarke marked this pull request as ready for review October 8, 2025 18:21

gaaclarke requested review from chinmaygarde and flar October 8, 2025 18:21

flar reviewed Oct 8, 2025

View reviewed changes

engine/src/flutter/lib/ui/painting.dart Show resolved Hide resolved

engine/src/flutter/lib/ui/painting.dart Show resolved Hide resolved

engine/src/flutter/lib/ui/painting.dart Outdated Show resolved Hide resolved

gaaclarke mentioned this pull request Oct 8, 2025

impeller: allow setting image sampler uniforms by name #176749

Merged

9 tasks

gaaclarke marked this pull request as draft October 9, 2025 15:58

gaaclarke added 8 commits October 9, 2025 09:15

lint

0fe66b8

started updating slots (works for reordering uniforms)

3fba754

added reload test

47aede1

added test for inserting new uniforms

bcb812f

fixed flakiness of test

cdb247c

updated examples

8598883

lint

a6d6be9

updated web api

c999316

github-actions bot added the platform-web Web applications specifically label Oct 10, 2025

gaaclarke marked this pull request as ready for review October 10, 2025 18:58

gaaclarke added the autosubmit Merge PR when tree becomes green via auto submit App label Oct 13, 2025

gaaclarke mentioned this pull request Oct 13, 2025

Updated fragment shader sample to use uniform-by-name accessor flutter/samples#2736

Draft

5 tasks

auto-submit bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Oct 13, 2025

gaaclarke added the autosubmit Merge PR when tree becomes green via auto submit App label Oct 14, 2025

auto-submit bot added this pull request to the merge queue Oct 14, 2025

Merged via the queue into flutter:master with commit d04705c Oct 14, 2025
191 checks passed

flutter-dashboard bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Oct 14, 2025

engine-flutter-autoroll mentioned this pull request Oct 14, 2025

Roll Flutter from e11e2c11288b to c63c6b08a711 (69 revisions) flutter/packages#10225

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 14, 2025

d04705c92 impeller: allows access of float uniforms by name (flutter/…

28617da

…flutter#176728)

engine-flutter-autoroll mentioned this pull request Oct 14, 2025

Roll Flutter from e11e2c11288b to 55712c460fb8 (71 revisions) flutter/packages#10226

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 14, 2025

d04705c92 impeller: allows access of float uniforms by name (flutter/…

72147e4

…flutter#176728)

engine-flutter-autoroll mentioned this pull request Oct 14, 2025

Roll Flutter from e11e2c11288b to 48d5d48b5d90 (72 revisions) flutter/packages#10227

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 14, 2025

d04705c92 impeller: allows access of float uniforms by name (flutter/…

c74b664

…flutter#176728)

engine-flutter-autoroll mentioned this pull request Oct 14, 2025

Roll Flutter from e11e2c11288b to 7cd821c21093 (73 revisions) flutter/packages#10228

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 14, 2025

d04705c92 impeller: allows access of float uniforms by name (flutter/…

ab8755b

…flutter#176728)

engine-flutter-autoroll mentioned this pull request Oct 14, 2025

Manual roll Flutter from e11e2c11288b to 7cd821c21093 (73 revisions) flutter/packages#10229

Merged

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 14, 2025

d04705c92 impeller: allows access of float uniforms by name (flutter/…

10c3624

…flutter#176728)

engine-flutter-autoroll mentioned this pull request Oct 14, 2025

Roll Flutter from e11e2c11288b to 56ce192dc679 (74 revisions) flutter/packages#10230

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 14, 2025

d04705c92 impeller: allows access of float uniforms by name (flutter/…

ca25eaf

…flutter#176728)

engine-flutter-autoroll mentioned this pull request Oct 15, 2025

Roll Flutter from e11e2c11288b to cb94cc070574 (75 revisions) flutter/packages#10233

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 15, 2025

d04705c92 impeller: allows access of float uniforms by name (flutter/…

ebc5734

…flutter#176728)

engine-flutter-autoroll mentioned this pull request Oct 15, 2025

Roll Flutter from e11e2c11288b to cb94cc070574 (75 revisions) flutter/packages#10234

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 15, 2025

d04705c92 impeller: allows access of float uniforms by name (flutter/…

cc8f61f

…flutter#176728)

impeller: allows access of float uniforms by name #176728

impeller: allows access of float uniforms by name #176728

Uh oh!

Conversation

gaaclarke commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Limitations

Features

Followup work

Example

Pre-launch Checklist

Uh oh!

gaaclarke commented Oct 8, 2025

Uh oh!

flar commented Oct 8, 2025

Uh oh!

flar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gaaclarke commented Oct 8, 2025

Uh oh!

flar commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gaaclarke commented Oct 8, 2025

Uh oh!

gaaclarke commented Oct 8, 2025

Uh oh!

gaaclarke commented Oct 9, 2025

Uh oh!

flutter-dashboard bot commented Oct 9, 2025

Uh oh!

auto-submit bot commented Oct 13, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gaaclarke commented Oct 8, 2025 •

edited

Loading

flar commented Oct 8, 2025 •

edited

Loading