Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(render): the scene can draw a G-buffer beside its colour, and reflections read each surface's normal, roughness and metalness from it

yhh59a2ef4e74ac
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 51c9532b8..68cd1b6da 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Added
+- **Quality levels can leave out expensive effects.** Quality levels can now skip expensive post-process effects by name. A level's `skipEffects` lists the effects it leaves out, each named by what its passes' names start with (`ssr`, `taa`, `depthOfField`, `lightShafts`, …); a project's own list in its quality profile replaces the level's. By default low leaves out reflections, temporal anti-aliasing, depth of field and light shafts, and medium leaves out reflections and depth of field; high leaves out nothing. These defaults come from the work each effect does per pixel, not from a weak device: the editor's new `fx-cost` check measured every effect on Bistro at 2560×1600 on a fast desktop GPU, and none added more than about 6 ms (reflections ~5, bloom ~4, the example's whole eight-effect chain ~11, the rest within the ±3 ms the run drifts by), so the levels have not been checked against the hardware they are for.
+- **A G-buffer, and reflections that read it.** Reflections now know how rough and how metal each surface is, from a G-buffer the frame draws on request. A post-process shader that says `#pragma gbuffer` makes the scene target carry a second RGBA8 colour attachment, written in the same pass by the scene's own shaders — octahedral normal in `r`/`g`, roughness in `b`, metalness in `a` (0 where nothing wrote) — and finds it at `u_gbuffer`. A frame whose chain has no such effect makes none and compiles no variant. The render device grew multiple colour attachments for it on both backends: WebGL2 attaches and resolves a second target and sets the draw buffers per pipeline, and WebGPU declares the second target on every pipeline of the pass (written by the ones that write it, an empty write mask for the rest), clears it to zero and resolves it with the colour. Pipelines say whether they write it (`PipelineDesc::gbuffer`), a blended draw never does, and the second output is its own shader variant (`ES_GBUFFER`), so no pass pays for what it did not ask for. The built-in Model shader — what an imported glTF material becomes — writes it from the material's roughness, metalness and normal map. `ssr` reads it: it takes the surface's own normal (normal-map detail that depth cannot see), weighs and blurs the reflection by roughness, reflects a metal at nearly full strength where a dielectric reflects 4%, skips a surface rougher than `maxRoughness` before marching the ray, and takes the Rain effect's `wetness` as a film that smooths the ground. Where nothing wrote a record, it falls back to depth and the dielectric it has always assumed. Verified in the editor on both backends: of two floors that differ only in their material's roughness, the glossy one changes ten times the pixels the rough one does.
- **Rain, wet ground and puddles.** A Rain post-process effect adds falling rain, wet ground, puddles and ripples. `rain` draws three layers of slanted streaks, each at its own distance so a nearer surface hides them and the sky does not; darkens the ground that faces up by `wetness`; lays ripples and splashes where drops land on a grid in the world, so they stay on the ground as the camera moves (ripples need `intensity` above 0: wet ground under no rain is still); and, by `puddles` and `puddleScale`, covers part of the flat ground with standing water that is darker and takes denser, clearer ripples. `ssr` takes the same two numbers and treats those pools as mirrors — flat, far more reflective than dry ground, and sharp — so the pools the rain darkens are the pools that reflect. The clock is `u_time * timeScale + phase`, so a capture can pin it. The rain is a screen-space layer, not particles that collide with the world, and a puddle is flat ground whatever it lies on. Verified in the editor on both backends: streaks light a dark sky and move between two moments, wet ground reads darker, standing water darker still, and puddles change the reflection.
- **Auto Exposure and Depth of Field.** Auto Exposure and Depth of Field post-process effects are available. `autoExposure` measures the average log luminance of the picture (leaving out pixels darker than 2^-8, so a black backdrop does not open the exposure to its limit), turns it into the exposure that puts it at middle grey, and moves toward that over time from where the last frame left it — brighter faster than darker, per second, within `minEV` and `maxEV`, with a `bias` in stops. To keep the settled value between frames a post-process shader can now declare a `u_feedback` texture: the engine keeps that pass's last output, at the pass's own size, and binds it there, without shifting the picture the way `u_history` does. `depthOfField` blurs by distance from `focusDistance`, with a sharp slab of `focusRange`, a blur radius that grows with how far a surface is from focus up to `maxBlur`, and a gather that counts a neighbour only where its own blur reaches back, so a sharp object does not bleed into a blurred background. Verified in the editor on both backends: a dim scene brightens (mean 6.9 to 16.5) and a bright one darkens (30.7 to 20.4), a drop in light is first dark and then recovered over real time (5.2 then 15.8), and focusing close takes the squared edge energy down to 21% of the sharp frame.
- **Height Fog and Light Shafts.** Height Fog and Light Shafts post-process effects add atmosphere. `heightFog` is exponential height fog with a closed-form integral — no marching — so a valley fills and a hilltop clears, the horizon turns hazy while the zenith stays clear, and looking toward the sun the haze takes the sun's colour; sky pixels run through the same formula with a very long ray, and `skyFog` sets how much haze the sky keeps. `lightShafts` marches each pixel toward the sun's place on screen and counts how much of the way is open sky, leaving rays through whatever stands in front of the sun. The sun's direction is set on the effects (azimuth and elevation), not read from a light. Neither is a shadowed volume: fog is lit evenly. Both run on WebGL2 and WebGPU; with an output transform of None, a floor fully taken by the fog reads exactly the authored colour on both.
diff --git a/desktop b/desktop
index 7cf0ce90a..205561b42 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 7cf0ce90aa5d0491b834124ab89b11351bb07d36
+Subproject commit 205561b42bcb6cb49f0b50527e8a37cb6f84cc7e
diff --git a/docs/astro/src/content/docs/graphics/materials.mdx b/docs/astro/src/content/docs/graphics/materials.mdx
index 8ae649efb..ca25ccaa5 100644
--- a/docs/astro/src/content/docs/graphics/materials.mdx
+++ b/docs/astro/src/content/docs/graphics/materials.mdx
@@ -89,6 +89,7 @@ One file holds every stage plus its metadata, separated by pragmas:
| `#pragma switch NAME [default(on)]` | Material-facing static permutation toggle (a `#define`). |
| `#pragma feature NAME` | Engine-chosen compile-time variant keyword. |
| `#pragma coverage PARAM` | While the float param `PARAM` is above zero, the shader's output alpha is coverage — a cutout's alpha sharpened to about a texel around the cutoff. An opaque draw into a multisampled target then turns it into multisample coverage, so the cutout's edge is antialiased instead of stair-stepped. The built-in Model shader declares `u_alphaCutoff`. |
+| `#pragma gbuffer` | A `PostProcess` shader reads the scene's surface record (see [the G-buffer](/docs/graphics/post-processing/#the-g-buffer)) at `u_gbuffer`. Declaring it is what makes the frame draw one; a chain whose shaders do not never pays for it. |
| `#pragma vertex` / `#pragma fragment` … `#pragma end` | Stage bodies. **The vertex block is optional for 2D domains** — the engine injects the canonical stage. |
| `#include "path"` | Textual include (resolved by the host). |
diff --git a/docs/astro/src/content/docs/graphics/post-processing.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdx
index a66d3ded7..4b8089dd3 100644
--- a/docs/astro/src/content/docs/graphics/post-processing.mdx
+++ b/docs/astro/src/content/docs/graphics/post-processing.mdx
@@ -87,6 +87,23 @@ circle, counting a neighbour only to the extent that neighbour's own blur reache
blurred background does not bleed into it, while a blurred foreground spreads over what is behind it. The gather is
rotated per pixel, so it leaves a fine grain that `taa` averages away.
+### The G-buffer
+
+Some effects have to know what a surface IS, not only how it looks. An effect whose shader says `#pragma gbuffer` makes the
+frame draw a second colour attachment beside the scene's, in the same pass and from the same shaders: **octahedral normal in
+`r` and `g`, roughness in `b`, metalness in `a`** (`a` is 0 where nothing wrote, and `0.25 + 0.75 × metalness`
+where something did), 8 bits a channel. The effect finds it at `u_gbuffer` (GLSL) or `t6` (WGSL, read with `textureLoad`).
+
+It costs one extra RGBA8 target and one extra write per pixel, and only while an enabled effect asks: a frame with no such
+effect has no attachment and compiles no variant. What writes it today is the built-in **Model** shader — what an imported
+glTF material becomes — which is roughness, metalness and normal map as the material says. A mesh drawn without a material, a sprite, a
+blended surface and a custom shader leave it at 0, and an effect must treat that as "unknown" and fall back, as `ssr` does.
+A shader of your own can write it: it is compiled with `ES_GBUFFER` defined when the pass has the attachment, and then declares
+a second output (`layout(location = 1) out vec4`, or a struct return in WGSL) and writes the same encoding.
+
+On WebGL2 and WebGPU alike the attachment is multisampled with the scene and resolved with it. A blended draw never writes
+it — a normal averaged with the one behind it is neither's — and the scene's own background clears it to 0.
+
### Fog and atmosphere
`heightFog` is fog that thins with height: a valley fills, a hilltop clears. Its density falls
@@ -117,9 +134,14 @@ is a hit. What it finds is blended over the pixel by a Schlick Fresnel term: fai
strong at a grazing angle, so the floor shines toward the horizon. A farther hit is blurred more,
which stands in for roughness.
-Nothing in the chain knows a material's roughness, so `floorBias` decides what may reflect: at 1
-only up-facing surfaces do, at 0 every surface reflects by its Fresnel term alone. It cannot show
-what is off screen, behind another object or in the sky — there it leaves the pixel as it was, so
+What a surface is comes from [the G-buffer](#the-g-buffer): where the scene wrote one, the reflection uses the
+surface's own normal (a normal map's detail, which depth cannot see), its roughness and its metalness. A rough surface
+reflects dimly and blurred, and one rougher than `maxRoughness` is skipped before the ray is marched, which is most of the
+cost; a metal reflects nearly all it receives where a dielectric reflects 4% face-on. `wetness` makes ground
+smoother (a film of water fills the pores), so it reflects as it gets wet, and puddles are mirrors. Where nothing wrote
+a record — a mesh with no material, a sprite — the depth normal stands, the surface is taken for a middling dielectric and
+`floorBias` decides what may reflect: at 1 only up-facing surfaces do, at 0 every surface by its Fresnel term alone.
+It cannot show what is off screen, behind another object or in the sky — there it leaves the pixel as it was, so
it sits on top of the environment's own specular rather than replacing it. `maxDistance` is a
world length; the step count is fixed, so a longer reach is a coarser march, and the per-pixel
start offset that hides the banding is what `taa` averages away — use them together.
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
index 36720fbc2..d05a40316 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
@@ -75,6 +75,7 @@ std140 uniform 块,于是 CPU 能按名字设置、并安全地送到 GPU。一
| `#pragma switch NAME [default(on)]` | 材质可控的静态排列开关(一个 `#define`)。 |
| `#pragma coverage PARAM` | 浮点参数 `PARAM` 大于零时,着色器输出的 alpha 就是覆盖率——镂空的 alpha 在阈值附近锐化到约一个纹素宽。不透明物体画进多重采样目标时,它会转成多重采样覆盖率,镂空边缘就有抗锯齿而不是台阶。内置 Model 着色器声明了 `u_alphaCutoff`。 |
| `#pragma feature NAME` | 引擎选择的编译期变体关键字。 |
+| `#pragma gbuffer` | `PostProcess` 着色器要读取场景的表面记录(见[G-buffer](/docs/zh-cn/graphics/post-processing/#g-buffer)),在 `u_gbuffer` 处。声明它才会让这一帧画出一份;着色器里没有它的链路永远不付这笔钱。 |
| `#pragma vertex` / `#pragma fragment` … `#pragma end` | Stage 代码体。**2D 域的顶点段可省略**——引擎注入规范顶点段。 |
| `#include "path"` | 文本 include(由宿主解析)。 |
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
index b719e169a..2c948ad08 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
@@ -71,6 +71,19 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
收集邻居,只在邻居自己的模糊够得着这里时才计入:清晰的前景物体不会渗进模糊的背景,而模糊的前景会铺到它后面的东西上。
收集按像素旋转,留下一层细颗粒,由 `taa` 平均掉。
+### G-buffer
+
+有些效果必须知道表面**是什么**,而不只是它看起来怎样。着色器里写了 `#pragma gbuffer` 的效果会让这一帧在场景的颜色旁多画一个颜色附件,
+同一个 pass、同样的着色器:**八面体法线在 `r`、`g`,粗糙度在 `b`,金属度在 `a`**(没写的地方 `a` 为 0,写了的地方是
+`0.25 + 0.75 × 金属度`),每通道 8 位。效果在 `u_gbuffer`(GLSL)或 `t6`(WGSL,用 `textureLoad` 读)处找到它。
+
+它多花一个 RGBA8 目标和每像素一次额外写入,而且只在有已启用的效果要它时才有:没有这种效果的帧没有附件,也不编译变体。
+目前写它的是内置的 **Model** 着色器——导入的 glTF 材质变成的就是它——粗糙度、金属度和法线贴图都按材质所说。没有材质的网格、精灵、
+混合表面和自定义着色器都留 0,效果必须把它当"未知"并回退,`ssr` 就是这样做的。你自己的着色器也可以写它:当 pass 有这个附件时,
+编译会定义 `ES_GBUFFER`,然后声明第二个输出(`layout(location = 1) out vec4`,WGSL 里是返回结构体)并按同样的编码写入。
+
+在 WebGL2 和 WebGPU 上,附件都与场景一起多重采样、一起解析。混合绘制从不写它——与背后那个平均过的法线谁也不是——场景自己的背景把它清成 0。
+
### 雾与大气
`heightFog` 是随高度变薄的雾:山谷被填满,山顶是清朗的。它的密度按指数下降,所以射线穿过多少雾有
@@ -93,9 +106,11 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
刚好后面的一步算命中。找到的颜色按 Schlick 菲涅尔项混到像素上:正对时很弱,掠射时很强,所以地面
越靠近地平线越亮。命中越远越模糊,这代替了粗糙度。
-链路里没有任何东西知道材质的粗糙度,所以由 `floorBias` 决定谁可以反射:为 1 时只有朝上的表面反射,
-为 0 时每个表面仅按菲涅尔项反射。它看不到屏幕外、被别的物体挡住的或天空里的东西——那里像素保持
-原样,所以它叠在环境自身的高光之上而不是取代它。`maxDistance` 是世界长度;步数固定,所以距离越长
+表面是什么来自 [G-buffer](#g-buffer):场景写了记录的地方,反射用表面自己的法线(法线贴图的细节,深度看不到)、粗糙度和金属度。
+粗糙的表面反射暗而模糊,比 `maxRoughness` 更粗糙的表面在步进射线之前就被跳过,这是大头开销;金属几乎全部反射
+所得的光,而电介质正对时只反射 4%。`wetness` 让地面变光滑(水膜填满了孔隙),所以越湿越反光,水坑是镜子。没有写记录的地方——没有材质的网格、
+精灵——用深度法线,表面按中等电介质对待,由 `floorBias` 决定谁可以反射:为 1 时只有朝上的表面反射,为 0 时每个表面仅按菲涅尔项反射。
+它看不到屏幕外、被别的物体挡住的或天空里的东西——那里像素保持原样,所以它叠在环境自身的高光之上而不是取代它。`maxDistance` 是世界长度;步数固定,所以距离越长
步进越粗,而用来藏起条带的逐像素起始偏移要靠 `taa` 平均掉——两者配合使用。
### 时间性抗锯齿
diff --git a/sdk/src/postprocess/PostProcessAPI.ts b/sdk/src/postprocess/PostProcessAPI.ts
index aa2c8d26d..3c9acb4f3 100644
--- a/sdk/src/postprocess/PostProcessAPI.ts
+++ b/sdk/src/postprocess/PostProcessAPI.ts
@@ -208,7 +208,11 @@ export class PostProcessAPI {
private allowQualityPass_ = (name: string): boolean => {
const q = this.qualityFilter_;
- return q === null || (q.postProcess && (q.ssao || !name.toLowerCase().startsWith('ssao')));
+ if (q === null) return true;
+ if (!q.postProcess) return false;
+ const lower = name.toLowerCase();
+ if (!q.ssao && lower.startsWith('ssao')) return false;
+ return !q.skipEffects.some((skipped) => lower.startsWith(skipped.toLowerCase()));
};
// -- per-App state (stacks / bindings / screen stack) --------------------
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index 557407b53..b126772b0 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -375,6 +375,10 @@ registerEffect({
// and the pools it darkens are the pools that reflect.
{ name: 'u_puddles', label: 'Puddles', min: 0, max: 1, step: 0.01, defaultValue: 0, neutralValue: 0 },
{ name: 'u_puddleScale', label: 'Puddle Size', min: 40, max: 2000, step: 10, defaultValue: 350 },
+ // Surfaces rougher than this reflect nothing and cost nothing: the ray is never marched for them.
+ { name: 'u_maxRoughness', label: 'Max Roughness', min: 0.05, max: 1, step: 0.01, defaultValue: 0.75 },
+ // How wet the ground is: wet is smoother, so it reflects. Give it the Rain effect's wetness.
+ { name: 'u_wetness', label: 'Wetness', min: 0, max: 1, step: 0.01, defaultValue: 0, neutralValue: 0 },
],
});
diff --git a/sdk/src/postprocess/postProcessEffects.ts b/sdk/src/postprocess/postProcessEffects.ts
index 2c539de83..cb3cf02a4 100644
--- a/sdk/src/postprocess/postProcessEffects.ts
+++ b/sdk/src/postprocess/postProcessEffects.ts
@@ -111,6 +111,44 @@ fn puddleMask(xz : vec2f, coverage : f32, scale : f32) -> f32 {
return smoothstep(t - 0.03, t + 0.03, n);
}`;
+/**
+ * Reading the scene's surface record, in both languages: what each pixel IS, as the scene's own shaders
+ * wrote it beside the colour — octahedral normal in rg, roughness in b, metalness in a (a is 0 where nothing
+ * wrote, and 0.25 + 0.75 * metalness where something did). An effect that wants it says `#pragma gbuffer`,
+ * which is what makes the frame draw one, and finds it at `u_gbuffer`.
+ */
+const GBUFFER_GLSL = `
+struct Surface { vec3 normal; float roughness; float metallic; bool known; };
+Surface readSurface(ivec2 t) {
+ vec4 g = texelFetch(u_gbuffer, t, 0);
+ Surface s;
+ s.known = g.a > 0.01;
+ vec2 f = g.rg * 2.0 - 1.0;
+ vec3 n = vec3(f.x, f.y, 1.0 - abs(f.x) - abs(f.y));
+ float k = clamp(-n.z, 0.0, 1.0);
+ n.xy += vec2(n.x >= 0.0 ? -k : k, n.y >= 0.0 ? -k : k);
+ s.normal = normalize(n);
+ s.roughness = g.b;
+ s.metallic = clamp((g.a - 0.25) / 0.75, 0.0, 1.0);
+ return s;
+}`;
+
+const GBUFFER_WGSL = `
+struct Surface { normal : vec3f, roughness : f32, metallic : f32, known : bool };
+fn readSurface(t : vec2i) -> Surface {
+ let g = textureLoad(t6, t, 0);
+ var f = g.rg * 2.0 - 1.0;
+ var n = vec3f(f.x, f.y, 1.0 - abs(f.x) - abs(f.y));
+ let k = clamp(-n.z, 0.0, 1.0);
+ n = vec3f(n.x + select(k, -k, n.x >= 0.0), n.y + select(k, -k, n.y >= 0.0), n.z);
+ var s : Surface;
+ s.known = g.a > 0.01;
+ s.normal = normalize(n);
+ s.roughness = g.b;
+ s.metallic = clamp((g.a - 0.25) / 0.75, 0.0, 1.0);
+ return s;
+}`;
+
export const postProcessEffects = {
createLutGrade(): ShaderHandle {
// True LUT color grading: a 2D-packed 32^3 LUT (1024x32 — 32 slices of
@@ -370,6 +408,9 @@ fn project(P : vec3f) -> vec3f {
#pragma param u_floorBias float default(1) range(0,1)
#pragma param u_puddles float default(0) range(0,1)
#pragma param u_puddleScale float default(350) range(40,2000)
+#pragma param u_maxRoughness float default(0.75) range(0.05,1)
+#pragma param u_wetness float default(0) range(0,1)
+#pragma gbuffer
#pragma fragment
precision highp float;
@@ -377,10 +418,12 @@ precision highp float;
in vec2 v_texCoord;
uniform sampler2D u_texture;
uniform highp sampler2D u_sceneDepth;
+uniform highp sampler2D u_gbuffer;
out vec4 fragColor;
${SSAO_GLSL}
${PUDDLE_GLSL}
+${GBUFFER_GLSL}
${GLSL}
void main() {
@@ -407,21 +450,44 @@ void main() {
vec3 V = viewDirection(P);
if (dot(N, V) < 0.0) N = -N;
+ // What the surface is, where the scene wrote it: its own normal (a normal map's detail, which depth
+ // cannot see), how rough it is and whether it is metal. Where nothing wrote — a sprite, a draw
+ // with a shader that has no record to give — the depth normal stands, and the surface is taken
+ // for a middling dielectric, which is what reflecting it by Fresnel alone has always assumed.
+ Surface sf = readSurface(c);
+ float rough = 0.5;
+ float metal = 0.0;
+ if (sf.known) {
+ N = sf.normal;
+ if (dot(N, V) < 0.0) N = -N;
+ rough = sf.roughness;
+ metal = sf.metallic;
+ }
+
// Standing water is flat and mirror-like whatever the ground under it is: its normal is
// straight up, and a still surface reflects far more than the 4% a dry one does.
+ float flatUp = smoothstep(0.86, 0.95, N.y);
float puddle = 0.0;
if (u_puddles > 0.0) {
- puddle = puddleMask(P.xz, u_puddles, u_puddleScale) * smoothstep(0.86, 0.95, N.y);
+ puddle = puddleMask(P.xz, u_puddles, u_puddleScale) * flatUp;
N = normalize(mix(N, vec3(0.0, 1.0, 0.0), puddle));
}
-
- // Fresnel at this angle, Schlick with the dielectric 4% a surface without a metal in
- // it reflects face-on; and the floor mask that keeps walls from shining.
+ // Wet ground is smoother than dry: a film of water fills the pores a rough surface scatters from.
+ rough = mix(rough, rough * 0.35, u_wetness * flatUp);
+ rough = mix(rough, 0.04, puddle);
+ // Too rough to show anything: skipped before the march, which is the whole cost.
+ if (sf.known && rough > u_maxRoughness) { fragColor = scene; return; }
+
+ // Fresnel at this angle, Schlick from the surface's own reflectance face-on: a dielectric's 4%, a
+ // metal's near-all. The floor mask keeps a surface nobody described from shining on every wall.
float cosT = clamp(dot(N, V), 0.0, 1.0);
- float fresnel = 0.04 + 0.96 * pow(1.0 - cosT, 5.0);
+ float f0 = mix(0.04, 0.9, metal);
+ float fresnel = f0 + (1.0 - f0) * pow(1.0 - cosT, 5.0);
fresnel = mix(fresnel, max(fresnel, 0.55), puddle);
- float up = mix(1.0, smoothstep(0.55, 0.9, N.y), u_floorBias);
- float weight = fresnel * up * u_intensity;
+ // A rough surface's reflection is spread over the lobe and dimmer for it.
+ float gloss = sf.known ? (1.0 - rough) * (1.0 - rough) : 1.0;
+ float up = sf.known ? 1.0 : mix(1.0, smoothstep(0.55, 0.9, N.y), u_floorBias);
+ float weight = fresnel * up * gloss * u_intensity;
if (weight < 0.002) { fragColor = scene; return; }
vec3 R = reflect(-V, N);
@@ -463,7 +529,8 @@ void main() {
vec2 e = min(sh.xy, 1.0 - sh.xy);
float edge = smoothstep(0.0, 0.1, min(e.x, e.y));
// A farther hit is a rougher reflection: blur it by how far it is.
- float blur = (length(b - P) / max(u_maxDistance, 1.0)) * 6.0 * (1.0 - 0.85 * puddle);
+ // Wider with the surface's own roughness, and with how far the ray went.
+ float blur = ((length(b - P) / max(u_maxDistance, 1.0)) * 6.0 + rough * 10.0) * (1.0 - 0.85 * puddle);
vec2 texel = 1.0 / vec2(textureSize(u_texture, 0));
vec3 col = texture(u_texture, sh.xy).rgb * 0.4;
col += texture(u_texture, sh.xy + vec2( blur, 0.0) * texel).rgb * 0.15;
@@ -484,6 +551,7 @@ void main() {
#pragma fragment wgsl
${SSAO_WGSL}
${PUDDLE_WGSL}
+${GBUFFER_WGSL}
${WGSL}
@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
@@ -508,17 +576,35 @@ ${WGSL}
let V = viewDirection(P);
if (dot(N, V) < 0.0) { N = -N; }
+ let sf = readSurface(c);
+ var rough = 0.5;
+ var metal = 0.0;
+ if (sf.known) {
+ N = sf.normal;
+ if (dot(N, V) < 0.0) { N = -N; }
+ rough = sf.roughness;
+ metal = sf.metallic;
+ }
+
+ let flatUp = smoothstep(0.86, 0.95, N.y);
var puddle = 0.0;
if (mc.u_puddles > 0.0) {
- puddle = puddleMask(P.xz, mc.u_puddles, mc.u_puddleScale) * smoothstep(0.86, 0.95, N.y);
+ puddle = puddleMask(P.xz, mc.u_puddles, mc.u_puddleScale) * flatUp;
N = normalize(mix(N, vec3f(0.0, 1.0, 0.0), puddle));
}
+ rough = mix(rough, rough * 0.35, mc.u_wetness * flatUp);
+ rough = mix(rough, 0.04, puddle);
+ if (sf.known && rough > mc.u_maxRoughness) { return scene; }
let cosT = clamp(dot(N, V), 0.0, 1.0);
- var fresnel = 0.04 + 0.96 * pow(1.0 - cosT, 5.0);
+ let f0 = mix(0.04, 0.9, metal);
+ var fresnel = f0 + (1.0 - f0) * pow(1.0 - cosT, 5.0);
fresnel = mix(fresnel, max(fresnel, 0.55), puddle);
- let up = mix(1.0, smoothstep(0.55, 0.9, N.y), mc.u_floorBias);
- let weight = fresnel * up * mc.u_intensity;
+ var gloss = 1.0;
+ if (sf.known) { gloss = (1.0 - rough) * (1.0 - rough); }
+ var up = 1.0;
+ if (!sf.known) { up = mix(1.0, smoothstep(0.55, 0.9, N.y), mc.u_floorBias); }
+ let weight = fresnel * up * gloss * mc.u_intensity;
if (weight < 0.002) { return scene; }
let R = reflect(-V, N);
@@ -556,7 +642,7 @@ ${WGSL}
let e = min(sh.xy, vec2f(1.0) - sh.xy);
let edge = smoothstep(0.0, 0.1, min(e.x, e.y));
let travelled = length(b - P);
- let blur = (travelled / max(mc.u_maxDistance, 1.0)) * 6.0 * (1.0 - 0.85 * puddle);
+ let blur = ((travelled / max(mc.u_maxDistance, 1.0)) * 6.0 + rough * 10.0) * (1.0 - 0.85 * puddle);
let texel = 1.0 / vec2f(vec2i(textureDimensions(t0, 0)));
var col = textureSampleLevel(t0, s0, sh.xy, 0.0).rgb * 0.4;
col = col + textureSampleLevel(t0, s0, sh.xy + vec2f( blur, 0.0) * texel, 0.0).rgb * 0.15;
diff --git a/sdk/src/render/builtinShaders.ts b/sdk/src/render/builtinShaders.ts
index a6d9b607f..8debd6269 100644
--- a/sdk/src/render/builtinShaders.ts
+++ b/sdk/src/render/builtinShaders.ts
@@ -379,7 +379,23 @@ in highp vec3 v_worldXYZ;
// engine injects and a bake.
uniform sampler2D u_textures[1];
+#ifdef ES_GBUFFER
+// The frame draws a second attachment beside the colour: what this surface IS, for the post effects
+// that need to know (reflections: how rough, how metal, which way it faces). Only a pass that has the
+// attachment asks for this variant.
+layout(location = 0) out vec4 fragColor;
+layout(location = 1) out vec4 fragSurface;
+
+// Octahedral normal: a unit vector in two channels, which is what an 8-bit target can hold.
+vec2 packNormal(vec3 n) {
+ n /= (abs(n.x) + abs(n.y) + abs(n.z));
+ vec2 sgn = vec2(n.x >= 0.0 ? 1.0 : -1.0, n.y >= 0.0 ? 1.0 : -1.0);
+ vec2 e = n.z >= 0.0 ? n.xy : (1.0 - abs(n.yx)) * sgn;
+ return e * 0.5 + 0.5;
+}
+#else
out vec4 fragColor;
+#endif
// Geometric specular anti-aliasing (Tokuyoshi & Kaplanyan 2019, as Filament spells it).
// Where the vertex normal turns quickly across a pixel — a bevel, a curved rail, a
@@ -439,6 +455,10 @@ void main() {
vec3 lit = applyLightingPBR(base.rgb, N, P, viewDirection(P),
u_metallic * mr.b, roughness, 1.0, ao);
fragColor = vec4(lit + u_emissive.rgb * texture(u_emissiveMap, v_texCoord).rgb, alpha);
+#ifdef ES_GBUFFER
+ // Alpha says something was drawn here (0 is "nothing wrote"), and carries the metalness above a floor.
+ fragSurface = vec4(packNormal(normalize(N)), roughness, 0.25 + 0.75 * clamp(u_metallic * mr.b, 0.0, 1.0));
+#endif
}
#pragma end
@@ -451,7 +471,25 @@ fn specularAA(dndx : vec3f, dndy : vec3f, roughness : f32) -> f32 {
return sqrt(sqrt(clamp(alpha * alpha + kernel, 0.0, 1.0)));
}
+#ifdef ES_GBUFFER
+// What the frame's second attachment takes, beside the colour (see the GLSL twin).
+struct FragOut {
+ @location(0) color : vec4f,
+ @location(1) surface : vec4f,
+};
+
+fn packNormal(n : vec3f) -> vec2f {
+ let a = n / (abs(n.x) + abs(n.y) + abs(n.z));
+ let sgn = vec2f(select(-1.0, 1.0, a.x >= 0.0), select(-1.0, 1.0, a.y >= 0.0));
+ var e = a.xy;
+ if (a.z < 0.0) { e = (vec2f(1.0) - abs(a.yx)) * sgn; }
+ return e * 0.5 + 0.5;
+}
+
+@fragment fn fs_main(v : VSOut, @builtin(front_facing) front : bool) -> FragOut {
+#else
@fragment fn fs_main(v : VSOut, @builtin(front_facing) front : bool) -> @location(0) vec4f {
+#endif
// Taken before any branch: a derivative needs every fragment of its quad.
let duvx = dpdx(v.v_texCoord);
let duvy = dpdy(v.v_texCoord);
@@ -498,7 +536,14 @@ fn specularAA(dndx : vec3f, dndy : vec3f, roughness : f32) -> f32 {
mc.u_metallic * mr.b, roughness, 1.0, ao);
let emit = mc.u_emissive.rgb
* textureSampleGrad(u_emissiveMap, u_emissiveMap_s, v.v_texCoord, duvx, duvy).rgb;
+#ifdef ES_GBUFFER
+ var frag : FragOut;
+ frag.color = vec4f(lit + emit, alpha);
+ frag.surface = vec4f(packNormal(normalize(N)), roughness, 0.25 + 0.75 * clamp(mc.u_metallic * mr.b, 0.0, 1.0));
+ return frag;
+#else
return vec4f(lit + emit, alpha);
+#endif
}
#pragma end
`;
diff --git a/sdk/src/render/quality.ts b/sdk/src/render/quality.ts
index fc3d36c26..c7e0d7c89 100644
--- a/sdk/src/render/quality.ts
+++ b/sdk/src/render/quality.ts
@@ -26,6 +26,13 @@ export interface QualityProfile {
planarReflectionUpdatesPerSecond: number;
postProcess: boolean;
ssao: boolean;
+ /**
+ * Post-process effects this level leaves out, each named by what its passes' names start with
+ * (`ssr`, `taa`, `depthOfField`, `lightShafts` …), compared without regard to case. The expensive ones are
+ * the ones a weak device has no use for: they are measured per effect (`fx-cost` in the editor checks), and
+ * what a level skips follows from what a frame on that device can afford.
+ */
+ skipEffects: readonly string[];
}
export interface DeviceQualityRule {
@@ -52,18 +59,21 @@ const PROFILES: Record<QualityLevel, QualityProfile> = {
shadowAtlasSize: 1024, shadowCellSize: 256, shadowCascades: 2,
planarReflectionScale: 0.25, planarReflectionMaxSize: 512, planarReflectionUpdatesPerSecond: 0,
shadowDistance: 0, particleLimit: 1000, postProcess: true, ssao: false,
+ skipEffects: ['ssr', 'taa', 'depthOfField', 'lightShafts'],
},
medium: {
renderScale: 1, minRenderScale: 0.65, msaaSamples: 2,
shadowAtlasSize: 2048, shadowCellSize: 512, shadowCascades: 3,
planarReflectionScale: 0.5, planarReflectionMaxSize: 1024, planarReflectionUpdatesPerSecond: 0,
shadowDistance: 0, particleLimit: 5000, postProcess: true, ssao: true,
+ skipEffects: ['ssr', 'depthOfField'],
},
high: {
renderScale: 1, minRenderScale: 0.75, msaaSamples: 4,
shadowAtlasSize: 2048, shadowCellSize: 512, shadowCascades: 4,
planarReflectionScale: 1, planarReflectionMaxSize: 2048, planarReflectionUpdatesPerSecond: 0,
shadowDistance: 0, particleLimit: 20000, postProcess: true, ssao: true,
+ skipEffects: [],
},
};
@@ -136,6 +146,10 @@ function resolveProfile(level: QualityLevel, value: unknown): QualityProfile {
planarReflectionUpdatesPerSecond: finite(r.planarReflectionUpdatesPerSecond, base.planarReflectionUpdatesPerSecond, 0, 120),
postProcess: typeof r.postProcess === 'boolean' ? r.postProcess : base.postProcess,
ssao: typeof r.ssao === 'boolean' ? r.ssao : base.ssao,
+ skipEffects: Array.isArray(r.skipEffects)
+ ? r.skipEffects.filter((e): e is string => typeof e === 'string' && e.trim() !== '')
+ .map((e) => e.trim()).slice(0, 32)
+ : base.skipEffects,
};
}
diff --git a/sdk/tests/quality.test.ts b/sdk/tests/quality.test.ts
index 79c7d079c..278d1f34e 100644
--- a/sdk/tests/quality.test.ts
+++ b/sdk/tests/quality.test.ts
@@ -90,6 +90,20 @@ describe('dynamic resolution', () => {
expect(q.renderScale).toBeLessThanOrEqual(1);
});
+ it('says which post-process effects each level leaves out, and takes an override', () => {
+ const levels = (config: object, level: 'low' | 'medium' | 'high') => {
+ const q = new QualityController({ mode: level, ...config });
+ return q.profile.skipEffects;
+ };
+ // The expensive effects are left to the devices that can afford them.
+ expect(levels({}, 'low')).toContain('ssr');
+ expect(levels({}, 'medium')).toContain('ssr');
+ expect(levels({}, 'high')).toEqual([]);
+ // A project's own list replaces the level's, and what is not a name is dropped.
+ expect(levels({ profiles: { low: { skipEffects: ['Bloom', 7, ' ', null, 'ssr'] } } }, 'low'))
+ .toEqual(['Bloom', 'ssr']);
+ });
+
it('does not react to background gaps, invalid clocks or a static tier', () => {
const q = make();
for (const ms of [NaN, Infinity, 0, -5, 30000]) q.sample(ms);
diff --git a/src/esengine/bindings/MaterialBindings.cpp b/src/esengine/bindings/MaterialBindings.cpp
index 6f1477d07..2af997aed 100644
--- a/src/esengine/bindings/MaterialBindings.cpp
+++ b/src/esengine/bindings/MaterialBindings.cpp
@@ -47,6 +47,7 @@ static MaterialUniformLayout buildMaterialLayout(const resource::ParsedShader& p
MaterialUniformLayout layout;
layout.blockSize = parsed.materialBlockSize;
layout.coverageParam = parsed.coverageParam;
+ layout.usesGBuffer = parsed.usesGBuffer;
layout.vertexBounds = parsed.vertexBounds;
layout.vertexHook = !parsed.vertexHook.empty();
for (const auto& p : parsed.properties) {
diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hpp
index ba1248b2c..03dc55938 100644
--- a/src/esengine/renderer/RenderTypePlugin.hpp
+++ b/src/esengine/renderer/RenderTypePlugin.hpp
@@ -69,6 +69,9 @@ struct RenderFrameContext {
u32 shadow_texture_id = 0;
/// The frame environment's prefiltered reflection atlas (0 = none this frame).
u32 environment_texture_id = 0;
+ /// The pass these draws execute in has a second colour attachment for the surface's material, so a
+ /// shader that can write it is asked for the variant that does. False for every other collect.
+ bool gbuffer = false;
};
/** @brief What every plugin needs to know about the camera, derived once per collect
diff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cpp
index a5cda0724..64a544b1e 100644
--- a/src/esengine/renderer/draw/DrawList.cpp
+++ b/src/esengine/renderer/draw/DrawList.cpp
@@ -399,6 +399,9 @@ void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,
desc.depthBias = cmd.depth_bias;
desc.topology = cmd.topology;
desc.alphaToCoverage = !desc.blendEnabled && materials.alphaIsCoverage(cmd.material_id);
+ // What a surface is is recorded only for what replaces what was behind it: a blended
+ // surface is no one thing, and a normal averaged with the one under it is neither's.
+ desc.gbuffer = gbuffer_pass_ && !desc.blendEnabled && materials.programWritesGBuffer(cmd.shader_id);
if (lastHandle == PipelineHandle::Invalid || !(desc == lastDesc)) {
lastHandle = device.createPipeline(desc);
diff --git a/src/esengine/renderer/draw/DrawList.hpp b/src/esengine/renderer/draw/DrawList.hpp
index b987fd5d1..ca1439463 100644
--- a/src/esengine/renderer/draw/DrawList.hpp
+++ b/src/esengine/renderer/draw/DrawList.hpp
@@ -36,6 +36,11 @@ public:
/// merge spends slots) and reserved top-down, so a sampler's unit never moves.
void reserveMask2DSlots(u32 count) { mask_2d_slots_ = std::min(count, MAX_CMD_TEXTURE_SLOTS); }
+ /// The pass this list is about to execute into carries a second colour attachment, so the draws
+ /// whose shaders write it say so in their pipelines. Set for the scene pass and cleared after:
+ /// the same list is executed into other targets, which have no second output to take.
+ void setGBufferPass(bool on) { gbuffer_pass_ = on; }
+
/// A mask itself, which every draw then binds on its unit. Zero leaves the unit
/// filled with white — "nothing shadows anything", and "the shape covers all".
void setMask2DTexture(u32 unit, u32 textureId) {
@@ -231,6 +236,7 @@ private:
/// @see setMask2DTexture — indexed by texture unit, 0 where that unit is not a mask.
u32 mask_2d_textures_[MAX_CMD_TEXTURE_SLOTS] = {};
/// @see reserveMask2DSlots
+ bool gbuffer_pass_ = false;
u32 mask_2d_slots_ = 0;
u32 merged_draw_calls_ = 0;
u32 merged_away_ = 0;
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index d45e13ef4..ff734dac1 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp
@@ -297,6 +297,16 @@ u64 PostProcessPipeline::feedbackKey(const std::string& passName) const {
return temporalKey_ * 1000003ull + std::hash<std::string>{}(passName);
}
+bool PostProcessPipeline::passesWantGBuffer() {
+ if (bypass_) return false;
+ for (const auto& pass : passes_) {
+ if (!pass.enabled) continue;
+ const MaterialUniformLayout* layout = context_.materials().layoutFor(pass.shader);
+ if (layout && layout->usesGBuffer) return true;
+ }
+ return false;
+}
+
bool PostProcessPipeline::temporalActive() {
if (!initialized_ || bypass_) return false;
for (const auto& pass : passes_) {
@@ -495,6 +505,10 @@ void PostProcessPipeline::begin(const f32* clearColor) {
// Every other target in the chain is a fullscreen pass and stays at one
// sample. Gate: check-postfx-aa.
sceneDesc.samples = scene_samples_;
+ // The surface record needs the scene's depth to test against and to be read beside, so a frame
+ // with no depth has no use for one.
+ scene_gbuffer_ = scene_needs_depth_ && passesWantGBuffer();
+ sceneDesc.gbuffer = scene_gbuffer_;
sceneResource_ = graph_->createExternalTarget(sceneDesc);
if (sceneResource_ == rg::kNoResource) {
ES_LOG_ERROR("PostProcessPipeline: no scene target this frame");
@@ -560,6 +574,9 @@ void PostProcessPipeline::renderPass(PostProcessPass& pass, const rg::PassContex
if (shader->hasUniform("u_sceneDepth")) {
shader->setUniform("u_sceneDepth", static_cast<i32>(kSceneDepthUnit));
}
+ if (shader->hasUniform("u_gbuffer")) {
+ shader->setUniform("u_gbuffer", static_cast<i32>(kGBufferUnit));
+ }
}
// #pragma-param effects: params ride the reflected MaterialConstants block
@@ -626,6 +643,9 @@ void PostProcessPipeline::renderPass(PostProcessPass& pass, const rg::PassContex
// wrote none then finds no edge — the right answer for a flat one.
device->bindTexture(kSceneDepthUnit, graph_ ? graph_->depthTextureOf(sceneResource_)
: TextureHandle::Invalid);
+ // And the surface record, on the unit below it, on the same terms: nothing where the frame drew none.
+ device->bindTexture(kGBufferUnit, graph_ && scene_gbuffer_ ? graph_->gbufferTextureOf(sceneResource_)
+ : TextureHandle::Invalid);
// Texture params (LUTs, masks) bind at their reflected material units;
// an unset param gets its declared default (white/black/flatnormal).
@@ -653,7 +673,7 @@ void PostProcessPipeline::renderPass(PostProcessPass& pass, const rg::PassContex
for (const auto& [name, glId] : pass.textureUniforms) {
// Stops below the scene-depth unit rather than walking into it: a
// sixth loose texture would otherwise take the binding depth is on.
- if (extraUnit >= kSceneDepthUnit) break;
+ if (extraUnit >= kGBufferUnit) break;
if (glId != 0 && shader->hasUniform(name)) {
device->bindTexture(extraUnit, TextureHandle{glId});
shader->setUniform(name, static_cast<i32>(extraUnit));
@@ -739,7 +759,7 @@ void PostProcessPipeline::runChain(std::vector<PostProcessPass>& passes, rg::Res
// Every pass samples the scene's depth, so the scene target has to outlive
// the last pass that reads its colour: returned to the pool any earlier,
// an SSAO behind a colour grade found no depth and occluded nothing.
- if (scene_needs_depth_) node.dependencies = {scene};
+ if (scene_needs_depth_ || scene_gbuffer_) node.dependencies = {scene};
// The last pass feeds the blit, which copies into the output rect at the
// chain's size — so it draws full-size whatever fraction it asked for.
rg::TargetDesc writeDesc = (i == lastEnabled) ? blitDesc : desc;
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hpp
index 6f1f7d141..32f6d4f5f 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp
@@ -220,6 +220,16 @@ public:
*/
bool temporalActive();
+ /**
+ * @brief Whether this frame's scene target carries a second attachment for the surface's material.
+ *
+ * @details Decided when the capture opens, from the passes: an effect whose shader says
+ * `#pragma gbuffer` reads what a surface IS (normal, roughness, metalness), which the
+ * scene's own shaders write beside the colour. A frame with no such effect makes none, so
+ * the cost is paid only by the project that asked for it.
+ */
+ bool sceneHasGBuffer() const { return inFrame_ && scene_gbuffer_; }
+
/**
* @brief Starts a frame of the temporal view @p key, and answers how far to shift it.
*
@@ -501,6 +511,9 @@ private:
std::unordered_map<u64, TemporalState> temporal_;
u64 temporalKey_ = 0;
bool passIsTemporal(const PostProcessPass& pass);
+ /// Some enabled pass of the chain reads the surface record.
+ bool passesWantGBuffer();
+ bool scene_gbuffer_ = false;
bool passHasTexture(const PostProcessPass& pass, const char* name);
/// A history made (or kept) at @p w x @p h, or null when it cannot be.
TemporalState* prepareHistory(TemporalState& state, u32 w, u32 h);
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index a2855aaac..ff4286832 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -256,8 +256,12 @@ void RenderFrame::drawScene() {
{
ES_PROFILE_SCOPE("render.submit");
+#ifdef ES_ENABLE_POSTPROCESS
+ draw_list_.setGBufferPass(post_process_ && post_process_->sceneHasGBuffer());
+#endif
draw_list_.execute(device_, pool_, context_.materials(), context_.getWhiteTextureId(),
&frame_capture_, context_.perDrawBlocks());
+ draw_list_.setGBufferPass(false);
}
// Handed over to whatever the graph runs next. Blend/depth/colour-mask come
@@ -765,7 +769,8 @@ void RenderFrame::renderSurface(ecs::Registry& registry, const glm::mat4& viewPr
draw_list_.clear();
clip_state_.clear();
- collectAll(registry);
+ // A preview target is a plain one, whatever the camera's chain is doing.
+ collectAll(registry, /*sceneGBuffer=*/false);
// AFTER the collect, because the clear above would have eaten them. Geometry
// a caller posed itself and handed over, replayed through the one skeletal
@@ -2122,7 +2127,7 @@ RenderPrewarmResult RenderFrame::prewarmDocument(const MeshDocumentRecord* rows,
return out;
}
-void RenderFrame::collectAll(ecs::Registry& registry) {
+void RenderFrame::collectAll(ecs::Registry& registry, bool sceneGBuffer) {
ES_PROFILE_SCOPE("render.collect");
// Split because "collect is expensive" names no mechanism: planning shadows,
// gathering lights and walking one render type's population are different
@@ -2151,6 +2156,13 @@ void RenderFrame::collectAll(ecs::Registry& registry) {
{ ES_PROFILE_SCOPE("render.collect.planar"); declarePlanarReflection(registry); }
auto ctx = makeContext();
+#ifdef ES_ENABLE_POSTPROCESS
+ // Asked at the collect, because it decides which program each material draw is compiled as; the
+ // scene pass that executes them is the one the answer is about.
+ ctx.gbuffer = sceneGBuffer && post_process_ && post_process_->sceneHasGBuffer();
+#else
+ (void)sceneGBuffer;
+#endif
RenderCollectContext collectCtx{registry, frustum_, clip_state_, pool_, draw_list_, ctx,
computeCameraView(ctx.view_projection)};
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index d8c406d23..82fb625c5 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -496,7 +496,7 @@ public:
/** @brief The same readiness, from a prepared cell's own description — no
* entity of it need exist. */
RenderPrewarmResult prewarmDocument(const MeshDocumentRecord* rows, u32 count);
- void collectAll(ecs::Registry& registry);
+ void collectAll(ecs::Registry& registry, bool sceneGBuffer = true);
/**
* @brief Whether the camera being rendered right now would draw something of
diff --git a/src/esengine/renderer/graph/RenderGraph.cpp b/src/esengine/renderer/graph/RenderGraph.cpp
index edb8a5ac0..74af866d4 100644
--- a/src/esengine/renderer/graph/RenderGraph.cpp
+++ b/src/esengine/renderer/graph/RenderGraph.cpp
@@ -143,6 +143,7 @@ TargetHandle RenderGraph::acquire(const Resource& res) {
shape.linearFilter = res.desc.linearFilter;
shape.depthStencil = res.desc.depthStencil;
shape.samples = res.desc.samples;
+ shape.gbuffer = res.desc.gbuffer;
const TargetHandle handle = pool_.acquire(shape);
if (handle != kNoTarget) borrowed_.push_back(handle);
return handle;
@@ -245,6 +246,13 @@ TextureHandle RenderGraph::depthTextureOf(ResourceId id) const {
return pool_.depthTextureOf(res.pooled);
}
+TextureHandle RenderGraph::gbufferTextureOf(ResourceId id) const {
+ if (id >= resources_.size()) return TextureHandle::Invalid;
+ const Resource& res = resources_[id];
+ if (res.kind != Kind::Transient || res.pooled == kNoTarget) return TextureHandle::Invalid;
+ return pool_.gbufferTextureOf(res.pooled);
+}
+
void RenderGraph::releasePool() {
for (auto& res : resources_) {
res.pooled = kNoTarget;
diff --git a/src/esengine/renderer/graph/RenderGraph.hpp b/src/esengine/renderer/graph/RenderGraph.hpp
index 8b5f45729..9a617499b 100644
--- a/src/esengine/renderer/graph/RenderGraph.hpp
+++ b/src/esengine/renderer/graph/RenderGraph.hpp
@@ -64,6 +64,8 @@ struct TargetDesc {
/// Samples to DRAW with. What the target hands back to be sampled stays
/// single-sample either way — the resolve is the target's own business.
u32 samples = 1;
+ /// A second colour attachment for the surface's material, drawn beside the first.
+ bool gbuffer = false;
};
/** What a pass's execute() is told: where it is drawing and what it may read. */
@@ -191,6 +193,9 @@ public:
* import (the graph did not make it) and for a target without depth. */
TextureHandle depthTextureOf(ResourceId id) const;
+ /** Its second colour attachment, for a resource declared with one. Invalid otherwise. */
+ TextureHandle gbufferTextureOf(ResourceId id) const;
+
/** Drops every pooled target. For shutdown and for device loss, after which
* the handles the pool holds name nothing. */
void releasePool();
diff --git a/src/esengine/renderer/graph/TargetPool.cpp b/src/esengine/renderer/graph/TargetPool.cpp
index 0a46f5e74..102b6c22b 100644
--- a/src/esengine/renderer/graph/TargetPool.cpp
+++ b/src/esengine/renderer/graph/TargetPool.cpp
@@ -32,7 +32,7 @@ u64 texelBytes(const TargetShape& shape) {
bool sameShape(const TargetShape& a, const TargetShape& b) {
return a.width == b.width && a.height == b.height && a.format == b.format
&& a.linearFilter == b.linearFilter && a.depthStencil == b.depthStencil
- && a.samples == b.samples;
+ && a.samples == b.samples && a.gbuffer == b.gbuffer;
}
} // namespace
@@ -74,6 +74,7 @@ TargetHandle TargetPool::acquire(const TargetShape& shape) {
spec.linearFilter = shape.linearFilter;
spec.colorFormat = shape.format;
spec.samples = shape.samples;
+ spec.gbuffer = shape.gbuffer;
auto fbo = Framebuffer::create(device_, spec);
if (!fbo) {
ES_LOG_ERROR("TargetPool: failed to create a {}x{} target", shape.width, shape.height);
@@ -128,6 +129,11 @@ TextureHandle TargetPool::depthTextureOf(TargetHandle handle) const {
return entry ? entry->fbo->getDepthAttachment() : TextureHandle::Invalid;
}
+TextureHandle TargetPool::gbufferTextureOf(TargetHandle handle) const {
+ const Entry* entry = resolve(handle);
+ return entry ? entry->fbo->getGBufferAttachment() : TextureHandle::Invalid;
+}
+
void TargetPool::age() {
for (auto& entry : entries_) {
if (!entry.fbo || entry.inUse) continue;
diff --git a/src/esengine/renderer/graph/TargetPool.hpp b/src/esengine/renderer/graph/TargetPool.hpp
index 7e046d442..815e3a902 100644
--- a/src/esengine/renderer/graph/TargetPool.hpp
+++ b/src/esengine/renderer/graph/TargetPool.hpp
@@ -55,6 +55,8 @@ struct TargetShape {
/// Samples the target is DRAWN into with; what it hands back to be sampled
/// is always single-sample, because the target resolves itself.
u32 samples = 1;
+ /// A second colour attachment for the surface's material (see FramebufferSpec::gbuffer).
+ bool gbuffer = false;
};
class TargetPool {
@@ -83,6 +85,8 @@ public:
/** The depth attachment, for a target that has one — an effect reading the
* scene's depth samples this. Invalid when the shape carried no depth. */
TextureHandle depthTextureOf(TargetHandle handle) const;
+ /** Its second colour attachment, Invalid for a target made without one. */
+ TextureHandle gbufferTextureOf(TargetHandle handle) const;
/**
* @brief One tick of the clock every borrowed target is aged against.
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 265d1187f..bc4287b69 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -812,7 +812,8 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
materialProgram = ctx.materials->meshProgram(key.materialId, ctx.resources,
resident->hasNormals, skinned,
key.envTextureId != 0,
- resident->hasLightmapUV);
+ resident->hasLightmapUV,
+ ctx.gbuffer && !shadowDepth);
if (materialProgram == 0) {
if (!warned_material_) {
warned_material_ = true;
diff --git a/src/esengine/renderer/rhi/Framebuffer.cpp b/src/esengine/renderer/rhi/Framebuffer.cpp
index 0d1a21c48..3ffddd8a9 100644
--- a/src/esengine/renderer/rhi/Framebuffer.cpp
+++ b/src/esengine/renderer/rhi/Framebuffer.cpp
@@ -36,7 +36,11 @@ Framebuffer::Framebuffer(Framebuffer&& other) noexcept
colorAttachment_(other.colorAttachment_),
depthAttachment_(other.depthAttachment_),
resolveColor_(other.resolveColor_),
- resolveDepth_(other.resolveDepth_) {
+ resolveDepth_(other.resolveDepth_),
+ colorAttachment1_(other.colorAttachment1_),
+ resolveColor1_(other.resolveColor1_) {
+ other.colorAttachment1_ = TextureHandle::Invalid;
+ other.resolveColor1_ = TextureHandle::Invalid;
other.handle_ = FramebufferHandle::Default;
other.colorAttachment_ = TextureHandle::Invalid;
other.depthAttachment_ = TextureHandle::Invalid;
@@ -54,6 +58,10 @@ Framebuffer& Framebuffer::operator=(Framebuffer&& other) noexcept {
depthAttachment_ = other.depthAttachment_;
resolveColor_ = other.resolveColor_;
resolveDepth_ = other.resolveDepth_;
+ colorAttachment1_ = other.colorAttachment1_;
+ resolveColor1_ = other.resolveColor1_;
+ other.colorAttachment1_ = TextureHandle::Invalid;
+ other.resolveColor1_ = TextureHandle::Invalid;
other.handle_ = FramebufferHandle::Default;
other.colorAttachment_ = TextureHandle::Invalid;
other.depthAttachment_ = TextureHandle::Invalid;
@@ -126,6 +134,21 @@ bool Framebuffer::initialize() {
colorDesc.samples = samples;
colorAttachment_ = device_->createTexture(colorDesc, GfxContent::transient(), nullptr);
+ // The surface's own record: 8 bits a channel is what an octahedral normal, a roughness and a metalness
+ // need, and a float target would spend four times the bandwidth for precision none of them uses.
+ if (spec_.gbuffer) {
+ TextureDesc gDesc = colorDesc;
+ gDesc.format = GfxPixelFormat::RGBA8;
+ // Nearest: a normal or a roughness blended with its neighbour's is neither's.
+ gDesc.minFilter = TextureFilter::Nearest;
+ gDesc.magFilter = TextureFilter::Nearest;
+ colorAttachment1_ = device_->createTexture(gDesc, GfxContent::transient(), nullptr);
+ if (samples > 1) {
+ gDesc.samples = 1;
+ resolveColor1_ = device_->createTexture(gDesc, GfxContent::transient(), nullptr);
+ }
+ }
+
TextureDesc depthDesc;
depthDesc.width = spec_.width;
depthDesc.height = spec_.height;
@@ -152,9 +175,16 @@ bool Framebuffer::initialize() {
}
}
- handle_ = device_->createFramebuffer({colorAttachment_, depthAttachment_,
- resolveColor_, resolveDepth_,
- spec_.width, spec_.height});
+ FramebufferDesc fb;
+ fb.color0 = colorAttachment_;
+ fb.depthStencil = depthAttachment_;
+ fb.resolveColor0 = resolveColor_;
+ fb.resolveDepthStencil = resolveDepth_;
+ fb.color1 = colorAttachment1_;
+ fb.resolveColor1 = resolveColor1_;
+ fb.width = spec_.width;
+ fb.height = spec_.height;
+ handle_ = device_->createFramebuffer(fb);
if (handle_ == FramebufferHandle::Default) {
ES_LOG_ERROR("Framebuffer is incomplete! (size: {}x{}, GL error 0x{:X})",
spec_.width, spec_.height, device_->getError());
@@ -171,6 +201,14 @@ void Framebuffer::cleanup() {
device_->deleteTexture(resolveColor_);
resolveColor_ = TextureHandle::Invalid;
}
+ if (resolveColor1_ != TextureHandle::Invalid) {
+ device_->deleteTexture(resolveColor1_);
+ resolveColor1_ = TextureHandle::Invalid;
+ }
+ if (colorAttachment1_ != TextureHandle::Invalid) {
+ device_->deleteTexture(colorAttachment1_);
+ colorAttachment1_ = TextureHandle::Invalid;
+ }
if (resolveDepth_ != TextureHandle::Invalid) {
device_->deleteTexture(resolveDepth_);
resolveDepth_ = TextureHandle::Invalid;
diff --git a/src/esengine/renderer/rhi/Framebuffer.hpp b/src/esengine/renderer/rhi/Framebuffer.hpp
index 7249252bb..53149a8e4 100644
--- a/src/esengine/renderer/rhi/Framebuffer.hpp
+++ b/src/esengine/renderer/rhi/Framebuffer.hpp
@@ -56,6 +56,8 @@ struct FramebufferSpec {
bool linearFilter = false;
/** @brief Color attachment format. RGBA16F needs GfxDevice::supportsFloatTargets. */
GfxPixelFormat colorFormat = GfxPixelFormat::RGBA8;
+ /** @brief A second colour attachment (RGBA8) drawn in the same pass: the surface's material, for effects that need to know what they are looking at. */
+ bool gbuffer = false;
};
// =============================================================================
@@ -150,6 +152,11 @@ public:
return resolveColor_ != TextureHandle::Invalid ? resolveColor_ : colorAttachment_;
}
+ /** @brief The second colour attachment, resolved like the first (Invalid when the target has none). */
+ TextureHandle getGBufferAttachment() const {
+ return resolveColor1_ != TextureHandle::Invalid ? resolveColor1_ : colorAttachment1_;
+ }
+
/** @brief Gets the depth attachment texture (Invalid if none) */
TextureHandle getDepthAttachment() const {
return resolveDepth_ != TextureHandle::Invalid ? resolveDepth_ : depthAttachment_;
@@ -187,6 +194,9 @@ private:
/// Single-sample twins, non-Invalid only when spec_.samples > 1.
TextureHandle resolveColor_ = TextureHandle::Invalid;
TextureHandle resolveDepth_ = TextureHandle::Invalid;
+ /// The second colour attachment and its single-sample twin (spec_.gbuffer).
+ TextureHandle colorAttachment1_ = TextureHandle::Invalid;
+ TextureHandle resolveColor1_ = TextureHandle::Invalid;
};
} // namespace esengine
diff --git a/src/esengine/renderer/rhi/GLDevice.cpp b/src/esengine/renderer/rhi/GLDevice.cpp
index 21bbd42f2..d5c00e65e 100644
--- a/src/esengine/renderer/rhi/GLDevice.cpp
+++ b/src/esengine/renderer/rhi/GLDevice.cpp
@@ -984,6 +984,8 @@ void GLDevice::backendSetPipeline(u32 id, const PipelineDesc& desc) {
alpha_to_coverage_ = static_cast<i8>(desc.alphaToCoverage);
}
+ if (current_fbo_has_gbuffer_) applyDrawBuffers(desc.gbuffer);
+
current_pipeline_id_ = id;
current_topology_ = desc.topology;
current_stencil_mode_ = desc.stencil;
@@ -1261,6 +1263,7 @@ bool GLDevice::backendCreateFramebuffer(u32 id, const FramebufferDesc& desc) {
};
if (desc.color0 != TextureHandle::Invalid) attach(GL_COLOR_ATTACHMENT0, desc.color0);
+ if (desc.color1 != TextureHandle::Invalid) attach(GL_COLOR_ATTACHMENT1, desc.color1);
if (desc.depthStencil != TextureHandle::Invalid) {
// Attach point follows the texture's pixel format (depth-only vs packed depth+stencil).
attach(depthPoint(desc.depthStencil), desc.depthStencil);
@@ -1282,6 +1285,7 @@ bool GLDevice::backendCreateFramebuffer(u32 id, const FramebufferDesc& desc) {
glGenFramebuffers(1, &dst);
glBindFramebuffer(GL_FRAMEBUFFER, dst);
attach(GL_COLOR_ATTACHMENT0, desc.resolveColor0);
+ if (desc.resolveColor1 != TextureHandle::Invalid) attach(GL_COLOR_ATTACHMENT1, desc.resolveColor1);
if (desc.resolveDepthStencil != TextureHandle::Invalid) {
attach(depthPoint(desc.resolveDepthStencil), desc.resolveDepthStencil);
}
@@ -1289,7 +1293,8 @@ bool GLDevice::backendCreateFramebuffer(u32 id, const FramebufferDesc& desc) {
glBindFramebuffer(GL_FRAMEBUFFER, 0);
if (ok) {
framebuffer_resolve_[id] = {dst, desc.width, desc.height,
- desc.resolveDepthStencil != TextureHandle::Invalid};
+ desc.resolveDepthStencil != TextureHandle::Invalid,
+ desc.resolveColor1 != TextureHandle::Invalid};
} else {
glDeleteFramebuffers(1, &dst);
ES_LOG_ERROR("GLDevice: multisample resolve target incomplete");
@@ -1312,7 +1317,21 @@ void GLDevice::resolveFramebuffer(u32 framebufferId) {
glBindFramebuffer(GL_READ_FRAMEBUFFER, nameOf(framebuffer_names_, framebufferId));
glBindFramebuffer(GL_DRAW_FRAMEBUFFER, r.destFbo);
const GLsizei w = static_cast<GLsizei>(r.width), h = static_cast<GLsizei>(r.height);
- glBlitFramebuffer(0, 0, w, h, 0, 0, w, h, GL_COLOR_BUFFER_BIT, GL_LINEAR);
+ if (r.gbuffer) {
+ // Each attachment on its own: a blit copies the read buffer into every live draw buffer,
+ // and the two are different surfaces.
+ const GLenum only0[2] = {GL_COLOR_ATTACHMENT0, GL_NONE};
+ const GLenum only1[2] = {GL_NONE, GL_COLOR_ATTACHMENT1};
+ glDrawBuffers(2, only0);
+ glBlitFramebuffer(0, 0, w, h, 0, 0, w, h, GL_COLOR_BUFFER_BIT, GL_LINEAR);
+ glReadBuffer(GL_COLOR_ATTACHMENT1);
+ glDrawBuffers(2, only1);
+ // Nearest: a normal or a roughness averaged with its neighbour's is neither's.
+ glBlitFramebuffer(0, 0, w, h, 0, 0, w, h, GL_COLOR_BUFFER_BIT, GL_NEAREST);
+ glReadBuffer(GL_COLOR_ATTACHMENT0);
+ } else {
+ glBlitFramebuffer(0, 0, w, h, 0, 0, w, h, GL_COLOR_BUFFER_BIT, GL_LINEAR);
+ }
if (r.depth) {
// A separate blit: depth and colour cannot share one when the filter
// differs, and depth refuses anything but NEAREST.
@@ -1351,7 +1370,20 @@ void GLDevice::beginRenderPass(const RenderPassDesc& desc) {
if (const FramebufferDesc* fb = framebufferDesc(desc.target)) {
evictSamplerBinding(nameOf(texture_names_, static_cast<u32>(fb->color0)));
evictSamplerBinding(nameOf(texture_names_, static_cast<u32>(fb->depthStencil)));
+ if (fb->color1 != TextureHandle::Invalid) {
+ evictSamplerBinding(nameOf(texture_names_, static_cast<u32>(fb->color1)));
+ }
}
+ // Which draw buffers are live is the framebuffer's own state and a pipeline decides it per draw,
+ // so a pass starts by saying it is not yet known — and the pipeline cache forgets, or a pipeline
+ // left bound by the last pass would skip the call that says it.
+ const FramebufferDesc* passTarget = framebufferDesc(desc.target);
+ const bool hasGBuffer = passTarget && passTarget->color1 != TextureHandle::Invalid;
+ if (hasGBuffer || current_fbo_has_gbuffer_) {
+ current_pipeline_id_ = 0;
+ draw_buffers_ = -1;
+ }
+ current_fbo_has_gbuffer_ = hasGBuffer;
if (!desc.clearColor && !desc.clearDepth && !desc.clearStencil) return;
@@ -1375,13 +1407,33 @@ void GLDevice::beginRenderPass(const RenderPassDesc& desc) {
} else {
setScissorTest(false);
}
+ // The first attachment takes the clear colour (the camera's background); the second records what a
+ // surface is, and the background is not one, so it clears to zero — "nothing wrote here".
+ if (hasGBuffer && desc.clearColor) applyDrawBuffers(false);
clear(desc.clearColor, desc.clearDepth, desc.clearStencil);
+ if (hasGBuffer && desc.clearColor) {
+ applyDrawBuffers(true);
+ const GLfloat zero[4] = {0.0f, 0.0f, 0.0f, 0.0f};
+ glClearBufferfv(GL_COLOR, 1, zero);
+ }
if (scoped) setScissorTest(false);
}
+void GLDevice::applyDrawBuffers(bool gbuffer) {
+ const i8 want = gbuffer ? 1 : 0;
+ if (draw_buffers_ == want) return;
+ // The second slot is NONE for a draw that does not write it, so a shader with one output does not
+ // leave an undefined value in the surface record.
+ const GLenum both[2] = {GL_COLOR_ATTACHMENT0, GL_COLOR_ATTACHMENT1};
+ const GLenum first[2] = {GL_COLOR_ATTACHMENT0, GL_NONE};
+ glDrawBuffers(2, gbuffer ? both : first);
+ draw_buffers_ = want;
+}
+
void GLDevice::endRenderPass() {
resolveFramebuffer(current_framebuffer_);
current_framebuffer_ = 0;
+ current_fbo_has_gbuffer_ = false;
glBindFramebuffer(GL_FRAMEBUFFER, 0);
}
diff --git a/src/esengine/renderer/rhi/GLDevice.hpp b/src/esengine/renderer/rhi/GLDevice.hpp
index a90662325..f8930c272 100644
--- a/src/esengine/renderer/rhi/GLDevice.hpp
+++ b/src/esengine/renderer/rhi/GLDevice.hpp
@@ -228,6 +228,11 @@ private:
u32 bound_texture_[kTextureSlots] = {};
i16 current_depth_bias_ = 0;
i8 alpha_to_coverage_ = -1; ///< -1: unknown, so the next pipeline sets it.
+ /// The framebuffer being drawn into carries a second colour attachment, and which of the two draw
+ /// buffer sets is live: 0 = colour only, 1 = both, -1 = not yet said for this pass.
+ bool current_fbo_has_gbuffer_ = false;
+ i8 draw_buffers_ = -1;
+ void applyDrawBuffers(bool gbuffer);
int scissor_test_ = -1; // tri-state: -1 unknown, 0 disabled, 1 enabled
struct VaoCache {
@@ -252,6 +257,7 @@ private:
u32 width = 0;
u32 height = 0;
bool depth = false;
+ bool gbuffer = false;
};
std::unordered_map<u32, ResolvePair> framebuffer_resolve_;
/// Blit a multisampled target into the single-sample one it owns; no-op for
diff --git a/src/esengine/renderer/rhi/GfxEnums.hpp b/src/esengine/renderer/rhi/GfxEnums.hpp
index 488aea2b0..26e4ac4cd 100644
--- a/src/esengine/renderer/rhi/GfxEnums.hpp
+++ b/src/esengine/renderer/rhi/GfxEnums.hpp
@@ -427,6 +427,12 @@ struct FramebufferDesc {
/// RHI learns the target was multisampled.
TextureHandle resolveColor0 = TextureHandle::Invalid;
TextureHandle resolveDepthStencil = TextureHandle::Invalid;
+ /// A second colour attachment, drawn in the same pass as the first: what the surface IS rather than
+ /// how it looks (normal, roughness, metalness) — see `PipelineDesc::gbuffer`. Invalid for a target
+ /// that carries none, which is nearly all of them.
+ TextureHandle color1 = TextureHandle::Invalid;
+ /// Its single-sample twin, when the target is multisampled.
+ TextureHandle resolveColor1 = TextureHandle::Invalid;
/// Pixel size, required only when resolving: a blit needs a rectangle and an
/// attachment handle carries no dimensions.
u32 width = 0;
diff --git a/src/esengine/renderer/rhi/PipelineState.hpp b/src/esengine/renderer/rhi/PipelineState.hpp
index c33551d4d..7825fc427 100644
--- a/src/esengine/renderer/rhi/PipelineState.hpp
+++ b/src/esengine/renderer/rhi/PipelineState.hpp
@@ -76,6 +76,10 @@ struct PipelineDesc {
/// meaningful on an opaque draw into a multisampled target; ignored elsewhere.
bool alphaToCoverage = false;
GfxTopology topology = GfxTopology::Triangles;
+ /// The shader writes a second colour output (location 1) and the target's second attachment is
+ /// to receive it. A pipeline without it draws into a target that has one and leaves it alone:
+ /// WebGPU wants that said in the pipeline, and GL wants the draw buffers set to match.
+ bool gbuffer = false;
bool operator==(const PipelineDesc&) const = default;
};
diff --git a/src/esengine/renderer/store/MaterialConstants.hpp b/src/esengine/renderer/store/MaterialConstants.hpp
index e6dbd5eaf..3dac32539 100644
--- a/src/esengine/renderer/store/MaterialConstants.hpp
+++ b/src/esengine/renderer/store/MaterialConstants.hpp
@@ -35,4 +35,13 @@ inline constexpr u32 MATERIAL_TEXTURE_UNIT_BASE = 8;
*/
inline constexpr u32 kSceneDepthUnit = 7;
+/**
+ * @brief The unit a PostProcess pass reads the scene's surface record at: what a surface IS —
+ * octahedral normal in rg, roughness in b, metalness in a (0 = nothing wrote here).
+ *
+ * @details Just below the depth, on the same reasoning: the loose-uniform path fills upward from
+ * 2 and stops short of both, and a material's own textures start at 8.
+ */
+inline constexpr u32 kGBufferUnit = 6;
+
} // namespace esengine
diff --git a/src/esengine/renderer/store/MaterialStore.cpp b/src/esengine/renderer/store/MaterialStore.cpp
index cbbe4f348..45b0a6042 100644
--- a/src/esengine/renderer/store/MaterialStore.cpp
+++ b/src/esengine/renderer/store/MaterialStore.cpp
@@ -67,13 +67,21 @@ void MaterialStore::clear() {
u32 MaterialStore::meshProgram(u32 materialId, resource::ResourceManager& resources,
bool withNormals, bool skinned, bool envMapped,
- bool lightmapped) const {
+ bool lightmapped, bool gbuffer) const {
+ // Only for a shader that has something to write: one that never mentions the feature would
+ // compile the same program twice and then be declared to write an output it does not have.
+ if (gbuffer) {
+ const MaterialRecord* rec = find(materialId);
+ const auto src = rec && rec->shaderRef.isValid() ? sources_.find(rec->shaderRef.id()) : sources_.end();
+ gbuffer = src != sources_.end() && src->second.source.find("ES_GBUFFER") != std::string::npos;
+ }
// Keyed by shader AND vertex shape: a layout may not declare an attribute its
// shader ignores, so geometry with normals — or posed by bones — needs its own.
const u64 shape = (withNormals ? (1ull << 32) : 0ull)
| (skinned ? (1ull << 33) : 0ull)
| (envMapped ? (1ull << 34) : 0ull)
- | (lightmapped ? (1ull << 36) : 0ull);
+ | (lightmapped ? (1ull << 36) : 0ull)
+ | (gbuffer ? (1ull << 38) : 0ull);
std::vector<std::string> features{ "MESH" };
if (withNormals) features.push_back("MESH_NORMALS");
if (skinned) features.push_back("SKINNED");
@@ -86,7 +94,10 @@ u32 MaterialStore::meshProgram(u32 materialId, resource::ResourceManager& resour
// As above: this vertex source gives the fragment a real world position, so a
// positional light is read from where it is rather than from the plane.
features.push_back("ES_SURFACE_3D");
- return variantProgram(materialId, resources, shape, features, "resident geometry");
+ if (gbuffer) features.push_back("ES_GBUFFER");
+ const u32 program = variantProgram(materialId, resources, shape, features, "resident geometry");
+ if (gbuffer && program != 0) gbuffer_programs_.insert(program);
+ return program;
}
u32 MaterialStore::shadowProgram(u32 materialId, resource::ResourceManager& resources,
diff --git a/src/esengine/renderer/store/MaterialStore.hpp b/src/esengine/renderer/store/MaterialStore.hpp
index c7cde7d2b..0705fb25f 100644
--- a/src/esengine/renderer/store/MaterialStore.hpp
+++ b/src/esengine/renderer/store/MaterialStore.hpp
@@ -31,6 +31,7 @@
#include <cstring>
#include <string>
#include <unordered_map>
+#include <unordered_set>
#include <vector>
namespace esengine {
@@ -91,6 +92,8 @@ struct MaterialUniformLayout {
/// The param whose value above zero makes output alpha coverage (see
/// ParsedShader::coverageParam); empty when the shader declares none.
std::string coverageParam;
+ /// The shader reads the scene's surface record (ParsedShader::usesGBuffer).
+ bool usesGBuffer = false;
/// What the shader's vertex hook can move a vertex by (ParsedShader::vertexBounds), and whether it
/// has a hook at all — culling grows a mesh's box by the first, and the shadow pass builds a
/// program of its own for the second.
@@ -188,7 +191,14 @@ public:
/// caller falls back rather than drawing it wrong.
u32 meshProgram(u32 materialId, resource::ResourceManager& resources,
bool withNormals = false, bool skinned = false,
- bool envMapped = false, bool lightmapped = false) const;
+ bool envMapped = false, bool lightmapped = false, bool gbuffer = false) const;
+
+ /// Whether @p programId is a variant that writes the surface record's second output — set when
+ /// it was compiled for a pass that has one AND the material's shader has something to write
+ /// (it mentions ES_GBUFFER). The draw list asks per command, so a pipeline says what its shader does.
+ bool programWritesGBuffer(u32 programId) const {
+ return gbuffer_programs_.count(programId) != 0;
+ }
/// How far @p materialId's vertex hook can move a vertex from the mesh's own bounds, in the
/// mesh's local units; 0 for a material without one.
@@ -350,6 +360,8 @@ private:
// Indexed first by source shader: retirement touches only its own variants.
// Handles resolve to the current device program, including after recovery.
mutable std::unordered_map<u32, std::unordered_map<u64, resource::ShaderHandle>> mesh_programs_;
+ /// Programs compiled with ES_GBUFFER (see programWritesGBuffer).
+ mutable std::unordered_set<u32> gbuffer_programs_;
public:
/** @brief How many material program variants have been built. A prewarm counts
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
index a4975f6a6..0d4a2af52 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
@@ -1241,11 +1241,14 @@ WGPURenderPipeline WebGPUDevice::ensurePipeline(u32 id) {
if (!described || !device_) return nullptr;
PipelineRec& built = pipelines_[id];
const u32 dsVariant = dsVariantOf(pass_ds_format_);
- const u32 variant = (dsVariant * kColorVariantCount + colorVariantOf(pass_color_format_))
- * kSampleVariantCount + (pass_samples_ > 1 ? kMultiSample : kSingleSample);
+ const PipelineDesc& desc = *described;
+ const u32 gbufferVariant = !pass_gbuffer_ ? kGBufferNone
+ : desc.gbuffer ? kGBufferWrites : kGBufferSkips;
+ const u32 variant = ((dsVariant * kColorVariantCount + colorVariantOf(pass_color_format_))
+ * kSampleVariantCount + (pass_samples_ > 1 ? kMultiSample : kSingleSample))
+ * kGBufferVariantCount + gbufferVariant;
if (built.variants[variant]) return built.variants[variant];
- const PipelineDesc& desc = *described;
auto progIt = programs_.find(static_cast<u32>(desc.program));
const VertexLayoutDesc* layout = vertexLayoutDesc(desc.vertexLayout);
if (progIt == programs_.end() || !layout) {
@@ -1283,17 +1286,24 @@ WGPURenderPipeline WebGPUDevice::ensurePipeline(u32 id) {
blendState.color = blend.color;
blendState.alpha = blend.alpha;
- WGPUColorTargetState target{};
- target.format = pass_color_format_;
- target.blend = desc.blendEnabled ? &blendState : nullptr;
- target.writeMask = writesStencil(desc.stencil) ? WGPUColorWriteMask_None
- : WGPUColorWriteMask_All;
+ WGPUColorTargetState targets[2]{};
+ targets[0].format = pass_color_format_;
+ targets[0].blend = desc.blendEnabled ? &blendState : nullptr;
+ targets[0].writeMask = writesStencil(desc.stencil) ? WGPUColorWriteMask_None
+ : WGPUColorWriteMask_All;
+ // The second attachment, when the pass has one: written by a shader that has the output, and
+ // declared with an empty write mask by every other — WebGPU asks the pipeline to account for
+ // every attachment of the pass, and a shader with one output may not be given a mask that
+ // would write the second. Never blended: a normal averaged with what was there is neither's.
+ targets[1].format = WGPUTextureFormat_RGBA8Unorm;
+ targets[1].writeMask = (desc.gbuffer && !writesStencil(desc.stencil)) ? WGPUColorWriteMask_All
+ : WGPUColorWriteMask_None;
WGPUFragmentState fragment{};
fragment.module = progIt->second.fragment;
fragment.entryPoint = sv("fs_main");
- fragment.targetCount = 1;
- fragment.targets = &target;
+ fragment.targetCount = pass_gbuffer_ ? 2 : 1;
+ fragment.targets = targets;
WGPURenderPipelineDescriptor pd{};
// Explicit layout from the program's binding masks — the same cached
@@ -1660,7 +1670,8 @@ void WebGPUDevice::resolveDepthAttachment(u32 msaaDepth, u32 resolveDepth) {
WGPURenderPipeline WebGPUDevice::ensureClearPipeline(bool color, bool depth, bool stencil) {
// The sample count is part of the key for the same reason the formats are:
// a clear pipeline is validated against the pass it runs in.
- const u32 key = colorVariantOf(pass_color_format_) << 6 |
+ const u32 key = (pass_gbuffer_ ? 1u << 12 : 0u) |
+ colorVariantOf(pass_color_format_) << 6 |
dsVariantOf(pass_ds_format_) << 4 |
(pass_samples_ > 1 ? 8u : 0u) |
(color ? 1u : 0u) | (depth ? 2u : 0u) | (stencil ? 4u : 0u);
@@ -1721,15 +1732,18 @@ struct ClearColor { value : vec4f };
WGPUShaderModule vs = makeModule(kClearVS);
WGPUShaderModule fs = makeModule(kClearFS);
- WGPUColorTargetState target{};
- target.format = pass_color_format_;
- target.writeMask = color ? WGPUColorWriteMask_All : WGPUColorWriteMask_None;
+ WGPUColorTargetState clearTargets[2]{};
+ clearTargets[0].format = pass_color_format_;
+ clearTargets[0].writeMask = color ? WGPUColorWriteMask_All : WGPUColorWriteMask_None;
+ // A scoped clear is the camera's background, which a surface record has no part in.
+ clearTargets[1].format = WGPUTextureFormat_RGBA8Unorm;
+ clearTargets[1].writeMask = WGPUColorWriteMask_None;
WGPUFragmentState fragment{};
fragment.module = fs;
fragment.entryPoint = sv("fs_main");
- fragment.targetCount = 1;
- fragment.targets = &target;
+ fragment.targetCount = pass_gbuffer_ ? 2 : 1;
+ fragment.targets = clearTargets;
WGPURenderPipelineDescriptor pd{};
pd.layout = clear_layout_;
@@ -2120,6 +2134,9 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {
pass_depth_texture_ = 0;
pass_is_surface_ = desc.target == FramebufferHandle::Default;
pass_samples_ = 1;
+ pass_gbuffer_ = false;
+ WGPUTextureView gbufferView = nullptr;
+ WGPUTextureView gbufferResolveView = nullptr;
pass_depth_msaa_ = 0;
pass_depth_resolve_ = 0;
if (desc.target != FramebufferHandle::Default) {
@@ -2154,6 +2171,21 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {
resolveView = resolveIt->second.view;
pass_color_texture_ = resolve;
}
+ if (fb->color1 != TextureHandle::Invalid) {
+ auto gIt = textures_.find(static_cast<u32>(fb->color1));
+ if (gIt != textures_.end()) {
+ gbufferView = gIt->second.view;
+ pass_gbuffer_ = true;
+ if (gIt->second.samples > 1) {
+ auto gResolve = textures_.find(static_cast<u32>(fb->resolveColor1));
+ if (gResolve == textures_.end()) {
+ ES_LOG_ERROR("WebGPUDevice::beginRenderPass: a multisampled surface record with no resolve twin");
+ return;
+ }
+ gbufferResolveView = gResolve->second.view;
+ }
+ }
+ }
if (depthStencil != 0) {
auto dsIt = textures_.find(depthStencil);
if (dsIt != textures_.end()) {
@@ -2252,9 +2284,21 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {
color.storeOp = WGPUStoreOp_Store;
color.clearValue = toWGPUClearColor(desc);
+ // The surface record clears to zero — "nothing wrote here" — whatever the background is.
+ WGPURenderPassColorAttachment colors[2]{};
+ colors[0] = color;
+ if (pass_gbuffer_) {
+ colors[1].view = gbufferView;
+ colors[1].resolveTarget = gbufferResolveView;
+ colors[1].depthSlice = WGPU_DEPTH_SLICE_UNDEFINED;
+ colors[1].loadOp = toWGPULoadOp(desc.clearColor, scoped);
+ colors[1].storeOp = WGPUStoreOp_Store;
+ colors[1].clearValue = {0.0, 0.0, 0.0, 0.0};
+ }
+
WGPURenderPassDescriptor rp{};
- rp.colorAttachmentCount = 1;
- rp.colorAttachments = &color;
+ rp.colorAttachmentCount = pass_gbuffer_ ? 2 : 1;
+ rp.colorAttachments = colors;
WGPURenderPassDepthStencilAttachment ds{};
if (dsView) {
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
index b0b33521d..08eff5b4a 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
@@ -377,10 +377,15 @@ private:
/// Which of group1Mask's bindings are `texture_depth_2d`.
u32 group1DepthMask = 0;
};
+ /// What a pass's second colour attachment means to the pipeline drawn into it: there is none, the
+ /// pipeline writes it, or the pipeline leaves it alone (its target is declared with an empty write mask).
+ enum GBufferVariant : u32 { kGBufferNone = 0, kGBufferWrites = 1, kGBufferSkips = 2, kGBufferVariantCount = 3 };
struct PipelineRec {
- /// Lazily built per pass shape: [(ds * kColorVariantCount + color) * kSampleVariantCount + samples].
+ /// Lazily built per pass shape:
+ /// [((ds * kColorVariantCount + color) * kSampleVariantCount + samples) * kGBufferVariantCount + gbuffer].
WGPURenderPipeline variants[static_cast<u32>(kDsVariantCount) * static_cast<u32>(kColorVariantCount)
- * static_cast<u32>(kSampleVariantCount)] = {};
+ * static_cast<u32>(kSampleVariantCount)
+ * static_cast<u32>(kGBufferVariantCount)] = {};
};
struct ReadbackRec {
WGPUBuffer buffer = nullptr; ///< CopyDst|MapRead staging buffer.
@@ -514,6 +519,8 @@ private:
WGPUTextureFormat pass_color_format_ = WGPUTextureFormat_RGBA8Unorm;
/// Samples of the pass's colour attachment — what its pipelines must declare.
u32 pass_samples_ = 1;
+ /// The pass draws into a second colour attachment (always RGBA8) beside the first.
+ bool pass_gbuffer_ = false;
/// The multisampled depth attachment of the pass being ended, and the
/// single-sample texture it owes its contents to. Both 0 unless resolving.
u32 pass_depth_msaa_ = 0;
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 066e064e9..2f237ce77 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -694,6 +694,11 @@ ParsedShader ShaderParser::parse(const std::string& source, const ShaderIncludeR
continue;
}
+ if (directive == "gbuffer") {
+ result.usesGBuffer = true;
+ continue;
+ }
+
if (directive == "vertexbounds") {
// How far the vertex hook may move a vertex, in the mesh's local units.
result.vertexBounds = std::strtof(argument.c_str(), nullptr);
diff --git a/src/esengine/resource/ShaderParser.hpp b/src/esengine/resource/ShaderParser.hpp
index 63f9227fb..114eba68a 100644
--- a/src/esengine/resource/ShaderParser.hpp
+++ b/src/esengine/resource/ShaderParser.hpp
@@ -152,6 +152,9 @@ struct ParsedShader {
/// output alpha is coverage (a cutout sharpened to one texel), so an opaque draw
/// may turn it into multisample coverage instead of a hard edge.
std::string coverageParam;
+ /// `#pragma gbuffer`: a post-process shader reads the scene's surface record (normal, roughness,
+ /// metalness) at unit kGBufferUnit, so the frame must draw one for it.
+ bool usesGBuffer = false;
/// `#pragma vertexoffset`: the body of `esMaterialVertex(inout local, inout localNormal, uv)`,
/// run on a resident mesh's local-space vertex before it is posed and placed. It is the
/// material's own, so the canonical mesh vertex stage calls it and a material without one
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index c5bd2748b..b635835a4 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2481,4 +2481,8 @@ export const NOTED = {
{"note":"Auto Exposure and Depth of Field post-process effects are available."},
"feat(render): a Rain effect with wet ground, puddles, ripples and splashes, and reflections that treat puddles as mirrors":
{"note":"A Rain post-process effect adds falling rain, wet ground, puddles and ripples."},
+ "feat(render): the scene can draw a G-buffer beside its colour, and reflections read each surface's normal, roughness and metalness from it":
+ {"note":"Reflections now know how rough and how metal each surface is, from a G-buffer the frame draws on request."},
+ "feat(render): quality levels can leave out named post-process effects":
+ {"note":"Quality levels can now skip expensive post-process effects by name."},
};