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 Framebuffer.hpp
* @brief GPU framebuffer abstraction for render-to-texture
* @details Provides off-screen rendering targets with color and depth attachments
* for OpenGL ES/WebGL.
*
* @author ESEngine Team
* @date 2026
*
* @copyright Copyright (c) 2026 ESEngine Team
* Licensed under the Apache License, Version 2.0.
*/
#pragma once
// =============================================================================
// Includes
// =============================================================================
#include "../../core/Types.hpp"
#include "./Texture.hpp"
namespace esengine {
class GfxDevice;
// =============================================================================
// Framebuffer Specification
// =============================================================================
/**
* @brief Framebuffer creation parameters
*
* @details Specifies the dimensions and attachment configuration
* for an off-screen rendering target.
*
* @code
* FramebufferSpec spec;
* spec.width = 1280;
* spec.height = 720;
* spec.samples = 1; // No multisampling
* auto fbo = Framebuffer::create(spec);
* @endcode
*/
struct FramebufferSpec {
/** @brief Framebuffer width in pixels */
u32 width = 1280;
/** @brief Framebuffer height in pixels */
u32 height = 720;
/** @brief Number of samples for MSAA (1 = no multisampling) */
u32 samples = 1;
/** @brief Whether to create depth/stencil attachment */
bool depthStencil = true;
/** @brief Texture filter mode: false=GL_NEAREST, true=GL_LINEAR */
bool linearFilter = false;
/** @brief Color attachment format. RGBA16F needs GfxDevice::supportsFloatTargets. */
GfxPixelFormat colorFormat = GfxPixelFormat::RGBA8;
/** @brief A second colour attachment (RGBA8) drawn in the same pass: the surface's material, for effects that need to know what they are looking at. */
bool gbuffer = false;
/** @brief The colour attachment can also be written by a compute shader (GfxDevice::supportsCompute). */
bool storage = false;
};
// =============================================================================
// Framebuffer Class
// =============================================================================
/**
* @brief Off-screen rendering target
*
* @details Encapsulates an OpenGL/WebGL framebuffer object with
* color and optional depth attachments. Supports render-to-texture
* for scene views, post-processing, and shadow maps.
*
* @code
* // Create framebuffer
* FramebufferSpec spec;
* spec.width = 800;
* spec.height = 600;
* auto fbo = Framebuffer::create(spec);
*
* // Render to texture
* fbo->bind();
* device.clear(true, true, false);
* // ... render scene ...
* fbo->unbind();
*
* // Use color texture
* TextureHandle texture = fbo->getColorAttachment();
* @endcode
*/
class Framebuffer {
public:
Framebuffer() = default;
~Framebuffer();
// Non-copyable, movable
Framebuffer(const Framebuffer&) = delete;
Framebuffer& operator=(const Framebuffer&) = delete;
Framebuffer(Framebuffer&& other) noexcept;
Framebuffer& operator=(Framebuffer&& other) noexcept;
// =========================================================================
// Creation
// =========================================================================
/**
* @brief Creates a framebuffer from specification
* @param spec Framebuffer parameters
* @return Unique pointer to the framebuffer
*
* @details Creates framebuffer with color attachment and optional
* depth/stencil attachment based on spec.
*/
static Unique<Framebuffer> create(GfxDevice& device, const FramebufferSpec& spec);
// =========================================================================
// Operations
// =========================================================================
/**
* @brief Binds the framebuffer for rendering
* @details All subsequent draw calls will render to this framebuffer
* until unbind() is called.
*/
void bind() const;
/**
* @brief Unbinds the framebuffer
* @details Restores rendering to the default framebuffer (screen).
*/
void unbind() const;
/**
* @brief Resizes the framebuffer
* @param width New width in pixels
* @param height New height in pixels
*
* @details Recreates all attachments with new dimensions.
* Existing content is lost.
*/
void resize(u32 width, u32 height);
// =========================================================================
// Properties
// =========================================================================
/** @brief Gets the color attachment texture */
/// What a shader samples. On a multisampled target this is the RESOLVED
/// attachment, not the one drawn into — the caller never handles the
/// multisampled side, which cannot be sampled at all.
TextureHandle getColorAttachment() const {
return resolveColor_ != TextureHandle::Invalid ? resolveColor_ : colorAttachment_;
}
/** @brief The second colour attachment, resolved like the first (Invalid when the target has none). */
TextureHandle getGBufferAttachment() const {
return resolveColor1_ != TextureHandle::Invalid ? resolveColor1_ : colorAttachment1_;
}
/** @brief The third colour attachment, the surface's diffuse colour (RGBA8, alpha 1 where a surface wrote it). */
TextureHandle getAlbedoAttachment() const {
return resolveColor2_ != TextureHandle::Invalid ? resolveColor2_ : colorAttachment2_;
}
/** @brief Gets the depth attachment texture (Invalid if none) */
TextureHandle getDepthAttachment() const {
return resolveDepth_ != TextureHandle::Invalid ? resolveDepth_ : depthAttachment_;
}
/** @brief Gets the framebuffer width in pixels */
u32 getWidth() const { return spec_.width; }
/** @brief Gets the framebuffer height in pixels */
u32 getHeight() const { return spec_.height; }
/** @brief Gets the framebuffer specification */
const FramebufferSpec& getSpecification() const { return spec_; }
/** @brief Gets the device framebuffer handle */
FramebufferHandle handle() const { return handle_; }
private:
/**
* @brief Initializes the framebuffer on GPU
* @return True on success
*/
bool initialize();
/**
* @brief Releases GPU resources
*/
void cleanup();
GfxDevice* device_ = nullptr; ///< Set by create(); all GL goes through it.
FramebufferSpec spec_;
FramebufferHandle handle_ = FramebufferHandle::Default;
TextureHandle colorAttachment_ = TextureHandle::Invalid;
TextureHandle depthAttachment_ = TextureHandle::Invalid;
/// Single-sample twins, non-Invalid only when spec_.samples > 1.
TextureHandle resolveColor_ = TextureHandle::Invalid;
TextureHandle resolveDepth_ = TextureHandle::Invalid;
/// The second colour attachment and its single-sample twin (spec_.gbuffer).
TextureHandle colorAttachment1_ = TextureHandle::Invalid;
TextureHandle resolveColor1_ = TextureHandle::Invalid;
/// The third, the surface's diffuse colour, and its twin (also spec_.gbuffer).
TextureHandle colorAttachment2_ = TextureHandle::Invalid;
TextureHandle resolveColor2_ = TextureHandle::Invalid;
};
} // namespace esengine