Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

25.1 KB
Raw Blame
// 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