RuntimeShaders class final

Materials and render steps compiled while the game runs.

A registry the application hands the engine beside the renderer's: it holds the doors a run-time shader needs — the device's loadShaders, the renderer's renderSteps.addMaterials, for WebGL2 the engine's GLSL headers, and for WebGPU the engine's compiled stage a material is spliced into (webGpuMaterialHost() from flutter3d_webgpu) — so a plugin brings source and nothing else.

A raw render step is compiled on WebGL2 alone: its stage is a whole fragment shader in one backend's language, and on WebGPU it would come with no reflection to bind it by.

final shaders = RuntimeShaders(
  backend: RuntimeBackends.cpu,
  loadShaders: device.loadShaders,
  addMaterials: renderer.renderSteps.addMaterials,
);
EngineLoop(
  input: input,
  backend: RuntimeBackends.cpu,
  registries: [renderer.renderSteps, shaders],
  plugins: [glow],
);

A material or a step the backend cannot compile is off, not an error. Decision 15: a missing backend switches the step off and reports why. statuses holds the reason for each, by name, and the rest of the plugin installs. Compiling and loading are asynchronous; a material is in the renderer, and a step draws, from the frame after its library arrives. settled completes when nothing is pending.

On Impeller a material is found, not compiled (D19). impellerc ships with the Flutter SDK and not with a game, so flutter3d_build's hook compiles every installed plugin's materials into the project for the SDK that builds it; prebuilt hands back that bundle for a material's name (EngineBundleStamp.projectMaterialAsset). A material it has no bundle for is off with a MissingShaderStageException in refusals naming the stage and the plugin.

Constructors

RuntimeShaders({required String? backend, required Future<LoadedShaderLibrary> loadShaders(ByteData bundle), required Registration addMaterials(ShaderLibrary library), Map<String, String>? engineSources, PackedStage? webGpuHost, int? webGpuFullscreenUvLocation, MaterialCompilerRegistry? compilers, Future<ByteData?> prebuilt(String material)?})

Properties

backend → String?
The backend shaders are built for, normalised — see RuntimeBackends.normalize.
no setter
companions → Iterable<PluginRegistry>
The registries that come with this one, found by PluginHost.registry as if each had been handed to the host itself.
no setterinherited
hashCode → int
The hash code for this object.
no setterinherited
refusals → Map<String, Flutter3dException>
The typed reason a material or a step is off, by name, where there is one to throw: a stage the build did not compile for Impeller is a MissingShaderStageException. Its message is the one in statuses.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
settled → Future<void>
Completes once every load asked for so far has arrived or failed.
no setter
statuses → Map<String, String?>
Every material and step added, by name, and why each is off — null for one that is on or still loading.
no setter

Methods

addMaterial(String source, {required String from}) → Registration
Compiles source for this engine's backend and adds it to the renderer's materials once loaded. from names it in every message.
addRenderStep(RuntimeRenderStep step, RendererSteps into) → Registration
Adds step to into — the renderer's steps as the same plugin sees them — with a pass that draws once its stage for this backend is loaded.
forPlugin(PluginScope scope) → RuntimeShaders
This registry as scope's plugin sees it: everything registered through the result is tracked by scope, ranked by it, and checked against its manifest. Must return the same type the registry is looked up by.
lighting(String material) → LightingModel?
The lighting model a material added here is drawn with, once it is loaded: RenderMaterial(lighting: shaders.lighting('RimGlow')). Null before then, and for a material that is off.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited