Skip to content

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

feat(environment): read OpenEXR panoramas, and low-dynamic-range pictures as a source

yhh5df7398d2b94
diff --git a/desktop b/desktop
index 670550635..adf3cf32e 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 670550635a47a567dbdf8ae202aeb2a9f9283ccf
+Subproject commit adf3cf32e6ff92c050b214a0f5ff2215cb138b3f
diff --git a/fixtures/scenes/studio-preview-hdr.esscene b/fixtures/scenes/studio-preview-hdr.esscene
new file mode 100644
index 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.esscene
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.md
new file mode 100644
index 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.exr
new file mode 100644
index 000000000..59764b729
Binary files /dev/null and b/pipeline/tests/fixtures/exr/big_pxr24_32.exr differ
diff --git a/pipeline/tests/fixtures/exr/big_rle_32.exr b/pipeline/tests/fixtures/exr/big_rle_32.exr
new file mode 100644
index 000000000..67ca909db
Binary files /dev/null and b/pipeline/tests/fixtures/exr/big_rle_32.exr differ
diff --git a/pipeline/tests/fixtures/exr/big_zip_32.exr b/pipeline/tests/fixtures/exr/big_zip_32.exr
new file mode 100644
index 000000000..08c8b19ae
Binary files /dev/null and b/pipeline/tests/fixtures/exr/big_zip_32.exr differ
diff --git a/pipeline/tests/fixtures/exr/big_zips_16.exr b/pipeline/tests/fixtures/exr/big_zips_16.exr
new file mode 100644
index 000000000..24d42154a
Binary files /dev/null and b/pipeline/tests/fixtures/exr/big_zips_16.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_dwaa_16.exr b/pipeline/tests/fixtures/exr/ref_dwaa_16.exr
new file mode 100644
index 000000000..2c7a843e7
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_dwaa_16.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_dwaa_32.exr b/pipeline/tests/fixtures/exr/ref_dwaa_32.exr
new file mode 100644
index 000000000..0b22891b6
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_dwaa_32.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_none_16.exr b/pipeline/tests/fixtures/exr/ref_none_16.exr
new file mode 100644
index 000000000..80ae4739c
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_none_16.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_none_32.exr b/pipeline/tests/fixtures/exr/ref_none_32.exr
new file mode 100644
index 000000000..b0338921c
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_none_32.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_piz_16.exr b/pipeline/tests/fixtures/exr/ref_piz_16.exr
new file mode 100644
index 000000000..9e3ae17f9
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_piz_16.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_piz_32.exr b/pipeline/tests/fixtures/exr/ref_piz_32.exr
new file mode 100644
index 000000000..be501489c
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_piz_32.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_pxr24_16.exr b/pipeline/tests/fixtures/exr/ref_pxr24_16.exr
new file mode 100644
index 000000000..7189f0cab
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_pxr24_16.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_pxr24_32.exr b/pipeline/tests/fixtures/exr/ref_pxr24_32.exr
new file mode 100644
index 000000000..e47277044
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_pxr24_32.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_rle_16.exr b/pipeline/tests/fixtures/exr/ref_rle_16.exr
new file mode 100644
index 000000000..1ea8a2a10
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_rle_16.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_rle_32.exr b/pipeline/tests/fixtures/exr/ref_rle_32.exr
new file mode 100644
index 000000000..9162e536d
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_rle_32.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_zip_16.exr b/pipeline/tests/fixtures/exr/ref_zip_16.exr
new file mode 100644
index 000000000..e88dcc9d1
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_zip_16.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_zip_32.exr b/pipeline/tests/fixtures/exr/ref_zip_32.exr
new file mode 100644
index 000000000..ea42f594e
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_zip_32.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_zips_16.exr b/pipeline/tests/fixtures/exr/ref_zips_16.exr
new file mode 100644
index 000000000..7eee61b2a
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_zips_16.exr differ
diff --git a/pipeline/tests/fixtures/exr/ref_zips_32.exr b/pipeline/tests/fixtures/exr/ref_zips_32.exr
new file mode 100644
index 000000000..f669de086
Binary files /dev/null and b/pipeline/tests/fixtures/exr/ref_zips_32.exr differ
diff --git a/pipeline/tests/ldr-panorama.test.ts b/pipeline/tests/ldr-panorama.test.ts
new file mode 100644
index 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.md
index 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 = 1
Stretch = 4
```
+## AmbientSkip — type @experimental
+```
+'hidden' | 'disabled' | 'no-intensity'
+```
+
## Ambiguity — interface @experimental
```
a: string
@@ -2700,6 +2705,11 @@ EditorGridData
EditorViewData
```
+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental
+```
+EditorViewLightingData
+```
+
## DEFAULT_FACING_COSINE — const @experimental
```
0.2
@@ -3348,6 +3358,11 @@ tabIndex: number | undefined
world: 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: number
spacing: number
```
+## EditorLightingMode — type @experimental
+```
+'scene' | 'studio'
+```
+
## EditorView — const @experimental
```
ResourceDef<EditorViewData>
@@ -3445,6 +3465,22 @@ yaw: number
z: 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) | undefined
ySortLayers: 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>>) => void
unbindPostProcess: (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): CaptureSummary
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 = 1
Stretch = 4
```
+## AmbientSkip — type @experimental
+```
+'hidden' | 'disabled' | 'no-intensity'
+```
+
## Ambiguity — interface @experimental
```
a: string
@@ -2708,6 +2713,11 @@ EditorGridData
EditorViewData
```
+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental
+```
+EditorViewLightingData
+```
+
## DEFAULT_FACING_COSINE — const @experimental
```
0.2
@@ -3356,6 +3366,11 @@ tabIndex: number | undefined
world: 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: number
spacing: number
```
+## EditorLightingMode — type @experimental
+```
+'scene' | 'studio'
+```
+
## EditorView — const @experimental
```
ResourceDef<EditorViewData>
@@ -3453,6 +3473,22 @@ yaw: number
z: 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) | undefined
ySortLayers: 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>>) => void
unbindPostProcess: (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): CaptureSummary
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 = 1
Stretch = 4
```
+## AmbientSkip — type @experimental
+```
+'hidden' | 'disabled' | 'no-intensity'
+```
+
## Ambiguity — interface @experimental
```
a: string
@@ -2695,6 +2700,11 @@ EditorGridData
EditorViewData
```
+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental
+```
+EditorViewLightingData
+```
+
## DEFAULT_FACING_COSINE — const @experimental
```
0.2
@@ -3343,6 +3353,11 @@ tabIndex: number | undefined
world: 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: number
spacing: number
```
+## EditorLightingMode — type @experimental
+```
+'scene' | 'studio'
+```
+
## EditorView — const @experimental
```
ResourceDef<EditorViewData>
@@ -3440,6 +3460,22 @@ yaw: number
z: 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) | undefined
ySortLayers: 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>>) => void
unbindPostProcess: (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): CaptureSummary
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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 = 1
Stretch = 4
```
+## AmbientSkip — type @experimental
+```
+'hidden' | 'disabled' | 'no-intensity'
+```
+
## Ambiguity — interface @experimental
```
a: string
@@ -2695,6 +2700,11 @@ EditorGridData
EditorViewData
```
+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental
+```
+EditorViewLightingData
+```
+
## DEFAULT_FACING_COSINE — const @experimental
```
0.2
@@ -3343,6 +3353,11 @@ tabIndex: number | undefined
world: 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: number
spacing: number
```
+## EditorLightingMode — type @experimental
+```
+'scene' | 'studio'
+```
+
## EditorView — const @experimental
```
ResourceDef<EditorViewData>
@@ -3440,6 +3460,22 @@ yaw: number
z: 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) | undefined
ySortLayers: 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>>) => void
unbindPostProcess: (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): CaptureSummary
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 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: nu
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) | undefined
postprocess_shutdown: () => void
probe_volume_create: ((resX: number, resY: number, resZ: number, shPtr: number) => number) | undefined
probe_volume_release: ((volumeHandle: number) => void) | undefined
@@ -489,6 +490,7 @@ renderer_setShadowDistance: ((distance: number) => void) | undefined
renderer_setStage: (stage: number) => void
renderer_setTextureParams: (textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number) => void
renderer_setViewId: ((view: number) => void) | undefined
+renderer_setViewLighting: ((mode: number, rotationDegrees: number, keyIntensity: number, fillIntensity: number, skyIntensity: number, showSky: boolean) => void) | undefined
renderer_setViewport: (x: number, y: number, w: number, h: number) => void
renderer_setYSortLayers: ((mask: number) => void) | undefined
renderer_shadowStatus: ((entity: number, outPtr: number) => number) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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 = 1
Stretch = 4
```
+## AmbientSkip — type @experimental
+```
+'hidden' | 'disabled' | 'no-intensity'
+```
+
## Ambiguity — interface @experimental
```
a: string
@@ -2695,6 +2700,11 @@ EditorGridData
EditorViewData
```
+## DEFAULT_EDITOR_VIEW_LIGHTING — const @experimental
+```
+EditorViewLightingData
+```
+
## DEFAULT_FACING_COSINE — const @experimental
```
0.2
@@ -3343,6 +3353,11 @@ tabIndex: number | undefined
world: 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: number
spacing: number
```
+## EditorLightingMode — type @experimental
+```
+'scene' | 'studio'
+```
+
## EditorView — const @experimental
```
ResourceDef<EditorViewData>
@@ -3440,6 +3460,22 @@ yaw: number
z: 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) | undefined
ySortLayers: 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>>) => void
unbindPostProcess: (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): CaptureSummary
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.cpp
index 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.hpp
index 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; see
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 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.hpp
index 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.cpp
index 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.esshader
index 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_TONEMAP
c = vec4f(acesFilmic(c.rgb), c.a);
#endif
diff --git a/src/esengine/renderer/frame/FrameConstants.hpp b/src/esengine/renderer/frame/FrameConstants.hpp
index 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.cpp
index 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::s
resourceManager_.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.hpp
index 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.cpp
index 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.hpp
index 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.cpp
index 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.hpp
index 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.hpp
index 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_TONEMAP
c = vec4f(acesFilmic(c.rgb), c.a);
#endif
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 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& p
headerLines += 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.js
index 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.mjs
index 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_SLICE
diff --git a/tools/render-host/host.ts b/tools/render-host/host.ts
index 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.mjs
index 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.mjs
index 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" } },