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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdindex 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.mdxindex 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 itneeds 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 thechain. 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.mdxindex 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.mdindex f4f9cc4cf..52d411340 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -3747,6 +3747,7 @@ fallback: EffectSubPass[] | undefinedlabel: stringmultiPass: EffectSubPass[] | undefinednative: string | undefined+stage: "output" | undefinedtextures: EffectTextureDef[] | undefinedtype: stringuniforms: EffectUniformDef[]@@ -7179,6 +7180,7 @@ addPass: (name: string, shader: ShaderHandle, scale?: number, continuesEffect?:clearDirty: () => voidclearPasses: () => PostProcessStackdestroy: () => void+displayLut: { readonly texture: number; readonly amount: number; }enabledPassCount: numberid: numberisDestroyed: boolean@@ -7187,6 +7189,7 @@ passCount: numberpasses: readonly PassConfig[]removePass: (name: string) => PostProcessStacksetAllPassesEnabled: (enabled: boolean) => void+setDisplayLut: (texture: number, amount: number) => PostProcessStacksetEnabled: (name: string, enabled: boolean) => PostProcessStacksetTexture: (passName: string, uniform: string, textureHandle: number) => PostProcessStacksetUniform: (passName: string, uniform: string, value: number) => PostProcessStackdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex a6659e491..36c743bcc 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -3755,6 +3755,7 @@ fallback: EffectSubPass[] | undefinedlabel: stringmultiPass: EffectSubPass[] | undefinednative: string | undefined+stage: "output" | undefinedtextures: EffectTextureDef[] | undefinedtype: stringuniforms: EffectUniformDef[]@@ -7382,6 +7383,7 @@ addPass: (name: string, shader: ShaderHandle, scale?: number, continuesEffect?:clearDirty: () => voidclearPasses: () => PostProcessStackdestroy: () => void+displayLut: { readonly texture: number; readonly amount: number; }enabledPassCount: numberid: numberisDestroyed: boolean@@ -7390,6 +7392,7 @@ passCount: numberpasses: readonly PassConfig[]removePass: (name: string) => PostProcessStacksetAllPassesEnabled: (enabled: boolean) => void+setDisplayLut: (texture: number, amount: number) => PostProcessStacksetEnabled: (name: string, enabled: boolean) => PostProcessStacksetTexture: (passName: string, uniform: string, textureHandle: number) => PostProcessStacksetUniform: (passName: string, uniform: string, value: number) => PostProcessStackdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 506c9bf52..89648e452 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -3742,6 +3742,7 @@ fallback: EffectSubPass[] | undefinedlabel: stringmultiPass: EffectSubPass[] | undefinednative: string | undefined+stage: "output" | undefinedtextures: EffectTextureDef[] | undefinedtype: stringuniforms: EffectUniformDef[]@@ -7174,6 +7175,7 @@ addPass: (name: string, shader: ShaderHandle, scale?: number, continuesEffect?:clearDirty: () => voidclearPasses: () => PostProcessStackdestroy: () => void+displayLut: { readonly texture: number; readonly amount: number; }enabledPassCount: numberid: numberisDestroyed: boolean@@ -7182,6 +7184,7 @@ passCount: numberpasses: readonly PassConfig[]removePass: (name: string) => PostProcessStacksetAllPassesEnabled: (enabled: boolean) => void+setDisplayLut: (texture: number, amount: number) => PostProcessStacksetEnabled: (name: string, enabled: boolean) => PostProcessStacksetTexture: (passName: string, uniform: string, textureHandle: number) => PostProcessStacksetUniform: (passName: string, uniform: string, value: number) => PostProcessStackdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 417b75553..f2654a543 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -3742,6 +3742,7 @@ fallback: EffectSubPass[] | undefinedlabel: stringmultiPass: EffectSubPass[] | undefinednative: string | undefined+stage: "output" | undefinedtextures: EffectTextureDef[] | undefinedtype: stringuniforms: EffectUniformDef[]@@ -7467,6 +7468,7 @@ addPass: (name: string, shader: ShaderHandle, scale?: number, continuesEffect?:clearDirty: () => voidclearPasses: () => PostProcessStackdestroy: () => void+displayLut: { readonly texture: number; readonly amount: number; }enabledPassCount: numberid: numberisDestroyed: boolean@@ -7475,6 +7477,7 @@ passCount: numberpasses: readonly PassConfig[]removePass: (name: string) => PostProcessStacksetAllPassesEnabled: (enabled: boolean) => void+setDisplayLut: (texture: number, amount: number) => PostProcessStacksetEnabled: (name: string, enabled: boolean) => PostProcessStacksetTexture: (passName: string, uniform: string, textureHandle: number) => PostProcessStacksetUniform: (passName: string, uniform: string, value: number) => PostProcessStackdiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex d5d78b6ad..95c358bb5 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -410,6 +410,7 @@ postprocess_isInitialized: () => booleanpostprocess_maxMsaaSamples: (() => number) | undefinedpostprocess_resize: (width: number, height: number) => voidpostprocess_setBypass: (bypass: boolean) => void+postprocess_setDisplayLut: ((textureHandle: number, amount: number) => void) | undefinedpostprocess_setMsaaSamples: (samples: number) => voidpostprocess_setOutputTransform: ((transform: number) => void) | undefinedpostprocess_setOutputViewport: (x: number, y: number, w: number, h: number) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 9356a941d..2e91e2d0f 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -3742,6 +3742,7 @@ fallback: EffectSubPass[] | undefinedlabel: stringmultiPass: EffectSubPass[] | undefinednative: string | undefined+stage: "output" | undefinedtextures: EffectTextureDef[] | undefinedtype: stringuniforms: EffectUniformDef[]@@ -7181,6 +7182,7 @@ addPass: (name: string, shader: ShaderHandle, scale?: number, continuesEffect?:clearDirty: () => voidclearPasses: () => PostProcessStackdestroy: () => void+displayLut: { readonly texture: number; readonly amount: number; }enabledPassCount: numberid: numberisDestroyed: boolean@@ -7189,6 +7191,7 @@ passCount: numberpasses: readonly PassConfig[]removePass: (name: string) => PostProcessStacksetAllPassesEnabled: (enabled: boolean) => void+setDisplayLut: (texture: number, amount: number) => PostProcessStacksetEnabled: (name: string, enabled: boolean) => PostProcessStacksetTexture: (passName: string, uniform: string, textureHandle: number) => PostProcessStacksetUniform: (passName: string, uniform: string, value: number) => PostProcessStackdiff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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<PostProcesstype 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.tsindex 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.tsnew file mode 100644index 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.cppindex 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& featuif (!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.cppindex 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.hppindex 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.cppindex 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.esshaderindex 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 fragmentprecision 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_DEPTHlet 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 enddiff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex 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::PassContevoid 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.hppindex 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.hppindex 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 fragmentprecision 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_DEPTHlet 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.cppindex 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& resreturn 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.hppindex 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.mjsindex 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":