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(render): a Neutral output transform keeps hue and saturation where ACES walks a lit red to cream
yhh1cab6141a705
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4559bf527..76ba770ab 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ published separately; it ships inside the editor.### Added+- **A Neutral output transform.** The output transform has a Neutral option that keeps hue and saturation. The output transform is the one curve a finished frame goes through on its way to the display; None only encodes and ACES rolls highlights off a filmic shoulder, but ACES also desaturates as it goes, so a brightly lit red drifts toward cream. Neutral (Khronos PBR Neutral) rolls highlights off in the same way and leaves colour alone, so a sunlit red awning stays red. Pick it in Settings → Project → Rendering, or set `outputTransform: 'neutral'`; it applies to the viewport, Play and every export, on WebGL2 and WebGPU alike.- **Static batching.** Static meshes that share a material can be drawn as one. Add `StaticBatch` to a mesh that will not move, and the meshes that share its material, texture, colour and layer are merged while the game runs into one mesh per area, so a level built from many different props costs a few draws instead of one per distinct mesh. The renderer already drew copies of the same mesh as one instanced draw; this is for different meshes. The marked entities stay as authored — scripts find them, colliders collide, the editor picks them — and only their drawing moves to the merged mesh. A mesh is left out, and the reason recorded, when it is skinned, morphing, a level-of-detail group, blended, moving (a dynamic body or a character), lit by a bake or a probe volume, or alone in its group. Merging copies each part's vertices, so it spends memory to save draws; `StaticBatching` reports each merged mesh's size and what drawing its parts cost before. In the editor the outliner's menu marks the selected meshes, a marked mesh's Details say whether it merged and why not, and the profiler lists every merged mesh and the meshes left out.- **Camera shots and nested sequences on the timeline.** Timelines have camera and sequence tracks. A camera track is a row of shots: each bar is the camera that is the view for its span, bars that touch cut, and a bar dragged over the previous one blends across the overlap with its own curve. A sequence track plays another timeline in a window of this one, on its own clock, with a speed, a loop, and a node to bind to so one sequence can play on different characters. A timeline cannot play itself, directly or through another, and nesting stops at four levels. The Sequencer shows both as bars above the object tracks, with the shot or clip in Details, and the viewport's camera preview follows the shot while you scrub. Which shot and which nested frame show is a function of time alone, so scrubbing, jumping and playing backwards agree.diff --git a/README.md b/README.mdindex b3ccfc67e..7cf07b08b 100644--- a/README.md+++ b/README.md@@ -24,9 +24,9 @@Estella is a **2D and 3D game engine** — sprites, tilemaps and UI as much as lit, shadowed, physically simulated 3D worlds — with a TypeScript SDK driven by a high-performance **C++** core — as WebAssembly on the web, and compiled ahead of time on native platforms. It outputs games that run in **web browsers**, on the **desktop**, in **WeChat MiniGames**, as single-file **playable ads**, and as native **Android / iOS** apps. A visual editor is available as a separate, free download.<div align="center">- <img src="docs/assets/hero-cf5bccde.png" alt="A Paris street corner in daylight, rendered in real time by the Estella engine" width="900" />+ <img src="docs/assets/hero-630f124c.png" alt="A Paris street corner in daylight, rendered in real time by the Estella engine" width="900" /><br/>- <sub><i>Amazon Lumberyard Bistro, rendered in real time by Estella (a sun that follows the sky, baked bounce light and reflections, post-processing). Scene © Amazon Lumberyard, <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>, modified.</i></sub>+ <sub><i>Amazon Lumberyard Bistro, rendered in real time by Estella (a sun that follows the sky, baked bounce light and reflections, the Neutral output transform). Scene © Amazon Lumberyard, <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>, modified.</i></sub></div>## Why Estella?diff --git a/desktop b/desktopindex 8548e7cfe..fa526a489 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 8548e7cfe697a9e87b6d8279418223d965a3811c+Subproject commit fa526a48954a22aa2e87f9bf9219494f520fb1f9diff --git a/docs/ROADMAP_BLOCKED_2026-10-16.md b/docs/ROADMAP_BLOCKED_2026-10-16.mdnew file mode 100644index 000000000..7e3d6fc9a--- /dev/null+++ b/docs/ROADMAP_BLOCKED_2026-10-16.md@@ -0,0 +1,84 @@+# Roadmap maintenance blocked — 2026-10-16 11:49 UTC++Command execution recovered. Reading Project 8 still fails before authentication because the sandbox denies GitHub CLI/config.yml. This does not establish an expired login or missing project scope. No authorization retry or permission bypass attempted.++Read local git status and AGENTS.md. The current policy treats 2D and 3D equally. Existing edits in build-tools/build.config.js, cmake/Emscripten.cmake and desktop, and untracked games were left untouched. Cached origin/master is 1d945263b22ba539f76bda2892dd3a5bed92a257; pinned editor is 47d797d1d96ac0b2b7a2d541cd712b5a1c26f44f. These are cached references, not freshly fetched remote evidence.++Previous docs/ROADMAP_BLOCKED_2026-09-28.md is no longer present. No roadmap files were returned by the docs filename search. Do not reconstruct an old snapshot from conversation history or overwrite user changes.++No new requirements or remote mutations. Latest release, PR merge status and acceptance evidence remain unverified. No engine edits, visible applications, tags or releases. This local blocker record is not committed: .git is read-only under the current sandbox, and GitHub CLI access is blocked. Resume with a fresh full Project read after environment access is restored.++## 2026-10-16 18:47 UTC recheck++Project read still fails before authentication: GitHub CLI/config.yml access denied (exit 1). No fresh draft inventory, release or PR acceptance verification obtained. No remote changes, snapshot replacement or engine edits; no new pending requirements. Same reported sandbox blocker, no repeated authorization request. 2D and 3D remain equal priorities. This log remains local and uncommitted under the read-only .git restriction.+++## 2026-10-17 01:47 UTC recheck++Project read again fails before authentication because GitHub CLI/config.yml is inaccessible (exit 1). No new remote evidence or pending requirements. No card, snapshot or engine changes; latest release and acceptance evidence remain unverified. Same reported sandbox blocker; no authorization retry. This local log is uncommitted because .git remains read-only.+++## 2026-10-17 08:44 UTC recheck++GitHub Project read remains blocked before authentication: access denied to GitHub CLI/config.yml (exit 1). No latest draft inventory, release or acceptance evidence obtained. No new pending requirements; no remote card, snapshot or engine changes. No repeated authorization request or sandbox bypass. Local record remains uncommitted under the read-only .git restriction.+++## 2026-10-17 15:46 UTC recheck++Project read still fails before authentication because the sandbox denies GitHub CLI/config.yml (exit 1). Latest drafts, releases and verification evidence were not obtained. No new pending requirements or changes to remote cards, snapshots or engine code. Same reported blocker; no repeated authorization request. This local log remains uncommitted under the read-only .git restriction.+++## 2026-10-17 22:50 UTC recheck++GitHub Project read still fails before authentication: access denied to GitHub CLI/config.yml (exit 1). No latest drafts, release or acceptance evidence obtained. No new pending requirements; remote cards, snapshots and engine code remain untouched. Same reported sandbox blocker, no repeated authorization request. Local record remains uncommitted under the read-only .git restriction.+++## 2026-10-18 05:49 UTC recheck++Project read remains blocked before authentication: the sandbox denies GitHub CLI/config.yml (exit 1). Latest drafts, release and acceptance evidence were not obtained. No new pending requirements or changes to remote cards, snapshots or engine code. Same reported blocker; no repeated authorization request. Local log remains uncommitted under the read-only .git restriction.+++## 2026-10-18 12:54 UTC recheck++Project read again fails before authentication: access denied to GitHub CLI/config.yml (exit 1). No latest draft inventory, release or acceptance evidence obtained. No remote card, snapshot or engine changes; no new pending requirements. Same reported sandbox blocker, no repeated authorization request. Local record remains uncommitted under the read-only .git restriction.+++## 2026-10-18 19:56 UTC recheck++Project read still fails before authentication: GitHub CLI/config.yml access denied (exit 1). Latest drafts, releases and verification evidence were not obtained. No new pending requirements or changes to remote cards, snapshots or engine code. Same reported sandbox blocker; no repeated authorization request. Local record remains uncommitted under the read-only .git restriction.+++## 2026-10-19 02:57 UTC recheck++Project read remains blocked before authentication: access denied to GitHub CLI/config.yml (exit 1). No latest draft inventory, release or acceptance evidence obtained. No new pending requirements; remote cards, snapshots and engine code remain untouched. Same reported sandbox blocker; no repeated authorization request. Local record remains uncommitted under the read-only .git restriction.+++## 2026-10-19 10:01 UTC recheck++Project read still fails before authentication: GitHub CLI/config.yml access denied (exit 1). Latest drafts, releases and acceptance evidence remain unverified. No new pending requirements; no changes to remote cards, snapshots or engine code. Same reported sandbox blocker; no authorization retry or bypass. Local log remains uncommitted under the read-only .git restriction.+++## 2026-10-20 01:08 UTC recheck++Project read still fails before authentication: GitHub CLI/config.yml access denied (exit 1). No latest drafts, releases or acceptance evidence obtained. No new pending requirements; remote cards, snapshots and engine code remain untouched. Same reported sandbox blocker; no repeated authorization request or bypass. Local log remains uncommitted under the read-only .git restriction.+++## 2026-10-20 08:06 UTC recheck++Project read still fails before authentication: GitHub CLI/config.yml access denied (exit 1). Latest drafts, release and acceptance evidence remain unverified. No new pending requirements; no changes to remote cards, snapshots or engine code. Same reported sandbox blocker; no repeated authorization request or bypass. Local log remains uncommitted under the read-only .git restriction.+++## 2026-10-20 15:05 UTC recheck++Project read remains blocked before authentication: access denied to GitHub CLI/config.yml (exit 1). No latest drafts, releases or acceptance evidence obtained. No new pending requirements; remote cards, snapshots and engine code remain untouched. Same reported sandbox blocker; no repeated authorization request or bypass. Local log remains uncommitted under the read-only .git restriction.+++## 2026-10-20 22:02 UTC recheck++Project read still fails before authentication: GitHub CLI/config.yml access denied (exit 1). No latest drafts, releases or acceptance evidence obtained. No new pending requirements; remote cards, snapshots and engine code remain untouched. Same reported sandbox blocker; no repeated authorization request or bypass. Local log remains uncommitted under the read-only .git restriction.+++## 2026-10-21 05:06 UTC recheck++Project read remains blocked before authentication: access denied to GitHub CLI/config.yml (exit 1). Latest drafts, releases and acceptance evidence were not obtained. No new pending requirements; no changes to remote cards, snapshots or engine code. Same reported sandbox blocker; no repeated authorization request or bypass. Local log remains uncommitted under the read-only .git restriction.+diff --git a/docs/assets/hero-630f124c.png b/docs/assets/hero-630f124c.pngnew file mode 100644index 000000000..04b439bb7Binary files /dev/null and b/docs/assets/hero-630f124c.png differdiff --git a/docs/assets/hero-cf5bccde.png b/docs/assets/hero-cf5bccde.pngdeleted file mode 100644index 8990fae1d..000000000Binary files a/docs/assets/hero-cf5bccde.png and /dev/null differdiff --git a/docs/astro/src/content/docs/graphics/post-processing.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdxindex 159102f31..05a4f9689 100644--- a/docs/astro/src/content/docs/graphics/post-processing.mdx+++ b/docs/astro/src/content/docs/graphics/post-processing.mdx@@ -63,6 +63,28 @@ clamping at the 8-bit store:In gamma mode (or without float-target support) the chain is LDR and behaves asbefore; a `threshold` above ~0.75 then never fires.+## Output transform++A scene lit in linear space can hold light brighter than a display can show. The+**output transform** is the one curve the finished frame goes through on its way to+the screen — **once, after every effect** — and it is a project setting, not an+effect: **Settings → Project → Rendering → Output transform**.++| Transform | What it does | Use it for |+| --- | --- | --- |+| **None** | Encodes only. Values above 1 clip. | Flat 2D art, UI, anything that must round-trip exactly. |+| **ACES** | A filmic shoulder: highlights roll off, shadows deepen. It desaturates as it goes, so a very bright red drifts toward cream. | Lit 3D scenes that want a filmic look. |+| **Neutral** | Khronos PBR Neutral: the same roll-off, but hue and saturation survive. A sunlit red stays red. | Product shots, stylised art, anything whose colours are the point. |++It applies to the editor viewport, to Play and to every export, and changing it+needs no reload. In code: `outputTransform: 'none' | 'aces' | 'neutral'`.++<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:+pick the output transform and leave the effect off.+</Aside>+## Using a `PostProcessVolume`Add a `PostProcessVolume`, enable effects, and set their parameters. Volumesdiff --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 5950d8b51..1b4f1f0da 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@@ -53,6 +53,24 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess伽马模式(或无浮点目标能力)下效果链仍是 LDR,行为与从前一致;此时 `threshold` 超过约 0.75就永远不会触发。+## 输出变换++在线性空间里打光的场景,亮度可以超出显示器能显示的范围。**输出变换**是成品帧在送往屏幕前经过的唯一一条曲线——+**在所有效果之后、只作用一次**——它是项目设置,不是效果:**设置 → 项目 → 渲染 → 输出变换**。++| 变换 | 作用 | 适用 |+| --- | --- | --- |+| **无** | 只做编码。大于 1 的值被截断。 | 平面 2D 美术、UI,以及必须原样往返的内容。 |+| **ACES** | 电影式高光肩部:高光收卷、暗部加深。它会一路去饱和,所以很亮的红色会偏向奶白。 | 想要电影质感的 3D 光照场景。 |+| **中性** | Khronos PBR Neutral:同样收卷高光,但色相和饱和度保留。阳光下的红色仍是红色。 | 产品展示、风格化美术,以及颜色本身就是重点的内容。 |++它对编辑器视口、运行预览和所有导出都生效,改动无需重新加载。代码里是 `outputTransform: 'none' | 'aces' | 'neutral'`。++<Aside>+上面列表里的 `tonemap` *效果*是效果链里一个单独的、可选的 ACES 通道。设了输出变换之后,通常既不需要它,也不需要第二条曲线:+选输出变换,把这个效果关掉。+</Aside>+## 使用 `PostProcessVolume`加一个 `PostProcessVolume`,启用效果,设置参数。体积**在重叠处混合**,所以你可以按区域驱动diff --git a/docs/landing/hero-630f124c.png b/docs/landing/hero-630f124c.pngnew file mode 100644index 000000000..04b439bb7Binary files /dev/null and b/docs/landing/hero-630f124c.png differdiff --git a/docs/landing/hero-cf5bccde.png b/docs/landing/hero-cf5bccde.pngdeleted file mode 100644index 8990fae1d..000000000Binary files a/docs/landing/hero-cf5bccde.png and /dev/null differdiff --git a/docs/landing/index.html b/docs/landing/index.htmlindex a749ab017..2949404da 100644--- a/docs/landing/index.html+++ b/docs/landing/index.html@@ -446,9 +446,9 @@<div class="shot"><figure>- <img src="/hero-cf5bccde.png" width="1742" height="980"+ <img src="/hero-630f124c.png" width="1742" height="980"alt="A Paris street corner in daylight, rendered in real time by the Estella engine: a cafe, a scooter, cobbles and sun shadows" loading="lazy" />- <figcaption>Amazon Lumberyard Bistro, rendered in real time by Estella — a sun that follows the sky, baked bounce light and reflections, post-processing. Scene © Amazon Lumberyard, <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>, modified.</figcaption>+ <figcaption>Amazon Lumberyard Bistro, rendered in real time by Estella — a sun that follows the sky, baked bounce light and reflections, the Neutral output transform. Scene © Amazon Lumberyard, <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>, modified.</figcaption></figure></div></section>diff --git a/examples/bistro/README.md b/examples/bistro/README.mdindex 286cbb8d2..0348463ec 100644--- a/examples/bistro/README.md+++ b/examples/bistro/README.md@@ -28,4 +28,4 @@ node pipeline/bin/estella.mjs bake-scene examples/bistro/assets/scenes/main.essc```The sun is the sky's own (`followEnvironmentSun`), the sky is turned half a revolution, and the project-renders in linear light with the ACES output transform. Leaves, flowers and ivy are cut out by alpha and bake like everything else.\ No newline at end of file+renders in linear light with the Neutral output transform, which keeps the awnings red where ACES walks them to cream. Leaves, flowers and ivy are cut out by alpha and bake like everything else.\ No newline at end of filediff --git a/examples/bistro/assets/scenes/main.esscene b/examples/bistro/assets/scenes/main.essceneindex d472faeb3..e54321724 100644--- a/examples/bistro/assets/scenes/main.esscene+++ b/examples/bistro/assets/scenes/main.esscene@@ -57,7 +57,7 @@"type": "colorGrade","enabled": true,"uniforms": {- "u_exposure": -0.8,+ "u_exposure": 0.1,"u_contrast": 1.04,"u_saturation": 1.08,"u_temperature": 0,diff --git a/examples/bistro/project.esproject b/examples/bistro/project.esprojectindex f8404e74f..657d772cd 100644--- a/examples/bistro/project.esproject+++ b/examples/bistro/project.esproject@@ -13,7 +13,7 @@"features": {"rendering": {"colorSpace": "linear",- "outputTransform": "aces"+ "outputTransform": "neutral"}}}\ No newline at end of filediff --git a/pipeline/src/project/format.ts b/pipeline/src/project/format.tsindex 586d87759..d5cb0afa1 100644--- a/pipeline/src/project/format.ts+++ b/pipeline/src/project/format.ts@@ -171,9 +171,9 @@ export interface ProjectFeatures {* shaders compile against it. Absent ⇒ 'gamma'. */colorSpace?: 'linear';/** The curve the frame applies on its way to the display, once and last.- * 'aces' engages the capture on its own, so it applies with an empty effect+ * 'aces' and 'neutral' engage the capture on their own, so it applies with an empty effect* stack. Absent ⇒ none, which is the exact round trip flat content wants. */- outputTransform?: 'aces';+ outputTransform?: 'aces' | 'neutral';/** Multisampling for the scene target: 1 turns it off, 4 is the default and* what a browser gives its own drawing buffer. Clamped by what the device* supports. A low-end target turns this down; nothing else should. */@@ -814,7 +814,7 @@ export function parseManifest(raw: unknown): ProjectManifest {// Only 'linear' persists; 'gamma' (the default) is expressed by absence.if (r.colorSpace === 'linear') rendering.colorSpace = 'linear';// Same shape: only the curve persists, no transform is absence.- if (r.outputTransform === 'aces') rendering.outputTransform = 'aces';+ if (r.outputTransform === 'aces' || r.outputTransform === 'neutral') rendering.outputTransform = r.outputTransform;// Only a NON-default count persists; 4 is absence, like the fields above.if (r.msaa === 1 || r.msaa === 2 || r.msaa === 8) rendering.msaa = r.msaa;if (r.quality) {diff --git a/pipeline/src/project/runtimeConfig.ts b/pipeline/src/project/runtimeConfig.tsindex 2cbe749ff..1fec2efe5 100644--- a/pipeline/src/project/runtimeConfig.ts+++ b/pipeline/src/project/runtimeConfig.ts@@ -73,7 +73,7 @@ export interface RuntimeProjectConfig {/** Render colour space; 'gamma' is the default. Boot-fixed (shaders compile against it). */colorSpace: 'gamma' | 'linear';/** The curve on the way to the display; 'none' is the default. */- outputTransform: 'none' | 'aces';+ outputTransform: 'none' | 'aces' | 'neutral';/** Scene-target multisampling the project asks for; 4 is the default. The* device clamps it — this is the policy half, never the capability. */msaaSamples: number;@@ -158,7 +158,8 @@ export function runtimeConfigOf(ySortLayers: layerMask(f?.rendering?.ySortLayers),depthLayers: layerMask(f?.rendering?.depthLayers),colorSpace: f?.rendering?.colorSpace === 'linear' ? 'linear' : 'gamma',- outputTransform: f?.rendering?.outputTransform === 'aces' ? 'aces' : 'none',+ outputTransform: f?.rendering?.outputTransform === 'aces' ? 'aces'+ : f?.rendering?.outputTransform === 'neutral' ? 'neutral' : 'none',msaaSamples: msaaOf(f?.rendering?.msaa),quality: parseQualityConfig(f?.rendering?.quality),renderBackend: f?.rendering?.backend === 'webgpu' ? 'webgpu' : 'webgl2',@@ -200,7 +201,7 @@ export function packagedRuntimeFields(rc: RuntimeProjectConfig): PackagedRuntime...(rc.ySortLayers ? { ySortLayers: rc.ySortLayers } : {}),...(rc.depthLayers ? { depthLayers: rc.depthLayers } : {}),...(rc.colorSpace === 'linear' ? { colorSpace: rc.colorSpace } : {}),- ...(rc.outputTransform === 'aces' ? { outputTransform: rc.outputTransform } : {}),+ ...(rc.outputTransform !== 'none' ? { outputTransform: rc.outputTransform } : {}),...(rc.msaaSamples !== 4 ? { msaaSamples: rc.msaaSamples } : {}),...(rc.quality.mode !== 'off' ? { quality: rc.quality } : {}),...(rc.renderBackend === 'webgpu' ? { renderBackend: rc.renderBackend } : {}),diff --git a/pipeline/tests/project-rendering.test.ts b/pipeline/tests/project-rendering.test.tsindex ffb1c2bdd..89106eb97 100644--- a/pipeline/tests/project-rendering.test.ts+++ b/pipeline/tests/project-rendering.test.ts@@ -18,6 +18,11 @@ describe('parseManifest — rendering.outputTransform', () => {expect(m.features?.rendering?.outputTransform).toBe('aces');});+ it("keeps 'neutral' — the hue-preserving curve", () => {+ const m = parseManifest({ name: 'X', features: { rendering: { outputTransform: 'neutral' } } });+ expect(m.features?.rendering?.outputTransform).toBe('neutral');+ });+it("drops 'none' (default = absence) and junk values", () => {for (const v of ['none', 'ACES', 'filmic', 42, true, null]) {const m = parseManifest({ name: 'X', features: { rendering: { outputTransform: v } } });diff --git a/pipeline/tests/runtime-config.test.ts b/pipeline/tests/runtime-config.test.tsindex b75614d42..eb197a372 100644--- a/pipeline/tests/runtime-config.test.ts+++ b/pipeline/tests/runtime-config.test.ts@@ -97,6 +97,12 @@ describe('packagedRuntimeFields', () => {expect(fields.depthLayers).toBe(0b110);});+ it('reads the neutral output transform and ships it', () => {+ const rc = runtimeConfigOf({ features: { rendering: { outputTransform: 'neutral' } } });+ expect(rc.outputTransform).toBe('neutral');+ expect(packagedRuntimeFields(rc).outputTransform).toBe('neutral');+ });+it('carries every non-default and nothing else', () => {const fields = packagedRuntimeFields(runtimeConfigOf({designResolution: { width: 800, height: 600 },diff --git a/sdk/src/postprocess/PostProcessAPI.ts b/sdk/src/postprocess/PostProcessAPI.tsindex baa83c2ee..aa2c8d26d 100644--- a/sdk/src/postprocess/PostProcessAPI.ts+++ b/sdk/src/postprocess/PostProcessAPI.ts@@ -167,11 +167,13 @@ export function syncStackToWasm(stack: PostProcessStack, force = false,* The curve a frame applies on its way to the display — the pipeline's, not an* effect a stack happens to hold, so it runs once and last. `none` leaves values* alone, which is the exact round trip flat content wants; `aces` maps radiance- * above 1 down a filmic shoulder, which is what a lit 3D scene needs.+ * above 1 down a filmic shoulder, which is what a lit 3D scene needs; `neutral`+ * (Khronos PBR Neutral) rolls highlights off while keeping hue and saturation, so a+ * sunlit red stays red where `aces` walks it toward cream.** @experimental*/-export type OutputTransform = 'none' | 'aces';+export type OutputTransform = 'none' | 'aces' | 'neutral';/*** The curve's number at the wasm boundary. Here and not at each call: the@@ -179,7 +181,7 @@ export type OutputTransform = 'none' | 'aces';* them and been silently read as `none` by the other.*/export function outputTransformCode(transform: OutputTransform | undefined): number {- return transform === 'aces' ? 1 : 0;+ return transform === 'aces' ? 1 : transform === 'neutral' ? 2 : 0;}export class PostProcessAPI {diff --git a/sdk/src/runtime/packagedRuntime.ts b/sdk/src/runtime/packagedRuntime.tsindex b7d37bc68..d38df37a4 100644--- a/sdk/src/runtime/packagedRuntime.ts+++ b/sdk/src/runtime/packagedRuntime.ts@@ -65,7 +65,7 @@ export interface PackagedGameConfig {/** Project color space — 'linear' boots the linear-light pipeline. */colorSpace?: 'gamma' | 'linear';/** The curve the frame applies on the way to the display; absent = none. */- outputTransform?: 'none' | 'aces';+ outputTransform?: 'none' | 'aces' | 'neutral';/** Scene-target multisampling the project asked for; absent ⇒ 4. Clamped by* the device, which answers capability and never policy. */msaaSamples?: number;@@ -207,7 +207,7 @@ export function packagedAppOptions(ySortLayers?: number;depthLayers?: number;colorSpace?: 'gamma' | 'linear';- outputTransform?: 'none' | 'aces';+ outputTransform?: 'none' | 'aces' | 'neutral';msaaSamples?: number;quality?: QualityConfig;/** GPU backend the build asks for; absent ⇒ WebGL2. A request fordiff --git a/sdk/tests/postprocess.test.ts b/sdk/tests/postprocess.test.tsindex d3dfdc9b0..2c5df0886 100644--- a/sdk/tests/postprocess.test.ts+++ b/sdk/tests/postprocess.test.ts@@ -551,3 +551,13 @@ describe('PostProcess API', () => {});});});++describe('outputTransformCode', () => {+ it('spells each curve as the number the wasm boundary reads', async () => {+ const { outputTransformCode } = await import('../src/postprocess');+ expect(outputTransformCode(undefined)).toBe(0);+ expect(outputTransformCode('none')).toBe(0);+ expect(outputTransformCode('aces')).toBe(1);+ expect(outputTransformCode('neutral')).toBe(2);+ });+});diff --git a/sdk/tests/zz-alpha-png-repro.test.ts b/sdk/tests/zz-alpha-png-repro.test.tsnew file mode 100644index 000000000..e1059f3f2--- /dev/null+++ b/sdk/tests/zz-alpha-png-repro.test.ts@@ -0,0 +1,30 @@+import { describe, it } from 'vitest';+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { transcoderFromModule, type BasisWasmModule } from '../src/asset/basisTranscoder';+import { hasSideModule, loadSideModule } from './helpers/loadWasm';++describe.skipIf(!hasSideModule('basis'))('repro', () => {+ it('matrix', async () => {+ const transcoder = transcoderFromModule(await loadSideModule<BasisWasmModule>('basis'));+ const encoder = await import(path.join('D:/estella', 'build-tools/basis/encoder.mjs'));+ const png = new Uint8Array(readFileSync('D:/estella/examples/bistro/assets/models/Vespa_Headlight_BaseColor.png'));+ const rgba = new Uint8Array(16 * 16 * 4).map((_, i) => (i * 37) & 0xff);+ const cases: [string, any, any][] = [+ ['rgba uastc nomips', { type: encoder.ImageType.RGBA, data: rgba, width: 16, height: 16 }, { mode: 'uastc', mipmaps: false }],+ ['rgba uastc mips', { type: encoder.ImageType.RGBA, data: rgba, width: 16, height: 16 }, { mode: 'uastc', mipmaps: true }],+ ['rgba uastc mips zstd', { type: encoder.ImageType.RGBA, data: rgba, width: 16, height: 16 }, { mode: 'uastc', mipmaps: true, supercompress: true }],+ ['png uastc mips zstd', { type: encoder.ImageType.PNG, data: png }, { mode: 'uastc', mipmaps: true, supercompress: true, srgb: true }],+ ['png uastc mips', { type: encoder.ImageType.PNG, data: png }, { mode: 'uastc', mipmaps: true, srgb: true }],+ ['png uastc nomips', { type: encoder.ImageType.PNG, data: png }, { mode: 'uastc', mipmaps: false, srgb: true }],+ ['png etc1s mips', { type: encoder.ImageType.PNG, data: png }, { mode: 'etc1s', mipmaps: true, srgb: true }],+ ];+ for (const [label, img, opts] of cases) {+ try {+ const k = await encoder.encodeToKtx2(img, opts);+ const r = await transcoder.transcodeToRgba(k);+ console.log(label, k.length, 'rgba', !!r);+ } catch (e) { console.log(label, 'ENCODE THREW', String(e).slice(0, 100)); }+ }+ }, 120000);+});diff --git a/src/esengine/bindings/PostProcessBindings.cpp b/src/esengine/bindings/PostProcessBindings.cppindex b5952a264..d98f4a7d0 100644--- a/src/esengine/bindings/PostProcessBindings.cpp+++ b/src/esengine/bindings/PostProcessBindings.cpp@@ -169,7 +169,8 @@ void postprocess_setOutputTransform(u32 transform) {// An unknown value is the identity, not a guess: a project built against a// newer curve list must not get a different one silently.g_postProcessPipeline->setOutputTransform(transform == 1 ? OutputTransform::ACES- : OutputTransform::None);+ : transform == 2 ? OutputTransform::Neutral+ : OutputTransform::None);}void postprocess_setViewExposure(f32 ev) {diff --git a/src/esengine/data/shaders/blit.esshader b/src/esengine/data/shaders/blit.esshaderindex 96244e3b7..328589ef4 100644--- a/src/esengine/data/shaders/blit.esshader+++ b/src/esengine/data/shaders/blit.esshader@@ -20,6 +20,9 @@ void main() {// is a transfer function and not a look.c = vec4(acesFilmic(c.rgb), c.a);#endif+#ifdef ES_TONEMAP_NEUTRAL+ c = vec4(pbrNeutral(c.rgb), c.a);+#endif#ifdef ES_LINEAR// The one mandatory OETF: the chain upstream is linear (sRGB attachments// decode on sample), the canvas backbuffer is plain UNORM.@@ -37,6 +40,9 @@ void main() {#ifdef ES_TONEMAPc = vec4f(acesFilmic(c.rgb), c.a);#endif+#ifdef ES_TONEMAP_NEUTRAL+ c = vec4f(pbrNeutral(c.rgb), c.a);+#endif#ifdef ES_LINEARreturn vec4f(linearToSrgb(c.rgb), c.a);#elsediff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex 2a37b89cd..183a05936 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp@@ -96,6 +96,16 @@ void PostProcessPipeline::setViewExposure(f32 ev) {* than at init: a project that never asks for a curve never pays for one.*/resource::ShaderHandle PostProcessPipeline::outputShader() {+ 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"});@@ -195,6 +205,10 @@ void PostProcessPipeline::shutdown() {resourceManager_.releaseShader(tonemapShader_);tonemapShader_ = resource::ShaderHandle{};}+ if (neutralShader_.isValid()) {+ resourceManager_.releaseShader(neutralShader_);+ neutralShader_ = resource::ShaderHandle{};+ }initialized_ = false;ES_LOG_INFO("PostProcessPipeline shutdown");diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hppindex 311e38d37..5513c1e4f 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp@@ -45,6 +45,7 @@ namespace resource {enum class OutputTransform : u8 {None = 0, ///< Encode only. Values above 1 clip, which is what LDR content means.ACES = 1, ///< Narkowicz ACES filmic curve, for a scene that carries HDR radiance.+ Neutral = 2, ///< Khronos PBR Neutral: hue and saturation survive, highlights roll off.};/**@@ -419,6 +420,7 @@ private:resource::ShaderHandle blitShader_;/// The ES_TONEMAP variant of the same file. Invalid until a chain asks for it.resource::ShaderHandle tonemapShader_;+ resource::ShaderHandle neutralShader_;std::vector<PostProcessPass> passes_;u32 width_ = 0;diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hppindex 5580b654b..53a9835d1 100644--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp@@ -260,6 +260,9 @@ void main() {c = vec4(acesFilmic(c.rgb), c.a);#endif+#ifdef ES_TONEMAP_NEUTRAL+ c = vec4(pbrNeutral(c.rgb), c.a);+#endif#ifdef ES_LINEAR@@ -277,6 +280,9 @@ void main() {#ifdef ES_TONEMAPc = vec4f(acesFilmic(c.rgb), c.a);#endif+#ifdef ES_TONEMAP_NEUTRAL+ c = vec4f(pbrNeutral(c.rgb), c.a);+#endif#ifdef ES_LINEARreturn vec4f(linearToSrgb(c.rgb), c.a);#elsediff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex 69f758e1c..066e064e9 100644--- a/src/esengine/resource/ShaderParser.cpp+++ b/src/esengine/resource/ShaderParser.cpp@@ -1088,6 +1088,22 @@ fn linearToSrgb(c : vec3f) -> vec3f {fn acesFilmic(x : vec3f) -> vec3f {return clamp((x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14), vec3f(0.0), vec3f(1.0));}+fn pbrNeutral(color : vec3f) -> vec3f {+ let startCompression = 0.8 - 0.04;+ let desaturation = 0.15;+ var c = color;+ let x = min(c.r, min(c.g, c.b));+ var offset = 0.04;+ if (x < 0.08) { offset = x - 6.25 * x * x; }+ c = c - vec3f(offset);+ let peak = max(c.r, max(c.g, c.b));+ if (peak < startCompression) { return c; }+ let d = 1.0 - startCompression;+ let newPeak = 1.0 - d * d / (peak + d - startCompression);+ c = c * (newPeak / peak);+ let g = 1.0 - 1.0 / (desaturation * (peak - newPeak) + 1.0);+ return mix(c, vec3f(newPeak), g);+})";const char* kLitHeaderWGSL = R"(struct Light { posDir : vec4f, color : vec4f, spot : vec4f, shadow : vec4f, shadowMap : vec4f, falloff : vec4f };@@ -1840,6 +1856,22 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p// carries one applies it once, in the pass that also encodes."highp vec3 acesFilmic(highp vec3 x) {\n"" return clamp((x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14), 0.0, 1.0);\n"+ "}\n"+ // Khronos PBR Neutral (Apache-2.0, KhronosGroup/ToneMapping): hue and saturation+ // survive the curve, so a lit red stays red where ACES walks it to cream.+ "highp vec3 pbrNeutral(highp vec3 c) {\n"+ " const highp float startCompression = 0.8 - 0.04;\n"+ " const highp float desaturation = 0.15;\n"+ " highp float x = min(c.r, min(c.g, c.b));\n"+ " highp float offset = x < 0.08 ? x - 6.25 * x * x : 0.04;\n"+ " c -= offset;\n"+ " highp float peak = max(c.r, max(c.g, c.b));\n"+ " if (peak < startCompression) return c;\n"+ " const highp float d = 1.0 - startCompression;\n"+ " highp float newPeak = 1.0 - d * d / (peak + d - startCompression);\n"+ " c *= newPeak / peak;\n"+ " highp float g = 1.0 - 1.0 / (desaturation * (peak - newPeak) + 1.0);\n"+ " return mix(c, newPeak * vec3(1.0, 1.0, 1.0), g);\n""}\n";assembled << kColorHelpers;headerLines += countNewlines(kColorHelpers);diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex d2ce1b54d..911272721 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -2461,4 +2461,8 @@ export const NOTED = {{"note":"Timelines have camera and sequence tracks."},"feat(editor): the Sequencer edits camera shots and sequence clips":{"note":"Timelines have camera and sequence tracks."},+ "feat(render): a Neutral output transform keeps hue and saturation where ACES walks a lit red to cream":+ {"note":"The output transform has a Neutral option that keeps hue and saturation."},+ "feat(editor): the project's Output transform offers Neutral":+ {"note":"The output transform has a Neutral option that keeps hue and saturation."},};