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.

feat(engine): per-frame GPU timer via EXT_disjoint_timer_query

esengine5afe3550a5d1
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index b1c77ea18..9ea357ea2 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -288,6 +288,8 @@ export interface ESEngineModule {
renderer_getSpine?(): number;
renderer_getMeshes(): number;
renderer_getCulled(): number;
+ /** Last frame's GPU time (ms) via EXT_disjoint_timer_query, or -1 if unavailable. */
+ renderer_getGpuTimeMs?(): number;
renderer_setClearColor(r: number, g: number, b: number, a: number): void;
renderer_setViewport(x: number, y: number, w: number, h: number): void;
renderer_setScissor(x: number, y: number, w: number, h: number, enable: boolean): void;
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 6b7a83d75..df58872ee 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -413,6 +413,11 @@ u32 renderer_getCulled() {
return g_renderFrame->stats().culled;
}
+f32 renderer_getGpuTimeMs() {
+ if (!g_renderFrame) return -1.0f;
+ return g_renderFrame->stats().gpu_time_ms;
+}
+
void renderer_setDeltaTime(f32 dt) {
ctx().state().delta_time = dt;
}
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index f7da2343f..50079e972 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -106,6 +106,7 @@ u32 renderer_getSpine();
u32 renderer_getText();
u32 renderer_getMeshes();
u32 renderer_getCulled();
+f32 renderer_getGpuTimeMs();
void renderer_setDeltaTime(f32 dt);
void renderer_setClearColor(f32 r, f32 g, f32 b, f32 a);
void renderer_setViewport(i32 x, i32 y, i32 w, i32 h);
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 28bb0d890..d27f460fb 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -518,6 +518,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_getText", &esengine::renderer_getText);
emscripten::function("renderer_getMeshes", &esengine::renderer_getMeshes);
emscripten::function("renderer_getCulled", &esengine::renderer_getCulled);
+ emscripten::function("renderer_getGpuTimeMs", &esengine::renderer_getGpuTimeMs);
emscripten::function("renderer_setDeltaTime", &esengine::renderer_setDeltaTime);
emscripten::function("renderer_setClearColor", &esengine::renderer_setClearColor);
emscripten::function("renderer_setViewport", &esengine::renderer_setViewport);
diff --git a/src/esengine/renderer/RenderFrame.cpp b/src/esengine/renderer/RenderFrame.cpp
index 458939101..17031098c 100644
--- a/src/esengine/renderer/RenderFrame.cpp
+++ b/src/esengine/renderer/RenderFrame.cpp
@@ -9,6 +9,10 @@
#include "../ecs/components/ShadowCaster2D.hpp"
#include "../resource/ShaderParser.hpp"
#include "../core/Log.hpp"
+#include "OpenGLHeaders.hpp"
+#ifdef __EMSCRIPTEN__
+#include <emscripten/html5.h>
+#endif
#include <glm/gtc/type_ptr.hpp>
@@ -18,6 +22,65 @@
namespace esengine {
+// EXT_disjoint_timer_query_webgl2 enums — not guaranteed in <GLES3/gl3.h>.
+#ifndef GL_TIME_ELAPSED_EXT
+#define GL_TIME_ELAPSED_EXT 0x88BF
+#endif
+#ifndef GL_GPU_DISJOINT_EXT
+#define GL_GPU_DISJOINT_EXT 0x8FBB
+#endif
+
+void GpuTimer::ensureInit() {
+ if (state_ != 0) return;
+#ifdef __EMSCRIPTEN__
+ // The extension must be ENABLED (not just present) for emscripten to route the
+ // TIME_ELAPSED query entry points; enable returns false when it's unavailable.
+ EMSCRIPTEN_WEBGL_CONTEXT_HANDLE ctx = emscripten_webgl_get_current_context();
+ if (ctx && emscripten_webgl_enable_extension(ctx, "EXT_disjoint_timer_query_webgl2")) {
+ glGenQueries(kRing, queries_);
+ state_ = 1;
+ return;
+ }
+#endif
+ state_ = 2; // unavailable — stays -1ms
+}
+
+void GpuTimer::begin() {
+ ensureInit();
+ if (state_ != 1 || inflight_[write_]) return; // unavailable or ring full → skip
+ glBeginQuery(GL_TIME_ELAPSED_EXT, queries_[write_]);
+ active_ = true;
+}
+
+void GpuTimer::end() {
+ if (!active_) return;
+ glEndQuery(GL_TIME_ELAPSED_EXT);
+ inflight_[write_] = true;
+ write_ = (write_ + 1) % kRing;
+ active_ = false;
+}
+
+void GpuTimer::poll() {
+ if (state_ != 1) return;
+ GLint disjoint = 0;
+ glGetIntegerv(GL_GPU_DISJOINT_EXT, &disjoint);
+ if (disjoint) { // GPU timing was disturbed this window — drop everything in flight
+ for (int i = 0; i < kRing; ++i) inflight_[i] = false;
+ read_ = write_;
+ return;
+ }
+ while (inflight_[read_]) {
+ GLuint avail = 0;
+ glGetQueryObjectuiv(queries_[read_], GL_QUERY_RESULT_AVAILABLE, &avail);
+ if (!avail) break; // oldest not ready yet — try again next frame
+ GLuint ns = 0;
+ glGetQueryObjectuiv(queries_[read_], GL_QUERY_RESULT, &ns);
+ last_ms_ = static_cast<f32>(ns) / 1.0e6f;
+ inflight_[read_] = false;
+ read_ = (read_ + 1) % kRing;
+ }
+}
+
f32 Plane::signedDistance(const glm::vec3& point) const {
return glm::dot(normal, point) + distance;
}
@@ -190,7 +253,13 @@ void RenderFrame::flush() {
context_.updateFrameConstants(view_projection_);
context_.lights().uploadAndBind();
+
+ // GPU time for the scene draw: read back prior frames, then bracket this one.
+ gpu_timer_.poll();
+ gpu_timer_.begin();
draw_list_.execute(device_, pool_, context_.materials(), &frame_capture_);
+ gpu_timer_.end();
+ stats_.gpu_time_ms = gpu_timer_.lastMs();
stats_.draw_calls = draw_list_.mergedDrawCallCount();
for (u32 i = 0; i < draw_list_.commandCount(); ++i) {
diff --git a/src/esengine/renderer/RenderFrame.hpp b/src/esengine/renderer/RenderFrame.hpp
index 200a7fcba..6973d3255 100644
--- a/src/esengine/renderer/RenderFrame.hpp
+++ b/src/esengine/renderer/RenderFrame.hpp
@@ -38,6 +38,30 @@ struct Frustum {
bool intersectsAABB(const glm::vec3& center, const glm::vec3& halfExtents) const;
};
+// Per-frame GPU timer over EXT_disjoint_timer_query_webgl2 (GL_TIME_ELAPSED). A
+// small ring of query objects so readback never stalls the CPU; reports the most
+// recent completed frame's GPU ms, or -1 when unavailable. Only POD state lives
+// here — the methods (which touch GL / emscripten) are defined in RenderFrame.cpp
+// so no GL headers leak through this widely-included header.
+class GpuTimer {
+public:
+ void begin(); // bracket the frame's draw submission (no-op if unavailable)
+ void end();
+ void poll(); // read back finished queries → last_ms_
+ f32 lastMs() const { return last_ms_; }
+
+private:
+ void ensureInit(); // lazy: enable the extension + gen queries on first use
+ static constexpr int kRing = 3;
+ unsigned queries_[kRing] = {0, 0, 0};
+ bool inflight_[kRing] = {false, false, false};
+ int write_ = 0;
+ int read_ = 0;
+ int state_ = 0; // 0 = uninit, 1 = available, 2 = unavailable
+ bool active_ = false;
+ f32 last_ms_ = -1.0f;
+};
+
class RenderFrame {
public:
struct Stats {
@@ -52,6 +76,9 @@ public:
u32 particles = 0;
u32 shapes = 0;
u32 culled = 0;
+ // Last completed frame's GPU time (ms) via EXT_disjoint_timer_query, or -1
+ // when the timer isn't available (extension missing / driver disjoint).
+ f32 gpu_time_ms = -1.0f;
};
RenderFrame(GfxDevice& device, RenderContext& context,
@@ -169,6 +196,7 @@ private:
RenderStage current_stage_ = RenderStage::Transparent;
Stats stats_;
+ GpuTimer gpu_timer_;
FrameCapture frame_capture_;
std::vector<u8> snapshot_pixels_;
RenderTargetManager::Handle replay_rt_ = 0;