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(render): an environment can be seen, not only reflected

esengine439afa91a358
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dea98e92c..2dc00af70 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,26 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Added
+
+- **An environment can be seen, not only reflected.** A baked `.esenv` gave a
+ scene its irradiance and a prefiltered reflection, so a metal ball had a sky in
+ it — and behind the ball was a flat clear colour. The same panorama was half
+ visible and half not, for no reason anyone chose.
+
+ `Light2D.drawEnvironment` draws it as the background: a quad on the far plane,
+ shaded by the direction from the eye through each pixel, which is the direction
+ the reflection already samples. Off by default, so a scene that adopts an
+ environment for its lighting does not also acquire a sky it did not ask for; and
+ only where there is a prefiltered reflection to look at, since the nine
+ irradiance coefficients are that sky averaged over every direction — as a
+ background, one flat colour.
+
+ It is not a renderable: a sky belongs to no transform, is culled by nothing, and
+ sorts first by being in the Background stage. Its own vertex stream, because the
+ Batch one spends every sampler slot on a per-vertex merge and the sky has to
+ reach the environment atlas on the unit the shaders pin it to.
+
### Fixed
- **Whether a surface has normals no longer decides where its light is.** Two
diff --git a/desktop/public/scenes/mesh-sky.esscene b/desktop/public/scenes/mesh-sky.esscene
new file mode 100644
index 000000000..bc276336c
--- /dev/null
+++ b/desktop/public/scenes/mesh-sky.esscene
@@ -0,0 +1,70 @@
+{
+ "version": 1,
+ "name": "MeshSky",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 0,
+ "fov": 90,
+ "nearPlane": 1,
+ "farPlane": 1000,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Sky",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Light2D",
+ "data": {
+ "type": 2,
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "intensity": 1,
+ "environment": "/scenes/studio.esenv",
+ "drawEnvironment": true
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 6d6ce3e0c..60273d86a 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -1634,6 +1634,12 @@
"default": "none",
"doc": "Baked environment (.esenv) this Ambient light casts."
},
+ {
+ "key": "drawEnvironment",
+ "type": "boolean",
+ "default": "false",
+ "doc": "Draw this environment as the sky behind the scene."
+ },
{
"key": "enabled",
"type": "boolean",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 217f49dd8..71bb89bd3 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 66 beta · 1458 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"ea9373ff870f868a"
+"9169449040ae1dcb"
```
## ANCHOR_AXES — const @experimental
@@ -3982,6 +3982,7 @@ BuiltinComponentDef<Light2DData>
color: Color
direction: Vec2
directionZ: number
+drawEnvironment: boolean
enabled: boolean
environment: number
innerAngle: number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 0a8e2f1fc..173a16eea 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 71 beta · 1477 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"ea9373ff870f868a"
+"9169449040ae1dcb"
```
## ANCHOR_AXES — const @experimental
@@ -3990,6 +3990,7 @@ BuiltinComponentDef<Light2DData>
color: Color
direction: Vec2
directionZ: number
+drawEnvironment: boolean
enabled: boolean
environment: number
innerAngle: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index ec72669f3..403d4cd74 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -3977,6 +3977,7 @@ BuiltinComponentDef<Light2DData>
color: Color
direction: Vec2
directionZ: number
+drawEnvironment: boolean
enabled: boolean
environment: number
innerAngle: number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 7a3e3d3d2..51f981f36 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -3977,6 +3977,7 @@ BuiltinComponentDef<Light2DData>
color: Color
direction: Vec2
directionZ: number
+drawEnvironment: boolean
enabled: boolean
environment: number
innerAngle: number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index b0850d1fe..7ce7fb711 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -3984,6 +3984,7 @@ BuiltinComponentDef<Light2DData>
color: Color
direction: Vec2
directionZ: number
+drawEnvironment: boolean
enabled: boolean
environment: number
innerAngle: number
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index 98a5a7fb2..b0eaa70a3 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -699,6 +699,7 @@ export interface Light2DPtrData {
meshShadows: boolean;
shadowExtent: number;
environment: number;
+ drawEnvironment: boolean;
enabled: boolean;
}
@@ -719,7 +720,8 @@ export function fillLight2D(
out.meshShadows = u8[ptr + 56] !== 0;
out.shadowExtent = f32[(ptr + 60) >> 2];
out.environment = u32[(ptr + 64) >> 2];
- out.enabled = u8[ptr + 68] !== 0;
+ out.drawEnvironment = u8[ptr + 68] !== 0;
+ out.enabled = u8[ptr + 69] !== 0;
}
export function writeLight2D(
@@ -739,7 +741,8 @@ export function writeLight2D(
u8[ptr + 56] = data.meshShadows ? 1 : 0;
f32[(ptr + 60) >> 2] = data.shadowExtent;
u32[(ptr + 64) >> 2] = data.environment;
- u8[ptr + 68] = data.enabled ? 1 : 0;
+ u8[ptr + 68] = data.drawEnvironment ? 1 : 0;
+ u8[ptr + 69] = data.enabled ? 1 : 0;
}
export function createLight2DData(): Light2DPtrData {
@@ -757,6 +760,7 @@ export function createLight2DData(): Light2DPtrData {
meshShadows: false,
shadowExtent: 0,
environment: 0,
+ drawEnvironment: false,
enabled: false,
};
}
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index 0dd9f5835..23de78fd1 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { Dimension, Padding } from '../wasm/wasm.generated';
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = 'ea9373ff870f868a';
+export const ABI_LAYOUT_HASH = '9169449040ae1dcb';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -401,6 +401,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
meshShadows: false,
shadowExtent: 0,
environment: 0,
+ drawEnvironment: false,
enabled: true,
},
renderableField: 'enabled',
@@ -421,6 +422,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
meshShadows: { tooltip: "Cast a shadow map over 3D meshes (Directional)." },
shadowExtent: { min: 0, tooltip: "Shadow map coverage radius; 0 = fit the view.", advanced: true },
environment: { tooltip: "Baked environment (.esenv) this Ambient light casts." },
+ drawEnvironment: { tooltip: "Draw this environment as the sky behind the scene." },
},
},
Mesh2D: {
@@ -1213,6 +1215,7 @@ export interface Light2DData {
meshShadows: boolean;
shadowExtent: number;
environment: number;
+ drawEnvironment: boolean;
enabled: boolean;
}
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index 465f7e270..96b599ba5 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -212,7 +212,8 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'meshShadows', type: 'bool', offset: 56 },
{ name: 'shadowExtent', type: 'f32', offset: 60 },
{ name: 'environment', type: 'u32', offset: 64 },
- { name: 'enabled', type: 'bool', offset: 68 },
+ { name: 'drawEnvironment', type: 'bool', offset: 68 },
+ { name: 'enabled', type: 'bool', offset: 69 },
],
},
Mesh2D: {
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index 381c2df12..df092dfb5 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -384,6 +384,7 @@ export interface Light2D {
meshShadows: boolean;
shadowExtent: number;
environment: number;
+ drawEnvironment: boolean;
enabled: boolean;
}
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 718919a5f..c7af766c9 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -2,10 +2,10 @@
* @file EditorAPI.generated.cpp
* @brief Auto-generated editor API with string-dispatched component access
* @details Generated by EHT - DO NOT EDIT
- * @schema_hash 5c60fe026ad2d679
+ * @schema_hash 77c5905fcad9c63e
*/
-#define ES_EDITOR_API_SCHEMA_HASH "5c60fe026ad2d679"
+#define ES_EDITOR_API_SCHEMA_HASH "77c5905fcad9c63e"
#include <emscripten/bind.h>
#include <string>
@@ -303,6 +303,7 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"meshShadows","type":"bool","group":"Light2D"},
{"key":"shadowExtent","type":"float","group":"Light2D"},
{"key":"environment","type":"asset","group":"Light2D"},
+ {"key":"drawEnvironment","type":"bool","group":"Light2D"},
{"key":"enabled","type":"bool","group":"Light2D"}
])JSON";
} else if (name == "Mesh2D") {
@@ -2369,6 +2370,7 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::st
if (!reg.has<esengine::ecs::Light2D>(entity)) return false;
auto& c = reg.get<esengine::ecs::Light2D>(entity);
if (field == "meshShadows") { c.meshShadows = value; }
+ else if (field == "drawEnvironment") { c.drawEnvironment = value; }
else if (field == "enabled") { c.enabled = value; }
else { return false; }
return true;
@@ -2580,6 +2582,7 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::st
if (!reg.has<esengine::ecs::Light2D>(entity)) return false;
const auto& c = reg.get<esengine::ecs::Light2D>(entity);
if (field == "meshShadows") { return c.meshShadows; }
+ else if (field == "drawEnvironment") { return c.drawEnvironment; }
else if (field == "enabled") { return c.enabled; }
} else if (comp == "Mesh2D") {
if (!reg.has<esengine::ecs::Mesh2D>(entity)) return false;
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 0a586d7bb..ce2c45cfc 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -485,6 +485,7 @@ struct Light2DJS {
bool meshShadows;
f32 shadowExtent;
u32 environment;
+ bool drawEnvironment;
bool enabled;
};
@@ -502,6 +503,7 @@ void light2dApplyJS(esengine::ecs::Light2D& c, const Light2DJS& js) {
c.meshShadows = js.meshShadows;
c.shadowExtent = js.shadowExtent;
c.environment = resource::EnvironmentHandle(js.environment);
+ c.drawEnvironment = js.drawEnvironment;
c.enabled = js.enabled;
}
@@ -526,6 +528,7 @@ Light2DJS light2dToJS(const esengine::ecs::Light2D& c) {
js.meshShadows = c.meshShadows;
js.shadowExtent = c.shadowExtent;
js.environment = c.environment.id();
+ js.drawEnvironment = c.drawEnvironment;
js.enabled = c.enabled;
return js;
}
@@ -1446,6 +1449,7 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("meshShadows", &Light2DJS::meshShadows)
.field("shadowExtent", &Light2DJS::shadowExtent)
.field("environment", &Light2DJS::environment)
+ .field("drawEnvironment", &Light2DJS::drawEnvironment)
.field("enabled", &Light2DJS::enabled);
value_object<Mesh2DJS>("Mesh2D")
@@ -2791,7 +2795,8 @@ static_assert(offsetof(esengine::ecs::Light2D, shadowDistance) == 52, "ABI offse
static_assert(offsetof(esengine::ecs::Light2D, meshShadows) == 56, "ABI offset drift: esengine::ecs::Light2D.meshShadows (EHT expected 56)");
static_assert(offsetof(esengine::ecs::Light2D, shadowExtent) == 60, "ABI offset drift: esengine::ecs::Light2D.shadowExtent (EHT expected 60)");
static_assert(offsetof(esengine::ecs::Light2D, environment) == 64, "ABI offset drift: esengine::ecs::Light2D.environment (EHT expected 64)");
-static_assert(offsetof(esengine::ecs::Light2D, enabled) == 68, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 68)");
+static_assert(offsetof(esengine::ecs::Light2D, drawEnvironment) == 68, "ABI offset drift: esengine::ecs::Light2D.drawEnvironment (EHT expected 68)");
+static_assert(offsetof(esengine::ecs::Light2D, enabled) == 69, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 69)");
static_assert(offsetof(esengine::ecs::Mesh2D, texture) == 0, "ABI offset drift: esengine::ecs::Mesh2D.texture (EHT expected 0)");
static_assert(offsetof(esengine::ecs::Mesh2D, normalMap) == 4, "ABI offset drift: esengine::ecs::Mesh2D.normalMap (EHT expected 4)");
static_assert(offsetof(esengine::ecs::Mesh2D, color) == 8, "ABI offset drift: esengine::ecs::Mesh2D.color (EHT expected 8)");
@@ -3024,7 +3029,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "ea9373ff870f868a";
+static const char* kEsAbiLayoutHash = "9169449040ae1dcb";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/data/shaders/sky.esshader b/src/esengine/data/shaders/sky.esshader
new file mode 100644
index 000000000..d05186546
--- /dev/null
+++ b/src/esengine/data/shaders/sky.esshader
@@ -0,0 +1,75 @@
+#pragma shader "Sky"
+#pragma version 300 es
+#pragma domain Lit2D
+
+// The background half of an environment. The reflection in a metal ball and the
+// sky behind it are the same baked panorama; without this only one of them was
+// ever visible, and a scene lit by a sky sat in front of a flat clear colour.
+//
+// Geometry is a quad on the far plane, so the vertex stage needs no matrix of its
+// own — the fragment's direction is the one from the eye through it, which is
+// what viewDirection() already answers (negated: it points AT the viewer).
+
+#pragma vertex
+layout(location = 0) in vec3 a_position;
+
+out highp vec3 v_worldPos;
+
+void main() {
+ gl_Position = u_projection * vec4(a_position, 1.0);
+ v_worldPos = a_position;
+}
+#pragma end
+
+#pragma fragment
+precision highp float;
+
+in highp vec3 v_worldPos;
+out vec4 fragColor;
+
+void main() {
+ // Mip 0: the sharpest level of the prefiltered atlas is the sky as it was
+ // photographed. The rougher ones exist to be reflected, not to be looked at.
+ fragColor = vec4(envSampleMip(-viewDirection(v_worldPos), 0.0), 1.0);
+}
+#pragma end
+
+#pragma vertex wgsl
+struct VSIn {
+ @location(0) a_position : vec3f,
+};
+struct VSOut {
+ @builtin(position) pos : vec4f,
+ @location(0) v_worldPos : vec3f,
+};
+
+@vertex fn vs_main(v : VSIn) -> VSOut {
+ var out : VSOut;
+ out.pos = frame.projection * vec4f(v.a_position, 1.0);
+ out.v_worldPos = v.a_position;
+ return out;
+}
+#pragma end
+
+#pragma fragment wgsl
+// Slot 0 is bound and never read — a draw fills it so the walk that pins the
+// atlas one slot on has somewhere to start. The atlas itself is on 3, and
+// without these two the injected sampler names identifiers this twin never
+// declared: an invalid pipeline that does not mention a shader.
+@group(1) @binding(0) var t0 : texture_2d<f32>;
+@group(1) @binding(8) var s0 : sampler;
+@group(1) @binding(3) var t3 : texture_2d<f32>;
+@group(1) @binding(11) var s3 : sampler;
+
+// Declared again: each WGSL block is compiled on its own, so a struct defined in
+// the vertex one is an undeclared name here — and that reaches anyone as an
+// invalid pipeline with nothing in the log about a shader.
+struct VSOut {
+ @builtin(position) pos : vec4f,
+ @location(0) v_worldPos : vec3f,
+};
+
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
+ return vec4f(envSampleMip(-viewDirection(v.v_worldPos), 0.0), 1.0);
+}
+#pragma end
diff --git a/src/esengine/ecs/components/Light2D.hpp b/src/esengine/ecs/components/Light2D.hpp
index 99c23a3e4..b6960ee9b 100644
--- a/src/esengine/ecs/components/Light2D.hpp
+++ b/src/esengine/ecs/components/Light2D.hpp
@@ -119,6 +119,13 @@ struct Light2D {
ES_PROPERTY(asset = environment, tooltip="Baked environment (.esenv) this Ambient light casts.")
resource::EnvironmentHandle environment;
+ /** @brief Draw @ref environment as the background as well as reflecting it. Off by
+ * default, so a scene that adopts an environment for its lighting does not
+ * also acquire a sky it did not ask for. Ignored without one — and the
+ * camera still decides whether the background is drawn at all. */
+ ES_PROPERTY(tooltip="Draw this environment as the sky behind the scene.")
+ bool drawEnvironment{false};
+
/** @brief Disabled lights are skipped during collection. */
ES_PROPERTY()
bool enabled{true};
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 216ee70bf..1eb94ec09 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -4,6 +4,7 @@
#include "../rhi/Shader.hpp"
#include "../rhi/ShaderEmbeds.generated.hpp"
#include "../store/LightStore.hpp"
+#include "../draw/BatchBuilder.hpp"
#include "../../ecs/components/Transform.hpp"
#include "../../ecs/components/Light2D.hpp"
#include "../../ecs/components/ShadowCaster2D.hpp"
@@ -17,6 +18,7 @@
#include <algorithm>
#include <cmath>
+#include <limits>
#include <vector>
namespace esengine {
@@ -649,6 +651,7 @@ void RenderFrame::collectLights(ecs::Registry& registry) {
lights.clear();
shadow_light_slot_ = -1;
environment_texture_id_ = 0;
+ draw_sky_ = false;
// Gather non-ambient lights, then (if over the UBO's cap) keep the most intense — the
// brightest contribute most, and an explicit importance cull beats silently dropping
@@ -768,6 +771,9 @@ bool RenderFrame::collectEnvironment(const ecs::Light2D& light, const glm::vec3&
return false;
}
environment_texture_id_ = textureId;
+ // Only a reflection can be looked at directly: the nine coefficients are the
+ // sky averaged over every direction, which as a background is one flat colour.
+ draw_sky_ = light.drawEnvironment && textureId != 0;
return true;
}
@@ -1011,6 +1017,58 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {
device_.setViewport(sceneViewport.x, sceneViewport.y, sceneViewport.w, sceneViewport.h);
}
+/**
+ * The background an environment is, as a quad on the far plane. Not a plugin and
+ * not an entity: a sky belongs to no transform and is culled by nothing. Its
+ * corners are the far plane's, unprojected, so a fragment's direction is the one
+ * from the eye through it — which viewDirection() already answers.
+ */
+void RenderFrame::collectSky(RenderCollectContext& ctx) {
+ if (!draw_sky_ || environment_texture_id_ == 0) return;
+ if (!sky_compiled_) {
+ sky_compiled_ = true;
+ auto parsed = resource::ShaderParser::parse(ShaderEmbeds::SKY);
+ const auto target = resource_manager_.preferredShaderTarget();
+ const std::vector<std::string> features{"ES_ENV_MAP"};
+ resource::ShaderHandle handle = resource_manager_.createShaderWithBindings(
+ resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Vertex, "",
+ features, target),
+ resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Fragment, "",
+ features, target),
+ {}, resource_manager_.preferredShaderLanguage());
+ if (auto* shader = resource_manager_.getShader(handle)) sky_program_ = shader->getProgramId();
+ }
+ if (sky_program_ == 0) return;
+
+ // The far plane's four corners in world space. Clip z = 1 is that plane under
+ // both backends' shared projection, and w divides out whichever it is.
+ const glm::mat4 invVP = glm::inverse(ctx.frame_context.view_projection);
+ glm::vec3 corners[4];
+ const glm::vec2 ndc[4] = {{-1.0f, -1.0f}, {1.0f, -1.0f}, {1.0f, 1.0f}, {-1.0f, 1.0f}};
+ for (u32 i = 0; i < 4; ++i) {
+ const glm::vec4 p = invVP * glm::vec4(ndc[i], 1.0f, 1.0f);
+ corners[i] = glm::vec3(p) / p.w;
+ }
+
+ BatchDrawKey key{};
+ key.stage = RenderStage::Background;
+ key.layer = std::numeric_limits<i32>::min();
+ key.shaderId = sky_program_;
+ key.blend = BlendMode::None;
+ key.layoutId = LayoutId::Sky;
+ // Slot 0 is filled with white and never sampled: the atlas rides the unit the
+ // shaders pin it to, and the fill is what the slot walk below it expects.
+ key.textureId = ctx.frame_context.white_texture_id;
+ key.envTextureId = environment_texture_id_;
+ key.type = RenderType::Mesh;
+ // Neither tested nor written: the sky is behind everything by being first, and
+ // depth of its own would fight the geometry that draws over it.
+ key.depthTest = false;
+ key.depthWrite = false;
+ appendIndexedDraw(ctx.buffer_pool, ctx.draw_list, ctx.clip_state, corners, 4,
+ BATCH_QUAD_INDICES, 6, key);
+}
+
void RenderFrame::collectAll(ecs::Registry& registry, u32 skipFlags) {
ES_PROFILE_SCOPE("render.collect");
buildClipState();
@@ -1021,6 +1079,7 @@ void RenderFrame::collectAll(ecs::Registry& registry, u32 skipFlags) {
RenderCollectContext collectCtx{registry, frustum_, clip_state_, pool_, draw_list_, ctx,
computeCameraWorldRect(ctx.view_projection)};
+ collectSky(collectCtx);
for (auto& plugin : plugins_) {
if (skipFlags != 0 && (skipFlags & plugin->skipFlag()) != 0) continue;
plugin->collect(collectCtx);
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 1090ddebc..d8fe03fc8 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -336,6 +336,13 @@ private:
u32 shadow_texture_id_ = 0;
/// The frame environment's reflection atlas, on the same terms. 0 = none this frame.
u32 environment_texture_id_ = 0;
+ /// Whether that environment is also the background this frame.
+ bool draw_sky_ = false;
+ /// The far-plane quad's program, compiled on first use.
+ u32 sky_program_ = 0;
+ bool sky_compiled_ = false;
+ /// Emits the background quad when an environment asked to be seen behind the scene.
+ void collectSky(RenderCollectContext& ctx);
// processMasks scratch, reused across cameras/frames.
std::vector<Entity> mask_scissor_scratch_;
diff --git a/src/esengine/renderer/rhi/GfxEnums.hpp b/src/esengine/renderer/rhi/GfxEnums.hpp
index e5cae28ac..f819188a2 100644
--- a/src/esengine/renderer/rhi/GfxEnums.hpp
+++ b/src/esengine/renderer/rhi/GfxEnums.hpp
@@ -85,9 +85,13 @@ enum class LayoutId : u8 {
/// pool's; the layout belongs to the mesh, which is the one that knows what
/// its own vertices look like.
MeshInstance = 3,
+ /// The background quad: a world position and nothing else. Its own stream
+ /// because the Batch one spends every sampler slot on a per-vertex merge, and
+ /// the sky has to reach the environment atlas on the slot the shaders pin it to.
+ Sky = 4,
};
-static constexpr u32 LAYOUT_COUNT = 4;
+static constexpr u32 LAYOUT_COUNT = 5;
/// One per-object record for a resident mesh: a model matrix and a tint.
static constexpr u32 MESH_INSTANCE_STRIDE = 68;
diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
index 2d68d37d1..e75c62a6d 100644
--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
@@ -794,4 +794,81 @@ struct VSOut {
#pragma end
)esshader";
+inline constexpr const char* SKY = R"esshader(#pragma shader "Sky"
+#pragma version 300 es
+#pragma domain Lit2D
+
+// The background half of an environment. The reflection in a metal ball and the
+// sky behind it are the same baked panorama; without this only one of them was
+// ever visible, and a scene lit by a sky sat in front of a flat clear colour.
+//
+// Geometry is a quad on the far plane, so the vertex stage needs no matrix of its
+// own — the fragment's direction is the one from the eye through it, which is
+// what viewDirection() already answers (negated: it points AT the viewer).
+
+#pragma vertex
+layout(location = 0) in vec3 a_position;
+
+out highp vec3 v_worldPos;
+
+void main() {
+ gl_Position = u_projection * vec4(a_position, 1.0);
+ v_worldPos = a_position;
+}
+#pragma end
+
+#pragma fragment
+precision highp float;
+
+in highp vec3 v_worldPos;
+out vec4 fragColor;
+
+void main() {
+ // Mip 0: the sharpest level of the prefiltered atlas is the sky as it was
+ // photographed. The rougher ones exist to be reflected, not to be looked at.
+ fragColor = vec4(envSampleMip(-viewDirection(v_worldPos), 0.0), 1.0);
+}
+#pragma end
+
+#pragma vertex wgsl
+struct VSIn {
+ @location(0) a_position : vec3f,
+};
+struct VSOut {
+ @builtin(position) pos : vec4f,
+ @location(0) v_worldPos : vec3f,
+};
+
+@vertex fn vs_main(v : VSIn) -> VSOut {
+ var out : VSOut;
+ out.pos = frame.projection * vec4f(v.a_position, 1.0);
+ out.v_worldPos = v.a_position;
+ return out;
+}
+#pragma end
+
+#pragma fragment wgsl
+// Slot 0 is bound and never read — a draw fills it so the walk that pins the
+// atlas one slot on has somewhere to start. The atlas itself is on 3, and
+// without these two the injected sampler names identifiers this twin never
+// declared: an invalid pipeline that does not mention a shader.
+@group(1) @binding(0) var t0 : texture_2d<f32>;
+@group(1) @binding(8) var s0 : sampler;
+@group(1) @binding(3) var t3 : texture_2d<f32>;
+@group(1) @binding(11) var s3 : sampler;
+
+// Declared again: each WGSL block is compiled on its own, so a struct defined in
+// the vertex one is an undeclared name here — and that reaches anyone as an
+// invalid pipeline with nothing in the log about a shader.
+struct VSOut {
+ @builtin(position) pos : vec4f,
+ @location(0) v_worldPos : vec3f,
+};
+
+@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
+ return vec4f(envSampleMip(-viewDirection(v.v_worldPos), 0.0), 1.0);
+}
+#pragma end
+)esshader";
+
} // namespace esengine::ShaderEmbeds
diff --git a/src/esengine/renderer/rhi/TransientBufferPool.cpp b/src/esengine/renderer/rhi/TransientBufferPool.cpp
index f61e232ec..2f9d522de 100644
--- a/src/esengine/renderer/rhi/TransientBufferPool.cpp
+++ b/src/esengine/renderer/rhi/TransientBufferPool.cpp
@@ -18,6 +18,7 @@ void TransientBufferPool::init(u32 initialVertexBytes, u32 initialIndexCount) {
initial_index_count_ = initialIndexCount;
for (auto layout : {LayoutId::Batch, LayoutId::ParticleInstance, LayoutId::Shape,
+ LayoutId::Sky,
LayoutId::MeshInstance}) {
setupStream(layout);
}
@@ -280,6 +281,13 @@ void TransientBufferPool::setupStream(LayoutId layout) {
desc.attributes[2] = {2, 4, GfxDataType::Float, false, 16, 0};
desc.attributes[3] = {3, 4, GfxDataType::Float, false, 32, 0};
break;
+ case LayoutId::Sky:
+ // One vec3 and nothing else: a layout may not declare an attribute its
+ // shader does not consume, which is why this is not the Batch one.
+ desc.attributeCount = 1;
+ desc.strides[0] = 12;
+ desc.attributes[0] = {0, 3, GfxDataType::Float, false, 0, 0};
+ break;
default:
break;
}
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index fb1569bfc..6b338065d 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -80,6 +80,7 @@ export const SCENES = [
// A baked panorama lighting a surface BY DIRECTION: two coplanar triangles, one
// white colour, normals up and down under a sky blue above and red below. A flat
// ambient term draws the halves identically, which is why the probes invert.
+ { id: "mesh-sky", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-sky.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.15,\"rgb\":[0,0,153],\"tol\":20},{\"x\":0.5,\"y\":0.85,\"rgb\":[153,0,0],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[106,0,33],\"tol\":20},{\"x\":0.15,\"y\":0.5,\"rgb\":[76,0,70],\"tol\":20}]" } },
{ id: "mat-env", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-env.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.55,\"rgb\":[0,6,149],\"tol\":20},{\"x\":0.75,\"y\":0.55,\"rgb\":[148,8,0],\"tol\":20},{\"x\":0.5,\"y\":0.55,\"rgb\":[0,0,0],\"tol\":20}]" } },
// The same sky in a MIRROR: two metal quads, roughness 0 and 1. A head-on
// surface reflects +Z, which is the image centre — green there, and the whole