Skip to content

Commit f538bd7

Browse files
authored
[Flutter GPU] Bind uniforms and textures by cached reflection index (flutter#189820)
Fixes flutter#189819. `RenderPass.bindUniform` and `RenderPass.bindTexture` passed the uniform name across the FFI boundary as a string on every call, and the native side allocated a `std::string` and resolved the binding through a string-keyed map lookup per bind, per draw. `UniformSlot` now resolves the binding's index in the shader's reflection data once, caches it, and binds through new index-taking entry points. `Shader.getUniformSlot` memoizes slots by name so per-draw lookups share the cache, and a reload epoch re-resolves cached indices after a shader library hot reload. The name-keyed entry points remain, and public API behavior is unchanged. In a benchmark submitting ~10k draws per frame (flutter_scene's stress harness, macOS/Metal, profile engine, A/B at the same revision), CPU render time improves 7-12% at p50. ## 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/ [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
1 parent 4a6a70a commit f538bd7

9 files changed

Lines changed: 309 additions & 37 deletions

File tree

‎engine/src/flutter/lib/gpu/lib/src/buffer.dart‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -84,13 +84,14 @@ base class DeviceBuffer extends NativeFieldWrapperClass1 {
8484

8585
bool _bindAsUniform(
8686
RenderPass renderPass,
87-
UniformSlot slot,
87+
Shader shader,
88+
int uniformStructIndex,
8889
int offsetInBytes,
8990
int lengthInBytes,
9091
) {
91-
return renderPass._bindUniformDevice(
92-
slot.shader,
93-
slot.uniformName,
92+
return renderPass._bindUniformDeviceIndexed(
93+
shader,
94+
uniformStructIndex,
9495
this,
9596
offsetInBytes,
9697
lengthInBytes,

‎engine/src/flutter/lib/gpu/lib/src/render_pass.dart‎

Lines changed: 26 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -468,9 +468,18 @@ base class RenderPass extends NativeFieldWrapperClass1 {
468468
}
469469

470470
void bindUniform(UniformSlot slot, BufferView bufferView) {
471+
// The slot's index is resolved once and cached, so steady-state binds
472+
// pass an integer across the native boundary instead of the name.
473+
int uniformStructIndex = slot._resolvedStructIndex;
474+
if (uniformStructIndex < 0) {
475+
throw Exception(
476+
"Failed to bind uniform (no uniform struct named '${slot.uniformName}')",
477+
);
478+
}
471479
bool success = bufferView.buffer._bindAsUniform(
472480
this,
473-
slot,
481+
slot.shader,
482+
uniformStructIndex,
474483
bufferView.offsetInBytes,
475484
bufferView.lengthInBytes,
476485
);
@@ -510,9 +519,15 @@ base class RenderPass extends NativeFieldWrapperClass1 {
510519
);
511520
}
512521

513-
bool success = _bindTexture(
522+
int uniformTextureIndex = slot._resolvedTextureIndex;
523+
if (uniformTextureIndex < 0) {
524+
throw Exception(
525+
"Failed to bind texture (no texture named '${slot.uniformName}')",
526+
);
527+
}
528+
bool success = _bindTextureIndexed(
514529
slot.shader,
515-
slot.uniformName,
530+
uniformTextureIndex,
516531
texture,
517532
sampler.minFilter.index,
518533
sampler.magFilter.index,
@@ -801,11 +816,11 @@ base class RenderPass extends NativeFieldWrapperClass1 {
801816
);
802817

803818
@Native<
804-
Bool Function(Pointer<Void>, Pointer<Void>, Handle, Pointer<Void>, Int, Int)
805-
>(symbol: 'InternalFlutterGpu_RenderPass_BindUniformDevice')
806-
external bool _bindUniformDevice(
819+
Bool Function(Pointer<Void>, Pointer<Void>, Int, Pointer<Void>, Int, Int)
820+
>(symbol: 'InternalFlutterGpu_RenderPass_BindUniformDeviceIndexed')
821+
external bool _bindUniformDeviceIndexed(
807822
Shader shader,
808-
String uniformName,
823+
int uniformStructIndex,
809824
DeviceBuffer buffer,
810825
int offsetInBytes,
811826
int lengthInBytes,
@@ -827,7 +842,7 @@ base class RenderPass extends NativeFieldWrapperClass1 {
827842
Bool Function(
828843
Pointer<Void>,
829844
Pointer<Void>,
830-
Handle,
845+
Int,
831846
Pointer<Void>,
832847
Int,
833848
Int,
@@ -836,10 +851,10 @@ base class RenderPass extends NativeFieldWrapperClass1 {
836851
Int,
837852
Int,
838853
)
839-
>(symbol: 'InternalFlutterGpu_RenderPass_BindTexture')
840-
external bool _bindTexture(
854+
>(symbol: 'InternalFlutterGpu_RenderPass_BindTextureIndexed')
855+
external bool _bindTextureIndexed(
841856
Shader shader,
842-
String uniformName,
857+
int uniformTextureIndex,
843858
Texture texture,
844859
int minFilter,
845860
int magFilter,

‎engine/src/flutter/lib/gpu/lib/src/shader.dart‎

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,49 @@
66

77
part of flutter_gpu;
88

9+
/// Bumped whenever any shader library hot reloads. [UniformSlot] caches
10+
/// reflection indices against this epoch, since a reload replaces the
11+
/// shaders' reflection data in place and invalidates cached indices.
12+
int _shaderReloadEpoch = 0;
13+
14+
const int _kSlotIndexUnresolved = -2;
15+
916
base class UniformSlot {
1017
UniformSlot._(this.shader, this.uniformName);
1118
final Shader shader;
1219
final String uniformName;
1320

21+
// Reflection indices for the name-free bind path, resolved through one
22+
// native call on first use and cached until a shader hot reload. -1
23+
// means the shader has no struct/texture with this slot's name.
24+
int _structIndex = _kSlotIndexUnresolved;
25+
int _textureIndex = _kSlotIndexUnresolved;
26+
int _epoch = _shaderReloadEpoch;
27+
28+
void _syncEpoch() {
29+
if (_epoch != _shaderReloadEpoch) {
30+
_structIndex = _kSlotIndexUnresolved;
31+
_textureIndex = _kSlotIndexUnresolved;
32+
_epoch = _shaderReloadEpoch;
33+
}
34+
}
35+
36+
int get _resolvedStructIndex {
37+
_syncEpoch();
38+
if (_structIndex == _kSlotIndexUnresolved) {
39+
_structIndex = shader._getUniformStructIndex(uniformName);
40+
}
41+
return _structIndex;
42+
}
43+
44+
int get _resolvedTextureIndex {
45+
_syncEpoch();
46+
if (_textureIndex == _kSlotIndexUnresolved) {
47+
_textureIndex = shader._getUniformTextureIndex(uniformName);
48+
}
49+
return _textureIndex;
50+
}
51+
1452
/// The reflected total size of a shader's uniform struct by name.
1553
///
1654
/// Returns [null] if the shader does not contain a uniform struct with the
@@ -35,8 +73,12 @@ base class Shader extends NativeFieldWrapperClass1 {
3573
// [Shader] handles are instantiated when interacting with a [ShaderLibrary].
3674
Shader._();
3775

76+
// Memoized so per-draw lookups return the same slot instance, whose
77+
// cached reflection indices make repeat binds name-free.
78+
final Map<String, UniformSlot> _uniformSlots = <String, UniformSlot>{};
79+
3880
UniformSlot getUniformSlot(String uniformName) {
39-
return UniformSlot._(this, uniformName);
81+
return _uniformSlots[uniformName] ??= UniformSlot._(this, uniformName);
4082
}
4183

4284
@Native<Int Function(Pointer<Void>, Handle)>(
@@ -52,6 +94,16 @@ base class Shader extends NativeFieldWrapperClass1 {
5294
String memberName,
5395
);
5496

97+
@Native<Int Function(Pointer<Void>, Handle)>(
98+
symbol: 'InternalFlutterGpu_Shader_GetUniformStructIndex',
99+
)
100+
external int _getUniformStructIndex(String uniformStructName);
101+
102+
@Native<Int Function(Pointer<Void>, Handle)>(
103+
symbol: 'InternalFlutterGpu_Shader_GetUniformTextureIndex',
104+
)
105+
external int _getUniformTextureIndex(String uniformTextureName);
106+
55107
/// Test-only. Whether this shader is currently marked dirty (will be
56108
/// evicted and re-registered with the impeller shader library on next
57109
/// pipeline build). Used by tests to assert that reload dedupe keeps

‎engine/src/flutter/lib/gpu/lib/src/shader_library.dart‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -110,14 +110,22 @@ base class ShaderLibrary extends NativeFieldWrapperClass1 {
110110
if (error != null) {
111111
throw Exception("Failed to reinitialize ShaderLibrary: ${error}");
112112
}
113+
// The reload replaced the shaders' reflection data in place, so cached
114+
// uniform slot indices must re-resolve.
115+
_shaderReloadEpoch++;
113116
}
114117

115118
/// Test-only. Reloads this library from `assetName`'s bytes while keeping
116119
/// this library's identity and registry key. Production hot reload always
117120
/// re-fetches the original asset path via [reinitialize]; this hook lets
118121
/// tests simulate an edited bundle by swapping in a different fixture.
119-
String? debugReinitializeFromAsset(String assetName) =>
120-
_reinitializeWithAsset(assetName);
122+
String? debugReinitializeFromAsset(String assetName) {
123+
final String? error = _reinitializeWithAsset(assetName);
124+
if (error == null) {
125+
_shaderReloadEpoch++;
126+
}
127+
return error;
128+
}
121129

122130
/// Reparses [bytes] into this library in place, preserving its identity so
123131
/// any [Shader]s already handed out keep working (they are mutated and
@@ -127,8 +135,13 @@ base class ShaderLibrary extends NativeFieldWrapperClass1 {
127135
///
128136
/// Returns null on success, or an error message if [bytes] could not be
129137
/// parsed (the live shaders are left unchanged in that case).
130-
String? reinitializeFromBytes(ByteData bytes) =>
131-
_reinitializeWithBytes(bytes);
138+
String? reinitializeFromBytes(ByteData bytes) {
139+
final String? error = _reinitializeWithBytes(bytes);
140+
if (error == null) {
141+
_shaderReloadEpoch++;
142+
}
143+
return error;
144+
}
132145

133146
@Native<Handle Function(Handle, Handle)>(
134147
symbol: 'InternalFlutterGpu_ShaderLibrary_InitializeWithAsset',

‎engine/src/flutter/lib/gpu/render_pass.cc‎

Lines changed: 55 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -405,18 +405,13 @@ void InternalFlutterGpu_RenderPass_BindIndexBufferDevice(
405405
length_in_bytes, index_type);
406406
}
407407

408-
static bool BindUniform(
408+
static bool BindUniformStruct(
409409
flutter::gpu::RenderPass* wrapper,
410410
flutter::gpu::Shader* shader,
411-
Dart_Handle uniform_name_handle,
411+
const flutter::gpu::Shader::UniformBinding* uniform_struct,
412412
const std::shared_ptr<const impeller::DeviceBuffer>& buffer,
413413
int offset_in_bytes,
414414
int length_in_bytes) {
415-
auto uniform_name = tonic::StdStringFromDart(uniform_name_handle);
416-
const flutter::gpu::Shader::UniformBinding* uniform_struct =
417-
shader->GetUniformStruct(uniform_name);
418-
// TODO(bdero): Return an error string stating that no uniform struct with
419-
// this name exists and throw an exception.
420415
if (!uniform_struct) {
421416
return false;
422417
}
@@ -458,27 +453,35 @@ bool InternalFlutterGpu_RenderPass_BindUniformDevice(
458453
flutter::gpu::DeviceBuffer* device_buffer,
459454
int offset_in_bytes,
460455
int length_in_bytes) {
461-
return BindUniform(wrapper, shader, uniform_name_handle,
462-
device_buffer->GetBuffer(), offset_in_bytes,
463-
length_in_bytes);
456+
auto uniform_name = tonic::StdStringFromDart(uniform_name_handle);
457+
return BindUniformStruct(
458+
wrapper, shader, shader->GetUniformStruct(uniform_name),
459+
device_buffer->GetBuffer(), offset_in_bytes, length_in_bytes);
464460
}
465461

466-
bool InternalFlutterGpu_RenderPass_BindTexture(
462+
bool InternalFlutterGpu_RenderPass_BindUniformDeviceIndexed(
467463
flutter::gpu::RenderPass* wrapper,
468464
flutter::gpu::Shader* shader,
469-
Dart_Handle uniform_name_handle,
465+
int uniform_struct_index,
466+
flutter::gpu::DeviceBuffer* device_buffer,
467+
int offset_in_bytes,
468+
int length_in_bytes) {
469+
return BindUniformStruct(
470+
wrapper, shader, shader->GetUniformStructAt(uniform_struct_index),
471+
device_buffer->GetBuffer(), offset_in_bytes, length_in_bytes);
472+
}
473+
474+
static bool BindTextureBinding(
475+
flutter::gpu::RenderPass* wrapper,
476+
flutter::gpu::Shader* shader,
477+
const flutter::gpu::Shader::TextureBinding* texture_binding,
470478
flutter::gpu::Texture* texture,
471479
int min_filter,
472480
int mag_filter,
473481
int mip_filter,
474482
int width_address_mode,
475483
int height_address_mode,
476484
int max_anisotropy) {
477-
auto uniform_name = tonic::StdStringFromDart(uniform_name_handle);
478-
const flutter::gpu::Shader::TextureBinding* texture_binding =
479-
shader->GetUniformTexture(uniform_name);
480-
// TODO(bdero): Return an error string stating that no uniform texture with
481-
// this name exists and throw an exception.
482485
if (!texture_binding) {
483486
return false;
484487
}
@@ -520,6 +523,41 @@ bool InternalFlutterGpu_RenderPass_BindTexture(
520523
return true;
521524
}
522525

526+
bool InternalFlutterGpu_RenderPass_BindTexture(
527+
flutter::gpu::RenderPass* wrapper,
528+
flutter::gpu::Shader* shader,
529+
Dart_Handle uniform_name_handle,
530+
flutter::gpu::Texture* texture,
531+
int min_filter,
532+
int mag_filter,
533+
int mip_filter,
534+
int width_address_mode,
535+
int height_address_mode,
536+
int max_anisotropy) {
537+
auto uniform_name = tonic::StdStringFromDart(uniform_name_handle);
538+
return BindTextureBinding(
539+
wrapper, shader, shader->GetUniformTexture(uniform_name), texture,
540+
min_filter, mag_filter, mip_filter, width_address_mode,
541+
height_address_mode, max_anisotropy);
542+
}
543+
544+
bool InternalFlutterGpu_RenderPass_BindTextureIndexed(
545+
flutter::gpu::RenderPass* wrapper,
546+
flutter::gpu::Shader* shader,
547+
int uniform_texture_index,
548+
flutter::gpu::Texture* texture,
549+
int min_filter,
550+
int mag_filter,
551+
int mip_filter,
552+
int width_address_mode,
553+
int height_address_mode,
554+
int max_anisotropy) {
555+
return BindTextureBinding(
556+
wrapper, shader, shader->GetUniformTextureAt(uniform_texture_index),
557+
texture, min_filter, mag_filter, mip_filter, width_address_mode,
558+
height_address_mode, max_anisotropy);
559+
}
560+
523561
void InternalFlutterGpu_RenderPass_ClearBindings(
524562
flutter::gpu::RenderPass* wrapper) {
525563
wrapper->ClearBindings();

‎engine/src/flutter/lib/gpu/render_pass.h‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,15 @@ extern bool InternalFlutterGpu_RenderPass_BindUniformDevice(
194194
int offset_in_bytes,
195195
int length_in_bytes);
196196

197+
FLUTTER_GPU_EXPORT
198+
extern bool InternalFlutterGpu_RenderPass_BindUniformDeviceIndexed(
199+
flutter::gpu::RenderPass* wrapper,
200+
flutter::gpu::Shader* shader,
201+
int uniform_struct_index,
202+
flutter::gpu::DeviceBuffer* device_buffer,
203+
int offset_in_bytes,
204+
int length_in_bytes);
205+
197206
FLUTTER_GPU_EXPORT
198207
extern bool InternalFlutterGpu_RenderPass_BindTexture(
199208
flutter::gpu::RenderPass* wrapper,
@@ -207,6 +216,19 @@ extern bool InternalFlutterGpu_RenderPass_BindTexture(
207216
int height_address_mode,
208217
int max_anisotropy);
209218

219+
FLUTTER_GPU_EXPORT
220+
extern bool InternalFlutterGpu_RenderPass_BindTextureIndexed(
221+
flutter::gpu::RenderPass* wrapper,
222+
flutter::gpu::Shader* shader,
223+
int uniform_texture_index,
224+
flutter::gpu::Texture* texture,
225+
int min_filter,
226+
int mag_filter,
227+
int mip_filter,
228+
int width_address_mode,
229+
int height_address_mode,
230+
int max_anisotropy);
231+
210232
FLUTTER_GPU_EXPORT
211233
extern void InternalFlutterGpu_RenderPass_ClearBindings(
212234
flutter::gpu::RenderPass* wrapper);

0 commit comments

Comments
 (0)