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.

4.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    FrameConstants.hpp
 * @brief   Per-frame shader constants shared via a single Uniform Buffer Object.
 * @details The engine's per-frame data (the view-projection) lives in exactly one
 *          UBO, bound once per frame at FRAME_CONSTANTS_BINDING. Every engine shader
 *          declares `layout(std140) uniform FrameConstants { mat4 u_projection; };`
 *          and Shader::compile auto-links that block to the binding point — there is
 *          no loose per-shader u_projection upload. This is the first non-texture
 *          resource of the eventual BindGroup model.
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */
#pragma once

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

#include <glm/glm.hpp>

#include <cmath>

namespace esengine {

/**
 * @brief CPU mirror of the GLSL FrameConstants block (std140).
 * @details A mat4 at 0, a vec4 at 64 and a mat4 at 80 need no std140 padding.
 *          Append future fields here and in ShaderParser's injected block in the
 *          same order. camera: w = 1 means xyz is the eye's world position
 *          (perspective), w = 0 that xyz points at the viewer.
 */
struct FrameConstants {
    glm::mat4 viewProjection{1.0f};
    glm::vec4 camera{0.0f, 0.0f, 1.0f, 0.0f};
    /**
     * The inverse of the matrix ABOVE, so a shader holding a depth sample can put
     * it back in the world — of the UPLOADED one, since what a shader un-projects
     * is the clip space its own device rasterised into. Without it a sampled
     * depth is a number with no length in it.
     */
    glm::mat4 inverseViewProjection{1.0f};
    /// The render origin (RenderOrigin.hpp): a world position is the one the shader holds plus this, for what depends on the world's own coordinates.
    glm::vec4 renderOrigin{0.0f};
};

/**
 * @brief Where the frame is seen from, read out of the matrix that projects it.
 *
 * @details inverse(VP) on the clip z axis: a perspective divide brings it down to
 *          the eye POINT (w = 1); orthographic has none, so it stays a DIRECTION,
 *          negated to point at the viewer (w = 0). One answer for both the shaders'
 *          FrameConstants::camera and the CPU's draw ordering.
 */
inline glm::vec4 cameraFromViewProjection(const glm::mat4& viewProjection) {
    const glm::vec4 axis = glm::inverse(viewProjection)[2];
    if (std::abs(axis.w) > 1e-6f) return glm::vec4(glm::vec3(axis) / axis.w, 1.0f);
    const f32 len = glm::length(glm::vec3(axis));
    if (len < 1e-12f) return glm::vec4(0.0f, 0.0f, 1.0f, 0.0f);
    return glm::vec4(-glm::vec3(axis) / len, 0.0f);
}

/**
 * @brief The projection @p p as a device keeping @p range wants it.
 *
 * @details The engine builds for [-1, 1], so MinusOneToOne returns @p p itself and
 *          such a device is handed the matrix bit for bit. ZeroToOne averages row 2
 *          with row 3, which is that remap written as a matrix; the viewpoint
 *          cameraFromViewProjection reads is invariant under it.
 */
inline glm::mat4 toClipDepthRange(const glm::mat4& p, ClipDepthRange range) {
    if (range == ClipDepthRange::MinusOneToOne) return p;
    glm::mat4 out = p;
    for (int col = 0; col < 4; ++col) out[col][2] = (p[col][2] + p[col][3]) * 0.5f;
    return out;
}

/** @brief Indexed uniform binding point the FrameConstants block is bound to. */
inline constexpr u32 FRAME_CONSTANTS_BINDING = 0;

/** @brief GLSL block name; must match the shader declarations and Shader::compile lookup. */
inline constexpr const char* FRAME_CONSTANTS_BLOCK = "FrameConstants";

/**
 * @brief CPU mirror of the injected TimeConstants block (std140).
 * @details u_time = (elapsed s, delta s, view exposure EV, 0); u_viewport = (w, h, 1/w, 1/h) of the
 *          canvas in pixels. Engine-owned: ShaderParser injects the block into every
 *          assembled stage — shaders never declare it.
 */
struct TimeConstants {
    glm::vec4 time{0.0f};
    glm::vec4 viewport{0.0f};
};

inline constexpr u32 TIME_CONSTANTS_BINDING = 3;
inline constexpr const char* TIME_CONSTANTS_BLOCK = "TimeConstants";

}  // namespace esengine