Skip to content

feat: Add ShaderPostProcess to draw a fragment shader as a post process - #4213

Merged
ufrshubham merged 15 commits into
mainfrom
devkage/shader-post-process
Nov 17, 2026
Merged

ufrshubham merged 15 commits into
mainfrom
devkage/shader-post-process

Conversation

@ufrshubham

@ufrshubham ufrshubham commented Nov 5, 2026 •

Copy link
Copy Markdown
Member

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:

  • It loads the shader from an asset, or uses a FragmentProgram that is already loaded with ShaderPostProcess.fromProgram.
  • Every frame, it sets uSize and uTime if the shader declares them. Other uniforms are set by name in updateUniforms.
  • If the shader declares uTexture as 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 there sampleSubtree has to say whether the shader samples the subtree. On the other platforms it's detected, and a sampleSubtree that doesn't match the shader throws, so a wrong value is caught there.
  • ShaderPlacement decides 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 for uTexture is also drawn as the subtree, so the subtree is only rendered once per frame. reuseRasterizedSubtree: false renders it again instead, for when pixelRatio is lowered to make the shader cheaper.

It also adds extensions on the named uniform slots of dart:ui to set them from Flame's types: setVector, setSize and setOffset on UniformVec2Slot, setVector on UniformVec3Slot, setVector and setColor on UniformVec4Slot, and setMatrix on the matrix slots. They work on any FragmentShader.

The post processing docs get a ShaderPostProcess section, 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, FragmentShader and the uniform slots are base classes 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

  • I have followed the Contributor Guide when preparing my PR.
  • I have updated/added tests for ALL new/updated/fixed functionality.
  • I have updated/added relevant documentation in docs and added dartdoc comments with ///.
  • I have updated/added relevant examples in examples or docs.

Breaking Change?

  • Yes, this PR is a breaking change.
  • No, this PR is not a breaking change.

Related Issues

ufrshubham and others added 6 commits November 5, 2026 21:10
…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
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.
@ufrshubham
ufrshubham requested review from a team and a balanced review from Copilot November 10, 2026 18:25

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

@spydon spydon left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cooool! Lgtm

@ufrshubham
ufrshubham merged commit bf63e37 into main Nov 17, 2026
9 checks passed
@ufrshubham
ufrshubham deleted the devkage/shader-post-process branch November 17, 2026 15:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants