Repository navigation
feat: Add ShaderPostProcess to draw a fragment shader as a post process - #4213
Merged
Merged
Conversation
…lame's types
Flutter's `FragmentShader` can look up uniforms by name, like
`shader.getUniformVec2('uSize')`, instead of setting them by their position.
These extensions set those slots from Flame's types:
- `UniformVec2Slot`: `setVector`, `setSize` and `setOffset`.
- `UniformVec3Slot`: `setVector`.
- `UniformVec4Slot`: `setVector` and `setColor`, with the channels between
0 and 1 and an optional premultiplied alpha.
- `UniformMat2Slot`, `UniformMat3Slot` and `UniformMat4Slot`: `setMatrix`,
keeping the columns and rows of the matrix.
They're exported from both `extensions.dart` and `post_process.dart`.
…cess Most post processes draw a fragment shader over their subtree, and each one had to load the shader, keep track of the time, rasterize the subtree and draw the shader itself. `ShaderPostProcess` does that: - It loads the shader from an asset, or uses a `FragmentProgram` with `ShaderPostProcess.fromProgram`. - Every frame, it sets `uSize` and `uTime`, if the shader declares them, and other uniforms can be set by name in `updateUniforms`. - If the shader declares `uTexture` as its first sampler, the subtree is rasterized every frame and given to it. Since samplers can't be looked up by name on the web yet, whether the shader samples the subtree has to be given with `sampleSubtree` there. On the other platforms it's detected, and a `sampleSubtree` that doesn't match the shader throws. - `ShaderPlacement` decides whether the shader replaces the subtree, or is drawn over or under it. The subtree is rendered at most once per frame, reusing the image rasterized for `uTexture` if there is one. The post processing docs and the pixelation example now use it.
…xamples The example shows every combination of a `ShaderPostProcess` whose shader does or doesn't sample the subtree, with each `ShaderPlacement`: a pixelation, a glow, a drop shadow, a vignette and stripes, over the Flame logo with Ember flying around it.
…ize its docs When a shader that samples the subtree is placed over or under it, the image rasterized for `uTexture` is drawn as the subtree, so the subtree is only rendered once per frame. That image is rasterized at `pixelRatio`, so lowering `pixelRatio` to make a shader cheaper also blurred the subtree itself. `reuseRasterizedSubtree` can now be set to false to render the subtree again at the full resolution of the screen. It defaults to true, which keeps the previous behavior. The post processing docs now group everything about `ShaderPostProcess` under its own section: the uniforms it sets, placement, the cost of rendering the subtree, setting other uniforms, the web, and the pixelation example, which moved there from the section about custom post processes. The basic shader tutorial now points to `ShaderPostProcess`.
Adds pixelates, premultiply and ufrshubham to the cspell dictionaries. `_findWhetherShaderSamplesSubtree` threw its errors from inside catch blocks, which DCM warns about. The catch blocks now only record whether the sampler was found, and the errors are thrown after the try, with the same messages.
…mple The uniforms are set with the `set` of their slots, and Ember's position with `setValues`, instead of building new vectors every frame.
ufrshubham
marked this pull request as ready for review
November 6, 2026 07:06
The rasterized subtree was sampled by the shader with the default filter quality of `setImageSampler`, `FilterQuality.none`, but drawn as the subtree with `FilterQuality.low`. `filterQuality` now decides both, and defaults to `FilterQuality.low`. It only makes a difference when the pixels of the rasterized subtree don't line up with the pixels of the screen, like when the post process is rotated or zoomed, or when `pixelRatio` is lowered. In those cases, `FilterQuality.none` leaves jagged edges, while `FilterQuality.low` keeps them smooth, with no measurable difference in the raster time of the frames. `none` is still useful to keep the pixels sharp, like for pixel art.
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Active issues allow zero-sized subtree rasterization to throw during rendering and cause reused subtree images to misalign with shader bounds at fractional pixel ratios.
2 open issues
What changed in this PR
Adds ShaderPostProcess to simplify fragment-shader effects within Flame’s post-processing system.
Changes:
- Handles shader loading, common uniforms, subtree sampling, and placement.
- Adds named uniform-slot extensions for vectors, colors, sizes, offsets, and matrices.
- Documents the API and adds examples covering all sampling and placement combinations.
| File | Description |
|---|---|
packages/flame/lib/src/post_process/shader_post_process.dart |
Implements shader post-processing and placement options. |
packages/flame/lib/src/extensions/uniform_slot.dart |
Adds typed uniform setters. |
packages/flame/lib/post_process.dart |
Exports the new API and extensions. |
packages/flame/lib/extensions.dart |
Exports uniform-slot extensions. |
examples/pubspec.yaml |
Registers example shader assets. |
examples/lib/stories/shaders/shaders.dart |
Adds the Shaders example category. |
examples/lib/stories/shaders/shader_placement_example.dart |
Demonstrates six sampling and placement combinations. |
examples/lib/main.dart |
Registers shader examples in Widgetbook. |
examples/assets/shaders/vignette.frag |
Adds a pulsing vignette effect. |
examples/assets/shaders/stripes.frag |
Adds animated procedural stripes. |
examples/assets/shaders/pixelation.frag |
Adds subtree pixelation. |
examples/assets/shaders/glow.frag |
Adds a subtree outline glow. |
examples/assets/shaders/drop_shadow.frag |
Adds an offset subtree shadow. |
doc/tutorials/basic_shader/takeaways.md |
Points readers to the higher-level API. |
doc/flame/rendering/post_processing.md |
Documents shader configuration and updates the pixelation example. |
doc/flame/examples/lib/post_process.dart |
Migrates pixelation to ShaderPostProcess. |
.github/.cspell/people_usernames.txt |
Adds a referenced username to the spelling dictionary. |
.github/.cspell/gamedev_dictionary.txt |
Adds terminology used by the new API and examples. |
Review effort: Balanced
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Description
Most post processes draw a fragment shader over their subtree, and each one has to load the shader, keep track of the time, rasterize the subtree, give it to the shader and draw the shader itself. This adds
ShaderPostProcess, which does all of that:FragmentProgramthat is already loaded withShaderPostProcess.fromProgram.uSizeanduTimeif the shader declares them. Other uniforms are set by name inupdateUniforms.uTextureas its first sampler, the subtree is rasterized every frame and given to it. Samplers can't be looked up by name on the web yet, so theresampleSubtreehas to say whether the shader samples the subtree. On the other platforms it's detected, and asampleSubtreethat doesn't match the shader throws, so a wrong value is caught there.ShaderPlacementdecides whether the shader replaces the subtree, or is drawn over or under it. When a shader that samples the subtree is drawn over or under it, the image rasterized foruTextureis also drawn as the subtree, so the subtree is only rendered once per frame.reuseRasterizedSubtree: falserenders it again instead, for whenpixelRatiois lowered to make the shader cheaper.It also adds extensions on the named uniform slots of
dart:uito set them from Flame's types:setVector,setSizeandsetOffsetonUniformVec2Slot,setVectoronUniformVec3Slot,setVectorandsetColoronUniformVec4Slot, andsetMatrixon the matrix slots. They work on anyFragmentShader.The post processing docs get a
ShaderPostProcesssection, and the pixelation example there now uses it. The basic shader tutorial points to it too. The examples get a Shaders section with a Shader Placement example, which shows every combination of a shader that does or doesn't sample the subtree with each placement.shader_placement_example.mp4
There are no unit tests for
ShaderPostProcess.FragmentProgram,FragmentShaderand the uniform slots arebaseclasses that can't be faked, and a real shader can only be loaded from the assets of the package under test, so it would have to ship with Flame. I ran the example on Windows, and on the web with both CanvasKit and Skwasm.Checklist
docsand added dartdoc comments with///.examplesordocs.Breaking Change?
Related Issues