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 RenderFrame.cpp
* @brief Assemble and submit shared scene views, lighting and shadow passes.
*/
#include "./RenderFrame.hpp"
#ifdef ES_ENABLE_GPU_PARTICLES
#include "./GpuParticles.hpp"
#endif
#include "../rhi/Shader.hpp"
#include "../rhi/ShaderEmbeds.generated.hpp"
#include "../store/LightStore.hpp"
#include "../draw/BatchBuilder.hpp"
#include "../draw/ImmediateDraw.hpp"
#include "../draw/MeshGeometry.hpp"
#include "../draw/PlacementBounds.hpp"
#include "../../ecs/components/Transform.hpp"
#include "../../ecs/components/Light.hpp"
#include "../../ecs/components/Occluder.hpp"
#include "../../ecs/components/ReflectionProbe.hpp"
#include "../../ecs/components/ShadowCaster2D.hpp"
#include "../../ecs/components/SortingGroup.hpp"
#include "../../ecs/components/SpriteMask.hpp"
#include "../../ecs/components/Sprite.hpp"
#include "../../ecs/components/Hierarchy.hpp"
#include "../../ecs/components/MeshRenderer.hpp"
#include "../../resource/ShaderParser.hpp"
#include "../../core/Log.hpp"
#include "../../core/FrameProfiler.hpp"
#include <glm/gtc/matrix_transform.hpp>
#include <glm/gtc/type_ptr.hpp>
#include <algorithm>
#ifdef __EMSCRIPTEN__
#include <emscripten.h>
#endif
#include <cmath>
#include <cstring>
#include <limits>
#include <utility>
#include <vector>
namespace esengine {
glm::vec3 srgbToLinearCpu(const glm::vec3& c);
void GpuTimer::begin(GfxDevice& device) {
if (state_ == 0) {
// Lazy probe: the device reports timer support by whether it can create a query.
queries_[0] = device.createTimerQuery();
if (queries_[0] != 0) {
for (int i = 1; i < kRing; ++i) queries_[i] = device.createTimerQuery();
state_ = 1;
} else {
state_ = 2;
}
}
if (state_ != 1 || inflight_[write_]) return;
device.beginTimerQuery(queries_[write_]);
active_ = true;
}
void GpuTimer::end(GfxDevice& device) {
if (!active_) return;
device.endTimerQuery();
inflight_[write_] = true;
write_ = (write_ + 1) % kRing;
active_ = false;
}
void GpuTimer::poll(GfxDevice& device) {
if (state_ != 1) return;
if (device.timerDisjoint()) { // timing disturbed — drop everything in flight
for (int i = 0; i < kRing; ++i) inflight_[i] = false;
read_ = write_;
return;
}
while (inflight_[read_]) {
u64 ns = 0;
if (!device.getTimerQueryNs(queries_[read_], &ns)) break;
last_ms_ = static_cast<f32>(ns) / 1.0e6f;
inflight_[read_] = false;
read_ = (read_ + 1) % kRing;
}
}
f32 Plane::signedDistance(const glm::vec3& point) const {
return glm::dot(normal, point) + distance;
}
void Frustum::extractFromMatrix(const glm::mat4& vp) {
const f32* m = glm::value_ptr(vp);
planes[0].normal = glm::vec3(m[3] + m[0], m[7] + m[4], m[11] + m[8]);
planes[0].distance = m[15] + m[12];
planes[1].normal = glm::vec3(m[3] - m[0], m[7] - m[4], m[11] - m[8]);
planes[1].distance = m[15] - m[12];
planes[2].normal = glm::vec3(m[3] + m[1], m[7] + m[5], m[11] + m[9]);
planes[2].distance = m[15] + m[13];
planes[3].normal = glm::vec3(m[3] - m[1], m[7] - m[5], m[11] - m[9]);
planes[3].distance = m[15] - m[13];
planes[4].normal = glm::vec3(m[3] + m[2], m[7] + m[6], m[11] + m[10]);
planes[4].distance = m[15] + m[14];
planes[5].normal = glm::vec3(m[3] - m[2], m[7] - m[6], m[11] - m[10]);
planes[5].distance = m[15] - m[14];
for (u32 i = 0; i < 6; ++i) {
f32 len = glm::length(planes[i].normal);
if (len > 1e-7f) {
planes[i].normal /= len;
planes[i].distance /= len;
}
}
}
bool Frustum::intersectsAABB(const glm::vec3& center, const glm::vec3& halfExtents) const {
for (u32 i = 0; i < 6; ++i) {
f32 r = halfExtents.x * std::abs(planes[i].normal.x) +
halfExtents.y * std::abs(planes[i].normal.y) +
halfExtents.z * std::abs(planes[i].normal.z);
f32 dist = planes[i].signedDistance(center);
if (dist < -r) {
return false;
}
}
return true;
}
bool Frustum::intersectsSweptSphere(const glm::vec3& a, const glm::vec3& b, f32 radius) const {
for (u32 i = 0; i < 6; ++i) {
if (planes[i].signedDistance(a) < -radius && planes[i].signedDistance(b) < -radius) return false;
}
return true;
}
RenderFrame::RenderFrame(GfxDevice& device, RenderContext& context,
resource::ResourceManager& resource_manager)
: device_(device)
, context_(context)
, resource_manager_(resource_manager)
, pool_(device)
, target_pool_(device)
, graph_(device, target_pool_)
, shadow_pool_(device)
, velocity_pool_(device)
, cover_pool_(device) {
target_manager_.setDevice(device);
}
RenderFrame::~RenderFrame() {
shutdown();
}
void RenderFrame::init(u32 width, u32 height) {
width_ = width;
height_ = height;
// state_tracker_ is inited once by EstellaContext (its owner); flush()/replay
// reset() it each frame, so no per-RenderFrame init is needed here.
// Adopt the boot-declared color space before any shader compiles below —
// renderer_setColorSpace may run before this frame exists (pre-init).
linear_color_ = resource::ShaderParser::linearColorSpace();
#ifdef ES_ENABLE_POSTPROCESS
post_process_ = makeUnique<PostProcessPipeline>(device_, context_, resource_manager_,
graph_);
post_process_->setLinearOutput(linear_color_);
// The requirement may have been declared before the pipeline existed (a depth
// layer arrives with the project, init happens on the first frame) — and until
// a frame has answered, the answer is that the capture carries depth.
applySceneDepthNeed();
post_process_->init(width, height);
#endif
#ifdef ES_ENABLE_GPU_PARTICLES
gpu_particles_ = makeUnique<GpuParticles>(device_);
#endif
pool_.init();
shadow_pool_.init();
velocity_pool_.init();
cover_pool_.init();
planar_pool_.init();
probe_pool_.init();
batch_shader_id_ = initBatchShader();
RenderFrameContext initCtx{
context_,
resource_manager_,
context_.getWhiteTextureId(),
batch_shader_id_,
RenderStage::Transparent,
glm::mat4(1.0f),
nullptr,
this
};
for (auto& plugin : plugins_) {
plugin->init(initCtx);
}
}
void RenderFrame::shutdown() {
for (auto& plugin : plugins_) {
plugin->shutdown();
}
plugins_.clear();
#ifdef ES_ENABLE_GPU_PARTICLES
if (gpu_particles_) {
gpu_particles_->release();
gpu_particles_.reset();
}
#endif
pool_.shutdown();
shadow_pool_.shutdown();
velocity_pool_.shutdown();
cover_pool_.shutdown();
if (cover_frame_ubo_ != BufferHandle::Invalid) {
device_.deleteBuffer(cover_frame_ubo_);
cover_frame_ubo_ = BufferHandle::Invalid;
}
planar_pool_.shutdown();
probe_pool_.shutdown();
if (probe_capture_.frameUbo != BufferHandle::Invalid) {
device_.deleteBuffer(probe_capture_.frameUbo);
probe_capture_.frameUbo = BufferHandle::Invalid;
}
releasePlanarCaptures();
releaseShadowFrameUbos();
releaseShadow2DResources();
releaseShape2DResources();
releaseFrameTargets();
target_pool_.clear();
#ifdef ES_ENABLE_POSTPROCESS
if (post_process_) {
post_process_->shutdown();
post_process_.reset();
}
#endif
ES_LOG_INFO("RenderFrame shutdown");
}
void RenderFrame::resize(u32 width, u32 height) {
width_ = width;
height_ = height;
#ifdef ES_ENABLE_POSTPROCESS
if (post_process_) {
post_process_->resize(width, height);
}
#endif
}
// The scene pass's body. The graph has bound the target and set the camera's
// viewport; this is the draw and the constants it needs current.
bool RenderFrame::gpuDetailWanted() const {
#ifdef __EMSCRIPTEN__
// A harness's switch, read only while the profiler is on: `module.esGpuDetail = true` from the page.
return EM_ASM_INT({ return Module.esGpuDetail ? 1 : 0; }) != 0;
#else
return false;
#endif
}
void RenderFrame::submitColorList(DrawList& list, TransientBufferPool& buffers, FrameCapture* capture,
DrawList::Phase phase, const char* prepassCounter) {
const bool opaque = phase == DrawList::Phase::All || phase == DrawList::Phase::WithoutSceneColor || phase == DrawList::Phase::OpaqueOnly;
const u32 prepassDraws = depth_prepass_ && opaque ? list.depthPrepassDraws() : 0u;
const bool prepass = prepassDraws > 0;
if (opaque) ES_PROFILE_COUNTER(prepassCounter, prepassDraws);
const bool detail = running_pass_timer_ && gpuDetailWanted();
const auto sinkFor = [this, &list](const char* prefix) {
rg::PassTimer* timer = running_pass_timer_;
list.setShaderRunSink([timer, prefix](const char* shader) {
timer->segment(shader ? std::string(prefix) + shader : std::string("tail"));
});
};
if (prepass) {
ES_PROFILE_SCOPE("render.submit.prepass");
if (detail) sinkFor("prepass:");
list.execute(device_, buffers, context_.materials(), context_.getWhiteTextureId(),
nullptr, context_.perDrawBlocks(), phase, DrawList::DrawPass::DepthPrepass);
if (detail) list.setShaderRunSink(nullptr);
}
if (detail) sinkFor("");
list.execute(device_, buffers, context_.materials(), context_.getWhiteTextureId(),
capture, context_.perDrawBlocks(), phase,
prepass ? DrawList::DrawPass::ColorAfterPrepass : DrawList::DrawPass::Color);
if (detail) {
running_pass_timer_->segment("tail");
list.setShaderRunSink(nullptr);
}
}
void RenderFrame::drawScene(DrawList::Phase phase) {
// A temporal effect in the chain asks for the picture to be shifted by a different
// sub-pixel amount each frame, so its history samples what a single frame cannot.
// The scene only: the overlay and the shadow maps are drawn with constants of their own.
glm::vec2 jitter{0.0f};
#ifdef ES_ENABLE_POSTPROCESS
// The atlas the meshes reflect, for an effect that adds a reflection of its own where the scene's ray found none.
if (post_process_) post_process_->setEnvironmentTexture(environment_texture_id_);
if (phase == DrawList::Phase::SceneColorOnly || phase == DrawList::Phase::BlendedOnly) {
// The second half of a scene drawn in two: the same camera, shifted the same way, and a frame that must not step the
// temporal view a second time.
jitter = scene_jitter_;
} else if (post_process_ && post_process_->isEngaged() && post_process_->temporalActive()) {
jitter = post_process_->beginTemporalView(view_projection_, current_target_);
} else if (post_process_ && post_process_->isEngaged() && post_process_->cameraMotionWanted()) {
post_process_->trackView(view_projection_, current_target_);
}
#endif
scene_jitter_ = jitter;
context_.updateCameraConstants(view_projection_, jitter);
// Where THIS camera's pixels sit inside the 2D shadow mask. Per camera because the
// mask is screen space: two cameras drew into two parts of one target, and a
// fragment has to read the part its own camera filled.
if ((shadow2DActive() || shape2DActive()) && width_ > 0 && height_ > 0) {
const f32 w = static_cast<f32>(width_);
const f32 h = static_cast<f32>(height_);
// The height's SIGN carries which way this backend stores the rows it just drew.
// One shader source serves both backends — the WGSL a material runs is translated
// from the GLSL — so the convention travels as data rather than a #ifdef.
const f32 rows = device_.textureOriginTopLeft() ? -1.0f : 1.0f;
context_.lights().setMask2DRect(glm::vec4(
static_cast<f32>(std::max(scene_viewport_.x, 0)) / w,
static_cast<f32>(std::max(scene_viewport_.y, 0)) / h,
static_cast<f32>(scene_viewport_.w) / w,
static_cast<f32>(scene_viewport_.h) / h * rows));
} else {
context_.lights().setMask2DRect(glm::vec4(0.0f));
}
draw_list_.setMask2DTexture(SHADOW_2D_TEXTURE_UNIT, shadow_2d_masks_[0].textureId);
// Unit 6 is the shape mask's, or the second shadow mask's in a frame with no cookie (see MAX_SHADOW_2D_LIGHTS).
draw_list_.setMask2DTexture(SHAPE_2D_TEXTURE_UNIT, shape_2d_texture_id_ != 0 ? shape_2d_texture_id_ : shadow_2d_masks_[1].textureId);
// Here and not in flush(): the shadow pass runs before this one and decides
// which atlas tile each light reads, so the block has to go up after it.
context_.lights().uploadAndBind();
{
ES_PROFILE_SCOPE("render.submit");
#ifdef ES_ENABLE_POSTPROCESS
draw_list_.setGBufferPass(post_process_ && post_process_->sceneHasGBuffer());
#endif
submitColorList(draw_list_, pool_, &frame_capture_, phase, "render.prepass.draws");
draw_list_.setGBufferPass(false);
if (device_.skipPendingPrograms()) {
ES_PROFILE_COUNTER("render.draws.waitingForProgram", draw_list_.skippedForProgram());
ES_PROFILE_COUNTER("render.programs.pending", device_.pendingProgramCount());
}
}
// Handed over to whatever the graph runs next. Blend/depth/colour-mask come
// from each fullscreen pass's own pipeline, but scissor is dynamic state and
// a chain pass would inherit whatever the last scene draw left.
device_.invalidatePipelineCache();
device_.setScissorTest(false);
}
// The atlas texture this frame published, unpublished — the target behind it is
// the graph's loan. Owed by a new frame, a device loss and shutdown, because the
// id the receiving draws were keyed by names nothing once its device is gone.
void RenderFrame::releaseFrameTargets() {
shadow_texture_id_ = 0;
}
void RenderFrame::beginFrame() {
++planar_frame_;
#ifdef ES_ENABLE_GPU_PARTICLES
if (gpu_particles_) gpu_particles_->beginFrame();
#endif
for (auto it = planar_captures_.begin(); it != planar_captures_.end();) {
if (frame_collected_ && it->second.lastSeen + 1 < planar_frame_) {
if (it->second.frameUbo != BufferHandle::Invalid) device_.deleteBuffer(it->second.frameUbo);
it = planar_captures_.erase(it);
} else ++it;
}
// Here and not at end(), which runs once per CAMERA: every camera plans and
// renders its own maps, and the pool hands the same physical atlas to each in
// turn. Then one tick of the clock, by the frame that owns the pool.
releaseFrameTargets();
target_pool_.age();
// Last frame's answer becomes this frame's, once. A frame that collected
// nothing answered nothing — an editor frame that only blits, a frame the host
// skipped — so it neither latches nor releases.
if (frame_collected_) {
depth_answered_ = true;
if (frame_depth_seen_) depth_seen_ = true;
scene_picture_seen_ = frame_scene_picture_seen_;
}
frame_scene_picture_seen_ = false;
frame_collected_ = false;
frame_depth_seen_ = false;
applySceneDepthNeed();
// Counted over the whole frame rather than per camera, because a selection is
// one view's answer: the same object seen by two cameras is two selections, and
// that they can differ is the whole claim.
lod_counts_ = {};
lod_view_state_.beginFrame();
// The per-draw blocks go back at the FRAME boundary and not at each pass's:
// a frame reaches the device as several passes with one submission behind
// them, so a buffer reused between two of them is read by both.
context_.beginPerDrawBlocks();
frame_capture_.beginFrame();
// The frame's tally, over every camera and the overlay.
stats_ = Stats{};
frame_merged_ = 0;
std::fill(std::begin(frame_breaks_), std::end(frame_breaks_), 0u);
}
void RenderFrame::applySceneDepthNeed() {
#ifdef ES_ENABLE_POSTPROCESS
if (!post_process_) return;
bool computeNeedsDepth = false;
#ifdef ES_ENABLE_GPU_PARTICLES
computeNeedsDepth = gpu_particles_ && gpu_particles_->wantsDepth();
#endif
post_process_->setComputeNeedsDepth(computeNeedsDepth || scene_picture_seen_);
post_process_->setSceneNeedsDepth(!depth_answered_ || depth_seen_ || computeNeedsDepth || scene_picture_seen_
|| draw_list_.depthMask() != 0);
#endif
}
void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::Handle target) {
begin(view_projection, target, PassClear{});
}
void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::Handle target,
const PassClear& camera_clear) {
// A chain that is engaged draws the scene into a capture exactly as big as the camera's rect, and only its present lands at
// the rect's offset (setOutputViewport). So the camera's rect starts at the capture's origin: left at the camera's own x/y
// it names pixels outside the capture, and a camera that does not start at the window's corner (the right half of a split,
// a minimap) drew nothing at all whenever the frame was linear, tone mapped or post-processed.
PassClear clear = camera_clear;
#ifdef ES_ENABLE_POSTPROCESS
if (post_process_ && post_process_->isEngaged()) {
clear.x = 0;
clear.y = 0;
}
#endif
// Emptied before the device is asked, so a refused frame starts empty too: the host still submits text and skinned batches into
// it, and while a lost device waits for its content no end() ever ran to empty them, so the staging grew every frame until an
// allocation of gigabytes failed.
pool_.beginFrame();
draw_list_.clear();
clip_state_.clear();
// A lost device makes the whole frame meaningless, so it is refused here
// rather than discovered by each pass and readback failing separately.
// in_frame_ stays false, which makes end() a no-op too: no half-frame.
if (!device_.beginDeviceFrame()) {
in_frame_ = false;
return;
}
view_projection_ = view_projection;
frustum_.extractFromMatrix(view_projection);
// A camera that names no view looks from the shared default one rather than
// remembering the levels the previous camera settled on.
view_id_ = 0;
current_target_ = target;
current_stage_ = RenderStage::Transparent;
in_frame_ = true;
frame_capture_.beginPass(CapturePass::Scene);
openPass(clear, target);
// The rect this camera draws into, taken where the camera STATES it — a zero size
// means the whole target, as it does to a pass. Read off the device at flush it is
// whatever the collect between left there, and one camera covered the other.
scene_viewport_ = {clear.x, clear.y, clear.w, clear.h};
// What the scene pass writes. With a chain engaged the capture is already a
// graph resource (the pipeline declared it when it opened); without one the
// frame's own target is imported, and the graph culls back from it.
scene_resource_ = rg::kNoResource;
#ifdef ES_ENABLE_POSTPROCESS
if (post_process_ && post_process_->isEngaged()) {
scene_resource_ = post_process_->sceneResource();
}
#endif
if (scene_resource_ == rg::kNoResource) {
graph_.begin(width_, height_);
scene_resource_ = graph_.importTarget(scene_fbo_, width_, height_);
}
}
// Opening the frame's target: the load-op clear, the post-process capture when
// one is engaged, the default surface otherwise. Bound EAGERLY, before the graph
// runs, so a host draw between this call and end() lands in the scene.
void RenderFrame::openPass(const PassClear& clear, RenderTargetManager::Handle target) {
#ifdef ES_ENABLE_POSTPROCESS
const bool usePostProcess = post_process_ && post_process_->isEngaged();
#else
const bool usePostProcess = false;
#endif
// The pass's load-op clear, values carried in the desc (never sticky device
// state). Region-scoped when the caller renders one camera's viewport of a
// shared target.
RenderPassDesc pass{};
pass.clearColor = clear.color;
pass.clearDepth = clear.depth;
// Stencil shares depth's attachment, so it clears on the same terms and costs the same
// load-op. A frame keeping last frame's stencil cuts along a mask that has since moved;
// a camera deliberately keeping depth means to keep that cut too.
pass.clearStencil = clear.depth;
// Authored clear colors are sRGB; the linear frame clears in linear light.
const glm::vec3 clearRgb = linear_color_
? srgbToLinearCpu({clear.colorValue.r, clear.colorValue.g, clear.colorValue.b})
: glm::vec3{clear.colorValue.r, clear.colorValue.g, clear.colorValue.b};
pass.clearColorValue[0] = clearRgb.r;
pass.clearColorValue[1] = clearRgb.g;
pass.clearColorValue[2] = clearRgb.b;
pass.clearColorValue[3] = clear.colorValue.a;
scene_clear_ = glm::make_vec4(pass.clearColorValue);
#ifdef ES_ENABLE_POSTPROCESS
// An effect that lays a sky UNDER the scene needs the scene's alpha to be its coverage, which a clear to nothing makes it.
if (usePostProcess && post_process_->sceneCoverageWanted()) {
for (f32& channel : pass.clearColorValue) channel = 0.0f;
}
// A camera that keeps the colour under it still draws into a capture of its own when the frame is linear or has an
// output transform. The capture starts transparent and the present lays it over the camera beneath by coverage, rather
// than replacing that camera's picture with black around a held gun.
if (usePostProcess && !clear.color) {
for (f32& channel : pass.clearColorValue) channel = 0.0f;
post_process_->setPresentOver(true);
}
#endif
pass.clearX = clear.x;
pass.clearY = clear.y;
pass.clearW = clear.w;
pass.clearH = clear.h;
if (usePostProcess) {
#ifdef ES_ENABLE_POSTPROCESS
if (target != RenderTargetManager::INVALID_HANDLE) {
auto* rt = target_manager_.get(target);
if (rt) {
post_process_->setOutputTarget(rt->getFramebuffer());
}
}
// Fresh begin: colors the capture's own load-op clear. When TS already
// began the capture (renderCamera drives pp.begin first) this no-ops.
post_process_->begin(pass.clearColorValue);
// Then BIND it, clear or no clear: this is where the frame gets its target
// back after the shadow pass drew through one of its own. Skipping it for
// a camera with nothing to clear left the atlas current — a black frame.
pass.target = post_process_->currentSceneFBO();
device_.beginRenderPass(pass);
#endif
} else if (target != RenderTargetManager::INVALID_HANDLE) {
auto* rt = target_manager_.get(target);
if (rt) {
pass.target = rt->getFramebuffer();
device_.beginRenderPass(pass);
}
} else {
// The scene may be rendering into the TS screen-capture FBO (screen post
// stack without a per-camera stack): the clear must land on that surface —
// blind-rebinding the default target here would break the capture.
#ifdef ES_ENABLE_POSTPROCESS
if (post_process_) pass.target = post_process_->currentSceneFBO();
#endif
device_.beginRenderPass(pass);
}
// What the scene pass will draw into. Bound already, because a host draw
// between this call and the graph's run (the editor's grid) has to land in
// the scene; the pass re-opens it with a load, so that work survives.
scene_fbo_ = pass.target;
}
// What a finalized list cost, added to the frame's tally. Accumulated rather
// than assigned because a frame reports more than one list: the scene's, and the
// screen overlay's after every camera.
void RenderFrame::accumulateStats(const DrawList& list) {
stats_.draw_calls += list.mergedDrawCallCount();
for (u32 i = 0; i < list.commandCount(); ++i) {
const auto& cmd = list.command(i);
// An instanced command holds ONE copy of the geometry and draws it
// instance_count times; a batched one merged its indices in already. The
// multiply is what stops the number meaning two things on the two paths.
stats_.triangles += (cmd.index_count / 3) * (cmd.instance_count ? cmd.instance_count : 1);
}
stats_.sprites += list.sourceEntityCount(RenderType::Sprite) + list.sourceEntityCount(RenderType::UIElement);
stats_.text += list.sourceEntityCount(RenderType::Text);
stats_.meshes += list.sourceEntityCount(RenderType::Mesh) + list.sourceEntityCount(RenderType::ExternalMesh)
+ list.sourceEntityCount(RenderType::Trail);
#ifdef ES_ENABLE_PARTICLES
stats_.particles += list.sourceEntityCount(RenderType::Particle);
#endif
stats_.shapes += list.sourceEntityCount(RenderType::Shape);
stats_.skeletal += list.sourceEntityCount(RenderType::Skeletal);
}
void RenderFrame::flush() {
if (!in_frame_ || flushed_) return;
flushed_ = true;
// The device can still die between begin() and here — a GL error check, a
// spontaneous WebGPU callback. Marked flushed above first, so end() does not
// come back for a second attempt at a frame that has nowhere to go.
if (!device_.isDeviceUsable()) return;
// Drop any pipeline a prior phase left bound, so the first draw re-applies its state.
device_.invalidatePipelineCache();
// finalize() sorts + coalesces and rewrites per-vertex texIndex into the staging, so it
// must run before upload() ships that staging to the GPU. Both stay here rather
// than riding the pass: the counters below read what finalize decided, and the
// host asks for them before the graph has run.
{
ES_PROFILE_SCOPE("render.finalize");
// Around the CALLS, which are synchronous: what the device does with an
// upload afterwards is its own clock and cannot be read off this one.
{
ES_PROFILE_SCOPE("render.finalize.drawList");
// Before the merge, which spends texture slots: a mask needs a top one and
// does not exist yet. The shape mask sits below the shadow one, so a frame
// with a shape keeps both whether anything casts or not.
draw_list_.reserveMask2DSlots(
(shape_2d_resource_ != rg::kNoResource || shadow_2d_masks_[1].resource != rg::kNoResource) ? 2u
: (shadow_2d_masks_[0].resource != rg::kNoResource ? 1u : 0u));
draw_list_.finalize(pool_);
}
{
ES_PROFILE_SCOPE("render.finalize.upload");
pool_.upload();
}
}
accumulateStats(draw_list_);
// What the frame's render targets cost. The atlas and every chain
// intermediate come out of one pool, so one number answers for all of them —
// and a pool that stopped giving targets back is visible in no pixel.
tallyPass(draw_list_);
}
void RenderFrame::endFrame() {
frame_capture_.endFrame();
device_.endFrame();
stats_.gpu_draws = device_.takeDraws();
publishFrameCounters();
// Once per frame and not per camera: a commit at each camera's end kept only
// the last camera's scopes and counters.
FrameProfiler::get().commit();
}
// What one real pass's merge decided, added to the frame's tally. A preview
// surface finalizes a list too, and is not part of the frame.
void RenderFrame::tallyPass(const DrawList& list) {
frame_merged_ += list.mergedAwayCount();
for (u32 r = 1; r < static_cast<u32>(BatchBreak::Count); ++r) {
frame_breaks_[r] += list.breakCount(static_cast<BatchBreak>(r));
}
}
void RenderFrame::publishFrameCounters() {
if (!FrameProfiler::get().enabled()) return;
ES_PROFILE_COUNTER("batch.draws", stats_.draw_calls);
ES_PROFILE_COUNTER("render.gpu.draws", stats_.gpu_draws);
ES_PROFILE_COUNTER("batch.merged", frame_merged_);
// Every material bake drawn since the renderer started: a check that a baked surface was drawn at all, which no pixel of a correct
// one tells from the same surface drawn live.
ES_PROFILE_COUNTER("render.bakes.drawn", material_bakes_drawn_);
// Emitted per reason and only where it happened, so a clean frame publishes
// nothing rather than a wall of zeroes for a caller to read past.
for (u32 r = 1; r < static_cast<u32>(BatchBreak::Count); ++r) {
if (frame_breaks_[r] == 0) continue;
FrameProfiler::get().counter(batchBreakCounter(static_cast<BatchBreak>(r)), frame_breaks_[r]);
}
// The shadow atlas is the frame's own and kept, not pooled, and counted with the pool it used to come from: a colour and a
// depth texel per atlas texel, four bytes each, as the pool counts its own.
const u64 atlasSide = shadow_target_ ? shadow_target_->getWidth() : 0u;
ES_PROFILE_COUNTER("render.targets", target_pool_.count() + (shadow_target_ ? 1u : 0u));
ES_PROFILE_COUNTER("render.targets.bytes", target_pool_.bytes() + atlasSide * atlasSide * 8u);
// Memory on the other side: pixels and buffers the device copies so they
// survive a loss, which no GPU figure counts.
ES_PROFILE_COUNTER("render.retained.bytes", device_.retainedBytes());
ES_PROFILE_COUNTER("render.culled", stats_.culled);
// Which question did the culling, and how much was declared to do it with. A
// scene whose occluders stopped being taken — turned past the near plane, or
// authored to nothing — reads zero boxes here while render.culled says nothing.
ES_PROFILE_COUNTER("render.cull.occluded", stats_.occluded);
ES_PROFILE_COUNTER("render.cull.occluders", occlusion_.boxes());
ES_PROFILE_COUNTER("render.reflection.probes", context_.reflections().count());
ES_PROFILE_COUNTER("render.sprites", stats_.sprites);
// Light slots the lit quads were spared: a light out of reach added nothing before either, so no pixel says whether it is skipped.
ES_PROFILE_COUNTER("render.lights2d.spared", stats_.lightsSpared);
// The same for what has no quads of its own to say it (a tilemap's strips): how many (screen tile, loop light) pairs are left set.
ES_PROFILE_COUNTER("render.lights2d.tileBits", context_.lights().loopTileBits());
// The 3D path had no counter at all, and its cost is the one a pixel hides
// best: identical geometry drawn N times merges into ONE instanced call, so
// batch.draws does not move when a cull stops working. These two do.
ES_PROFILE_COUNTER("render.meshes", stats_.meshes);
ES_PROFILE_COUNTER("render.triangles", stats_.triangles);
ES_PROFILE_COUNTER("render.text", stats_.text);
ES_PROFILE_COUNTER("render.lod.groups", lod_counts_.selections);
ES_PROFILE_COUNTER("render.lod.level0", lod_counts_.level[0]);
ES_PROFILE_COUNTER("render.lod.level1", lod_counts_.level[1]);
ES_PROFILE_COUNTER("render.lod.level2", lod_counts_.level[2]);
ES_PROFILE_COUNTER("render.lod.level3", lod_counts_.level[3]);
ES_PROFILE_COUNTER("render.lod.culled", lod_counts_.culled);
ES_PROFILE_COUNTER("render.shapes", stats_.shapes);
#ifdef ES_ENABLE_PARTICLES
ES_PROFILE_COUNTER("render.particles", stats_.particles);
// What the compute-simulated emitters asked of the GPU: a scene whose emitters fell back to the CPU reads zero here.
#ifdef ES_ENABLE_GPU_PARTICLES
ES_PROFILE_COUNTER("render.particles.gpuSlots", gpu_particles_ ? gpu_particles_->drawnSlots() : 0u);
#endif
#endif
}
void RenderFrame::end() {
if (!in_frame_) return;
if (!flushed_) {
flush();
}
#ifdef ES_ENABLE_POSTPROCESS
const bool usePostProcess = post_process_ && post_process_->isEngaged();
#else
const bool usePostProcess = false;
#endif
// Everything this camera draws, declared in one place and run once. The
// scene is a pass like the effects that read it: the graph binds its target,
// sets the camera's rect and calls drawScene.
if (scene_resource_ != rg::kNoResource) {
rg::PassDesc scene;
scene.name = "scene";
scene.write = scene_resource_;
scene.viewportX = static_cast<u32>(std::max(scene_viewport_.x, 0));
scene.viewportY = static_cast<u32>(std::max(scene_viewport_.y, 0));
scene.viewportW = scene_viewport_.w;
scene.viewportH = scene_viewport_.h;
// Named, not read: every draw that receives a shadow carries the atlas in
// its own key, so the graph owes the scene ordering and lifetime but must
// not spend a texture unit on it.
if (shadow_resource_ != rg::kNoResource) {
scene.dependencies.push_back(shadow_resource_);
}
// The same terms for the 2D mask: every Lit draw samples it through a pinned
// unit, so the graph owes the scene its ordering and its lifetime, not a bind.
if (shape_2d_resource_ != rg::kNoResource) {
scene.dependencies.push_back(shape_2d_resource_);
}
for (const Shadow2DMask& mask : shadow_2d_masks_) {
if (mask.resource != rg::kNoResource) scene.dependencies.push_back(mask.resource);
}
if (planar_resource_ != rg::kNoResource) scene.dependencies.push_back(planar_resource_);
#ifdef ES_ENABLE_GPU_PARTICLES
// The particles a kernel advances this frame are drawn by the scene, so it runs first.
if (gpu_particles_) {
const rg::ResourceId simulated = gpu_particles_->declare(graph_);
if (simulated != rg::kNoResource) scene.dependencies.push_back(simulated);
}
#endif
// A surface that refracts has to see what stands behind it, and what stands behind it is the opaque scene: the pass is
// drawn in two, with a copy of the picture taken between. Only where the scene is a texture a pass can read (a chain is
// engaged) and a draw in the list asks for the copy.
bool glass = false;
#ifdef ES_ENABLE_POSTPROCESS
glass = usePostProcess && draw_list_.anyUsesSceneColor(context_.materials());
#endif
// A blended surface (a pane, a particle, a leaf card) writes no depth, so drawn before the water it is covered by it wherever the water is in
// front of the pixel's opaque, whichever side of the surface it is on. So where there are any, the scene is built in layers: the opaque
// scene, then the blended draws over it (the picture the water refracts, so what is under the surface is seen through it), then the opaque
// scene put back and the water drawn, and last the blended draws once more, depth-tested against the water now: those in front of the
// surface land on it, those behind it fail and are only seen through it. The pixels the water does not cover were put back, so they are blended once.
bool layered = false;
#ifdef ES_ENABLE_POSTPROCESS
layered = glass && draw_list_.anyBlendedWithoutSceneColor(context_.materials());
#endif
rg::PassDesc glassPass;
rg::PassDesc blendedPass, overPass;
rg::ResourceId grabOpaque = rg::kNoResource;
rg::ResourceId grab = rg::kNoResource;
rg::ResourceId grabDepth = rg::kNoResource;
if (glass) {
#ifdef ES_ENABLE_POSTPROCESS
grab = graph_.createTarget(post_process_->grabTarget());
if (layered) grabOpaque = graph_.createTarget(post_process_->grabTarget());
// The distance to what stands behind, for a surface that measures the water in front of it: only when one asks, and
// only where a float target can hold distances.
if (draw_list_.anyUsesSceneDepth(context_.materials()) && post_process_->canGrabDepth()) {
grabDepth = graph_.createTarget(post_process_->grabDepthTarget());
}
glassPass = scene;
glassPass.name = "scene-glass";
glassPass.dependencies.push_back(grab);
if (grabDepth != rg::kNoResource) glassPass.dependencies.push_back(grabDepth);
if (layered) {
blendedPass = scene;
blendedPass.name = "scene-blended";
blendedPass.dependencies.push_back(grabOpaque);
if (grabDepth != rg::kNoResource) blendedPass.dependencies.push_back(grabDepth);
blendedPass.execute = [this](const rg::PassContext&) { drawScene(DrawList::Phase::BlendedOnly); };
overPass = scene;
overPass.name = "scene-blended-over";
overPass.dependencies.push_back(grab);
overPass.execute = [this](const rg::PassContext&) {
drawScene(DrawList::Phase::BlendedOnly);
if (presented_overlay_draw_) presented_overlay_draw_->flushDeferred();
};
}
glassPass.execute = [this, grab, grabDepth, layered](const rg::PassContext&) {
context_.materials().setSceneColor(graph_.textureOf(grab));
if (grabDepth != rg::kNoResource) context_.materials().setSceneDepth(graph_.textureOf(grabDepth));
drawScene(DrawList::Phase::SceneColorOnly);
context_.materials().setSceneColor(TextureHandle::Invalid);
context_.materials().setSceneDepth(TextureHandle::Invalid);
if (!layered && presented_overlay_draw_) presented_overlay_draw_->flushDeferred();
};
#endif
}
// With no chain to take the scene from, water and glass draw in the one pass, and the order the list sorts blended draws in (by
// where each object stands) put a water surface after every pane in front of it: the surface follows the camera, so it stands
// nearest of all. Ordered by the pixel instead, as the layers above do without the copies: the opaque scene, then the water, which
// writes depth, then the blended draws, depth-tested against it. Those in front of the surface land on it, those under it are hidden.
const bool ordered = !glass && draw_list_.anyUsesSceneColor(context_.materials())
&& draw_list_.anyBlendedWithoutSceneColor(context_.materials());
scene.execute = [this, glass, layered, ordered](const rg::PassContext&) {
if (ordered) {
drawScene(DrawList::Phase::OpaqueOnly);
drawScene(DrawList::Phase::SceneColorOnly);
drawScene(DrawList::Phase::BlendedOnly);
} else {
drawScene(layered ? DrawList::Phase::OpaqueOnly : glass ? DrawList::Phase::WithoutSceneColor : DrawList::Phase::All);
}
if (!glass && presented_overlay_draw_) presented_overlay_draw_->flushDeferred();
};
graph_.addPass(std::move(scene));
#ifdef ES_ENABLE_GPU_PARTICLES
if (gpu_particles_) {
gpu_particles_->declareDepthCopy(graph_, scene_resource_, width_, height_, toClipDepthRange(view_projection_, device_.clipDepthRange()));
}
#endif
if (glass) {
#ifdef ES_ENABLE_POSTPROCESS
rg::PassDesc copy;
copy.name = "scene-grab";
copy.reads = {scene_resource_};
copy.write = layered ? grabOpaque : grab;
// Layered, this copy is only ever put back (scene-restore): kept exact, alpha and all. Otherwise the water reads it, marked.
copy.execute = [this, layered](const rg::PassContext&) { post_process_->grabScene(/*marked=*/!layered); };
graph_.addPass(std::move(copy));
if (grabDepth != rg::kNoResource) {
rg::PassDesc copyDepth;
copyDepth.name = "scene-grab-depth";
copyDepth.reads = {scene_resource_};
copyDepth.write = grabDepth;
copyDepth.execute = [this](const rg::PassContext&) { post_process_->grabDepth(); };
graph_.addPass(std::move(copyDepth));
}
if (layered) {
graph_.addPass(std::move(blendedPass));
rg::PassDesc copyBlended;
copyBlended.name = "scene-grab-blended";
copyBlended.reads = {scene_resource_};
copyBlended.write = grab;
copyBlended.execute = [this](const rg::PassContext&) { post_process_->grabScene(); };
graph_.addPass(std::move(copyBlended));
// The opaque scene put back: what the blended draws left in the pixels is theirs to leave again, in the pass after the water.
rg::PassDesc restore;
restore.name = "scene-restore";
restore.reads = {grabOpaque};
restore.write = scene_resource_;
// Exact: the scene's alpha is how much of each pixel geometry covers, which the sky reads. Restored through the marked
// copy, every pixel came back half covered and the sky showed through every wall, wherever water and a pane were both in view.
restore.execute = [this](const rg::PassContext&) { post_process_->grabScene(/*marked=*/false); };
graph_.addPass(std::move(restore));
}
#endif
graph_.addPass(std::move(glassPass));
if (layered) graph_.addPass(std::move(overPass));
}
}
#ifdef ES_ENABLE_POSTPROCESS
// What the scene drew, drawn again for how far each moving surface travelled: a temporal pass in the
// chain reads it, and nothing else does, so a frame whose meshes all stood still declares nothing.
if (usePostProcess && scene_resource_ != rg::kNoResource && velocity_list_.commandCount() > 0) {
const rg::ResourceId velocity = post_process_->declareVelocity();
if (velocity != rg::kNoResource) {
rg::PassDesc motion;
motion.name = "motion";
motion.write = velocity;
motion.clear = true;
motion.clearDepth = true;
// Nothing written is alpha 0: a reader treats it as "the camera's motion, not an object's".
motion.clearColor[0] = motion.clearColor[1] = motion.clearColor[2] = motion.clearColor[3] = 0.0f;
motion.execute = [this](const rg::PassContext&) { executeMotionPass(); };
graph_.addPass(std::move(motion));
}
}
#endif
#ifdef ES_ENABLE_POSTPROCESS
// What stands over each place, for an effect that keeps rain off what is sheltered.
if (usePostProcess && scene_resource_ != rg::kNoResource && cover_list_.commandCount() > 0) {
const rg::ResourceId cover = post_process_->declareCover(1024);
if (cover != rg::kNoResource) {
post_process_->setCoverMatrix(cover_view_projection_);
rg::PassDesc pass;
pass.name = "rain-cover";
pass.write = cover;
pass.clear = true;
pass.clearDepth = true;
// White is depth 1: nothing above.
pass.clearColor[0] = pass.clearColor[1] = pass.clearColor[2] = pass.clearColor[3] = 1.0f;
pass.execute = [this](const rg::PassContext&) { executeCoverPass(); };
graph_.addPass(std::move(pass));
}
}
#endif
if (usePostProcess) {
#ifdef ES_ENABLE_POSTPROCESS
post_process_->setShadowAtlas(shadow_texture_id_, shadow_resource_);
post_process_->declareChain();
#endif
}
{
ES_PROFILE_SCOPE("render.graph");
// With the profiler on, each pass is timed and the graph is their sum; otherwise one query spans the graph.
rg::PassTimer* passTimer = nullptr;
if (FrameProfiler::get().enabled()) {
if (!pass_timer_) pass_timer_ = makeUnique<rg::PassTimer>(device_);
if (pass_timer_->available()) passTimer = pass_timer_.get();
}
if (passTimer) {
passTimer->beginFrame();
graph_.setPassTimer(passTimer);
running_pass_timer_ = passTimer;
graph_.execute();
running_pass_timer_ = nullptr;
graph_.setPassTimer(nullptr);
passTimer->endFrame();
// The scope names are the passes' own, under pass/ so they cannot meet a scope of another kind.
for (const auto& e : passTimer->last()) {
pass_scope_names_.try_emplace(e.name, std::string("pass/") + e.name);
FrameProfiler::get().gpuScope(pass_scope_names_[e.name].c_str(), e.ms);
}
if (passTimer->lastTotalMs() >= 0.0f) {
pass_graph_ms_ = passTimer->lastTotalMs();
FrameProfiler::get().gpuScope("graph", pass_graph_ms_);
}
} else {
gpu_timer_.poll(device_);
gpu_timer_.begin(device_);
graph_.execute();
gpu_timer_.end(device_);
pass_graph_ms_ = -1.0f;
FrameProfiler::get().gpuScope("graph", gpu_timer_.lastMs());
}
}
#ifdef ES_ENABLE_GPU_PARTICLES
// After the graph, which is where the kernels run: a frame that dispatched none (its emitters fell back to the CPU, or
// nothing moved) says so.
ES_PROFILE_COUNTER("render.particles.gpuDispatches", gpu_particles_ ? gpu_particles_->lastDispatches() : 0u);
#endif
scene_resource_ = rg::kNoResource;
shadow_resource_ = rg::kNoResource;
shadow_views_.clear();
if (usePostProcess) {
#ifdef ES_ENABLE_POSTPROCESS
post_process_->chainDone();
#endif
} else if (current_target_ != RenderTargetManager::INVALID_HANDLE) {
auto* rt = target_manager_.get(current_target_);
if (rt) {
rt->unbind();
}
}
// The graph's own time is the whole frame's — the scene pass runs inside it.
stats_.gpu_time_ms = pass_graph_ms_ >= 0.0f ? pass_graph_ms_ : gpu_timer_.lastMs();
// The frame's pass closes HERE, not at the next begin: a WebGPU backend
// submits on endRenderPass, and a surface texture acquired this task must
// not ride into the next one (the swapchain recycles it at task end). On
// GL this is just the default-framebuffer rebind.
device_.endRenderPass();
if (current_target_ != RenderTargetManager::INVALID_HANDLE) {
if (auto* rt = target_manager_.get(current_target_)) rt->publish();
}
runPendingReplay(view_projection_, scene_viewport_.w, scene_viewport_.h);
in_frame_ = false;
flushed_ = false;
}
void RenderFrame::replayToDrawCall(i32 drawIndex) {
if (drawIndex < 0 || static_cast<u32>(drawIndex) >= frame_capture_.getRecordCount()) return;
const DrawCallRecord* records = frame_capture_.getRecords();
const u32 pass = records[drawIndex].pass;
i32 local = 0;
for (i32 i = 0; i < drawIndex; ++i) {
if (records[i].pass == pass) ++local;
}
replay_pass_ = static_cast<i32>(pass);
replay_draw_ = local;
if (snapshot_readback_ != ReadbackHandle::Invalid) device_.discardReadback(snapshot_readback_);
snapshot_readback_ = ReadbackHandle::Invalid;
snapshot_pixels_.clear();
}
void RenderFrame::runPendingReplay(const glm::mat4& projection, u32 w, u32 h) {
if (replay_draw_ < 0 || frame_capture_.currentPass() != replay_pass_) return;
const i32 stopAt = replay_draw_;
replay_pass_ = -1;
replay_draw_ = -1;
if (w == 0 || h == 0) {
w = width_;
h = height_;
}
snapshot_matches_ = draw_list_.mergedDrawCallCount()
== frame_capture_.recordsInPass(frame_capture_.currentPass());
// With depth and stencil: a replayed 3D draw tests against the draws before
// it, and a UI mask writes the stencil the draws after it read.
if (replay_rt_ == 0) {
replay_rt_ = target_manager_.create(w, h, /*depth=*/true, /*linearFilter=*/false);
} else if (auto* existing = target_manager_.get(replay_rt_);
existing && (existing->getWidth() != w || existing->getHeight() != h)) {
existing->resize(w, h);
}
auto* rt = target_manager_.get(replay_rt_);
if (!rt) return;
RenderPassDesc replayPass{rt->getFramebuffer(), /*clearColor=*/true};
replayPass.clearDepth = true;
replayPass.clearStencil = true;
replayPass.clearColorValue[3] = 0.0f;
device_.beginRenderPass(replayPass);
device_.setViewport(0, 0, w, h);
frame_capture_.setReplayMode(stopAt + 1);
context_.updateCameraConstants(projection);
context_.lights().uploadAndBind();
draw_list_.execute(device_, pool_, context_.materials(), context_.getWhiteTextureId(),
&frame_capture_, context_.perDrawBlocks());
frame_capture_.clearReplayMode();
device_.setScissorTest(false);
device_.invalidatePipelineCache();
device_.endRenderPass();
snapshot_w_ = w;
snapshot_h_ = h;
snapshot_pixels_.clear();
snapshot_readback_ = device_.requestReadback(rt->getFramebuffer(), w, h);
}
void RenderFrame::renderToTarget(ecs::Registry& registry, const glm::mat4& viewProjection, u32 w, u32 h) {
renderSurface(registry, viewProjection, preview_, w, h, {});
}
void RenderFrame::renderSurface(ecs::Registry& registry, const glm::mat4& viewProjection,
PreviewSurface& surface, u32 w, u32 h,
std::span<const PendingSkeletalBatch> extraSkeletalBatches) {
if (w == 0 || h == 0) return;
if (!device_.isDeviceUsable()) return;
if (surface.target == 0) {
surface.target = target_manager_.create(w, h, /*depth=*/true, /*linearFilter=*/false);
} else if (auto* existing = target_manager_.get(surface.target);
existing && (existing->getWidth() != w || existing->getHeight() != h)) {
existing->resize(w, h);
}
auto* rt = target_manager_.get(surface.target);
if (!rt) return;
RenderPassDesc previewPass{rt->getFramebuffer(), /*clearColor=*/true};
previewPass.clearDepth = true; // a mesh drawn here needs its near faces to win
previewPass.clearStencil = true;
previewPass.clearColorValue[3] = 0.0f; // transparent black
device_.beginRenderPass(previewPass);
device_.setViewport(0, 0, w, h);
// A self-contained collect (begin()'s setup minus post-process) + execute (flush()'s body),
// drawn to the bound preview target. Reuses the real collect+material+execute path so a
// preview is pixel-identical to the viewport.
view_projection_ = viewProjection;
frustum_.extractFromMatrix(viewProjection);
view_id_ = kPreviewViewId;
current_stage_ = RenderStage::Transparent;
pool_.beginFrame();
draw_list_.clear();
clip_state_.clear();
// A preview target is a plain one, whatever the camera's chain is doing.
collectAll(registry, /*sceneGBuffer=*/false);
// AFTER the collect, because the clear above would have eaten them. Geometry
// a caller posed itself and handed over, replayed through the one skeletal
// path a scene's batches take.
for (const auto& batch : extraSkeletalBatches) {
submitSkeletalBatch(batch.vertices.data(), static_cast<i32>(batch.vertices.size() / 8),
batch.indices.data(), static_cast<i32>(batch.indices.size()),
batch.textureId, batch.blendMode, &batch.transform[0][0],
batch.entity, batch.layer, batch.depth, batch.materialId, batch.premultipliedColor);
}
draw_list_.finalize(pool_);
pool_.upload();
context_.updateCameraConstants(viewProjection);
context_.lights().uploadAndBind();
draw_list_.execute(device_, pool_, context_.materials(), context_.getWhiteTextureId(),
nullptr, context_.perDrawBlocks());
rt->unbind();
device_.invalidatePipelineCache();
// Async readback seam (same shape as the replay snapshot above).
if (surface.readback != ReadbackHandle::Invalid) device_.discardReadback(surface.readback);
surface.width = w;
surface.height = h;
surface.pixels.clear();
surface.readback = device_.requestReadback(rt->getFramebuffer(), w, h);
}
i32 RenderFrame::pollSnapshotReadback() {
if (replay_draw_ >= 0) return 0;
return pollReadback(snapshot_readback_, snapshot_pixels_, snapshot_w_, snapshot_h_);
}
RenderFrame::SkeletalPreview* RenderFrame::skeletalPreview(SkeletalPreviewId id) {
auto it = skeletal_previews_.find(id);
return it == skeletal_previews_.end() ? nullptr : it->second.get();
}
const RenderFrame::SkeletalPreview* RenderFrame::skeletalPreview(SkeletalPreviewId id) const {
auto it = skeletal_previews_.find(id);
return it == skeletal_previews_.end() ? nullptr : it->second.get();
}
RenderFrame::SkeletalPreviewId RenderFrame::createSkeletalPreview(u32 w, u32 h) {
if (w == 0 || h == 0) return 0;
auto preview = std::make_unique<SkeletalPreview>();
// Its own one-entity scene. The transform is identity and stays that way:
// where a preview stands is the preview camera's business, and a batch
// arrives with its own model matrix.
preview->entity = preview->registry.create();
preview->registry.emplace<ecs::Transform>(preview->entity);
preview->surface.width = w;
preview->surface.height = h;
const SkeletalPreviewId id = next_skeletal_preview_++;
skeletal_previews_.emplace(id, std::move(preview));
return id;
}
bool RenderFrame::submitSkeletalPreviewBatch(
SkeletalPreviewId id,
const f32* vertices, i32 vertexCount,
const u16* indices, i32 indexCount,
u32 textureId, i32 blendMode, const f32* transform16,
i32 layer, f32 depth, u32 materialId, bool premultipliedColor
) {
auto* preview = skeletalPreview(id);
if (!preview || !vertices || !indices || vertexCount < 0 || indexCount < 0) return false;
PendingSkeletalBatch batch;
// COPIED, not referenced: this sits until the next render call, and the
// caller's scratch is gone the moment it returns.
batch.vertices.assign(vertices, vertices + static_cast<usize>(vertexCount) * 8);
batch.indices.assign(indices, indices + static_cast<usize>(indexCount));
batch.textureId = textureId;
batch.blendMode = blendMode;
batch.premultipliedColor = premultipliedColor;
if (transform16) std::memcpy(&batch.transform[0][0], transform16, sizeof(f32) * 16);
batch.entity = preview->entity;
batch.layer = layer;
batch.depth = depth;
batch.materialId = materialId;
preview->pending.push_back(std::move(batch));
return true;
}
bool RenderFrame::renderSkeletalPreview(SkeletalPreviewId id, const glm::mat4& viewProjection) {
auto* preview = skeletalPreview(id);
if (!preview) return false;
// One in flight per preview. A second render would land two images for one
// camera and leave a caller no way to say which its overlay belongs to.
if (preview->surface.readback != ReadbackHandle::Invalid) return false;
// Taken before the draw: a render that throws or bails must not leave last
// frame's geometry to be drawn again on top of the next one.
const auto batches = std::exchange(preview->pending, {});
renderSurface(preview->registry, viewProjection, preview->surface,
preview->surface.width, preview->surface.height, batches);
return true;
}
i32 RenderFrame::pollSkeletalPreview(SkeletalPreviewId id) {
auto* preview = skeletalPreview(id);
if (!preview) return 2;
return pollReadback(preview->surface.readback, preview->surface.pixels,
preview->surface.width, preview->surface.height);
}
const u8* RenderFrame::skeletalPreviewPixels(SkeletalPreviewId id) const {
const auto* preview = skeletalPreview(id);
return preview ? preview->surface.pixels.data() : nullptr;
}
u32 RenderFrame::skeletalPreviewSize(SkeletalPreviewId id) const {
const auto* preview = skeletalPreview(id);
return preview ? static_cast<u32>(preview->surface.pixels.size()) : 0;
}
u32 RenderFrame::skeletalPreviewWidth(SkeletalPreviewId id) const {
const auto* preview = skeletalPreview(id);
return preview ? preview->surface.width : 0;
}
u32 RenderFrame::skeletalPreviewHeight(SkeletalPreviewId id) const {
const auto* preview = skeletalPreview(id);
return preview ? preview->surface.height : 0;
}
void RenderFrame::destroySkeletalPreview(SkeletalPreviewId id) {
auto it = skeletal_previews_.find(id);
if (it == skeletal_previews_.end()) return;
// Logical ownership ends now; the device's outstanding work is handed back
// the same way every other readback is, so nothing lands in freed pixels.
auto& surface = it->second->surface;
if (surface.readback != ReadbackHandle::Invalid) {
device_.discardReadback(surface.readback);
surface.readback = ReadbackHandle::Invalid;
}
if (surface.target != 0) target_manager_.release(surface.target);
skeletal_previews_.erase(it);
}
i32 RenderFrame::pollPreviewReadback() {
return pollReadback(preview_.readback, preview_.pixels, preview_.width, preview_.height);
}
i32 RenderFrame::pollReadback(ReadbackHandle& handle, std::vector<u8>& pixels, u32 w, u32 h) {
if (handle == ReadbackHandle::Invalid) {
// No readback in flight: the last landed pixels (if any) stay available.
return pixels.empty() ? 2 : 1;
}
switch (device_.pollReadback(handle)) {
case GfxReadbackStatus::Pending:
return 0;
case GfxReadbackStatus::Ready: {
pixels.resize(static_cast<usize>(w) * h * 4);
const bool ok = device_.takeReadback(handle, pixels.data(), pixels.size());
handle = ReadbackHandle::Invalid;
if (!ok) pixels.clear();
return ok ? 1 : 2;
}
case GfxReadbackStatus::Failed:
default:
handle = ReadbackHandle::Invalid;
pixels.clear();
return 2;
}
}
void RenderFrame::setEntityClipRect(u32 entity, i32 x, i32 y, i32 w, i32 h) {
clip_rects_[entity] = ScissorRect{x, y, w, h};
}
void RenderFrame::clearAllClipRects() {
clip_rects_.clear();
}
void RenderFrame::setEntityStencilMask(u32 entity, i32 refValue, bool hierarchical) {
stencil_masks_[entity] = {refValue, true, hierarchical};
}
void RenderFrame::setEntityStencilTest(u32 entity, i32 refValue, bool hierarchical) {
stencil_masks_[entity] = {refValue, false, hierarchical};
}
void RenderFrame::clearAllStencilMasks() {
stencil_masks_.clear();
}
// ─── Mask Processing ── see RenderFrameMask.cpp ─────────────────────────────
// ─── Tile/Spine Submit ── see RenderFrameSubmit.cpp ──────────────────────────
// ============================================================================
// Plugin Pipeline
// ============================================================================
void RenderFrame::addPlugin(std::unique_ptr<RenderTypePlugin> plugin) {
plugins_.push_back(std::move(plugin));
}
void RenderFrame::buildClipState() {
clip_state_.clear();
for (const auto& [entity, rect] : clip_rects_) {
clip_state_.setScissor(entity, rect.x, rect.y, rect.w, rect.h);
}
for (const auto& [entity, info] : stencil_masks_) {
if (info.hierarchical) {
if (info.is_mask) clip_state_.setUIStencilMask(entity, info.ref_value);
else clip_state_.setUIStencilTest(entity, info.ref_value);
continue;
}
if (info.is_mask) {
clip_state_.setStencilMask(entity, info.ref_value);
} else {
clip_state_.setStencilTest(entity, info.ref_value);
}
}
}
namespace {
/**
* @brief Hands one group's identity to a subtree, stopping the descent at nothing.
*
* @details An inner group does not start a new identity — a weapon rigged under an arm
* would drift out of its character. It becomes a BLOCK in the outer one:
* everything below shares the inner group's order.
*/
void assignSortingSubtree(ecs::Registry& registry, DrawList& list, Entity entity,
DrawList::GroupIdentity identity) {
list.setSortingGroup(entity.id(), identity);
if (!registry.has<ecs::Children>(entity)) return;
for (auto child : registry.get<ecs::Children>(entity).entities) {
DrawList::GroupIdentity childIdentity = identity;
// The FIRST nesting decides the block; deeper ones join it. A grandchild group
// restating it would interleave its contents with a sibling of its own block.
if (!childIdentity.blockOrder && registry.has<ecs::SortingGroup>(child)) {
const auto& inner = registry.get<ecs::SortingGroup>(child);
if (inner.enabled) {
childIdentity.blockOrder = true;
childIdentity.block = inner.order;
}
}
assignSortingSubtree(registry, list, child, childIdentity);
}
}
/// Whether some ENABLED group already encloses @p entity, making it a member rather
/// than a root. A disabled group is not a group, so it does not enclose anything.
bool hasEnclosingGroup(ecs::Registry& registry, Entity entity) {
Entity current = entity;
while (registry.has<ecs::Parent>(current)) {
Entity parent = registry.get<ecs::Parent>(current).entity;
if (parent == INVALID_ENTITY) break;
if (registry.has<ecs::SortingGroup>(parent) &&
registry.get<ecs::SortingGroup>(parent).enabled) {
return true;
}
current = parent;
}
return false;
}
} // namespace
void RenderFrame::buildSortingGroups(ecs::Registry& registry) {
draw_list_.clearSortingGroups();
auto groups = registry.activeView<ecs::SortingGroup>();
for (auto entity : groups) {
const auto& group = groups.get(entity);
if (!group.enabled) continue;
// Only the OUTERMOST group seeds an identity; the walk below reaches the inner
// ones as blocks. Seeding from an inner group too would overwrite what the outer
// one just wrote, and which of the two won would be view iteration order.
if (hasEnclosingGroup(registry, entity)) continue;
assignSortingSubtree(registry, draw_list_, entity,
{group.layer, group.order, false, 0});
}
}
void RenderFrame::buildTreeSequence(ecs::Registry& registry) {
if (draw_list_.treeMask() == 0) {
draw_list_.clearTreeSequence();
return;
}
// One preorder walk over every tree of the world: a root is an entity with no live parent, taken in storage order (which is the painter's
// order of roots), and its children follow in their list order. The same order a scene's nodes stack in.
std::vector<u32> sequence;
u32 counter = 1;
std::vector<Entity> pending;
auto walk = [&](Entity root) {
pending.push_back(root);
while (!pending.empty()) {
const Entity entity = pending.back();
pending.pop_back();
if (!registry.valid(entity)) continue;
const u32 index = entity.index();
if (index >= sequence.size()) sequence.resize(index + 1, 0u);
sequence[index] = counter++;
const auto* children = registry.tryGet<ecs::Children>(entity);
if (!children) continue;
for (auto child = children->entities.rbegin(); child != children->entities.rend(); ++child) pending.push_back(*child);
}
};
auto transforms = registry.view<ecs::Transform>();
for (auto entity : transforms) {
const auto* parent = registry.tryGet<ecs::Parent>(entity);
if (parent && parent->entity != INVALID_ENTITY && registry.valid(parent->entity)) continue;
walk(entity);
}
draw_list_.setTreeSequence(std::move(sequence));
}
void RenderFrame::buildSpriteMasks(ecs::Registry& registry) {
// 255 is the stencil attachment's, not a budget: refs are per FRAME and a mask past
// the last one is dropped rather than aliased onto another mask's cut.
static constexpr i32 MAX_MASK_REF = 255;
std::vector<ResolvedMask>& masks = sprite_mask_scratch_;
masks.clear();
auto maskView = registry.activeView<ecs::SpriteMask>();
for (auto entity : maskView) {
const auto& mask = maskView.get(entity);
if (!mask.enabled) continue;
// The mask IS its sprite, so a sprite that will not be drawn cuts nothing. Without
// this, hiding a mask makes everything it reached disappear instead of appear.
if (!registry.has<ecs::Sprite>(entity)) continue;
const auto& sprite = registry.get<ecs::Sprite>(entity);
if (!sprite.enabled) continue;
masks.push_back({
draw_list_.sortIdentity(entity.id(), sprite.layer, sprite.order),
{mask.rangeEndLayer, mask.rangeEndOrder},
mask.limitRange,
0,
});
mask_entities_scratch_.push_back(entity);
}
if (masks.empty()) { mask_entities_scratch_.clear(); return; }
// Refs run in DRAW order so a later mask overwrites an earlier one where they overlap,
// which is what the stencil does anyway — assigning them in view order would make which
// mask wins depend on entity creation.
std::vector<u32> byDraw(masks.size());
for (u32 i = 0; i < masks.size(); ++i) byDraw[i] = i;
std::sort(byDraw.begin(), byDraw.end(),
[&](u32 a, u32 b) { return masks[a].at < masks[b].at; });
i32 nextRef = 1;
for (u32 slot : byDraw) {
if (nextRef > MAX_MASK_REF) {
ES_LOG_WARN("SpriteMask: more than 255 masks in one frame; the rest cut nothing");
break;
}
masks[slot].ref = nextRef++;
clip_state_.setStencilMask(mask_entities_scratch_[slot].id(), masks[slot].ref);
}
if (clip_state_.reserveSpriteStencilReferences(nextRef - 1)) {
ES_LOG_WARN("UI masks exceed remaining stencil references after SpriteMask allocation; overflowing subtrees are clipped");
}
auto spriteView = registry.activeView<ecs::Sprite>();
for (auto entity : spriteView) {
const auto& sprite = spriteView.get(entity);
if (sprite.maskInteraction == 0 || !sprite.enabled) continue;
if (registry.has<ecs::SpriteMask>(entity)) continue; // a mask is not its own subject
const auto where = draw_list_.sortIdentity(entity.id(), sprite.layer, sprite.order);
const ResolvedMask* nearest =
nearestReachingMask(masks.data(), static_cast<u32>(masks.size()), where);
if (!nearest) continue;
if (sprite.maskInteraction == static_cast<i32>(ecs::SpriteMaskInteraction::VisibleOutside)) {
clip_state_.setStencilTestOutside(entity.id(), nearest->ref);
} else {
clip_state_.setStencilTest(entity.id(), nearest->ref);
}
}
mask_entities_scratch_.clear();
}
std::string RenderFrame::takeTextureWants() {
std::string out;
out.reserve(texture_wants_.size() * 12);
for (const auto& [texture, side] : texture_wants_) {
if (!out.empty()) out += ',';
out += std::to_string(texture);
out += ':';
out += std::to_string(static_cast<u32>(std::ceil(side)));
}
texture_wants_.clear();
return out;
}
RenderFrameContext RenderFrame::makeContext() {
RenderFrameContext ctx{
context_,
resource_manager_,
context_.getWhiteTextureId(),
batch_shader_id_,
current_stage_,
view_projection_,
&context_.materials(),
this,
RenderPurpose::Scene,
shadow_texture_id_,
environment_texture_id_
};
ctx.lighting_direct = lighting_direct_;
const glm::vec4 eye = cameraFromViewProjection(view_projection_);
ctx.has_view_eye = eye.w > 0.5f;
if (ctx.has_view_eye) ctx.view_eye = glm::vec3(eye);
return ctx;
}
/// Where a light aims: the entity's forward, its rotation applied to -Z. A light
/// without a Transform aims the way an unrotated one does, which is into the screen —
/// where a 2D scene's light comes from.
static glm::vec3 lightForward(ecs::Transform* transform) {
if (!transform) return glm::vec3(0.0f, 0.0f, -1.0f);
transform->ensureDecomposed();
return transform->worldRotation * glm::vec3(0.0f, 0.0f, -1.0f);
}
/**
* @brief Gathers the frame's probe volumes: a world box each, and the grid inside it.
*
* @details A volume BORROWS its coefficients from the resource manager rather than
* copying them — the store is filled and read within one collect, and a
* grid is kilobytes an every-frame copy would spend nothing to gain.
*/
void RenderFrame::collectProbes(ecs::Registry& registry) {
ProbeStore& probes = context_.probes();
probes.clear();
auto view = registry.activeView<ecs::LightProbeVolume>();
for (auto entity : view) {
const auto& volume = view.get(entity);
if (!volume.enabled) continue;
// A volume filled at run time (a capture's grid) reads that instead of what it was baked with.
const auto overridden = probe_overrides_.find(static_cast<u32>(entity));
const ProbeVolume* grid = resource_manager_.getProbeVolume(
overridden != probe_overrides_.end() ? overridden->second : volume.probes);
if (!grid) continue;
// The box is axis-aligned around the entity's world position: a grid was
// solved on world axes, so a turned volume would be read along axes it
// never had. Scale is not read for the same reason.
const auto* transform = registry.tryGet<ecs::Transform>(entity);
const glm::vec3 centre = transform ? rebased(transform->worldPosition) : rebased(glm::vec3(0.0f));
const glm::vec3 half = glm::abs(volume.halfExtents);
probes.add(centre - half, centre + half, grid);
}
// 2048 is the side WebGL2 guarantees; a grid past it keeps the per-object read rather than failing.
if (probes.layoutAtlas(2048) && probes.atlasWidth() > 0) {
probes.fillAtlas(probe_atlas_texels_);
probe_atlas_ = Texture::createRaw(device_, GfxContent::retained(), probes.atlasWidth(), probes.atlasHeight(),
probe_atlas_texels_.data(), TextureFormat::RGBA16F, false);
}
probes.setAtlasTexture(probes.atlasWidth() > 0 && probe_atlas_ ? probe_atlas_->getId() : 0);
}
/**
* @brief Rasterises this camera's occluders: every declared box, as this view sees it.
*
* @details Before the plugins, because every one of them reads it: a renderable is
* tested against the whole scene's occluders and not against those that
* happen to have been walked first. The box is ORIENTED, never its own
* bounding box — that would claim the corners the wall does not fill.
*/
void RenderFrame::collectOccluders(ecs::Registry& registry) {
occlusion_.begin(view_projection_);
auto view = registry.activeView<ecs::Occluder>();
for (auto entity : view) {
const auto& occluder = view.get(entity);
if (!occluder.enabled) continue;
auto* transform = registry.tryGet<ecs::Transform>(entity);
if (!transform) continue;
transform->ensureDecomposed();
// Scale is not read, matching every other authored extent and the box the
// viewport draws: one value, two readers, and the picture an author places
// the box by IS what the cull uses.
occlusion_.addBox(rebased(transform->worldPosition), transform->worldRotation,
glm::abs(occluder.halfExtents));
}
occlusion_.finish();
}
/**
* @brief Gathers the frame's reflection probes: a box each, and the atlas column
* the bake gave it.
*
* @details After the lights, because it OVERRIDES what they bound: a baked scene
* reflects its bake, whose column 0 is the sky it was solved under. The
* irradiance stays the ambient light's — an atlas is the other half.
*/
void RenderFrame::collectReflections(ecs::Registry& registry) {
ReflectionStore& store = context_.reflections();
store.clear();
auto view = registry.activeView<ecs::ReflectionProbe>();
for (auto entity : view) {
const auto& probe = view.get(entity);
if (!probe.enabled || !probe.reflection.isValid()) continue;
const auto* transform = registry.tryGet<ecs::Transform>(entity);
if (!transform) continue;
const glm::vec3 centre = rebased(transform->worldPosition);
const glm::vec3 half = glm::abs(probe.halfExtents);
store.add(centre - half, centre + half, probe.slot, probe.reflection.id());
}
// Probe volumes filled at run time reflect their capture too, a column each of the atlas the SDK built from them;
// the frame binds one atlas, so a scene with baked reflection probes keeps those.
if (store.empty() && !probe_reflections_.empty()) {
auto volumes = registry.activeView<ecs::LightProbeVolume>();
for (auto entity : volumes) {
const auto found = probe_reflections_.find(static_cast<u32>(entity));
if (found == probe_reflections_.end() || !volumes.get(entity).enabled) continue;
const auto* transform = registry.tryGet<ecs::Transform>(entity);
if (!transform) continue;
const glm::vec3 centre = rebased(transform->worldPosition);
const glm::vec3 half = glm::abs(volumes.get(entity).halfExtents);
store.add(centre - half, centre + half, found->second.slot, found->second.environment);
}
}
if (store.empty()) return;
const Environment* baked =
resource_manager_.getEnvironment(resource::EnvironmentHandle(store.environment()));
if (!baked || !baked->hasSpecular()) return;
Texture* atlas = resource_manager_.getTexture(baked->specular);
if (!atlas) return;
// Boxes by COLUMN and not in the order the registry walked them: the shader
// indexes by the number written on the probe, and a frame that packed them
// tightly would project one room's reflection onto another's walls.
glm::vec4 boxes[2 * MAX_REFLECTION_PROBES]{};
u32 highest = 0;
for (const ReflectionStore::Probe& probe : store.probes()) {
const u32 at = (probe.slot - 1) * 2;
boxes[at] = glm::vec4(probe.min, 0.0f);
boxes[at + 1] = glm::vec4(probe.max, 0.0f);
highest = std::max(highest, probe.slot);
}
environment_texture_id_ = atlas->getId();
context_.lights().setReflections(
glm::vec4(1.0f, baked->maxRange, static_cast<f32>(baked->mipCount) - 1.0f,
baked->faceSize),
boxes, highest);
}
/// A direction in an environment's own frame, in the world's: the inverse of the
/// shaders' envDirection, which turns a world direction by -yaw about +Y.
static glm::vec3 environmentToWorld(const glm::vec3& d, f32 yawDegrees) {
const f32 a = glm::radians(yawDegrees);
const f32 c = std::cos(a), s = std::sin(a);
return {c * d.x + s * d.z, d.y, -s * d.x + c * d.z};
}
void RenderFrame::collectLights(ecs::Registry& registry) {
LightStore& lights = context_.lights();
lights.clear();
shadow_casters_.clear();
cloud_sun_slot_ = -1;
light_cap_.clear();
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
// the environment lights with — so the answer cannot depend on registry order.
auto view = registry.activeView<ecs::Light>();
Entity skyLight{};
const Environment* sky = nullptr;
glm::vec3 skyScale(0.0f);
f32 skyYaw = 0.0f;
bool sunFollowed = false;
for (auto entity : view) {
const auto& light = view.get(entity);
if (!light.enabled || light.intensity <= 0.0f) continue;
const auto type = static_cast<ecs::LightType>(light.type);
if (type == ecs::LightType::Directional && light.followEnvironmentSun) sunFollowed = true;
if (sky || type != ecs::LightType::Ambient || !environmentOf(light).isValid()) continue;
if (const Environment* environment = resource_manager_.getEnvironment(environmentOf(light))) {
sky = environment;
skyLight = entity;
const glm::vec3 rgb = linear_color_ ? srgbToLinearCpu(glm::vec3{light.color})
: glm::vec3{light.color};
skyScale = rgb * light.intensity;
skyYaw = light.environmentRotation;
}
}
// How the baked reflections are shown: the frame's environment light says, else the first ambient light does.
{
const ecs::Light* tone = nullptr;
for (auto entity : view) {
const auto& light = view.get(entity);
if (!light.enabled || static_cast<ecs::LightType>(light.type) != ecs::LightType::Ambient) continue;
if (entity == skyLight) { tone = &light; break; }
if (!tone) tone = &light;
}
if (tone) context_.lights().setReflectionTone(tone->reflectionScale, tone->reflectionSaturation);
context_.lights().setBakedTint(tone ? glm::vec3(tone->bakedTint) : glm::vec3(1.0f));
}
const bool sunCast = sunFollowed && sky && sky->hasSun;
if (sunCast) {
light_cap_.environmentSun = true;
light_cap_.environmentSunAim = -environmentToWorld(sky->sunDirection, skyYaw);
}
// 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
// whichever happened to come last in iteration order. Ambient lights sum without a cap.
std::vector<CollectedLight>& collected = light_scratch_;
collected.clear();
bool haveSun = false;
// A light's Transform need is type-dependent. Ambient is a flat scene-wide term and
// reads none of it; Directional takes only the rotation, so it works without one and
// aims into the screen; Point/Spot need a position and are skipped without one.
for (auto entity : view) {
const auto& light = view.get(entity);
if (!light.enabled || light.intensity <= 0.0f) continue;
const auto type = static_cast<ecs::LightType>(light.type);
// color.a is unused; intensity carries the strength. Authored sRGB ->
// linear when the frame lights in linear space.
const glm::vec3 rgb = linear_color_ ? srgbToLinearCpu(glm::vec3{light.color})
: glm::vec3{light.color};
if (type == ecs::LightType::Ambient) {
// An environment REPLACES this light's flat term rather than adding to
// it: its coefficients already carry the same colour, and summing both
// would light the scene twice from one source.
if (collectEnvironment(light, rgb * light.intensity,
sunCast && entity == skyLight)) continue;
lights.addAmbient(rgb * light.intensity);
if (light.hemisphere) {
const glm::vec3 ground = linear_color_ ? srgbToLinearCpu(glm::vec3{light.groundColor})
: glm::vec3{light.groundColor};
lights.addAmbientGround((ground - rgb) * light.intensity);
}
continue;
}
const bool followsSun = type == ecs::LightType::Directional && light.followEnvironmentSun;
if (followsSun && !sunCast) {
light_cap_.refused.push_back({entity, static_cast<u8>(type), light.intensity,
LightRefusal::NoEnvironmentSun});
continue;
}
GpuLight gpu;
bool castsMeshShadow = false;
ShadowCaster caster;
caster.light = entity;
// The sun is the environment's, so the ambient light's colour and intensity
// scale it as they scale the rest of the panorama; this light's own scale on top.
gpu.color = glm::vec4(followsSun ? sky->sunColor * skyScale * rgb : rgb, light.intensity);
// shadow.x = penumbra softness (all types); shadow.y = directional march distance (only the
// directional branch of shadowFactor2D reads it; 0 keeps directional shadows off).
gpu.shadow = glm::vec4(std::max(light.shadowSoftness, 0.0f),
std::max(light.shadowDistance, 0.0f), 0.0f, 0.0f);
// Clamped where it is PACKED: a shader given a negative exponent lights the far
// side of the radius, and a fragment cannot say who authored it. The shader
// floors the exponent too — pow(0, 0) is 1, which lights the whole screen.
// y: the ramp's power, or for an inverse-square light minus the world units in a metre (a power is never
// negative, so the sign says which; distanceFalloff reads both).
gpu.falloff = glm::vec4(std::max(light.innerRadius, 0.0f),
light.inverseSquare ? -world_units_per_meter_ : std::max(light.falloff, 0.0f),
// w: the shape mask channel, -1 for a light with no shape of its own. A zero would read channel 0 of whatever sits on that unit.
std::clamp(light.shadowStrength, 0.0f, 1.0f), -1.0f);
// The sprite layers it reaches ride above the tile count the shadow atlas fills in later.
gpu.shadowMap.y = LIGHT_TILE_BITS * packLightLayerRange(light.layerMin, light.layerMax);
if (type == ecs::LightType::Directional) {
// z=1 flags directional (no attenuation) in the shader; w carries the aim's third
// component, which only a directional light has a use for — point and spot spend
// that slot on their falloff radius.
const glm::vec3 aim = followsSun && !light.aimFollowedSun ? light_cap_.environmentSunAim
: lightForward(registry.tryGet<ecs::Transform>(entity));
gpu.posDir = glm::vec4(aim.x, aim.y, 1.0f, aim.z);
// A source infinitely far away has no half-extent a map can divide by a
// distance, so what it carries is the angle it subtends — as its tangent,
// which is what the penumbra is made of either way.
gpu.shadowMap.z = std::tan(glm::radians(
std::clamp(light.sourceAngle, 0.0f, 179.0f) * 0.5f));
// One sun: a second set of cascades would claim the atlas a first one is
// already spending, and two suns is not a scene anybody authors.
if (light.meshShadows && !haveSun) {
haveSun = true;
castsMeshShadow = true;
caster.shape = ShadowShape::Box;
caster.dir = aim;
caster.extent = std::max(light.shadowExtent, 0.0f);
}
} else { // Point / Spot — world position from the Transform, w=falloff radius.
auto* transform = registry.tryGet<ecs::Transform>(entity);
if (!transform) continue; // a positional light with no position casts nothing
transform->ensureDecomposed();
const glm::vec3 p = rebased(transform->worldPosition);
const f32 typeId = (type == ecs::LightType::Spot) ? 2.0f : 0.0f;
gpu.posDir = glm::vec4(p.x, p.y, typeId, light.radius);
// The height a surface with real geometry measures against. A sprite has no
// depth of its own and keeps the plane's convention, so this reaches only the
// MESH_NORMALS half of the lighting loop.
gpu.shadow.z = p.z;
if (type == ecs::LightType::Spot) {
// Split across two slots because the two shading halves read different
// parts: the plane's xy, and the whole of it in three.
const glm::vec3 aim = lightForward(transform);
// The aim as it IS. A cone with no component in the plane needs a
// substitute there, but that belongs where the plane's convention is
// applied — stored, it tilts the three-dimensional axis as well.
gpu.spot = glm::vec4(aim.x, aim.y,
std::cos(glm::radians(light.innerAngle * 0.5f)),
std::cos(glm::radians(light.outerAngle * 0.5f)));
gpu.shadow.w = aim.z;
caster.dir = aim;
}
// A cone's map is the cone it opens. A point opens none and lights every
// direction, so its map is six cones at right angles — the same projection,
// six times.
if (light.meshShadows) {
castsMeshShadow = true;
caster.shape = type == ecs::LightType::Spot ? ShadowShape::Cone
: ShadowShape::Cube;
caster.pos = p;
caster.range = std::max(light.radius, 0.0f);
caster.outerAngle = light.outerAngle;
}
}
collected.push_back({gpu, castsMeshShadow, caster});
}
light_cap_.limit = MAX_LIGHTS + MAX_TILED_LIGHTS;
light_cap_.requested = static_cast<u32>(collected.size() + light_cap_.refused.size());
// The lights past the loop's sixteen that can still be carried: point and spot lights with no shadow map, which a tile mask
// can hand to the fragments they reach. Everything else turned away is refused as it always was.
std::vector<CollectedLight> tiled;
if (collected.size() > MAX_LIGHTS) {
// Which sixteen the loop reads: the sun, and what casts a shadow (the loop is the only place a shadow is read), first;
// then the brightest. Sorted whole, since what is left over is read in this order too.
const auto rank = [](const CollectedLight& l) {
const bool directional = l.gpu.posDir.z > 0.5f && l.gpu.posDir.z < 1.5f;
return directional ? 0 : (l.castsMeshShadow ? 1 : 2);
};
std::stable_sort(collected.begin(), collected.end(), [&rank](const CollectedLight& a, const CollectedLight& b) {
const int ra = rank(a), rb = rank(b);
if (ra != rb) return ra < rb;
return a.gpu.color.a > b.gpu.color.a;
});
for (usize i = MAX_LIGHTS; i < collected.size(); ++i) {
CollectedLight& rest = collected[i];
const bool positional = rest.gpu.posDir.z < 0.5f || rest.gpu.posDir.z > 1.5f;
if (positional && !rest.castsMeshShadow && tiled.size() < MAX_TILED_LIGHTS) {
tiled.push_back(rest);
continue;
}
// Recorded AFTER the sort and BEFORE the resize: this is the one moment
// the frame knows which lights it is about to stop carrying, and it used
// to spend that moment printing how many.
light_cap_.refused.push_back({rest.caster.light, static_cast<u8>(rest.gpu.posDir.z),
rest.gpu.color.a, LightRefusal::Capacity});
ES_LOG_WARN("collectLights: light {} is not in this frame ({}); {} kept of {}, brightest first",
rest.caster.light.raw, lightRefusalName(LightRefusal::Capacity),
MAX_LIGHTS + tiled.size(), collected.size());
}
collected.resize(MAX_LIGHTS);
}
light_cap_.accepted = static_cast<u32>(collected.size() + tiled.size());
for (u32 slot = 0; slot < collected.size(); ++slot) {
if (collected[slot].castsMeshShadow) {
ShadowCaster caster = collected[slot].caster;
caster.slot = slot;
shadow_casters_.push_back(caster);
}
// The sun a sky's clouds shade is the first directional light, as the sky's own findSun takes it.
const glm::vec4& pd = collected[slot].gpu.posDir;
if (cloud_sun_slot_ < 0 && pd.z > 0.5f && pd.z < 1.5f) {
const glm::vec3 aim(pd.x, pd.y, pd.w);
if (glm::length(aim) > 1e-6f) {
cloud_sun_slot_ = static_cast<i32>(slot);
cloud_sun_aim_ = glm::normalize(aim);
}
}
lights.addLight(collected[slot].gpu);
}
for (const CollectedLight& light : tiled) {
lights.addTiledLight(light.gpu, view_projection_);
}
// ...and which screen tiles each of the loop's own lights can reach, for the flat lit surfaces (sprites, tilemap layers).
lights.markLoopLights(view_projection_);
// Last, because which lights the mask can carry is a question about the array the
// loop above just filled.
collectShadow2D(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);
}
resource::EnvironmentHandle RenderFrame::environmentOf(const ecs::Light& light) const {
return light.environment.isValid() ? light.environment : sky_environment_;
}
bool RenderFrame::collectEnvironment(const ecs::Light& light, const glm::vec3& scale,
bool withoutSun) {
const resource::EnvironmentHandle handle = environmentOf(light);
if (!handle.isValid()) return false;
const Environment* environment = resource_manager_.getEnvironment(handle);
if (!environment) return false;
u32 textureId = 0;
if (environment->hasSpecular()) {
if (Texture* atlas = resource_manager_.getTexture(environment->specular)) {
textureId = atlas->getId();
}
}
const glm::vec4 params{textureId != 0 ? 1.0f : 0.0f, environment->maxRange,
static_cast<f32>(environment->mipCount) - 1.0f,
environment->faceSize};
const auto& baked = withoutSun ? environment->skyIrradiance : environment->irradiance;
// The diffuse half on its own: the nine coefficients carry only what a surface is lit by, and the tint the shader
// applies (scale) covers what it reflects as well, so this light's diffuse colour goes on the coefficients alone.
const glm::vec3 tint = linear_color_ ? srgbToLinearCpu(glm::vec3{light.diffuseTint}) : glm::vec3{light.diffuseTint};
const glm::vec3 diffuse = tint * std::max(light.diffuseScale, 0.0f);
auto irradiance = baked;
if (diffuse != glm::vec3(1.0f)) {
for (glm::vec3& c : irradiance) c *= diffuse;
}
if (!context_.lights().setEnvironment(irradiance.data(), params, scale,
glm::radians(light.environmentRotation))) {
return false;
}
environment_texture_id_ = textureId;
sky_texture_id_ = 0;
if (environment->sky.isValid()) {
if (Texture* sky = resource_manager_.getTexture(environment->sky)) sky_texture_id_ = sky->getId();
}
// Only an image 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 || sky_texture_id_ != 0);
return true;
}
RenderFrame::ShadowBounds RenderFrame::gatherShadowBounds(ecs::Registry& registry, bool includeHair) {
auto meshes = registry.activeView<ecs::Transform, ecs::MeshRenderer>();
ShadowBounds bounds;
for (auto entity : meshes) {
const auto& mesh = meshes.get<ecs::MeshRenderer>(entity);
if (!mesh.enabled || !mesh.mesh.isValid()) continue;
const Mesh* resident = resource_manager_.getMesh(mesh.mesh);
if (!resident) continue;
const auto* placements = registry.tryGet<ecs::MeshInstances>(entity);
if (placements && placements->transforms.empty()) continue;
const auto& materials = context_.materials();
const f32 bend = materials.vertexBounds(mesh.material);
const bool hair = includeHair && materials.hairShadowDensity(mesh.material) > 0.0f;
glm::vec3 lo, hi;
meshLocalBounds(*resident, placements ? placementCoarseMesh(resource_manager_, *resident, *placements) : nullptr, bend, lo, hi);
if (!placements) {
const auto* group = registry.tryGet<ecs::LODGroup>(entity);
LodLevels levels;
if (group && group->enabled && gatherLodLevels(resource_manager_, *group, *resident, levels)) {
lo = levels.localMin - glm::vec3(bend);
hi = levels.localMax + glm::vec3(bend);
}
}
auto& transform = meshes.get<ecs::Transform>(entity);
transform.ensureDecomposed();
const glm::vec3 position = rebased(transform.worldPosition);
const auto include = [&](const glm::vec3& centre, const glm::vec3& half) {
bounds.all.include(centre, half);
if (mesh.castShadows) bounds.casters.include(centre, half);
if (hair) bounds.hair.include(centre, half);
};
if (placements) {
const glm::mat3 linear(glm::mat4_cast(transform.worldRotation) * glm::scale(glm::mat4(1.0f), transform.worldScale));
const glm::vec3 localCentre = (lo + hi) * 0.5f, localHalf = (hi - lo) * 0.5f;
for (usize i = 0; i + 16 <= placements->transforms.size(); i += 16) {
const f32* r = placements->transforms.data() + i;
const glm::vec3 origin = position + linear * glm::vec3(r[3], r[7], r[11]);
glm::vec3 centre, half;
placement_bounds::transformedBox(linear, r, origin, localCentre, localHalf, centre, half);
include(centre, half);
}
} else {
glm::vec3 centre, half;
orientedWorldAabb(position, transform.worldRotation, transform.worldScale, lo, hi, centre, half);
include(centre, half);
}
}
return bounds;
}
/// The camera frustum's eight world corners, near plane first (GL clip z in [-1,1],
/// which both backends' shared projection helpers write).
static void frustumCorners(const glm::mat4& invVP, glm::vec3 out[8]) {
u32 at = 0;
for (f32 z : {-1.0f, 1.0f}) {
for (f32 y : {-1.0f, 1.0f}) {
for (f32 x : {-1.0f, 1.0f}) {
const glm::vec4 p = invVP * glm::vec4(x, y, z, 1.0f);
out[at++] = glm::vec3(p) / p.w;
}
}
}
}
/// Where cascade boundary @p i falls along near..far, as a fraction. Logarithmic is
/// the split that gives every cascade equal texel density, uniform keeps the near one
/// from collapsing when near is small; 0.75 is the standard mix of the two.
static f32 splitFraction(u32 i, u32 count, f32 nearDist, f32 farDist) {
const f32 t = static_cast<f32>(i) / static_cast<f32>(count);
const f32 logSplit = nearDist * std::pow(farDist / nearDist, t);
const f32 uniform = nearDist + (farDist - nearDist) * t;
const f32 d = uniform + 0.75f * (logSplit - uniform);
return (d - nearDist) / std::max(farDist - nearDist, 1e-6f);
}
/**
* The frustum a cone sees, with clip z running [0, 1] over [near, far].
*
* @details That range is the point: a GL-convention perspective puts half its volume
* below zero, which the second backend discards. This matrix is free to be
* built either way — its depths are only compared against a copy of itself.
*/
static glm::mat4 spotProjection(f32 fovDegrees, f32 nearDist, f32 farDist) {
const f32 half = glm::radians(std::clamp(fovDegrees, 1.0f, 179.0f) * 0.5f);
const f32 cot = 1.0f / std::tan(half);
glm::mat4 proj(0.0f);
proj[0][0] = cot;
proj[1][1] = cot;
proj[2][2] = farDist / (nearDist - farDist);
proj[2][3] = -1.0f;
proj[3][2] = (nearDist * farDist) / (nearDist - farDist);
return proj;
}
/// An up that cannot be parallel to @p dir, whichever way it points.
static glm::vec3 shadowUp(const glm::vec3& dir) {
return std::abs(dir.z) > 0.99f ? glm::vec3(0.0f, 1.0f, 0.0f) : glm::vec3(0.0f, 0.0f, 1.0f);
}
/**
* The map a light standing somewhere casts over one cone: the frustum it sees.
*
* @details A spot's whole map and one face of a point light's cube are this same call.
* They differ by how wide the cone opens and which way it points, which is the
* only sense in which a point light is a new kind of caster at all.
*/
static glm::mat4 coneShadow(const glm::vec3& pos, const glm::vec3& dir, f32 fovDegrees,
f32 reach) {
// A fraction of the reach and not a constant: a perspective depth spends its
// precision next to the near plane, and one fixed in world units would put that
// wherever the scene's scale happened to be.
const f32 farPlane = std::max(reach, 1e-3f);
const f32 nearPlane = std::max(farPlane * 0.005f, 1e-3f);
return spotProjection(fovDegrees, nearPlane, farPlane)
* glm::lookAt(pos, pos + dir, shadowUp(dir));
}
/// Face @p index of a cube: the axis it looks down, positive first. Six of them cover
/// every direction from a point, which is what lets a point light's map be six cones
/// rather than a projection nothing else in the pass understands.
static glm::vec3 cubeFace(u32 index) {
glm::vec3 dir(0.0f);
dir[static_cast<i32>(index / 2)] = (index % 2 == 0) ? 1.0f : -1.0f;
return dir;
}
void RenderFrame::setShadowBudget(u32 atlasSize, u32 cellSize, u32 cascades) {
const auto powerOfTwo = [](u32 n) { return n > 0 && (n & (n - 1)) == 0; };
if (!powerOfTwo(atlasSize) || atlasSize < 512 || atlasSize > 4096
|| !powerOfTwo(cellSize) || cellSize < 128 || cellSize > atlasSize / 2) {
ES_LOG_WARN("invalid shadow quality budget: atlas {}, cell {}", atlasSize, cellSize);
return;
}
shadow_cascades_ = std::clamp(cascades, 1u, MAX_SHADOW_CASCADES);
if (shadow_atlas_size_ == atlasSize && shadow_cell_size_ == cellSize) return;
shadow_atlas_size_ = atlasSize;
shadow_cell_size_ = cellSize;
shadow_atlas_ = ShadowAtlas(atlasSize, cellSize);
}
void RenderFrame::setShadowDistance(f32 distance) {
shadow_distance_ = std::isfinite(distance) ? std::max(distance, 0.0f) : 0.0f;
}
void RenderFrame::setLightingDirect(bool on) {
lighting_direct_ = on;
context_.materials().setLightingDirect(on);
}
void RenderFrame::setShadow2DSoftSamples(u32 samples) {
shadow_2d_soft_samples_ = std::clamp(samples, 1u, 32u);
}
void RenderFrame::buildShadowPlan(ecs::Registry& registry) {
shadow_texture_id_ = 0;
shadow_resource_ = rg::kNoResource;
shadow_views_.clear();
cloud_tile_ = -1;
// Zeroed first, and the atlas given back: a tile that outlived its map would
// shadow the scene against geometry from a frame that no longer exists.
shadow_atlas_.reset();
std::swap(shadow_plan_, previous_shadow_plan_);
shadow_plan_.clear();
shadow_plan_.atlasSize = shadow_atlas_size_;
shadow_plan_.cellSize = shadow_cell_size_;
ES_PROFILE_COUNTER("render.shadow.atlasBudget", shadow_atlas_size_);
ES_PROFILE_COUNTER("render.shadow.atlasSize", 0);
context_.lights().setShadowTiles(nullptr, nullptr, 0, glm::vec4(0.0f));
if (!in_frame_ || !device_.isDeviceUsable()) return;
// How far the sun's cloud shadow map reaches each way, in world units: 0 where no sky casts one, or there is no sun to dim.
f32 cloudExtent = 0.0f;
#ifdef ES_ENABLE_POSTPROCESS
if (cloud_sun_slot_ >= 0 && post_process_ && post_process_->isEngaged()) {
f32 km = 0.0f, unitsPerKm = 0.0f;
if (post_process_->cloudShadowCaster(km, unitsPerKm)) {
cloudExtent = km * (unitsPerKm > 0.0f ? unitsPerKm : 1000.0f * world_units_per_meter_);
}
}
#endif
if (shadow_casters_.empty() && cloudExtent <= 0.0f) return;
const glm::mat4 invVP = glm::inverse(view_projection_);
// Clip's z axis back in world: w != 0 is an eye point, w == 0 says the projection
// is orthographic and there is none. Cascades only pay off under perspective —
// an orthographic view already spends its texels evenly over what it can see.
const glm::vec4 eye = invVP * glm::vec4(0.0f, 0.0f, 1.0f, 0.0f);
const bool perspective = std::abs(eye.w) > 1e-6f;
glm::vec3 corners[8];
frustumCorners(invVP, corners);
const ShadowBounds sceneBounds = gatherShadowBounds(registry, perspective);
const auto& boundsMin = sceneBounds.all.min;
const auto& boundsMax = sceneBounds.all.max;
const bool haveBounds = sceneBounds.all.valid;
// A map of a fixed size goes where the shadows come from. Centred on everything, a backdrop far behind a character takes it away from her: a large
// receiver says nothing of where a shadow can start.
const auto& castersMin = sceneBounds.casters.min;
const auto& castersMax = sceneBounds.casters.max;
const bool haveCasters = sceneBounds.casters.valid;
// Hair is layers of cards a few millimetres apart, which a cascade spread over the view cannot tell apart: its texel is as wide as the gap.
// So a perspective sun with cascades of its own also gets one fitted to the hair alone, first in its list (the nearest tile covering a
// fragment wins), and everything that falls inside it, the face under a fringe included, is shadowed at that resolution.
const auto& hairMin = sceneBounds.hair.min;
const auto& hairMax = sceneBounds.hair.max;
const bool haveHair = sceneBounds.hair.valid;
f32 nearDist = 0.0f, farDist = 1.0f;
if (perspective) {
const glm::vec3 eyePos = glm::vec3(eye) / eye.w;
nearDist = glm::length((corners[0] + corners[3]) * 0.5f - eyePos);
farDist = glm::length((corners[4] + corners[7]) * 0.5f - eyePos);
// A near plane at zero would make the logarithmic split infinite, and one far
// behind the far plane is a camera nothing can be seen through.
nearDist = std::max(nearDist, 1e-3f);
farDist = std::max(farDist, nearDist * 1.001f);
// Nothing past the farthest piece of geometry in the scene can receive a shadow, so the cascades are spread over what is there and
// not over the whole view: a close shot of a character in a view that reaches fifty metres otherwise spends its first cascade on
// three. Rounded up by quarter octaves so the split moves a few times as the camera does, not every frame (a continuously
// changing split is shadow edges that swim).
f32 reach = shadow_distance_ > 0.0f ? shadow_distance_ : farDist;
if (haveBounds) {
f32 farthest = 0.0f;
for (u32 i = 0; i < 8; ++i) {
const glm::vec3 corner((i & 1) ? boundsMax.x : boundsMin.x, (i & 2) ? boundsMax.y : boundsMin.y,
(i & 4) ? boundsMax.z : boundsMin.z);
farthest = std::max(farthest, glm::length(corner - eyePos));
}
const f32 stepped = std::exp2(std::ceil(std::log2(std::max(farthest, 1e-3f)) * 4.0f) / 4.0f);
reach = std::min(reach, stepped);
}
if (reach < farDist) {
const f32 limitedFar = std::max(reach, nearDist * 1.001f);
const f32 fraction = (limitedFar - nearDist) / (farDist - nearDist);
for (u32 i = 0; i < 4; ++i) {
corners[i + 4] = corners[i] + (corners[i + 4] - corners[i]) * fraction;
}
farDist = limitedFar;
}
}
// Who gets what. A light that stands somewhere claims first, because a sun taking the
// atlas whole would leave every other caster mapless; the sun then loses its farthest
// cascade rather than costing a light whose map cannot be shortened.
struct TilePlan {
u32 first = 0;
u32 count = 0;
};
std::vector<TilePlan> plan(shadow_casters_.size());
for (usize i = 0; i < shadow_casters_.size(); ++i) {
const ShadowCaster& caster = shadow_casters_[i];
if (caster.shape == ShadowShape::Box) continue;
const u32 want = caster.shape == ShadowShape::Cube ? SHADOW_CUBE_FACES : 1;
i32 at = -1;
const ShadowGrant grant = claimTiles(shadow_atlas_, caster.light, want, 1, at);
if (at >= 0) plan[i] = {static_cast<u32>(at), grant.granted};
shadow_plan_.grants.push_back(grant);
}
// The sun's cloud shadow, before its cascades: one tile for the whole of what the camera sees under the clouds, where a cascade
// is the nearest stretch of it. With the atlas full a sun then gives up its farthest cascade, as it does for a light that stands somewhere.
if (cloudExtent > 0.0f) {
claimTiles(shadow_atlas_, INVALID_ENTITY, 1, 1, cloud_tile_);
}
for (usize i = 0; i < shadow_casters_.size(); ++i) {
const ShadowCaster& caster = shadow_casters_[i];
if (caster.shape != ShadowShape::Box) continue;
// A fixed reach is the author saying what the map covers; splitting it would
// hand the rest of the atlas to slices they never asked for.
const bool focus = haveHair && caster.extent <= 0.0f;
const u32 want = (perspective && caster.extent <= 0.0f) ? shadow_cascades_ + (focus ? 1u : 0u) : 1;
i32 at = -1;
const ShadowGrant grant = claimTiles(shadow_atlas_, caster.light, want,
kShadowCascadeCells, at, ShadowClaim::AllowFewer);
if (at >= 0) plan[i] = {static_cast<u32>(at), grant.granted};
shadow_plan_.grants.push_back(grant);
}
for (const ShadowGrant& g : shadow_plan_.grants) {
shadow_plan_.requestedTiles += g.requested;
shadow_plan_.grantedTiles += g.granted;
// The light cap two hundred lines up warns when it drops a light. This is the
// same contention over the same frame and said nothing at all, which is how a
// light that stopped casting became a question with no answer in the engine.
// Keep the live report every frame, but only log a new denial. A stable
// over-budget scene must not spend every frame formatting the same warning.
if (g.denied() && !previous_shadow_plan_.hasSameDenial(g)) {
ES_LOG_WARN("shadow atlas: light {} asked for {} tile(s) and got none ({})",
g.light.raw, g.requested, refusalName(g.refusal));
}
}
const u32 atlasSize = shadow_atlas_.occupiedSize();
glm::mat4 matrices[MAX_SHADOW_TILES];
glm::vec4 tiles[MAX_SHADOW_TILES];
bool anyTile = false;
if (cloud_tile_ >= 0) {
// Along the sun's rays, round the camera, snapped to the map's own texels so the shadows do not crawl as the camera moves.
// Every point on one ray is under the same cloud, so where along it the map stands does not matter: only x and y are read.
const ShadowTile& tile = shadow_atlas_.tile(static_cast<u32>(cloud_tile_));
const glm::vec3 toLight = -cloud_sun_aim_;
const glm::vec3 up = shadowUp(toLight);
const glm::mat4 lightRot = glm::lookAt(glm::vec3(0.0f), -toLight, up);
const glm::mat4 lightRotInv = glm::inverse(lightRot);
const glm::vec3 seen = perspective ? glm::vec3(eye) / eye.w : (corners[0] + corners[7]) * 0.5f;
const f32 texel = (cloudExtent * 2.0f) / static_cast<f32>(tile.size);
glm::vec3 inLight = glm::vec3(lightRot * glm::vec4(seen, 1.0f));
inLight.x = std::floor(inLight.x / texel) * texel;
inLight.y = std::floor(inLight.y / texel) * texel;
const glm::vec3 centre = glm::vec3(lightRotInv * glm::vec4(inLight, 1.0f));
const glm::mat4 lightView = glm::lookAt(centre + toLight * cloudExtent, centre, up);
glm::mat4 lightProj(1.0f);
lightProj[0][0] = 1.0f / cloudExtent;
lightProj[1][1] = 1.0f / cloudExtent;
lightProj[2][2] = -0.5f / cloudExtent;
lightProj[3][2] = 0.0f;
cloud_matrix_ = lightProj * lightView;
matrices[cloud_tile_] = cloud_matrix_;
tiles[cloud_tile_] = shadow_atlas_.unitRect(static_cast<u32>(cloud_tile_), atlasSize);
context_.lights().setLightCloudTile(static_cast<u32>(cloud_sun_slot_), static_cast<u32>(cloud_tile_));
anyTile = true;
}
for (usize ci = 0; ci < shadow_casters_.size(); ++ci) {
const ShadowCaster& caster = shadow_casters_[ci];
const TilePlan mine = plan[ci];
if (mine.count == 0) continue;
u32 plannedTiles = 0;
// The first tile of a perspective sun with cascades is the hair's, when there is hair; the cascades follow it.
const bool hasFocus = haveHair && caster.shape == ShadowShape::Box && caster.extent <= 0.0f && mine.count > 1;
const u32 cascadeCount = mine.count - (hasFocus ? 1u : 0u);
for (u32 c = 0; c < mine.count; ++c) {
const u32 tileIndex = mine.first + c;
const ShadowTile& tile = shadow_atlas_.tile(tileIndex);
glm::mat4 projection(1.0f);
if (caster.shape != ShadowShape::Box) {
// A receiver resolves in exactly one face, and whatever stands between
// it and the light is inside that same face: a face's frustum IS the
// cone from the light through everything the face covers.
const bool cube = caster.shape == ShadowShape::Cube;
projection = coneShadow(caster.pos, cube ? cubeFace(c) : caster.dir,
cube ? 90.0f : caster.outerAngle, caster.range);
} else {
// The shader lights a surface from normalize(-aim), so rays travel the
// other way; the rotation alone snaps a centre to the map's own grid.
const glm::vec3 toLight = glm::normalize(-caster.dir);
const glm::vec3 up = shadowUp(toLight);
const glm::mat4 lightRot = glm::lookAt(glm::vec3(0.0f), -toLight, up);
const glm::mat4 lightRotInv = glm::inverse(lightRot);
glm::vec3 centre(0.0f);
f32 radius = 1.0f;
if (!perspective || caster.extent > 0.0f) {
// What the map covers: the 3D geometry, unless the light asked for a
// fixed reach. A radius, so coverage does not change as the light turns.
const CameraView view = computeCameraView(view_projection_);
const f32 fitted = haveBounds
? 0.5f * glm::length(boundsMax - boundsMin)
: 0.5f * glm::length(glm::vec2(view.right - view.left,
view.top - view.bottom));
radius = caster.extent > 0.0f ? caster.extent : std::max(fitted, 1.0f);
centre = caster.extent > 0.0f && haveCasters ? (castersMin + castersMax) * 0.5f
: haveBounds ? (boundsMin + boundsMax) * 0.5f
: glm::vec3(view.center.x, view.center.y, 0.0f);
} else if (hasFocus && c == 0) {
// The hair, as a sphere a little wider than its box so the face under it is inside, its radius stepped by quarter octaves
// so the texel does not change every frame, and the centre snapped to the map's grid so the edges do not crawl.
centre = (hairMin + hairMax) * 0.5f;
const f32 wanted = std::max(0.5f * glm::length(hairMax - hairMin) * 1.25f, 0.02f);
radius = std::exp2(std::ceil(std::log2(wanted) * 4.0f) / 4.0f);
const f32 texel = (radius * 2.0f) / static_cast<f32>(tile.size);
glm::vec3 inLight = glm::vec3(lightRot * glm::vec4(centre, 1.0f));
inLight.x = std::floor(inLight.x / texel) * texel;
inLight.y = std::floor(inLight.y / texel) * texel;
centre = glm::vec3(lightRotInv * glm::vec4(inLight, 1.0f));
} else {
// This slice of the view, as a sphere: a box would grow and shrink as
// the light turns, and the texel density with it.
const u32 slot = hasFocus ? c - 1 : c;
const f32 t0 = splitFraction(slot, cascadeCount, nearDist, farDist);
const f32 t1 = splitFraction(slot + 1, cascadeCount, nearDist, farDist);
glm::vec3 slice[8];
for (u32 i = 0; i < 4; ++i) {
const glm::vec3 ray = corners[i + 4] - corners[i];
slice[i] = corners[i] + ray * t0;
slice[i + 4] = corners[i] + ray * t1;
}
for (const glm::vec3& p : slice) centre += p;
centre *= 0.125f;
for (const glm::vec3& p : slice) {
radius = std::max(radius, glm::length(p - centre));
}
// Snap to the map's own texel grid, in the light's axes: without it the
// cascade slides continuously with the camera and every shadow edge
// crawls along the geometry a texel at a time.
const f32 texel = (radius * 2.0f) / static_cast<f32>(tile.size);
glm::vec3 inLight = glm::vec3(lightRot * glm::vec4(centre, 1.0f));
inLight.x = std::floor(inLight.x / texel) * texel;
inLight.y = std::floor(inLight.y / texel) * texel;
centre = glm::vec3(lightRotInv * glm::vec4(inLight, 1.0f));
}
// ★ How far back the near plane goes. A cascade covers a slice of the VIEW,
// but what shadows it can stand anywhere between the slice and the light —
// clip at the slice and the caster is not drawn, and nothing says why.
f32 castDistance = radius * 2.0f;
if (haveBounds) {
for (u32 i = 0; i < 8; ++i) {
const glm::vec3 corner((i & 1) ? boundsMax.x : boundsMin.x,
(i & 2) ? boundsMax.y : boundsMin.y,
(i & 4) ? boundsMax.z : boundsMin.z);
castDistance = std::max(castDistance, glm::dot(corner - centre, toLight));
}
}
const glm::mat4 lightView = glm::lookAt(centre + toLight * castDistance,
centre, up);
// Written out rather than built from math::ortho: this maps the occluders it
// draws onto exactly [0,1], so it needs no conversion for either device —
// which is what lets the depths it writes be compared against the receiver's.
glm::mat4 lightProj(1.0f);
const f32 range = castDistance + radius * 2.0f;
lightProj[0][0] = 1.0f / radius;
lightProj[1][1] = 1.0f / radius;
lightProj[2][2] = -1.0f / range;
lightProj[3][2] = 0.0f;
projection = lightProj * lightView;
}
matrices[tileIndex] = projection;
// Where the tile sits, and nothing else. What a comparison against it has
// to forgive is not a property of the tile but of the fragment asking, and
// is derived there out of this matrix and the size of the square.
tiles[tileIndex] = shadow_atlas_.unitRect(tileIndex, atlasSize);
// A face whose frustum misses the whole of the geometry gathers nothing, and
// asking each mesh in turn is the only way to find that out otherwise. The
// box every mesh is inside answers it once, for the price of one test.
Frustum tileFrustum;
tileFrustum.extractFromMatrix(projection);
if (haveBounds && !tileFrustum.intersectsAABB((boundsMin + boundsMax) * 0.5f,
(boundsMax - boundsMin) * 0.5f)) {
continue;
}
ShadowView view{projection, tile.x, tile.y, tile.size};
// A sun's rays are parallel, so what a caster shades is a segment along them, down to the lowest thing that can receive it. That is
// worth drawing only where the camera sees some of it. Not with a planar reflection in the frame (it looks through a frustum
// of its own, and receives from the same atlas), nor without bounds to say where the rays end.
if (caster.shape == ShadowShape::Box && haveBounds && planar_captures_.empty() && glm::length(caster.dir) > 1e-6f) {
view.sun = true;
view.ray = glm::normalize(caster.dir);
view.floorY = boundsMin.y;
view.reachCap = glm::length(boundsMax - boundsMin);
}
shadow_views_.push_back(view);
++plannedTiles;
}
// A caster whose every tile was rejected has no map to read. Published anyway,
// its range would cost each of the fragments it lights a fetch that can only
// answer "nothing here".
if (plannedTiles == 0) {
plan[ci].count = 0;
} else {
anyTile = true;
}
}
ES_PROFILE_COUNTER("render.shadow.collects", static_cast<u32>(shadow_views_.size()));
// Asked for BESIDE handed out: the two being equal is the only reading under
// which "16 tiles" says the frame got what it wanted.
ES_PROFILE_COUNTER("render.shadow.requested", shadow_plan_.requestedTiles);
ES_PROFILE_COUNTER("render.shadow.denied", shadow_plan_.deniedCasters());
ES_PROFILE_COUNTER("render.shadow.reduced", shadow_plan_.reducedCasters());
if (!anyTile) return;
// The texture must exist before scene collection puts it in receiver sort keys.
// Owned and kept, not pooled: what was drawn into it last frame is what lets this frame skip drawing it.
if (!shadow_target_ || shadow_target_->getWidth() != atlasSize) {
FramebufferSpec spec;
spec.width = atlasSize;
spec.height = atlasSize;
spec.depthStencil = true;
spec.linearFilter = false;
spec.colorFormat = GfxPixelFormat::RGBA8;
shadow_target_ = Framebuffer::create(device_, spec);
shadow_drawn_valid_ = false;
}
if (!shadow_target_) {
shadow_views_.clear();
return;
}
shadow_resource_ = graph_.importTarget(shadow_target_->handle(), atlasSize, atlasSize, /*output=*/false,
shadow_target_->getColorAttachment());
if (shadow_resource_ == rg::kNoResource) {
shadow_views_.clear();
return;
}
shadow_texture_id_ = static_cast<u32>(graph_.textureOf(shadow_resource_));
ES_PROFILE_COUNTER("render.shadow.atlasSize", atlasSize);
context_.lights().setShadowTiles(
matrices, tiles, shadow_atlas_.tileCount(),
glm::vec4(1.0f, 1.0f / static_cast<f32>(atlasSize), 0.0f, 0.0f));
// Which of them each light reads. Without it a fragment would test against
// every map in the atlas, including ones rendered from where it cannot see.
for (usize i = 0; i < shadow_casters_.size(); ++i) {
if (plan[i].count == 0) continue;
context_.lights().setLightShadowTiles(shadow_casters_[i].slot,
plan[i].first, plan[i].count);
}
}
void RenderFrame::declareShadowPass(ecs::Registry& registry) {
if (shadow_resource_ == rg::kNoResource) {
// A frame that plans no map gives the atlas back, as the pool it came from gave back what no frame asked for.
shadow_target_.reset();
shadow_drawn_valid_ = false;
return;
}
// Collected now rather than when the pass runs: whether it runs at all is decided by what it would draw. (Before the camera's
// own collect, as the casters' level of detail always assumed: they cast what the camera settled on last frame.)
// First what the collect would read. The same as what the collect that drew the atlas read, it would come back with the key
// the atlas holds, and is not made. With the change audit on it is made all the same, and a different key is a bug: something
// the collect reads that the inputs do not say.
u64 inputs = 0;
const bool vouched = shadowInputs(registry, inputs);
const bool inputsMatch = vouched && shadow_drawn_valid_ && shadow_drawn_inputs_valid_ && inputs == shadow_drawn_inputs_;
const bool skipped = inputsMatch && !registry.changeAuditEnabled();
if (skipped) {
shadow_reused_ = true;
} else {
u64 key = 0;
const bool trusted = collectShadowViews(registry, key);
shadow_reused_ = trusted && shadow_drawn_valid_ && key == shadow_drawn_key_;
if (inputsMatch && !shadow_reused_) {
++shadow_inputs_stale_;
if (!warned_shadow_inputs_) {
warned_shadow_inputs_ = true;
ES_LOG_WARN("change audit: the shadow collect's inputs were those of the frame that drew the atlas, but it drew"
" something else - it reads something its inputs do not say");
}
}
if (shadow_reused_) {
// The atlas stands, and now also for these inputs.
shadow_drawn_inputs_ = inputs;
shadow_drawn_inputs_valid_ = vouched;
} else {
shadow_pending_key_ = key;
shadow_pending_trusted_ = trusted;
shadow_pending_inputs_ = inputs;
shadow_pending_inputs_valid_ = vouched;
}
}
ES_PROFILE_COUNTER("render.shadow.collectSkipped", skipped ? 1u : 0u);
// Why a frame could not skip it: 1 a caster could not vouch, 2 the atlas cannot be trusted to stand (a compute-written record, a
// material that moves its vertices), 4 the inputs moved (the plugin says which of its own did: render.mesh.castChanged).
ES_PROFILE_COUNTER("render.shadow.collectWhy", skipped ? 0u : (!vouched ? 1u : 0u) | (!shadow_drawn_valid_ ? 2u : 0u)
| (vouched && shadow_drawn_inputs_valid_ && inputs != shadow_drawn_inputs_ ? 4u : 0u));
ES_PROFILE_COUNTER("render.shadow.inputsStale", shadow_inputs_stale_);
ES_PROFILE_COUNTER("render.shadow.reused", shadow_reused_ ? 1u : 0u);
if (shadow_reused_) {
// What this frame drew (nothing) and, apart from it, what the atlas it reads holds: the maps and draws of the frame that drew it.
ES_PROFILE_COUNTER("render.shadow.tiles", 0u);
ES_PROFILE_COUNTER("render.shadow.draws", 0u);
ES_PROFILE_COUNTER("render.shadow.heldTiles", shadow_held_tiles_);
ES_PROFILE_COUNTER("render.shadow.heldDraws", shadow_held_draws_);
ES_PROFILE_COUNTER("render.shadow.castersCulled", shadow_casters_culled_);
} else {
// Recorded by the pass when it runs, not here: a pass the graph culls drew nothing, and its key would vouch for an atlas
// that never held what it says.
shadow_drawn_valid_ = false;
}
rg::PassDesc shadow;
shadow.name = "shadow-atlas";
shadow.write = shadow_resource_;
// The map is the packed depth in its colour; the depth buffer beside it only orders the casters while they are drawn.
shadow.discardDepth = true;
// One pass for every map the frame renders, because they share an attachment:
// a point light's six faces are six viewports inside this pass rather than six
// passes the device has to transition the atlas between.
shadow.clear = true;
shadow.clearDepth = true;
// White is depth 1 unpacked: nothing here. A square the plan kept but whose
// collect comes back empty reads as no occluder rather than as a black wall.
shadow.clearColor[0] = shadow.clearColor[1] = shadow.clearColor[2] = 1.0f;
shadow.clearColor[3] = 1.0f;
shadow.execute = [this](const rg::PassContext&) { executeShadowPass(); };
// The atlas already holds what this would draw: no pass, and every reader samples last frame's squares, which are this frame's.
if (!shadow_reused_) graph_.addPass(std::move(shadow));
#ifdef ES_ENABLE_POSTPROCESS
if (cloud_tile_ < 0 || !post_process_) return;
// The sky draws what of the sun its clouds leave into the sun's tile, before the scene reads it: white above, that in the alpha.
rg::PassDesc cloud;
cloud.name = "cloud-shadow";
cloud.write = shadow_resource_;
cloud.keep = true;
cloud.discardDepth = true;
const glm::vec4 rect = shadow_atlas_.unitRect(static_cast<u32>(cloud_tile_), shadow_atlas_.occupiedSize());
const glm::mat4 inverse = glm::inverse(cloud_matrix_);
cloud.execute = [this, rect, inverse](const rg::PassContext& ctx) { post_process_->drawCloudShadow(inverse, rect, ctx); };
graph_.addPass(std::move(cloud));
#endif
}
u32 RenderFrame::queueMaterialBake(u32 material, u32 shader, u32 target, u32 x, u32 y, u32 w, u32 h,
const glm::vec4& a, const glm::vec4& b) {
const u32 ticket = next_material_bake_++;
if (next_material_bake_ == 0) next_material_bake_ = 1;
#ifdef ES_ENABLE_POSTPROCESS
material_bakes_.push_back({ticket, material, shader, target, x, y, w, h, a, b});
material_bake_states_[ticket] = 0;
#else
material_bake_states_[ticket] = -1;
#endif
return ticket;
}
i32 RenderFrame::materialBakeState(u32 ticket) {
auto it = material_bake_states_.find(ticket);
if (it == material_bake_states_.end()) return -1;
const i32 state = it->second;
if (state != 0) material_bake_states_.erase(it);
return state;
}
void RenderFrame::declareMaterialBakes() {
#ifdef ES_ENABLE_POSTPROCESS
// Once a frame, by the first view that collects: the passes write textures of their own, not any view's picture.
if (material_bakes_.empty() || material_bakes_frame_ == planar_frame_ || !post_process_) return;
material_bakes_frame_ = planar_frame_;
std::vector<MaterialBake> waiting;
u32 scratch = 0;
for (const MaterialBake& bake : material_bakes_) {
RenderTarget* target = target_manager_.get(bake.target);
Shader* shader = resource_manager_.getShader(resource::ShaderHandle(bake.shader));
if (!target || !shader || bake.w == 0 || bake.h == 0) {
material_bake_states_[bake.ticket] = -1;
continue;
}
// A program still compiling draws nothing: the bake waits a frame for it rather than leaving its rect as it was and saying done.
if (!device_.programReady(shader->handle())) {
waiting.push_back(bake);
continue;
}
rg::PassDesc pass;
pass.name = "material-bake";
pass.keep = true;
pass.write = graph_.importTarget(target->getFramebuffer(), target->getWidth(), target->getHeight(), /*output=*/false,
target->getColorTexture());
pass.viewportX = bake.x;
pass.viewportY = bake.y;
pass.viewportW = bake.w;
pass.viewportH = bake.h;
const u32 slot = scratch++;
pass.execute = [this, bake, slot](const rg::PassContext&) {
const std::vector<std::pair<std::string, glm::vec4>> overrides{{"u_bakeA", bake.a}, {"u_bakeB", bake.b}};
const bool drawn = post_process_ && post_process_->drawMaterialThrough(bake.material, bake.shader, overrides, slot);
material_bake_states_[bake.ticket] = drawn ? 1 : -1;
if (drawn) ++material_bakes_drawn_;
};
graph_.addPass(std::move(pass));
}
material_bakes_ = std::move(waiting);
#endif
}
void RenderFrame::ensureShadowFrameUbos(u32 count) {
const u32 bytes = RenderContext::frameConstantsSize();
while (shadow_frame_ubos_.size() < count) {
const BufferHandle ubo = device_.createBuffer(
{GfxBufferUsage::Uniform, bytes, /*dynamic=*/true}, GfxContent::transient(), nullptr);
if (ubo == BufferHandle::Invalid) break;
shadow_frame_ubos_.push_back(ubo);
}
}
void RenderFrame::releaseShadowFrameUbos() {
for (BufferHandle ubo : shadow_frame_ubos_) {
if (ubo != BufferHandle::Invalid) device_.deleteBuffer(ubo);
}
shadow_frame_ubos_.clear();
}
bool RenderFrame::shadowInputs(ecs::Registry& registry, u64& key) {
u64 h = 0xcbf29ce484222325ull;
const auto mix = [&h](u64 v) { h ^= v + 0x9e3779b97f4a7c15ull + (h << 6) + (h >> 2); };
const auto words = [&mix](const void* data, usize bytes) {
const auto* p = static_cast<const u8*>(data);
usize at = 0;
for (; at + 8 <= bytes; at += 8) { u64 w; std::memcpy(&w, p + at, 8); mix(w); }
u64 tail = 0;
if (at < bytes) { std::memcpy(&tail, p + at, bytes - at); mix(tail); }
};
// Every caster is asked, whether or not an earlier one vouched: each keeps its own look at what changed.
bool vouched = true;
auto ctx = makeContext();
ctx.purpose = RenderPurpose::ShadowDepth;
for (auto& plugin : plugins_) {
if (!plugin->castsShadows()) continue;
u64 part = 0;
if (!plugin->castInputs(ctx, registry, part)) vouched = false;
mix(part);
}
// What the collect reads besides the casters: where each square is and what it looks through, the camera (a sun's casters are
// culled to what can shade what it sees), and what makes the same handles draw something else.
mix(device_.deviceGeneration());
mix(device_.geometryWrites());
mix(static_cast<u64>(shadow_target_ ? static_cast<u32>(shadow_target_->handle()) : 0u));
mix(shadow_views_.size());
for (const ShadowView& view : shadow_views_) {
words(&view.view_projection, sizeof(glm::mat4));
mix((static_cast<u64>(view.x) << 32) | view.y);
mix(view.size);
mix(view.sun ? 1u : 0u);
words(&view.ray, sizeof(view.ray));
words(&view.floorY, sizeof(view.floorY));
words(&view.reachCap, sizeof(view.reachCap));
}
words(&view_projection_, sizeof(glm::mat4));
mix(shadow_receiver_cull_ ? 1u : 0u);
mix(view_id_);
key = h;
return vouched;
}
bool RenderFrame::collectShadowViews(ecs::Registry& registry, u64& key) {
u32 shadowCastersCulled = 0;
const usize viewCount = shadow_views_.size();
// Reset once for the pass, NOT once per view: a draw carries an offset rather
// than the bytes behind it, so six faces reset to zero are six draws reading
// whatever landed at zero last.
shadow_pool_.beginFrame();
ensureShadowFrameUbos(static_cast<u32>(viewCount));
if (shadow_view_lists_.size() < viewCount) shadow_view_lists_.resize(viewCount);
// Collect every view before any is drawn, so the pool uploads once and then
// stays still: growth re-creates the buffer behind the handle, and a recorded
// draw names the buffer it was recorded with.
for (usize vi = 0; vi < viewCount; ++vi) {
const ShadowView& view = shadow_views_[vi];
DrawList& list = shadow_view_lists_[vi];
list.clear();
// What this looks through is the view's, held here rather than swapped into
// the frame's own: the scene pass after this one still reads the camera it
// was given, so there is nothing to put back.
Frustum viewFrustum;
viewFrustum.extractFromMatrix(view.view_projection);
auto ctx = makeContext();
ctx.view_projection = view.view_projection;
ctx.purpose = RenderPurpose::ShadowDepth;
// Only the plugins that cast are asked: a map holds depth, and everything
// else would write colour into a texture every receiver reads back as one.
RenderCollectContext collectCtx{registry, viewFrustum, clip_state_, shadow_pool_,
list, ctx,
computeCameraView(view.view_projection)};
if (view.sun && shadow_receiver_cull_) {
collectCtx.shadowReceivers = &frustum_;
collectCtx.shadowRay = view.ray;
collectCtx.shadowFloor = view.floorY;
collectCtx.shadowReachCap = view.reachCap;
}
collectCtx.screen_ui = screen_domain_;
collectCtx.ui_tree_layers = ui_tree_layers_;
// A shadow is part of the camera's picture: what the camera culled by its level of detail (grass past its distance)
// does not cast, and what it draws coarse casts coarse.
collectCtx.lod = {view_id_, &lod_view_state_, nullptr, true};
for (auto& plugin : plugins_) {
if (plugin->castsShadows()) plugin->collect(collectCtx);
}
shadowCastersCulled += collectCtx.shadowCulled;
list.finalize(shadow_pool_);
}
shadow_casters_culled_ = shadowCastersCulled;
// What the squares would draw, as one number. Everything a depth draw reads: where each square is and what it looks through,
// the draws, their records in the pool, and the materials of the few that carry one (a cut-out's alpha, a bent caster). Beside
// them, what would make the same handles draw something else: a lost device, geometry rewritten in place, another atlas.
u64 h = 0xcbf29ce484222325ull;
const auto mix = [&h](u64 v) { h ^= v + 0x9e3779b97f4a7c15ull + (h << 6) + (h >> 2); };
const auto words = [&mix](const void* data, usize bytes) {
const auto* p = static_cast<const u8*>(data);
usize at = 0;
for (; at + 8 <= bytes; at += 8) { u64 w; std::memcpy(&w, p + at, 8); mix(w); }
u64 tail = 0;
if (at < bytes) { std::memcpy(&tail, p + at, bytes - at); mix(tail); }
};
bool trusted = true;
mix(device_.deviceGeneration());
mix(device_.geometryWrites());
mix(static_cast<u64>(shadow_target_ ? static_cast<u32>(shadow_target_->handle()) : 0u));
mix(viewCount);
const MaterialStore& materials = context_.materials();
for (usize vi = 0; vi < viewCount; ++vi) {
const ShadowView& view = shadow_views_[vi];
words(&view.view_projection, sizeof(glm::mat4));
mix((static_cast<u64>(static_cast<u32>(view.x)) << 32) | static_cast<u32>(view.y));
mix(view.size);
const DrawList& list = shadow_view_lists_[vi];
h = list.contentHash(h);
for (u32 c = 0; c < list.commandCount(); ++c) {
const DrawCommand& cmd = list.command(c);
// Records a compute pass wrote are not in the pool to be read.
if (cmd.instance_buffer != BufferHandle::Invalid) trusted = false;
if (cmd.material_id == 0) continue;
// A material that moves its vertices may move them by the clock (wind): the same draw, another shape.
if (materials.hasVertexHook(cmd.material_id)) { trusted = false; continue; }
if (const MaterialRecord* m = materials.find(cmd.material_id)) {
words(m->uboBytes.data(), m->uboBytes.size());
for (const auto& binding : m->textures) mix(binding.texture.id());
}
}
}
for (u32 layout = 0; layout < LAYOUT_COUNT; ++layout) {
const auto id = static_cast<LayoutId>(layout);
const u32 used = shadow_pool_.vertexBytesUsed(id);
mix(used);
if (used > 0) words(shadow_pool_.vertexData(id), used);
// Indices built this frame are not read back here; a caster drawn through them is drawn every frame.
if (shadow_pool_.indicesUsed(id) > 0) trusted = false;
}
key = h;
return trusted;
}
void RenderFrame::executeShadowPass() {
// What the pass cost, for a profiler and the gates that pin it: the maps it
// actually rendered and the draws they took. Neither shows in a pixel, and a
// face that stopped being skipped would look exactly like one that never was.
u32 shadowTiles = 0;
u32 shadowDraws = 0;
const usize viewCount = shadow_views_.size();
shadow_drawn_key_ = shadow_pending_key_;
shadow_drawn_valid_ = shadow_pending_trusted_;
shadow_drawn_inputs_ = shadow_pending_inputs_;
shadow_drawn_inputs_valid_ = shadow_pending_inputs_valid_;
shadow_pool_.upload();
for (usize vi = 0; vi < viewCount; ++vi) {
const ShadowView& view = shadow_views_[vi];
DrawList& list = shadow_view_lists_[vi];
// A cube face pointing away from every mesh collects nothing, and a point
// light has six chances at that. The square already holds what the atlas was
// cleared to — depth 1, nothing here — so drawing it would agree at cost.
if (list.commandCount() == 0) continue;
device_.setViewport(view.x, view.y, view.size, view.size);
// Not a camera's: this projection spans exactly the occluders it draws, so
// it sits inside either clip volume as built, and the depths it writes are
// compared against the copy of it the receiving shader holds.
//
// One buffer per view, not one written per view: the write reaches the GPU
// on the queue, never between draws already recorded into this open pass.
// Binding IS an encoder command, so that is what tells the faces apart.
context_.useFrameConstants(shadow_frame_ubos_[vi], view.view_projection);
// The depth variant is still a Lit shader and still declares the light block,
// and a draw whose declared UBO is unbound is undefined behaviour that draws
// nothing — the whole pass came back empty for exactly this.
context_.lights().uploadAndBind();
list.execute(device_, shadow_pool_, context_.materials(),
context_.getWhiteTextureId(), nullptr, context_.perDrawBlocks());
++shadowTiles;
shadowDraws += list.mergedDrawCallCount();
}
ES_PROFILE_COUNTER("render.shadow.tiles", shadowTiles);
ES_PROFILE_COUNTER("render.shadow.draws", shadowDraws);
shadow_held_tiles_ = shadowTiles;
shadow_held_draws_ = shadowDraws;
ES_PROFILE_COUNTER("render.shadow.heldTiles", shadow_held_tiles_);
ES_PROFILE_COUNTER("render.shadow.heldDraws", shadow_held_draws_);
ES_PROFILE_COUNTER("render.shadow.castersCulled", shadow_casters_culled_);
ES_PROFILE_COUNTER("render.shadow.cullViews", [&] { u32 n = 0; for (const ShadowView& v : shadow_views_) n += v.sun ? 1u : 0u; return n; }());
// The scene draws next, through pipelines nothing here matches.
device_.invalidatePipelineCache();
}
/**
* The background an environment is, as a quad covering the screen. Not a plugin
* and not an entity: a sky belongs to no transform and is culled by nothing. Its
* corners are unprojected screen corners, 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_) return;
// The panorama where the environment carries one; the atlas' mip 0 is a
// reflection's resolution, too coarse to look at, and only the fallback.
const bool panorama = sky_texture_id_ != 0;
if (!panorama && environment_texture_id_ == 0) return;
u32& program = sky_programs_[panorama ? 1 : 0];
bool& compiled = sky_compiled_[panorama ? 1 : 0];
if (!compiled) {
compiled = true;
auto parsed = resource::ShaderParser::parse(ShaderEmbeds::SKY);
const auto target = resource_manager_.preferredShaderTarget();
std::vector<std::string> features{"ES_ENV_MAP"};
if (panorama) features.push_back("ES_SKY_PANORAMA");
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)) {
program = shader->getProgramId();
if (panorama && shader->language() == GfxShaderLanguage::GLSL_ES300) {
shader->bind();
shader->setUniform("u_texture", 0);
shader->unbind();
}
}
}
if (program == 0) return;
// The rays through the screen's corners, at a depth inside both backends'
// ranges: a quad at clip z = 1 rounds past the far plane at some view angles and
// is clipped whole. The depth does not change which rays are drawn.
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], 0.5f, 1.0f);
corners[i] = glm::vec3(p) / p.w;
}
BatchDrawKey key{};
key.stage = RenderStage::Background;
key.layer = std::numeric_limits<i32>::min();
key.shaderId = program;
key.blend = BlendMode::None;
key.layoutId = LayoutId::Sky;
// Slot 0 is the panorama, or a white fill the atlas variant never samples: the
// atlas rides the unit the shaders pin it to either way.
key.textureId = panorama ? sky_texture_id_ : 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);
}
bool RenderFrame::visibleToCamera(i32 layer, const glm::vec3& center,
const glm::vec3& halfExtents) const {
if (!draw_list_.layerVisible(DrawList::layerBit(layer))) return false;
return frustum_.intersectsAABB(center, halfExtents);
}
RenderPrewarmResult RenderFrame::prewarmPrograms(ecs::Registry& registry,
const Entity* entities, u32 count) {
auto ctx = makeContext();
// What the SCENE renders, read from the plan the last frame built rather than
// assumed: a world with no shadow caster needs no depth variant, and readying
// one would be six milliseconds spent on a program nothing asks for.
const bool shadowPasses = !shadow_casters_.empty();
RenderPrewarmResult out;
for (auto& plugin : plugins_) {
out += plugin->prewarm(ctx, registry, entities, count, shadowPasses);
}
return out;
}
RenderPrewarmResult RenderFrame::prewarmDocument(const MeshDocumentRecord* rows, u32 count) {
auto ctx = makeContext();
const bool shadowPasses = !shadow_casters_.empty();
RenderPrewarmResult out;
for (auto& plugin : plugins_) out += plugin->prewarmDocument(ctx, rows, count, shadowPasses);
return out;
}
void RenderFrame::collectAll(ecs::Registry& registry, bool sceneGBuffer) {
ES_PROFILE_SCOPE("render.collect");
// Split because "collect is expensive" names no mechanism: planning shadows,
// gathering lights and walking one render type's population are different
// work that a single total cannot be told apart by.
{ ES_PROFILE_SCOPE("render.collect.clip"); buildClipState(); }
{ ES_PROFILE_SCOPE("render.collect.sorting"); buildSortingGroups(registry); buildTreeSequence(registry); }
// After the groups, because a mask's reach is stated in the order a group may own.
{ ES_PROFILE_SCOPE("render.collect.spriteMasks"); buildSpriteMasks(registry); }
{ ES_PROFILE_SCOPE("render.collect.lights"); collectLights(registry); }
// Beside the lights and for the same reason: this answers what reaches a point
// that no light can be asked about, and the mesh collect below reads both.
{ ES_PROFILE_SCOPE("render.collect.probes"); collectProbes(registry); }
// After the lights: what a bake says a surface MIRRORS replaces what the
// ambient light's own environment would have answered.
{ ES_PROFILE_SCOPE("render.collect.reflections"); collectReflections(registry); }
// A view that shows one part of the light keeps only that part, for this camera alone.
{
const ShadingMode viewMode = view_shading_.get(view_id_);
if (viewMode == ShadingMode::DirectLighting) context_.lights().isolate(true);
else if (viewMode == ShadingMode::IndirectLighting) context_.lights().isolate(false);
}
// Before the plugins and after nothing: it reads the scene and this camera's
// projection, both of which are already settled when the collect opens.
{ ES_PROFILE_SCOPE("render.collect.occluders"); collectOccluders(registry); }
// Decided here, drawn by the graph. Nothing in this function may touch the
// device: the frame reaches the host as several calls with its own draws
// between them, and a pass opened here would swallow them.
{ ES_PROFILE_SCOPE("render.collect.shadowPlan"); buildShadowPlan(registry); }
{ ES_PROFILE_SCOPE("render.collect.shadowDeclare"); declareShadowPass(registry); }
declareMaterialBakes();
{ ES_PROFILE_SCOPE("render.collect.shadow2dDeclare"); declareShadow2DPass(); }
{ ES_PROFILE_SCOPE("render.collect.shape2dDeclare"); declareShape2DPass(); }
{ ES_PROFILE_SCOPE("render.collect.planar"); declarePlanarReflection(registry); }
{ ES_PROFILE_SCOPE("render.collect.probeCapture"); declareProbeCapture(registry); }
auto ctx = makeContext();
#ifdef ES_ENABLE_POSTPROCESS
// Asked at the collect, because it decides which program each material draw is compiled as; the
// scene pass that executes them is the one the answer is about.
ctx.gbuffer = sceneGBuffer && post_process_ && post_process_->sceneHasGBuffer();
// A temporal effect that follows moving surfaces: the scene collect remembers where each mesh stands,
// and the motion collect below compares.
const bool followMotion = sceneGBuffer && post_process_ && post_process_->isEngaged()
&& post_process_->velocityWanted();
ctx.track_motion = followMotion;
ctx.motion_key = static_cast<u64>(current_target_);
ctx.motion_frame = planar_frame_;
#else
(void)sceneGBuffer;
#endif
RenderCollectContext collectCtx{registry, frustum_, clip_state_, pool_, draw_list_, ctx,
computeCameraView(ctx.view_projection)};
// What this collect must NOT draw. A camera's job is the world; the screen's
// entities are laid out in pixels centred on the origin, and drawing them
// through a view matrix puts a HUD wherever the view happens to be looking.
collectCtx.screen_ui = screen_domain_;
collectCtx.ui_tree_layers = ui_tree_layers_;
collectCtx.lod = {view_id_, &lod_view_state_, &lod_counts_};
collectCtx.shading = view_shading_.get(view_id_);
collectCtx.weights = view_shading_.weights(view_id_);
// Only the camera collect. The shadow collect above builds its own context and
// leaves this null: what a player cannot see still casts, and a caster dropped
// because the camera cannot see IT takes its shadow off the ground with it.
collectCtx.occlusion = &occlusion_;
{ ES_PROFILE_SCOPE("render.collect.sky"); collectSky(collectCtx); }
for (auto& plugin : plugins_) {
ES_PROFILE_SCOPE(plugin->collectScope());
plugin->collect(collectCtx);
}
// The other half of what the frame cost: what it did NOT draw. Accumulated
// like the per-type counts beside it, so a frame composited from several
// cameras reports every cull each of them made.
stats_.culled += collectCtx.culled;
stats_.occluded += collectCtx.occluded;
stats_.lightsSpared += collectCtx.lightsSpared;
velocity_list_.clear();
cover_list_.clear();
#ifdef ES_ENABLE_POSTPROCESS
if (followMotion) collectMotion(registry);
if (sceneGBuffer && post_process_ && post_process_->isEngaged() && post_process_->coverWanted()) collectCover(registry);
#endif
// OR-ed across the frame's cameras, applied at the next beginFrame and never
// mid-frame: the capture is scratch each camera composites out of, and the
// editor's grid draws into it between begin() and this collect.
frame_collected_ = true;
frame_depth_seen_ = frame_depth_seen_ || draw_list_.needsDepth();
frame_scene_picture_seen_ = frame_scene_picture_seen_ || draw_list_.anyNeedsScenePicture(context_.materials());
}
void RenderFrame::collectMotion(ecs::Registry& registry) {
ES_PROFILE_SCOPE("render.collect.motion");
#ifdef ES_ENABLE_POSTPROCESS
const auto view = post_process_->peekTemporalView(view_projection_, static_cast<u64>(current_target_));
// The shift is only there when something resolves it; a chain that follows motion without a history draws still.
const bool shifted = post_process_->temporalActive();
velocity_jitter_ = shifted ? view.jitter : glm::vec2(0.0f);
velocity_pool_.beginFrame();
velocity_list_.clear();
auto ctx = makeContext();
ctx.purpose = RenderPurpose::Motion;
ctx.track_motion = true;
ctx.motion_key = static_cast<u64>(current_target_);
ctx.motion_frame = planar_frame_;
ctx.motion_prev_view_projection = view.previous;
ctx.motion_prev_jitter = shifted ? view.previousJitter : glm::vec2(0.0f);
RenderCollectContext collectCtx{registry, frustum_, clip_state_, velocity_pool_, velocity_list_, ctx,
computeCameraView(ctx.view_projection)};
collectCtx.screen_ui = screen_domain_;
collectCtx.ui_tree_layers = ui_tree_layers_;
// The level the scene settled on, not a new choice, and not counted a second time.
collectCtx.lod = {view_id_, &lod_view_state_, nullptr};
collectCtx.occlusion = &occlusion_;
for (auto& plugin : plugins_) {
if (plugin->drawsMotion()) plugin->collect(collectCtx);
}
velocity_list_.finalize(velocity_pool_);
#else
(void)registry;
#endif
}
void RenderFrame::collectCover(ecs::Registry& registry) {
ES_PROFILE_SCOPE("render.collect.cover");
#ifdef ES_ENABLE_POSTPROCESS
const f32 range = post_process_->coverRange();
// From above, over the camera, snapped to the map's own texel grid so the map does not shimmer as the camera moves.
const glm::vec4 eye4 = cameraFromViewProjection(view_projection_);
const glm::vec3 eye = eye4.w > 0.5f ? glm::vec3(eye4) : glm::vec3(0.0f);
const f32 texel = (range * 2.0f) / 1024.0f;
const glm::vec3 centre(std::floor(eye.x / texel) * texel, eye.y, std::floor(eye.z / texel) * texel);
const f32 depth = range * 2.0f;
const glm::mat4 view = glm::lookAt(centre + glm::vec3(0.0f, range, 0.0f), centre, glm::vec3(0.0f, 0.0f, -1.0f));
// Written out like the shadow maps' own, so the depth it stores runs over [0, 1] on either device.
glm::mat4 proj(1.0f);
proj[0][0] = 1.0f / range;
proj[1][1] = 1.0f / range;
proj[2][2] = -1.0f / depth;
proj[3][2] = 0.0f;
cover_view_projection_ = proj * view;
cover_pool_.beginFrame();
cover_list_.clear();
Frustum frustum;
frustum.extractFromMatrix(cover_view_projection_);
auto ctx = makeContext();
ctx.view_projection = cover_view_projection_;
ctx.purpose = RenderPurpose::ShadowDepth;
ctx.rainCover = true;
RenderCollectContext collectCtx{registry, frustum, clip_state_, cover_pool_, cover_list_, ctx,
computeCameraView(cover_view_projection_)};
collectCtx.screen_ui = screen_domain_;
collectCtx.ui_tree_layers = ui_tree_layers_;
for (auto& plugin : plugins_) {
if (plugin->castsShadows()) plugin->collect(collectCtx);
}
cover_list_.finalize(cover_pool_);
#else
(void)registry;
#endif
}
void RenderFrame::executeCoverPass() {
if (cover_list_.commandCount() == 0) return;
ES_PROFILE_SCOPE("render.cover");
// Here, in the pass, and not while collecting: an upload during collect opens a pass that swallows the host draws that follow it.
cover_pool_.upload();
if (cover_frame_ubo_ == BufferHandle::Invalid) {
cover_frame_ubo_ = device_.createBuffer({GfxBufferUsage::Uniform, RenderContext::frameConstantsSize(), /*dynamic=*/true},
GfxContent::transient(), nullptr);
}
if (cover_frame_ubo_ == BufferHandle::Invalid) return;
device_.setViewport(0, 0, 1024, 1024);
context_.useFrameConstants(cover_frame_ubo_, cover_view_projection_);
context_.lights().uploadAndBind();
cover_list_.execute(device_, cover_pool_, context_.materials(), context_.getWhiteTextureId(), nullptr,
context_.perDrawBlocks());
ES_PROFILE_COUNTER("render.cover.draws", cover_list_.mergedDrawCallCount());
// The constants the chain after this reads are the camera's, which this pass borrowed the slot from.
context_.updateCameraConstants(view_projection_, scene_jitter_);
device_.invalidatePipelineCache();
}
void RenderFrame::executeMotionPass() {
if (velocity_list_.commandCount() == 0) return;
ES_PROFILE_SCOPE("render.motion");
velocity_pool_.upload();
// Through the camera the scene was drawn with, jitter included: a surface's depth here has to be the
// scene's, since that is what the reader compares it with.
context_.updateCameraConstants(view_projection_, velocity_jitter_);
// The program is still a Lit shader and still declares the light block (see executeShadowPass).
context_.lights().uploadAndBind();
velocity_list_.execute(device_, velocity_pool_, context_.materials(), context_.getWhiteTextureId(),
nullptr, context_.perDrawBlocks());
ES_PROFILE_COUNTER("render.motion.draws", velocity_list_.mergedDrawCallCount());
device_.invalidatePipelineCache();
}
glm::vec3 srgbToLinearCpu(const glm::vec3& c) {
auto conv = [](f32 v) {
return v <= 0.04045f ? v / 12.92f : std::pow((v + 0.055f) / 1.055f, 2.4f);
};
return {conv(c.r), conv(c.g), conv(c.b)};
}
void RenderFrame::setColorSpace(bool linear) {
linear_color_ = linear;
resource::ShaderParser::setLinearColorSpace(linear);
#ifdef ES_ENABLE_POSTPROCESS
if (post_process_) post_process_->setLinearOutput(linear);
#endif
}
u32 RenderFrame::initBatchShader() {
// The default (featureless) batch program; seeds the variant cache.
return batchProgram({});
}
u32 RenderFrame::premultipliedBatchProgram() {
if (!premultiplied_batch_handle_) {
const std::vector<std::string> features{"PREMULTIPLIED_COLOR"};
batchProgram(features);
premultiplied_batch_handle_ = &batch_variants_.at(resource::ShaderParser::variantKey(features));
}
// Map values survive rehash; the device may replace the program behind them.
Shader* shader = resource_manager_.getShader(*premultiplied_batch_handle_);
return shader ? shader->getProgramId() : 0;
}
u32 RenderFrame::batchProgram(const std::vector<std::string>& features) {
const std::string key = resource::ShaderParser::variantKey(features);
auto it = batch_variants_.find(key);
if (it == batch_variants_.end()) {
it = batch_variants_.emplace(key, compileBatchVariant(features)).first;
}
// Resolved per lookup rather than cached: the program id is what the device
// replaces on a rebuild, and the handle is what survives it.
Shader* shader = resource_manager_.getShader(it->second);
return shader ? shader->getProgramId() : 0;
}
resource::ShaderHandle RenderFrame::compileBatchVariant(const std::vector<std::string>& features) {
// The batch shader is authored as a single .esshader with its WGSL twin,
// embedded for the web build. Parse it and assemble the two stages for the
// preferred target (single source of truth), injecting the requested
// feature permutation — GLSL as #defines, WGSL through the assembly-time
// preprocessor.
const auto target = resource_manager_.preferredShaderTarget();
auto parsed = resource::ShaderParser::parse(ShaderEmbeds::BATCH);
// LIT is a Lit-domain variant: the domain drives the lighting injection,
// same path as Lit material shaders.
if (std::find(features.begin(), features.end(), "LIT") != features.end()) {
parsed.domain = "Lit";
}
resource::ShaderHandle handle = resource_manager_.createShaderWithBindings(
resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Vertex, "", features, target),
resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Fragment, "", features, target),
{{0, "a_position"}, {1, "a_color"}, {2, "a_texCoord"}},
resource_manager_.preferredShaderLanguage(), resource_manager_.deferLinks());
Shader* shader = resource_manager_.getShader(handle);
if (shader && shader->isValid()) {
// After it links: at once, or (where shaders are not waited for) when a draw first needs it.
// Sampler seeding is a GLSL concept; on WGSL the textures ride the bind group.
if (shader->language() == GfxShaderLanguage::GLSL_ES300) shader->whenLinked([](Shader& s) {
s.bind();
// Bind the 8 multi-texture samplers to units 0..7 (per-program, set once).
for (i32 i = 0; i < 8; ++i) {
const std::string name = "u_textures[" + std::to_string(i) + "]";
s.setUniform(name, i);
}
s.unbind();
});
return handle;
}
const std::string vk = resource::ShaderParser::variantKey(features);
ES_LOG_ERROR("Failed to create batch shader variant '{}'", vk.empty() ? "default" : vk.c_str());
return {};
}
} // namespace esengine