A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file skyEnvironment.ts
* @brief The Sky Atmosphere as the scene's environment: the light the sky sends down, and what a surface sees of it.
*
* @details With Sky Atmosphere's **Light the Scene** on, the dome the effect draws is worked out here too, on the CPU, by the
* same expressions (single scattering through the air, the cloud slab marched against the same noise), as a small
* panorama of radiance. That panorama is made into an environment the way an imported `.hdr` is (nine irradiance
* coefficients and a prefiltered octahedral reflection, lightmap/environmentAtlas) and handed to the frame as its sky
* environment, which every Ambient light that names no environment of its own then lights with: its colour and
* intensity scale it, as they scale an imported one.
*
* The sun's disc is left out: the directional light the sky follows is the sun's direct light, and counting the disc
* in the environment as well would light the scene twice from it. A night sky's moon and stars are left out for
* the same kind of reason (they are points, and the nine coefficients cannot hold them); its glow is kept.
*
* A sky that changes (a sun that moves, a weather coming in, clouds drifting) is worked out again, at most once a
* second, and only when what it is made from has moved by more than can be seen in its light.
*/
import { getEffectDef } from './effects';
import type { BlendedEffect } from './volumeBlending';
import { projectIrradianceSH, prefilterOctahedral, type Panorama } from '../lightmap/environmentAtlas';
import { panoramaDirection } from '../lightmap/panorama';
import { createTextureFromPixels } from '../runtime/runtimeAssets';
import { getResourceManager } from '../wasm/resourceManager';
import { TextureContent } from '../wasm';
import type { ESEngineModule } from '../wasm';
import { withScratch } from '../wasm/wasmScratch';
import { log } from '../util/logger';
import { CUSTOM_SKY_HEIGHT, CUSTOM_SKY_WIDTH, decodeSkyCapture } from './customSky';
/** What the sky is made from: the effect's resolved parameters and the direction toward the sun. */
export interface SkyEnvironmentInput {
/** Toward the sun, unit. */
sun: [number, number, number];
params: (name: string) => number;
/** Whether the frame lights in linear space (the effect's small constant colours are authored sRGB). */
linear: boolean;
}
// The constants of the effect's own shader (sources/atmosphere.ts): kilometres, per kilometre.
const R_E = 6360;
const R_A = 6420;
const BETA_R = [0.0058, 0.0135, 0.0331] as const;
const BETA_M = 0.021;
const H_R = 8;
const H_M = 1.2;
const SUN_I = 22;
const fract = (x: number): number => x - Math.floor(x);
const mix = (a: number, b: number, t: number): number => a + (b - a) * t;
const clamp01 = (x: number): number => Math.min(Math.max(x, 0), 1);
const smoothstep = (a: number, b: number, x: number): number => {
const t = clamp01((x - a) / (b - a));
return t * t * (3 - 2 * t);
};
const toLinear = (c: number): number => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
function hash13(x: number, y: number, z: number): number {
let px = fract(x * 0.1031), py = fract(y * 0.1031), pz = fract(z * 0.1031);
const d = px * (pz + 31.32) + py * (py + 31.32) + pz * (px + 31.32);
px += d; py += d; pz += d;
return fract((px + py) * pz);
}
function vnoise(x: number, y: number, z: number): number {
const ix = Math.floor(x), iy = Math.floor(y), iz = Math.floor(z);
let fx = x - ix, fy = y - iy, fz = z - iz;
fx = fx * fx * (3 - 2 * fx); fy = fy * fy * (3 - 2 * fy); fz = fz * fz * (3 - 2 * fz);
const a = mix(hash13(ix, iy, iz), hash13(ix + 1, iy, iz), fx);
const b = mix(hash13(ix, iy + 1, iz), hash13(ix + 1, iy + 1, iz), fx);
const c = mix(hash13(ix, iy, iz + 1), hash13(ix + 1, iy, iz + 1), fx);
const d = mix(hash13(ix, iy + 1, iz + 1), hash13(ix + 1, iy + 1, iz + 1), fx);
return mix(mix(a, b, fy), mix(c, d, fy), fz);
}
/** Where a ray from o along d leaves the sphere of radius r about the planet's centre; -1 for a miss. */
function sphereExit(oy: number, dy: number, r: number): number {
// o = (0, oy, 0): b = oy * dy, |o|^2 = oy^2.
const b = oy * dy;
const disc = b * b - (oy * oy - r * r);
return disc < 0 ? -1 : -b + Math.sqrt(disc);
}
/** The air between p and the top of the atmosphere along d as (Rayleigh, Mie) optical depth, or null where the planet is in the way. */
function lightDepth(px: number, py: number, pz: number, dx: number, dy: number, dz: number): [number, number] | null {
const b = px * dx + py * dy + pz * dz;
const pp = px * px + py * py + pz * pz;
const discE = b * b - (pp - R_E * R_E);
if (discE >= 0) {
const s = Math.sqrt(discE);
if (-b - s > 0 && -b + s > 0) return null;
}
const discA = b * b - (pp - R_A * R_A);
const len = discA < 0 ? 0 : -b + Math.sqrt(discA);
const ds = len / 4;
let r = 0, m = 0;
for (let j = 0; j < 4; j++) {
const t = ds * (j + 0.5);
const qx = px + dx * t, qy = py + dy * t, qz = pz + dz * t;
const h = Math.hypot(qx, qy, qz) - R_E;
r += Math.exp(-h / H_R) * ds;
m += Math.exp(-h / H_M) * ds;
}
return [r, m];
}
/** The sky's radiance along dir by single scattering (the effect's `scatter`), and the sun's light where the eye is. */
function scatter(dir: readonly number[], sun: readonly number[], alt: number, haze: number,
out: Float64Array, sunTrans: Float64Array): void {
const oy = R_E + alt;
const len = sphereExit(oy, dir[1]!, R_A);
const N = 16;
const ds = len / N;
const mu = dir[0]! * sun[0]! + dir[1]! * sun[1]! + dir[2]! * sun[2]!;
const g = 0.76;
const phaseR = 3 / (16 * Math.PI) * (1 + mu * mu);
const phaseM = 3 / (8 * Math.PI) * ((1 - g * g) * (1 + mu * mu)) / ((2 + g * g) * (1 + g * g - 2 * g * mu) ** 1.5);
let odR = 0, odM = 0;
let rR = 0, rG = 0, rB = 0, mR = 0, mG = 0, mB = 0;
const kM = BETA_M * haze * 1.1;
for (let i = 0; i < N; i++) {
const t = ds * (i + 0.5);
const px = dir[0]! * t, py = oy + dir[1]! * t, pz = dir[2]! * t;
const h = Math.hypot(px, py, pz) - R_E;
const dR = Math.exp(-h / H_R) * ds, dM = Math.exp(-h / H_M) * ds;
odR += dR; odM += dM;
const ol = lightDepth(px, py, pz, sun[0]!, sun[1]!, sun[2]!);
if (!ol) continue;
const tr = odR + ol[0], tm = odM + ol[1];
const ar = Math.exp(-(BETA_R[0] * tr + kM * tm));
const ag = Math.exp(-(BETA_R[1] * tr + kM * tm));
const ab = Math.exp(-(BETA_R[2] * tr + kM * tm));
rR += ar * dR; rG += ag * dR; rB += ab * dR;
mR += ar * dM; mG += ag * dM; mB += ab * dM;
}
const st = lightDepth(0, oy, 0, sun[0]!, sun[1]!, sun[2]!);
for (let c = 0; c < 3; c++) {
sunTrans[c] = st ? Math.exp(-(BETA_R[c]! * st[0] + kM * st[1])) : 0;
}
const kMs = BETA_M * haze * phaseM;
out[0] = (rR * BETA_R[0] * phaseR + mR * kMs) * SUN_I;
out[1] = (rG * BETA_R[1] * phaseR + mG * kMs) * SUN_I;
out[2] = (rB * BETA_R[2] * phaseR + mB * kMs) * SUN_I;
}
interface CloudParams {
coverage: number; base: number; thick: number; alt: number; scale: number; softness: number; evolve: number;
silver: number; brightness: number; driftX: number; driftZ: number;
c2: { coverage: number; base: number; thick: number; scale: number; driftX: number; driftZ: number };
}
function cloudDensity(x: number, y: number, z: number, p: CloudParams, octaves: number): number {
const h = clamp01((y - p.base) / p.thick);
const shape = smoothstep(0, 0.14, h) * smoothstep(1, 0.55, h);
if (shape <= 0) return 0;
const k = 0.32 * p.scale;
const qx = x * k, qy = (y * 1.8 + p.evolve) * k, qz = z * k;
let n = vnoise(qx, qy, qz) * 0.58 + vnoise(qx * 2.13, qy * 2.13, qz * 2.13) * 0.28;
n += octaves > 2 ? vnoise(qx * 4.7, qy * 4.7, qz * 4.7) * 0.14 : 0.07;
let d = smoothstep(1 - p.coverage, 1 - p.coverage + p.softness, n) * shape;
if (octaves > 2 && d > 0 && d < 0.9) d = Math.max(d - (1 - d) * vnoise(qx * 11, qy * 11, qz * 11) * 0.55, 0);
return d;
}
function cloud2Density(x: number, y: number, z: number, p: CloudParams): number {
const c = p.c2;
const h = clamp01((y - c.base) / c.thick);
const shape = smoothstep(0, 0.3, h) * smoothstep(1, 0.5, h);
if (shape <= 0) return 0;
const k = 0.32 * c.scale;
const qx = x * k, qy = (y * 3 + p.evolve * 1.7) * k, qz = z * k;
const n = vnoise(qx, qy, qz) * 0.62 + vnoise(qx * 2.31, qy * 2.31, qz * 2.31) * 0.38;
return smoothstep(1 - c.coverage, 1 - c.coverage + 0.3, n) * shape;
}
function cloudPhase(cosS: number, silver: number): number {
const G = 0.86;
return 0.42 + 0.018 * silver * (1 - G * G) / (1 + G * G - 2 * G * cosS) ** 1.5;
}
/** The cloud slab along dir as colour * T + L (the effect's `cloudLayer`), with the march's jitter at its middle. */
function cloudLayer(dir: readonly number[], sun: readonly number[], dome: Float64Array, sunTrans: Float64Array,
nightGlow: readonly number[], overcast: number, p: CloudParams, L: Float64Array): number {
L[0] = 0; L[1] = 0; L[2] = 0;
let T = 1;
const fade = smoothstep(0.01, 0.14, dir[1]!);
const cosS = dir[0]! * sun[0]! + dir[1]! * sun[1]! + dir[2]! * sun[2]!;
const amb = [dome[0]! * 0.7 + nightGlow[0]!, dome[1]! * 0.7 + nightGlow[1]!, dome[2]! * 0.7 + nightGlow[2]!];
const sunL = [sunTrans[0]! * 1.2 * p.brightness, sunTrans[1]! * 1.2 * p.brightness, sunTrans[2]! * 1.2 * p.brightness];
if (p.coverage > 0.01 && dir[1]! > 0.01) {
const tb = Math.max(p.base - p.alt, 0) / dir[1]!;
const tt = Math.min((p.base + p.thick - p.alt) / dir[1]!, tb + p.thick * 6);
const STEPS = 16;
const ds = (tt - tb) / STEPS;
const sigma = 1.3 * (1 + overcast * 1.5);
const phase = cloudPhase(cosS, p.silver);
let trans = 1, lr = 0, lg = 0, lb = 0;
for (let i = 0; i < STEPS && trans >= 0.02; i++) {
const t = tb + (i + 0.5) * ds;
const x = dir[0]! * t + p.driftX, y = p.alt + dir[1]! * t, z = dir[2]! * t + p.driftZ;
const d = cloudDensity(x, y, z, p, 3);
if (d < 0.002) continue;
let tau = 0;
const reach = Math.max(p.thick, 0.5) * 0.14;
for (let k = 1; k <= 3; k++) {
const along = reach * k * k;
tau += cloudDensity(x + sun[0]! * along, y + sun[1]! * along, z + sun[2]! * along, p, 2) * reach * (2 * k - 1) * sigma;
}
const energy = (Math.exp(-tau * 1.1) + 0.25 * Math.exp(-tau * 0.25)) * mix(1, 1 - Math.exp(-(d * sigma * ds + tau) * 3), 0.5);
const tr = Math.exp(-d * sigma * ds);
const w = trans * (1 - tr);
lr += w * (sunL[0]! * energy * phase * 2 + amb[0]!);
lg += w * (sunL[1]! * energy * phase * 2 + amb[1]!);
lb += w * (sunL[2]! * energy * phase * 2 + amb[2]!);
trans *= tr;
}
T = mix(1, trans, fade);
L[0] = lr * fade; L[1] = lg * fade; L[2] = lb * fade;
}
const c2 = p.c2;
if (c2.coverage > 0.01 && dir[1]! > 0.01) {
const tb = Math.max(c2.base - p.alt, 0) / dir[1]!;
const tt = Math.max(c2.base + c2.thick - p.alt, 0) / dir[1]!;
const STEPS = 6;
const ds = (tt - tb) / STEPS;
const sigma = 1.3 * (1 + overcast);
const phase = cloudPhase(cosS, p.silver);
let trans = 1, lr = 0, lg = 0, lb = 0;
for (let i = 0; i < STEPS; i++) {
const t = tb + (i + 0.5) * ds;
const x = dir[0]! * t + p.driftX + c2.driftX, y = p.alt + dir[1]! * t, z = dir[2]! * t + p.driftZ + c2.driftZ;
const d = cloud2Density(x, y, z, p);
if (d < 0.002) continue;
const half = c2.thick * 0.5;
const tau = cloud2Density(x + sun[0]! * half, y + sun[1]! * half, z + sun[2]! * half, p) * half * sigma;
const e = Math.exp(-tau) * phase * 2;
const tr = Math.exp(-d * sigma * ds);
const w = trans * (1 - tr);
lr += w * (sunL[0]! * e + amb[0]!); lg += w * (sunL[1]! * e + amb[1]!); lb += w * (sunL[2]! * e + amb[2]!);
trans *= tr;
}
trans = mix(1, trans, fade);
lr *= fade; lg *= fade; lb *= fade;
if (c2.base >= p.base) { L[0] += T * lr; L[1] += T * lg; L[2] += T * lb; }
else { L[0] = lr + trans * L[0]!; L[1] = lg + trans * L[1]!; L[2] = lb + trans * L[2]!; }
T *= trans;
}
return T;
}
/**
* The sky the effect draws along `dir`, without the sun's disc, the moon or the stars: the dome, the glow a night keeps, the
* clouds over it and the grey an overcast lends it. In the frame's units, before exposure.
*/
export function skyRadianceAt(dir: readonly number[], input: SkyEnvironmentInput, out: Float64Array): void {
skyRadianceAndClouds(dir, input, out);
}
/** {@link skyRadianceAt}, answering also how much of the light behind the clouds along dir comes through them (1 = clear). */
function skyRadianceAndClouds(dir: readonly number[], input: SkyEnvironmentInput, out: Float64Array): number {
let through = 1;
const P = input.params;
const sun = input.sun;
const overcast = clamp01(P('u_overcast'));
const haze = P('u_haze') * (1 + overcast * 2);
const lin = (c: number): number => (input.linear ? toLinear(c) : c);
const dy = Math.max(dir[1]!, 0.015);
const n = Math.hypot(dir[0]!, dy, dir[2]!);
const sdir = [dir[0]! / n, dy / n, dir[2]! / n];
const dome = new Float64Array(3);
const sunTrans = new Float64Array(3);
scatter(sdir, sun, P('u_altitude'), haze, dome, sunTrans);
const below = 1 - 0.75 * smoothstep(0, -0.3, dir[1]!);
const k = 0.55 * P('u_intensity') * below;
dome[0]! *= k; dome[1]! *= k; dome[2]! *= k;
const night = 1 - smoothstep(-0.1, 0.12, sun[1]!);
const up = (1 - Math.max(dir[1]!, 0)) ** 3;
const glow = [mix(lin(0.003), lin(0.016), up) * night, mix(lin(0.006), lin(0.024), up) * night, mix(lin(0.02), lin(0.06), up) * night];
for (let c = 0; c < 3; c++) dome[c]! += glow[c]!;
out[0] = dome[0]!; out[1] = dome[1]!; out[2] = dome[2]!;
const coverage = Math.max(P('u_clouds'), overcast * 0.95);
if ((coverage > 0.01 || P('u_cloud2Coverage') > 0.01) && dir[1]! > 0.01) {
const cloudNight = [lin(0.55) * 0.015 * night, lin(0.65) * 0.015 * night, lin(0.9) * 0.015 * night];
const L = new Float64Array(3);
const T = cloudLayer(dir, sun, dome, sunTrans, cloudNight, overcast, {
coverage, base: P('u_cloudBase'), thick: P('u_cloudThickness'), alt: P('u_altitude'), scale: P('u_cloudScale'),
softness: P('u_cloudSoftness'), evolve: P('u_cloudEvolve'), silver: P('u_cloudSilver'), brightness: P('u_cloudBrightness'),
driftX: P('u_cloudDriftX'), driftZ: P('u_cloudDriftZ'),
c2: { coverage: P('u_cloud2Coverage'), base: P('u_cloud2Base'), thick: P('u_cloud2Thickness'), scale: P('u_cloud2Scale'),
driftX: P('u_cloud2DriftX') - P('u_cloudDriftX'), driftZ: P('u_cloud2DriftZ') - P('u_cloudDriftZ') },
}, L);
for (let c = 0; c < 3; c++) out[c] = out[c]! * T + L[c]!;
through = T;
}
const luma = 0.2126 * out[0]! + 0.7152 * out[1]! + 0.0722 * out[2]!;
for (let c = 0; c < 3; c++) out[c] = mix(out[c]!, luma, overcast * 0.5);
return through;
}
/**
* What lights the ground under this sky, as irradiance over pi (the unit an environment's coefficients and a light's colour
* times intensity are in): the sky's own sun — the brightness its scattering is computed from, through the air at its
* elevation and through the clouds as much as they let through on average — and the dome above, `skyAbove`.
*/
function groundIrradiance(input: SkyEnvironmentInput, skyAbove: readonly number[], cloudsThrough: number, out: Float64Array): void {
const P = input.params;
const sun = input.sun;
const dome = new Float64Array(3);
const sunTrans = new Float64Array(3);
scatter([0, 1, 0], sun, P('u_altitude'), P('u_haze') * (1 + clamp01(P('u_overcast')) * 2), dome, sunTrans);
// The sun the dome was scattered from, scaled as the dome is (0.55 x Brightness), over pi, onto level ground.
const sunOverPi = SUN_I * 0.55 * P('u_intensity') / Math.PI * Math.max(sun[1]!, 0) * cloudsThrough;
for (let c = 0; c < 3; c++) out[c] = sunOverPi * sunTrans[c]! + skyAbove[c]!;
}
/** The sky as an equirectangular panorama of radiance, `width` by `width / 2` (panoramaDirection's mapping). */
export function skyPanorama(input: SkyEnvironmentInput, width = SKY_PANORAMA_WIDTH): Panorama {
const height = Math.max(2, width >> 1);
const rgb = new Float32Array(width * height * 3);
const c = new Float64Array(3);
// Above the horizon: the sky, and as it goes, what it gives level ground (cosine-weighted, over pi) and how much the
// clouds let through on average (by solid angle, away from the horizon where the slab is thinnest).
const skyAbove = [0, 0, 0];
let through = 0, throughWeight = 0;
const cellAngle = (2 * Math.PI / width) * (Math.PI / height);
for (let y = 0; y < height; y++) {
for (let x = 0; x < width; x++) {
const dir = panoramaDirection((x + 0.5) / width, (y + 0.5) / height);
if (dir[1]! < 0) continue;
const t = skyRadianceAndClouds(dir, input, c);
const o = (y * width + x) * 3;
rgb[o] = c[0]!; rgb[o + 1] = c[1]!; rgb[o + 2] = c[2]!;
const solid = cellAngle * Math.sqrt(Math.max(1 - dir[1]! * dir[1]!, 0));
for (let k = 0; k < 3; k++) skyAbove[k]! += c[k]! * dir[1]! * solid / Math.PI;
if (dir[1]! > 0.1) { through += t * solid; throughWeight += solid; }
}
}
// Below it: the ground, lit by that sun and that sky (Ground Albedo of it given back, as a matte surface does), fading
// into the horizon's own colour toward the horizon, as distant ground does through the haze between.
const ground = new Float64Array(3);
groundIrradiance(input, skyAbove, throughWeight > 0 ? through / throughWeight : 1, ground);
const albedo = clamp01(input.params('u_groundAlbedo'));
const horizon = new Float64Array(3);
for (let y = 0; y < height; y++) {
for (let x = 0; x < width; x++) {
const dir = panoramaDirection((x + 0.5) / width, (y + 0.5) / height);
if (dir[1]! >= 0) continue;
const flat = Math.hypot(dir[0]!, dir[2]!) || 1;
skyRadianceAt([dir[0]! / flat, 0, dir[2]! / flat], input, horizon);
const t = smoothstep(0, -0.2, dir[1]!);
const o = (y * width + x) * 3;
for (let k = 0; k < 3; k++) rgb[o + k] = mix(horizon[k]!, albedo * ground[k]!, t);
}
}
return { width, height, rgb };
}
/** Small: the light a sky sends is smooth, and its reflection on anything but a mirror is a blur of it. */
export const SKY_PANORAMA_WIDTH = 64;
export const SKY_FACE_SIZE = 32;
export const SKY_MIP_COUNT = 3;
export const SKY_MAX_RANGE = 8;
/** The parameters of a resolved Sky Atmosphere, its own default where the volume says nothing. */
export function skyParamsOf(effect: BlendedEffect): (name: string) => number {
const def = getEffectDef('skyAtmosphere');
return (name) => effect.uniforms.get(name) ?? def?.uniforms.find((u) => u.name === name)?.defaultValue ?? 0;
}
/** Toward the sun as the effect places it: the first directional light when it follows one, else its own azimuth and elevation. */
export function skySunOf(params: (name: string) => number, light: [number, number, number] | null): [number, number, number] {
if (params('u_followSun') > 0.5 && light) return light;
const az = params('u_sunAzimuth') * Math.PI / 180, el = params('u_sunElevation') * Math.PI / 180;
return [Math.cos(el) * Math.sin(az), Math.sin(el), Math.cos(el) * Math.cos(az)];
}
/**
* What the sky is made from, rounded to what can be seen in its light: a key that changes only when the environment would.
* The cloud drift is rounded coarsest — a drifting sky lights the ground the same from one second to the next.
*/
export function skyEnvironmentKey(input: SkyEnvironmentInput): string {
const P = input.params;
const r = (v: number, step: number): number => Math.round(v / step);
const parts = [
r(input.sun[0], 0.004), r(input.sun[1], 0.004), r(input.sun[2], 0.004),
r(P('u_intensity'), 0.01), r(P('u_haze'), 0.02), r(P('u_overcast'), 0.01), r(P('u_altitude'), 0.05), r(P('u_groundAlbedo'), 0.01),
r(P('u_clouds'), 0.01), r(P('u_cloudBase'), 0.02), r(P('u_cloudThickness'), 0.02), r(P('u_cloudBrightness'), 0.02),
r(P('u_cloudScale'), 0.02), r(P('u_cloudSoftness'), 0.01), r(P('u_cloudSilver'), 0.05),
r(P('u_cloud2Coverage'), 0.01), r(P('u_cloud2Base'), 0.05), r(P('u_cloud2Thickness'), 0.05), r(P('u_cloud2Scale'), 0.05),
r(P('u_cloudDriftX'), 0.5), r(P('u_cloudDriftZ'), 0.5), r(P('u_cloudEvolve'), 0.25),
input.linear ? 1 : 0,
];
return parts.join(',');
}
/** A sky made into an environment: what the frame is handed, and the reflection atlas it holds. */
interface BakedSky {
environment: number;
texture: number;
}
interface SkyEnvironmentCore {
HEAPF32: Float32Array;
HEAPU8: Uint8Array;
postprocess_requestSkyCapture?(passName: string, width: number, height: number): void;
postprocess_pollSkyCapture?(): number;
postprocess_takeSkyCapture?(dst: number, bytes: number): boolean;
environment_create?(shPtr: number, specularHandle: number, faceSize: number, mipCount: number, maxRange: number, columns: number): number;
environment_release?(environmentHandle: number): void;
renderer_setSkyEnvironment?(environmentHandle: number): void;
}
/**
* The sky environment the frame lights with: worked out again when the sky changes, at most once a `minInterval` seconds, and
* let go (the frame told it has none) when no Sky Atmosphere asks to light the scene.
*/
export class SkyEnvironment {
private baked_: BakedSky | null = null;
private key_ = '';
private lastBake_ = -Infinity;
private warned_ = false;
private capturing_ = false;
private panorama_: Panorama | null = null;
constructor(private readonly minInterval = 1) {}
/** The panorama the sky's environment was last made from (radiance, Panorama's layout), or null: what a probe capture
* shows where it sees the sky. */
get panorama(): Panorama | null { return this.panorama_; }
/** The environment handle the frame is lighting with, 0 when none. */
get environment(): number { return this.baked_?.environment ?? 0; }
update(module: ESEngineModule | null, input: SkyEnvironmentInput | null, now: number): void {
const core = module as unknown as SkyEnvironmentCore | null;
if (!core?.environment_create || !core.renderer_setSkyEnvironment) {
if (input && !this.warned_) {
this.warned_ = true;
log.warn('postprocess', 'Sky Atmosphere cannot light the scene: this engine build has no sky environment');
}
return;
}
if (!input) {
if (this.baked_) {
core.renderer_setSkyEnvironment(0);
this.drop(core);
this.key_ = '';
}
return;
}
const key = skyEnvironmentKey(input);
if (key === this.key_) return;
// A first sky is made at once; a sky that keeps changing waits its turn.
if (this.baked_ && now - this.lastBake_ < this.minInterval) return;
const panorama = skyPanorama(input);
const made = bakePanorama(module, core, panorama);
if (!made) return;
this.panorama_ = panorama;
this.adopt(core, made, key, now);
}
/**
* A sky a project wrote (customSky.ts), lighting the scene from what the GPU drew of it: a panorama of the effect `type`
* is asked for, read back over the frames that follow, and made into the environment, once a `minInterval`.
*/
updateCaptured(module: ESEngineModule | null, type: string, now: number): void {
const core = module as unknown as SkyEnvironmentCore | null;
if (!core?.postprocess_requestSkyCapture || !core.postprocess_pollSkyCapture || !core.postprocess_takeSkyCapture
|| !core.environment_create || !core.renderer_setSkyEnvironment) {
if (!this.warned_) {
this.warned_ = true;
log.warn('postprocess', 'A custom sky cannot light the scene: this engine build cannot capture it');
}
return;
}
if (this.capturing_) {
const status = core.postprocess_pollSkyCapture();
if (status === 0) return;
this.capturing_ = false;
if (status !== 1) return;
const bytes = CUSTOM_SKY_WIDTH * CUSTOM_SKY_HEIGHT * 4;
const pixels = withScratch(core as never, (alloc: (n: number) => number) => {
const ptr = alloc(bytes);
return core.postprocess_takeSkyCapture!(ptr, bytes) ? core.HEAPU8.slice(ptr, ptr + bytes) : null;
});
if (!pixels) return;
const panorama = decodeSkyCapture(pixels, CUSTOM_SKY_WIDTH, CUSTOM_SKY_HEIGHT);
const made = bakePanorama(module, core, panorama);
if (made) { this.panorama_ = panorama; this.adopt(core, made, `custom:${type}`, now); }
return;
}
if (this.baked_ && this.key_ === `custom:${type}` && now - this.lastBake_ < this.minInterval) return;
core.postprocess_requestSkyCapture(type, CUSTOM_SKY_WIDTH, CUSTOM_SKY_HEIGHT);
this.capturing_ = true;
}
private adopt(core: SkyEnvironmentCore, made: BakedSky, key: string, now: number): void {
core.renderer_setSkyEnvironment!(made.environment);
this.drop(core);
this.baked_ = made;
this.key_ = key;
this.lastBake_ = now;
}
/** Lets the environment and its atlas go and tells the frame. */
release(module: ESEngineModule | null): void {
const core = module as unknown as SkyEnvironmentCore | null;
if (!core) return;
if (this.baked_) core.renderer_setSkyEnvironment?.(0);
this.drop(core);
this.key_ = '';
}
private drop(core: SkyEnvironmentCore): void {
if (!this.baked_) return;
core.environment_release?.(this.baked_.environment);
getResourceManager()?.releaseTexture(this.baked_.texture);
this.baked_ = null;
}
}
/** A panorama of radiance made into an environment: its nine irradiance coefficients and its prefiltered reflection. */
function bakePanorama(module: ESEngineModule | null, core: SkyEnvironmentCore, panorama: Panorama): BakedSky | null {
const irradiance = projectIrradianceSH(panorama);
const atlas = prefilterOctahedral(panorama, SKY_FACE_SIZE, SKY_MIP_COUNT, SKY_MAX_RANGE);
// flipY false: the atlas' rows are a layout (row 0 is mip 0), as the environment loader takes it.
const texture = createTextureFromPixels(module, { width: atlas.width, height: atlas.height, pixels: atlas.rgba },
TextureContent.Retained, false, { filterMode: 'linear', wrapMode: 'clamp', srgb: false });
if (!texture) return null;
const environment = withScratch(core as never, (alloc: (bytes: number) => number) => {
const shPtr = alloc(27 * 4);
core.HEAPF32.set(irradiance, shPtr >> 2);
return core.environment_create!(shPtr, texture, SKY_FACE_SIZE, SKY_MIP_COUNT, SKY_MAX_RANGE, 1);
});
if (!environment) {
getResourceManager()?.releaseTexture(texture);
return null;
}
return { environment, texture };
}