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(environment): read OpenEXR panoramas, and low-dynamic-range pictures as a source
yhh5df7398d2b94
diff --git a/desktop b/desktopindex 670550635..adf3cf32e 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 670550635a47a567dbdf8ae202aeb2a9f9283ccf+Subproject commit adf3cf32e6ff92c050b214a0f5ff2215cb138b3fdiff --git a/fixtures/scenes/studio-preview-hdr.esscene b/fixtures/scenes/studio-preview-hdr.esscenenew file mode 100644index 000000000..aa3536a1b--- /dev/null+++ b/fixtures/scenes/studio-preview-hdr.esscene@@ -0,0 +1,144 @@+{+ "version": 4,+ "name": "StudioPreviewHdr",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 300+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 150,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Cube",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -75,+ "y": 0,+ "z": 0+ },+ "rotation": {+ "x": 0,+ "y": -0.3826834324,+ "z": 0,+ "w": 0.9238795325+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Sphere",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 75,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:sphere",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 4,+ "name": "Sky",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Light",+ "data": {+ "type": 2,+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "intensity": 1,+ "environment": "/scenes/studio.esenv",+ "drawEnvironment": true+ }+ }+ ]+ }+ ]+}diff --git a/fixtures/scenes/studio-preview-nolight.esscene b/fixtures/scenes/studio-preview-nolight.esscenenew file mode 100644index 000000000..669fe206f--- /dev/null+++ b/fixtures/scenes/studio-preview-nolight.esscene@@ -0,0 +1,110 @@+{+ "version": 4,+ "name": "StudioPreviewNoLight",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 300+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 150,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Cube",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -75,+ "y": 0,+ "z": 0+ },+ "rotation": {+ "x": 0,+ "y": -0.3826834324,+ "z": 0,+ "w": 0.9238795325+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:cube",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Sphere",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 75,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "builtin:sphere",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "lit": true,+ "opaque": true,+ "cullBackfaces": true,+ "enabled": true+ }+ }+ ]+ }+ ]+}diff --git a/pipeline/src/assets/environmentCube.ts b/pipeline/src/assets/environmentCube.tsindex 66de6de17..59175e8bb 100644--- a/pipeline/src/assets/environmentCube.ts+++ b/pipeline/src/assets/environmentCube.ts@@ -14,6 +14,7 @@* fixed per face with `rotate` and `flip`, never by editing the images.*/import type { Panorama } from './environmentImport';+import { SRGB_TO_LINEAR } from './ldrPanorama';export const CUBE_FACE_NAMES = ['px', 'nx', 'py', 'ny', 'pz', 'nz'] as const;export type CubeFaceName = typeof CUBE_FACE_NAMES[number];@@ -75,15 +76,6 @@ export function validateCubeFaces(faces: CubeFaceSet): void {}}-const SRGB_TO_LINEAR = (() => {- const lut = new Float32Array(256);- for (let i = 0; i < 256; i++) {- const c = i / 255;- lut[i] = c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);- }- return lut;-})();-/** A direction → the face it leaves through and where on it, in [0, 1]² of the face as* seen from inside, before any rotate or flip. */function faceOf(x: number, y: number, z: number): { face: CubeFaceName; a: number; b: number } {@@ -171,6 +163,12 @@ export interface CubeSourceDocument {/** How the images are encoded. PNG and JPEG are sRGB, the default. */colorSpace?: 'srgb' | 'linear';faces: Partial<Record<CubeFaceName, { file: string; rotate?: 0 | 90 | 180 | 270; flip?: boolean }>>;+ /**+ * Instead of six faces, one equirectangular picture (PNG or JPEG). The source is then a+ * low-dynamic-range panorama: it needs a colour space chosen, and it is not a recovered+ * HDR — nothing in it is brighter than white. `faces` is empty beside it.+ */+ panorama?: { file: string };}/** Read a `.escube` document, refusing what it cannot mean. A face left out is allowed here:@@ -186,11 +184,22 @@ export function parseCubeSource(raw: unknown): CubeSourceDocument {if (doc.colorSpace !== undefined && doc.colorSpace !== 'srgb' && doc.colorSpace !== 'linear') {throw new CubeImportError(`colorSpace must be "srgb" or "linear", not ${JSON.stringify(doc.colorSpace)}`);}- if (typeof doc.faces !== 'object' || doc.faces === null || Array.isArray(doc.faces)) {+ let panorama: { file: string } | undefined;+ if (doc.panorama !== undefined) {+ const p = doc.panorama as Record<string, unknown> | null;+ if (typeof p !== 'object' || p === null || typeof p.file !== 'string' || p.file === '') {+ throw new CubeImportError('a panorama image needs the "file" it reads');+ }+ if (doc.faces !== undefined && (typeof doc.faces !== 'object' || doc.faces === null+ || Array.isArray(doc.faces) || Object.keys(doc.faces).length > 0)) {+ throw new CubeImportError('a source is six faces or one panorama image, not both');+ }+ panorama = { file: p.file };+ } else if (typeof doc.faces !== 'object' || doc.faces === null || Array.isArray(doc.faces)) {throw new CubeImportError('a cube source names its images under "faces"');}const faces: CubeSourceDocument['faces'] = {};- for (const [key, value] of Object.entries(doc.faces as Record<string, unknown>)) {+ for (const [key, value] of Object.entries(panorama ? {} : doc.faces as Record<string, unknown>)) {const name = (CUBE_FACE_NAMES as readonly string[]).includes(key) ? key as CubeFaceName : null;if (!name) {throw new CubeImportError(`"${key}" is not a face; the faces are ${CUBE_FACE_NAMES.join(', ')}`);@@ -208,5 +217,6 @@ export function parseCubeSource(raw: unknown): CubeSourceDocument {faces[name] = { file: f.file, ...(f.rotate !== undefined ? { rotate: f.rotate } : {}),...(f.flip !== undefined ? { flip: f.flip } : {}) };}- return { version: CUBE_SOURCE_VERSION, ...(doc.colorSpace ? { colorSpace: doc.colorSpace } : {}), faces };+ return { version: CUBE_SOURCE_VERSION, ...(doc.colorSpace ? { colorSpace: doc.colorSpace } : {}), faces,+ ...(panorama ? { panorama } : {}) };}diff --git a/pipeline/src/assets/exrDecode.ts b/pipeline/src/assets/exrDecode.tsnew file mode 100644index 000000000..5ad3c2c3f--- /dev/null+++ b/pipeline/src/assets/exrDecode.ts@@ -0,0 +1,296 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file OpenEXR → the linear panorama an environment import takes.+ *+ * Only what a lat-long sky is: ONE scanline image with red, green and blue (or a single+ * luminance) channel, half or float. Everything else is refused by name, so a file that+ * cannot be read says why instead of importing as something nearby:+ *+ * supported compression NONE, RLE, ZIPS, ZIP, PXR24+ * refused compression PIZ, B44, B44A, DWAA, DWAB, HTJ2K — re-save as ZIP+ * layout tiled, deep, multi-part, mip/rip-mapped, cube-map+ * channels subsampled, or neither R,G,B nor Y+ *+ * Read from the OpenEXR file layout: a magic number and version, a header of typed+ * attributes, a table of block offsets, then blocks of scanlines each carrying its own+ * first line, so a file stored bottom-to-top lands the right way up.+ */+import { inflateSync } from 'node:zlib';+import type { Panorama } from './environmentImport';++export class ExrError extends Error {+ constructor(message: string) {+ super(message);+ this.name = 'ExrError';+ }+}++/** The compressions this reads. */+export const EXR_SUPPORTED_COMPRESSIONS = ['NONE', 'RLE', 'ZIPS', 'ZIP', 'PXR24'] as const;++const COMPRESSION_NAMES = ['NONE', 'RLE', 'ZIPS', 'ZIP', 'PIZ', 'PXR24', 'B44', 'B44A', 'DWAA', 'DWAB', 'HTJ2K256', 'HTJ2K32'];+/** Scanlines in one block, by compression number. */+const LINES_PER_BLOCK = [1, 1, 1, 16, 32, 16, 32, 32, 32, 256, 256, 32];++/** The widest panorama read: a float RGB copy of it is 12 bytes a texel. */+export const EXR_MAX_TEXELS = 8192 * 4096;++// Pixel types: 0 is UINT, which the sample reader falls through to.+const PIXEL_HALF = 1, PIXEL_FLOAT = 2;+const SAMPLE_BYTES = [4, 2, 4];++interface Channel {+ name: string;+ pixelType: number;+ bytesPerSample: number;+}++export interface ExrImage {+ panorama: Panorama;+ /** What the file said about itself that the import should pass on. */+ warnings: string[];+}++const HALF_TABLE = (() => {+ const t = new Float32Array(65536);+ for (let h = 0; h < 65536; h++) {+ const s = h & 0x8000 ? -1 : 1, e = (h >> 10) & 0x1f, m = h & 0x3ff;+ t[h] = e === 0 ? s * m * 2 ** -24 : e === 31 ? (m ? NaN : s * Infinity) : s * (1 + m / 1024) * 2 ** (e - 15);+ }+ return t;+})();++/** Undo the byte reordering and delta coding that ZIP and RLE apply before compressing. */+function unpredict(src: Uint8Array): Uint8Array {+ const n = src.length;+ const t = new Uint8Array(n);+ t[0] = src[0] ?? 0;+ for (let i = 1; i < n; i++) t[i] = (t[i - 1]! + src[i]! - 128) & 0xff;+ const out = new Uint8Array(n);+ const half = (n + 1) >> 1;+ for (let i = 0, a = 0, b = half; i < n; i += 2, a++, b++) {+ out[i] = t[a]!;+ if (i + 1 < n) out[i + 1] = t[b]!;+ }+ return out;+}++function rleDecode(src: Uint8Array, expected: number): Uint8Array {+ const out = new Uint8Array(expected);+ let i = 0, o = 0;+ while (i < src.length && o < expected) {+ const count = (src[i++]! << 24) >> 24;+ if (count < 0) {+ const n = -count;+ if (i + n > src.length || o + n > expected) throw new ExrError('the RLE data runs past its block');+ out.set(src.subarray(i, i + n), o);+ i += n; o += n;+ } else {+ const n = count + 1;+ if (i >= src.length || o + n > expected) throw new ExrError('the RLE data runs past its block');+ out.fill(src[i++]!, o, o + n);+ o += n;+ }+ }+ if (o !== expected) throw new ExrError('the RLE data ends before its block does');+ return out;+}++/** PXR24: per scanline and channel, byte planes of the delta-coded values, floats cut to 24 bits. */+function pxr24Decode(src: Uint8Array, channels: readonly Channel[], width: number, lines: number): Uint8Array {+ const raw = inflateSync(src);+ const lineBytes = channels.reduce((s, c) => s + c.bytesPerSample * width, 0);+ const out = new Uint8Array(lineBytes * lines);+ const view = new DataView(out.buffer);+ let at = 0, o = 0;+ for (let y = 0; y < lines; y++) {+ for (const c of channels) {+ let pixel = 0;+ if (c.pixelType === PIXEL_HALF) {+ const p0 = at, p1 = at + width;+ at += 2 * width;+ for (let x = 0; x < width; x++) {+ pixel = (pixel + ((raw[p0 + x]! << 8) | raw[p1 + x]!)) & 0xffff;+ view.setUint16(o + x * 2, pixel, true);+ }+ } else if (c.pixelType === PIXEL_FLOAT) {+ const p0 = at, p1 = at + width, p2 = at + 2 * width;+ at += 3 * width;+ for (let x = 0; x < width; x++) {+ pixel = (pixel + ((raw[p0 + x]! << 24) | (raw[p1 + x]! << 16) | (raw[p2 + x]! << 8))) >>> 0;+ view.setUint32(o + x * 4, pixel, true);+ }+ } else {+ const p0 = at, p1 = at + width, p2 = at + 2 * width, p3 = at + 3 * width;+ at += 4 * width;+ for (let x = 0; x < width; x++) {+ pixel = (pixel + ((raw[p0 + x]! << 24) | (raw[p1 + x]! << 16) | (raw[p2 + x]! << 8) | raw[p3 + x]!)) >>> 0;+ view.setUint32(o + x * 4, pixel, true);+ }+ }+ o += c.bytesPerSample * width;+ }+ }+ if (at > raw.length) throw new ExrError('the PXR24 data ends before its block does');+ return out;+}++interface Header {+ width: number;+ height: number;+ yMin: number;+ compression: number;+ channels: Channel[];+ pos: number;+}++function readHeader(bytes: Uint8Array): Header {+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);+ if (bytes.length < 8 || view.getUint32(0, true) !== 20000630) throw new ExrError('not an OpenEXR file: no magic number');+ // One 32-bit word: the version in the low byte, the layout flags in bits 9 to 12.+ const word = view.getUint32(4, true);+ const version = word & 0xff;+ const flags = word & ~0xff;+ if (version !== 2) throw new ExrError(`OpenEXR version ${version} is not one this reads (2)`);+ if (flags & 0x200) throw new ExrError('a tiled OpenEXR is not supported; save it as scanlines');+ if (flags & 0x800) throw new ExrError('a deep OpenEXR is not supported');+ if (flags & 0x1000) throw new ExrError('a multi-part OpenEXR is not supported; save one layer');++ let pos = 8;+ const text = (): string => {+ const start = pos;+ while (pos < bytes.length && bytes[pos] !== 0) pos++;+ if (pos >= bytes.length) throw new ExrError('the OpenEXR header ends inside a name');+ const s = new TextDecoder().decode(bytes.subarray(start, pos));+ pos++;+ return s;+ };+ let channels: Channel[] | null = null;+ let compression = -1;+ let window: [number, number, number, number] | null = null;+ let envmap = -1;+ for (;;) {+ if (pos >= bytes.length) throw new ExrError('the OpenEXR header never ends');+ if (bytes[pos] === 0) { pos++; break; }+ const name = text();+ const type = text();+ const size = view.getInt32(pos, true);+ pos += 4;+ if (size < 0 || pos + size > bytes.length) throw new ExrError(`the header attribute ${name} runs past the file`);+ const end = pos + size;+ if (name === 'channels' && type === 'chlist') {+ const list: Channel[] = [];+ while (pos < end && bytes[pos] !== 0) {+ const channelName = text();+ const pixelType = view.getInt32(pos, true);+ const xs = view.getInt32(pos + 8, true), ys = view.getInt32(pos + 12, true);+ pos += 16;+ if (pixelType < 0 || pixelType > 2) throw new ExrError(`channel ${channelName} has pixel type ${pixelType}`);+ if (xs !== 1 || ys !== 1) throw new ExrError(`channel ${channelName} is subsampled, which is not supported`);+ list.push({ name: channelName, pixelType, bytesPerSample: SAMPLE_BYTES[pixelType]! });+ }+ channels = list;+ } else if (name === 'compression' && type === 'compression') {+ compression = view.getUint8(pos);+ } else if (name === 'dataWindow' && type === 'box2i') {+ window = [view.getInt32(pos, true), view.getInt32(pos + 4, true), view.getInt32(pos + 8, true), view.getInt32(pos + 12, true)];+ } else if (name === 'envmap' && type === 'envmap') {+ envmap = view.getUint8(pos);+ }+ pos = end;+ }+ if (!channels || compression < 0 || !window) throw new ExrError('the OpenEXR header lacks its channels, compression or data window');+ if (envmap === 1) throw new ExrError('a cube-map OpenEXR is not supported; use a lat-long panorama');+ const width = window[2] - window[0] + 1, height = window[3] - window[1] + 1;+ if (!(width > 0) || !(height > 0)) throw new ExrError('the OpenEXR data window is empty');+ if (width * height > EXR_MAX_TEXELS) {+ throw new ExrError(`the panorama is ${width}x${height}; at most ${EXR_MAX_TEXELS} texels are read`);+ }+ return { width, height, yMin: window[1], compression, channels, pos };+}++/** Decode one block of scanlines to its raw, line-by-line, channel-by-channel bytes. */+function inflateBlock(compression: number, payload: Uint8Array, channels: readonly Channel[], width: number, lines: number): Uint8Array {+ const expected = channels.reduce((s, c) => s + c.bytesPerSample * width, 0) * lines;+ if (compression === 0 || payload.length === expected) {+ if (payload.length !== expected) throw new ExrError('a block holds fewer bytes than its lines need');+ return payload;+ }+ switch (compression) {+ case 1: return unpredict(rleDecode(payload, expected));+ case 2:+ case 3: return unpredict(inflateSync(payload));+ case 5: return pxr24Decode(payload, channels, width, lines);+ default: throw new ExrError(`unsupported compression ${COMPRESSION_NAMES[compression] ?? compression}`);+ }+}++/** Decode an OpenEXR panorama into linear RGB, row 0 = up (+Y). */+export function decodeExr(bytes: Uint8Array): ExrImage {+ const header = readHeader(bytes);+ const { width, height, yMin, compression, channels } = header;+ if (!(compression in LINES_PER_BLOCK) || (EXR_SUPPORTED_COMPRESSIONS as readonly string[]).indexOf(COMPRESSION_NAMES[compression]!) < 0) {+ throw new ExrError(`unsupported compression ${COMPRESSION_NAMES[compression] ?? compression}; `+ + `re-save the file with ${EXR_SUPPORTED_COMPRESSIONS.join(', ')}`);+ }+ const names = channels.map((c) => c.name);+ const rgbIndex = ['R', 'G', 'B'].map((n) => names.indexOf(n));+ const yIndex = names.indexOf('Y');+ const gray = rgbIndex.some((i) => i < 0);+ if (gray && yIndex < 0) {+ throw new ExrError(`the channels are ${names.join(', ')}; a panorama needs R, G and B (or a single Y)`);+ }++ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);+ const linesPerBlock = LINES_PER_BLOCK[compression]!;+ const blocks = Math.ceil(height / linesPerBlock);+ let pos = header.pos;+ const offsets: number[] = [];+ for (let i = 0; i < blocks; i++, pos += 8) {+ if (pos + 8 > bytes.length) throw new ExrError('the block offset table runs past the file');+ offsets.push(view.getUint32(pos, true) + view.getUint32(pos + 4, true) * 2 ** 32);+ }++ const lineBytes = channels.reduce((s, c) => s + c.bytesPerSample * width, 0);+ const channelOffset: number[] = [];+ let run = 0;+ for (const c of channels) { channelOffset.push(run); run += c.bytesPerSample * width; }+ const rgb = new Float32Array(width * height * 3);+ const warnings: string[] = [];+ let repaired = 0;++ const sample = (data: DataView, base: number, c: Channel, x: number): number => {+ const at = base + x * c.bytesPerSample;+ if (c.pixelType === PIXEL_HALF) return HALF_TABLE[data.getUint16(at, true)]!;+ if (c.pixelType === PIXEL_FLOAT) return data.getFloat32(at, true);+ return data.getUint32(at, true);+ };++ for (const offset of offsets) {+ if (offset + 8 > bytes.length) throw new ExrError('a block starts past the end of the file');+ const y0 = view.getInt32(offset, true) - yMin;+ const size = view.getInt32(offset + 4, true);+ if (size < 0 || offset + 8 + size > bytes.length) throw new ExrError('a block runs past the end of the file');+ const lines = Math.min(linesPerBlock, height - y0);+ if (y0 < 0 || lines <= 0) throw new ExrError(`a block names the line ${y0 + yMin}, outside the data window`);+ const raw = inflateBlock(compression, bytes.subarray(offset + 8, offset + 8 + size), channels, width, lines);+ const data = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);+ for (let l = 0; l < lines; l++) {+ const row = (y0 + l) * width * 3;+ const base = l * lineBytes;+ for (let x = 0; x < width; x++) {+ for (let k = 0; k < 3; k++) {+ const ci = gray ? yIndex : rgbIndex[k]!;+ let v = sample(data, base + channelOffset[ci]!, channels[ci]!, x);+ // Radiance is a finite, non-negative amount of light; anything else would+ // poison every texel the prefilter averages it into.+ if (!Number.isFinite(v) || v < 0) { v = 0; repaired++; }+ rgb[row + x * 3 + k] = v;+ }+ }+ }+ }+ if (repaired > 0) warnings.push(`${repaired} sample(s) were negative or not a number and were read as black`);+ return { panorama: { width, height, rgb }, warnings };+}diff --git a/pipeline/src/assets/ldrPanorama.ts b/pipeline/src/assets/ldrPanorama.tsnew file mode 100644index 000000000..c978d3ad0--- /dev/null+++ b/pipeline/src/assets/ldrPanorama.ts@@ -0,0 +1,57 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file An 8-bit picture as a panorama in linear light.+ *+ * Six faces and a single lat-long picture are both low-dynamic-range sources, and both+ * need the same two things: the sRGB curve undone, and the plain fact that nothing in them+ * is brighter than white. One conversion serves both, so a face set and a panorama of the+ * same sky read as the same light.+ */+import type { Panorama } from './environmentImport';++/** How the 8-bit values are encoded. PNG and JPEG are sRGB unless said otherwise. */+export type LdrColorSpace = 'srgb' | 'linear';++/** sRGB byte → linear light. */+export const SRGB_TO_LINEAR = (() => {+ const lut = new Float32Array(256);+ for (let i = 0; i < 256; i++) {+ const c = i / 255;+ lut[i] = c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);+ }+ return lut;+})();++/** A decoded 8-bit picture, row 0 = top. */+export interface LdrImage {+ width: number;+ height: number;+ rgba: Uint8Array;+}++/** The widest picture read: a float RGB copy is 12 bytes a texel. */+export const LDR_MAX_TEXELS = 8192 * 4096;++/** What an import of a low-dynamic-range source has to tell its author. */+export const LDR_NOTE = 'an 8-bit picture holds no light brighter than white, so this environment has no sun brighter'+ + ' than its sky; import a Radiance .hdr or an OpenEXR to light a scene from a real one';++/** A lat-long picture in linear light, row 0 = up (+Y). */+export function ldrToPanorama(image: LdrImage, colorSpace: LdrColorSpace = 'srgb'): Panorama {+ const { width, height } = image;+ if (!(width > 0) || !(height > 0) || image.rgba.length !== width * height * 4) {+ throw new Error(`a ${width}x${height} picture needs ${width * height * 4} bytes, not ${image.rgba.length}`);+ }+ if (width * height > LDR_MAX_TEXELS) {+ throw new Error(`the picture is ${width}x${height}; at most ${LDR_MAX_TEXELS} texels are read`);+ }+ const rgb = new Float32Array(width * height * 3);+ for (let i = 0, o = 0; i < width * height; i++, o += 3) {+ for (let c = 0; c < 3; c++) {+ const v = image.rgba[i * 4 + c]!;+ rgb[o + c] = colorSpace === 'srgb' ? SRGB_TO_LINEAR[v]! : v / 255;+ }+ }+ return { width, height, rgb };+}diff --git a/pipeline/tests/environment-cube.test.ts b/pipeline/tests/environment-cube.test.tsindex 128056881..233897b96 100644--- a/pipeline/tests/environment-cube.test.ts+++ b/pipeline/tests/environment-cube.test.ts@@ -200,3 +200,19 @@ describe('a cube source document', () => {expect(refused('nope').message).toMatch(/JSON object/);});});++describe('a panorama image as the source instead of six faces', () => {+ it('reads one picture, with no faces beside it', () => {+ expect(parseCubeSource({ version: 1, colorSpace: 'linear', panorama: { file: 'sky/day.png' } })).toEqual({+ version: 1, colorSpace: 'linear', faces: {}, panorama: { file: 'sky/day.png' },+ });+ expect(parseCubeSource({ version: 1, faces: {}, panorama: { file: 'a.jpg' } }).panorama).toEqual({ file: 'a.jpg' });+ });++ it('refuses faces and a picture together, and a picture with no file', () => {+ expect(() => parseCubeSource({ version: 1, faces: { px: { file: 'a.png' } }, panorama: { file: 'b.png' } }))+ .toThrow(/six faces or one panorama/);+ expect(() => parseCubeSource({ version: 1, panorama: {} })).toThrow(/needs the "file"/);+ expect(() => parseCubeSource({ version: 1, panorama: { file: '' } })).toThrow(/needs the "file"/);+ });+});diff --git a/pipeline/tests/exr-decode.test.ts b/pipeline/tests/exr-decode.test.tsnew file mode 100644index 000000000..89a18b1e9--- /dev/null+++ b/pipeline/tests/exr-decode.test.ts@@ -0,0 +1,112 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * OpenEXR panoramas, read against files an independent writer produced.+ *+ * The fixtures were written by Blender 5.2 (see tests/fixtures/exr/README.md): a 16x8 image+ * whose every texel differs, one of them far past 1, stored in each compression at half and+ * float precision. A decoder that agreed only with a writer of its own would agree with its+ * own misreading of the format; these files cannot.+ */+import { describe, it, expect } from 'vitest';+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { decodeExr, ExrError, EXR_SUPPORTED_COMPRESSIONS } from '../src/assets/exrDecode';++const DIR = path.join(__dirname, 'fixtures/exr');+const load = (name: string): Uint8Array => new Uint8Array(readFileSync(path.join(DIR, name)));++const W = 16, H = 8;+/** The value the generator wrote at (x, y), counted from the top of the picture. */+function expected(x: number, y: number): [number, number, number] {+ return [x + 0.25, y + 0.5, (x * 3 + y) / 4 + (x === 5 && y === 2 ? 100 : 0)];+}++function expectMatches(name: string, relative: number): void {+ const { panorama, warnings } = decodeExr(load(name));+ expect(warnings).toEqual([]);+ expect(panorama.width).toBe(W);+ expect(panorama.height).toBe(H);+ for (let y = 0; y < H; y++) {+ for (let x = 0; x < W; x++) {+ const want = expected(x, y);+ for (let k = 0; k < 3; k++) {+ const got = panorama.rgb[(y * W + x) * 3 + k]!;+ // Half floats carry ten bits of mantissa, so a value near 100 is good to ~0.06.+ expect(Math.abs(got - want[k]!), `${name} (${x},${y}) channel ${k}: ${got} vs ${want[k]}`)+ .toBeLessThanOrEqual(Math.max(1e-3, Math.abs(want[k]!) * relative));+ }+ }+ }+}++describe('the compressions this reads', () => {+ for (const codec of ['none', 'rle', 'zips', 'zip', 'pxr24']) {+ it(`${codec}, half precision: every texel where the writer put it, top row first`, () => {+ expectMatches(`ref_${codec}_16.exr`, 2 ** -10);+ });+ it(`${codec}, float precision`, () => {+ // PXR24 cuts a float to 24 bits; the others keep all 32.+ expectMatches(`ref_${codec}_32.exr`, codec === 'pxr24' ? 2 ** -14 : 1e-6);+ });+ }++ it('lists what it supports', () => {+ expect([...EXR_SUPPORTED_COMPRESSIONS]).toEqual(['NONE', 'RLE', 'ZIPS', 'ZIP', 'PXR24']);+ });+});++describe('what it refuses, by name', () => {+ const refused = (bytes: Uint8Array): string => {+ try { decodeExr(bytes); } catch (e) { expect(e).toBeInstanceOf(ExrError); return (e as Error).message; }+ throw new Error('expected the file to be refused');+ };++ it('names a compression it does not read and says what to save as', () => {+ const message = refused(load('ref_dwaa_16.exr'));+ expect(message).toMatch(/unsupported compression DWAA/);+ expect(message).toMatch(/NONE, RLE, ZIPS, ZIP, PXR24/);+ });++ it('is not an OpenEXR when the magic number is not there', () => {+ expect(refused(new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9]))).toMatch(/no magic number/);+ });++ it('refuses a tiled, a deep and a multi-part file for what they are', () => {+ for (const [flag, word] of [[0x200, /tiled/], [0x800, /deep/], [0x1000, /multi-part/]] as const) {+ const bytes = load('ref_zip_16.exr').slice();+ const view = new DataView(bytes.buffer);+ view.setUint32(4, 2 | flag, true);+ expect(refused(bytes)).toMatch(word);+ }+ });++ it('refuses a file cut short rather than reading past it', () => {+ const bytes = load('ref_zip_16.exr');+ expect(() => decodeExr(bytes.subarray(0, bytes.length - 40))).toThrow(ExrError);+ expect(() => decodeExr(bytes.subarray(0, 60))).toThrow(ExrError);+ });+});++describe('an image taller than one block', () => {+ // 64x40: ZIP and PXR24 hold 16 lines a block, so three blocks and the last is short.+ const check = (name: string, relative: number): void => {+ const { panorama } = decodeExr(load(name));+ expect([panorama.width, panorama.height]).toEqual([64, 40]);+ for (let y = 0; y < 40; y++) {+ for (let x = 0; x < 64; x++) {+ const want = [x / 2, y / 4, ((x * 7 + y * 13) % 17) / 4];+ for (let k = 0; k < 3; k++) {+ const got = panorama.rgb[(y * 64 + x) * 3 + k]!;+ expect(Math.abs(got - want[k]!), `${name} (${x},${y}) channel ${k}`)+ .toBeLessThanOrEqual(Math.max(1e-3, Math.abs(want[k]!) * relative));+ }+ }+ }+ };++ it('reads every block of a ZIP file', () => check('big_zip_32.exr', 1e-6));+ it('reads every block of a PXR24 file', () => check('big_pxr24_32.exr', 2 ** -14));+ it('reads a ZIPS file, one line a block', () => check('big_zips_16.exr', 2 ** -10));+ it('reads an RLE file, one line a block', () => check('big_rle_32.exr', 1e-6));+});diff --git a/pipeline/tests/fixtures/exr/README.md b/pipeline/tests/fixtures/exr/README.mdnew file mode 100644index 000000000..8929fc2bd--- /dev/null+++ b/pipeline/tests/fixtures/exr/README.md@@ -0,0 +1,39 @@+# Reference OpenEXR files++Written by Blender 5.2.1 (`blender -b --python make_exr.py`), as an independent producer: the+decoder is checked against files it did not help write.++Each file is a 16x8 RGB image, one file per compression (`none`, `rle`, `zips`, `zip`, `piz`,+`pxr24`, `dwaa`) at half (`_16`) and float (`_32`) precision. The value at texel (x, y), counted+from the top of the picture, is++ r = x + 0.25+ g = y + 0.5+ b = (x * 3 + y) / 4 + (100 if x == 5 and y == 2 else 0)++so every channel differs from its neighbours and one texel is far past 1.++The generator script:++```python+import bpy, sys, os+out = sys.argv[sys.argv.index('--') + 1]+os.makedirs(out, exist_ok=True)+W, H = 16, 8+def value(x, y):+ return (x + 0.25, y + 0.5, (x * 3 + y) / 4 + (100.0 if (x == 5 and y == 2) else 0.0))+img = bpy.data.images.new('ref', W, H, alpha=True, float_buffer=True)+px = []+for row in range(H): # Blender stores rows bottom to top+ y = H - 1 - row+ for x in range(W):+ r, g, b = value(x, y)+ px += [r, g, b, 1.0]+img.pixels = px+scene = bpy.context.scene+s = scene.render.image_settings+for codec in ('NONE', 'RLE', 'ZIPS', 'ZIP', 'PIZ', 'PXR24', 'DWAA'):+ for depth in ('16', '32'):+ s.file_format = 'OPEN_EXR'; s.color_mode = 'RGB'; s.color_depth = depth; s.exr_codec = codec+ img.save_render(os.path.join(out, f'ref_{codec.lower()}_{depth}.exr'), scene=scene)+```diff --git a/pipeline/tests/fixtures/exr/big_pxr24_32.exr b/pipeline/tests/fixtures/exr/big_pxr24_32.exrnew file mode 100644index 000000000..59764b729Binary files /dev/null and b/pipeline/tests/fixtures/exr/big_pxr24_32.exr differdiff --git a/pipeline/tests/fixtures/exr/big_rle_32.exr b/pipeline/tests/fixtures/exr/big_rle_32.exrnew file mode 100644index 000000000..67ca909dbBinary files /dev/null and b/pipeline/tests/fixtures/exr/big_rle_32.exr differdiff --git a/pipeline/tests/fixtures/exr/big_zip_32.exr b/pipeline/tests/fixtures/exr/big_zip_32.exrnew file mode 100644index 000000000..08c8b19aeBinary files /dev/null and b/pipeline/tests/fixtures/exr/big_zip_32.exr differdiff --git a/pipeline/tests/fixtures/exr/big_zips_16.exr b/pipeline/tests/fixtures/exr/big_zips_16.exrnew file mode 100644index 000000000..24d42154aBinary files /dev/null and b/pipeline/tests/fixtures/exr/big_zips_16.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_dwaa_16.exr b/pipeline/tests/fixtures/exr/ref_dwaa_16.exrnew file mode 100644index 000000000..2c7a843e7Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_dwaa_16.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_dwaa_32.exr b/pipeline/tests/fixtures/exr/ref_dwaa_32.exrnew file mode 100644index 000000000..0b22891b6Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_dwaa_32.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_none_16.exr b/pipeline/tests/fixtures/exr/ref_none_16.exrnew file mode 100644index 000000000..80ae4739cBinary files /dev/null and b/pipeline/tests/fixtures/exr/ref_none_16.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_none_32.exr b/pipeline/tests/fixtures/exr/ref_none_32.exrnew file mode 100644index 000000000..b0338921cBinary files /dev/null and b/pipeline/tests/fixtures/exr/ref_none_32.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_piz_16.exr b/pipeline/tests/fixtures/exr/ref_piz_16.exrnew file mode 100644index 000000000..9e3ae17f9Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_piz_16.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_piz_32.exr b/pipeline/tests/fixtures/exr/ref_piz_32.exrnew file mode 100644index 000000000..be501489cBinary files /dev/null and b/pipeline/tests/fixtures/exr/ref_piz_32.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_pxr24_16.exr b/pipeline/tests/fixtures/exr/ref_pxr24_16.exrnew file mode 100644index 000000000..7189f0cabBinary files /dev/null and b/pipeline/tests/fixtures/exr/ref_pxr24_16.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_pxr24_32.exr b/pipeline/tests/fixtures/exr/ref_pxr24_32.exrnew file mode 100644index 000000000..e47277044Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_pxr24_32.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_rle_16.exr b/pipeline/tests/fixtures/exr/ref_rle_16.exrnew file mode 100644index 000000000..1ea8a2a10Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_rle_16.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_rle_32.exr b/pipeline/tests/fixtures/exr/ref_rle_32.exrnew file mode 100644index 000000000..9162e536dBinary files /dev/null and b/pipeline/tests/fixtures/exr/ref_rle_32.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_zip_16.exr b/pipeline/tests/fixtures/exr/ref_zip_16.exrnew file mode 100644index 000000000..e88dcc9d1Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_zip_16.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_zip_32.exr b/pipeline/tests/fixtures/exr/ref_zip_32.exrnew file mode 100644index 000000000..ea42f594eBinary files /dev/null and b/pipeline/tests/fixtures/exr/ref_zip_32.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_zips_16.exr b/pipeline/tests/fixtures/exr/ref_zips_16.exrnew file mode 100644index 000000000..7eee61b2aBinary files /dev/null and b/pipeline/tests/fixtures/exr/ref_zips_16.exr differdiff --git a/pipeline/tests/fixtures/exr/ref_zips_32.exr b/pipeline/tests/fixtures/exr/ref_zips_32.exrnew file mode 100644index 000000000..f669de086Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_zips_32.exr differdiff --git a/pipeline/tests/ldr-panorama.test.ts b/pipeline/tests/ldr-panorama.test.tsnew file mode 100644index 000000000..6262589d8--- /dev/null+++ b/pipeline/tests/ldr-panorama.test.ts@@ -0,0 +1,44 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * An 8-bit picture as light: the sRGB curve undone or not as the author says, nothing+ * brighter than white, and a picture whose bytes are not its size refused.+ */+import { describe, it, expect } from 'vitest';+import { ldrToPanorama, SRGB_TO_LINEAR, LDR_NOTE } from '../src/assets/ldrPanorama';++const solid = (v: number, width = 4, height = 2) => ({+ width, height, rgba: new Uint8Array(width * height * 4).fill(v),+});++describe('an 8-bit panorama', () => {+ it('is linearized by the sRGB curve, so a mid grey is far darker than half', () => {+ const p = ldrToPanorama(solid(128), 'srgb');+ expect(p.rgb[0]).toBeCloseTo(0.2158, 3);+ expect(SRGB_TO_LINEAR[255]).toBe(1);+ expect(SRGB_TO_LINEAR[0]).toBe(0);+ });++ it('is taken as it is when the author says it is already linear', () => {+ expect(ldrToPanorama(solid(128), 'linear').rgb[0]).toBeCloseTo(128 / 255, 6);+ });++ it('holds nothing brighter than white', () => {+ const p = ldrToPanorama(solid(255));+ expect(Math.max(...p.rgb)).toBe(1);+ expect(LDR_NOTE).toMatch(/no light brighter than white/);+ });++ it('keeps the picture\'s size and row order', () => {+ const image = solid(0, 4, 2);+ image.rgba.set([255, 255, 255, 255], 0); // top-left texel only+ const p = ldrToPanorama(image);+ expect([p.width, p.height]).toEqual([4, 2]);+ expect(p.rgb[0]).toBe(1);+ expect(p.rgb[4 * 3]).toBe(0); // first texel of the second row+ });++ it('refuses bytes that are not the picture\'s size', () => {+ expect(() => ldrToPanorama({ width: 4, height: 2, rgba: new Uint8Array(5) })).toThrow(/needs 32 bytes/);+ });+});diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 2f0872bd1..3973c19a1 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 109 beta · 1581 experimental · 3 deprecated+Symbols: 115 public · 109 beta · 1599 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -304,6 +304,11 @@ Start = 1Stretch = 4```+## AmbientSkip — type @experimental+```+'hidden' | 'disabled' | 'no-intensity'+```+## Ambiguity — interface @experimental```a: string@@ -2700,6 +2705,11 @@ EditorGridDataEditorViewData```+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental+```+EditorViewLightingData+```+## DEFAULT_FACING_COSINE — const @experimental```0.2@@ -3348,6 +3358,11 @@ tabIndex: number | undefinedworld: World```+## EDITOR_EXPOSURE_RANGE — const @experimental+```+{ readonly min: -6; readonly max: 6; }+```+## EDITOR_UI_ANCHOR — const @experimental```{ readonly x: 0; readonly y: 0; }@@ -3418,6 +3433,11 @@ majorEvery: numberspacing: number```+## EditorLightingMode — type @experimental+```+'scene' | 'studio'+```+## EditorView — const @experimental```ResourceDef<EditorViewData>@@ -3445,6 +3465,22 @@ yaw: numberz: number```+## EditorViewLighting — const @experimental+```+ResourceDef<EditorViewLightingData>+```++## EditorViewLightingData — interface @experimental+```+exposure: number+fillIntensity: number+keyIntensity: number+mode: EditorLightingMode+rotation: number+showSky: boolean+skyIntensity: number+```+## EditorWorkPlane — interface @experimental```normal: WorldAxis@@ -3589,6 +3625,14 @@ pickable: ((entity: Entity) => boolean) | undefinedySortLayers: number | undefined```+## EnvironmentLightEntity — interface @experimental+```+components: readonly { type: string; data: Record<string, unknown>; }[]+id: number+name: string+visible: boolean | undefined+```+## EventBinding — const @experimental```ComponentDef<EventBindingData>@@ -7375,6 +7419,18 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAmbientLight — interface @experimental+```+drawEnvironment: boolean+entityId: number+environment: string | null+environmentMissing: boolean+intensity: number+name: string+rotation: number+skipped: AmbientSkip | null+```+## SceneAssetRefs — interface @experimental```byType: Map<string, Set<string>>@@ -7428,6 +7484,11 @@ trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => voidunbindPostProcess: (camera: Entity) => void```+## SceneDark — type @experimental+```+'no-lights' | 'no-enabled-light'+```+## SceneData — interface @experimental```entities: SceneEntityData[]@@ -7921,6 +7982,11 @@ vertices: Uint8Array<ArrayBufferLike>| { kind: 'sh'; irradiance: readonly number[]; yaw: number; tint: readonly [number, number, number] }```+## SkyUnavailable — type @experimental+```+'no-ambient' | 'no-environment' | 'missing' | 'off' | 'unusable'+```+## SliceBorder — interface @experimental```bottom: number@@ -8531,6 +8597,14 @@ ComponentDef<StreamedWorldData>cellSize: number```+## StudioPreviewReport — interface @experimental+```+environment: SceneAmbientLight | null+sceneDark: SceneDark | null+sceneLights: number+skyUnavailable: SkyUnavailable | null+```+## SubEmitterTrigger — enum @beta```Birth = 1@@ -10826,6 +10900,11 @@ MotionDriver<AnimatorBlend2DMotion>(at: readonly [number, number, number], bvh: Bvh, lookup: HitLookup, atlas: Float32Array, atlasSize: number, width: number, height: number, sky: SkyRadiance): CapturedPanorama```+## carriesEnvironment — function @experimental+```+(light: SceneAmbientLight): boolean+```+## catalogFromManifest — function @experimental```(manifest: AddressableManifest): Catalog | undefined@@ -11366,6 +11445,16 @@ DragPlugin(view: EditorViewData): boolean```+## editorViewLightingArgs — function @experimental+```+(data: EditorViewLightingData, viewActive: boolean): { mode: number; rotation: number; key: number; fill: number; sky: number; showSky: boolean; exposure: number; }+```++## editorViewLightingIsOverriding — function @experimental+```+(data: EditorViewLightingData): boolean+```+## editorViewStandoff — function @experimental```(view: EditorViewData): number@@ -12766,6 +12855,11 @@ PrefabsPlugin(): CppResourceManager```+## resetEditorViewLighting — function @experimental+```+(data: EditorViewLightingData): EditorViewLightingData+```+## resetWorldTo — function @experimental```(world: World, sceneData: SceneData): Map<number, Entity>@@ -12856,6 +12950,16 @@ SafeAreaPlugin{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }```+## sceneAmbientLights — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]+```++## sceneEnvironment — function @experimental+```+(lights: readonly SceneAmbientLight[]): { effective: SceneAmbientLight | null; shadowed: SceneAmbientLight[]; }+```+## sceneManagerPlugin — const @experimental```Plugin@@ -13241,6 +13345,11 @@ StatsPlugin(world: World, entity: Entity): void```+## studioPreviewReport — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): StudioPreviewReport+```+## summarizeCapture — function @experimental```(capture: ProfileCapture): CaptureSummarydiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 6db8ed849..059e3ba88 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 114 beta · 1600 experimental · 3 deprecated+Symbols: 115 public · 114 beta · 1618 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -304,6 +304,11 @@ Start = 1Stretch = 4```+## AmbientSkip — type @experimental+```+'hidden' | 'disabled' | 'no-intensity'+```+## Ambiguity — interface @experimental```a: string@@ -2708,6 +2713,11 @@ EditorGridDataEditorViewData```+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental+```+EditorViewLightingData+```+## DEFAULT_FACING_COSINE — const @experimental```0.2@@ -3356,6 +3366,11 @@ tabIndex: number | undefinedworld: World```+## EDITOR_EXPOSURE_RANGE — const @experimental+```+{ readonly min: -6; readonly max: 6; }+```+## EDITOR_UI_ANCHOR — const @experimental```{ readonly x: 0; readonly y: 0; }@@ -3426,6 +3441,11 @@ majorEvery: numberspacing: number```+## EditorLightingMode — type @experimental+```+'scene' | 'studio'+```+## EditorView — const @experimental```ResourceDef<EditorViewData>@@ -3453,6 +3473,22 @@ yaw: numberz: number```+## EditorViewLighting — const @experimental+```+ResourceDef<EditorViewLightingData>+```++## EditorViewLightingData — interface @experimental+```+exposure: number+fillIntensity: number+keyIntensity: number+mode: EditorLightingMode+rotation: number+showSky: boolean+skyIntensity: number+```+## EditorWorkPlane — interface @experimental```normal: WorldAxis@@ -3597,6 +3633,14 @@ pickable: ((entity: Entity) => boolean) | undefinedySortLayers: number | undefined```+## EnvironmentLightEntity — interface @experimental+```+components: readonly { type: string; data: Record<string, unknown>; }[]+id: number+name: string+visible: boolean | undefined+```+## EventBinding — const @experimental```ComponentDef<EventBindingData>@@ -7588,6 +7632,18 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAmbientLight — interface @experimental+```+drawEnvironment: boolean+entityId: number+environment: string | null+environmentMissing: boolean+intensity: number+name: string+rotation: number+skipped: AmbientSkip | null+```+## SceneAssetRefs — interface @experimental```byType: Map<string, Set<string>>@@ -7641,6 +7697,11 @@ trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => voidunbindPostProcess: (camera: Entity) => void```+## SceneDark — type @experimental+```+'no-lights' | 'no-enabled-light'+```+## SceneData — interface @experimental```entities: SceneEntityData[]@@ -8134,6 +8195,11 @@ vertices: Uint8Array<ArrayBufferLike>| { kind: 'sh'; irradiance: readonly number[]; yaw: number; tint: readonly [number, number, number] }```+## SkyUnavailable — type @experimental+```+'no-ambient' | 'no-environment' | 'missing' | 'off' | 'unusable'+```+## SliceBorder — interface @experimental```bottom: number@@ -8744,6 +8810,14 @@ ComponentDef<StreamedWorldData>cellSize: number```+## StudioPreviewReport — interface @experimental+```+environment: SceneAmbientLight | null+sceneDark: SceneDark | null+sceneLights: number+skyUnavailable: SkyUnavailable | null+```+## SubEmitterTrigger — enum @beta```Birth = 1@@ -11054,6 +11128,11 @@ MotionDriver<AnimatorBlend2DMotion>(at: readonly [number, number, number], bvh: Bvh, lookup: HitLookup, atlas: Float32Array, atlasSize: number, width: number, height: number, sky: SkyRadiance): CapturedPanorama```+## carriesEnvironment — function @experimental+```+(light: SceneAmbientLight): boolean+```+## catalogFromManifest — function @experimental```(manifest: AddressableManifest): Catalog | undefined@@ -11619,6 +11698,16 @@ DragPlugin(view: EditorViewData): boolean```+## editorViewLightingArgs — function @experimental+```+(data: EditorViewLightingData, viewActive: boolean): { mode: number; rotation: number; key: number; fill: number; sky: number; showSky: boolean; exposure: number; }+```++## editorViewLightingIsOverriding — function @experimental+```+(data: EditorViewLightingData): boolean+```+## editorViewStandoff — function @experimental```(view: EditorViewData): number@@ -13029,6 +13118,11 @@ PrefabsPlugin(): CppResourceManager```+## resetEditorViewLighting — function @experimental+```+(data: EditorViewLightingData): EditorViewLightingData+```+## resetWorldTo — function @experimental```(world: World, sceneData: SceneData): Map<number, Entity>@@ -13119,6 +13213,16 @@ SafeAreaPlugin{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }```+## sceneAmbientLights — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]+```++## sceneEnvironment — function @experimental+```+(lights: readonly SceneAmbientLight[]): { effective: SceneAmbientLight | null; shadowed: SceneAmbientLight[]; }+```+## sceneManagerPlugin — const @experimental```Plugin@@ -13504,6 +13608,11 @@ StatsPlugin(world: World, entity: Entity): void```+## studioPreviewReport — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): StudioPreviewReport+```+## summarizeCapture — function @experimental```(capture: ProfileCapture): CaptureSummarydiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 073c8c3d6..18f893185 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 111 beta · 1580 experimental · 3 deprecated+Symbols: 115 public · 111 beta · 1598 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -299,6 +299,11 @@ Start = 1Stretch = 4```+## AmbientSkip — type @experimental+```+'hidden' | 'disabled' | 'no-intensity'+```+## Ambiguity — interface @experimental```a: string@@ -2695,6 +2700,11 @@ EditorGridDataEditorViewData```+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental+```+EditorViewLightingData+```+## DEFAULT_FACING_COSINE — const @experimental```0.2@@ -3343,6 +3353,11 @@ tabIndex: number | undefinedworld: World```+## EDITOR_EXPOSURE_RANGE — const @experimental+```+{ readonly min: -6; readonly max: 6; }+```+## EDITOR_UI_ANCHOR — const @experimental```{ readonly x: 0; readonly y: 0; }@@ -3413,6 +3428,11 @@ majorEvery: numberspacing: number```+## EditorLightingMode — type @experimental+```+'scene' | 'studio'+```+## EditorView — const @experimental```ResourceDef<EditorViewData>@@ -3440,6 +3460,22 @@ yaw: numberz: number```+## EditorViewLighting — const @experimental+```+ResourceDef<EditorViewLightingData>+```++## EditorViewLightingData — interface @experimental+```+exposure: number+fillIntensity: number+keyIntensity: number+mode: EditorLightingMode+rotation: number+showSky: boolean+skyIntensity: number+```+## EditorWorkPlane — interface @experimental```normal: WorldAxis@@ -3584,6 +3620,14 @@ pickable: ((entity: Entity) => boolean) | undefinedySortLayers: number | undefined```+## EnvironmentLightEntity — interface @experimental+```+components: readonly { type: string; data: Record<string, unknown>; }[]+id: number+name: string+visible: boolean | undefined+```+## EventBinding — const @experimental```ComponentDef<EventBindingData>@@ -7370,6 +7414,18 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAmbientLight — interface @experimental+```+drawEnvironment: boolean+entityId: number+environment: string | null+environmentMissing: boolean+intensity: number+name: string+rotation: number+skipped: AmbientSkip | null+```+## SceneAssetRefs — interface @experimental```byType: Map<string, Set<string>>@@ -7423,6 +7479,11 @@ trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => voidunbindPostProcess: (camera: Entity) => void```+## SceneDark — type @experimental+```+'no-lights' | 'no-enabled-light'+```+## SceneData — interface @experimental```entities: SceneEntityData[]@@ -7916,6 +7977,11 @@ vertices: Uint8Array<ArrayBufferLike>| { kind: 'sh'; irradiance: readonly number[]; yaw: number; tint: readonly [number, number, number] }```+## SkyUnavailable — type @experimental+```+'no-ambient' | 'no-environment' | 'missing' | 'off' | 'unusable'+```+## SliceBorder — interface @experimental```bottom: number@@ -8526,6 +8592,14 @@ ComponentDef<StreamedWorldData>cellSize: number```+## StudioPreviewReport — interface @experimental+```+environment: SceneAmbientLight | null+sceneDark: SceneDark | null+sceneLights: number+skyUnavailable: SkyUnavailable | null+```+## SubEmitterTrigger — enum @beta```Birth = 1@@ -10821,6 +10895,11 @@ MotionDriver<AnimatorBlend2DMotion>(at: readonly [number, number, number], bvh: Bvh, lookup: HitLookup, atlas: Float32Array, atlasSize: number, width: number, height: number, sky: SkyRadiance): CapturedPanorama```+## carriesEnvironment — function @experimental+```+(light: SceneAmbientLight): boolean+```+## catalogFromManifest — function @experimental```(manifest: AddressableManifest): Catalog | undefined@@ -11361,6 +11440,16 @@ DragPlugin(view: EditorViewData): boolean```+## editorViewLightingArgs — function @experimental+```+(data: EditorViewLightingData, viewActive: boolean): { mode: number; rotation: number; key: number; fill: number; sky: number; showSky: boolean; exposure: number; }+```++## editorViewLightingIsOverriding — function @experimental+```+(data: EditorViewLightingData): boolean+```+## editorViewStandoff — function @experimental```(view: EditorViewData): number@@ -12771,6 +12860,11 @@ PrefabsPlugin(): CppResourceManager```+## resetEditorViewLighting — function @experimental+```+(data: EditorViewLightingData): EditorViewLightingData+```+## resetWorldTo — function @experimental```(world: World, sceneData: SceneData): Map<number, Entity>@@ -12861,6 +12955,16 @@ SafeAreaPlugin{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }```+## sceneAmbientLights — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]+```++## sceneEnvironment — function @experimental+```+(lights: readonly SceneAmbientLight[]): { effective: SceneAmbientLight | null; shadowed: SceneAmbientLight[]; }+```+## sceneManagerPlugin — const @experimental```Plugin@@ -13246,6 +13350,11 @@ StatsPlugin(world: World, entity: Entity): void```+## studioPreviewReport — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): StudioPreviewReport+```+## summarizeCapture — function @experimental```(capture: ProfileCapture): CaptureSummarydiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 7d4a0b808..20af3f57b 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 109 beta · 1602 experimental · 3 deprecated+Symbols: 115 public · 109 beta · 1620 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -299,6 +299,11 @@ Start = 1Stretch = 4```+## AmbientSkip — type @experimental+```+'hidden' | 'disabled' | 'no-intensity'+```+## Ambiguity — interface @experimental```a: string@@ -2695,6 +2700,11 @@ EditorGridDataEditorViewData```+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental+```+EditorViewLightingData+```+## DEFAULT_FACING_COSINE — const @experimental```0.2@@ -3343,6 +3353,11 @@ tabIndex: number | undefinedworld: World```+## EDITOR_EXPOSURE_RANGE — const @experimental+```+{ readonly min: -6; readonly max: 6; }+```+## EDITOR_UI_ANCHOR — const @experimental```{ readonly x: 0; readonly y: 0; }@@ -3413,6 +3428,11 @@ majorEvery: numberspacing: number```+## EditorLightingMode — type @experimental+```+'scene' | 'studio'+```+## EditorView — const @experimental```ResourceDef<EditorViewData>@@ -3440,6 +3460,22 @@ yaw: numberz: number```+## EditorViewLighting — const @experimental+```+ResourceDef<EditorViewLightingData>+```++## EditorViewLightingData — interface @experimental+```+exposure: number+fillIntensity: number+keyIntensity: number+mode: EditorLightingMode+rotation: number+showSky: boolean+skyIntensity: number+```+## EditorWorkPlane — interface @experimental```normal: WorldAxis@@ -3584,6 +3620,14 @@ pickable: ((entity: Entity) => boolean) | undefinedySortLayers: number | undefined```+## EnvironmentLightEntity — interface @experimental+```+components: readonly { type: string; data: Record<string, unknown>; }[]+id: number+name: string+visible: boolean | undefined+```+## EventBinding — const @experimental```ComponentDef<EventBindingData>@@ -7663,6 +7707,18 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAmbientLight — interface @experimental+```+drawEnvironment: boolean+entityId: number+environment: string | null+environmentMissing: boolean+intensity: number+name: string+rotation: number+skipped: AmbientSkip | null+```+## SceneAssetRefs — interface @experimental```byType: Map<string, Set<string>>@@ -7716,6 +7772,11 @@ trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => voidunbindPostProcess: (camera: Entity) => void```+## SceneDark — type @experimental+```+'no-lights' | 'no-enabled-light'+```+## SceneData — interface @experimental```entities: SceneEntityData[]@@ -8209,6 +8270,11 @@ vertices: Uint8Array<ArrayBufferLike>| { kind: 'sh'; irradiance: readonly number[]; yaw: number; tint: readonly [number, number, number] }```+## SkyUnavailable — type @experimental+```+'no-ambient' | 'no-environment' | 'missing' | 'off' | 'unusable'+```+## SliceBorder — interface @experimental```bottom: number@@ -8819,6 +8885,14 @@ ComponentDef<StreamedWorldData>cellSize: number```+## StudioPreviewReport — interface @experimental+```+environment: SceneAmbientLight | null+sceneDark: SceneDark | null+sceneLights: number+skyUnavailable: SkyUnavailable | null+```+## SubEmitterTrigger — enum @beta```Birth = 1@@ -11120,6 +11194,11 @@ MotionDriver<AnimatorBlend2DMotion>(at: readonly [number, number, number], bvh: Bvh, lookup: HitLookup, atlas: Float32Array, atlasSize: number, width: number, height: number, sky: SkyRadiance): CapturedPanorama```+## carriesEnvironment — function @experimental+```+(light: SceneAmbientLight): boolean+```+## catalogFromManifest — function @experimental```(manifest: AddressableManifest): Catalog | undefined@@ -11665,6 +11744,16 @@ DragPlugin(view: EditorViewData): boolean```+## editorViewLightingArgs — function @experimental+```+(data: EditorViewLightingData, viewActive: boolean): { mode: number; rotation: number; key: number; fill: number; sky: number; showSky: boolean; exposure: number; }+```++## editorViewLightingIsOverriding — function @experimental+```+(data: EditorViewLightingData): boolean+```+## editorViewStandoff — function @experimental```(view: EditorViewData): number@@ -13075,6 +13164,11 @@ PrefabsPlugin(): CppResourceManager```+## resetEditorViewLighting — function @experimental+```+(data: EditorViewLightingData): EditorViewLightingData+```+## resetWorldTo — function @experimental```(world: World, sceneData: SceneData): Map<number, Entity>@@ -13165,6 +13259,16 @@ SafeAreaPlugin{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }```+## sceneAmbientLights — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]+```++## sceneEnvironment — function @experimental+```+(lights: readonly SceneAmbientLight[]): { effective: SceneAmbientLight | null; shadowed: SceneAmbientLight[]; }+```+## sceneManagerPlugin — const @experimental```Plugin@@ -13550,6 +13654,11 @@ StatsPlugin(world: World, entity: Entity): void```+## studioPreviewReport — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): StudioPreviewReport+```+## summarizeCapture — function @experimental```(capture: ProfileCapture): CaptureSummarydiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex d06e82f9f..c0c3af074 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -398,6 +398,7 @@ postprocess_setScreenUniformFloat: (passName: string, uniform: string, value: nupostprocess_setScreenUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => voidpostprocess_setUniformFloat: (passName: string, uniform: string, value: number) => voidpostprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => void+postprocess_setViewExposure: ((ev: number) => void) | undefinedpostprocess_shutdown: () => voidprobe_volume_create: ((resX: number, resY: number, resZ: number, shPtr: number) => number) | undefinedprobe_volume_release: ((volumeHandle: number) => void) | undefined@@ -489,6 +490,7 @@ renderer_setShadowDistance: ((distance: number) => void) | undefinedrenderer_setStage: (stage: number) => voidrenderer_setTextureParams: (textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number) => voidrenderer_setViewId: ((view: number) => void) | undefined+renderer_setViewLighting: ((mode: number, rotationDegrees: number, keyIntensity: number, fillIntensity: number, skyIntensity: number, showSky: boolean) => void) | undefinedrenderer_setViewport: (x: number, y: number, w: number, h: number) => voidrenderer_setYSortLayers: ((mask: number) => void) | undefinedrenderer_shadowStatus: ((entity: number, outPtr: number) => number) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex d90773976..bc5ce6e57 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 109 beta · 1593 experimental · 3 deprecated+Symbols: 115 public · 109 beta · 1611 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -299,6 +299,11 @@ Start = 1Stretch = 4```+## AmbientSkip — type @experimental+```+'hidden' | 'disabled' | 'no-intensity'+```+## Ambiguity — interface @experimental```a: string@@ -2695,6 +2700,11 @@ EditorGridDataEditorViewData```+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental+```+EditorViewLightingData+```+## DEFAULT_FACING_COSINE — const @experimental```0.2@@ -3343,6 +3353,11 @@ tabIndex: number | undefinedworld: World```+## EDITOR_EXPOSURE_RANGE — const @experimental+```+{ readonly min: -6; readonly max: 6; }+```+## EDITOR_UI_ANCHOR — const @experimental```{ readonly x: 0; readonly y: 0; }@@ -3413,6 +3428,11 @@ majorEvery: numberspacing: number```+## EditorLightingMode — type @experimental+```+'scene' | 'studio'+```+## EditorView — const @experimental```ResourceDef<EditorViewData>@@ -3440,6 +3460,22 @@ yaw: numberz: number```+## EditorViewLighting — const @experimental+```+ResourceDef<EditorViewLightingData>+```++## EditorViewLightingData — interface @experimental+```+exposure: number+fillIntensity: number+keyIntensity: number+mode: EditorLightingMode+rotation: number+showSky: boolean+skyIntensity: number+```+## EditorWorkPlane — interface @experimental```normal: WorldAxis@@ -3584,6 +3620,14 @@ pickable: ((entity: Entity) => boolean) | undefinedySortLayers: number | undefined```+## EnvironmentLightEntity — interface @experimental+```+components: readonly { type: string; data: Record<string, unknown>; }[]+id: number+name: string+visible: boolean | undefined+```+## EventBinding — const @experimental```ComponentDef<EventBindingData>@@ -7377,6 +7421,18 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAmbientLight — interface @experimental+```+drawEnvironment: boolean+entityId: number+environment: string | null+environmentMissing: boolean+intensity: number+name: string+rotation: number+skipped: AmbientSkip | null+```+## SceneAssetRefs — interface @experimental```byType: Map<string, Set<string>>@@ -7430,6 +7486,11 @@ trackAssets: (byType: ReadonlyMap<string, ReadonlySet<string>>) => voidunbindPostProcess: (camera: Entity) => void```+## SceneDark — type @experimental+```+'no-lights' | 'no-enabled-light'+```+## SceneData — interface @experimental```entities: SceneEntityData[]@@ -7923,6 +7984,11 @@ vertices: Uint8Array<ArrayBufferLike>| { kind: 'sh'; irradiance: readonly number[]; yaw: number; tint: readonly [number, number, number] }```+## SkyUnavailable — type @experimental+```+'no-ambient' | 'no-environment' | 'missing' | 'off' | 'unusable'+```+## SliceBorder — interface @experimental```bottom: number@@ -8533,6 +8599,14 @@ ComponentDef<StreamedWorldData>cellSize: number```+## StudioPreviewReport — interface @experimental+```+environment: SceneAmbientLight | null+sceneDark: SceneDark | null+sceneLights: number+skyUnavailable: SkyUnavailable | null+```+## SubEmitterTrigger — enum @beta```Birth = 1@@ -10852,6 +10926,11 @@ MotionDriver<AnimatorBlend2DMotion>(at: readonly [number, number, number], bvh: Bvh, lookup: HitLookup, atlas: Float32Array, atlasSize: number, width: number, height: number, sky: SkyRadiance): CapturedPanorama```+## carriesEnvironment — function @experimental+```+(light: SceneAmbientLight): boolean+```+## catalogFromManifest — function @experimental```(manifest: AddressableManifest): Catalog | undefined@@ -11392,6 +11471,16 @@ DragPlugin(view: EditorViewData): boolean```+## editorViewLightingArgs — function @experimental+```+(data: EditorViewLightingData, viewActive: boolean): { mode: number; rotation: number; key: number; fill: number; sky: number; showSky: boolean; exposure: number; }+```++## editorViewLightingIsOverriding — function @experimental+```+(data: EditorViewLightingData): boolean+```+## editorViewStandoff — function @experimental```(view: EditorViewData): number@@ -12802,6 +12891,11 @@ PrefabsPlugin(): CppResourceManager```+## resetEditorViewLighting — function @experimental+```+(data: EditorViewLightingData): EditorViewLightingData+```+## resetWorldTo — function @experimental```(world: World, sceneData: SceneData): Map<number, Entity>@@ -12892,6 +12986,16 @@ SafeAreaPlugin{ readonly clamp: (x: number, min: number, max: number) => number; readonly clamp01: (x: number) => number; readonly lerp: (a: number, b: number, t: number) => number; readonly inverseLerp: (a: number, b: number, value: number) => number; readonly remap: (value: number, inMin: number, inMax: number, outMin: number, outMax: number) => number; readonly deg2rad: (deg: number) => number; readonly rad2deg: (rad: number) => number; readonly approximately: (a: number, b: number, epsilon?: number) => boolean; readonly smoothstep: (edge0: number, edge1: number, x: number) => number; readonly mod: (x: number, n: number) => number; readonly sign: (x: number) => number; }```+## sceneAmbientLights — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): SceneAmbientLight[]+```++## sceneEnvironment — function @experimental+```+(lights: readonly SceneAmbientLight[]): { effective: SceneAmbientLight | null; shadowed: SceneAmbientLight[]; }+```+## sceneManagerPlugin — const @experimental```Plugin@@ -13277,6 +13381,11 @@ StatsPlugin(world: World, entity: Entity): void```+## studioPreviewReport — function @experimental+```+(entities: readonly EnvironmentLightEntity[], exists: (ref: string) => boolean): StudioPreviewReport+```+## summarizeCapture — function @experimental```(capture: ProfileCapture): CaptureSummarydiff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex ed016af34..631b82c95 100644--- a/sdk/src/camera/CameraPlugin.ts+++ b/sdk/src/camera/CameraPlugin.ts@@ -22,6 +22,7 @@ import { ScreenOverlay } from '../ui/core/screen-overlay';import { ProjectionType, SceneOwner, ClearFlags } from '../ecs/component';import { canvasRootEntities } from '../ui/core/canvas-roots';import { uiLayoutRect, computeEffectiveOrthoSize, EDITOR_VIEW_ENTITY, type CanvasScale } from './uiLayoutRect';+import { EditorViewLighting, DEFAULT_EDITOR_VIEW_LIGHTING, pushEditorViewLighting } from './EditorViewLighting';import { EditorView, DEFAULT_EDITOR_VIEW, editorViewStandoff, editorViewClipFar, editorViewClipNear, type EditorViewData } from './EditorView';import { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './ScreenScaling';import { planPresent, viewportPixels, RenderResolution } from './presentPlan';@@ -782,6 +783,9 @@ export function cameraPlugin(// The editor view is inactive by default — shipped games never touch// it; the editor activates it in edit mode (see desktop EngineHost).app.insertResource(EditorView, { ...DEFAULT_EDITOR_VIEW });+ // Its lighting is the view's too: untouched, the scene renders by its own.+ app.insertResource(EditorViewLighting, { ...DEFAULT_EDITOR_VIEW_LIGHTING });+ let lastViewLighting = '';// The camera director: by default it just tracks the active camera;// games call setViewTarget(app, entity, {time, curve}) to blend, or// shakeCamera(app, {...}) to shake. Fresh state (own arrays) per App.@@ -845,6 +849,12 @@ export function cameraPlugin(// Transforms resolve BEFORE any camera is read — a view is built// from Transform.worldPosition, and a pass behind the read hands// back the previous frame's placement. beginFrame clears the memo.+ // The editor view's lighting reaches the engine only while that view is+ // the one drawing; play mode and shipped games push the neutral state.+ lastViewLighting = pushEditorViewLighting(+ module, app.getResource(EditorViewLighting),+ app.hasResource(EditorView) && app.getResource(EditorView).active,+ lastViewLighting);pipeline.beginFrame(elapsed);app.measureFrameScope('render.updateTransforms', () =>Renderer.updateTransforms({ _cpp: cppRegistry }));diff --git a/sdk/src/camera/EditorViewLighting.ts b/sdk/src/camera/EditorViewLighting.tsnew file mode 100644index 000000000..d0c84f1f8--- /dev/null+++ b/sdk/src/camera/EditorViewLighting.ts@@ -0,0 +1,159 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file EditorViewLighting.ts+ * @brief The editor viewport's own lighting and exposure — view state, like EditorView.+ *+ * @details "Scene lighting" shows the scene by the lights it carries. "Studio preview"+ * replaces them, for the eye only, with a neutral sky, a key and a fill, so a+ * model the scene left dark can be read while it is authored. The exposure is+ * a second, independent control: a stop count applied where the frame is+ * written out, the same exp2(EV) the post-process exposure uses.+ *+ * None of it is a scene entity, none of it is serialized, and it reaches the+ * engine only while the editor view is active — a packaged build never inserts+ * the view, never calls the engine setters, and so renders by the scene's own+ * settings. Play mode deactivates the view and with it every override here.+ */+import { defineResource } from '../ecs/resource';+import type { ESEngineModule } from '../wasm';+import { COMPONENT_META } from '../lightmap/metaAccess';+import { LightType } from '../wasm/wasm.generated';+import {+ sceneAmbientLights, sceneEnvironment, carriesEnvironment,+ type EnvironmentLightEntity, type SceneAmbientLight,+} from '../lightmap/environmentLight';++export type EditorLightingMode = 'scene' | 'studio';++export interface EditorViewLightingData {+ mode: EditorLightingMode;+ /** Degrees about +Y that the key and the fill turn together. */+ rotation: number;+ keyIntensity: number;+ fillIntensity: number;+ /** Scales the neutral sky. Never the scene's Ambient: that light is not consulted. */+ skyIntensity: number;+ /** Draw the scene's environment as the background while studio-lit. */+ showSky: boolean;+ /** Preview exposure in stops, independent of the mode. 0 is exact identity. */+ exposure: number;+}++export const DEFAULT_EDITOR_VIEW_LIGHTING: EditorViewLightingData = {+ mode: 'scene', rotation: 0, keyIntensity: 0.8, fillIntensity: 0.3,+ skyIntensity: 1, showSky: false, exposure: 0,+};++export const EDITOR_EXPOSURE_RANGE = { min: -6, max: 6 } as const;++export const EditorViewLighting = defineResource<EditorViewLightingData>(+ { ...DEFAULT_EDITOR_VIEW_LIGHTING }, 'EditorViewLighting');++/** True when the view differs from the game's own settings in any way. */+export function editorViewLightingIsOverriding(data: EditorViewLightingData): boolean {+ return data.mode === 'studio' || data.exposure !== 0;+}++/** The game's own settings: studio off and exposure at zero. The rig's tuning is kept. */+export function resetEditorViewLighting(data: EditorViewLightingData): EditorViewLightingData {+ return { ...data, mode: 'scene', exposure: 0 };+}++/** The numbers the engine setters take, so the push and its tests share one reading. */+export function editorViewLightingArgs(data: EditorViewLightingData, viewActive: boolean): {+ mode: number; rotation: number; key: number; fill: number; sky: number; showSky: boolean; exposure: number;+} {+ // An inactive view (play mode, a packaged build) carries no override at all.+ if (!viewActive) return { mode: 0, rotation: 0, key: 0, fill: 0, sky: 1, showSky: false, exposure: 0 };+ const finite = (v: number, fallback: number) => (Number.isFinite(v) ? v : fallback);+ return {+ mode: data.mode === 'studio' ? 1 : 0,+ rotation: finite(data.rotation, 0),+ key: Math.max(0, finite(data.keyIntensity, 0)),+ fill: Math.max(0, finite(data.fillIntensity, 0)),+ sky: Math.max(0, finite(data.skyIntensity, 1)),+ showSky: data.showSky,+ exposure: Math.min(EDITOR_EXPOSURE_RANGE.max, Math.max(EDITOR_EXPOSURE_RANGE.min, finite(data.exposure, 0))),+ };+}++/**+ * Pushes the view's lighting to the engine, once per change. Returns the key it last+ * pushed, so a caller skips the crossing while nothing moved.+ */+export function pushEditorViewLighting(+ module: ESEngineModule | null,+ data: EditorViewLightingData,+ viewActive: boolean,+ lastKey: string,+): string {+ const a = editorViewLightingArgs(data, viewActive);+ const key = `${a.mode}|${a.rotation}|${a.key}|${a.fill}|${a.sky}|${a.showSky}|${a.exposure}`;+ // A module that does not carry the setters (an older core) is simply not+ // overridden; the key still advances so it is not asked every frame.+ if (key === lastKey || !module) return lastKey;+ module.renderer_setViewLighting?.(a.mode, a.rotation, a.key, a.fill, a.sky, a.showSky);+ module.postprocess_setViewExposure?.(a.exposure);+ return key;+}++export type SkyUnavailable = 'no-ambient' | 'no-environment' | 'missing' | 'off' | 'unusable';+export type SceneDark = 'no-lights' | 'no-enabled-light';++/** What a scene gives the studio preview to say about itself. */+export interface StudioPreviewReport {+ /** Non-Ambient lights that are visible, enabled and have intensity. */+ sceneLights: number;+ /** The environment the scene's own frame would use, or null. */+ environment: SceneAmbientLight | null;+ /** Why there is no environment to show as a sky, or null when there is one. */+ skyUnavailable: SkyUnavailable | null;+ /** Why the scene alone would read dark, or null when it has light. */+ sceneDark: SceneDark | null;+}++/**+ * The actual reasons, read from the scene document: nothing here guesses at what the+ * engine did. The Lighting panel uses it to say why a toggle is disabled or why the+ * scene looks dark without the studio.+ */+export function studioPreviewReport(+ entities: readonly EnvironmentLightEntity[],+ exists: (ref: string) => boolean,+): StudioPreviewReport {+ const meta = COMPONENT_META['Light'];+ const defaults = {+ ...(meta?.defaults as Record<string, unknown> | undefined),+ ...(meta?.editorDefaults as Record<string, unknown> | undefined),+ };+ let lit = 0;+ let anyLight = 0;+ for (const entity of entities) {+ for (const c of entity.components) {+ if (c.type !== 'Light') continue;+ anyLight++;+ const type = (c.data.type ?? defaults.type ?? 0) as number;+ if (type === LightType.Ambient) continue;+ const enabled = (c.data.enabled ?? defaults.enabled ?? true) !== false;+ const intensity = (c.data.intensity ?? defaults.intensity ?? 1) as number;+ if (entity.visible !== false && enabled && intensity > 0) lit++;+ }+ }+ const ambient = sceneAmbientLights(entities, exists);+ const { effective } = sceneEnvironment(ambient);+ const named = ambient.filter((l) => l.environment !== null);++ let skyUnavailable: SkyUnavailable | null = null;+ if (!effective) {+ if (ambient.length === 0) skyUnavailable = 'no-ambient';+ else if (named.length === 0) skyUnavailable = 'no-environment';+ else if (named.every((l) => l.environmentMissing)) skyUnavailable = 'missing';+ else if (named.some((l) => l.skipped !== null && !carriesEnvironment(l))) skyUnavailable = 'off';+ else skyUnavailable = 'unusable';+ }++ let sceneDark: SceneDark | null = null;+ if (lit === 0 && !effective) sceneDark = anyLight === 0 ? 'no-lights' : 'no-enabled-light';+ return { sceneLights: lit, environment: effective, skyUnavailable, sceneDark };+}diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex b85769f2b..804de1435 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -46,6 +46,8 @@ export { CameraCommit, onCameraCommitChanged, cameraCommitChanged,type CameraCommitData, type CameraCommitListener } from './camera/CameraCommit';export { EditorView, DEFAULT_EDITOR_VIEW, editorViewHalfHeight, editorViewHalfExtent, editorViewWorldPerPixel, setEditorViewHalfHeight, editorViewIsOrbited, editorViewAxes, editorViewAxisAngles, editorViewBasis, editorViewEye, editorViewStandoff, editorViewClipFar, editorViewClipNear, editorViewWorkPlane, editorViewGridPlane, screenWorkAxes, worldAxisVector, moveEditorViewFocus, editorViewBoxExtent } from './camera/EditorView';export type { EditorViewData, ScreenAxis, EditorViewBasis, EditorWorkPlane, WorldAxis } from './camera/EditorView';+export { EditorViewLighting, DEFAULT_EDITOR_VIEW_LIGHTING, EDITOR_EXPOSURE_RANGE, editorViewLightingIsOverriding, resetEditorViewLighting, editorViewLightingArgs, studioPreviewReport } from './camera/EditorViewLighting';+export type { EditorViewLightingData, EditorLightingMode, StudioPreviewReport, SkyUnavailable, SceneDark } from './camera/EditorViewLighting';export { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './camera/ScreenScaling';export type { ScreenScalingData } from './camera/ScreenScaling';export { EditorGrid, DEFAULT_EDITOR_GRID } from './camera/EditorGrid';diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 1683a0dc7..578580b63 100644--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts@@ -119,6 +119,7 @@ export interface NativeEngineApi {postprocess_setScreenUniformVec4?(passName: string, uniform: string, x: number, y: number, z: number, w: number): void;postprocess_setUniformFloat?(passName: string, uniform: string, value: number): void;postprocess_setUniformVec4?(passName: string, uniform: string, x: number, y: number, z: number, w: number): void;+ postprocess_setViewExposure?(ev: number): void;postprocess_shutdown?(): void;probe_volume_create?(resX: number, resY: number, resZ: number, shPtr: number): number;probe_volume_release?(volumeHandle: number): void;@@ -202,6 +203,7 @@ export interface NativeEngineApi {renderer_setStage?(stage: number): void;renderer_setTextureParams?(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void;renderer_setViewId?(view: number): void;+ renderer_setViewLighting?(mode: number, rotationDegrees: number, keyIntensity: number, fillIntensity: number, skyIntensity: number, showSky: boolean): void;renderer_setViewport?(x: number, y: number, w: number, h: number): void;renderer_setYSortLayers?(mask: number): void;renderer_shadowStatus?(entity: number, outPtr: number): number;@@ -417,6 +419,7 @@ export function createNativeEngineApi(bind('postprocess_setScreenUniformVec4', 'es_postprocess_setScreenUniformVec4', false);bind('postprocess_setUniformFloat', 'es_postprocess_setUniformFloat', false);bind('postprocess_setUniformVec4', 'es_postprocess_setUniformVec4', false);+ bind('postprocess_setViewExposure', 'es_postprocess_setViewExposure', false);bind('postprocess_shutdown', 'es_postprocess_shutdown', false);bind('probe_volume_create', 'es_probe_volume_create', false);bind('probe_volume_release', 'es_probe_volume_release', false);@@ -500,6 +503,7 @@ export function createNativeEngineApi(bind('renderer_setStage', 'es_renderer_setStage', false);bind('renderer_setTextureParams', 'es_renderer_setTextureParams', false);bind('renderer_setViewId', 'es_renderer_setViewId', false);+ bind('renderer_setViewLighting', 'es_renderer_setViewLighting', false);bind('renderer_setViewport', 'es_renderer_setViewport', false);bind('renderer_setYSortLayers', 'es_renderer_setYSortLayers', false);bind('renderer_shadowStatus', 'es_renderer_shadowStatus', false);diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 3006fb050..7fb258ff7 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -539,6 +539,7 @@ export interface ESEngineModule {/** The curve the chain applies on the way out: 0 = none, 1 = ACES filmic.* Absent on an engine built before the output transform existed. */postprocess_setOutputTransform?(transform: number): void;+ postprocess_setViewExposure?(ev: 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. */@@ -666,6 +667,7 @@ export interface ESEngineModule {renderer_setQualityBudgets?(atlasSize: number, cellSize: number,cascades: number, particleLimit: number): void;renderer_setShadowDistance?(distance: number): void;+ renderer_setViewLighting?(mode: number, rotationDegrees: number, keyIntensity: number, fillIntensity: number, skyIntensity: number, showSky: boolean): void;renderer_setCullingMask?(mask: number): void;renderer_setViewId?(view: number): void;renderer_lodInspect?(view: number, entity: number, outPtr: number): number;diff --git a/sdk/tests/editor-view-lighting.test.ts b/sdk/tests/editor-view-lighting.test.tsnew file mode 100644index 000000000..1ab595d38--- /dev/null+++ b/sdk/tests/editor-view-lighting.test.ts@@ -0,0 +1,91 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * The editor view's lighting is VIEW state: it reaches the engine only while the editor eye+ * is the one drawing, it never carries a value the engine cannot take, and the scene's+ * own reasons for being dark are read from the document, not guessed.+ */+import { describe, it, expect } from 'vitest';+import {+ DEFAULT_EDITOR_VIEW_LIGHTING, EDITOR_EXPOSURE_RANGE, editorViewLightingArgs,+ editorViewLightingIsOverriding, resetEditorViewLighting, studioPreviewReport,+} from '../src/camera/EditorViewLighting';+import { pushEditorViewLighting } from '../src/camera/EditorViewLighting';+import type { EnvironmentLightEntity } from '../src/lightmap';++const studio = { ...DEFAULT_EDITOR_VIEW_LIGHTING, mode: 'studio' as const, exposure: 1.5, rotation: 30 };++describe('what reaches the engine', () => {+ it('is the neutral state whenever the editor eye is not drawing', () => {+ expect(editorViewLightingArgs(studio, false)).toEqual({+ mode: 0, rotation: 0, key: 0, fill: 0, sky: 1, showSky: false, exposure: 0,+ });+ });++ it('is the studio rig while it is, with every number made safe', () => {+ const a = editorViewLightingArgs({ ...studio, keyIntensity: -3, fillIntensity: Number.NaN, exposure: 40 }, true);+ expect(a.mode).toBe(1);+ expect(a.rotation).toBe(30);+ expect(a.key).toBe(0);+ expect(a.fill).toBe(0);+ expect(a.exposure).toBe(EDITOR_EXPOSURE_RANGE.max);+ });++ it('crosses into the engine once per change, and leaves the old core alone', () => {+ const calls: unknown[][] = [];+ const module = {+ renderer_setViewLighting: (...a: unknown[]) => calls.push(['light', ...a]),+ postprocess_setViewExposure: (...a: unknown[]) => calls.push(['ev', ...a]),+ } as never;+ let key = '';+ key = pushEditorViewLighting(module, studio, true, key);+ key = pushEditorViewLighting(module, studio, true, key);+ expect(calls).toHaveLength(2);+ // Play mode deactivates the eye: the very next frame is the game's own.+ key = pushEditorViewLighting(module, studio, false, key);+ expect(calls.slice(2)).toEqual([['light', 0, 0, 0, 0, 1, false], ['ev', 0]]);+ expect(() => pushEditorViewLighting({} as never, studio, true, '')).not.toThrow();+ });+});++describe('returning to the game', () => {+ it('is studio off and exposure zero, and nothing else', () => {+ expect(editorViewLightingIsOverriding(DEFAULT_EDITOR_VIEW_LIGHTING)).toBe(false);+ expect(editorViewLightingIsOverriding(studio)).toBe(true);+ expect(editorViewLightingIsOverriding({ ...DEFAULT_EDITOR_VIEW_LIGHTING, exposure: -1 })).toBe(true);+ expect(resetEditorViewLighting(studio)).toEqual({ ...studio, mode: 'scene', exposure: 0 });+ });+});++let next = 1;+const light = (data: Record<string, unknown>, visible?: boolean): EnvironmentLightEntity =>+ ({ id: next++, name: `L${next}`, ...(visible === undefined ? {} : { visible }), components: [{ type: 'Light', data }] });+const all = (): boolean => true;++describe('why the scene is dark, from the document', () => {+ it('says a scene with no lights has none', () => {+ const r = studioPreviewReport([], all);+ expect(r.sceneDark).toBe('no-lights');+ expect(r.skyUnavailable).toBe('no-ambient');+ });++ it('is not dark when a light shines, and says so only about what is missing', () => {+ const r = studioPreviewReport([light({ type: 1 })], all);+ expect(r.sceneLights).toBe(1);+ expect(r.sceneDark).toBeNull();+ expect(r.skyUnavailable).toBe('no-ambient');+ });++ it('names a disabled light as no light', () => {+ expect(studioPreviewReport([light({ type: 1, enabled: false })], all).sceneDark).toBe('no-enabled-light');+ });++ it('tells apart an Ambient that names nothing, one that names a missing file, and a usable one', () => {+ expect(studioPreviewReport([light({ type: 2 })], all).skyUnavailable).toBe('no-environment');+ expect(studioPreviewReport([light({ type: 2, environment: 'a.esenv' })], () => false).skyUnavailable).toBe('missing');+ const ok = studioPreviewReport([light({ type: 2, environment: 'a.esenv' })], all);+ expect(ok.skyUnavailable).toBeNull();+ expect(ok.environment).not.toBeNull();+ expect(ok.sceneDark).toBeNull();+ });+});diff --git a/src/esengine/bindings/PostProcessBindings.cpp b/src/esengine/bindings/PostProcessBindings.cppindex c0be6e594..b5952a264 100644--- a/src/esengine/bindings/PostProcessBindings.cpp+++ b/src/esengine/bindings/PostProcessBindings.cpp@@ -172,6 +172,10 @@ void postprocess_setOutputTransform(u32 transform) {: OutputTransform::None);}+void postprocess_setViewExposure(f32 ev) {+ if (g_postProcessPipeline) g_postProcessPipeline->setViewExposure(ev);+}+void postprocess_clearPasses() {if (g_postProcessPipeline) {g_postProcessPipeline->clearPasses();diff --git a/src/esengine/bindings/PostProcessBindings.hpp b/src/esengine/bindings/PostProcessBindings.hppindex da2b2db76..658e24528 100644--- a/src/esengine/bindings/PostProcessBindings.hpp+++ b/src/esengine/bindings/PostProcessBindings.hpp@@ -52,6 +52,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);+/** The editor view's exposure in stops (EV); 0 is exact identity. View state, never saved. */+void postprocess_setViewExposure(f32 ev);void postprocess_clearPasses();void postprocess_setOutputViewport(u32 x, u32 y, u32 w, u32 h);/** Say the frame needs a present even when the two rects look alike; seediff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex b584ea88d..ec304be16 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -1,6 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+#include <cmath>#include "RendererBindings.hpp"#include "TestProbeBindings.hpp"@@ -1039,6 +1040,19 @@ void renderer_setDepthLayers(u32 mask) {if (auto* frame = g_renderFrame) frame->setDepthLayers(mask);}+void renderer_setViewLighting(u32 mode, f32 rotationDegrees, f32 keyIntensity, f32 fillIntensity,+ f32 skyIntensity, bool showSky) {+ if (!g_renderFrame) return;+ RenderFrame::ViewLighting lighting;+ lighting.studio = mode == 1;+ lighting.rotation = std::isfinite(rotationDegrees) ? rotationDegrees : 0.0f;+ lighting.keyIntensity = std::isfinite(keyIntensity) ? std::max(keyIntensity, 0.0f) : 0.0f;+ lighting.fillIntensity = std::isfinite(fillIntensity) ? std::max(fillIntensity, 0.0f) : 0.0f;+ lighting.skyIntensity = std::isfinite(skyIntensity) ? std::max(skyIntensity, 0.0f) : 0.0f;+ lighting.showSky = showSky;+ g_renderFrame->setViewLighting(lighting);+}+void renderer_setShadowDistance(f32 distance) {if (g_renderFrame) g_renderFrame->setShadowDistance(distance);}diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex 03451e0e5..3789ac0d6 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -26,6 +26,13 @@ void renderer_init(u32 width, u32 height);void renderer_resize(u32 width, u32 height);void renderer_setQualityBudgets(u32 atlasSize, u32 cellSize, u32 cascades, u32 particleLimit);void renderer_setShadowDistance(f32 distance);+/**+ * The editor view's lighting. mode 0 = the scene's own lights (the default, and the+ * only one a packaged build ever has); 1 = studio: a neutral sky, a key and a fill, in+ * their place. View state — nothing here is saved with a scene.+ */+void renderer_setViewLighting(u32 mode, f32 rotationDegrees, f32 keyIntensity, f32 fillIntensity,+ f32 skyIntensity, bool showSky);void renderer_beginFrame(f32 elapsedSec);void renderer_begin(uintptr_t matrixPtr, u32 targetHandle, i32 clearFlags,f32 r, f32 g, f32 b, f32 a,diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 63b3fff1c..9f60f63d0 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -611,6 +611,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_setViewExposure", &esengine::postprocess_setViewExposure);emscripten::function("postprocess_clearPasses", &esengine::postprocess_clearPasses);emscripten::function("postprocess_setOutputViewport", &esengine::postprocess_setOutputViewport);emscripten::function("postprocess_setPresentRequired", &esengine::postprocess_setPresentRequired);@@ -766,6 +767,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("renderer_setDepthLayers", &esengine::renderer_setDepthLayers);emscripten::function("renderer_setQualityBudgets", &esengine::renderer_setQualityBudgets);emscripten::function("renderer_setShadowDistance", &esengine::renderer_setShadowDistance);+ emscripten::function("renderer_setViewLighting", &esengine::renderer_setViewLighting);emscripten::function("renderer_setCullingMask", &esengine::renderer_setCullingMask);emscripten::function("renderer_setViewId", &esengine::renderer_setViewId);emscripten::function("renderer_lodInspect", &esengine::renderer_lodInspect);diff --git a/src/esengine/data/shaders/blit.esshader b/src/esengine/data/shaders/blit.esshaderindex a26355d87..96244e3b7 100644--- a/src/esengine/data/shaders/blit.esshader+++ b/src/esengine/data/shaders/blit.esshader@@ -11,6 +11,9 @@ out vec4 fragColor;void main() {vec4 c = texture(u_texture, v_texCoord);+ // The editor view's exposure (u_time.z, stops): zero outside the editor, where+ // exp2(0) = 1 leaves every pixel as it was. Before the curve, like any exposure.+ c = vec4(c.rgb * exp2(u_time.z), c.a);#ifdef ES_TONEMAP// The output transform: scene radiance can exceed 1.0 on an HDR target,// and this is the one place a chain maps it down. Before the OETF, which@@ -30,6 +33,7 @@ void main() {#pragma fragment wgsl@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {var c = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);+ c = vec4f(c.rgb * exp2(tc.u_time.z), c.a);#ifdef ES_TONEMAPc = vec4f(acesFilmic(c.rgb), c.a);#endifdiff --git a/src/esengine/renderer/frame/FrameConstants.hpp b/src/esengine/renderer/frame/FrameConstants.hppindex e515fb26b..75990e347 100644--- a/src/esengine/renderer/frame/FrameConstants.hpp+++ b/src/esengine/renderer/frame/FrameConstants.hpp@@ -85,7 +85,7 @@ inline constexpr const char* FRAME_CONSTANTS_BLOCK = "FrameConstants";/*** @brief CPU mirror of the injected TimeConstants block (std140).- * @details u_time = (elapsed s, delta s, 0, 0); u_viewport = (w, h, 1/w, 1/h) of the+ * @details u_time = (elapsed s, delta s, view exposure EV, 0); u_viewport = (w, h, 1/w, 1/h) of the* canvas in pixels. Engine-owned: ShaderParser injects the block into every* assembled stage — shaders never declare it.*/diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex 701dc976e..2a37b89cd 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp@@ -21,6 +21,7 @@#include "../../resource/ShaderParser.hpp"#include "../../core/Log.hpp"#include <algorithm>+#include <cmath>#include <cstring>#include "../rhi/GfxEnums.hpp"@@ -85,6 +86,11 @@ resource::ShaderHandle PostProcessPipeline::compileBlit(const std::vector<std::sresourceManager_.preferredShaderLanguage());}+void PostProcessPipeline::setViewExposure(f32 ev) {+ view_exposure_ = std::isfinite(ev) ? std::clamp(ev, -10.0f, 10.0f) : 0.0f;+ context_.setViewExposure(view_exposure_);+}+/*** 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.diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hppindex 3ddae63af..311e38d37 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp@@ -220,6 +220,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+ || view_exposure_ != 0.0f|| presentScales() || present_required_);}@@ -306,6 +307,9 @@ public:* than a pass of its own.*/void setOutputTransform(OutputTransform transform) { output_transform_ = transform; }+ /// 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);OutputTransform outputTransform() const { return output_transform_; }/**@@ -436,6 +440,7 @@ private:u32 scene_samples_ = 1;void applySampleRequest();OutputTransform output_transform_ = OutputTransform::None;+ f32 view_exposure_ = 0.0f;/// The graph resource the scene is drawn into, live between begin() and end().rg::ResourceId sceneResource_ = rg::kNoResource;TextureHandle sceneTexture_ = TextureHandle::Invalid;diff --git a/src/esengine/renderer/frame/RenderContext.cpp b/src/esengine/renderer/frame/RenderContext.cppindex 1737ec2bd..c18d66d7b 100644--- a/src/esengine/renderer/frame/RenderContext.cpp+++ b/src/esengine/renderer/frame/RenderContext.cpp@@ -207,7 +207,7 @@ void RenderContext::setFrameTime(f32 elapsedSec, u32 viewportW, u32 viewportH) {const f32 w = static_cast<f32>(viewportW);const f32 h = static_cast<f32>(viewportH);TimeConstants time{- glm::vec4(elapsedSec, dt, 0.0f, 0.0f),+ glm::vec4(elapsedSec, dt, viewExposure_, 0.0f),glm::vec4(w, h, w > 0.0f ? 1.0f / w : 0.0f, h > 0.0f ? 1.0f / h : 0.0f),};device_.updateBuffer(timeUbo_, 0, &time, sizeof(TimeConstants));diff --git a/src/esengine/renderer/frame/RenderContext.hpp b/src/esengine/renderer/frame/RenderContext.hppindex c748e3f35..8db40e8d1 100644--- a/src/esengine/renderer/frame/RenderContext.hpp+++ b/src/esengine/renderer/frame/RenderContext.hpp@@ -174,6 +174,14 @@ public:/** @brief Uploads the frame clock + canvas size into the injected TimeConstants UBO. */void setFrameTime(f32 elapsedSec, u32 viewportW, u32 viewportH);+ /**+ * @brief The editor view's exposure, in stops, carried to the output blit in+ * u_time.z. VIEW state: zero (the default, and every packaged build) is+ * exp2(0) = 1, an exact no-op.+ */+ void setViewExposure(f32 ev) { viewExposure_ = ev; }+ f32 viewExposure() const { return viewExposure_; }+/*** @brief The engine-side material registry (handle -> resolved render state).* @details Written by the SDK material binding (defineMaterial) and read by the render@@ -241,6 +249,7 @@ public:private:f32 lastElapsed_ = 0.0f;+ f32 viewExposure_ = 0.0f;MaterialStore materials_;LightStore lights_;ProbeStore probes_;diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex e83dc9186..a1f4237d4 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -1236,6 +1236,12 @@ void RenderFrame::collectLights(ecs::Registry& registry) {environment_texture_id_ = 0;sky_texture_id_ = 0;draw_sky_ = false;+ scene_sky_available_ = false;++ if (view_lighting_.studio) {+ collectStudioLights(registry);+ return;+ }// The frame's environment is decided before any light is: a directional light// following its sun needs it, and whether one does decides which irradiance@@ -1417,6 +1423,82 @@ void RenderFrame::collectLights(ecs::Registry& registry) {collectShape2D(registry);}+/// The studio rig. A sky that is light from above and less from below, so a surface+/// reads by its facing even before a light touches it; the radiance is a + b*y, whose+/// cosine-convolved nine coefficients (already over pi, like an imported environment's)+/// are a/Y00 for the constant term and (2/3)*b/Y1 for the y one.+static void neutralSkyIrradiance(std::array<glm::vec3, 9>& sh) {+ constexpr f32 a = 0.45f;+ constexpr f32 b = 0.15f;+ sh.fill(glm::vec3(0.0f));+ sh[0] = glm::vec3(a / 0.282095f);+ sh[1] = glm::vec3((2.0f / 3.0f) * b / 0.488603f);+}++void RenderFrame::collectStudioLights(ecs::Registry& registry) {+ LightStore& lights = context_.lights();+ const ViewLighting& view = view_lighting_;++ // The scene's own environment, found by the same rule the scene frame uses, only+ // to be LOOKED AT: it never lights anything here.+ auto lightView = registry.activeView<ecs::Light>();+ for (auto entity : lightView) {+ const auto& light = lightView.get(entity);+ if (!light.enabled || light.intensity <= 0.0f) continue;+ if (static_cast<ecs::LightType>(light.type) != ecs::LightType::Ambient) continue;+ if (!light.environment.isValid()) continue;+ const Environment* environment = resource_manager_.getEnvironment(light.environment);+ if (!environment) continue;+ u32 textureId = 0;+ if (environment->hasSpecular()) {+ if (Texture* atlas = resource_manager_.getTexture(environment->specular)) {+ textureId = atlas->getId();+ }+ }+ u32 panorama = 0;+ if (environment->sky.isValid()) {+ if (Texture* sky = resource_manager_.getTexture(environment->sky)) panorama = sky->getId();+ }+ scene_sky_available_ = textureId != 0 || panorama != 0;+ if (view.showSky && scene_sky_available_) {+ environment_texture_id_ = textureId;+ sky_texture_id_ = panorama;+ draw_sky_ = true;+ }+ break;+ }++ std::array<glm::vec3, 9> sh;+ neutralSkyIrradiance(sh);+ // params.x = 0: no specular atlas, so the sky is a diffuse term only.+ lights.setEnvironment(sh.data(), glm::vec4(0.0f, 1.0f, 0.0f, 0.0f),+ glm::vec3(std::max(view.skyIntensity, 0.0f)), 0.0f);++ auto rig = [&](f32 azimuthDeg, f32 elevationDeg, f32 intensity) {+ if (intensity <= 0.0f) return;+ const f32 az = glm::radians(azimuthDeg + view.rotation);+ const f32 el = glm::radians(elevationDeg);+ // Toward the light; a directional light's aim is the way it travels.+ const glm::vec3 toLight(std::sin(az) * std::cos(el), std::sin(el), std::cos(az) * std::cos(el));+ const glm::vec3 aim = -toLight;+ GpuLight gpu;+ gpu.color = glm::vec4(1.0f, 1.0f, 1.0f, intensity);+ gpu.posDir = glm::vec4(aim.x, aim.y, 1.0f, aim.z);+ lights.addLight(gpu);+ ++light_cap_.accepted;+ };+ light_cap_.limit = MAX_LIGHTS;+ // Key from the upper left of a viewer standing on +z; the fill low on the far side.+ rig(-35.0f, 40.0f, view.keyIntensity);+ rig(145.0f, 15.0f, view.fillIntensity);+ light_cap_.requested = light_cap_.accepted;++ // Last, as in the scene path: the masks are a question about the array just filled,+ // and with none of the scene's lights in it they come back empty rather than stale.+ collectShadow2D(registry);+ collectShape2D(registry);+}+bool RenderFrame::collectEnvironment(const ecs::Light& light, const glm::vec3& scale,bool withoutSun) {if (!light.environment.isValid()) return false;diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 5b33b2dff..77e2b0cec 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -335,6 +335,33 @@ public:*/const LightCapReport& lightCap() const { return light_cap_; }+ /**+ * @brief The editor view's own lighting, in place of the scene's.+ *+ * @details VIEW state, not scene state: nothing here is a component, nothing is+ * saved, and a host that never calls the setter (every packaged build)+ * lights the scene by its own lights exactly as before. In studio mode+ * the frame ignores the scene's lights and lights with a neutral sky,+ * a key and a fill, so a model the scene left dark can be read. The+ * scene's environment may still be drawn as the BACKGROUND (`showSky`):+ * seeing the sky and being lit by it are separate questions.+ */+ struct ViewLighting {+ bool studio = false;+ /// Degrees about +Y that the key and fill turn together.+ f32 rotation = 0.0f;+ f32 keyIntensity = 0.8f;+ f32 fillIntensity = 0.3f;+ /// Scales the neutral sky's light; the scene's own Ambient is not consulted.+ f32 skyIntensity = 1.0f;+ /// Draw the scene's environment as the background while studio-lit.+ bool showSky = false;+ };+ void setViewLighting(const ViewLighting& lighting) { view_lighting_ = lighting; }+ const ViewLighting& viewLighting() const { return view_lighting_; }+ /// Whether the frame found a scene environment it could draw as the background.+ bool sceneSkyAvailable() const { return scene_sky_available_; }+/*** @brief Switch the frame to linear-light rendering (project colorSpace).* @details Sets the global ES_LINEAR shader input, linearizes CPU-side@@ -604,6 +631,8 @@ private:/// (point/directional into the light array, ambient summed). Run each frame in collectAll;/// flush() uploads + binds the result so Lit material shaders read it.void collectLights(ecs::Registry& registry);+ /// collectLights' studio branch: the view's neutral light in place of the scene's.+ void collectStudioLights(ecs::Registry& registry);/** @brief Gathers the frame's LightProbeVolume components into the ProbeStore. */void collectProbes(ecs::Registry& registry);@@ -882,6 +911,8 @@ private:f32 shadow_distance_ = 0.0f;ShadowPlanReport shadow_plan_;LightCapReport light_cap_;+ ViewLighting view_lighting_;+ bool scene_sky_available_ = false;/// The map's colour texture, handed to every mesh that receives it. 0 = none this frame.u32 shadow_texture_id_ = 0;/// The frame environment's reflection atlas, on the same terms. 0 = none this frame.diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hppindex e8b228226..b381bd9d9 100644--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp@@ -251,6 +251,9 @@ out vec4 fragColor;void main() {vec4 c = texture(u_texture, v_texCoord);+++ c = vec4(c.rgb * exp2(u_time.z), c.a);#ifdef ES_TONEMAP@@ -270,6 +273,7 @@ void main() {#pragma fragment wgsl@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {var c = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);+ c = vec4f(c.rgb * exp2(tc.u_time.z), c.a);#ifdef ES_TONEMAPc = vec4f(acesFilmic(c.rgb), c.a);#endifdiff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cppindex 164bbd45a..982b5bbd6 100644--- a/src/esengine/resource/ShaderParser.cpp+++ b/src/esengine/resource/ShaderParser.cpp@@ -1793,7 +1793,7 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& pheaderLines += countNewlines(kFrameHeader);// Engine-owned frame block, injected into every stage (identical in both, so the- // program links). u_time = (elapsed s, delta s, 0, 0); u_viewport = canvas+ // program links). u_time = (elapsed s, delta s, view exposure EV, 0); u_viewport = canvas// (w, h, 1/w, 1/h) in pixels; binding 3 (Shader::compile).static const char* kTimeHeader ="layout(std140) uniform TimeConstants { highp vec4 u_time; highp vec4 u_viewport; };\n";diff --git a/tools/assetMetaTable.js b/tools/assetMetaTable.jsindex d61828066..617f297d1 100644--- a/tools/assetMetaTable.js+++ b/tools/assetMetaTable.js@@ -72,6 +72,7 @@ export const EXT_TO_TYPE = Object.freeze({// images instead of holding one — the same type, because it is imported the same// way and answers to the same settings.'.hdr': 'panorama',+ '.exr': 'panorama','.escube': 'panorama',// And for 2D art: a layered document produces one image per layer plus the// prefab that stacks them, and those are what a scene references.diff --git a/tools/check-render-scenes.mjs b/tools/check-render-scenes.mjsindex eaa6442a7..b854734b4 100644--- a/tools/check-render-scenes.mjs+++ b/tools/check-render-scenes.mjs@@ -44,7 +44,7 @@ for (const s of SCENES) {const asserts = s.env.ESTELLA_VERIFY_EXPECT || s.env.ESTELLA_VERIFY_COUNT|| s.env.ESTELLA_VERIFY_DEVICE_LOSS === 'roundtrip'|| s.env.ESTELLA_VERIFY_SEAM- || s.env.ESTELLA_VERIFY_GRID || s.env.ESTELLA_VERIFY_PREVIEW+ || s.env.ESTELLA_VERIFY_GRID || s.env.ESTELLA_VERIFY_STUDIO || s.env.ESTELLA_VERIFY_PREVIEW|| s.env.ESTELLA_VERIFY_MESH_PREVIEW || s.env.ESTELLA_VERIFY_DEPTH_LAYERS|| s.env.ESTELLA_VERIFY_COUNTERS || s.env.ESTELLA_VERIFY_COUNTERS_MAX || s.env.ESTELLA_VERIFY_FRAME_DEBUG || s.env.ESTELLA_VERIFY_EDGE || s.env.ESTELLA_VERIFY_CUTOUT_EDGE || s.env.ESTELLA_VERIFY_MINIFIED || s.env.ESTELLA_VERIFY_TWINS|| s.env.ESTELLA_VERIFY_DRAW_CALLS || s.env.ESTELLA_VERIFY_NINE_SLICEdiff --git a/tools/render-host/host.ts b/tools/render-host/host.tsindex 4b799341c..b8c115666 100644--- a/tools/render-host/host.ts+++ b/tools/render-host/host.ts@@ -22,7 +22,7 @@ import {getComponent, DeviceStatus, getDeviceStatus, getDeviceLostReport, recoverDevice,getContextLossGuardInfo, decodeImagePixels, captureFramePixels, captureFrame, replayDraw, BatchBreak,RenderTexture, Camera, Sprite,- EditorView, EditorGrid, installEditorGrid, editorViewHalfHeight, setEditorViewHalfHeight,+ EditorViewLighting, EditorView, EditorGrid, installEditorGrid, editorViewHalfHeight, setEditorViewHalfHeight,ProfileRecorder, AnimatorController, Timeline, onDeviceRestored, Schedule, defineSystem,textureImportSettingsFrom,} from 'esengine';@@ -672,6 +672,18 @@ const api = {setEditorViewHalfHeight(view, seen);},+ /** The editor view's own lighting and exposure — view state, never part of the+ * scene. Pass nothing to return to the game's own settings. The eye the frame+ * is drawn through has to be the editor's, so this wakes it if it is asleep. */+ setViewLighting(spec?: Record<string, unknown>): void {+ if (!app) throw new Error('set_view_lighting before boot');+ const view = app.getResource(EditorView);+ if (!view.active) { seedEditorViewFromScene(); view.active = true; }+ const lighting = app.getResource(EditorViewLighting);+ if (!spec) { lighting.mode = 'scene'; lighting.exposure = 0; return; }+ Object.assign(lighting, spec);+ },+/** The reference grid. Enabling seeds and activates the eye it draws through,* because this host boots with that eye inactive. */setGrid(enabled: boolean, spacing?: number): void {diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjsindex bbdcf2856..515c43daf 100644--- a/tools/render-host/run.mjs+++ b/tools/render-host/run.mjs@@ -30,6 +30,7 @@* ESTELLA_VERIFY_ANIMATOR drive an animator to a point in time (JSON)* ESTELLA_VERIFY_PICK hit-test a viewport point, asserting the entity (JSON)* ESTELLA_VERIFY_ORBIT turn the editor eye before capture ("yaw,pitch" degrees)+ * ESTELLA_VERIFY_STUDIO the editor view's studio lighting and exposure (JSON: see the block)* ESTELLA_VERIFY_COUNTERS engine counters the drawn frame must report (JSON)* ESTELLA_VERIFY_COUNTERS_MAX counters the frame must stay UNDER — a budget (JSON)* ESTELLA_VERIFY_FRAME_DEBUG capture the frame and replay it (the frame debugger)@@ -215,14 +216,17 @@ function finish(result, server) {// A frame of one colour reads as a bare clear. Where one colour IS the answer, a// count of that colour is what proves something drew it.const uniformByDesign = Boolean(process.env.ESTELLA_VERIFY_UNIFORM) && result.count?.ok === true;- const renderedOk = (result.capture?.rendered ?? false) || uniformByDesign;+ // The studio gate's own last frame is the scene's, which for the scene with no light is+ // black on purpose; what proves a frame was drawn there is the studio frame it measured.+ const studioDrew = result.studio?.ok === true && (result.studio.S?.litShare ?? 0) > 0;+ const renderedOk = (result.capture?.rendered ?? false) || uniformByDesign || studioDrew;// A scene that could not load an asset it names draws a frame nobody declared, so// its pixels answer a different question — say which asset instead.const assetsOk = (result.missingAssets?.length ?? 0) === 0;const ok = result.ok && renderedOk && assetsOk && (result.expect?.ok ?? true) && (result.twins?.ok ?? true) && (result.count?.ok ?? true) &&(result.seam?.ok ?? true) && (result.nineSlice?.ok ?? true) &&(result.resize?.ok ?? true) && (result.preview?.ok ?? true) &&- (result.meshPreview?.ok ?? true) && (result.grid?.ok ?? true) &&+ (result.meshPreview?.ok ?? true) && (result.grid?.ok ?? true) && (result.studio?.ok ?? true) &&(result.draws?.ok ?? true) && (result.counters?.ok ?? true) && (result.frameDebug?.ok ?? true) && (result.edge?.ok ?? true) && (result.cutoutEdge?.ok ?? true) && (result.minified?.ok ?? true) &&(result.roundtrip?.ok ?? true) && deviceLossOk && meshOk && pickOk;const why = assetsOk ? '' : `: could not load ${result.missingAssets.join(', ')}`;@@ -1052,7 +1056,82 @@ app.whenReady().then(async () => {`);if (respaced != null) grid = { ...grid, respacedPixels: respaced, ok: grid.ok && respaced > 300 };}- finish({ ok: true, entityCount, missingAssets, drawCalls, draws, counters, frameDebug, edge, cutoutEdge, minified, profile, capture, expect, twins, nineSlice, count, seam, resize, preview, meshPreview, grid, deviceLoss, roundtrip, meshResident, meshAsset, meshMaterial, meshPrefab, setField, animator, pick, cameraTarget }, server);+ // ESTELLA_VERIFY_STUDIO = { studio?: {...lighting}, dark?, exposure?, scene? }: the editor+ // view's own lighting, the one thing that is NOT the scene. Four frames through the+ // same eye — scene A, studio S, scene A' (switched back), and A under exposure — and+ // the claims are about their relations:+ // dark: false -> S differs from A and the scene was already lit (the studio replaces it);+ // dark: true -> A is unreadable (almost no lit pixels) and S is readable: a lit share and+ // a spread of tones, because a flat blob is not a model;+ // A' == A byte for byte, whatever the studio did in between;+ // exposure: EV -> mean display luma of A under EV scales by 2^EV (gamma frame), and+ // resetting returns A exactly.+ let studio = null;+ if (process.env.ESTELLA_VERIFY_STUDIO) {+ const spec = JSON.parse(process.env.ESTELLA_VERIFY_STUDIO);+ const api = (call) => exec(`(async () => { const api = window.__estellaHeadless.api; ${call}; await api.step(2, 1 / 60); })()`);+ const stats = (name) => readFrame(`+ window.__studio = window.__studio || {};+ window.__studio[${JSON.stringify(name)}] = px.slice();+ const lum = (i) => 0.2126 * px[i] + 0.7152 * px[i + 1] + 0.0722 * px[i + 2];+ const dec = (c) => { c /= 255; return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4); };+ const l = []; let lit = 0, sum = 0, lin = 0;+ for (let i = 0; i < px.length; i += 4) { const v = lum(i); l.push(v); sum += v; if (v > 30) lit++; lin += 0.2126 * dec(px[i]) + 0.7152 * dec(px[i + 1]) + 0.0722 * dec(px[i + 2]); }+ const n = l.length;+ // The spread of tones among the pixels that carry any: a model reads by its shading.+ const on = l.filter((v) => v > 30).sort((a, b) => a - b);+ const spread = on.length ? on[Math.floor(on.length * 0.95)] - on[Math.floor(on.length * 0.05)] : 0;+ return { litShare: lit / n, mean: sum / n, meanLinear: lin / n, spread };+ `);+ const diff = (a, b) => readFrame(`+ const A = window.__studio[${JSON.stringify(a)}], B = window.__studio[${JSON.stringify(b)}];+ let max = 0, differing = 0;+ for (let i = 0; i < A.length; i++) { const d = Math.abs(A[i] - B[i]); if (d > max) max = d; if (d > 0) differing++; }+ return { max, differing };+ `);+ await api('api.setViewLighting()');+ const A = await stats('A');+ let S = null, back = null, dStudio = null;+ if (spec.studio) {+ await api(`api.setViewLighting(${JSON.stringify({ mode: 'studio', ...spec.studio })})`);+ S = await stats('S');+ dStudio = await diff('A', 'S');+ await api('api.setViewLighting()');+ await stats('A2');+ back = await diff('A', 'A2');+ }+ // Seeing the sky and being lit by it are separate: showSky draws the scene's environment+ // behind the studio-lit model ('adds'), and a scene with none has nothing to draw ('noop').+ let sky = null;+ if (spec.sky) {+ await api(`api.setViewLighting(${JSON.stringify({ mode: 'studio', ...spec.studio, showSky: true })})`);+ await stats('SS');+ const d = await diff('S', 'SS');+ await api('api.setViewLighting()');+ await stats('A4');+ const reset = await diff('A', 'A4');+ sky = { differing: d.differing, resetMax: reset.max,+ ok: reset.max === 0 && (spec.sky === 'adds' ? d.differing > 2000 : d.differing === 0) };+ }+ let exp = null;+ if (spec.exposure !== undefined) {+ await api(`api.setViewLighting(${JSON.stringify({ mode: 'scene', exposure: spec.exposure })})`);+ const E = await stats('E');+ await api('api.setViewLighting()');+ await stats('A3');+ const reset = await diff('A', 'A3');+ const want = Math.pow(2, spec.exposure);+ // In a linear frame the exposure is a scale of radiance, so it is measured there.+ const ratio = spec.linear ? E.meanLinear / A.meanLinear : E.mean / A.mean;+ exp = { ev: spec.exposure, ratio, want, resetMax: reset.max,+ ok: Math.abs(ratio - want) <= (spec.tol ?? 0.08) * want && reset.max === 0 };+ }+ const darkOk = spec.dark === undefined ? true+ : spec.dark ? (A.litShare < 0.02 && S && S.litShare > 0.08 && S.spread > 40)+ : (S && dStudio.differing > 200);+ studio = { A, S, dStudio, back, sky, exp, ok: Boolean(darkOk) && (!spec.studio || back.max === 0) && (!sky || sky.ok) && (!exp || exp.ok) };+ }+ finish({ ok: true, studio, entityCount, missingAssets, drawCalls, draws, counters, frameDebug, edge, cutoutEdge, minified, profile, capture, expect, twins, nineSlice, count, seam, resize, preview, meshPreview, grid, deviceLoss, roundtrip, meshResident, meshAsset, meshMaterial, meshPrefab, setField, animator, pick, cameraTarget }, server);} catch (e) {finish({ ok: false, error: String((e && e.stack) || e) }, server);}diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex e1293c90c..2ab8e1800 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -83,6 +83,14 @@ export const SCENES = [// horizon is. A plane turned to meet the eye lights the frame evenly and passes// the coverage check, so "grazing" is what tells the two apart.{ id: "editor-grid-grazing", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-instanced.esscene", ESTELLA_VERIFY_GRID: "64", ESTELLA_VERIFY_GRID_EXPECT: "grazing", ESTELLA_VERIFY_PERSPECTIVE: "1", ESTELLA_VERIFY_ORBIT: "0,4", ESTELLA_VERIFY_STEPS: "3" } },+ // The editor view's studio preview: a view-only light and exposure. The scene with NO light is dark+ // and the studio makes the model readable; a scene lit by its own light or an environment is+ // replaced by it; and in every case switching back is the scene's own frame to the byte.+ { id: "studio-preview-nolight", tier: "pr", webgpu: true, env: {"ESTELLA_VERIFY_SCENE": "/scenes/studio-preview-nolight.esscene", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "3", "ESTELLA_VERIFY_STUDIO": "{\"studio\":{},\"dark\":true,\"sky\":\"noop\"}"} },+ { id: "studio-preview-sun", tier: "pr", webgpu: true, env: {"ESTELLA_VERIFY_SCENE": "/scenes/mesh-builtin.esscene", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "3", "ESTELLA_VERIFY_STUDIO": "{\"studio\":{},\"dark\":false}"} },+ { id: "studio-preview-hdr", tier: "pr", webgpu: true, env: {"ESTELLA_VERIFY_SCENE": "/scenes/studio-preview-hdr.esscene", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "3", "ESTELLA_VERIFY_PERSPECTIVE": "1", "ESTELLA_VERIFY_ORBIT": "0,0", "ESTELLA_VERIFY_STUDIO": "{\"studio\":{},\"dark\":false,\"sky\":\"adds\"}"} },+ { id: "studio-exposure", tier: "pr", webgpu: true, env: {"ESTELLA_VERIFY_SCENE": "/scenes/mesh-builtin.esscene", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "3", "ESTELLA_VERIFY_STUDIO": "{\"exposure\":-1}"} },+ { id: "studio-exposure-linear", tier: "pr", webgpu: true, env: {"ESTELLA_VERIFY_COLORSPACE": "linear", "ESTELLA_VERIFY_SCENE": "/scenes/mesh-builtin.esscene", "ESTELLA_VERIFY_W": "256", "ESTELLA_VERIFY_H": "256", "ESTELLA_VERIFY_STEPS": "3", "ESTELLA_VERIFY_STUDIO": "{\"exposure\":-1,\"linear\":true}"} },{ id: "frame-debugger-2d", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/sprite-rendering.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/sprite-rendering.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_FRAME_DEBUG: "1" } },{ id: "frame-debugger-3d", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/ssao.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_FRAME_DEBUG: "1" } },{ id: "frame-debugger-split", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/camera-split.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/camera-split.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_FRAME_DEBUG: "1" } },