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.hpp
* @brief Frame resources and the shared scene rendering contract.
*/
#pragma once
#include "../../core/Types.hpp"
#include "../draw/RenderItem.hpp"
#include "../rhi/RenderTarget.hpp"
#include "./RenderContext.hpp"
#include "./PlanarReflectionCamera.hpp"
#include "../store/PlanarConstants.hpp"
#include "../store/LightConstants.hpp"
#include "../store/ShadowAtlas.hpp"
#include "../store/ShadowPlan.hpp"
#include "../store/LightPlan.hpp"
#include "../graph/TargetPool.hpp"
#include "../graph/RenderGraph.hpp"
#include "../RenderTypePlugin.hpp"
#ifdef ES_ENABLE_POSTPROCESS
#include "./PostProcessPipeline.hpp"
#endif
#include "./FrameCapture.hpp"
#include "../rhi/GfxDevice.hpp"
#include "../rhi/Texture.hpp"
#include "../rhi/TransientBufferPool.hpp"
#include "../draw/DrawList.hpp"
#include "../draw/RetainedText.hpp"
#include "../draw/ClipState.hpp"
#include "../draw/SpriteMaskRange.hpp"
#include "../../ecs/Registry.hpp"
#include "../../resource/ResourceManager.hpp"
#include <glm/glm.hpp>
#include <span>
#include <unordered_map>
#include <vector>
#include <string>
#include <memory>
#include <unordered_map>
#include <unordered_set>
namespace esengine {
class GpuParticles;
namespace ecs { struct Light; }
class ImmediateDraw;
/// The one shadow texture every map a frame renders shares. One size for every
/// scene: coverage adapts to the camera instead, so texel density is a property of
/// how far a light was asked to reach rather than of a knob nobody can calibrate.
inline constexpr u32 kShadowAtlasSize = 2048;
/// The unit the atlas is handed out in. A cascade takes a 2x2 block of them; the
/// texel snap and the depth bias are derived from the tile that comes back, not
/// from this, so a smaller tile is a smaller answer rather than a wrong one.
inline constexpr u32 kShadowCellSize = 512;
inline constexpr u32 kShadowCascadeCells = 2;
/**
* @brief The shape a light's map has to cover — the one thing a shadow pass differs by.
* @details A box of the world for a sun, one cone for a spot, and for a point light six
* cones at right angles, because a point lights every direction and no single
* projection covers that. Each face is a tile like any other, so the atlas, the
* collect, the vertex stage and the depth packing are shared by all three.
*/
enum class ShadowShape : u8 { Box, Cone, Cube };
// GPU frame timer: a small ring of device timer queries so a frame's result is
// read a few frames later without stalling the CPU on the GPU.
class GpuTimer {
public:
void begin(GfxDevice& device);
void end(GfxDevice& device);
void poll(GfxDevice& device);
f32 lastMs() const { return last_ms_; }
private:
static constexpr int kRing = 3;
u32 queries_[kRing] = {0, 0, 0};
bool inflight_[kRing] = {false, false, false};
int write_ = 0;
int read_ = 0;
int state_ = 0; // 0 = uninit, 1 = available, 2 = unavailable
bool active_ = false;
f32 last_ms_ = -1.0f;
};
class RenderFrame {
public:
struct Stats {
u32 draw_calls = 0;
/// Every draw the GPU was asked for in the frame, every pass included; `draw_calls` is the scene's and the overlay's lists only.
u32 gpu_draws = 0;
u32 triangles = 0;
u32 sprites = 0;
u32 skeletal = 0;
u32 meshes = 0;
u32 text = 0;
u32 particles = 0;
u32 shapes = 0;
u32 culled = 0;
/// Of `culled`, how many an occluder refused rather than the frustum.
u32 occluded = 0;
/// Loop lights the lit quads did not have to work out (RenderCollectContext::lightsSpared).
u32 lightsSpared = 0;
f32 gpu_time_ms = -1.0f; // -1 when the timer is unavailable
};
RenderFrame(GfxDevice& device, RenderContext& context,
resource::ResourceManager& resource_manager);
~RenderFrame();
RenderFrame(const RenderFrame&) = delete;
RenderFrame& operator=(const RenderFrame&) = delete;
void init(u32 width, u32 height);
void shutdown();
void resize(u32 width, u32 height);
void setShadowBudget(u32 atlasSize, u32 cellSize, u32 cascades);
void setShadowDistance(f32 distance);
/// How many samples across a light source a soft 2D shadow is drawn with: the quality level's say on the penumbra's smoothness and cost.
void setShadow2DSoftSamples(u32 samples);
/// Draws the opaque scene twice, depth alone first (see DrawList::DrawPass). Off unless asked: where a GPU already shades each pixel once
/// (a tiled one), the second pass is geometry paid for twice.
void setDepthPrepass(bool on) { depth_prepass_ = on; }
/**
* @brief The environment the sky lights the scene with (the Sky Atmosphere's, worked out by the SDK as the sky changes), or an
* invalid handle for none. An Ambient light that names no environment of its own lights with it.
*/
void setSkyEnvironment(resource::EnvironmentHandle environment) { sky_environment_ = environment; }
void setLightingDirect(bool on);
bool lightingDirect() const { return lighting_direct_; }
void setPlanarQuality(f32 scale, u32 maxSize, f32 updatesPerSecond);
/**
* @brief Note that a view drew a mesh with texture @p texture (a resource handle) where it needs @p side texels across for a texel to
* be about a pixel. The largest asked since the last take is kept.
*/
void wantTextureSide(u32 texture, f32 side) {
if (texture == 0 || !(side > 0.0f)) return;
f32& held = texture_wants_[texture];
if (side > held) held = side;
}
/** @brief What each texture was asked for since the last take, as `handle:side` pairs joined by commas; the record starts again. */
std::string takeTextureWants();
/** @brief The pixel height of the view being collected: what a texel is held to. */
f32 viewHeightPx() const { return static_cast<f32>(scene_viewport_.h > 0 ? scene_viewport_.h : height_); }
/** @brief An impostor's pictures: the atlas texture and how many frames along its side. */
struct ImpostorAtlas {
u32 texture = 0;
u32 frames = 0;
};
/** @brief Hand @p entity the atlas its Impostor draws from; a zero texture takes it away. */
void setImpostorAtlas(Entity entity, u32 texture, u32 frames) {
if (texture == 0 || frames < 2) { impostor_atlases_.erase(entity.raw); return; }
impostor_atlases_[entity.raw] = {texture, frames};
}
const ImpostorAtlas* impostorAtlas(Entity entity) const {
const auto it = impostor_atlases_.find(entity.raw);
return it == impostor_atlases_.end() ? nullptr : &it->second;
}
u32 planarTextureFor(Entity entity) const {
return entity == planar_receiver_ ? planar_texture_ : 0;
}
const PlanarConstants& planarConstants() const { return planar_constants_; }
std::string planarStatus(u32 view, u32 entity) const;
/** Geometry collected for this camera and drawn after its scene. */
void setPresentedOverlayDraw(ImmediateDraw* draw) { presented_overlay_draw_ = draw; }
/** @brief The frame's main-pass load-op: which attachments to clear, the color,
* and an optional region (w == 0 = full target — per-camera flows clear
* only their viewport on the shared default target). */
struct PassClear {
bool color = false;
bool depth = false;
glm::vec4 colorValue{0.0f, 0.0f, 0.0f, 1.0f};
i32 x = 0, y = 0;
u32 w = 0, h = 0;
};
/**
* @brief Opens the FRAME, once, before any of its cameras.
*
* @details begin()/end() bracket one CAMERA, so a decision that must hold
* steady across a frame cannot be made there. The scene's depth
* requirement is rolled forward and applied here
* (@ref applySceneDepthNeed), once, for every camera in the frame.
*/
void beginFrame();
void setPlanarTime(f32 seconds) { planar_elapsed_ = seconds; }
/**
* @brief Closes the FRAME, once, after every camera and every overlay.
*
* @details The pair of beginFrame, and the only place a backend that borrows
* the swapchain image gives it back. Releasing it in end(), which
* runs per CAMERA, leaves the post stack and the overlay drawing
* into an image the surface has taken away.
*/
void endFrame();
void begin(const glm::mat4& view_projection, RenderTargetManager::Handle target = 0);
void begin(const glm::mat4& view_projection, RenderTargetManager::Handle target,
const PassClear& clear);
void flush();
void end();
void processMasks(ecs::Registry& registry, i32 vpX, i32 vpY, i32 vpW, i32 vpH);
/// Same, resolved through @p projection rather than the current camera's —
/// a scissor rect is pixels, and which pixels a UI box covers is a question
/// only the projection that draws it can answer.
void processMasks(ecs::Registry& registry, const glm::mat4& projection,
i32 vpX, i32 vpY, i32 vpW, i32 vpH);
// ---- The screen-space overlay -------------------------------------------
//
// One pass a frame, after every camera and after post. The frame's, not a
// camera's: the projection comes from the layout domain.
/** @brief The screen's entities (UISystem::screenDomain), borrowed for the
* frame. Null partitions nothing — every collect is a world one. */
void setScreenDomain(const std::unordered_set<u32>* domain) { screen_domain_ = domain; }
/** @brief The layers of what a Canvas holds with no uiOrder, borrowed for the frame. @see ecs::UITreeOrder */
void setUITreeLayers(const std::unordered_map<u32, i32>* layers) { ui_tree_layers_ = layers; }
/** @brief Opens the overlay: @p projection maps the layout domain onto the
* pixel rect @p vpX/@p vpY/@p vpW/@p vpH of the surface. */
void beginScreenOverlay(const glm::mat4& projection, i32 vpX, i32 vpY, u32 vpW, u32 vpH);
/** @brief Collects the screen's renderables. Between this and
* endScreenOverlay a host may submit its own screen geometry (the
* SDK's glyph quads), which lands in the same list. */
void submitScreenOverlay(ecs::Registry& registry);
/** @brief Declares the overlay as a graph pass over @p target and runs it. */
void endScreenOverlay(RenderTargetManager::Handle target);
/** @brief Whether the overlay is open — what routes a host's submissions. */
bool screenOverlayOpen() const { return overlay_active_; }
void setEntityClipRect(u32 entity, i32 x, i32 y, i32 w, i32 h);
void clearAllClipRects();
void setEntityStencilMask(u32 entity, i32 refValue, bool hierarchical = false);
void setEntityStencilTest(u32 entity, i32 refValue, bool hierarchical = false);
void clearAllStencilMasks();
void submitTileQuad(
const glm::vec2& position, const glm::vec2& size,
const glm::vec2& uvOffset, const glm::vec2& uvScale,
const glm::vec4& color, u32 textureId,
Entity entity, i32 layer, f32 depth
);
/**
* Submit a batch of pre-laid-out glyph quads from TS. Same vertex format as
* submitSpineBatch (x,y,u,v,r,g,b,a per vertex), RenderType::Text, atlas page
* = `textureId`. `mode` picks the shader (see TextGlyphMode): Sdf → the SDF
* variant (scalable SDF atlas); Color → the plain textured batch (device-resolution
* bitmap atlas carrying native-AA coverage in alpha); Mask and Fill → the two
* ways a bitmap font with its outline baked into the page is read.
*/
void submitTextBatch(
const f32* vertices, i32 vertexCount,
const u16* indices, i32 indexCount,
u32 textureId, const f32* transform16,
Entity entity, i32 layer, f32 depth, TextGlyphMode mode, u32 cullBit = 0
);
/// The glyph quads of every label the text system laid out and handed over once, which the engine submits itself each frame.
RetainedTextStore& retainedText() { return retained_text_; }
/**
* @brief One offscreen render's resources, correct only together.
*
* @details Loose, they were one slot: two previews in flight overwrote each
* other's target, readback and pixels. As an object, a caller with
* its own preview owns its own surface.
*/
struct PreviewSurface {
RenderTargetManager::Handle target = 0;
ReadbackHandle readback = ReadbackHandle::Invalid;
std::vector<u8> pixels;
u32 width = 0;
u32 height = 0;
};
/**
* @brief Skeletal geometry a caller holds until it renders, owning its bytes.
*
* @details A scene's batches go straight into the frame being built. A
* preview's cross the ABI, wait for a render call, and are replayed
* — so they cannot be spans into the caller's scratch. Owning the
* bytes is what lets `submit` return and the caller reuse its buffer.
*/
struct PendingSkeletalBatch {
std::vector<f32> vertices;
std::vector<u16> indices;
u32 textureId = 0;
i32 blendMode = 0;
bool premultipliedColor = false;
glm::mat4 transform{1.0f};
Entity entity{};
i32 layer = 0;
f32 depth = 0.0f;
u32 materialId = 0;
};
/**
* @brief Batch vertices posed by a skeletal runtime, drawn as one entity's geometry.
* @details Serves every such runtime — Spine and DragonBones both arrive here — and
* links none of them: what crosses is x,y,u,v,r,g,b,a per vertex. @p materialId
* is the entity's material, resolved the way a Sprite's is (0 = the batch shader).
*
* A skeleton a Canvas holds paints by its place in the tree, like the controls round
* it (unless its author named a layer), and one a SCREEN Canvas holds is drawn by the
* screen overlay and by no camera: each call lands only in the collect it belongs to.
* @p treeAlpha is the opacity the UI tree above it multiplies in, and @p cullBit its
* Canvas' layer bit, as text carries them (0 = drawn by every camera).
*/
void submitSkeletalBatch(
const f32* vertices, i32 vertexCount,
const u16* indices, i32 indexCount,
u32 textureId, i32 blendMode,
const f32* transform16,
Entity entity, i32 layer, f32 depth, u32 materialId = 0, bool premultipliedColor = false,
f32 treeAlpha = 1.0f, u32 cullBit = 0
);
/** @brief Whether a Canvas holds @p entity with no uiOrder of its own (an emitter, a skeleton, a plain Sprite). */
bool uiTreeHolds(Entity entity) const {
return ui_tree_layers_ && ui_tree_layers_->count(entity.id()) != 0;
}
void setStage(RenderStage stage) { current_stage_ = stage; }
RenderStage getStage() const { return current_stage_; }
#ifdef ES_ENABLE_POSTPROCESS
PostProcessPipeline* postProcess() { return post_process_.get(); }
#endif
RenderTargetManager& targetManager() { return target_manager_; }
/**
* @brief Draws material @p material through @p shader (a PostProcess-domain shader) into the rect (x, y, w, h) of render target
* @p target, before the next frame's scene: a surface baked into a texture, as Unreal draws a material to a render target.
* @details The shader takes the material's values by name (MaterialStore::bindThrough), with @p a and @p b as its params
* `u_bakeA` and `u_bakeB`: what this one draw is of. A bake whose program is still compiling waits for it.
* @return A ticket for materialBakeState.
*/
u32 queueMaterialBake(u32 material, u32 shader, u32 target, u32 x, u32 y, u32 w, u32 h, const glm::vec4& a, const glm::vec4& b);
/** @brief A bake's state: 0 waiting, 1 drawn, -1 not drawable (no target, shader or material, or no post-processing in this build). A
* drawn or failed ticket is forgotten once asked. */
i32 materialBakeState(u32 ticket);
const Stats& stats() const { return stats_; }
FrameCapture& frameCapture() { return frame_capture_; }
/// Layers (bits 0..31) that sort by world Y within the layer — see DrawList::setYSortMask.
void setYSortLayers(u32 mask) { draw_list_.setYSortMask(mask); }
/// Layers (bits 0..31) that paint in hierarchy order within the layer — see DrawList::setTreeMask.
void setTreeSortLayers(u32 mask) { draw_list_.setTreeMask(mask); }
void setDepthLayers(u32 mask) {
draw_list_.setDepthMask(mask);
// Through the one applier: the mask is no longer the whole answer, only
// half of it. Before init there is no pipeline yet, and init asks again.
applySceneDepthNeed();
}
u32 depthLayers() const { return draw_list_.depthMask(); }
/// Layers the camera about to be collected renders — see DrawList::setCullingMask.
void setCullingMask(u32 mask) { draw_list_.setCullingMask(mask); }
/**
* @brief Names the view the camera about to be collected looks from, which is
* what its LOD levels are remembered under.
*
* @details Reset by begin(), so a camera that names none looks from the shared
* default view rather than inheriting the last camera's memory.
*/
void setViewId(u32 view) { view_id_ = view; }
/**
* @brief The LOD decision @p view last made about @p entity: the level, what
* the bare thresholds asked for, the stand-ins reachable, the size.
*
* @details A read of what was RECORDED where the choice was made: an editor
* explaining a level has to agree with the frame that drew it, and
* the only way to be sure is to not compute it twice.
*/
bool lodInspect(u32 view, Entity entity, u8& outLevel, u8& outUnbiased,
u8& outLevels, f32& outSize) const {
return lod_view_state_.inspect(view, entity, outLevel, outUnbiased, outLevels, outSize);
}
/**
* @brief Show @p level for @p entity in @p view instead of the level that
* view chose; @ref lod::kNoPreview goes back to choosing.
*
* @details View state, never component state: a group is authored policy and
* is the same everywhere. The choice is still made and remembered
* while a preview stands, so leaving one obeys the selector again.
*/
void setLodPreview(u32 view, Entity entity, u8 level) {
lod_view_state_.preview(view, entity, level);
}
/** @brief How many (view, entity) pairs are held up for inspection. */
usize lodPreviewCount() const { return lod_view_state_.previewCount(); }
/**
* @brief Shade @p view's meshes as @p mode says instead of as authored.
*
* @details View state, like a LOD preview: what the scene IS is the same
* everywhere, and what a creator wants to look at is decided by the
* window they are looking through.
*/
void setViewShading(u32 view, ShadingMode mode) { view_shading_.set(view, mode); }
/**
* @brief Capture the scene around @p position (world) into six @p face-pixel faces, one a frame, and read them back:
* a probe volume filled at run time (RenderFrameProbeCapture.cpp). A request replaces one in flight.
*/
void requestProbeCapture(const glm::vec3& position, u32 face);
/** @brief 0 = not yet, 1 = ready (probeCapturePixels), 2 = none asked for or it failed. Between frames only. */
i32 pollProbeCapture();
/** @brief The six faces side by side, +X -X +Y -Y +Z -Z, RGBM over 8 in RGBA8 (alpha 0 = nothing drawn), rows bottom-up. */
const std::vector<u8>& probeCapturePixels() const { return probe_capture_.pixels; }
/** @brief The grid a volume reads instead of its own `probes` (a capture's), or an invalid handle to stop. */
void setProbeVolumeOverride(u32 entity, resource::ProbeVolumeHandle grid);
/** @brief The volume on @p entity reflects column @p slot of @p environment (an atlas built from captures, column 0 the
* sky); an invalid environment stops. Used only where no baked ReflectionProbe is. */
void setProbeVolumeReflection(u32 entity, u32 environment, u32 slot) {
if (environment != 0 && slot != 0) probe_reflections_[entity] = {environment, slot};
else probe_reflections_.erase(entity);
}
/** @brief How many world units make a metre (the project's setting): what an inverse-square light measures in. */
void setWorldUnitsPerMeter(f32 units) {
world_units_per_meter_ = units > 0.0f ? units : 100.0f;
// The same answer for every default that is a length: a material's unset params follow it (MaterialParamSlot::worldUnits).
context_.materials().setWorldUnitsPerMeter(world_units_per_meter_);
}
/**
* @brief Colour @p entity in @p view by how much @p joint moves each of its vertices.
* @details View state like the shading beside it; an invalid entity goes back to none.
*/
void setViewSkinWeights(u32 view, Entity entity, u32 joint) { view_shading_.setWeights(view, entity, joint); }
/** @brief The mode @p view asked for; Shaded when it never did. */
ShadingMode viewShading(u32 view) const { return view_shading_.get(view); }
/**
* @brief What each caster asked the shadow atlas for last frame, and what it got.
*
* @details The answer to "why does this object have no shadow", which the engine
* could not give at all: tiles handed out were counted, refusals were not.
*/
const ShadowPlanReport& shadowPlan() const { return shadow_plan_; }
/**
* @brief Which lights the cap turned away last frame, and why.
*
* @details The count was logged and the identities were not, so "why is this
* light dark" could only be answered by deleting lights until one
* came back.
*/
const LightCapReport& lightCap() const { return light_cap_; }
/**
* @brief The editor view's own lighting, in place of the scene's.
*
* @details VIEW state, not scene state: nothing here is a component, nothing is
* saved, and a host that never calls the setter (every packaged build)
* lights the scene by its own lights exactly as before. In studio mode
* the frame ignores the scene's lights and lights with a neutral sky,
* a key and a fill, so a model the scene left dark can be read. The
* scene's environment may still be drawn as the BACKGROUND (`showSky`):
* seeing the sky and being lit by it are separate questions.
*/
struct ViewLighting {
bool studio = false;
/// Degrees about +Y that the key and fill turn together.
f32 rotation = 0.0f;
f32 keyIntensity = 0.8f;
f32 fillIntensity = 0.3f;
/// Scales the neutral sky's light; the scene's own Ambient is not consulted.
f32 skyIntensity = 1.0f;
/// Draw the scene's environment as the background while studio-lit.
bool showSky = false;
};
void setViewLighting(const ViewLighting& lighting) { view_lighting_ = lighting; }
const ViewLighting& viewLighting() const { return view_lighting_; }
/// Whether the frame found a scene environment it could draw as the background.
bool sceneSkyAvailable() const { return scene_sky_available_; }
/**
* @brief Switch the frame to linear-light rendering (project colorSpace).
* @details Sets the global ES_LINEAR shader input, linearizes CPU-side
* authored colors (lights, clears), and forces the post-process
* capture+blit so the final OETF encode always runs. Call before
* shaders compile; a later flip requires a reload.
*/
void setColorSpace(bool linear);
bool linearColor() const { return linear_color_; }
/**
* Asks for the captured frame's draws up to @p drawIndex. The replay runs on a
* later frame, right after the pass that drew it, so it draws from that pass's
* own list; the snapshot poll reports pending until then.
*/
void replayToDrawCall(i32 drawIndex);
/** Whether the replayed pass made as many draws as the captured one. False means
* the scene changed since the capture and the snapshot shows the later frame. */
bool snapshotMatchesCapture() const { return snapshot_matches_; }
const u8* getSnapshotPixels() const { return snapshot_pixels_.data(); }
u32 getSnapshotSize() const { return static_cast<u32>(snapshot_pixels_.size()); }
u32 getSnapshotWidth() const { return snapshot_w_; }
u32 getSnapshotHeight() const { return snapshot_h_; }
/**
* Lands the replay snapshot's async readback: 0 = still pending (poll again
* after yielding to the event loop), 1 = pixels are in the snapshot buffer
* (getSnapshot* serve them), 2 = no readback in flight / it failed.
* GL completes at request time, so the first poll reports 1 — callers use
* one polling loop for both backends.
*/
i32 pollSnapshotReadback();
/**
* Render @p registry once to an offscreen @p w×@p h target with @p viewProjection and read
* the RGBA pixels back (queried via getPreview*). A self-contained mini-frame (no
* post-process) reusing the real collect+execute path, so a material preview matches the
* viewport exactly. Clobbers the transient draw list/pool, which the next real frame rebuilds.
*/
void renderToTarget(ecs::Registry& registry, const glm::mat4& viewProjection, u32 w, u32 h);
const u8* getPreviewPixels() const { return preview_.pixels.data(); }
u32 getPreviewSize() const { return static_cast<u32>(preview_.pixels.size()); }
u32 getPreviewWidth() const { return preview_.width; }
u32 getPreviewHeight() const { return preview_.height; }
/** Lands the preview's async readback; same 0/1/2 contract as pollSnapshotReadback(). */
i32 pollPreviewReadback();
// — Skeletal previews —————————————————————————————————————————————————————
// Every call names its handle: no current preview, no mode, no begin/end
// pair, so two in flight cannot reach each other whatever the call order.
/** A skeletal preview's id. Carries a generation, so a destroyed one cannot
* come back pointing at whatever took its slot. */
using SkeletalPreviewId = u64;
/** A preview of @p w×@p h, or 0 when one cannot be made. */
SkeletalPreviewId createSkeletalPreview(u32 w, u32 h);
/** Hand one batch to @p id, which COPIES it: the caller may reuse its
* buffers the moment this returns. False for an id that is not live — a
* stale handle is a mistake worth hearing about, not a no-op. */
bool 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 = false);
/**
* Draw everything handed to @p id, and start its readback. CONSUMES the
* batches, so a render that fails cannot draw last frame's pose again.
*
* Refused while this preview's readback is in flight — one at a time keeps a
* landed image and the camera it was drawn with together.
*/
bool renderSkeletalPreview(SkeletalPreviewId id, const glm::mat4& viewProjection);
/** Lands @p id's readback: 0 pending, 1 pixels available, 2 nothing to read. */
i32 pollSkeletalPreview(SkeletalPreviewId id);
const u8* skeletalPreviewPixels(SkeletalPreviewId id) const;
u32 skeletalPreviewSize(SkeletalPreviewId id) const;
u32 skeletalPreviewWidth(SkeletalPreviewId id) const;
u32 skeletalPreviewHeight(SkeletalPreviewId id) const;
/**
* End @p id. Ownership ends here and the id stops answering; the target and
* any readback still in the device's hands are released the way every other
* one is, so nothing lands in freed memory.
*/
void destroySkeletalPreview(SkeletalPreviewId id);
void addPlugin(std::unique_ptr<RenderTypePlugin> plugin);
/**
* @brief Make ready the programs @p entities will need, drawing nothing.
*
* @details Ordinary renderer code, reachable by anything inside the engine —
* a residency lifecycle that wants a cell render-ready before it is
* seen would call THIS. The only thing gated to test builds is the
* WASM adapter that lets a driver call it from outside.
*/
RenderPrewarmResult prewarmPrograms(ecs::Registry& registry, const Entity* entities, u32 count);
/** @brief The same readiness, from a prepared cell's own description — no
* entity of it need exist. */
RenderPrewarmResult prewarmDocument(const MeshDocumentRecord* rows, u32 count);
void collectAll(ecs::Registry& registry, bool sceneGBuffer = true);
/** @brief Whether begin() opened a frame; false when it refused one for a lost device. */
bool inFrame() const { return in_frame_; }
/** @brief The vertex bytes staged for @p layout since the last begin(). */
u32 stagedVertexBytes(LayoutId layout) const { return pool_.vertexBytesUsed(layout); }
/**
* @brief Whether the camera being rendered right now would draw something of
* @p layer at these world bounds.
*
* @details The frame's OWN frustum and culling mask, both set by `begin`
* for the camera in hand — asked rather than reimplemented, so
* geometry from outside `collect` is culled by the same fact.
*/
bool visibleToCamera(i32 layer, const glm::vec3& center, const glm::vec3& halfExtents) const;
/**
* Compiled program id for a batch-shader feature variant, compiled+cached on
* first use. `{}` is the default batch program; `{"SDF"}`
* is the glyph-atlas SDF text variant. Same vertex layout + sampler/UBO setup
* as the default, so quads of any variant share the batch vertex format.
*/
u32 batchProgram(const std::vector<std::string>& features);
u32 premultipliedBatchProgram();
static constexpr u32 STAGE_COUNT = 4;
#ifdef ES_ENABLE_GPU_PARTICLES
/** Where emitters that simulate on the GPU queue their step, and find the buffer to draw (null before init). */
GpuParticles* gpuParticles() { return gpu_particles_.get(); }
#endif
private:
GfxDevice& device_;
RenderContext& context_;
resource::ResourceManager& resource_manager_;
ImmediateDraw* presented_overlay_draw_ = nullptr;
#ifdef ES_ENABLE_POSTPROCESS
Unique<PostProcessPipeline> post_process_;
#endif
#ifdef ES_ENABLE_GPU_PARTICLES
/// The compute-simulated particles' buffers live here, across frames: their state is the point of them.
Unique<GpuParticles> gpu_particles_;
#endif
RenderTargetManager target_manager_;
struct MaterialBake { u32 ticket; u32 material; u32 shader; u32 target; u32 x, y, w, h; glm::vec4 a, b; };
/// Bakes asked for and not yet declared, and each ticket's state (0 waiting, 1 drawn, -1 failed).
std::vector<MaterialBake> material_bakes_;
std::unordered_map<u32, i32> material_bake_states_;
u32 next_material_bake_ = 1;
u32 material_bakes_drawn_ = 0;
/// The frame the bakes were last declared in: once a frame, by its first view.
u64 material_bakes_frame_ = ~0ull;
glm::mat4 view_projection_{1.0f};
Frustum frustum_;
/// The other half of this camera's cull, rebuilt from the scene each collect.
OcclusionView occlusion_;
RenderTargetManager::Handle current_target_ = 0;
RenderStage current_stage_ = RenderStage::Transparent;
// Polls + lands one async readback: takes into @p pixels when Ready and
// resets @p handle. Returns the 0/1/2 contract of the public poll methods.
i32 pollReadback(ReadbackHandle& handle, std::vector<u8>& pixels, u32 w, u32 h);
/**
* The collect+execute body every preview shares, with an explicit target.
*
* @p extraSkeletalBatches replay AFTER `collectAll` — before it the draw
* list is cleared and they are dropped. A span, not a callback: a hook here
* would become where every future pass is inserted.
*/
void renderSurface(ecs::Registry& registry, const glm::mat4& viewProjection,
PreviewSurface& surface, u32 w, u32 h,
std::span<const PendingSkeletalBatch> extraSkeletalBatches);
Stats stats_;
/**
* ONE per frame, spanning the graph. GL's TIME_ELAPSED has a single global
* target and WebGPU's timestamps land in one queue, so a timer opened inside
* this one's span ends this query on GL and steals this reading on WebGPU.
*/
GpuTimer gpu_timer_;
/// Per-pass GPU times, made the first frame the profiler is on (it costs a query per pass).
Unique<rg::PassTimer> pass_timer_;
/// The profiler keeps a scope's name by pointer: "pass/<name>" per pass name, made once. Keyed by the timer's interned name.
std::unordered_map<const char*, std::string> pass_scope_names_;
f32 pass_graph_ms_ = -1.0f;
/// The graph's timer while it runs, so the scene's draws can be told to it a shader at a time (see drawScene).
rg::PassTimer* running_pass_timer_ = nullptr;
bool gpuDetailWanted() const;
FrameCapture frame_capture_;
std::vector<u8> snapshot_pixels_;
RenderTargetManager::Handle replay_rt_ = 0;
ReadbackHandle snapshot_readback_ = ReadbackHandle::Invalid;
i32 replay_pass_ = -1;
i32 replay_draw_ = -1;
bool snapshot_matches_ = false;
void runPendingReplay(const glm::mat4& projection, u32 w, u32 h);
void tallyPass(const DrawList& list);
void publishFrameCounters();
u32 frame_merged_ = 0;
u32 frame_breaks_[static_cast<u32>(BatchBreak::Count)] = {};
u32 snapshot_w_ = 0;
u32 snapshot_h_ = 0;
PreviewSurface preview_;
/** One editor preview: its own scene, its own surface, its own pending work. */
struct SkeletalPreview {
ecs::Registry registry;
Entity entity{};
std::vector<PendingSkeletalBatch> pending;
PreviewSurface surface;
};
/// The view an offscreen preview looks from: its own, so a thumbnail neither
/// reads nor writes the level a camera settled on for the same object.
static constexpr u32 kPreviewViewId = 0xFFFFFFFEu;
u32 view_id_ = 0;
lod::LodViewState lod_view_state_;
ViewShading view_shading_;
lod::SelectionCounts lod_counts_;
std::unordered_map<SkeletalPreviewId, Unique<SkeletalPreview>> skeletal_previews_;
/** Never reused, so a destroyed id can only ever be a destroyed id. */
SkeletalPreviewId next_skeletal_preview_ = 1;
SkeletalPreview* skeletalPreview(SkeletalPreviewId id);
const SkeletalPreview* skeletalPreview(SkeletalPreviewId id) const;
bool in_frame_ = false;
bool flushed_ = false;
/// Depth state for the capture's attachment — see applySceneDepthNeed.
/// Latched on for good: what once resolved by depth may leave the frustum.
bool depth_seen_ = false;
/// This frame's cameras, OR-ed; rolled into depth_seen_ at the next beginFrame.
bool frame_depth_seen_ = false;
/// A draw last frame could not work without a picture of the scene, so this frame's scene is drawn where one can be read.
bool scene_picture_seen_ = false;
bool frame_scene_picture_seen_ = false;
/// Whether this frame collected at all — an uncollected frame answers nothing,
/// so it must not be read as "nothing here needs depth".
bool frame_collected_ = false;
/// Whether ANY frame has answered yet. Until one has, the answer is "give it one".
bool depth_answered_ = false;
u32 width_ = 0;
u32 height_ = 0;
std::unordered_map<u32, ScissorRect> clip_rects_;
struct EntityStencilInfo {
i32 ref_value = 0;
bool is_mask = false;
bool hierarchical = false;
};
std::unordered_map<u32, EntityStencilInfo> stencil_masks_;
u32 batch_shader_id_ = 0;
// Compiled batch-shader variants keyed by ShaderParser::variantKey(features).
// {} → default, {"SDF"} → glyph-atlas text.
/// Variant key -> the shader HANDLE. Not the program id: rebuilding the
/// device changes every id, and the handle is what stays true across it.
std::unordered_map<std::string, resource::ShaderHandle> batch_variants_;
const resource::ShaderHandle* premultiplied_batch_handle_ = nullptr;
TransientBufferPool pool_;
DrawList draw_list_;
bool linear_color_ = false;
ClipState clip_state_;
std::vector<std::unique_ptr<RenderTypePlugin>> plugins_;
RenderFrameContext makeContext();
void buildClipState();
/// Resolves every SpriteMask into the stencil refs the draw path reads.
void buildSpriteMasks(ecs::Registry& registry);
/// Resolves every SortingGroup into the per-entity identity the draw path reads.
void buildSortingGroups(ecs::Registry& registry);
/// The hierarchy position of every entity, for the layers that paint in tree order (DrawList::setTreeMask).
void buildTreeSequence(ecs::Registry& registry);
/// Adds a finalized list's cost to this frame's tally (see the definition).
void accumulateStats(const DrawList& list);
/// The overlay pass's body: the projection its geometry was built for, then
/// the list. Runs inside the graph, like every other pass's draw.
void drawScreenOverlay();
/**
* @brief Tells the capture whether to carry a depth attachment.
*
* @details Chosen when the capture is BUILT, before this frame has collected,
* so the PREVIOUS frame answers and an unanswered one (boot) gets
* depth. Released once a frame proves nothing needs it, latched on
* once anything does — culling would make a per-frame answer flap.
*/
void applySceneDepthNeed();
/// Gathers the scene's enabled Light components into the per-frame LightConstants UBO
/// (point/directional into the light array, ambient summed). Run each frame in collectAll;
/// flush() uploads + binds the result so Lit material shaders read it.
void collectLights(ecs::Registry& registry);
/// collectLights' studio branch: the view's neutral light in place of the scene's.
void collectStudioLights(ecs::Registry& registry);
/** @brief Gathers the frame's LightProbeVolume components into the ProbeStore. */
void collectProbes(ecs::Registry& registry);
/**
* @brief Rasterises the scene's declared occluders into this camera's
* @ref occlusion_, which the collect below then tests bounds against.
*/
void collectOccluders(ecs::Registry& registry);
/** @brief Gathers the scene's reflection probes and binds the atlas they name. */
void collectReflections(ecs::Registry& registry);
void declarePlanarReflection(ecs::Registry& registry);
void declareProbeCapture(ecs::Registry& registry);
void executeProbeFace(ecs::Registry& registry);
struct ProbeCapture {
enum class State : u8 { Idle, Capturing, Drawn, Reading };
State state = State::Idle;
glm::vec3 position{0.0f};
u32 face = 32;
u32 next = 0;
u64 frame = ~0ull;
glm::mat4 viewProjection{1.0f};
Unique<Framebuffer> faces[6];
Unique<Framebuffer> atlas;
BufferHandle frameUbo = BufferHandle::Invalid;
ReadbackHandle readback = ReadbackHandle::Invalid;
std::vector<u8> pixels;
};
ProbeCapture probe_capture_;
std::unordered_map<u32, resource::ProbeVolumeHandle> probe_overrides_;
struct CapturedReflection { u32 environment = 0; u32 slot = 0; };
std::unordered_map<u32, CapturedReflection> probe_reflections_;
void executePlanarReflection(ecs::Registry& registry, u32 view);
struct PlanarCapture {
Unique<Framebuffer> target;
BufferHandle frameUbo = BufferHandle::Invalid;
Entity receiver = INVALID_ENTITY;
PlanarReflectionCamera camera;
u64 lastSeen = 0;
u64 generation = 0;
u32 revision = 0;
u32 mask = 0xFFFFFFFFu;
f32 lastTime = -1.0f;
u32 draws = 0;
u32 rejected = 0;
bool valid = false;
};
std::unordered_map<u32, PlanarCapture> planar_captures_;
TransientBufferPool planar_pool_{device_};
TransientBufferPool probe_pool_{device_};
DrawList probe_list_;
f32 world_units_per_meter_ = 100.0f;
/// The probe volumes' grids, packed for the per-pixel read (ProbeStore::layoutAtlas). Remade only when a grid
/// or the set of grids changes, so a still scene uploads it once.
Unique<Texture> probe_atlas_;
std::vector<u16> probe_atlas_texels_;
DrawList planar_list_;
u64 planar_frame_ = 0;
f32 planar_elapsed_ = 0;
f32 planar_scale_ = 0.5f;
bool planar_float_refused_ = false;
u32 planar_max_size_ = 1024;
f32 planar_rate_ = 0;
Entity planar_receiver_ = INVALID_ENTITY;
u32 planar_texture_ = 0;
/// Each impostor's atlas, by raw entity id: set by the SDK's bake, read by the mesh collect.
std::unordered_map<u32, ImpostorAtlas> impostor_atlases_;
/// The largest side each texture was asked for since the SDK last took the record (texture streaming).
std::unordered_map<u32, f32> texture_wants_;
PlanarConstants planar_constants_;
glm::vec4 scene_clear_{0.0f, 0.0f, 0.0f, 1.0f};
rg::ResourceId planar_resource_ = rg::kNoResource;
void releasePlanarCaptures();
/// Makes this ambient light the frame's environment, when it names one that is
/// loaded; `scale` (colour times intensity) is folded into the coefficients.
/// @p withoutSun lights with the sky alone, where a light casts its sun.
/// @return false when it names none, leaving the caller to add a flat term.
bool collectEnvironment(const ecs::Light& light, const glm::vec3& scale, bool withoutSun);
/// The environment an Ambient light lights with: its own, else the sky's (setSkyEnvironment).
resource::EnvironmentHandle environmentOf(const ecs::Light& light) const;
resource::EnvironmentHandle sky_environment_{};
/**
* @brief Decides what the shadow pass will draw, without drawing any of it.
*
* @details Runs in collectAll, where nothing may touch the GPU: it allocates
* the squares, builds each projection and drops the ones whose frustum
* misses the scene. The tiles are published before the scene collects,
* because the atlas id travels into every receiving draw's key.
*/
void buildShadowPlan(ecs::Registry& registry);
/**
* @brief Declares the pass that fills the atlas, ahead of the scene that reads it.
*
* @details Ordering is the graph's to know, not a matter of this call coming
* first: the scene names the atlas, so the graph keeps this pass alive
* and runs it before the one that samples it. @p registry is captured
* for the collect the pass does, and outlives execute().
*/
void declareShadowPass(ecs::Registry& registry);
/// The queued material bakes, as passes before the scene (queueMaterialBake).
void declareMaterialBakes();
/// Collects every planned square's occluders into its list, and answers what they would draw as one number
/// (shadow_drawn_key_): the squares, their views, the draws, their records and their materials. False when
/// something in them can change without the number changing (a material that moves its vertices, records a
/// compute pass wrote), and the atlas must be drawn whatever the number says.
bool collectShadowViews(ecs::Registry& registry, u64& key);
/// The shadow pass's body: the lists collectShadowViews made, drawn. The graph has bound and cleared the atlas.
void executeShadowPass();
/**
* @brief Gathers the frame's 2D occluders and hands the casting lights a mask channel.
*
* @details Runs inside collectLights, where nothing may touch the GPU: it turns each
* enabled ShadowCaster2D into world-space edges and picks which lights the
* mask can carry. A light past the cap keeps lighting the scene and stops
* shadowing — said out loud in the plan rather than silently.
*/
void collectShadow2D(ecs::Registry& registry);
/// Whether some light has a cookie the shape mask will draw, which keeps the texture unit the second shadow mask would take.
bool hasShape2DLight(ecs::Registry& registry);
/// Declares the pass that draws the mask, ahead of the scene that samples it.
void declareShadow2DPass();
/// The mask pass's body: the shadow each edge casts from each light, drawn with MIN
/// blending so a fragment keeps the darkest claim on it. The graph cleared the target.
void executeShadow2DPass(u32 mask);
/// Fills the vertices of mask @p mask (0: channels 0 to 3, 1: channels 4 to 7) with the geometry its pass draws.
void buildShadow2DGeometry(u32 mask);
/// Frees the mask's own GPU objects. Called while the device is still valid.
void releaseShadow2DResources();
/// Compiles the mask shader on first use, and says whether it is usable.
bool ensureShadow2DShader();
/// Whether this frame drew a mask — what the batch's slot budget and the sampler
/// binding both key off.
bool shadow2DActive() const { return shadow_2d_masks_[0].textureId != 0; }
/**
* @brief Gathers the frame's SHAPED lights and hands each one a shape-mask channel.
*
* @details The sibling of collectShadow2D, in the same no-GPU phase: a light with a
* cookie gets a channel, and past the cap a light lights without a shape.
*/
void collectShape2D(ecs::Registry& registry);
/// Declares the pass that draws the shape mask, ahead of the scene that samples it.
void declareShape2DPass();
/// The shape pass's body: one textured quad per shaped light, into its own channel.
void executeShape2DPass();
/// Frees the shape mask's own GPU objects. Called while the device is still valid.
void releaseShape2DResources();
/// Compiles the shape shader on first use, and says whether it is usable.
bool ensureShape2DShader();
/// Whether this frame drew a shape mask.
bool shape2DActive() const { return shape_2d_texture_id_ != 0; }
/// Grows the per-view frame-constant buffers to @p count and no further.
void ensureShadowFrameUbos(u32 count);
/// Deletes them. Device loss and shutdown: the handles name nothing afterwards.
void releaseShadowFrameUbos();
/// The scene pass's body: the draw, and the constants it needs current.
void drawScene(DrawList::Phase phase = DrawList::Phase::All);
/// Shared colour submission for scene and reflected views, including the quality policy's depth prepass and shader timings.
void submitColorList(DrawList& list, TransientBufferPool& buffers, FrameCapture* capture,
DrawList::Phase phase, const char* prepassCounter);
/// Drops the atlas texture id the frame published; its target is the graph's
/// to give back.
void releaseFrameTargets();
struct MeshBounds {
glm::vec3 min{0.0f}, max{0.0f};
bool valid = false;
void include(const glm::vec3& centre, const glm::vec3& half) {
min = valid ? glm::min(min, centre - half) : centre - half;
max = valid ? glm::max(max, centre + half) : centre + half;
valid = true;
}
};
struct ShadowBounds { MeshBounds all, casters, hair; };
/// One traversal supplies receiver coverage, caster depth and the hair focus cascade from the geometry actually drawn.
ShadowBounds gatherShadowBounds(ecs::Registry& registry, bool includeHair);
/// Opens the frame's own target with @p clear's load-op, for begin() to bind it
/// eagerly. Every other pass of the frame is the graph's to open.
void openPass(const PassClear& clear, RenderTargetManager::Handle target);
u32 initBatchShader();
resource::ShaderHandle compileBatchVariant(const std::vector<std::string>& features);
/**
* @brief What a light needs a shadow map FOR — everything the pass differs by.
*
* @details A sun's map covers a stretch of the view, a spot's its cone and a point's
* every direction, so the three build different projections and share the
* pass after that. A description rather than a flag on the light, because
* the cap sort reorders those and this has to survive it.
*/
struct ShadowCaster {
u32 slot = 0;
/// The light that asked. Carried for the same reason `slot` is — the cap sort
/// reorders these, and a refusal has to be able to name who was refused.
Entity light{};
ShadowShape shape = ShadowShape::Box;
/// Which way it points — the aim, not the direction light travels. A cube aims
/// six ways of its own and reads none of it.
glm::vec3 dir{0.0f, 0.0f, -1.0f};
/// Where it stands. Cone and cube only; a sun has no position.
glm::vec3 pos{0.0f};
/// Box: a fixed reach, or 0 to fit what the camera can see.
f32 extent = 0.0f;
/// Cone and cube: how far the falloff reaches, and how wide one cone opens in
/// degrees — a cube's six are right angles and do not read the angle.
f32 range = 0.0f;
f32 outerAngle = 0.0f;
};
/// A collected light and the map it asked for, if any. Paired rather than flagged
/// inside the GPU struct, because the cap sort reorders these and the answer has
/// to travel with the light.
struct CollectedLight {
GpuLight gpu;
bool castsMeshShadow;
ShadowCaster caster;
};
std::vector<CollectedLight> light_scratch_; // reused across frames; collectLights only
/// Every light that asked for a map this frame, in UBO slot order. Written by
/// collectLights, read by buildShadowPlan; empty = nobody asked.
std::vector<ShadowCaster> shadow_casters_;
/// The directional light the sky's clouds shade (the first in slot order, which is the one a sky takes for its sun): its slot
/// and the way its rays travel, as collectLights found it; slot -1 when the frame has none.
i32 cloud_sun_slot_ = -1;
glm::vec3 cloud_sun_aim_{0.0f, -1.0f, 0.0f};
/// The atlas tile the sky draws the sun's cloud shadow into this frame, or -1, and the matrix it is drawn and read through:
/// along the sun's rays, round the camera, as Unreal's cloud shadow map is.
i32 cloud_tile_ = -1;
glm::mat4 cloud_matrix_{1.0f};
/// The frame's render targets, borrowed by shape and given back when the
/// frame is done with them — shared with the post chains, which is what lets
/// the atlas be a loan rather than a framebuffer held for the whole run.
rg::TargetPool target_pool_;
/// Every pass a frame runs, declared in one place and executed in end():
/// the scene, and the post chains that read it. One per CAMERA, which is
/// what a chain has always been — begin() opens it, end() runs it.
rg::RenderGraph graph_;
/// What the scene draws into, declared at begin(): the post capture when a
/// chain is engaged, the frame's own target otherwise.
rg::ResourceId scene_resource_ = rg::kNoResource;
/// The framebuffer behind it, bound eagerly so a host draw between calls
/// (the editor's grid) lands in the scene rather than on the screen.
FramebufferHandle scene_fbo_ = FramebufferHandle::Default;
/// The camera's rect within its target; the scene pass carries it.
GfxDevice::Viewport scene_viewport_{};
/**
* @brief One occluder's outline in @ref shadow_points_2d_ — what a shadow is cast from.
*
* @details A ring rather than loose edges: a shadow is thrown by the SILHOUETTE —
* the two points of the outline a light sees the edges of — and what lies
* behind it is one shadow. Per edge, the shadows of one box overlap, and
* the overlap is a question a ring never raises.
*/
struct ShadowRing2D {
u32 first = 0;
u32 count = 0;
/// The middle of its points and how far the furthest is from it: what a light tests its reach against.
glm::vec2 centre{0.0f};
f32 radius = 0.0f;
};
/** @brief A light whose 2D shadows the frame draws, and the mask channel it owns. */
struct Shadow2DLight {
/// Where it stands. A directional light has no position and uses @ref dir.
glm::vec2 pos{0.0f};
/// The way a directional light's rays travel; zero for the others.
glm::vec2 dir{0.0f};
/// How far its shadows reach: a point/spot light's radius, a directional
/// light's march distance. Past it the light contributes nothing to shadow.
f32 reach = 0.0f;
/// Half-extent of the source, in world units — what widens the penumbra.
f32 softness = 0.0f;
/// Its slot in the light array (or, for a tiled light, its index in the tiled list), which is what the channel is recorded against.
u32 slot = 0;
/// The mask channel it draws into and is read from. Lights that cannot meet share one (see ShadowChannels2D.hpp).
u32 channel = 0;
/// A light of the tiled list, past the loop's sixteen.
bool tiled = false;
bool directional = false;
};
std::vector<glm::vec2> shadow_points_2d_;
std::vector<ShadowRing2D> shadow_rings_2d_;
std::vector<Shadow2DLight> shadow_2d_lights_;
/// How many casting lights the last collect could give no channel.
u32 shadow_2d_unplaced_ = 0;
/// The mask as a graph resource: the 2D shadow pass writes it, the scene reads it
/// through a pinned sampler unit rather than a graph-bound one.
/// One mask of the shadow channels: [0] carries channels 0 to 3, [1] channels 4 to 7 and exists only when a light holds one of those.
struct Shadow2DMask {
rg::ResourceId resource = rg::kNoResource;
u32 textureId = 0;
/// Interleaved (x, y, shadow, channel.rgba) — built on the CPU each frame, because
/// the geometry is a function of where every light stands.
std::vector<f32> vertices;
BufferHandle vbo = BufferHandle::Invalid;
u32 vboBytes = 0;
};
Shadow2DMask shadow_2d_masks_[2];
RetainedTextStore retained_text_;
VertexLayoutHandle shadow_2d_layout_ = VertexLayoutHandle::Invalid;
resource::ShaderHandle shadow_2d_shader_{};
bool shadow_2d_shader_tried_ = false;
/** @brief A light whose shape the frame draws, and the mask channel it owns. */
struct Shape2DLight {
/// The quad's four world corners, in the order the two triangles take them.
glm::vec2 corners[4]{};
/// The cookie itself — one draw per light, because each binds its own.
u32 texture = 0;
/// Its slot in the light array, which is what the channel is recorded against.
u32 slot = 0;
};
std::vector<Shape2DLight> shape_2d_lights_;
/// The shape mask as a graph resource, read through its own pinned sampler unit.
rg::ResourceId shape_2d_resource_ = rg::kNoResource;
u32 shape_2d_texture_id_ = 0;
/// Interleaved (x, y, u, v, channel.rgba), six vertices per light.
std::vector<f32> shape_2d_vertices_;
BufferHandle shape_2d_vbo_ = BufferHandle::Invalid;
u32 shape_2d_vbo_bytes_ = 0;
VertexLayoutHandle shape_2d_layout_ = VertexLayoutHandle::Invalid;
resource::ShaderHandle shape_2d_shader_{};
bool shape_2d_shader_tried_ = false;
/// The atlas as a graph resource: the shadow pass writes it and the scene names
/// it, which is what orders the two. Borrowed from the pool every other target
/// comes from. kNoResource = no map this frame.
rg::ResourceId shadow_resource_ = rg::kNoResource;
/**
* @brief One square of the atlas, and what fills it.
*
* @details Decided on the CPU: by the time the pass runs, where it draws and what
* it looks through are already answered, and all that is left is the draw.
*/
struct ShadowView {
glm::mat4 view_projection{1.0f};
u32 x = 0;
u32 y = 0;
u32 size = 0;
/// A sun's map: the way its rays travel, the lowest height a receiver can stand at and how far a shadow can reach, so a caster whose
/// shadow falls outside the camera's view is not drawn into it.
bool sun = false;
glm::vec3 ray{0.0f, -1.0f, 0.0f};
f32 floorY = 0.0f;
f32 reachCap = 0.0f;
};
/// Whether a sun's map leaves out the casters whose shadow cannot reach the camera's view.
bool shadow_receiver_cull_ = true;
/// What the pass will draw, in atlas order. Empty = nothing asked for a map, and
/// no pass is declared.
std::vector<ShadowView> shadow_views_;
/**
* @brief The shadow pass's own transient buffers and draw list.
*
* @details Not the scene's. By the time the graph runs the pass, flush() has
* finalized and uploaded the scene's list, and the scene pass is still to
* come — a shadow collect through the same pool would overwrite the
* vertices the scene is about to draw from.
*/
TransientBufferPool shadow_pool_;
/**
* @brief The motion pass's own buffers and draw list, for the same reason as the shadow pass's:
* the scene's list is finalized and uploaded before this one is collected.
*/
TransientBufferPool velocity_pool_;
DrawList velocity_list_;
/// This frame's shift, kept from the collect so the pass draws through the camera the scene did.
glm::vec2 velocity_jitter_{0.0f};
/// Collects the meshes that moved by themselves since the last frame into velocity_list_.
void collectMotion(ecs::Registry& registry);
void executeMotionPass();
/**
* @brief The scene seen from straight above, depth only, around the camera — what stands over each place.
*
* @details Collected like a shadow map (the depth variant of every resident mesh) through a camera of its own, because
* what an effect asks of it is whether something is above a point, and a shadow map from the sun answers that for
* the sun's direction only. Its own buffers and list, for the same reason as the motion pass's.
*/
void collectCover(ecs::Registry& registry);
void executeCoverPass();
TransientBufferPool cover_pool_;
DrawList cover_list_;
BufferHandle cover_frame_ubo_ = BufferHandle::Invalid;
glm::mat4 cover_view_projection_{1.0f};
/// The shift the scene was drawn with, so a pass that borrows the frame's constants can hand them back as they were.
glm::vec2 scene_jitter_{0.0f};
/// Whether the opaque scene is drawn twice, depth alone first. See DrawList::DrawPass.
bool depth_prepass_ = false;
bool lighting_direct_ = false;
/// One per view, kept across frames for the capacity. The whole pass is collected
/// before any of it is drawn, so a view's commands have to outlive its collect.
std::vector<DrawList> shadow_view_lists_;
/// The atlas, kept from frame to frame so that a frame whose squares would draw what they already hold need not draw them:
/// a still sun over a still scene, a lamp in a room. Pooled, it was any target of its size the graph had free that frame.
Unique<Framebuffer> shadow_target_;
/// What the atlas holds: the key collectShadowViews made the frame it was last drawn, and whether that drawing can be trusted
/// to stand. Drawing it again or not is the only thing the key decides.
u64 shadow_drawn_key_ = 0;
bool shadow_drawn_valid_ = false;
/// What this frame's pass will vouch for once it has drawn.
u64 shadow_pending_key_ = 0;
bool shadow_pending_trusted_ = false;
/// The frame's own answer, from collectShadowViews to the pass that draws (or does not).
bool shadow_reused_ = false;
/// What the collect that made shadow_drawn_key_ read (shadowInputs), when every caster vouched for it: a frame whose inputs
/// match need not collect at all, since the collect would come back with the key the atlas already holds.
u64 shadow_drawn_inputs_ = 0;
bool shadow_drawn_inputs_valid_ = false;
u64 shadow_pending_inputs_ = 0;
bool shadow_pending_inputs_valid_ = false;
/// Frames the change audit found the inputs matching while the collect did not (render.shadow.inputsStale): a bug.
u32 shadow_inputs_stale_ = 0;
bool warned_shadow_inputs_ = false;
/** @brief One number for what the shadow collect reads, or false when a caster cannot say. */
bool shadowInputs(ecs::Registry& registry, u64& key);
u32 shadow_casters_culled_ = 0;
/// The maps and draws the atlas holds, from the frame that last drew it (render.shadow.heldTiles / heldDraws).
u32 shadow_held_tiles_ = 0;
u32 shadow_held_draws_ = 0;
/// One FrameConstants buffer per view, grown to the busiest frame and never shrunk.
/// A buffer write lands on the queue, not between two draws already recorded into
/// an open pass — so what tells one view from another is which buffer is BOUND.
std::vector<BufferHandle> shadow_frame_ubos_;
/// Who owns which square of the atlas. Rebuilt every frame: a tile means
/// nothing once the depths in it belong to a frame that is gone.
ShadowAtlas shadow_atlas_{kShadowAtlasSize, kShadowCellSize};
u32 shadow_atlas_size_ = kShadowAtlasSize;
u32 shadow_cell_size_ = kShadowCellSize;
u32 shadow_cascades_ = MAX_SHADOW_CASCADES;
f32 shadow_distance_ = 0.0f;
u32 shadow_2d_soft_samples_ = 16;
ShadowPlanReport shadow_plan_;
ShadowPlanReport previous_shadow_plan_;
LightCapReport light_cap_;
ViewLighting view_lighting_;
bool scene_sky_available_ = false;
/// The map's colour texture, handed to every mesh that receives it. 0 = none this frame.
u32 shadow_texture_id_ = 0;
/// The frame environment's reflection atlas, on the same terms. 0 = none this frame.
u32 environment_texture_id_ = 0;
/// Whether that environment is also the background this frame.
bool draw_sky_ = false;
/// The far-plane quad's program, compiled on first use.
u32 sky_texture_id_ = 0;
/// The atlas variant, then the panorama one; each compiled when first drawn.
u32 sky_programs_[2] = {};
bool sky_compiled_[2] = {};
/// Emits the background quad when an environment asked to be seen behind the scene.
void collectSky(RenderCollectContext& ctx);
/// Borrowed from the UI system for the frame (see setScreenDomain).
const std::unordered_set<u32>* screen_domain_ = nullptr;
const std::unordered_map<u32, i32>* ui_tree_layers_ = nullptr;
bool overlay_active_ = false;
glm::mat4 overlay_projection_{1.0f};
i32 overlay_vp_x_ = 0, overlay_vp_y_ = 0;
u32 overlay_vp_w_ = 0, overlay_vp_h_ = 0;
/// buildSpriteMasks scratch, reused across cameras/frames.
std::vector<ResolvedMask> sprite_mask_scratch_;
std::vector<Entity> mask_entities_scratch_;
// processMasks scratch, reused across cameras/frames.
std::vector<Entity> mask_scissor_scratch_;
std::vector<Entity> mask_stencil_scratch_;
std::vector<Entity> mask_root_scratch_;
std::vector<std::pair<Entity, ScissorRect>> mask_scissor_walk_scratch_;
std::vector<std::pair<Entity, i32>> mask_stencil_walk_scratch_;
std::unordered_set<u32> mask_set_scratch_;
std::unordered_set<u32> stencil_set_scratch_;
};
} // namespace esengine