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(rc6): GfxDevice compressed-texture entry + capability query (RC6-A)

esengineea29fb6b3317
diff --git a/src/esengine/renderer/GLDevice.cpp b/src/esengine/renderer/GLDevice.cpp
index 624063310..7a248fa4b 100644
--- a/src/esengine/renderer/GLDevice.cpp
+++ b/src/esengine/renderer/GLDevice.cpp
@@ -13,9 +13,35 @@
#include "OpenGLHeaders.hpp"
#include "../core/Log.hpp"
+#include <cstring>
+
#ifndef GL_DEPTH_STENCIL
#define GL_DEPTH_STENCIL 0x84F9
#endif
+#ifndef GL_NUM_EXTENSIONS
+ #define GL_NUM_EXTENSIONS 0x821D
+#endif
+// Compressed-texture internal formats. ETC2/EAC is core in GLES3/WebGL2; ASTC and
+// S3TC are extension tokens that may be absent from the core gl3.h, so fall back to
+// the literal enum values.
+#ifndef GL_COMPRESSED_RGB8_ETC2
+ #define GL_COMPRESSED_RGB8_ETC2 0x9274
+#endif
+#ifndef GL_COMPRESSED_RGBA8_ETC2_EAC
+ #define GL_COMPRESSED_RGBA8_ETC2_EAC 0x9278
+#endif
+#ifndef GL_COMPRESSED_RGBA_ASTC_4x4_KHR
+ #define GL_COMPRESSED_RGBA_ASTC_4x4_KHR 0x93B0
+#endif
+#ifndef GL_COMPRESSED_RGBA_ASTC_8x8_KHR
+ #define GL_COMPRESSED_RGBA_ASTC_8x8_KHR 0x93B7
+#endif
+#ifndef GL_COMPRESSED_RGBA_S3TC_DXT1_EXT
+ #define GL_COMPRESSED_RGBA_S3TC_DXT1_EXT 0x83F1
+#endif
+#ifndef GL_COMPRESSED_RGBA_S3TC_DXT5_EXT
+ #define GL_COMPRESSED_RGBA_S3TC_DXT5_EXT 0x83F3
+#endif
#ifndef GL_UNSIGNED_INT_24_8
#define GL_UNSIGNED_INT_24_8 0x84FA
#endif
@@ -122,6 +148,30 @@ GLPixelFormatInfo toGLPixelFormat(GfxPixelFormat fmt) {
}
}
+GLenum toGLCompressedFormat(GfxCompressedFormat fmt) {
+ switch (fmt) {
+ case GfxCompressedFormat::ETC2_RGB8: return GL_COMPRESSED_RGB8_ETC2;
+ case GfxCompressedFormat::ETC2_RGBA8: return GL_COMPRESSED_RGBA8_ETC2_EAC;
+ case GfxCompressedFormat::ASTC_4x4: return GL_COMPRESSED_RGBA_ASTC_4x4_KHR;
+ case GfxCompressedFormat::ASTC_8x8: return GL_COMPRESSED_RGBA_ASTC_8x8_KHR;
+ case GfxCompressedFormat::S3TC_DXT1: return GL_COMPRESSED_RGBA_S3TC_DXT1_EXT;
+ case GfxCompressedFormat::S3TC_DXT5: return GL_COMPRESSED_RGBA_S3TC_DXT5_EXT;
+ default: return GL_COMPRESSED_RGBA8_ETC2_EAC;
+ }
+}
+
+// GLES3-correct extension probe (glGetString(GL_EXTENSIONS) returns null on a
+// core profile). Emscripten exposes WebGL extensions here under GL-style names.
+bool glExtensionPresent(const char* name) {
+ GLint count = 0;
+ glGetIntegerv(GL_NUM_EXTENSIONS, &count);
+ for (GLint i = 0; i < count; ++i) {
+ const char* ext = reinterpret_cast<const char*>(glGetStringi(GL_EXTENSIONS, static_cast<GLuint>(i)));
+ if (ext && std::strcmp(ext, name) == 0) return true;
+ }
+ return false;
+}
+
GLenum toGLAttachment(GfxAttachment attachment) {
switch (attachment) {
case GfxAttachment::Color0: return GL_COLOR_ATTACHMENT0;
@@ -605,6 +655,15 @@ void GLDevice::texSubImage2D(u32 textureId, i32 xoffset, i32 yoffset,
gl.format, gl.type, data);
}
+void GLDevice::compressedTexImage2D(u32 textureId, u32 width, u32 height,
+ GfxCompressedFormat format,
+ const void* data, u32 byteLength) {
+ glBindTexture(GL_TEXTURE_2D, textureId);
+ glCompressedTexImage2D(GL_TEXTURE_2D, 0, toGLCompressedFormat(format),
+ static_cast<GLsizei>(width), static_cast<GLsizei>(height),
+ 0, static_cast<GLsizei>(byteLength), data);
+}
+
void GLDevice::setTextureParams(u32 textureId, TextureFilter min, TextureFilter mag,
TextureWrap wrapS, TextureWrap wrapT) {
glBindTexture(GL_TEXTURE_2D, textureId);
@@ -701,4 +760,21 @@ i32 GLDevice::getInt(GfxIntParam name) {
return static_cast<i32>(v);
}
+bool GLDevice::supportsCompressedFormat(GfxCompressedFormat format) {
+ switch (format) {
+ case GfxCompressedFormat::ETC2_RGB8:
+ case GfxCompressedFormat::ETC2_RGBA8:
+ return true; // ETC2/EAC is core in GLES3 / WebGL2 — no extension needed
+ case GfxCompressedFormat::ASTC_4x4:
+ case GfxCompressedFormat::ASTC_8x8:
+ return glExtensionPresent("GL_KHR_texture_compression_astc_ldr")
+ || glExtensionPresent("WEBGL_compressed_texture_astc");
+ case GfxCompressedFormat::S3TC_DXT1:
+ case GfxCompressedFormat::S3TC_DXT5:
+ return glExtensionPresent("GL_EXT_texture_compression_s3tc")
+ || glExtensionPresent("WEBGL_compressed_texture_s3tc");
+ }
+ return false;
+}
+
} // namespace esengine
diff --git a/src/esengine/renderer/GLDevice.hpp b/src/esengine/renderer/GLDevice.hpp
index fbe9c1ac2..1c8beba03 100644
--- a/src/esengine/renderer/GLDevice.hpp
+++ b/src/esengine/renderer/GLDevice.hpp
@@ -102,6 +102,9 @@ public:
void texSubImage2D(u32 textureId, i32 xoffset, i32 yoffset,
u32 width, u32 height,
GfxPixelFormat format, const void* data) override;
+ void compressedTexImage2D(u32 textureId, u32 width, u32 height,
+ GfxCompressedFormat format,
+ const void* data, u32 byteLength) override;
void setTextureParams(u32 textureId, TextureFilter min, TextureFilter mag,
TextureWrap wrapS, TextureWrap wrapT) override;
void generateMipmaps(u32 textureId) override;
@@ -120,6 +123,7 @@ public:
u32 getError() override;
std::string getString(GfxStringName name) override;
i32 getInt(GfxIntParam name) override;
+ bool supportsCompressedFormat(GfxCompressedFormat format) override;
};
} // namespace esengine
diff --git a/src/esengine/renderer/GfxDevice.hpp b/src/esengine/renderer/GfxDevice.hpp
index 6e28ab2be..09fb4539b 100644
--- a/src/esengine/renderer/GfxDevice.hpp
+++ b/src/esengine/renderer/GfxDevice.hpp
@@ -267,6 +267,18 @@ public:
u32 width, u32 height,
GfxPixelFormat format, const void* data) = 0;
+ /**
+ * @brief Allocates texture storage from pre-compressed GPU block data.
+ * @param byteLength Size of the compressed payload in bytes.
+ * @details Pure addition alongside texImage2D — the uncompressed path is
+ * unchanged. The caller must first confirm the backend supports
+ * `format` (see supportsCompressedFormat) and fall back to RGBA8
+ * otherwise. Data is uploaded as-is; no CPU-side decode.
+ */
+ virtual void compressedTexImage2D(u32 textureId, u32 width, u32 height,
+ GfxCompressedFormat format,
+ const void* data, u32 byteLength) = 0;
+
/** @brief Sets texture filtering and wrap parameters */
virtual void setTextureParams(u32 textureId, TextureFilter min, TextureFilter mag,
TextureWrap wrapS, TextureWrap wrapT) = 0;
@@ -326,6 +338,14 @@ public:
/** @brief Queries a backend integer capability/limit */
virtual i32 getInt(GfxIntParam name) = 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 compressedTexImage2D with a non-core format.
+ */
+ virtual bool supportsCompressedFormat(GfxCompressedFormat format) = 0;
};
} // namespace esengine
diff --git a/src/esengine/renderer/GfxEnums.hpp b/src/esengine/renderer/GfxEnums.hpp
index 568b4e17a..235d801aa 100644
--- a/src/esengine/renderer/GfxEnums.hpp
+++ b/src/esengine/renderer/GfxEnums.hpp
@@ -80,6 +80,33 @@ enum class GfxPixelFormat : u8 {
Depth24Stencil8,
};
+// =============================================================================
+// Compressed Texture Format (GPU-compressed internal formats)
+// =============================================================================
+
+/**
+ * @brief GPU-compressed texture internal formats for compressedTexImage2D.
+ *
+ * @details Decoded textures stay compressed in VRAM (4–8× smaller than RGBA8),
+ * the key constraint on mobile. Tiering:
+ * - **ETC2/EAC** — core in the WebGL2 / GLES3 spec; available wherever
+ * WebGL2 is, no extension. The safe baseline.
+ * - **ASTC** — `WEBGL_compressed_texture_astc` (iOS A8+, most modern
+ * Android); best quality/size. Query before use.
+ * - **S3TC/DXT** — `WEBGL_compressed_texture_s3tc` (desktop GPUs).
+ *
+ * Always gate ASTC/S3TC behind GfxDevice::supportsCompressedFormat and
+ * fall back to the uncompressed RGBA8 path.
+ */
+enum class GfxCompressedFormat : u8 {
+ ETC2_RGB8, ///< GL_COMPRESSED_RGB8_ETC2 (core)
+ ETC2_RGBA8, ///< GL_COMPRESSED_RGBA8_ETC2_EAC (core)
+ ASTC_4x4, ///< GL_COMPRESSED_RGBA_ASTC_4x4_KHR (extension)
+ ASTC_8x8, ///< GL_COMPRESSED_RGBA_ASTC_8x8_KHR (extension)
+ S3TC_DXT1, ///< GL_COMPRESSED_RGBA_S3TC_DXT1_EXT (extension)
+ S3TC_DXT5, ///< GL_COMPRESSED_RGBA_S3TC_DXT5_EXT (extension)
+};
+
// =============================================================================
// Framebuffer Attachment
// =============================================================================
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index c43177848..84b5801d3 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -94,3 +94,11 @@ add_executable(test_buffer_device
)
target_include_directories(test_buffer_device PRIVATE ${CMAKE_SOURCE_DIR}/src)
add_test(NAME test_buffer_device COMMAND test_buffer_device)
+
+# GfxDevice compressed-texture entry (RC6-A). Header-only: drives MockGfxDevice to
+# assert the compressed upload + capability-gated RGBA8 fallback. No GL, no emsdk.
+add_executable(test_compressed_format
+ renderer/test_compressed_format.cpp
+)
+target_include_directories(test_compressed_format PRIVATE ${CMAKE_SOURCE_DIR}/src)
+add_test(NAME test_compressed_format COMMAND test_compressed_format)
diff --git a/tests/renderer/MockGfxDevice.hpp b/tests/renderer/MockGfxDevice.hpp
index 258a36cb8..fb22d7c5d 100644
--- a/tests/renderer/MockGfxDevice.hpp
+++ b/tests/renderer/MockGfxDevice.hpp
@@ -28,10 +28,14 @@ struct MockGfxDevice final : GfxDevice {
int deleteTextureCalls = 0;
int texImage2DCalls = 0;
int texSubImage2DCalls = 0;
+ int compressedTexImage2DCalls = 0;
int setTextureParamsCalls = 0;
int generateMipmapsCalls = 0;
u32 nextTextureId = 100;
u32 lastDeletedTexture = 0;
+ GfxCompressedFormat lastCompressedFormat = GfxCompressedFormat::ETC2_RGBA8;
+ u32 lastCompressedByteLength = 0;
+ bool compressedSupported = true; // toggle to exercise the RGBA8 fallback path
int createFramebufferCalls = 0;
int deleteFramebufferCalls = 0;
int framebufferTexture2DCalls = 0;
@@ -119,6 +123,11 @@ struct MockGfxDevice final : GfxDevice {
void deleteTexture(u32 id) override { ++deleteTextureCalls; lastDeletedTexture = id; }
void texImage2D(u32, u32, u32, GfxPixelFormat, const void*) override { ++texImage2DCalls; }
void texSubImage2D(u32, i32, i32, u32, u32, GfxPixelFormat, const void*) override { ++texSubImage2DCalls; }
+ void compressedTexImage2D(u32, u32, u32, GfxCompressedFormat format, const void*, u32 byteLength) override {
+ ++compressedTexImage2DCalls;
+ lastCompressedFormat = format;
+ lastCompressedByteLength = byteLength;
+ }
void setTextureParams(u32, TextureFilter, TextureFilter, TextureWrap, TextureWrap) override { ++setTextureParamsCalls; }
void generateMipmaps(u32) override { ++generateMipmapsCalls; }
void pixelStorei(u32, i32) override {}
@@ -136,6 +145,7 @@ struct MockGfxDevice final : GfxDevice {
u32 getError() override { return 0; }
std::string getString(GfxStringName) override { return {}; }
i32 getInt(GfxIntParam) override { return 16; }
+ bool supportsCompressedFormat(GfxCompressedFormat) override { return compressedSupported; }
};
} // namespace esengine
diff --git a/tests/renderer/test_compressed_format.cpp b/tests/renderer/test_compressed_format.cpp
new file mode 100644
index 000000000..4de603db5
--- /dev/null
+++ b/tests/renderer/test_compressed_format.cpp
@@ -0,0 +1,79 @@
+// Native MSVC/CTest harness for the GfxDevice compressed-texture entry (RC6-A).
+//
+// No GL here — it drives MockGfxDevice to prove (1) the interface shape compiles
+// and the mock satisfies the contract, and (2) the capability-gated upload
+// decision: compressed when the device supports the format, RGBA8 fallback
+// otherwise. This is the exact decision TextureLoader will make in Batch C.
+
+#include "MockGfxDevice.hpp"
+
+#include <cstdio>
+#include <vector>
+
+using namespace esengine;
+
+static int g_failures = 0;
+#define CHECK(cond, msg) \
+ do { \
+ if (!(cond)) { std::printf("FAIL: %s\n", msg); ++g_failures; } \
+ else { std::printf("ok: %s\n", msg); } \
+ } while (0)
+
+// The choice the asset upload path makes: prefer the compressed upload, fall back
+// to an uncompressed RGBA8 upload when the backend can't sample the format.
+static void uploadTexture(GfxDevice& d, u32 tex, u32 w, u32 h,
+ GfxCompressedFormat fmt,
+ const void* compressed, u32 compressedLen,
+ const void* rgba) {
+ if (d.supportsCompressedFormat(fmt)) {
+ d.compressedTexImage2D(tex, w, h, fmt, compressed, compressedLen);
+ } else {
+ d.texImage2D(tex, w, h, GfxPixelFormat::RGBA8, rgba);
+ }
+}
+
+int main() {
+ std::vector<u8> blocks(2048, 0xAB);
+ std::vector<u8> rgba(64 * 64 * 4, 0xFF);
+
+ // --- supported: compressed path ---
+ {
+ MockGfxDevice d;
+ d.compressedSupported = true;
+ u32 tex = d.createTexture();
+ uploadTexture(d, tex, 64, 64, GfxCompressedFormat::ASTC_4x4,
+ blocks.data(), static_cast<u32>(blocks.size()), rgba.data());
+ CHECK(d.compressedTexImage2DCalls == 1, "supported -> routes through device.compressedTexImage2D");
+ CHECK(d.texImage2DCalls == 0, "supported -> no RGBA8 upload");
+ CHECK(d.lastCompressedFormat == GfxCompressedFormat::ASTC_4x4, "format forwarded to device");
+ CHECK(d.lastCompressedByteLength == blocks.size(), "compressed byte length forwarded");
+ }
+
+ // --- unsupported: RGBA8 fallback (old assets keep working) ---
+ {
+ MockGfxDevice d;
+ d.compressedSupported = false;
+ u32 tex = d.createTexture();
+ uploadTexture(d, tex, 64, 64, GfxCompressedFormat::ASTC_4x4,
+ blocks.data(), static_cast<u32>(blocks.size()), rgba.data());
+ CHECK(d.compressedTexImage2DCalls == 0, "unsupported -> no compressed upload");
+ CHECK(d.texImage2DCalls == 1, "unsupported -> RGBA8 fallback via device.texImage2D");
+ }
+
+ // --- core ETC2/EAC baseline routes through the compressed entry ---
+ {
+ MockGfxDevice d;
+ u32 tex = d.createTexture();
+ d.compressedTexImage2D(tex, 32, 32, GfxCompressedFormat::ETC2_RGBA8, blocks.data(), 512);
+ CHECK(d.compressedTexImage2DCalls == 1, "ETC2_RGBA8 routes through device");
+ CHECK(d.lastCompressedFormat == GfxCompressedFormat::ETC2_RGBA8, "ETC2 format forwarded");
+ CHECK(d.lastCompressedByteLength == 512, "ETC2 byte length forwarded");
+ }
+
+ if (g_failures == 0) {
+ std::printf("\nALL COMPRESSED-FORMAT TESTS PASSED\n");
+ return 0;
+ }
+ std::printf("\n%d FAILURE(S)\n", g_failures);
+ return 1;
+}