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.

14.1 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    RenderGraph.hpp
 * @brief   Full-screen passes as a declared graph: what each one reads, what it
 *          writes, and at what size — the graph decides the rest.
 *
 * The chain it replaces was two fixed framebuffers ping-ponged in order, which
 * fixes three things it should not: every pass runs at full resolution, a pass
 * can only read the one before it (plus the scene, wired to a hard-coded unit),
 * and a disabled pass still costs its target. Here a pass names its inputs and
 * its output's SCALE, so a blur chain runs at a quarter size, a composite reads
 * both the blur and the scene, and a pass nothing reaches is never run.
 *
 * Physical targets come from a pool keyed by shape and handed back the moment a
 * resource is last read, so the two-buffer ping-pong is what the allocator does
 * on its own for a linear chain rather than something the caller arranges.
 *
 * The graph does NOT own scene geometry: the scene is rendered into an imported
 * texture by the frame, and the graph runs over it. See PostProcessPipeline.
 */
#pragma once

#include "../../core/Types.hpp"
#include "../rhi/Framebuffer.hpp"
#include "../rhi/GfxEnums.hpp"
#include "TargetPool.hpp"

#include <functional>
#include <memory>
#include <string>
#include <unordered_set>
#include <vector>

namespace esengine {

class GfxDevice;

namespace rg {

/** Index into the graph's resource table. */
using ResourceId = u32;
constexpr ResourceId kNoResource = static_cast<ResourceId>(-1);

/**
 * @brief Shape of a target the graph allocates.
 *
 * @details Size is a fraction of the graph's reference size rather than pixels:
 *          a half-size blur stays half-size when the window resizes, and the
 *          pool can hand the same physical target to any pass asking for that
 *          fraction.
 *
 *          `width`/`height` name pixels directly instead, for a target whose
 *          texels are its own: a shadow atlas is 2048² because that is how many
 *          its tiling divides, and as a `scale` it would be a different resource
 *          on every monitor. Zero (the default) follows `scale`.
 */
struct TargetDesc {
    f32 scale = 1.0f;
    u32 width = 0;
    u32 height = 0;
    GfxPixelFormat format = GfxPixelFormat::RGBA8;
    bool linearFilter = true;
    bool depthStencil = false;
    /// Samples to DRAW with. What the target hands back to be sampled stays
    /// single-sample either way — the resolve is the target's own business.
    u32 samples = 1;
    /// A second colour attachment for the surface's material, drawn beside the first.
    bool gbuffer = false;
    /// Written by a compute shader (a pass with `compute` set), then sampled like any target.
    bool storage = false;
};

/** What a pass's execute() is told: where it is drawing and what it may read. */
struct PassContext {
    u32 width = 0;
    u32 height = 0;
    /// The pass's declared reads, already bound to units 0..n-1, in order.
    const std::vector<TextureHandle>* inputs = nullptr;
    /// The texture this pass writes: the storage texture of a compute pass (a render pass draws into its framebuffer instead).
    TextureHandle output = TextureHandle::Invalid;

