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(postprocess): a display LUT in the last pass grades the picture as the display shows it, after the output transform

yhh0d4951837379
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ccc606ed3..bca3b5454 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ published separately; it ships inside the editor.
### Added
+- **A Display LUT.** The `displayLut` effect reads a look off a 1024x32 lookup table by the picture as the display will show it, in the last pass, after the output transform and the transfer function: the place a look authored against the finished image belongs, and one no effect in the chain can be, since they run on scene values before the curve. It is a variant of the pass that was running, one texture read and no pass of its own, and `PostProcessStack.setDisplayLut(texture, amount)` is the same thing in code. The last pass now reads its parameters off the reflected layout as a material does, and the copies it makes share them.
- **Light beams that follow the clouds.** `heightFog` has a `cloudShade`: its volumetric light marches the sun's ray up through the cloud layer of a `skyAtmosphere` whose clouds cast shadows (the same density the sky draws, fixed to the world and drifting with its wind), so a gap in the clouds is a beam in the air and what they cover is dark, whichever way the camera looks. `volumeRange` may now be as long as a million units, for beams through clouds kilometres up. The sky's clouds are copied onto the fog each frame, and an effect's uniform may be `internal`, which an inspector does not list.
- **Sparkle on the water.** The Water shader reads two tiled normal maps that scroll over the surface (`u_detailMap`, `u_detailTile0/1`, `u_detailStrength0/1`, `u_detailFlow0/1`), packed into the one texture a material has room for, so the sun's glints on small slopes come from lit specular response and not a white texture; a material that sets no strength is unchanged.
- **A generated world's plants.** A recipe's members can name a **plant** in the rules' `plants` (a `.esworld` file holds them): several parts (a trunk and its crown), a cheaper mesh and a far version, the colourings the art gives it, how far it is sunk and its `unit` (100 for metres in a world of centimetres). The world is laid out from the rules as the eye moves, the plants grown a cell at a time by the machinery a `PlacedFoliage` uses: a chunk stands at once and fills in over the frames after it inside the frame's budget, a cheaper mesh stands in at the middle distance, and a tree's crossed cards, laid out as a layer of their own, stand for it far off. A plant with no cards of its own may use its cheaper mesh as its far version and set `farKeep`, the share of its plants that version draws, so ground cover far off costs a share of what it does near; a member with `attach: 'align'` leans a plant with the ground, so a stone on a slope sits as the slope lies; the far versions are laid out in cells as wide as the shortest distance they are shown over allows, which took the Terrain & Water example's draws from about 1,800 to about 1,100. The terrain's paint is a field each of its layers (`paint.grass`), a rules file names noise fields of its own, and fields are worked out only where a condition reads them. The Terrain & Water example's woods, shrubs, stones, grass, flowers and reeds are laid out this way from `assets/worlds/plants.esworld`.
diff --git a/docs/astro/src/content/docs/graphics/post-processing.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdx
index a11a8b9d7..e14a8dfc9 100644
--- a/docs/astro/src/content/docs/graphics/post-processing.mdx
+++ b/docs/astro/src/content/docs/graphics/post-processing.mdx
@@ -17,7 +17,8 @@ several can stack in one frame at no extra target cost beyond the passes.
| `bloom` | Glow on bright areas | `threshold`, `intensity`, `radius` |
| `tonemap` | ACES filmic tonemapping | `exposure` |
| `colorGrade` | Exposure / contrast / saturation / white balance | `exposure`, `contrast`, `saturation`, `temperature`, `tint` |
-| `lutGrade` | Color grading through a lookup-table texture | `u_lut` (texture), `intensity` |
+| `lutGrade` | Color grading through a lookup-table texture, on scene values in the chain | `u_lut` (texture), `intensity` |
+| `displayLut` | A look read off a lookup table by the picture as the display shows it, in the last pass after the output transform | `u_lut` (texture), `intensity` |
| `agx` | The AgX view transform Blender uses: scene-linear in, display-linear out, so it goes last and the output transform stays `none`. Brings its own table | `contrast` (the look: 1 is AgX Base, 1.2 is Medium High Contrast) |
| `vignette` | Darkened screen edges | `intensity`, `softness` |
| `chromaticAberration` | RGB fringing | `intensity` |
@@ -401,6 +402,12 @@ effect: **Settings → Project → Rendering → Output transform**.
It applies to the editor viewport, to Play and to every export, and changing it
needs no reload. In code: `outputTransform: 'none' | 'aces' | 'neutral'`.
+A look authored against the finished picture (a warm LUT from a colourist, a film emulation) belongs after the curve, and no effect in the
+chain can be: they all run on scene values, before it. The **Display LUT** effect (`displayLut`) is the last pass's own stage: the picture is
+curved, encoded for the display, and then read off a 1024x32 table by the colour it will show: 32 slices along x, blue the slice, red along a slice and green up the picture (an image is read from its bottom).
+It adds a texture read to the pass that was running anyway, not a pass, whatever the output transform. Give the table's texture no compression,
+no mips and no sRGB: it is data. In code, `stack.setDisplayLut(textureHandle, amount)`.
+
<Aside>
The `tonemap` *effect* in the list above is a separate, optional ACES pass inside the
chain. With an output transform set you usually want neither it nor a second curve:
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 564d10c32..0936dee2a 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
@@ -16,7 +16,8 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess
| `bloom` | 亮部辉光 | `threshold`、`intensity`、`radius` |
| `tonemap` | ACES filmic 色调映射 | `exposure` |
| `colorGrade` | 曝光 / 对比度 / 饱和度 / 白平衡 | `exposure`、`contrast`、`saturation`、`temperature`、`tint` |
-| `lutGrade` | 通过查找表纹理(LUT)调色 | `u_lut`(纹理)、`intensity` |
+| `lutGrade` | 通过查找表纹理(LUT)调色,作用在效果链里的场景值上 | `u_lut`(纹理)、`intensity` |
+| `displayLut` | 在最后一个通道里、输出变换之后,按画面在显示器上的样子从查找表取出的调色 | `u_lut`(纹理)、`intensity` |
| `agx` | Blender 使用的 AgX 视图变换:输入场景线性、输出显示线性,所以放在最后,输出变换保持 `none`。自带查找表 | `contrast`(观感:1 是 AgX Base,1.2 是 Medium High Contrast) |
| `vignette` | 屏幕边缘变暗 | `intensity`、`softness` |
| `chromaticAberration` | RGB 色散 | `intensity` |
@@ -294,6 +295,11 @@ registerEffect({
它对编辑器视口、运行预览和所有导出都生效,改动无需重新加载。代码里是 `outputTransform: 'none' | 'aces' | 'neutral'`。
+对着成品画面做的调色(调色师给的暖色 LUT、胶片模拟)应该排在曲线之后,而效果链里的任何效果都做不到:它们都跑在
+场景值上,在曲线之前。**显示 LUT**(`displayLut`)是最后一个通道自己的阶段:画面先过曲线,再为显示器编码,然后按它将要
+显示的颜色从一张 1024x32 的表里取值:沿 x 排 32 片,蓝是片号,红沿片内 x 增大,绿沿图像向上增大(图像从最下面一行读起)。它是在本来就要跑的那个通道里多读一次纹理,不是多一个通道,
+和输出变换是哪个无关。表的纹理不要压缩、不要 mip、不要 sRGB:它是数据。代码里是 `stack.setDisplayLut(textureHandle, amount)`。
+
<Aside>
上面列表里的 `tonemap` *效果*是效果链里一个单独的、可选的 ACES 通道。设了输出变换之后,通常既不需要它,也不需要第二条曲线:
选输出变换,把这个效果关掉。
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index f4f9cc4cf..52d411340 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -3747,6 +3747,7 @@ fallback: EffectSubPass[] | undefined
label: string
multiPass: EffectSubPass[] | undefined
native: string | undefined
+stage: "output" | undefined
textures: EffectTextureDef[] | undefined
type: string
uniforms: EffectUniformDef[]
@@ -7179,6 +7180,7 @@ addPass: (name: string, shader: ShaderHandle, scale?: number, continuesEffect?:
clearDirty: () => void
clearPasses: () => PostProcessStack
destroy: () => void
+displayLut: { readonly texture: number; readonly amount: number; }
enabledPassCount: number
id: number
isDestroyed: boolean
@@ -7187,6 +7189,7 @@ passCount: number
passes: readonly PassConfig[]
removePass: (name: string) => PostProcessStack
setAllPassesEnabled: (enabled: boolean) => void
+setDisplayLut: (texture: number, amount: number) => PostProcessStack
setEnabled: (name: string, enabled: boolean) => PostProcessStack
setTexture: (passName: string, uniform: string, textureHandle: number) => PostProcessStack
setUniform: (passName: string, uniform: string, value: number) => PostProcessStack
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index a6659e491..36c743bcc 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -3755,6 +3755,7 @@ fallback: EffectSubPass[] | undefined
label: string
multiPass: EffectSubPass[] | undefined
native: string | undefined
+stage: "output" | undefined
textures: EffectTextureDef[] | undefined
type: string
uniforms: EffectUniformDef[]
@@ -7382,6 +7383,7 @@ addPass: (name: string, shader: ShaderHandle, scale?: number, continuesEffect?:
clearDirty: () => void
clearPasses: () => PostProcessStack
destroy: () => void
+displayLut: { readonly texture: number; readonly amount: number; }
enabledPassCount: number
id: number
isDestroyed: boolean
@@ -7390,6 +7392,7 @@ passCount: number
passes: readonly PassConfig[]
removePass: (name: string) => PostProcessStack
setAllPassesEnabled: (enabled: boolean) => void
+setDisplayLut: (texture: number, amount: number) => PostProcessStack
setEnabled: (name: string, enabled: boolean) => PostProcessStack
setTexture: (passName: string, uniform: string, textureHandle: number) => PostProcessStack
setUniform: (passName: string, uniform: string, value: number) => PostProcessStack
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 506c9bf52..89648e452 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -3742,6 +3742,7 @@ fallback: EffectSubPass[] | undefined
label: string
multiPass: EffectSubPass[] | undefined
native: string | undefined
+stage: "output" | undefined
textures: EffectTextureDef[] | undefined
type: string
uniforms: EffectUniformDef[]
@@ -7174,6 +7175,7 @@ addPass: (name: string, shader: ShaderHandle, scale?: number, continuesEffect?:
clearDirty: () => void
clearPasses: () => PostProcessStack
destroy: () => void
+displayLut: { readonly texture: number; readonly amount: number; }
enabledPassCount: number
id: number
isDestroyed: boolean
@@ -7182,6 +7184,7 @@ passCount: number
passes: readonly PassConfig[]
removePass: (name: string) => PostProcessStack
setAllPassesEnabled: (enabled: boolean) => void
+setDisplayLut: (texture: number, amount: number) => PostProcessStack
setEnabled: (name: string, enabled: boolean) => PostProcessStack
setTexture: (passName: string, uniform: string, textureHandle: number) => PostProcessStack
setUniform: (passName: string, uniform: string, value: number) => PostProcessStack
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 417b75553..f2654a543 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -3742,6 +3742,7 @@ fallback: EffectSubPass[] | undefined
label: string
multiPass: EffectSubPass[] | undefined
native: string | undefined
+stage: "output" | undefined
textures: EffectTextureDef[] | undefined
type: string
uniforms: EffectUniformDef[]
@@ -7467,6 +7468,7 @@ addPass: (name: string, shader: ShaderHandle, scale?: number, continuesEffect?:
clearDirty: () => void
clearPasses: () => PostProcessStack
destroy: () => void
+displayLut: { readonly texture: number; readonly amount: number; }
enabledPassCount: number
id: number
isDestroyed: boolean
@@ -7475,6 +7477,7 @@ passCount: number
passes: readonly PassConfig[]
removePass: (name: string) => PostProcessStack
setAllPassesEnabled: (enabled: boolean) => void
+setDisplayLut: (texture: number, amount: number) => PostProcessStack
setEnabled: (name: string, enabled: boolean) => PostProcessStack
setTexture: (passName: string, uniform: string, textureHandle: number) => PostProcessStack
setUniform: (passName: string, uniform: string, value: number) => PostProcessStack
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index d5d78b6ad..95c358bb5 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -410,6 +410,7 @@ postprocess_isInitialized: () => boolean
postprocess_maxMsaaSamples: (() => number) | undefined
postprocess_resize: (width: number, height: number) => void
postprocess_setBypass: (bypass: boolean) => void
+postprocess_setDisplayLut: ((textureHandle: number, amount: number) => void) | undefined
postprocess_setMsaaSamples: (samples: number) => void
postprocess_setOutputTransform: ((transform: number) => void) | undefined
postprocess_setOutputViewport: (x: number, y: number, w: number, h: number) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 9356a941d..2e91e2d0f 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -3742,6 +3742,7 @@ fallback: EffectSubPass[] | undefined
label: string
multiPass: EffectSubPass[] | undefined
native: string | undefined
+stage: "output" | undefined
textures: EffectTextureDef[] | undefined
type: string
uniforms: EffectUniformDef[]
@@ -7181,6 +7182,7 @@ addPass: (name: string, shader: ShaderHandle, scale?: number, continuesEffect?:
clearDirty: () => void
clearPasses: () => PostProcessStack
destroy: () => void
+displayLut: { readonly texture: number; readonly amount: number; }
enabledPassCount: number
id: number
isDestroyed: boolean
@@ -7189,6 +7191,7 @@ passCount: number
passes: readonly PassConfig[]
removePass: (name: string) => PostProcessStack
setAllPassesEnabled: (enabled: boolean) => void
+setDisplayLut: (texture: number, amount: number) => PostProcessStack
setEnabled: (name: string, enabled: boolean) => PostProcessStack
setTexture: (passName: string, uniform: string, textureHandle: number) => PostProcessStack
setUniform: (passName: string, uniform: string, value: number) => PostProcessStack
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index b0c79d06d..114e69570 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -118,6 +118,7 @@ export interface NativeEngineApi {
postprocess_maxMsaaSamples?(): number;
postprocess_resize?(width: number, height: number): void;
postprocess_setBypass?(bypass: boolean): void;
+ postprocess_setDisplayLut?(textureHandle: number, amount: number): void;
postprocess_setMsaaSamples?(samples: number): void;
postprocess_setOutputTransform?(transform: number): void;
postprocess_setOutputViewport?(x: number, y: number, w: number, h: number): void;
@@ -441,6 +442,7 @@ export function createNativeEngineApi(
bind('postprocess_maxMsaaSamples', 'es_postprocess_maxMsaaSamples', false);
bind('postprocess_resize', 'es_postprocess_resize', false);
bind('postprocess_setBypass', 'es_postprocess_setBypass', false);
+ bind('postprocess_setDisplayLut', 'es_postprocess_setDisplayLut', false);
bind('postprocess_setMsaaSamples', 'es_postprocess_setMsaaSamples', false);
bind('postprocess_setOutputTransform', 'es_postprocess_setOutputTransform', false);
bind('postprocess_setOutputViewport', 'es_postprocess_setOutputViewport', false);
diff --git a/sdk/src/postprocess/PostProcessAPI.ts b/sdk/src/postprocess/PostProcessAPI.ts
index ac7eb2041..6489de174 100644
--- a/sdk/src/postprocess/PostProcessAPI.ts
+++ b/sdk/src/postprocess/PostProcessAPI.ts
@@ -30,7 +30,7 @@ type PostProcessCore = Required<Pick<NonNullable<EngineApi>,
| 'postprocess_clearScreenPasses' | 'postprocess_setScreenUniformFloat'
| 'postprocess_setScreenUniformVec4'>>
// A core without a compute stage (or built before there was one) does not answer this one.
- & Pick<NonNullable<EngineApi>, 'postprocess_addComputePass' | 'postprocess_supportsCompute' | 'postprocess_addNativePass'>;
+ & Pick<NonNullable<EngineApi>, 'postprocess_addComputePass' | 'postprocess_supportsCompute' | 'postprocess_addNativePass' | 'postprocess_setDisplayLut'>;
/** Guarded view of the core: after a wasm abort a call throws instead of reaching
* a dead module; a native host's bindings never abort. */
@@ -182,6 +182,15 @@ export function syncStackToWasm(stack: PostProcessStack, force = false,
}
}
+ // The display look rides the stack as the passes do, and goes with them (clearPasses above): said again for every camera that has one.
+ if (stack.displayLut.amount > 0) {
+ try {
+ m.postprocess_setDisplayLut?.(stack.displayLut.texture, stack.displayLut.amount);
+ } catch (e) {
+ handleWasmError(e, 'PostProcess._applyForCamera:setDisplayLut');
+ }
+ }
+
stack.clearDirty();
}
diff --git a/sdk/src/postprocess/PostProcessStack.ts b/sdk/src/postprocess/PostProcessStack.ts
index 6616c9893..5cb24cc02 100644
--- a/sdk/src/postprocess/PostProcessStack.ts
+++ b/sdk/src/postprocess/PostProcessStack.ts
@@ -66,6 +66,7 @@ export class PostProcessStack {
private passes_: PassConfig[] = [];
private destroyed_ = false;
private dirty_ = true;
+ private displayLut_ = { texture: 0, amount: 0 };
constructor(state: PostProcessState) {
this.state_ = state;
@@ -136,9 +137,28 @@ export class PostProcessStack {
this.passes_.length = 0;
this.dirty_ = true;
}
+ this.setDisplayLut(0, 0);
return this;
}
+ /**
+ * A graded look for the last pass: `texture` is a 1024x32 table (a 32-slice strip, slice along x being blue) read by the picture as the
+ * display shows it, after the output transform, and `amount` how far the picture moves toward its answer (0 to 1). Part of the stack, as
+ * its passes are: 0 for no table clears it.
+ */
+ setDisplayLut(texture: number, amount: number): this {
+ const wanted = texture !== 0 && amount > 0 ? { texture, amount: Math.min(amount, 1) } : { texture: 0, amount: 0 };
+ if (wanted.texture !== this.displayLut_.texture || wanted.amount !== this.displayLut_.amount) {
+ this.displayLut_ = wanted;
+ this.dirty_ = true;
+ }
+ return this;
+ }
+
+ get displayLut(): { readonly texture: number; readonly amount: number } {
+ return this.displayLut_;
+ }
+
setEnabled(name: string, enabled: boolean): this {
const pass = this.passes_.find(p => p.name === name);
if (pass && pass.enabled !== enabled) {
diff --git a/sdk/src/postprocess/effects.ts b/sdk/src/postprocess/effects.ts
index e16decbd4..cd61727b7 100644
--- a/sdk/src/postprocess/effects.ts
+++ b/sdk/src/postprocess/effects.ts
@@ -84,7 +84,12 @@ export interface EffectDef {
label: string;
/** Set for every built-in effect, by the table at the end of this file. */
category?: EffectCategory;
- /** What compiles the effect's draw shader. Absent for a compute effect (see {@link compute}). */
+ /**
+ * Set for an effect that is a stage of the chain's last pass and not a pass of its own ("displayLut"): it has no shader, and the volume's
+ * values are handed to the stack for the last pass to read, which runs once and after the output transform.
+ */
+ stage?: 'output';
+ /** What compiles the effect's draw shader. Absent for a compute effect (see {@link compute}) and an output stage. */
factory?: () => ShaderHandle;
/** Set instead of `factory` for an effect that runs as a compute shader. */
compute?: ComputeEffectSource;
@@ -753,9 +758,23 @@ registerEffect({
],
});
+// A graded look read off a table by the picture as the display shows it: the last pass's, after the output transform and the transfer
+// function, which no effect in the chain can be (they run on scene values, before both). For a look authored against the finished image.
+registerEffect({
+ type: 'displayLut',
+ label: 'Display LUT',
+ stage: 'output',
+ uniforms: [
+ { name: 'u_intensity', label: 'Intensity', min: 0, max: 1, step: 0.01, defaultValue: 1 },
+ ],
+ textures: [
+ { name: 'u_lut', label: 'LUT (1024x32, 32 slices, as the display shows it)' },
+ ],
+});
+
const CATEGORIES: Record<EffectCategory, string[]> = {
lens: ['bloom', 'depthOfField', 'motionBlur', 'lensFlare', 'filmGrain', 'chromaticAberration', 'lensDistortion', 'vignette', 'sharpen'],
- color: ['tonemap', 'agx', 'colorGrade', 'lutGrade', 'autoExposure', 'grayscale'],
+ color: ['tonemap', 'agx', 'colorGrade', 'lutGrade', 'displayLut', 'autoExposure', 'grayscale'],
light: ['ssao', 'gtao', 'ssgi', 'ssr', 'voxelGI', 'contactShadows', 'lightShafts', 'subsurface'],
atmosphere: ['distanceFog', 'heightFog', 'skyAtmosphere', 'rain'],
aa: ['fxaa', 'taa'],
diff --git a/sdk/src/postprocess/volumeSystem.ts b/sdk/src/postprocess/volumeSystem.ts
index 2a6c6ecef..1ce02a3f8 100644
--- a/sdk/src/postprocess/volumeSystem.ts
+++ b/sdk/src/postprocess/volumeSystem.ts
@@ -84,6 +84,18 @@ function applyBuiltinTextures(api: PostProcessAPI, stack: ReturnType<PostProcess
type ResolvedEffects = Map<string, BlendedEffect>;
+/** What the output stages among the effects ask of the last pass: the display look's table (a texture handle) and amount. */
+function displayLutOf(effects: ResolvedEffects): { texture: number; amount: number } {
+ for (const [type, data] of effects) {
+ if (!data.enabled || getEffectDef(type)?.stage !== 'output' || type !== 'displayLut') continue;
+ const ref = data.textures.get('u_lut');
+ const texture = ref && volumeTextureResolver ? volumeTextureResolver(ref) : 0;
+ const amount = data.uniforms.get('u_intensity') ?? getEffectDef(type)?.uniforms.find((u) => u.name === 'u_intensity')?.defaultValue ?? 1;
+ return { texture, amount };
+ }
+ return { texture: 0, amount: 0 };
+}
+
function applyColors(
stack: ReturnType<PostProcessAPI['createStack']>,
passName: string,
@@ -125,8 +137,10 @@ function passNamesOf(effectType: string): string[] {
}
function writeValues(stack: ReturnType<PostProcessAPI['createStack']>, effects: ResolvedEffects): void {
+ const look = displayLutOf(effects);
+ stack.setDisplayLut(look.texture, look.amount);
for (const [effectType, effectData] of effects) {
- if (!effectData.enabled || !getEffectDef(effectType)) continue;
+ if (!effectData.enabled || !getEffectDef(effectType) || getEffectDef(effectType)!.stage) continue;
for (const passName of passNamesOf(effectType)) {
for (const [uniformName, uniformValue] of effectData.uniforms) {
stack.setUniform(passName, uniformName, uniformValue);
@@ -195,6 +209,8 @@ function applyBlendedEffects(
const def = getEffectDef(effectType);
if (!def) continue;
+ // A stage of the last pass is no pass: it is read off the effects once, below.
+ if (def.stage) continue;
if (def.multiPass) {
for (const [index, subPass] of def.multiPass.entries()) {
@@ -237,7 +253,11 @@ function applyBlendedEffects(
}
}
- if (stack.enabledPassCount > 0) {
+ const look = displayLutOf(effects);
+ stack.setDisplayLut(look.texture, look.amount);
+
+ // A stack with only a display look has no pass, and is still the camera's.
+ if (stack.enabledPassCount > 0 || stack.displayLut.amount > 0) {
api.bind(camera, stack);
} else {
api.unbind(camera);
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index db502662d..af28d45b3 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -548,6 +548,8 @@ export interface ESEngineModule {
* Absent on an engine built before the output transform existed. */
postprocess_setOutputTransform?(transform: number): void;
postprocess_setViewExposure?(ev: number): void;
+ /** A graded look the last pass applies to the picture as the display shows it. Absent on an engine built before there was one. */
+ postprocess_setDisplayLut?(textureHandle: number, amount: number): void;
postprocess_clearPasses(): void;
postprocess_setOutputViewport(x: number, y: number, w: number, h: number): void;
/** Say a present is needed when the rects cannot: see PostProcessPipeline. */
diff --git a/sdk/tests/display-lut.test.ts b/sdk/tests/display-lut.test.ts
new file mode 100644
index 000000000..db96c002e
--- /dev/null
+++ b/sdk/tests/display-lut.test.ts
@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The display LUT: a stage of the chain's last pass that rides a stack as its passes do, and is said to the engine with them.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { PostProcessAPI, initPostProcessAPI, getEffectDef } from '../src/postprocess';
+import { syncStackToWasm } from '../src/postprocess/PostProcessAPI';
+import type { ESEngineModule } from '../src/wasm';
+
+function mockModule() {
+ return {
+ postprocess_init: vi.fn().mockReturnValue(true),
+ postprocess_clearPasses: vi.fn(),
+ postprocess_addPass: vi.fn(),
+ postprocess_setPassScale: vi.fn(),
+ postprocess_setPassContinuesEffect: vi.fn(),
+ postprocess_setUniformFloat: vi.fn(),
+ postprocess_setUniformVec4: vi.fn(),
+ postprocess_setPassTexture: vi.fn(),
+ postprocess_setDisplayLut: vi.fn(),
+ postprocess_setOutputTransform: vi.fn(),
+ };
+}
+
+describe('the display LUT of a stack', () => {
+ let mock: ReturnType<typeof mockModule>;
+ let pp: PostProcessAPI;
+
+ beforeEach(() => {
+ mock = mockModule();
+ initPostProcessAPI(mock as unknown as ESEngineModule);
+ pp = new PostProcessAPI();
+ });
+
+ it('is an effect that is a stage of the last pass, with no shader of its own', () => {
+ const def = getEffectDef('displayLut')!;
+ expect(def.stage).toBe('output');
+ expect(def.factory).toBeUndefined();
+ expect(def.textures!.map((t) => t.name)).toEqual(['u_lut']);
+ });
+
+ it('is said to the engine with the stack, after the passes it clears, and not for a table with no amount', () => {
+ const stack = pp.createStack();
+ stack.setDisplayLut(7, 0.5);
+ syncStackToWasm(stack, true);
+ expect(mock.postprocess_clearPasses).toHaveBeenCalledOnce();
+ expect(mock.postprocess_setDisplayLut).toHaveBeenCalledWith(7, 0.5);
+ expect(mock.postprocess_clearPasses.mock.invocationCallOrder[0]!).toBeLessThan(mock.postprocess_setDisplayLut.mock.invocationCallOrder[0]!);
+
+ mock.postprocess_setDisplayLut.mockClear();
+ stack.setDisplayLut(7, 0);
+ syncStackToWasm(stack, true);
+ expect(mock.postprocess_setDisplayLut).not.toHaveBeenCalled();
+ });
+
+ it('makes the stack dirty only when it changes, holds the amount to 1, and is cleared with the passes', () => {
+ const stack = pp.createStack();
+ stack.clearDirty();
+ stack.setDisplayLut(3, 2);
+ expect(stack.isDirty).toBe(true);
+ expect(stack.displayLut).toEqual({ texture: 3, amount: 1 });
+ stack.clearDirty();
+ stack.setDisplayLut(3, 1);
+ expect(stack.isDirty).toBe(false);
+ stack.clearPasses();
+ expect(stack.displayLut).toEqual({ texture: 0, amount: 0 });
+ expect(stack.isDirty).toBe(true);
+ });
+
+ it('is nothing without a texture, whatever the amount', () => {
+ const stack = pp.createStack();
+ stack.setDisplayLut(0, 1);
+ expect(stack.displayLut).toEqual({ texture: 0, amount: 0 });
+ });
+});
diff --git a/src/esengine/bindings/MaterialBindings.cpp b/src/esengine/bindings/MaterialBindings.cpp
index a6130408e..ec840f423 100644
--- a/src/esengine/bindings/MaterialBindings.cpp
+++ b/src/esengine/bindings/MaterialBindings.cpp
@@ -27,56 +27,6 @@ static EstellaContext& ctx() { return activeCtx(); }
#define g_renderContext (ctx().tryGet<RenderContext>())
#define g_resourceManager (ctx().tryGet<resource::ResourceManager>())
-// Float component count for a std140 param type (textures have no block slot).
-static u32 materialParamArity(resource::ShaderPropertyType t) {
- using PT = resource::ShaderPropertyType;
- switch (t) {
- case PT::Float: case PT::Int: return 1;
- case PT::Vec2: return 2;
- case PT::Vec3: return 3;
- case PT::Vec4: case PT::Color: return 4;
- default: return 0;
- }
-}
-
-// Build the engine-side layout from a parsed shader's #pragma param reflection: non-texture
-// params into the std140 block (declared order == offset order), texture params into sampler
-// slots (their reflected units, >= MATERIAL_TEXTURE_UNIT_BASE).
-static MaterialUniformLayout buildMaterialLayout(const resource::ParsedShader& parsed,
- const RenderContext& rc) {
- MaterialUniformLayout layout;
- layout.blockSize = parsed.materialBlockSize;
- layout.coverageParam = parsed.coverageParam;
- layout.tipParam = parsed.tipParam;
- layout.hairShadowParam = parsed.hairShadowParam;
- layout.usesGBuffer = parsed.usesGBuffer;
- layout.usesLights = parsed.usesLights;
- layout.highPrecision = parsed.highPrecision;
- layout.vertexBounds = parsed.vertexBounds;
- layout.vertexHook = !parsed.vertexHook.empty();
- for (const auto& p : parsed.properties) {
- if (!p.fromParam) continue;
- if (p.type == resource::ShaderPropertyType::Texture) {
- if (p.textureUnit >= 0) {
- // Resolve the param's `default(<name>)` to a built-in default texture, bound when
- // a material leaves the param unset.
- layout.textures.push_back({ p.name, static_cast<u32>(p.textureUnit),
- materialDefaultByName(p.defaultValue) });
- }
- } else if (p.std140Offset >= 0) {
- MaterialParamSlot slot{ p.name, static_cast<u32>(p.std140Offset), materialParamArity(p.type) };
- // default(a,b,c,d) csv → the slot's initial block value.
- std::istringstream csv(p.defaultValue);
- std::string tok;
- for (u32 i = 0; i < slot.arity && std::getline(csv, tok, ','); ++i) {
- slot.defaults[i] = std::strtof(tok.c_str(), nullptr);
- }
- layout.params.push_back(slot);
- }
- }
- return layout;
-}
-
u32 material_compileEsshader(const std::string& source, const std::string& featuresCsv) {
auto* rm = g_resourceManager;
if (!rm) return 0;
@@ -103,7 +53,7 @@ u32 material_compileEsshader(const std::string& source, const std::string& featu
if (!handle.isValid()) return 0;
if (auto* rc = g_renderContext) {
if (Shader* s = rm->getShader(handle)) {
- rc->materials().registerLayout(handle, buildMaterialLayout(parsed, *rc));
+ rc->materials().registerLayout(handle, MaterialStore::layoutOf(parsed));
// Kept so the same material can be compiled for another vertex source
// (GPU-resident geometry) without the author's file being read again.
rc->materials().rememberSource(handle, source, featuresCsv);
diff --git a/src/esengine/bindings/PostProcessBindings.cpp b/src/esengine/bindings/PostProcessBindings.cpp
index 0af4ff980..2561e0edd 100644
--- a/src/esengine/bindings/PostProcessBindings.cpp
+++ b/src/esengine/bindings/PostProcessBindings.cpp
@@ -197,6 +197,17 @@ void postprocess_setOutputTransform(u32 transform) {
: OutputTransform::None);
}
+void postprocess_setDisplayLut(u32 textureHandle, f32 amount) {
+ if (!g_postProcessPipeline) return;
+ u32 glId = 0;
+ if (textureHandle != 0) {
+ if (auto* rm = ctx().tryGet<resource::ResourceManager>()) {
+ if (auto* tex = rm->getTexture(resource::TextureHandle(textureHandle))) glId = tex->getId();
+ }
+ }
+ g_postProcessPipeline->setDisplayLut(glId, amount);
+}
+
void postprocess_setViewExposure(f32 ev) {
if (g_postProcessPipeline) g_postProcessPipeline->setViewExposure(ev);
}
diff --git a/src/esengine/bindings/PostProcessBindings.hpp b/src/esengine/bindings/PostProcessBindings.hpp
index 8513012e0..5304a5d16 100644
--- a/src/esengine/bindings/PostProcessBindings.hpp
+++ b/src/esengine/bindings/PostProcessBindings.hpp
@@ -66,6 +66,8 @@ bool postprocess_isInitialized();
void postprocess_setBypass(bool bypass);
/** The curve the chain applies on the way out: 0 = none, 1 = ACES filmic. */
void postprocess_setOutputTransform(u32 transform);
+/** A graded look the last pass applies to the picture as the display shows it: a 1024x32 table (texture handle, 0 for none) and how far, 0 to 1. Let go with the passes. */
+void postprocess_setDisplayLut(u32 textureHandle, f32 amount);
/** The editor view's exposure in stops (EV); 0 is exact identity. View state, never saved. */
void postprocess_setViewExposure(f32 ev);
void postprocess_clearPasses();
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 8e263a33e..3581d8b19 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -615,6 +615,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("postprocess_isInitialized", &esengine::postprocess_isInitialized);
emscripten::function("postprocess_setBypass", &esengine::postprocess_setBypass);
emscripten::function("postprocess_setOutputTransform", &esengine::postprocess_setOutputTransform);
+ emscripten::function("postprocess_setDisplayLut", &esengine::postprocess_setDisplayLut);
emscripten::function("postprocess_setViewExposure", &esengine::postprocess_setViewExposure);
emscripten::function("postprocess_clearPasses", &esengine::postprocess_clearPasses);
emscripten::function("postprocess_setOutputViewport", &esengine::postprocess_setOutputViewport);
diff --git a/src/esengine/data/shaders/blit.esshader b/src/esengine/data/shaders/blit.esshader
index ecfc913ec..6edd05997 100644
--- a/src/esengine/data/shaders/blit.esshader
+++ b/src/esengine/data/shaders/blit.esshader
@@ -1,6 +1,10 @@
#pragma shader "Blit"
#pragma version 300 es
#pragma domain PostProcess
+// The display stage: with ES_DISPLAY_LUT, a graded look is read off a 32x32x32 table (1024x32: the slice along x is blue, red runs along a slice, green up the picture) by the picture as
+// the display will show it, after the output transform and the transfer function. The amount is the pipeline's, not a scene's.
+#pragma param u_displayLut texture default(white)
+#pragma param u_displayLutAmount float default(0)
#pragma fragment
precision highp float;
@@ -47,6 +51,20 @@ vec4 upscale(vec2 uv) {
}
#endif
+#ifdef ES_DISPLAY_LUT
+vec3 displayLookup(vec3 c) {
+ const float size = 32.0;
+ float b = clamp(c.b, 0.0, 1.0) * (size - 1.0);
+ float slice0 = floor(b);
+ float slice1 = min(slice0 + 1.0, size - 1.0);
+ float u = (clamp(c.r, 0.0, 1.0) * (size - 1.0) + 0.5) / (size * size);
+ float v = (clamp(c.g, 0.0, 1.0) * (size - 1.0) + 0.5) / size;
+ vec3 a = texture(u_displayLut, vec2(u + slice0 / size, v)).rgb;
+ vec3 d = texture(u_displayLut, vec2(u + slice1 / size, v)).rgb;
+ return mix(a, d, b - slice0);
+}
+#endif
+
void main() {
#ifdef ES_COPY_DEPTH
// How far each pixel of the opaque scene is from the eye, in world units, for a surface that measures the column of water or
@@ -84,10 +102,15 @@ void main() {
#ifdef ES_LINEAR
// The one mandatory OETF: the chain upstream is linear (sRGB attachments
// decode on sample), the canvas backbuffer is plain UNORM.
- fragColor = vec4(linearToSrgb(c.rgb), c.a);
+ vec3 shown = linearToSrgb(c.rgb);
#else
- fragColor = c;
+ vec3 shown = c.rgb;
+#endif
+#ifdef ES_DISPLAY_LUT
+ // What the display will show, graded: the table is authored against the picture as it looks, so it reads the encoded colour.
+ shown = mix(shown, displayLookup(shown), clamp(u_displayLutAmount, 0.0, 1.0));
#endif
+ fragColor = vec4(shown, c.a);
}
#pragma end
@@ -124,6 +147,20 @@ fn upscale(uv : vec2f) -> vec4f {
}
#endif
+#ifdef ES_DISPLAY_LUT
+fn displayLookup(c : vec3f) -> vec3f {
+ let size = 32.0;
+ let b = clamp(c.b, 0.0, 1.0) * (size - 1.0);
+ let slice0 = floor(b);
+ let slice1 = min(slice0 + 1.0, size - 1.0);
+ let u = (clamp(c.r, 0.0, 1.0) * (size - 1.0) + 0.5) / (size * size);
+ let v = (clamp(c.g, 0.0, 1.0) * (size - 1.0) + 0.5) / size;
+ let a = textureSampleLevel(u_displayLut, u_displayLut_s, vec2f(u + slice0 / size, v), 0.0).rgb;
+ let d = textureSampleLevel(u_displayLut, u_displayLut_s, vec2f(u + slice1 / size, v), 0.0).rgb;
+ return mix(a, d, b - slice0);
+}
+#endif
+
@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
#ifdef ES_COPY_DEPTH
let depthSize = vec2i(textureDimensions(t7, 0));
@@ -149,9 +186,13 @@ fn upscale(uv : vec2f) -> vec4f {
c = vec4f(pbrNeutral(c.rgb), c.a);
#endif
#ifdef ES_LINEAR
- return vec4f(linearToSrgb(c.rgb), c.a);
+ var shown = linearToSrgb(c.rgb);
#else
- return c;
+ var shown = c.rgb;
+#endif
+#ifdef ES_DISPLAY_LUT
+ shown = mix(shown, displayLookup(shown), clamp(mc.u_displayLutAmount, 0.0, 1.0));
#endif
+ return vec4f(shown, c.a);
}
#pragma end
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index d7fea4a97..196187a25 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp
@@ -16,6 +16,7 @@
#include "./VoxelGI.hpp"
#include "../rhi/GfxDevice.hpp"
#include "../store/MaterialConstants.hpp"
+#include "../store/MaterialStore.hpp"
#include "../store/LightConstants.hpp"
#include "../rhi/Shader.hpp"
#include "../rhi/ShaderEmbeds.generated.hpp"
@@ -81,11 +82,25 @@ void PostProcessPipeline::init(u32 width, u32 height) {
resource::ShaderHandle PostProcessPipeline::compileBlit(const std::vector<std::string>& features) {
const auto target = resourceManager_.preferredShaderTarget();
auto parsed = resource::ShaderParser::parse(ShaderEmbeds::BLIT);
- return resourceManager_.createShader(
+ const auto handle = resourceManager_.createShader(
resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Vertex, "", features, target),
resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Fragment, "", features, target),
/*rewriteLoose=*/false,
resourceManager_.preferredShaderLanguage());
+ // Its parameters are read as a material's are, off the reflected layout: the block and the texture slot every variant declares.
+ if (handle.isValid()) {
+ context_.materials().registerLayout(handle, MaterialStore::layoutOf(parsed));
+ // The table's sampler is in the program only where the look is (the others do not read it, and the compiler drops it).
+ if (Shader* compiled = resourceManager_.getShader(handle);
+ compiled && compiled->language() == GfxShaderLanguage::GLSL_ES300 && compiled->hasUniform("u_displayLut")) {
+ compiled->bind();
+ for (const auto& p : parsed.properties) {
+ if (p.fromParam && p.name == "u_displayLut" && p.textureUnit >= 0) compiled->setUniform(p.name, static_cast<i32>(p.textureUnit));
+ }
+ compiled->unbind();
+ }
+ }
+ return handle;
}
void PostProcessPipeline::setViewExposure(f32 ev) {
@@ -97,37 +112,37 @@ void PostProcessPipeline::setViewExposure(f32 ev) {
* The blit the current output transform needs. Compiled on first use rather
* than at init: a project that never asks for a curve never pays for one.
*/
+resource::ShaderHandle PostProcessPipeline::blitVariant(bool upscale, OutputTransform transform, bool lut) {
+ const u32 key = (upscale ? 1u : 0u) | (static_cast<u32>(transform) << 1) | (lut ? 8u : 0u);
+ if (key == 0) return blitShader_;
+ if (const auto it = blitVariants_.find(key); it != blitVariants_.end()) return it->second;
+ std::vector<std::string> features;
+ if (upscale) features.push_back("ES_UPSCALE");
+ if (transform == OutputTransform::Neutral) features.push_back("ES_TONEMAP_NEUTRAL");
+ if (transform == OutputTransform::ACES) features.push_back("ES_TONEMAP");
+ if (lut) features.push_back("ES_DISPLAY_LUT");
+ const resource::ShaderHandle handle = compileBlit(features);
+ if (!handle.isValid()) ES_LOG_ERROR("PostProcessPipeline: the last pass would not compile with upscale={} curve={} lut={}", upscale, static_cast<u32>(transform), lut);
+ blitVariants_[key] = handle;
+ return handle;
+}
+
resource::ShaderHandle PostProcessPipeline::outputShader() {
- if (presentUpscales()) {
- const usize which = output_transform_ == OutputTransform::Neutral ? 1 : output_transform_ == OutputTransform::ACES ? 2 : 0;
- if (!upscaleShaders_[which].isValid()) {
- std::vector<std::string> features{"ES_UPSCALE"};
- if (which == 1) features.push_back("ES_TONEMAP_NEUTRAL");
- if (which == 2) features.push_back("ES_TONEMAP");
- upscaleShaders_[which] = compileBlit(features);
- if (!upscaleShaders_[which].isValid()) ES_LOG_ERROR("PostProcessPipeline: no upscaling blit; the present stays bilinear");
- }
- if (upscaleShaders_[which].isValid()) return upscaleShaders_[which];
- }
- if (output_transform_ == OutputTransform::Neutral) {
- if (!neutralShader_.isValid()) {
- neutralShader_ = compileBlit({"ES_TONEMAP_NEUTRAL"});
- if (!neutralShader_.isValid()) {
- ES_LOG_ERROR("PostProcessPipeline: no ES_TONEMAP_NEUTRAL blit; output stays untonemapped");
- return blitShader_;
- }
- }
- return neutralShader_;
- }
- if (output_transform_ != OutputTransform::ACES) return blitShader_;
- if (!tonemapShader_.isValid()) {
- tonemapShader_ = compileBlit({"ES_TONEMAP"});
- if (!tonemapShader_.isValid()) {
- ES_LOG_ERROR("PostProcessPipeline: no ES_TONEMAP blit; output stays untonemapped");
- return blitShader_;
- }
+ // What the last pass is asked for, and then, where a variant would not compile, less of it: the look first (it is the part a flat frame
+ // can do without), then the resampling, then the curve. Never a black frame.
+ const bool upscale = presentUpscales();
+ const bool lut = displayLutActive();
+ const struct { bool upscale; OutputTransform transform; bool lut; } wants[] = {
+ {upscale, output_transform_, lut},
+ {upscale, output_transform_, false},
+ {false, output_transform_, false},
+ {false, OutputTransform::None, false},
+ };
+ for (const auto& w : wants) {
+ const resource::ShaderHandle handle = blitVariant(w.upscale, w.transform, w.lut);
+ if (handle.isValid()) return handle;
}
- return tonemapShader_;
+ return blitShader_;
}
/**
@@ -223,10 +238,6 @@ void PostProcessPipeline::shutdown() {
if (blitShader_.isValid()) {
resourceManager_.releaseShader(blitShader_);
}
- if (tonemapShader_.isValid()) {
- resourceManager_.releaseShader(tonemapShader_);
- tonemapShader_ = resource::ShaderHandle{};
- }
if (copyShader_.isValid()) {
resourceManager_.releaseShader(copyShader_);
copyShader_ = resource::ShaderHandle{};
@@ -235,14 +246,14 @@ void PostProcessPipeline::shutdown() {
resourceManager_.releaseShader(copyDepthShader_);
copyDepthShader_ = resource::ShaderHandle{};
}
- for (auto& shader : upscaleShaders_) {
- if (!shader.isValid()) continue;
- resourceManager_.releaseShader(shader);
- shader = resource::ShaderHandle{};
+ for (auto& [key, shader] : blitVariants_) {
+ if (shader.isValid()) resourceManager_.releaseShader(shader);
}
- if (neutralShader_.isValid()) {
- resourceManager_.releaseShader(neutralShader_);
- neutralShader_ = resource::ShaderHandle{};
+ blitVariants_.clear();
+ if (blitParamUbo_ != BufferHandle::Invalid) {
+ device_.deleteBuffer(blitParamUbo_);
+ blitParamUbo_ = BufferHandle::Invalid;
+ blitParamAmount_ = -1.0f;
}
initialized_ = false;
@@ -1000,6 +1011,9 @@ void PostProcessPipeline::computePass(PostProcessPass& pass, const rg::PassConte
void PostProcessPipeline::clearPasses() {
for (auto& pass : passes_) releasePassResources(pass);
passes_.clear();
+ // The display look is the chain's, like its passes: the next camera says its own.
+ display_lut_texture_ = 0;
+ display_lut_amount_ = 0.0f;
}
void PostProcessPipeline::setOutputTarget(FramebufferHandle target) {
@@ -1026,6 +1040,7 @@ void PostProcessPipeline::grabScene() {
applyPassPipeline(*shader);
if (shader->hasUniform("u_texture")) shader->setUniform("u_texture", 0);
shader->commitParams();
+ bindBlitInputs(copyShader_);
drawScreenQuad();
}
@@ -1048,11 +1063,13 @@ void PostProcessPipeline::grabDepth() {
if (shader->hasUniform("u_sceneDepth")) shader->setUniform("u_sceneDepth", static_cast<i32>(kSceneDepthUnit));
shader->commitParams();
device_.bindTexture(kSceneDepthUnit, graph_ ? graph_->depthTextureOf(sceneResource_) : TextureHandle::Invalid);
+ bindBlitInputs(copyDepthShader_);
drawScreenQuad();
}
void PostProcessPipeline::blitPass() {
- Shader* shader = resourceManager_.getShader(outputShader());
+ const resource::ShaderHandle outputHandle = outputShader();
+ Shader* shader = resourceManager_.getShader(outputHandle);
if (!shader) return;
// The output rect is the one thing a pass does not get from its target: the
@@ -1065,10 +1082,40 @@ void PostProcessPipeline::blitPass() {
applyPassPipeline(*shader);
if (shader->hasUniform("u_texture")) shader->setUniform("u_texture", 0);
shader->commitParams();
+ bindBlitInputs(outputHandle);
drawScreenQuad();
}
+void PostProcessPipeline::bindBlitInputs(const resource::ShaderHandle& handle) {
+ const MaterialUniformLayout* layout = context_.materials().layoutFor(handle);
+ if (!layout) return;
+ // Only the last pass applies the look: the copies share the file, and read the amount as none.
+ const bool lastPass = handle.id() != copyShader_.id() && handle.id() != copyDepthShader_.id();
+ const f32 amount = lastPass && displayLutActive() ? display_lut_amount_ : 0.0f;
+ if (layout->blockSize > 0) {
+ if (blitParamUbo_ == BufferHandle::Invalid || blitParamAmount_ != amount) {
+ std::vector<u8> bytes(layout->blockSize, 0);
+ for (const auto& p : layout->params) {
+ if (p.name == "u_displayLutAmount") std::memcpy(bytes.data() + p.offset, &amount, sizeof(f32));
+ }
+ if (blitParamUbo_ == BufferHandle::Invalid) {
+ blitParamUbo_ = device_.createBuffer({GfxBufferUsage::Uniform, layout->blockSize, /*dynamic=*/true},
+ GfxContent::retained(), bytes.data());
+ } else {
+ device_.updateBuffer(blitParamUbo_, 0, bytes.data(), static_cast<u32>(bytes.size()));
+ }
+ blitParamAmount_ = amount;
+ }
+ device_.setUniformBuffer(MATERIAL_CONSTANTS_BINDING, blitParamUbo_);
+ }
+ for (const auto& slot : layout->textures) {
+ TextureHandle gpu = context_.materials().builtinDefault(slot.defaultTexture);
+ if (slot.name == "u_displayLut" && lastPass && display_lut_texture_ != 0) gpu = TextureHandle{display_lut_texture_};
+ if (gpu != TextureHandle::Invalid) device_.bindTexture(slot.unit, gpu);
+ }
+}
+
void PostProcessPipeline::runChain(std::vector<PostProcessPass>& passes, rg::ResourceId scene) {
if (!graph_ || scene == rg::kNoResource) return;
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hpp
index d59d5d1f6..4a6a98c3b 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp
@@ -384,12 +384,8 @@ public:
/**
* @brief Whether the scene goes through the graph or straight to the surface.
*
- * @details Four things engage it: effects to run, the linear pipeline (whose
- * final pass carries an encode a WebGL2 canvas framebuffer cannot do
- * for itself), an output transform, or a present that scales. One
- * predicate because everyone asks at both ends of a frame, and two
- * copies of it is one edit away from a capture that is opened and
- * never resolved.
+ * @details Effects to run, the linear pipeline, an output transform, a display LUT or a scaling present engage it. One predicate, because
+ * everyone asks at both ends of a frame and a capture opened but never resolved is one edit away.
*/
bool isEngaged() const {
// `initialized_` leads, and that is load-bearing: init refuses when the
@@ -397,6 +393,7 @@ public:
// to drawing straight at the surface rather than to a black frame.
return initialized_ && ((!bypass_ && !passes_.empty()) || linear_output_
|| output_transform_ != OutputTransform::None
+ || displayLutActive()
|| view_exposure_ != 0.0f
|| presentScales() || present_required_);
}
@@ -491,6 +488,20 @@ public:
* than a pass of its own.
*/
void setOutputTransform(OutputTransform transform) { output_transform_ = transform; }
+ /**
+ * @brief A graded look the final pass applies to the picture as the display will show it.
+ *
+ * @details The display stage of the last pass: after the output transform and the transfer function, from a 32x32x32 table laid out as
+ * a 1024x32 strip (slice along x is blue). It is a variant of that shader, so it costs one texture read and no pass. It belongs
+ * to the chain that set it, and is let go with the passes (clearPasses): a camera that wants it says so each time.
+ * @param glTexture The table's texture, or 0 for none.
+ * @param amount How far the picture moves toward the table's answer, 0 to 1.
+ */
+ void setDisplayLut(u32 glTexture, f32 amount) {
+ display_lut_texture_ = glTexture;
+ display_lut_amount_ = std::isfinite(amount) ? std::clamp(amount, 0.0f, 1.0f) : 0.0f;
+ }
+ bool displayLutActive() const { return display_lut_texture_ != 0 && display_lut_amount_ > 0.0f; }
/// The editor view's exposure in stops, applied by the blit. Engages the blit when
/// non-zero, since only the blit carries it; the value rides the frame's time block.
void setViewExposure(f32 ev);
@@ -596,8 +607,12 @@ private:
/// The chain's last pass: the output transform, then the copy into the
/// output target's viewport.
void blitPass();
- /// The blit variant the current output transform needs, compiled on demand.
+ /// The blit variant the current output transform, present and display LUT need, compiled on demand.
resource::ShaderHandle outputShader();
+ /// The variant of the blit with these features, or an invalid handle when it does not compile.
+ resource::ShaderHandle blitVariant(bool upscale, OutputTransform transform, bool lut);
+ /// Binds what every variant of the blit declares: its parameter block (the display LUT's amount) and the table's texture.
+ void bindBlitInputs(const resource::ShaderHandle& shader);
/// One variant of blit.esshader, by feature.
resource::ShaderHandle compileBlit(const std::vector<std::string>& features);
/// Frees a pass's GPU-side param UBO (clearPasses/shutdown).
@@ -613,11 +628,14 @@ private:
VertexLayoutHandle screen_quad_layout_ = VertexLayoutHandle::Invalid;
BufferHandle screen_quad_vbo_ = BufferHandle::Invalid;
resource::ShaderHandle blitShader_;
- /// The ES_TONEMAP variant of the same file. Invalid until a chain asks for it.
- resource::ShaderHandle tonemapShader_;
- resource::ShaderHandle neutralShader_;
- /// The same three blits (plain, neutral, ACES) with the resampling upscaler, compiled when a present first needs one.
- resource::ShaderHandle upscaleShaders_[3];
+ /// The other variants of the same file the last pass needs (a curve, the resampling upscaler, the display LUT), by feature set, compiled when
+ /// a chain first asks. An invalid handle is a variant that would not compile: asked for once, not again.
+ std::unordered_map<u32, resource::ShaderHandle> blitVariants_;
+ u32 display_lut_texture_ = 0;
+ f32 display_lut_amount_ = 0.0f;
+ /// The last pass's parameter block (the display LUT's amount): one for every variant of the blit, written when the amount changes.
+ BufferHandle blitParamUbo_ = BufferHandle::Invalid;
+ f32 blitParamAmount_ = -1.0f;
resource::ShaderHandle copyShader_;
resource::ShaderHandle copyDepthShader_;
diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
index 1bf0a5739..bb05860c7 100644
--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
@@ -245,6 +245,10 @@ inline constexpr const char* BLIT = R"esshader(#pragma shader "Blit"
#pragma version 300 es
#pragma domain PostProcess
+
+#pragma param u_displayLut texture default(white)
+#pragma param u_displayLutAmount float default(0)
+
#pragma fragment
precision highp float;
@@ -290,6 +294,20 @@ vec4 upscale(vec2 uv) {
}
#endif
+#ifdef ES_DISPLAY_LUT
+vec3 displayLookup(vec3 c) {
+ const float size = 32.0;
+ float b = clamp(c.b, 0.0, 1.0) * (size - 1.0);
+ float slice0 = floor(b);
+ float slice1 = min(slice0 + 1.0, size - 1.0);
+ float u = (clamp(c.r, 0.0, 1.0) * (size - 1.0) + 0.5) / (size * size);
+ float v = (clamp(c.g, 0.0, 1.0) * (size - 1.0) + 0.5) / size;
+ vec3 a = texture(u_displayLut, vec2(u + slice0 / size, v)).rgb;
+ vec3 d = texture(u_displayLut, vec2(u + slice1 / size, v)).rgb;
+ return mix(a, d, b - slice0);
+}
+#endif
+
void main() {
#ifdef ES_COPY_DEPTH
@@ -327,10 +345,15 @@ void main() {
#ifdef ES_LINEAR
- fragColor = vec4(linearToSrgb(c.rgb), c.a);
+ vec3 shown = linearToSrgb(c.rgb);
#else
- fragColor = c;
+ vec3 shown = c.rgb;
#endif
+#ifdef ES_DISPLAY_LUT
+
+ shown = mix(shown, displayLookup(shown), clamp(u_displayLutAmount, 0.0, 1.0));
+#endif
+ fragColor = vec4(shown, c.a);
}
#pragma end
@@ -367,6 +390,20 @@ fn upscale(uv : vec2f) -> vec4f {
}
#endif
+#ifdef ES_DISPLAY_LUT
+fn displayLookup(c : vec3f) -> vec3f {
+ let size = 32.0;
+ let b = clamp(c.b, 0.0, 1.0) * (size - 1.0);
+ let slice0 = floor(b);
+ let slice1 = min(slice0 + 1.0, size - 1.0);
+ let u = (clamp(c.r, 0.0, 1.0) * (size - 1.0) + 0.5) / (size * size);
+ let v = (clamp(c.g, 0.0, 1.0) * (size - 1.0) + 0.5) / size;
+ let a = textureSampleLevel(u_displayLut, u_displayLut_s, vec2f(u + slice0 / size, v), 0.0).rgb;
+ let d = textureSampleLevel(u_displayLut, u_displayLut_s, vec2f(u + slice1 / size, v), 0.0).rgb;
+ return mix(a, d, b - slice0);
+}
+#endif
+
@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
#ifdef ES_COPY_DEPTH
let depthSize = vec2i(textureDimensions(t7, 0));
@@ -392,10 +429,14 @@ fn upscale(uv : vec2f) -> vec4f {
c = vec4f(pbrNeutral(c.rgb), c.a);
#endif
#ifdef ES_LINEAR
- return vec4f(linearToSrgb(c.rgb), c.a);
+ var shown = linearToSrgb(c.rgb);
#else
- return c;
+ var shown = c.rgb;
+#endif
+#ifdef ES_DISPLAY_LUT
+ shown = mix(shown, displayLookup(shown), clamp(mc.u_displayLutAmount, 0.0, 1.0));
#endif
+ return vec4f(shown, c.a);
}
#pragma end
)esshader";
diff --git a/src/esengine/renderer/store/MaterialStore.cpp b/src/esengine/renderer/store/MaterialStore.cpp
index 9599ef455..6401a6cf3 100644
--- a/src/esengine/renderer/store/MaterialStore.cpp
+++ b/src/esengine/renderer/store/MaterialStore.cpp
@@ -16,6 +16,9 @@
#include "../../core/Log.hpp"
#include "../rhi/ShaderEmbeds.generated.hpp"
+#include <cstdlib>
+#include <sstream>
+
namespace esengine {
MaterialStore::~MaterialStore() {
@@ -241,6 +244,57 @@ u32 MaterialStore::variantProgram(u32 materialId, resource::ResourceManager& res
return program;
}
+namespace {
+
+/// Float component count for a std140 param type (textures have no block slot).
+u32 paramArity(resource::ShaderPropertyType t) {
+ using PT = resource::ShaderPropertyType;
+ switch (t) {
+ case PT::Float: case PT::Int: return 1;
+ case PT::Vec2: return 2;
+ case PT::Vec3: return 3;
+ case PT::Vec4: case PT::Color: return 4;
+ default: return 0;
+ }
+}
+
+} // namespace
+
+MaterialUniformLayout MaterialStore::layoutOf(const resource::ParsedShader& parsed) {
+ MaterialUniformLayout layout;
+ layout.blockSize = parsed.materialBlockSize;
+ layout.coverageParam = parsed.coverageParam;
+ layout.tipParam = parsed.tipParam;
+ layout.hairShadowParam = parsed.hairShadowParam;
+ layout.usesGBuffer = parsed.usesGBuffer;
+ layout.usesLights = parsed.usesLights;
+ layout.highPrecision = parsed.highPrecision;
+ layout.vertexBounds = parsed.vertexBounds;
+ layout.vertexHook = !parsed.vertexHook.empty();
+ for (const auto& p : parsed.properties) {
+ if (!p.fromParam) continue;
+ if (p.type == resource::ShaderPropertyType::Texture) {
+ if (p.textureUnit >= 0) {
+ // Resolve the param's `default(<name>)` to a built-in default texture, bound when
+ // a material leaves the param unset.
+ layout.textures.push_back({ p.name, static_cast<u32>(p.textureUnit),
+ materialDefaultByName(p.defaultValue) });
+ }
+ } else if (p.std140Offset >= 0) {
+ MaterialParamSlot slot{ p.name, static_cast<u32>(p.std140Offset), paramArity(p.type) };
+ // default(a,b,c,d) csv -> the slot's initial block value.
+ std::istringstream csv(p.defaultValue);
+ std::string tok;
+ for (u32 i = 0; i < slot.arity && std::getline(csv, tok, ','); ++i) {
+ slot.defaults[i] = std::strtof(tok.c_str(), nullptr);
+ }
+ layout.params.push_back(slot);
+ }
+ }
+ return layout;
+}
+
+
void MaterialStore::seedSamplers(Shader& shader, const resource::ParsedShader& parsed) {
if (shader.language() != GfxShaderLanguage::GLSL_ES300) return;
shader.bind();
diff --git a/src/esengine/renderer/store/MaterialStore.hpp b/src/esengine/renderer/store/MaterialStore.hpp
index ffb6dd9f7..c45b10271 100644
--- a/src/esengine/renderer/store/MaterialStore.hpp
+++ b/src/esengine/renderer/store/MaterialStore.hpp
@@ -187,6 +187,11 @@ public:
*/
static void seedSamplers(Shader& shader, const resource::ParsedShader& parsed);
+ /// The layout a parsed shader's `#pragma param` reflection describes: the std140 block for the scalar and vector params (declared order
+ /// is offset order) and a sampler slot for each texture param, at the unit the parser gave it. Material shaders and the chain's own
+ /// last pass read their parameters through the same one.
+ static MaterialUniformLayout layoutOf(const resource::ParsedShader& parsed);
+
/// Keeps a material shader's SOURCE beside its handle, so the same material can
/// be compiled for another vertex source later. Without it the store holds only
/// the assembled program and a variant would need the author's file again.
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 4b6c93e84..58ce0d984 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2844,6 +2844,10 @@ export const NOTED = {
{"internal":"Hides parameters the engine writes itself."},
"feat(examples): Terrain & Water has a thin high haze whose beams follow the clouds":
{"note":"Light beams that follow the clouds."},
+ "feat(postprocess): a display LUT in the last pass grades the picture as the display shows it, after the output transform":
+ {"note":"A Display LUT."},
+ "feat(examples): Terrain & Water is graded warm by a display LUT":
+ {"note":"A Display LUT."},
"feat(water): two tiled, scrolling detail normal maps give the surface its sparkle":
{"note":"Sparkle on the water."},
"fix(lod): a LODGroup with only a cull size is no longer ignored":