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 GfxDevice.hpp
* @brief Abstract graphics device interface
* @details The render backend boundary (RHI). Upper-layer code (DrawList,
* RenderFrame, plugins) depends only on this interface: typed resource
* handles created from descriptors, immutable pipelines, and draw
* submission. Concrete backends (GLDevice today; WebGPU and native APIs
* later) own every API-specific concept behind it.
*
* @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 "../draw/BlendMode.hpp"
#include "./GfxContent.hpp"
#include "./GfxEnums.hpp"
#include "./GfxResourceRegistry.hpp"
#include "./PipelineState.hpp"
#include <functional>
#include <map>
#include <string>
#include <utility>
#include <vector>
namespace esengine {
// =============================================================================
// GfxDevice Interface
// =============================================================================
/** @brief Sentinel returned by getUniformBlockIndex when a program has no such block (GL_INVALID_INDEX). */
static constexpr u32 GFX_INVALID_UNIFORM_BLOCK = 0xFFFFFFFFu;
/** @brief What a uniform binding's offset must be a multiple of: the largest either API may ask. */
static constexpr u32 GFX_UNIFORM_OFFSET_ALIGNMENT = 256;
/**
* @brief GPU objects the device has created and not yet destroyed.
*
* @details ResourceManager reports a strict subset — render targets, the
* transient pool and plugin-created textures bypass it.
* @note Conserved: buffers, textures, programs, renderTargets. Caches that
* plateau: layouts, pipelines. `readbacks` is a queue, empty at rest.
*/
struct GfxLiveObjects {
u32 buffers = 0;
u32 textures = 0;
u32 programs = 0;
u32 layouts = 0;
u32 pipelines = 0;
u32 renderTargets = 0;
u32 readbacks = 0;
};
/**
* @brief Abstract graphics device interface
*
* @details The device owns its state: setPipeline binds an immutable pipeline and skips
* re-applying it when unchanged, so the renderer no longer micro-manages GL state
* through an external tracker. Per-draw dynamic state (scissor, stencil ref,
* textures) is applied directly; sorted+merged draws already group it coarsely.
*/
class GfxDevice {
public:
virtual ~GfxDevice() = default;
// =========================================================================
// Lifecycle
// =========================================================================
/** @brief Initializes the graphics device */
virtual void init() = 0;
/** @brief Shuts down the graphics device */
virtual void shutdown() = 0;
// =========================================================================
// Device Loss
// =========================================================================
// The state machine lives here, not in each backend: a backend only has to
// DETECT its own kind of loss and call markDeviceLost. What "lost" then MEANS
// — one report, one transition, submission stopped — stays identical.
/** @brief Whether the device can be drawn to (see {@link GfxDeviceStatus}). */
GfxDeviceStatus deviceStatus() const { return device_status_; }
/** @brief Strictly Live: recovered but still-refilling counts as false. */
bool isDeviceLive() const { return device_status_ == GfxDeviceStatus::Live; }
/**
* @brief Whether work may be submitted — the one check the guards make.
* @details True while Recovering as well as Live. A device that has been
* rebuilt but whose textures are still being re-uploaded must draw:
* refusing would leave the screen frozen for the whole reload
* instead of filling in as the content lands.
*/
bool isDeviceUsable() const {
return device_status_ == GfxDeviceStatus::Live ||
device_status_ == GfxDeviceStatus::Recovering;
}
/**
* @brief Which generation of the device the live GPU objects belong to.
* @details Bumped by every successful rebuild. A resource can record the
* generation it was realized on, so a diagnostic can say whether it
* truly came back — a non-zero handle only looks like it did.
*/
u64 deviceGeneration() const { return device_generation_; }
/**
* @brief How many times a static vertex or index buffer has been written or resized since the device was made.
*
* @details What a picture kept from an earlier frame (a shadow map drawn again only when what it holds changed) asks to
* know that geometry it names by handle is still the geometry it drew: a handle is never reused, but a static
* buffer can still be rewritten in place. Dynamic buffers (a frame's own vertex pool) are not counted.
*/
u64 geometryWrites() const { return geometry_writes_; }
/** @brief The loss report, or null while the device is Live. */
const GfxDeviceLostInfo* deviceLostInfo() const {
return device_status_ == GfxDeviceStatus::Live ? nullptr : &device_info_;
}
/**
* @brief Who this device is — available WHILE it is alive, unlike the loss report.
* @details The identity was always captured at init; it was only reachable
* through a report that exists after a loss, so a healthy session
* could not say which GPU it was running on.
*/
const GfxDeviceIdentity& deviceIdentity() const { return identity_; }
/**
* @brief The clip volume this device keeps along z.
* @details Pure: a backend that does not state this is a backend whose
* projections silently mean something else, which is the bug this
* exists to make impossible. It is not read off `deviceIdentity`,
* whose backend name is a label rather than a capability.
*/
virtual ClipDepthRange clipDepthRange() const = 0;
virtual bool storesTargetsTopDown() const { return false; }
virtual void copyTextureFlippedY(TextureHandle src, TextureHandle dst) { (void)src; (void)dst; }
/**
* @brief Declares the device lost from outside the backend.
* @details The host observes losses the backend cannot: a browser firing
* `webglcontextlost`, a shell told by the OS that the adapter is
* gone. Idempotent — the FIRST reason wins, because it is the one
* that explains the rest.
*/
void notifyDeviceLost(GfxDeviceLostReason reason, std::string message = {},
std::string context = {}) {
markDeviceLost(reason, std::move(message), std::move(context));
}
/**
* @brief Rebuilds the device and every object it issued, behind the same handles.
* @details Runs once per loss. Retained content is uploaded again and Sourced
* content becomes owed; the device turns Live when nothing is owed.
* @return True when the device is usable (Recovering or Live).
*/
bool recoverDevice();
/** @brief Sourced objects that have storage again and are waiting for their contents. */
std::vector<GfxOwedContent> owedContent() const { return registry_.owed(); }
/**
* @brief Gives up on one owed object's contents: it keeps its placeholder.
* @details For a provider that no longer exists. Logged by the caller, never silent.
*/
void forgoContent(const GfxOwedContent& owed);
/**
* @brief Settles one owed object whose provider wrote its contents itself.
* @details For content the device cannot upload: a JS-side path that draws a
* canvas or a video frame straight into the native texture behind the
* handle. The provider says so, because the device never saw the write.
*/
void restoreContent(const GfxOwedContent& owed);
/**
* @brief CPU bytes the device holds to put content back after a loss.
* @details Retained content, plus the initial bytes of objects created while
* lost until the recovery uploads them. A cost the GPU figures never show.
*/
usize retainedBytes() const { return retained_bytes_; }
/**
* @brief Every draw the GPU was asked for since the last call, and the tally started again.
* @details Counted where the backends issue them, so it holds every pass a frame has: the scene and
* the overlay, and the shadow maps, depth prepass, reflections, motion vectors and
* post-processing that the draw lists' own count leaves out. An instanced draw is one.
*/
u32 takeDraws() { const u32 n = draws_; draws_ = 0; return n; }
/**
* @brief Warns once when retainedBytes() grows past `bytes`; 0 never warns.
* @details Falling back under it re-arms the warning.
*/
void setRetainedBudget(usize bytes) {
retained_budget_ = bytes;
over_retained_budget_ = false;
}
/**
* @brief Gives up on the device: no further recovery will be attempted.
* @details The clean end of a loss that could not be recovered from. The
* report is kept; what changes is that the renderer stops waiting.
*/
void markDeviceDead() {
if (device_status_ == GfxDeviceStatus::Dead) return;
if (device_status_ == GfxDeviceStatus::Live) {
markDeviceLost(GfxDeviceLostReason::Unknown, {}, {});
}
device_status_ = GfxDeviceStatus::Dead;
}
/**
* @brief Takes a replacement device from the host, for backends that cannot
* make their own.
* @details A WebGPU device is created by the page, so only the page can
* replace a lost one; GL rebuilds itself and has no use for this.
* The next recovery attempt picks up whatever was handed over.
*/
virtual bool provideReplacementDevice(void* nativeDevice) {
(void)nativeDevice;
return false;
}
/**
* @brief Pumps backend-native loss detection.
* @details Backends whose loss arrives as a callback (WebGPU) or a status
* query (GL robustness) surface it here. Default: the backend
* cannot detect loss itself and depends entirely on
* notifyDeviceLost.
* @return True when THIS call is the one that observed the loss.
*/
virtual bool pollDeviceLost() { return false; }
/**
* @brief Opens a frame: polls for loss, and numbers the frame a report is stamped with.
* @details The one place the renderer asks "may I draw at all". Everything a
* frame does afterwards — passes, post-process, readbacks — is
* predicated on this having returned true, which is why it is a
* single question at the top rather than a check per submission.
* @return True when the frame may proceed (see {@link isDeviceUsable}).
*/
bool beginDeviceFrame() {
++device_frame_;
if (isDeviceUsable()) pollDeviceLost();
return isDeviceUsable();
}
/**
* @brief Called once per loss, with the completed report.
* @details One observer, not a list: the renderer owns the device and fans
* the report out to whoever else needs it.
*/
void setDeviceLostHandler(std::function<void(const GfxDeviceLostInfo&)> handler) {
device_lost_handler_ = std::move(handler);
}
// =========================================================================
// Viewport & Clear
// =========================================================================
/** @brief Sets the rendering viewport */
virtual void setViewport(i32 x, i32 y, u32 w, u32 h) = 0;
/**
* @brief The viewport last set, so a pass that borrows the device can give it back.
* @details Mirrored here because neither API this wraps reads it back cheaply, and
* a pass rendering elsewhere cannot recompute what to restore: a
* split-screen camera owns only part of the target. Set in setViewport.
*/
struct Viewport { i32 x = 0, y = 0; u32 w = 0, h = 0; };
const Viewport& viewport() const { return viewport_; }
// Clears are pass-scoped: RenderPassDesc carries the load-ops AND their values
// (color / stencil / optional region). There is no public clear entry point and
// no sticky clear state a pass could inherit by accident.
// =========================================================================
// Dynamic Per-Draw State (deliberately outside the pipeline; see PipelineState.hpp)
// =========================================================================
/**
* @brief Mid-pass stencil reset (the one clear that isn't a pass load-op).
* @details The mask pass wipes the stencil attachment of the CURRENT target
* before rebuilding mask refs — it must not restart the pass (the
* scene may be rendering into a post-process capture). GL clears the
* attachment; a WebGPU backend emulates with a stencil-write quad.
*/
virtual void clearStencil(i32 value) = 0;
/** @brief Enables or disables scissor test */
virtual void setScissorTest(bool enabled) = 0;
/** @brief Sets the scissor rectangle */
virtual void setScissor(i32 x, i32 y, i32 w, i32 h) = 0;
// =========================================================================
// Buffers
// =========================================================================
/**
* @brief Creates a buffer with fixed capacity and optional initial contents.
* @param content Who restores the contents after a loss.
* @param initialData When non-null, `desc.size` bytes uploaded at creation.
*/
BufferHandle createBuffer(const BufferDesc& desc, GfxContent content, const void* initialData);
/** @brief Deletes a buffer */
void deleteBuffer(BufferHandle buffer);
/** @brief Updates a sub-range of a buffer; must fit within its capacity. */
void updateBuffer(BufferHandle buffer, u32 offsetBytes, const void* data, u32 sizeBytes);
/**
* @brief Re-specifies a buffer's store with a new capacity, discarding prior contents.
* @details The handle stays valid (streaming growth without re-wiring vertex
* layouts). `data` may be null to allocate uninitialized storage.
*/
void resizeBuffer(BufferHandle buffer, u32 sizeBytes, const void* data);
/** @brief A buffer's description as it stands, or null for a handle that names none. */
const BufferDesc* bufferDesc(BufferHandle buffer) const;
/**
* @brief Binds a buffer to a uniform binding slot (the block index shaders are linked to).
* @details @p sizeBytes of it from @p offsetBytes, a multiple of
* GFX_UNIFORM_OFFSET_ALIGNMENT; a size of 0 is the whole buffer.
*/
void setUniformBuffer(u32 slot, BufferHandle buffer, u32 offsetBytes = 0, u32 sizeBytes = 0) {
backendSetUniformBuffer(slot, buffer, offsetBytes, sizeBytes);
}
// =========================================================================
// Vertex Input (layout in the pipeline, buffers bound per draw)
// =========================================================================
/** @brief Registers an immutable vertex layout; pipelines reference it by handle. */
VertexLayoutHandle createVertexLayout(const VertexLayoutDesc& desc);
/** @brief Deletes a vertex layout (no pipeline may reference it afterwards) */
void deleteVertexLayout(VertexLayoutHandle layout);
/** @brief A layout's description, or null for a handle that names none. */
const VertexLayoutDesc* vertexLayoutDesc(VertexLayoutHandle layout) const;
/**
* @brief Binds a vertex buffer to a layout slot for subsequent draws.
* @param offsetBytes Byte offset of element 0 — how an instanced draw rebases
* its per-instance stream (GLES3 has no baseInstance).
*/
virtual void setVertexBuffer(u32 slot, BufferHandle buffer, u32 offsetBytes) = 0;
/** @brief Binds the index buffer for subsequent indexed draws */
virtual void setIndexBuffer(BufferHandle buffer) = 0;
// =========================================================================
// Textures
// =========================================================================
/**
* @brief Creates a 2D texture; uploads `pixels` (tightly packed, desc-sized) when non-null.
* @details Storage is allocated either way. `desc.mipmaps` generates mipmaps
* after the initial upload.
*/
TextureHandle createTexture(const TextureDesc& desc, GfxContent content, const void* pixels);
/**
* @brief Creates a texture from pre-compressed GPU block data.
* @details The caller must first confirm the backend supports `format`
* (see supportsCompressedFormat) and fall back to an uncompressed
* createTexture otherwise. Data is uploaded as-is; no CPU-side decode.
* @param data All @p mipLevels concatenated, level 0 (base) first, each block-
* aligned (`gfxCompressedPyramidBytes`). Level i has size
* `max(1, width>>i) x max(1, height>>i)`.
* @param mipLevels Number of mip levels present (1 = base only).
*/
TextureHandle createCompressedTexture(const TextureDesc& desc, GfxContent content,
GfxCompressedFormat format, const void* data,
u32 byteLength, u32 mipLevels);
/** @brief Puts compressed contents back behind an owed texture's handle. */
bool restoreCompressedTexture(TextureHandle texture, GfxCompressedFormat format,
const void* data, u32 byteLength, u32 mipLevels);
/**
* @brief Adopts a texture a host created with the device's own API (a JS-side WebGL upload).
* @details The device owns it from here and, after a loss, recreates storage of
* `desc` behind the same handle for the provider in @p content to refill.
*/
TextureHandle importExternalTexture(u32 nativeId, const TextureDesc& desc, GfxContent content);
/** @brief Replaces the native texture behind @p texture with one the host created again. */
bool restoreTextureFromNative(TextureHandle texture, u32 nativeId);
/**
* @brief Moves @p from's storage and description behind @p into, and ends @p from.
* @details How a provider pays an owed texture: it loads the content the way it
* always does, into a texture of its own, and hands that over. @p into
* keeps its handle and content policy; @p from names nothing afterwards.
*/
bool adoptTextureContent(TextureHandle into, TextureHandle from);
/** @brief Deletes a texture */
void deleteTexture(TextureHandle texture);
/**
* @brief Uploads pixels to a sub-rectangle of a texture (transfer format from its desc).
* @param flipY Vertical flip on upload (WebGL upload state; no-op on native backends).
*/
void updateTexture(TextureHandle texture, i32 x, i32 y, u32 width, u32 height,
const void* pixels, bool flipY);
/** @brief Sets texture filtering and wrap parameters */
void setTextureParams(TextureHandle texture, TextureFilter min, TextureFilter mag,
TextureWrap wrapS, TextureWrap wrapT);
/** @brief Generates mipmaps for a texture */
void generateMipmaps(TextureHandle texture);
/** @brief A texture's description as it stands, or null for a handle that names none. */
/** @brief What @p texture's content is, as a number that changes whenever the device is given new content or sampling
* for it (see GfxTextureRecord::revision); 0 for none. */
u64 textureRevision(TextureHandle texture) const;
const TextureDesc* textureDesc(TextureHandle texture) const;
/** @brief Activates a texture slot and binds a 2D texture */
virtual void bindTexture(u32 slot, TextureHandle texture) = 0;
/**
* @brief Reports whether the backend can sample the given compressed format.
* @details ETC2/EAC is always true on a WebGL2/GLES3 backend (core spec);
* ASTC and S3TC depend on driver extensions. Probe this before
* calling createCompressedTexture with a non-core format.
*/
virtual bool supportsCompressedFormat(GfxCompressedFormat format) = 0;
/**
* @brief Whether RGBA16F color attachments are renderable.
* @details WebGL2 gates float-target rendering behind EXT_color_buffer_float
* (sampling half-float textures is core); WebGPU always supports it.
* Probe this before creating an HDR framebuffer and fall back to
* SRGB8_ALPHA8/RGBA8.
*/
virtual bool supportsFloatTargets() = 0;
/**
* @brief Whether a blended draw can write the surface record's second attachment unblended.
* @details The surface record is never blended: a normal averaged with the one under it is neither's. A draw that
* composes the scene behind itself (water, glass reading the scene's colour) is still blended into the
* first attachment, and owns the pixel's record all the same. WebGPU sets blend per target; WebGL2 needs
* OES_draw_buffers_indexed. Where this is false such a draw leaves the record as the opaque scene wrote it.
*/
virtual bool supportsUnblendedSurfaceTarget() const { return false; }
/**
* @brief Most samples an offscreen colour attachment may carry; 1 = none.
* @details The engine owns its own multisampling: a target the scene draws
* into is created with this many samples and resolves itself. Ask
* before requesting samples — a backend answering 1 has no MSAA to
* give, and a target that asks anyway would resolve from nothing.
*/
virtual u32 maxSamples() = 0;
/**
* @brief Whether this backend can resolve a multisampled DEPTH attachment.
* @details GL blits one; WebGPU has no depth resolve at all, so a pass that
* SAMPLES scene depth cannot run multisampled there. Colour resolves
* on both, which is what MSAA is usually asked for.
*/
virtual bool resolvesDepth() const { return false; }
/**
* @brief Asks for the backbuffer to be drawn with this many samples.
* @details Only a backend whose surface is NOT antialiased by the host has
* anything to do here: a WebGL canvas is created antialiased, a
* WebGPU surface texture never is. Ignored where it is free.
*/
virtual void setSurfaceSamples(u32 samples) { (void)samples; }
// =========================================================================
// Shader Programs
// =========================================================================
/**
* @brief Compiles and links a GPU program from GLSL sources.
* @param vertexSrc Vertex shader GLSL source (null-terminated).
* @param fragmentSrc Fragment shader GLSL source (null-terminated).
* @param bindings Attribute location bindings applied before link (may be null if count==0).
* @param bindingCount Number of entries in @p bindings.
* @param outLog Optional; receives the driver info log on failure.
* @param outFailedStage Optional; receives the stage that rejected the source.
* @return The linked program handle, or Invalid on failure.
*/
ShaderHandle createProgram(const GfxShaderSource& source,
const GfxAttribBinding* bindings, u32 bindingCount,
std::string* outLog, GfxShaderStage* outFailedStage);
/** @brief Whether this backend compiles @p language (GL: GLSL ES 300; WebGPU: WGSL). */
virtual bool supportsShaderLanguage(GfxShaderLanguage language) const = 0;
/** @brief Whether createProgram honours GfxShaderSource::deferLink (GL: yes; a backend that links at once does not). */
virtual bool supportsDeferredLink() const { return false; }
/**
* @brief Runs @p callback when @p program has linked, once: now if it already has, at the first thing that needs it otherwise.
* @details For what has to be done to a program only after it links. Never runs for one that fails.
*/
void onProgramLinked(ShaderHandle program, std::function<void()> callback);
/** @brief Waits for @p program to link if it has not yet. False when it failed to. */
bool finishProgram(ShaderHandle program) { return backendFinishProgram(static_cast<u32>(program)); }
/**
* @brief Whether @p program can be drawn with now, without waiting: linked, or finished linking in the background (and then finished here, which
* is quick). False while it is still compiling, and for one that failed. Always true for a program that was not deferred.
*/
bool programReady(ShaderHandle program) { return backendProgramReady(static_cast<u32>(program)); }
/**
* @brief How many programs made with deferLink are still compiling.
* @details Asking finishes the ones that are done (their shader objects are freed, what was owed to them is done), so a program nothing ever
* draws with does not stay on the list: a loading screen waits for this to be 0.
*/
u32 pendingProgramCount() { return backendPendingProgramCount(); }
/**
* @brief Whether a draw whose program is not ready is left out, instead of waited for.
* @details Off: the first draw to need a program waits for it, and a frame that needs one the browser has not compiled yet stops (seconds, for a
* heavy lit shader on a driver that compiles slowly). On: the draw is skipped until the program is ready, and the frame goes on.
*/
void setSkipPendingPrograms(bool on) { skip_pending_programs_ = on; }
bool skipPendingPrograms() const { return skip_pending_programs_; }
/**
* @brief Whether texel (0,0) of a rendered texture is its TOP-left corner.
*
* @details GL stores a framebuffer bottom-up and WebGPU top-down, so one geometry
* through one matrix lands in opposite rows. A shader sampling a target
* this frame rendered cannot ask — one source serves both backends — so
* the answer travels as data.
*/
virtual bool textureOriginTopLeft() const = 0;
/** @brief Deletes a shader program */
void deleteProgram(ShaderHandle program);
// =========================================================================
// Compute
// =========================================================================
/**
* @brief Whether this device runs compute shaders.
* @details WebGPU does; WebGL2 has no compute stage, so a caller asks first and keeps a fallback. The calls below
* are harmless on a device that does not: they refuse (Invalid, false) and draw nothing.
*/
virtual bool supportsCompute() const { return false; }
/**
* @brief Compiles a compute program.
* @return The program, or Invalid with @p outLog saying why (no compute, wrong language, a WGSL error).
*/
ComputeHandle createCompute(const GfxComputeSource& source, std::string* outLog = nullptr);
/** @brief Deletes a compute program. */
void deleteCompute(ComputeHandle program);
/**
* @brief Runs @p program over @p groupsX x @p groupsY x @p groupsZ workgroups, with these resources bound.
*
* @details Outside a render pass, in submission order with every pass before and after it, so what an earlier
* pass drew is there to read and what this writes is there for the next to sample. A storage buffer
* or texture is bound for write only by the bindings listed; the rest of the device's state is
* untouched.
* @return false when nothing ran: the device does not compute, a resource named is gone, a render pass is
* open, or a count is zero or over the device's limit.
*/
bool dispatchCompute(ComputeHandle program, const GfxComputeBinding* bindings, u32 bindingCount,
u32 groupsX, u32 groupsY = 1, u32 groupsZ = 1);
/**
* @brief Copies bytes of a storage buffer out, to be taken with pollReadback / takeReadback.
* @details takeReadback hands the bytes back as they are in the buffer; @p size and @p offsetBytes are
* multiples of 4. Invalid on a device that does not compute.
*/
virtual ReadbackHandle requestBufferReadback(BufferHandle buffer, u32 offsetBytes, u32 sizeBytes) {
(void)buffer; (void)offsetBytes; (void)sizeBytes;
return ReadbackHandle::Invalid;
}
/**
* @brief Copies a storage texture's pixels out, tightly packed in the texture's own format (rows top-down).
* @details Unlike requestReadback it names the texture, not a framebuffer, since a compute target has none.
* RGBA8, RGBA16F and RGBA32F: four, eight and sixteen bytes a texel.
*/
virtual ReadbackHandle requestTextureReadback(TextureHandle texture) {
(void)texture;
return ReadbackHandle::Invalid;
}
/**
* @brief Binds a program directly, for setup-time uniform seeding.
* @details Per-frame rendering binds programs through setPipeline.
*/
void useProgram(ShaderHandle program);
/**
* @brief Gets a uniform location by name, -1 when the linked program has none.
* @details The location belongs to the device, not the backend: it stays valid
* across a relink, and the value last set through it is set again.
*/
i32 getUniformLocation(ShaderHandle program, const char* name);
/** @brief Gets a vertex attribute location by name (-1 if not found) */
i32 getAttribLocation(ShaderHandle program, const char* name);
/**
* @brief The texture units the bound program samples, one bit a unit; every unit where the backend cannot say.
*
* @details A unit no active sampler reads can hold anything, so a draw binds only these: what a depth program, a
* shadow caster or a material that leaves maps unset never reads is never bound for it.
*/
u32 boundSamplerUnits() { return backendBoundSamplerUnits(); }
/** @brief Sets an integer uniform of the bound program */
void setUniform1i(i32 location, i32 value);
/** @brief Sets a float uniform */
void setUniform1f(i32 location, f32 value);
/** @brief Sets a vec2 uniform */
void setUniform2f(i32 location, f32 x, f32 y);
/** @brief Sets a vec3 uniform */
void setUniform3f(i32 location, f32 x, f32 y, f32 z);
/** @brief Sets a vec4 uniform */
void setUniform4f(i32 location, f32 x, f32 y, f32 z, f32 w);
/** @brief Sets a mat3 uniform */
void setUniformMat3(i32 location, const f32* data);
/** @brief Sets a mat4 uniform */
void setUniformMat4(i32 location, const f32* data);
/** @brief Enumerates all active uniforms of a linked shader program */
std::vector<GfxUniformInfo> getActiveUniforms(ShaderHandle program);
/** @brief Returns a program's uniform-block index by name, or GFX_INVALID_UNIFORM_BLOCK if absent. */
u32 getUniformBlockIndex(ShaderHandle program, const char* name);
/** @brief Links a program's uniform block to an indexed binding slot. */
void uniformBlockBinding(ShaderHandle program, u32 blockIndex, u32 bindingPoint);
// =========================================================================
// Pipeline State (immutable "how to draw"; see PipelineState.hpp)
// =========================================================================
/** @brief Resolves a pipeline description to a cached handle (creating it on first use). */
PipelineHandle createPipeline(const PipelineDesc& desc);
/** @brief A pipeline's description, or null for a handle that names none. */
const PipelineDesc* pipelineDesc(PipelineHandle handle) const;
/** @brief Binds a pipeline: applies its program, blend, depth, stencil compare/op and culling. */
void setPipeline(PipelineHandle handle);
/** @brief Sets the dynamic stencil reference for the bound pipeline's stencil mode (no-op if Off). */
virtual void setStencilReference(i32 ref) = 0;
/**
* @brief Forces the next setPipeline to re-apply, dropping the cached current pipeline.
* @details Call at the start of a render phase (frame flush, immediate-draw begin) so a
* pipeline left bound by a prior phase — or by a direct-state path like custom
* geometry — is not mistaken for the current one.
*/
void invalidatePipelineCache();
// =========================================================================
// Draw Calls
// =========================================================================
/** @brief Draws indexed triangles */
virtual void drawElements(u32 indexCount, GfxDataType indexType, u32 byteOffset) = 0;
/** @brief Draws non-indexed triangles */
virtual void drawArrays(u32 first, u32 vertexCount) = 0;
/** @brief Draws indexed triangles with instancing */
virtual void drawElementsInstanced(u32 indexCount, GfxDataType indexType, u32 byteOffset, u32 instanceCount) = 0;
/** @brief Whether drawElementsInstancedMulti is one call here, its draws told apart by gl_DrawID (WEBGL_multi_draw). */
virtual bool supportsMultiDraw() const { return false; }
/**
* @brief @p drawCount indexed instanced draws through the bound pipeline and buffers, as one call where supportsMultiDraw().
* @details Draw k reads counts[k] indices from byteOffsets[k], instanceCounts[k] times, and its vertex stage sees gl_DrawID
* = k. Elsewhere it is the draws one after another, which is the same picture only for a program that does not read
* gl_DrawID; the draw list asks for runs only where the device has said it draws them.
*/
virtual void drawElementsInstancedMulti(GfxDataType indexType, const u32* counts, const u32* byteOffsets,
const u32* instanceCounts, u32 drawCount) {
for (u32 k = 0; k < drawCount; ++k) drawElementsInstanced(counts[k], indexType, byteOffsets[k], instanceCounts[k]);
}
// =========================================================================
// Framebuffers
// =========================================================================
/**
* @brief Creates a framebuffer from its attachments and validates completeness.
* @return The framebuffer handle, or Default (0) when incomplete — the default
* framebuffer can never be created, so 0 unambiguously means failure.
*/
FramebufferHandle createFramebuffer(const FramebufferDesc& desc);
/** @brief Deletes a framebuffer (its attachment textures are owned by the caller) */
void deleteFramebuffer(FramebufferHandle framebuffer);
/** @brief A framebuffer's description, or null for Default and unknown handles. */
const FramebufferDesc* framebufferDesc(FramebufferHandle framebuffer) const;
// =========================================================================
// Render Pass
// =========================================================================
/**
* @brief Targets a framebuffer for subsequent draws and applies the pass's clears.
* @details Beginning a pass while another is open retargets directly (the GL
* model has no explicit pass object); endRenderPass returns to the
* backbuffer. A WebGPU backend maps this to real pass boundaries.
*/
virtual void beginRenderPass(const RenderPassDesc& desc) = 0;
/** @brief Ends the current pass, restoring the default framebuffer */
virtual void endRenderPass() = 0;
/**
* @brief The frame is over — everything drawn for it has been submitted.
* @details A backend that borrows the swapchain image for the duration of a
* frame gives it back here (WebGPU hands one out per frame and takes
* it back at present), which is why the boundary has to be stated
* rather than inferred from the last pass: a frame may open several
* passes on the swapchain — a post-process blit over the captured
* scene, a second camera — and each of those is NOT the end.
* Default: nothing to do (GL presents through the platform).
*/
virtual void endFrame() {}
/**
* @brief Resizes the default backbuffer to the viewport size.
* @details GL tracks the canvas drawing buffer implicitly (default no-op);
* WebGPU swapchains are fixed-size, so its backend reconfigures
* the surface + companion depth-stencil when the size changes.
* Called once per frame with the current viewport (cheap when
* unchanged); must not be called inside a render pass.
*/
virtual void resizeBackbuffer(u32 width, u32 height) {
(void)width;
(void)height;
}
// =========================================================================
// Readback (asynchronous seam — the one backend-neutral pixel-return path)
// =========================================================================
/**
* @brief Requests an RGBA8 readback of a framebuffer's color attachment.
* @details Backend-neutral contract: GL reads synchronously (the first poll
* reports Ready); WebGPU records a texture→staging copy and resolves
* when the buffer map lands, so callers must poll across event-loop
* turns. Must be called OUTSIDE a render pass. Rows land bottom-up
* (the GL convention every capture consumer assumes). The WebGPU
* backend reads offscreen targets only — the surface texture is not
* copyable — so a Default-target request returns Invalid there.
* @return A handle to poll, or Invalid when the request cannot be issued.
*/
virtual ReadbackHandle requestReadback(FramebufferHandle target, u32 w, u32 h) = 0;
/** @brief The state of an in-flight readback; pumps backend completion events.
* A Failed readback is released by the poll that reported it. */
virtual GfxReadbackStatus pollReadback(ReadbackHandle handle) = 0;
/**
* @brief Copies a Ready readback's pixels (w*h*4 bytes) into @p dest and releases it.
* @return False when the handle is unknown, still Pending, or @p destSize is short —
* a Pending readback stays alive.
*/
virtual bool takeReadback(ReadbackHandle handle, void* dest, usize destSize) = 0;
/** @brief Abandons a readback (any state); its resources are released. */
virtual void discardReadback(ReadbackHandle handle) = 0;
/**
* @brief Requests the next completed frame's on-screen image as a readback.
* @details One question, whichever backend answers it: a default framebuffer
* is read directly, a swapchain image only inside its own frame.
* Poll and take it like any other readback.
*/
virtual ReadbackHandle captureNextFrame(u32 w, u32 h) {
return requestReadback(FramebufferHandle::Default, w, h);
}
/** @brief Whether a captured frame's bytes are BGRA rather than RGBA — the
* surface's choice on a backend that has one, and never GL's. */
virtual bool frameCaptureIsBGRA() const { return false; }
// =========================================================================
// GPU Timing (optional; EXT_disjoint_timer_query on WebGL2)
// =========================================================================
/** @brief Creates a GPU elapsed-time query, or 0 when the backend cannot time GPU work. */
u32 createTimerQuery();
/**
* @brief Starts timing GPU work into a query; one query may be active at a time.
* @details The same span on every backend: the GPU's time for everything issued until endTimerQuery, every pass
* included. A render pass still open at the end belongs to the span up to where the pass ends.
*/
virtual void beginTimerQuery(u32 query) = 0;
/** @brief Stops the active timer query */
virtual void endTimerQuery() = 0;
/**
* @brief True when GPU timing was disturbed since the last check.
* @details In-flight query results are then meaningless and must be discarded.
*/
virtual bool timerDisjoint() = 0;
/** @brief Fetches a completed query's elapsed nanoseconds; false while still pending. */
virtual bool getTimerQueryNs(u32 query, u64* outNanoseconds) = 0;
/**
* @brief True when a pass is timed by arming it, not by bracketing it with begin/endTimerQuery.
* @details A GL query spans whatever is issued between its two calls; a WebGPU timestamp is written by the pass that
* carries it, so the pass has to be named before it opens. A per-pass timer picks its calls by this.
*/
virtual bool timesPassesByArming() const { return false; }
/**
* @brief Times the next render or compute pass into @p query (0 disarms), read back with getTimerQueryNs.
* @details Only where timesPassesByArming(). A pass that is split in two by the device (a mid-pass copy) is timed up
* to the split.
*/
virtual void armPassTimer(u32 query) { (void)query; }
// =========================================================================
// Debug
// =========================================================================
/** @brief Enables or disables wireframe rendering (desktop only) */
virtual void setWireframe(bool enabled) = 0;
/** @brief Queries the last error */
virtual u32 getError() = 0;
/** @brief Queries a backend identification string (diagnostics) */
virtual std::string getString(GfxStringName name) = 0;
/** @brief Queries a backend integer capability/limit */
virtual i32 getInt(GfxIntParam name) = 0;
/** @brief GPU objects alive right now (see {@link GfxLiveObjects}), read off the registry. */
GfxLiveObjects liveObjects() const;
/** Estimated live buffer/texture storage, including target attachments.
* Excludes driver overhead, shader binaries and host-owned swapchain images. */
virtual u64 estimatedGpuBytes() const;
/**
* @brief The backend's own name for the object behind `texture`, or 0.
* @details For a host that writes the contents itself — a JS video frame or
* canvas going straight into the texture. It is only valid until the
* next device loss, which is why it is asked for at every write.
*/
virtual u32 nativeTextureName(TextureHandle texture) const { (void)texture; return 0; }
protected:
/** @brief A backend has issued one draw (see takeDraws). */
void countDraw() { ++draws_; }
// =========================================================================
// Backend primitives. `id` is the handle's value; the backend maps it to its
// own object for the current generation and nothing else.
// =========================================================================
virtual bool backendCreateBuffer(u32 id, const BufferDesc& desc, const void* data) = 0;
virtual void backendDeleteBuffer(u32 id) = 0;
virtual void backendUpdateBuffer(u32 id, u32 offsetBytes, const void* data, u32 sizeBytes) = 0;
virtual void backendResizeBuffer(u32 id, const BufferDesc& desc, const void* data) = 0;
virtual void backendSetUniformBuffer(u32 slot, BufferHandle buffer, u32 offsetBytes, u32 sizeBytes) = 0;
virtual bool backendCreateTexture(u32 id, const TextureDesc& desc, const void* pixels) = 0;
virtual bool backendCreateCompressedTexture(u32 id, const TextureDesc& desc, GfxCompressedFormat format,
const void* data, u32 byteLength, u32 mipLevels) = 0;
/** @brief Takes over a native texture the host created; false when this backend cannot. */
virtual bool backendAdoptTexture(u32 id, u32 nativeId, const TextureDesc& desc) = 0;
virtual void backendDeleteTexture(u32 id) = 0;
/** @brief Re-keys @p from's native texture under @p into; @p into holds none on entry. */
virtual void backendMoveTexture(u32 into, u32 from) = 0;
virtual void backendUpdateTexture(u32 id, i32 x, i32 y, u32 width, u32 height,
const void* pixels, bool flipY) = 0;
virtual void backendSetTextureParams(u32 id, const TextureDesc& desc) = 0;
virtual void backendGenerateMipmaps(u32 id) = 0;
virtual bool backendCreateCompute(u32 id, const GfxComputeSource& source, std::string* outLog) {
(void)id; (void)source;
if (outLog) *outLog = "this device has no compute stage";
return false;
}
virtual void backendDeleteCompute(u32 id) { (void)id; }
virtual bool backendDispatchCompute(u32 id, const GfxComputeBinding* bindings, u32 bindingCount,
u32 groupsX, u32 groupsY, u32 groupsZ) {
(void)id; (void)bindings; (void)bindingCount; (void)groupsX; (void)groupsY; (void)groupsZ;
return false;
}
virtual bool backendCreateProgram(u32 id, const GfxShaderSource& source,
const GfxAttribBinding* bindings, u32 bindingCount,
std::string* outLog, GfxShaderStage* outFailedStage) = 0;
virtual void backendDeleteProgram(u32 id) = 0;
/** @brief True while a program created with deferLink has not been waited for. */
virtual bool backendProgramPending(u32 id) const { (void)id; return false; }
virtual bool backendProgramReady(u32 id) { (void)id; return true; }
virtual u32 backendPendingProgramCount() { return 0; }
/** @brief Waits for a deferred program, runs its onLinked callback; false when it failed to link. True for a program that was not deferred. */
virtual bool backendFinishProgram(u32 id) { (void)id; return true; }
/** @brief For a backend finishing a deferred program: runs its onLinked callback, leaving the bound program as it was. */
void notifyProgramLinked(u32 id);
virtual void backendUseProgram(u32 id) = 0;
/** @brief The backend's own location this generation, -1 when absent. */
virtual i32 backendUniformLocation(u32 program, const char* name) = 0;
virtual i32 backendAttribLocation(u32 program, const char* name) = 0;
virtual void backendSetUniform(i32 nativeLocation, const GfxUniformValue& value) = 0;
/** The units the bound program samples; a backend that cannot say answers every unit. */
virtual u32 backendBoundSamplerUnits() { return 0xFFFFFFFFu; }
/** An integer uniform of @p program was set: a sampler may have moved to another unit. */
virtual void backendIntUniformSet(u32 program) { (void)program; }
virtual std::vector<GfxUniformInfo> backendActiveUniforms(u32 program) = 0;
virtual u32 backendUniformBlockIndex(u32 program, const char* name) = 0;
virtual void backendUniformBlockBinding(u32 program, u32 nativeBlockIndex, u32 bindingPoint) = 0;
/** @brief False for a layout this backend has no way to express. */
virtual bool backendAcceptsVertexLayout(const VertexLayoutDesc& desc) { (void)desc; return true; }
/** @brief Drops what the backend derived from a layout (a GL VAO); the desc stays here. */
virtual void backendDeleteVertexLayout(u32 id) = 0;
virtual void backendSetPipeline(u32 id, const PipelineDesc& desc) = 0;
virtual void backendInvalidatePipelineCache() = 0;
virtual bool backendCreateFramebuffer(u32 id, const FramebufferDesc& desc) = 0;
virtual void backendDeleteFramebuffer(u32 id) = 0;
virtual bool backendCreateTimerQuery(u32 id) = 0;
/** @brief Readbacks in flight, the one live object the registry does not hold. */
virtual u32 backendReadbackCount() const = 0;
/** @brief The pipeline most recently bound, whose program uniforms are set on. */
PipelineHandle currentPipeline() const { return current_pipeline_; }
/// Backends record what they were last handed; see @ref viewport.
Viewport viewport_;
/**
* @brief Records who this backend is, so a later loss report can name it.
* @details Called from init() while the backend still answers, and again
* after a recovery: a rebuilt device can be a DIFFERENT GPU, and a
* report naming the one that is gone sends the reader hunting the
* wrong hardware. Implementations call setDeviceIdentity.
*/
virtual void captureDeviceIdentity() {}
/**
* @brief Backend half of {@link recoverDevice}: a working device again, with
* every id-to-native map and derived cache emptied.
* @details The registry then rebuilds each object through the primitives above.
* Default: this backend cannot rebuild itself, so a loss is final.
*/
virtual bool recreateDevice() { return false; }
/** @brief Records the backend identity; see {@link captureDeviceIdentity}. */
void setDeviceIdentity(std::string backend, std::string vendor,
std::string renderer, std::string version) {
identity_.backend = std::move(backend);
identity_.vendor = std::move(vendor);
identity_.renderer = std::move(renderer);
identity_.version = std::move(version);
}
/**
* @brief The single transition into Lost. Backends call this on detection.
* @details Idempotent: a lost device usually produces a burst of secondary
* failures, and the first reason is the one that explains them.
* @return True when this call performed the transition.
*/
bool markDeviceLost(GfxDeviceLostReason reason, std::string message = {},
std::string context = {});
/**
* @brief Release what only this backend can name, while the dead device is
* still the current one.
* @details The window matters: on a lost device these releases are silent
* no-ops, whereas after the rebuild the same calls hand a NEW
* device objects belonging to the old one.
*/
virtual void onDeviceLost() {}
private:
/** @brief Builds every recorded object on the current device, in dependency order. */
void realizeRegistry();
void realizeProgramState(u32 id, GfxProgramRecord& record);
/** @brief Recovering becomes Live once nothing is owed. */
void settleRecovery();
void payTexture(u32 id, GfxTextureRecord& record);
void keepBytes(std::vector<u8>& slot, std::vector<u8> bytes);
void dropBytes(std::vector<u8>& slot);
std::vector<u8> takeBytes(std::vector<u8>& slot);
void judgeRetainedBudget(usize grownBy);
void eraseBuffer(u32 id);
void eraseTexture(u32 id);
i32 nativeUniformLocation(GfxProgramRecord& record, u32 id, i32 location);
void setUniformValue(i32 location, const GfxUniformValue& value);
GfxDeviceStatus device_status_ = GfxDeviceStatus::Live;
GfxDeviceIdentity identity_;
GfxDeviceLostInfo device_info_;
u64 device_frame_ = 0;
u64 device_generation_ = 0;
u64 geometry_writes_ = 0;
void countGeometryWrite(const BufferDesc& desc) {
if (!desc.dynamic && (desc.usage == GfxBufferUsage::Vertex || desc.usage == GfxBufferUsage::Index)) ++geometry_writes_;
}
std::function<void(const GfxDeviceLostInfo&)> device_lost_handler_;
GfxResourceRegistry registry_;
u32 owed_count_ = 0;
usize retained_bytes_ = 0;
u32 draws_ = 0;
usize retained_budget_ = 0;
bool over_retained_budget_ = false;
ShaderHandle current_program_ = ShaderHandle::Invalid;
bool skip_pending_programs_ = false;
PipelineHandle current_pipeline_ = PipelineHandle::Invalid;
/// Native uniform locations per program for the current generation; -2 = not asked yet.
std::map<u32, std::vector<i32>> native_locations_;
};
} // namespace esengine