    TextureHandle input(u32 i) const {
        return (inputs && i < inputs->size()) ? (*inputs)[i] : TextureHandle::Invalid;
    }
};

/**
 * @brief One full-screen pass.
 *
 * @details `reads` are bound to texture units in declaration order, so a pass
 *          that wants the scene as its second sampler declares it second — the
 *          wiring is the declaration, not a convention the shader has to know.
 */
struct PassDesc {
    std::string name;
    std::vector<ResourceId> reads;
    /**
     * @brief Resources the pass uses but the graph must not bind.
     *
     * @details A scene pass reaches the shadow atlas through the material each
     *          draw carries, so it owes the graph ordering but must not spend a
     *          unit — as a `read` it would claim unit 0 from under the batch.
     *          Culling counts it either way: a producer nothing names is dropped.
     */
    std::vector<ResourceId> dependencies;
    ResourceId write = kNoResource;
    /**
     * @brief A compute pass: no render pass is opened and no unit is bound — `execute` dispatches, reading `ctx.input(i)` and
     *        writing `ctx.output`, which has to be a target declared with `storage`. Ordered, culled and recycled like any pass.
     */
    bool compute = false;
    /// Wanted by a later frame rather than by this picture: not culled for nothing having read it yet.
    bool keep = false;
    /// Its target's depth is only for testing while it draws, and nothing reads it afterwards (see RenderPassDesc::discardDepth).
    bool discardDepth = false;
    bool clear = false;
    /// Clears the depth attachment with the colour, for a target that has one.
    /// A geometry pass writes depth, so the frame before it is not what it
    /// should be tested against; a fullscreen pass has neither and ignores this.
    bool clearDepth = false;
    f32 clearColor[4] = {0.0f, 0.0f, 0.0f, 1.0f};
    /**
     * @brief The rect of its target this pass draws into. Zero width = all of it.
     *
     * @details Opening a render pass resets the viewport, so a pass that does
     *          not cover its whole target has to carry the rect: a fullscreen
     *          effect always covers its own, a camera's scene covers whatever
     *          slice of a shared target that camera was given.
     */
    u32 viewportX = 0;
    u32 viewportY = 0;
    u32 viewportW = 0;
    u32 viewportH = 0;
    std::function<void(const PassContext&)> execute;
};

/**
 * @brief A frame's full-screen passes, compiled and run.
 *
 * @details One instance is reused across frames: the graph is rebuilt every
 *          frame (cheap — a handful of passes) while the target pool it draws
 *          from persists, which is what makes reuse possible at all.
 *
 *          The pool is BORROWED, not owned: a graph is one chain and a frame
 *          holds several (per camera, plus the screen stack), so a pool inside
 *          the graph could hold nothing across two of them. Given one, every
 *          chain draws from the same targets, and so can a frame-lived resource.
 */
/**
 * @brief What each pass of a graph cost the GPU, read a few frames late.
 *
 * @details One timer query per pass per frame, in a ring so a result is fetched after the GPU has had time to finish
 *          it and the CPU never waits. A bracketing backend (GL) gets a begin/end around the pass; an arming one
 *          (WebGPU) gets the next pass named. Same-named passes of a frame (two cameras, two shadow views) are summed.
 *          Costs a query per pass, so it runs only while the profiler is on.
 */
class PassTimer {
public:
    struct Entry {
        const char* name;  ///< Interned: valid as long as the timer.
        f32 ms;
    };

    explicit PassTimer(GfxDevice& device) : device_(device) {}

    /** Whether the device can time GPU work at all; probes on first call. */
    bool available();

    /** Starts a frame: fetches what the ring has finished and claims this frame's slot. */
    void beginFrame();
    void endFrame();

    /** Around one pass; arms or brackets by what the device does. */
    void begin(const std::string& name);
    void end();

    /**
     * Splits the open pass: what has run so far is closed under the pass's own name, and the time from here is
     * `<pass>/<name>` until the next split or the pass's end. Only where a pass is bracketed (GL); where it is armed the
     * pass is one timestamp pair and this does nothing.
     */
    void segment(const std::string& name);

    /** The newest frame whose every pass was read back. Empty until one has been. */
    const std::vector<Entry>& last() const { return last_; }
    f32 lastTotalMs() const { return lastTotal_; }

private:
    static constexpr u32 kFrames = 4;
    struct Slot {
        const char* name = nullptr;
        u32 query = 0;
        bool done = false;
        f32 ms = 0.0f;
    };
    struct Frame {
        std::vector<Slot> slots;
        bool inflight = false;
    };

    static constexpr u32 kMaxPasses = 512;
    u32 queryFor(u32 frame, u32 index);
    bool poll(Frame& frame);

    GfxDevice& device_;
    int state_ = 0;  // 0 = unprobed, 1 = available, 2 = no timer
    bool arming_ = false;
    bool open_ = false;
    std::string pass_;  // the open pass
    Frame frames_[kFrames];
    std::vector<u32> queries_;
    std::unordered_set<std::string> names_;
    u32 cur_ = 0;
    u32 counter_ = 0;
    u32 frameNo_[kFrames] = {0, 0, 0, 0};
    u32 lastNo_ = 0;
    std::vector<Entry> last_;
    f32 lastTotal_ = -1.0f;
};

class RenderGraph {
public:
    /** Borrows the caller's pool: a frame's chains share one. */
    RenderGraph(GfxDevice& device, TargetPool& pool);
    /** Owns a pool of its own — for a lone chain and for tests. */
    explicit RenderGraph(GfxDevice& device);
    ~RenderGraph();

    RenderGraph(const RenderGraph&) = delete;
    RenderGraph& operator=(const RenderGraph&) = delete;

    /** Starts a new graph. `refWidth`/`refHeight` are what `scale` is a fraction of. */
    void begin(u32 refWidth, u32 refHeight);

    /** A texture the graph reads but does not own — the scene capture. */
    ResourceId importTexture(TextureHandle texture, u32 width, u32 height);

