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
#pragma once
#include "../core/Types.hpp"
#include "./RenderOrigin.hpp"
#include "./frame/RenderStage.hpp"
#include "./frame/Frustum.hpp"
#include "./frame/OcclusionView.hpp"
#include "./lod/LodSelection.hpp"
#include "./lod/LodViewState.hpp"
#include "./frame/ViewShading.hpp"
#include "./frame/FrameConstants.hpp"
#include "./draw/RenderItem.hpp"
#include "./draw/DrawCommand.hpp"
#include "./draw/DrawList.hpp"
#include "./draw/ClipState.hpp"
#include "./rhi/TransientBufferPool.hpp"
#include "../ecs/Registry.hpp"
#include "../ecs/components/Transform.hpp"
#include "../resource/ResourceManager.hpp"
#include <glm/glm.hpp>
#include <glm/gtc/matrix_access.hpp>
#include <glm/gtc/quaternion.hpp>
#include <cmath>
#include <algorithm>
#include <array>
#include <unordered_map>
#include <unordered_set>
#include <vector>
namespace esengine {
class RenderContext;
class MaterialStore;
class RenderFrame;
/**
* @brief What a collect is FOR — the phase, not a feature the geometry has.
*
* @details A shadow collect draws the scene's meshes from somewhere else for a
* different answer: depth only, no material, no light. A bool per phase
* would multiply as the frame gains passes, and two could be set at
* once — which no phase ever is.
*/
enum class RenderPurpose : u8 {
Scene,
ShadowDepth,
/// The frame's screen-space overlay: one pass after every camera and after
/// post, drawing what belongs to the screen rather than the world. It has no
/// camera — the projection it is given comes from the layout domain.
ScreenOverlay,
/// The pass that writes how far each moving surface travelled since last frame, for the temporal
/// effects: the scene's meshes again, only those that moved, through a program that writes motion.
Motion,
};
struct RenderFrameContext {
RenderContext& render_context;
resource::ResourceManager& resources;
u32 white_texture_id = 0;
u32 batch_shader_id = 0;
RenderStage current_stage = RenderStage::Transparent;
glm::mat4 view_projection{1.0f};
const MaterialStore* materials = nullptr;
/// The owning frame, for lazily-compiled batch variants (RenderFrame::batchProgram).
RenderFrame* frame = nullptr;
/// What this collect is for. The frame sets it, and also skips every plugin
/// that casts nothing when the purpose is a shadow map.
RenderPurpose purpose = RenderPurpose::Scene;
/// The map that pass produced, handed to the meshes that receive it (0 = none).
u32 shadow_texture_id = 0;
/// The frame environment's prefiltered reflection atlas (0 = none this frame).
u32 environment_texture_id = 0;
/// The pass these draws execute in has a second colour attachment for the surface's material, so a
/// shader that can write it is asked for the variant that does. False for every other collect.
bool gbuffer = false;
/// A temporal effect in the chain reads per-object motion, so the scene collect remembers where each mesh
/// was, and the Motion collect has something to compare against. Per view: `motion_key` names which.
bool track_motion = false;
u64 motion_key = 0;
u64 motion_frame = 0;
/// Last frame's view-projection (the engine's convention, unjittered) and the shift in NDC that frame was
/// drawn with: what the Motion collect writes into each record, so a displacement lands on the raster the
/// previous picture was actually drawn on.
glm::mat4 motion_prev_view_projection{1.0f};
glm::vec2 motion_prev_jitter{0.0f};
/// Where the SCENE camera is, in every collect of the frame (a shadow map's included): what a distance-limited draw measures from.
/// Absent for an orthographic camera, which has no position to be far from.
glm::vec3 view_eye{0.0f};
bool has_view_eye = false;
bool lighting_direct = false;
/// This shadow-depth collect is the RAIN's map of what stands overhead, not a light's: what keeps rain off is solid
/// whether or not light passes it, so a see-through surface that casts no shadow (a glass roof) is in it all the same.
/// Last, so the positional initialisers before it keep their places.
bool rainCover = false;
};
/** @brief What every plugin needs to know about the camera, derived once per collect
* from the inverse view-projection — the single source for parallax, world-rect
* culling and the depth draws are sorted by (each previously re-derived, or in
* the depth's case assumed, inside the plugins). */
struct CameraView {
f32 left = 0.0f, bottom = 0.0f, right = 0.0f, top = 0.0f;
glm::vec2 center{0.0f};
/// Where the frame is seen from, in FrameConstants::camera's convention: the
/// eye's world position when w = 1, or the unit direction pointing at the
/// viewer when w = 0. From cameraFromViewProjection, as the shaders' copy is.
glm::vec4 eye{0.0f, 0.0f, 1.0f, 0.0f};
/**
* @brief How near @p worldPos is to the viewer, larger = nearer — the order the
* sort key wants, and the one world z gives only while the camera looks
* down -Z. Orthographic projects onto the viewer direction (head-on that
* is worldPos.z exactly); perspective answers with -distance to the eye.
*/
f32 viewDepth(const glm::vec3& worldPos) const {
if (eye.w < 0.5f) return glm::dot(worldPos, glm::vec3(eye));
return -glm::length(worldPos - glm::vec3(eye));
}
};
inline CameraView computeCameraView(const glm::mat4& viewProjection) {
glm::mat4 invVP = glm::inverse(viewProjection);
glm::vec4 bl = invVP * glm::vec4(-1.0f, -1.0f, 0.0f, 1.0f);
glm::vec4 tr = invVP * glm::vec4( 1.0f, 1.0f, 0.0f, 1.0f);
CameraView view;
view.left = bl.x / bl.w;
view.bottom = bl.y / bl.w;
view.right = tr.x / tr.w;
view.top = tr.y / tr.w;
view.center = { (view.left + view.right) * 0.5f, (view.bottom + view.top) * 0.5f };
view.eye = cameraFromViewProjection(viewProjection);
return view;
}
/**
* @brief What a renderable's program key is made of, with no say in where the
* facts came from — a live entity's components, or a PREPARED cell's
* document. One combination, so the two can be shown to agree.
*/
/**
* @brief One renderable as a PREPARED cell knows it: document fields plus the
* handles its preparation decoded. Five words, so the boundary that
* carries it needs no encoding.
*/
struct MeshDocumentRecord {
u32 meshHandle = 0;
u32 lit = 0;
u32 normalMapHandle = 0;
u32 jointCount = 0;
u32 materialId = 0;
};
struct MeshProgramFacts {
bool hasNormals = false;
bool lit = false;
u32 normalTextureId = 0;
bool skinned = false;
/** Whether the GEOMETRY can be read through a bake — it carries the second UV
* set, and is not posed by bones. Whether it HAS one is the atlas rectangle
* in its record, which is a number rather than a program. */
bool lightmapped = false;
/** Whether the geometry carries a tangent frame (with its normals): the program then declares and reads it. */
bool tangents = false;
/** Whether it draws unblended (MeshRenderer.opaque). A document row does not say, and most meshes are, so readying assumes so. */
bool opaque = true;
u32 materialId = 0;
};
/** @brief What readying a set of renderables' programs found. Counts, not JSON:
* this crosses no boundary and pays for no encoding. */
struct RenderPrewarmResult {
u32 asks = 0;
u32 compiles = 0;
/** Distinct variant keys the content needed — the dimension of the answer. */
u32 uniqueKeys = 0;
u32 materialAsks = 0;
u32 materialCompiles = 0;
/** Which keys, not how many: an equality claim needs the set. One bit per
* MESH_VARIANTS, so it is two words rather than one. */
std::array<u64, MESH_VARIANTS / 64> keys{};
/** @brief Whether this key is already in the set; adds it if not. */
bool addKey(u32 variant) {
u64& word = keys[variant / 64];
const u64 bit = 1ull << (variant % 64);
if (word & bit) return false;
word |= bit;
return true;
}
/** The material programs the content needs, by identity rather than count.
* A material world whose shading changed must not digest the same as the
* one before it, and `materialAsks` alone cannot say that. */
std::vector<u64> materialKeys;
/** @brief What a material program is asked for, as one comparable value. */
static u64 materialKey(u32 materialId, bool normals, bool skinned, bool envMapped,
bool lightmapped, bool tangents = false) {
return (static_cast<u64>(materialId) << 5) | (tangents ? 16u : 0u) | (lightmapped ? 8u : 0u) | (normals ? 4u : 0u)
| (skinned ? 2u : 0u) | (envMapped ? 1u : 0u);
}
void addMaterialKey(u64 key) {
if (std::find(materialKeys.begin(), materialKeys.end(), key) == materialKeys.end()) {
materialKeys.push_back(key);
}
}
/**
* @brief A stable name for the SET of program requirements described here.
*
* @details Order-independent and duplicate-insensitive, because the question
* is which programs are needed and not how often each was asked
* for. Two derivations of the same content therefore agree, and a
* requirement arriving or leaving is what changes the answer.
*/
u64 requirementDigest() const {
std::vector<u64> sorted(materialKeys);
std::sort(sorted.begin(), sorted.end());
u64 h = 1469598103934665603ull; // FNV-1a offset basis
auto mix = [&h](u64 v) {
for (u32 b = 0; b < 8; ++b) {
h ^= (v >> (b * 8)) & 0xFFull;
h *= 1099511628211ull;
}
};
for (u64 word : keys) mix(word);
for (u64 k : sorted) mix(k);
return h;
}
RenderPrewarmResult& operator+=(const RenderPrewarmResult& other) {
asks += other.asks;
compiles += other.compiles;
uniqueKeys += other.uniqueKeys;
materialAsks += other.materialAsks;
materialCompiles += other.materialCompiles;
for (usize w = 0; w < keys.size(); ++w) keys[w] |= other.keys[w];
// A union, so combining two plugins' answers cannot depend on the order
// they ran in — the digest above rests on that.
for (u64 k : other.materialKeys) addMaterialKey(k);
return *this;
}
};
struct RenderCollectContext {
ecs::Registry& registry;
const Frustum& frustum;
const ClipState& clip_state;
TransientBufferPool& buffer_pool;
DrawList& draw_list;
RenderFrameContext& frame_context;
CameraView camera;
/**
* @brief The entities the SCREEN owns (UISystem::screenDomain), or null.
*
* @details A set rather than the UI system itself, so the renderer keeps
* knowing nothing about UI: what it needs is a membership answer,
* and that is all a set is.
*/
const std::unordered_set<u32>* screen_ui = nullptr;
/** @brief The layer of each emitter and plain Sprite a Canvas holds, by entity id, or null. @see ecs::UITreeOrder */
const std::unordered_map<u32, i32>* ui_tree_layers = nullptr;
/**
* @brief The layer @p entity draws at: its place in a Canvas's tree, unless its author named one.
* @details 0 is the default, and says nothing. A layer named outright is the way to hold something over or under a whole UI.
*/
i32 treeLayer(Entity entity, i32 authored) const {
if (authored != 0 || !ui_tree_layers) return authored;
const auto it = ui_tree_layers->find(entity.id());
return it == ui_tree_layers->end() ? authored : it->second;
}
/**
* @brief What this view is already blocked by, or null for a collect that
* must not ask — a shadow face looks from a light, and a camera's
* answer about what a camera cannot see says nothing about it.
*/
const OcclusionView* occlusion = nullptr;
Entity excluded = INVALID_ENTITY;
/**
* @brief A sun's shadow map only: the camera's frustum, which is what its shadows are worth drawing for, and the way the rays travel.
*
* @details A caster's shadow is the segment its sphere sweeps along the rays down to the lowest receiver. A caster whose segment stays
* outside the camera's frustum shades nothing the camera sees, so the map need not hold it. Null: every caster is drawn.
*/
const Frustum* shadowReceivers = nullptr;
glm::vec3 shadowRay{0.0f, -1.0f, 0.0f};
f32 shadowFloor = 0.0f;
f32 shadowReachCap = 0.0f;
/// How many casters that left out.
u32 shadowCulled = 0;
/** @brief Whether a caster bounded by a sphere can shade anything the camera sees. True where this collect asks no such thing. */
bool castsIntoView(const glm::vec3& centre, f32 radius) {
if (!shadowReceivers) return true;
f32 length = shadowReachCap;
if (shadowRay.y < -1e-3f) length = std::min(length, std::max(centre.y - shadowFloor + radius, 0.0f) / -shadowRay.y);
if (shadowReceivers->intersectsSweptSphere(centre, centre + shadowRay * length, radius)) return true;
++shadowCulled;
return false;
}
/** @brief Whether this collect is the frame's screen overlay. */
bool isOverlay() const { return frame_context.purpose == RenderPurpose::ScreenOverlay; }
/**
* @brief Whether @p entity belongs to THIS collect.
*
* @details One predicate, not a test on each side: the two collects partition
* the world, and two tests drifting apart is how something is drawn
* twice — or by nobody, which is what a 3D HUD was.
*/
bool accepts(Entity entity) const {
if (entity == excluded) return false;
const bool screen = screen_ui && screen_ui->count(entity.id()) != 0;
return isOverlay() == screen;
}
/**
* @brief Whether a renderable bounded by @p centre / @p halfExtents is drawn.
*
* @details TWO questions, one answer: outside the view, and inside it behind
* something solid. @p depthTested admits the second — an occluder may
* refuse only a draw a DEPTH TEST would have hidden anyway, since one
* that ignores depth paints over the wall and really is seen.
*/
bool visible(const glm::vec3& centre, const glm::vec3& halfExtents, bool depthTested) {
// A screen element is on the screen by construction, with no camera to be
// outside of — a frustum test would ask about wherever one is looking.
if (isOverlay()) return true;
if (!frustum.intersectsAABB(centre, halfExtents)) return false;
if (depthTested && occlusion && occlusion->hidden(centre, halfExtents)) {
++occluded;
return false;
}
return true;
}
/**
* @brief The sort depth of a draw anchored at @p worldPos.
*
* @details One value for every screen draw: their order is the UI tree's
* (layer = UI_BASE_LAYER + uiOrder), so a z left on a screen root's
* transform cannot outrank its siblings.
*/
f32 sortDepth(const glm::vec3& worldPos) const {
return isOverlay() ? 0.0f : camera.viewDepth(worldPos);
}
/**
* @brief How many renderables this collect's frustum rejected.
*
* @details Written by the plugins at their `continue`: a cull leaves no draw
* and no pixel, so where it happens is the only place to count it.
* Counts THIS collect — a shadow face has a context of its own, and
* what its frustum skipped is `render.shadow.collects`.
*/
u32 culled = 0;
/**
* @brief How many of those @ref culled an OCCLUDER refused.
*
* @details A subset, not a second total: the plugin counts the cull where it
* happens and this says which question rejected it. One number for
* both cannot tell an occluder that stopped working from a camera
* that turned away.
*/
u32 occluded = 0;
/**
* @brief Light slots the lit quads of this collect were spared: per quad, the loop lights that cannot reach it.
* @details What `lightReachMask2D` took off the fragments. A pixel shows nothing of it (a light out of reach added
* zero before as well), so this is the number that says the reach still rides in the lane.
*/
u32 lightsSpared = 0;
/**
* @brief Which view is looking, where its level choices are kept, and where
* the selections it makes are counted.
*
* @details A null `state` is what a collect that must not select says: the
* shadow pass draws level 0 rather than borrowing a camera's answer,
* which would make the answer the entity's rather than the view's.
*/
struct LodView {
u32 view = 0;
lod::LodViewState* state = nullptr;
lod::SelectionCounts* counts = nullptr;
/** @brief Read the level @ref view settled on instead of choosing one: what a shadow cast for that view's picture is
* cast by. What the view culled casts nothing; what it has not looked at lately casts at its finest. */
bool follow = false;
};
LodView lod;
/**
* @brief How the meshes of THIS collect are shaded. Shaded unless the view asked
* for another mode; a collect that is not a camera's (the shadow map) leaves
* it alone, because a depth write has no colour to override.
*/
ShadingMode shading = ShadingMode::Shaded;
/** @brief The one skinned draw this view colours by a joint's weights, if any. */
WeightTarget weights;
};
/** @brief Decomposes @p transform and returns its world position shifted toward the
* camera by (1 - parallax); factor 1 = no shift, 0 = screen-pinned. Applied
* before the frustum cull so a parallaxed renderable is culled where drawn. */
/**
* @brief The direction the viewer lies in from @p worldPos, in CameraView::eye's
* convention — the eye's own direction orthographically, where every point
* shares it, and the vector to the eye under perspective.
*/
inline glm::vec3 towardViewer(const glm::vec3& worldPos, const CameraView& camera) {
return camera.eye.w < 0.5f ? glm::vec3(camera.eye) : glm::vec3(camera.eye) - worldPos;
}
/**
* @brief The side vector a ribbon widens along: perpendicular to both its path and
* the viewer, so the strip faces the eye instead of lying in one plane.
* @details @p lastSide carries a segment aimed straight at the viewer — no width it
* could see, so no side of its own. Flat scenes are the degenerate case:
* the eye direction is +Z and this reduces to the XY perpendicular.
*/
inline glm::vec3 ribbonSide(const glm::vec3& tangent, const glm::vec3& worldPos,
const CameraView& camera, const glm::vec3& lastSide) {
const glm::vec3 side = glm::cross(towardViewer(worldPos, camera), tangent);
const f32 len2 = glm::dot(side, side);
return len2 > 1e-12f ? side / std::sqrt(len2) : lastSide;
}
inline glm::vec3 parallaxedWorldPosition(ecs::Transform& transform, const glm::vec2& parallax,
const CameraView& camera) {
transform.ensureDecomposed();
glm::vec3 position = rebased(transform.worldPosition);
position.x += camera.center.x * (1.0f - parallax.x);
position.y += camera.center.y * (1.0f - parallax.y);
return position;
}
/**
* @brief The cos/sin of the turn a plane renderable draws with: its entity's rotation
* about Z, which is the only part a flat quad uses.
*/
inline glm::vec2 flatTurnZ(const glm::quat& rotation) {
const f32 n = rotation.w * rotation.w + rotation.z * rotation.z;
if (n <= 1e-12f) return {1.0f, 0.0f};
return {(rotation.w * rotation.w - rotation.z * rotation.z) / n,
2.0f * rotation.w * rotation.z / n};
}
/**
* @brief The world AABB of a turned box: its centre and half-extents, from a local
* box and the position, rotation and scale that place it.
*
* @details Each axis takes |R| * halfExtents, which is exact for a box. One function
* because two things derive it — a mesh's cull and a shadow map's fit — and
* a rotation dropped from either bounds a model by a box smaller than itself.
*/
inline void orientedWorldAabb(const glm::vec3& position, const glm::quat& rotation,
const glm::vec3& scale, const glm::vec3& localMin,
const glm::vec3& localMax, glm::vec3& outCentre,
glm::vec3& outHalf) {
const glm::mat3 basis = glm::mat3_cast(rotation);
const glm::vec3 scaledHalf = glm::abs((localMax - localMin) * 0.5f * scale);
outCentre = position + basis * ((localMin + localMax) * 0.5f * scale);
outHalf = {
glm::dot(glm::abs(glm::row(basis, 0)), scaledHalf),
glm::dot(glm::abs(glm::row(basis, 1)), scaledHalf),
glm::dot(glm::abs(glm::row(basis, 2)), scaledHalf),
};
}
/**
* @brief World AABB half-extents of a flat box turned by @p turn (from flatTurnZ).
* |R| * half, exact for a box. An unturned entity gets @p half back, so the
* result is never narrower than the box itself.
*/
inline glm::vec3 flatHalfExtents(const glm::vec2& turn, const glm::vec3& half) {
const f32 c = std::abs(turn.x), s = std::abs(turn.y);
const glm::vec3 extent = glm::abs(half);
return {c * extent.x + s * extent.y, s * extent.x + c * extent.y, extent.z};
}
class RenderTypePlugin {
public:
virtual ~RenderTypePlugin() = default;
virtual void init(RenderFrameContext& ctx) { (void)ctx; }
virtual void shutdown() {}
/**
* @brief Whether what this plugin draws belongs in a shadow map.
*
* @details A map holds depth written from the light, and only geometry drawn
* through the depth-only variant writes any. Anything else reaches
* the atlas as COLOUR, which every receiver then reads back as a
* depth — so the default is no, and a plugin that casts says so.
*/
virtual bool castsShadows() const { return false; }
/**
* @brief For a plugin that casts: one number for everything its depth collect reads apart from the shadow views and the
* frame's camera, so a frame whose number, views and camera match those of the frame that drew the shadow map
* need not collect it again.
* @return False when it cannot vouch for what it would read (the frame then collects). Asked once a frame, before the
* shadow collect; a plugin may keep what it needs between calls.
*/
virtual bool castInputs(RenderFrameContext& /*ctx*/, ecs::Registry& /*registry*/, u64& /*key*/) { return false; }
/// Whether the Motion collect asks this plugin: what it draws can move by itself, and the picture
/// after it needs to know by how much.
virtual bool drawsMotion() const { return false; }
/**
* @brief Whether this plugin can draw an entity that lives in a UI tree.
*
* @details The overlay collect runs only these. Saying yes is a promise to
* consult RenderCollectContext::accepts, without which the plugin
* draws the screen's entities in the world's pass too.
*/
virtual bool drawsScreenUI() const { return false; }
virtual void collect(RenderCollectContext& ctx) = 0;
/**
* @brief Make ready the programs @p entities will be asked for, drawing none.
*
* @details What it readies is derived by the SAME rule the collect derives it
* by, so a caller cannot ready a variant the draw will not ask for.
* `shadowPasses` says whether this scene also renders depth, which
* needs its own variant. The default readies nothing.
*/
virtual RenderPrewarmResult prewarm(RenderFrameContext& ctx, ecs::Registry& registry,
const Entity* entities, u32 count, bool shadowPasses) {
(void)ctx; (void)registry; (void)entities; (void)count; (void)shadowPasses;
return {};
}
/**
* @brief The same readiness, asked of a PREPARED cell's own description.
*
* @details The second fact source. What it derives must equal what `prewarm`
* derives from the live entities, which is a claim a criterion holds
* rather than a comment.
*/
virtual RenderPrewarmResult prewarmDocument(RenderFrameContext& ctx,
const MeshDocumentRecord* rows, u32 count,
bool shadowPasses) {
(void)ctx; (void)rows; (void)count; (void)shadowPasses;
return {};
}
/**
* @brief What this plugin's collect is called in a frame profile.
*
* @details A literal: the profiler keys scopes by content and keeps the
* pointer. A type that does not answer is reported as `other`
* rather than folded into a neighbour, whose cost it would become.
*/
virtual const char* collectScope() const { return "render.collect.other"; }
};
} // namespace esengine