    /**
     * @brief The framebuffer the graph must end in (the screen, an editor FBO).
     *
     * @details Also what culling works back from: a pass no path reaches from
     *          here did not contribute to the image and is dropped. Set output
     *          false for a persistent intermediate capture: importing it must
     *          not move the final output away from the scene or its post stack.
     *          @p readable is the colour texture behind @p target, so a later pass
     *          can read what this one wrote — a history buffer is imported to be
     *          written and then sampled, by the next pass and by the next frame.
     */
    ResourceId importTarget(FramebufferHandle target, u32 width, u32 height, bool output = true,
                            TextureHandle readable = TextureHandle::Invalid);

    /** A target the graph allocates from the pool and recycles after its last read. */
    ResourceId createTarget(const TargetDesc& desc);

    /**
     * @brief A pooled target filled by a producer OUTSIDE any pass callback.
     *
     * @details The scene cannot be written from inside execute(): a frame reaches
     *          the host as several calls with the geometry drawn between them, so
     *          its target has to exist first. Pooled and recycled at its last read
     *          like any transient — the exception is WHEN it is filled, not who owns it.
     */
    ResourceId createExternalTarget(const TargetDesc& desc);

    /** The framebuffer behind a resource, for an external target to be drawn into. */
    FramebufferHandle framebufferOf(ResourceId id) const;

    void addPass(PassDesc pass);

    /** Culls, assigns physical targets, and runs what survives. */
    void execute();

    /** Times each pass of the next execute()s into @p timer; null stops. Borrowed. */
    void setPassTimer(PassTimer* timer) { timer_ = timer; }

    /** The texture behind a resource — valid for imports, and for a transient
     *  only while it holds a physical target. */
    TextureHandle textureOf(ResourceId id) const;

    /** Its depth attachment, for a resource declared with one. Invalid for an
     *  import (the graph did not make it) and for a target without depth. */
    TextureHandle depthTextureOf(ResourceId id) const;

    /** Its second colour attachment, for a resource declared with one. Invalid otherwise. */
    TextureHandle gbufferTextureOf(ResourceId id) const;
    /// The third attachment of a gbuffer target: the surface's diffuse colour (alpha 1 where one was written).
    TextureHandle albedoTextureOf(ResourceId id) const;

    /** Drops every pooled target. For shutdown and for device loss, after which
     *  the handles the pool holds name nothing. */
    void releasePool();

    /** The targets this graph draws from — shared with the frame's other chains
     *  when one was given, its own otherwise. */
    TargetPool& pool() { return pool_; }

    /** How many physical targets the pool is holding. Diagnostics and tests. */
    u32 pooledTargetCount() const { return pool_.count(); }

    /** What those targets cost in GPU memory, so the number a budget reads is
     *  bytes rather than a count of things with no common size. */
    u64 pooledTargetBytes() const { return pool_.bytes(); }

    /** Passes the last execute() ran, after culling. Diagnostics and tests. */
    u32 lastExecutedPassCount() const { return executed_; }

private:
    enum class Kind : u8 { ImportedTexture, ImportedTarget, Transient };

    struct Resource {
        Kind kind = Kind::Transient;
        TargetDesc desc;
        TextureHandle texture = TextureHandle::Invalid;
        FramebufferHandle target = FramebufferHandle::Default;
        u32 width = 0;
        u32 height = 0;
        /// The pool target a transient holds; kNoTarget when it holds none.
        TargetHandle pooled = kNoTarget;
        i32 lastRead = -1;
    };


    void resolveSize(Resource& res) const;
    TargetHandle acquire(const Resource& res);
    void release(Resource& res);
    /// Marks the passes that reach the imported target; false for everything else.
    void cull(std::vector<bool>& live) const;

    GfxDevice& device_;
    /// Set only by the pool-owning constructor; pool_ refers into it.
    Unique<TargetPool> ownedPool_;
    TargetPool& pool_;
    std::vector<Resource> resources_;
    std::vector<PassDesc> passes_;
    /// What this graph has borrowed and still owes back, released at the next
    /// begin() — a transient nothing reads is never released mid-execute, and
    /// the pool is no longer the graph's to reset wholesale.
    std::vector<TargetHandle> borrowed_;
    std::vector<TextureHandle> inputScratch_;
    ResourceId finalTarget_ = kNoResource;
    u32 refWidth_ = 0;
    u32 refHeight_ = 0;
    u32 executed_ = 0;
    PassTimer* timer_ = nullptr;
};

}  // namespace rg
}  // namespace esengine