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
feat(native): KTX2 compressed textures (basis transcode + real GPU upload)
esengine5ad5b63726cc
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txtindex db7645945..b81c595ad 100644--- a/native/CMakeLists.txt+++ b/native/CMakeLists.txt@@ -120,13 +120,20 @@ if(ESTELLA_QUICKJS_DIR)target_compile_definitions(qjs PRIVATE _GNU_SOURCE)target_compile_options(qjs PRIVATE -Wno-unused -Wno-sign-compare)+ # basis_universal transcoder (KTX2 -> ETC2/ASTC/BC), one big vendored TU behind+ # host_js/ktx2_decode.cpp, plus basis's bundled single-file zstd decoder (KTX2+ # zstd supercompression). Third-party, so silence their warnings.+ set(BASIS_TRANSCODER "${TP}/basis_universal/transcoder/basisu_transcoder.cpp")+ set(BASIS_ZSTD "${TP}/basis_universal/zstd/zstddeclib.c")+ set_source_files_properties("${BASIS_TRANSCODER}" "${BASIS_ZSTD}" PROPERTIES COMPILE_OPTIONS "-w")+# host_js/host_core.cpp is the platform-independent host; each platform adds its own# glue TU (the event loop, the window, the packaged assets).if(ESTELLA_IOS)# Static: the thin Xcode app (native/ios) links this plus the libraries# below. -ObjC on the app keeps the Obj-C classes in main_ios.mm alive.add_library(estella_js_host STATIC host_js/host_core.cpp host_js/main_ios.mm- host_js/native_audio.cpp "${NATIVE_BINDINGS}")+ host_js/native_audio.cpp host_js/ktx2_decode.cpp "${BASIS_TRANSCODER}" "${BASIS_ZSTD}" "${NATIVE_BINDINGS}")# miniaudio's CoreAudio backend uses AVAudioSession (Obj-C), so its TU must# be Objective-C++ on Apple; it also forces MA_NO_RUNTIME_LINKING there, so# the audio frameworks are linked at build time (the app links the merged@@ -147,7 +154,7 @@ if(ESTELLA_QUICKJS_DIR)# Android: plain C++; miniaudio dlopens AAudio/OpenSL at runtime (no extra# link libs). native_audio.cpp's Obj-C paths are __APPLE__-guarded out.add_library(estella_js_host SHARED host_js/host_core.cpp host_js/main_android.cpp- host_js/native_audio.cpp "${NATIVE_BINDINGS}")+ host_js/native_audio.cpp host_js/ktx2_decode.cpp "${BASIS_TRANSCODER}" "${BASIS_ZSTD}" "${NATIVE_BINDINGS}")target_link_libraries(estella_js_host esengine qjs native_app_glue android log)set_target_properties(estella_js_host PROPERTIES LINK_FLAGS "-u ANativeActivity_onCreate")endif()@@ -155,5 +162,6 @@ if(ESTELLA_QUICKJS_DIR)# the gen dir holds ptraccessors_js.h and the embedded SDK bundle; third_party/miniaudio# is the audio engine header.target_include_directories(estella_js_host PRIVATE- "${CMAKE_CURRENT_SOURCE_DIR}/host_js" "${ESTELLA_NATIVE_GEN_DIR}" "${TP}/miniaudio")+ "${CMAKE_CURRENT_SOURCE_DIR}/host_js" "${ESTELLA_NATIVE_GEN_DIR}" "${TP}/miniaudio"+ "${TP}/basis_universal/transcoder")endif()diff --git a/native/README.md b/native/README.mdindex 0c3a1e911..4cb761d84 100644--- a/native/README.md+++ b/native/README.md@@ -245,7 +245,12 @@ System bindings landing incrementally through the real SDK surfaces:differs per platform. Replies cross back thread-safely (`deliverFetch`) and run on the JSthread in the frame loop. This is what remote asset groups and hot-update need. Simulator-verified (an HTTPS GET returns bytes and a 200); the Android path needs a device retest.--Remaining: KTX2 / compressed textures (native decodes to RGBA only — no basis transcoder-yet) and hardening on a physical device (audio output, the background/foreground-transition, Android's miniaudio audio + JNI fetch paths).+- **KTX2 / compressed textures** — `Assets.loadTexture` on a `.ktx2` path transcodes with+ the host's vendored basis_universal (`es_createTextureKTX2` → `ktx2_decode.cpp`) to the+ best format the device supports (ASTC → ETC2 → BC, RGBA32 fallback) and uploads the+ compressed blocks through the engine's now-real `WebGPUDevice::createCompressedTexture` —+ 4–8× less VRAM than RGBA8. The web KTX2 path (WebGL2 + wasm transcoder) is untouched.+ Simulator-verified (a 64×64 KTX2 sprite renders); base mip only for now.++Remaining: mip chains for compressed textures, and hardening on a physical device (audio+output, the background/foreground transition, Android's miniaudio audio + JNI fetch paths).diff --git a/native/host_js/game.js b/native/host_js/game.jsindex 4dff30ca5..a9780c99e 100644--- a/native/host_js/game.js+++ b/native/host_js/game.js@@ -48,6 +48,20 @@ function init() {world.insert(orbit, ESEngine.ShapeRenderer, {shapeType: 0, color: { r: 1, g: 0.2, b: 0.9, a: 1 }, size: { x: S * 0.12, y: S * 0.12 } });+ // Stage: a KTX2 compressed texture through the SAME Assets API. The host+ // transcodes it (basis) to a device-supported format (ASTC/ETC2) and uploads+ // the compressed blocks — no WebGL2, no wasm transcoder.+ var ktx2Sprite = world.spawn();+ world.insert(ktx2Sprite, ESEngine.Transform, { position: { x: W * 0.5, y: H * 0.28, z: 0 } });+ assets.loadTexture('green.ktx2').then(function (res) {+ world.insert(ktx2Sprite, ESEngine.Sprite, {+ texture: res.handle, color: { r: 1, g: 1, b: 1, a: 1 },+ size: { x: S * 0.24, y: S * 0.24 } });+ console.log('[demo] ktx2: loaded ' + res.width + 'x' + res.height + ' handle=' + res.handle);+ }, function (e) {+ console.error('[demo] ktx2 failed:', e && e.message ? e.message : e);+ });+// Stage C: a startup chime through the REAL SDK Audio API. The native audio// backend decodes beep.wav and plays it in the host's miniaudio engine — the// audio pillar on device, the same Audio API a web game calls.diff --git a/native/host_js/green.ktx2 b/native/host_js/green.ktx2new file mode 100644index 000000000..a4727d8eaBinary files /dev/null and b/native/host_js/green.ktx2 differdiff --git a/native/host_js/host_core.cpp b/native/host_js/host_core.cppindex d29c888ea..b9381d322 100644--- a/native/host_js/host_core.cpp+++ b/native/host_js/host_core.cpp@@ -27,6 +27,7 @@#include "esn_shim.hpp" // quickjs + the esn_* plumbing decls (+ esn_register)#include "esengine_bundle.h" // the real SDK, bundled: installs globalThis.ESEngine#include "native_audio.hpp" // the miniaudio-backed engine behind es_audio*+#include "ktx2_decode.hpp" // basis_universal transcode behind es_createTextureKTX2#include "esengine/core/EstellaContext.hpp"#include "esengine/core/World.hpp"@@ -347,6 +348,25 @@ JSValue js_createTexture(JSContext* ctx, JSValueConst, int argc, JSValueConst* areturn JS_NewInt64(ctx, (int64_t)handle.id());}+// es_createTextureKTX2(ArrayBuffer|TypedArray, srgb?) -> { id, width, height } | null.+// Transcodes a KTX2/Basis container to the best device-supported compressed format+// (or RGBA32) and uploads it — the native counterpart of the web WebGL2 path.+JSValue js_createTextureKTX2(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ if (argc < 1) return JS_NULL;+ std::vector<u8> bytes;+ readByteSource(ctx, argv[0], bytes);+ if (bytes.empty()) return JS_NULL;+ const bool srgb = argc > 1 && JS_ToBool(ctx, argv[1]) != 0;+ auto r = eshost::transcodeKTX2(bytes.data(), bytes.size(), srgb,+ g_app->ctx->require<resource::ResourceManager>(), *g_app->gfx);+ if (r.handle < 0) return JS_NULL;+ JSValue o = JS_NewObject(ctx);+ JS_SetPropertyStr(ctx, o, "id", JS_NewInt32(ctx, r.handle));+ JS_SetPropertyStr(ctx, o, "width", JS_NewInt32(ctx, r.width));+ JS_SetPropertyStr(ctx, o, "height", JS_NewInt32(ctx, r.height));+ return o;+}+// es_releaseTexture(handle) — drop one native ResourceManager reference.JSValue js_releaseTexture(JSContext* ctx, JSValueConst, int, JSValueConst* argv) {int64_t id = 0;@@ -905,6 +925,7 @@ void initJS(App& a) {// createNativeResourceManager binds to (the asset pipeline's texture backend).bindGlobal(a, global, "es_setClear", js_setClear, 3);bindGlobal(a, global, "es_createTexture", js_createTexture, 3);+ bindGlobal(a, global, "es_createTextureKTX2", js_createTextureKTX2, 2);bindGlobal(a, global, "es_releaseTexture", js_releaseTexture, 1);bindGlobal(a, global, "es_getTextureDimensions", js_getTextureDimensions, 1);bindGlobal(a, global, "es_readAsset", js_readAsset, 1);@@ -1019,7 +1040,19 @@ bool boot(Platform& platform) {if (!a.adapter) { LOGE("no adapter"); return false; }auto onD = [](WGPURequestDeviceStatus s, WGPUDevice d, WGPUStringView, void* u, void*) {if (s == WGPURequestDeviceStatus_Success) *static_cast<WGPUDevice*>(u) = d; };+ // Enable the block-compression families this adapter supports (ETC2/ASTC/BC)+ // so the engine can create KTX2 textures; a device rejects a format it did not+ // opt into, even when the adapter advertises it.+ WGPUFeatureName compFeats[3];+ size_t compCount = 0;+ for (WGPUFeatureName f : {WGPUFeatureName_TextureCompressionETC2,+ WGPUFeatureName_TextureCompressionASTC,+ WGPUFeatureName_TextureCompressionBC}) {+ if (wgpuAdapterHasFeature(a.adapter, f)) compFeats[compCount++] = f;+ }WGPUDeviceDescriptor dd = {};+ dd.requiredFeatureCount = compCount;+ dd.requiredFeatures = compCount ? compFeats : nullptr;WGPURequestDeviceCallbackInfo dci = {};dci.mode = WGPUCallbackMode_WaitAnyOnly; dci.callback = onD; dci.userdata1 = &a.device;WGPUFutureWaitInfo df = {wgpuAdapterRequestDevice(a.adapter, &dd, dci), 0};diff --git a/native/host_js/ktx2_decode.cpp b/native/host_js/ktx2_decode.cppnew file mode 100644index 000000000..86f50ec1a--- /dev/null+++ b/native/host_js/ktx2_decode.cpp@@ -0,0 +1,89 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file ktx2_decode.cpp+ * @brief KTX2 → GPU transcode (see ktx2_decode.hpp), backed by basis_universal.+ */+#include "ktx2_decode.hpp"++#include "basisu_transcoder.h"++#include "esengine/renderer/GfxDevice.hpp"+#include "esengine/renderer/GfxEnums.hpp"+#include "esengine/renderer/Texture.hpp" // TextureFormat+#include "esengine/resource/ResourceManager.hpp"++#include <mutex>+#include <vector>++using namespace esengine;++namespace {++void ensureBasis() {+ static std::once_flag once;+ std::call_once(once, [] { basist::basisu_transcoder_init(); });+}++// The device format to prefer, its basis transcode target, and its sRGB variant.+// Ordered best-first for mobile GPUs (ASTC), then the ETC2 core baseline, then BC+// (desktop / some simulators); RGBA32 is the always-works fallback.+struct FormatChoice {+ GfxCompressedFormat linear;+ GfxCompressedFormat srgb;+ basist::transcoder_texture_format basisFmt;+};+const FormatChoice kChoices[] = {+ {GfxCompressedFormat::ASTC_4x4, GfxCompressedFormat::ASTC_4x4_SRGB,+ basist::transcoder_texture_format::cTFASTC_4x4_RGBA},+ {GfxCompressedFormat::ETC2_RGBA8, GfxCompressedFormat::ETC2_RGBA8_SRGB,+ basist::transcoder_texture_format::cTFETC2_RGBA},+ {GfxCompressedFormat::S3TC_DXT5, GfxCompressedFormat::S3TC_DXT5_SRGB,+ basist::transcoder_texture_format::cTFBC3_RGBA},+};++} // namespace++namespace eshost {++KTX2Result transcodeKTX2(const uint8_t* bytes, size_t n, bool srgb,+ resource::ResourceManager& rm, GfxDevice& device) {+ const KTX2Result fail{-1, 0, 0};+ ensureBasis();++ basist::ktx2_transcoder t;+ if (!t.init(bytes, static_cast<uint32_t>(n)) || !t.start_transcoding()) return fail;+ const uint32_t w = t.get_width();+ const uint32_t h = t.get_height();+ if (w == 0 || h == 0) return fail;++ basist::transcoder_texture_format basisFmt = basist::transcoder_texture_format::cTFRGBA32;+ GfxCompressedFormat gfxFmt = GfxCompressedFormat::ETC2_RGBA8;+ bool compressed = false;+ for (const FormatChoice& c : kChoices) {+ const GfxCompressedFormat want = srgb ? c.srgb : c.linear;+ if (device.supportsCompressedFormat(want)) {+ basisFmt = c.basisFmt;+ gfxFmt = want;+ compressed = true;+ break;+ }+ }++ // output_blocks_buf_size counts blocks (block formats) or pixels (RGBA32);+ // block_width/height is 1 for RGBA32, so this expression covers both.+ const uint32_t bw = basist::basis_get_block_width(basisFmt);+ const uint32_t bh = basist::basis_get_block_height(basisFmt);+ const uint32_t units = ((w + bw - 1) / bw) * ((h + bh - 1) / bh);+ std::vector<uint8_t> out(static_cast<size_t>(units) * basist::basis_get_bytes_per_block_or_pixel(basisFmt));+ if (!t.transcode_image_level(0, 0, 0, out.data(), units, basisFmt)) return fail;++ const ConstSpan<u8> span(out.data(), out.size());+ const resource::TextureHandle handle = compressed+ ? rm.createCompressedTexture(w, h, gfxFmt, span)+ : rm.createTexture(w, h, span, srgb ? TextureFormat::SRGB8A8 : TextureFormat::RGBA8, false);+ if (!handle.isValid()) return fail;+ return KTX2Result{static_cast<int>(handle.id()), static_cast<int>(w), static_cast<int>(h)};+}++} // namespace eshostdiff --git a/native/host_js/ktx2_decode.hpp b/native/host_js/ktx2_decode.hppnew file mode 100644index 000000000..f5b996ca9--- /dev/null+++ b/native/host_js/ktx2_decode.hpp@@ -0,0 +1,38 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file ktx2_decode.hpp+ * @brief Transcode a KTX2/Basis texture to a device-supported GPU format and+ * upload it, native-side.+ * @details The web KTX2 path is WebGL2 + the Basis wasm module, both absent on+ * native. Here the vendored basis_universal C++ transcoder (like stb /+ * miniaudio) turns a KTX2 container into ETC2/ASTC/BC blocks — or RGBA32+ * when the device supports none — and the engine ResourceManager uploads+ * them. This TU owns the basis include; host_core only calls transcodeKTX2.+ */+#pragma once++#include <cstddef>+#include <cstdint>++namespace esengine {+class GfxDevice;+namespace resource { class ResourceManager; }+} // namespace esengine++namespace eshost {++struct KTX2Result {+ int handle; ///< ResourceManager texture id, or < 0 on failure.+ int width;+ int height;+};++/** Transcode + upload a KTX2 clip (mip level 0). @p srgb selects the sRGB GPU+ * format variant (the block data is identical). Picks the best format the+ * @p device supports, falling back to RGBA32 so it always succeeds if the file+ * is valid. */+KTX2Result transcodeKTX2(const uint8_t* bytes, size_t n, bool srgb,+ esengine::resource::ResourceManager& rm, esengine::GfxDevice& device);++} // namespace eshostdiff --git a/native/ios/project.yml b/native/ios/project.ymlindex 9278fd0a4..9bdfecc15 100644--- a/native/ios/project.yml+++ b/native/ios/project.yml@@ -30,6 +30,9 @@ targets:- path: ../host_js/beep.wavbuildPhase: resourcestype: file+ - path: ../host_js/green.ktx2+ buildPhase: resources+ type: file# An exported project, staged by `cli native --target ios --content <dir>`.# A folder reference (not a group) so cooked subdirectories keep their# shape — the host reads Content/ first, the bundle root second.diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 9dabbb3b9..35d7f2be1 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1779,6 +1779,7 @@ createShader: (vertSrc: string, fragSrc: string) => numbercreateTexture: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean) => numbercreateTextureEx: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number) => numbercreateTextureFromBytes: ((width: number, height: number, pixels: Uint8Array, format: number, flipY: boolean, filterMode?: number, wrapMode?: number) => number) | undefined+createTextureFromKTX2: ((bytes: Uint8Array, srgb: boolean) => { handle: number; width: number; height: number; } | null) | undefinedgetBitmapFontRefCount: (handle: number) => numbergetResourceStats: () => { shaderCount: number; textureCount: number; vertexBufferCount: number; indexBufferCount: number; cacheHits: number; cacheMisses: number; textureBytes: number; textureBudget: number; textureEvictableCount: number; }getShaderRefCount: (handle: number) => numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex c3ea06c86..019dabd1b 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1787,6 +1787,7 @@ createShader: (vertSrc: string, fragSrc: string) => numbercreateTexture: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean) => numbercreateTextureEx: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number) => numbercreateTextureFromBytes: ((width: number, height: number, pixels: Uint8Array, format: number, flipY: boolean, filterMode?: number, wrapMode?: number) => number) | undefined+createTextureFromKTX2: ((bytes: Uint8Array, srgb: boolean) => { handle: number; width: number; height: number; } | null) | undefinedgetBitmapFontRefCount: (handle: number) => numbergetResourceStats: () => { shaderCount: number; textureCount: number; vertexBufferCount: number; indexBufferCount: number; cacheHits: number; cacheMisses: number; textureBytes: number; textureBudget: number; textureEvictableCount: number; }getShaderRefCount: (handle: number) => number@@ -5218,7 +5219,7 @@ static prototype: QueryInstance<any>## RESOURCE_BINDINGS — const```-{ readonly createTexture: "es_createTexture"; readonly releaseTexture: "es_releaseTexture"; readonly getTextureDimensions: "es_getTextureDimensions"; }+{ readonly createTexture: "es_createTexture"; readonly createTextureKTX2: "es_createTextureKTX2"; readonly releaseTexture: "es_releaseTexture"; readonly getTextureDimensions: "es_getTextureDimensions"; }```## RETIRED_COMPONENT_TYPES — constdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 600342ec4..43f45f43a 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1774,6 +1774,7 @@ createShader: (vertSrc: string, fragSrc: string) => numbercreateTexture: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean) => numbercreateTextureEx: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number) => numbercreateTextureFromBytes: ((width: number, height: number, pixels: Uint8Array, format: number, flipY: boolean, filterMode?: number, wrapMode?: number) => number) | undefined+createTextureFromKTX2: ((bytes: Uint8Array, srgb: boolean) => { handle: number; width: number; height: number; } | null) | undefinedgetBitmapFontRefCount: (handle: number) => numbergetResourceStats: () => { shaderCount: number; textureCount: number; vertexBufferCount: number; indexBufferCount: number; cacheHits: number; cacheMisses: number; textureBytes: number; textureBudget: number; textureEvictableCount: number; }getShaderRefCount: (handle: number) => numberdiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 8a5393481..5d192403f 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -141,6 +141,7 @@ createShader: (vertSrc: string, fragSrc: string) => numbercreateTexture: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean) => numbercreateTextureEx: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number) => numbercreateTextureFromBytes: ((width: number, height: number, pixels: Uint8Array, format: number, flipY: boolean, filterMode?: number, wrapMode?: number) => number) | undefined+createTextureFromKTX2: ((bytes: Uint8Array, srgb: boolean) => { handle: number; width: number; height: number; } | null) | undefinedgetBitmapFontRefCount: (handle: number) => numbergetResourceStats: () => { shaderCount: number; textureCount: number; vertexBufferCount: number; indexBufferCount: number; cacheHits: number; cacheMisses: number; textureBytes: number; textureBudget: number; textureEvictableCount: number; }getShaderRefCount: (handle: number) => numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 447d36809..cf5b8cfac 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1774,6 +1774,7 @@ createShader: (vertSrc: string, fragSrc: string) => numbercreateTexture: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean) => numbercreateTextureEx: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number) => numbercreateTextureFromBytes: ((width: number, height: number, pixels: Uint8Array, format: number, flipY: boolean, filterMode?: number, wrapMode?: number) => number) | undefined+createTextureFromKTX2: ((bytes: Uint8Array, srgb: boolean) => { handle: number; width: number; height: number; } | null) | undefinedgetBitmapFontRefCount: (handle: number) => numbergetResourceStats: () => { shaderCount: number; textureCount: number; vertexBufferCount: number; indexBufferCount: number; cacheHits: number; cacheMisses: number; textureBytes: number; textureBudget: number; textureEvictableCount: number; }getShaderRefCount: (handle: number) => numberdiff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.tsindex 0bfc16609..3b2c6419c 100644--- a/sdk/src/asset/loaders/TextureLoader.ts+++ b/sdk/src/asset/loaders/TextureLoader.ts@@ -203,6 +203,15 @@ export class TextureLoader implements AssetLoader<TextureResult> {const buf = await ctx.backend.fetchBinary(ctx.catalog.getBuildPath(path));const bytes = new Uint8Array(buf);if (!isKtx2(bytes)) throw new Error(`TextureLoader: ${path} is not a KTX2 file`);+ // Native (embedded Dawn): the ResourceManager transcodes the KTX2 with the+ // host's basis library and uploads the compressed blocks — no WebGL2, no+ // wasm transcoder. sRGB follows the color pipeline, like the web path below.+ const rm = requireResourceManager();+ if (rm.createTextureFromKTX2) {+ const r = rm.createTextureFromKTX2(bytes, linearColorSpace());+ if (!r) throw new Error(`TextureLoader: KTX2 transcode failed for ${path}`);+ return { handle: r.handle, width: r.width, height: r.height };+ }const gl = this.getWebGL2Context();if (!gl) throw new Error('TextureLoader: KTX2 textures require a WebGL2 context');const transcoder = await this.ensureTranscoder_();diff --git a/sdk/src/ecs/nativeBindings.ts b/sdk/src/ecs/nativeBindings.tsindex e9f0a475d..ed57c91c0 100644--- a/sdk/src/ecs/nativeBindings.ts+++ b/sdk/src/ecs/nativeBindings.ts@@ -29,6 +29,7 @@ export const REGISTRY_BINDINGS = {/** The native ResourceManager surface the asset pipeline uploads through. */export const RESOURCE_BINDINGS = {createTexture: 'es_createTexture',+ createTextureKTX2: 'es_createTextureKTX2',releaseTexture: 'es_releaseTexture',getTextureDimensions: 'es_getTextureDimensions',} as const;diff --git a/sdk/src/ecs/nativeResourceManager.ts b/sdk/src/ecs/nativeResourceManager.tsindex 7b1f13a56..6ad0863b5 100644--- a/sdk/src/ecs/nativeResourceManager.ts+++ b/sdk/src/ecs/nativeResourceManager.ts@@ -61,6 +61,14 @@ export function createNativeResourceManager(hostCall(scope, RESOURCE_BINDINGS.createTexture,[width, height, pixels, format, flipY, filterMode, wrapMode]) as number,+ // The host transcodes KTX2 (basis) and uploads the compressed blocks; it+ // returns { id, width, height } — expose it as { handle, ... }.+ createTextureFromKTX2: (bytes, srgb) => {+ const r = hostCall(scope, RESOURCE_BINDINGS.createTextureKTX2, [bytes, srgb]) as+ { id: number; width: number; height: number } | null;+ return r ? { handle: r.id, width: r.width, height: r.height } : null;+ },+updateTextureSubregionFromBytes: (handle, x, y, width, height, pixels): void => {hostCallOpt(scope, 'es_updateTextureSubregion', [handle, x, y, width, height, pixels]);},diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 690380052..b356c1802 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -49,6 +49,10 @@ export interface CppResourceManager {* the upload helpers fall through to the heap path and web stays byte-identical.* `filterMode`/`wrapMode` mirror {@link createTextureEx}'s codes (optional). */createTextureFromBytes?(width: number, height: number, pixels: Uint8Array, format: number, flipY: boolean, filterMode?: number, wrapMode?: number): number;+ /** Transcode + upload a KTX2/Basis container to a device-supported compressed+ * format (or RGBA32). Native only (the basis transcoder lives in the host);+ * the web KTX2 path is WebGL2 + the wasm transcoder instead. */+ createTextureFromKTX2?(bytes: Uint8Array, srgb: boolean): { handle: number; width: number; height: number } | null;/** Module-free {@link updateTextureSubregion} — native byte upload for the* glyph atlas, symmetric with {@link createTextureFromBytes}. */updateTextureSubregionFromBytes?(handle: number, x: number, y: number, width: number, height: number, pixels: Uint8Array): void;diff --git a/sdk/tests/binding-surface.test.ts b/sdk/tests/binding-surface.test.tsindex 47d4e02a6..42dadcec3 100644--- a/sdk/tests/binding-surface.test.ts+++ b/sdk/tests/binding-surface.test.ts@@ -365,6 +365,7 @@ describe('WASM binding surface: embind class methods', () => {// the web mirror the way embind's implicit `delete` is below.ts.delete('createTextureFromBytes');ts.delete('updateTextureSubregionFromBytes');+ ts.delete('createTextureFromKTX2'); // KTX2 transcode lives in the native host, not embindexpect(sorted(ts)).toEqual(sorted(cpp.keys()));});diff --git a/src/esengine/renderer/Texture.cpp b/src/esengine/renderer/Texture.cppindex 8a51e950a..50ce957a4 100644--- a/src/esengine/renderer/Texture.cpp+++ b/src/esengine/renderer/Texture.cpp@@ -123,6 +123,31 @@ Unique<Texture> Texture::createRaw(GfxDevice& device, u32 width, u32 height, conreturn texture;}+Unique<Texture> Texture::createCompressed(GfxDevice& device, u32 width, u32 height,+ GfxCompressedFormat format, std::span<const u8> data) {+ auto texture = makeUnique<Texture>();+ texture->device_ = &device;+ texture->width_ = width;+ texture->height_ = height;+ texture->format_ = TextureFormat::RGBA8; // sampled as colour; the GPU format is the compressed one++ TextureDesc desc;+ desc.width = width;+ desc.height = height;+ desc.minFilter = TextureFilter::Linear;+ desc.magFilter = TextureFilter::Linear;+ desc.wrapS = TextureWrap::ClampToEdge;+ desc.wrapT = TextureWrap::ClampToEdge;+ desc.mipmaps = false;++ texture->handle_ = device.createCompressedTexture(desc, format, data.data(), static_cast<u32>(data.size()));+ if (texture->handle_ == TextureHandle::Invalid) {+ ES_LOG_ERROR("Texture::createCompressed: failed for {}x{}", width, height);+ return nullptr;+ }+ return texture;+}+Unique<Texture> Texture::createFromExternalId(GfxDevice& device, u32 glTextureId, u32 width, u32 height,TextureFormat format) {TextureDesc desc;diff --git a/src/esengine/renderer/Texture.hpp b/src/esengine/renderer/Texture.hppindex 8debfd6f3..40840acdd 100644--- a/src/esengine/renderer/Texture.hpp+++ b/src/esengine/renderer/Texture.hpp@@ -240,6 +240,15 @@ public:TextureFormat format = TextureFormat::RGBA8,bool flipY = false);+ /**+ * @brief Creates a block-compressed texture (KTX2 → ETC2/ASTC/BC), uploading+ * the pre-compressed blocks in one shot. No setDataRaw afterward —+ * compressed data is immutable here.+ * @param data Compressed block data for mip level 0.+ */+ static Unique<Texture> createCompressed(GfxDevice& device, u32 width, u32 height,+ GfxCompressedFormat format, std::span<const u8> data);+/*** @brief Wraps an existing GL texture ID* @param glTextureId The OpenGL texture ID created externallydiff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cppindex 262c13d6e..78ee8a08a 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp@@ -516,10 +516,51 @@ TextureHandle WebGPUDevice::createTexture(const TextureDesc& desc, const void* preturn TextureHandle{id};}-TextureHandle WebGPUDevice::createCompressedTexture(const TextureDesc&, GfxCompressedFormat,- const void*, u32) {- stubOnce("createCompressedTexture");- return TextureHandle::Invalid;+TextureHandle WebGPUDevice::createCompressedTexture(const TextureDesc& desc, GfxCompressedFormat format,+ const void* data, u32 byteLength) {+ if (!device_ || !queue_) {+ ES_LOG_ERROR("WebGPUDevice::createCompressedTexture: no device");+ return TextureHandle::Invalid;+ }+ const WGPUTextureFormat wgpuFmt = toWGPUCompressedFormat(format);+ if (wgpuFmt == WGPUTextureFormat_Undefined) {+ ES_LOG_ERROR("WebGPUDevice::createCompressedTexture: unmapped format");+ return TextureHandle::Invalid;+ }++ WGPUTextureDescriptor td{};+ td.dimension = WGPUTextureDimension_2D;+ td.format = wgpuFmt;+ td.size = WGPUExtent3D{desc.width, desc.height, 1};+ td.mipLevelCount = 1;+ td.sampleCount = 1;+ td.usage = WGPUTextureUsage_TextureBinding | WGPUTextureUsage_CopyDst; // compressed = sampled, never a target++ WGPUTexture texture = wgpuDeviceCreateTexture(device_, &td);+ if (!texture) {+ ES_LOG_ERROR("WebGPUDevice::createCompressedTexture: creation failed ({}x{})", desc.width, desc.height);+ return TextureHandle::Invalid;+ }++ // writeTexture counts BLOCKS, not pixels: a partial edge block still counts.+ const CompressedBlockInfo bi = compressedBlockInfo(format);+ const u32 blocksX = (desc.width + bi.blockWidth - 1) / bi.blockWidth;+ const u32 blocksY = (desc.height + bi.blockHeight - 1) / bi.blockHeight;+ WGPUTexelCopyTextureInfo dst{};+ dst.texture = texture;+ dst.origin = WGPUOrigin3D{0, 0, 0};+ WGPUTexelCopyBufferLayout layout{};+ layout.bytesPerRow = blocksX * bi.bytesPerBlock;+ layout.rowsPerImage = blocksY;+ WGPUExtent3D extent{desc.width, desc.height, 1};+ wgpuQueueWriteTexture(queue_, &dst, data, byteLength, &layout, &extent);++ const u32 id = next_id_++;+ textures_[id] = TextureRec{texture, wgpuTextureCreateView(texture, nullptr),+ desc.width, desc.height, wgpuFmt,+ packSamplerKey(desc.minFilter, desc.magFilter,+ desc.wrapS, desc.wrapT)};+ return TextureHandle{id};}TextureHandle WebGPUDevice::importExternalTexture(u32, const TextureDesc&) {@@ -597,9 +638,13 @@ void WebGPUDevice::bindTexture(u32 slot, TextureHandle texture) {}bool WebGPUDevice::supportsCompressedFormat(GfxCompressedFormat format) {- // Real capability negotiation (adapter features) arrives with the adapter- // plumbing; ETC2 is core on WebGPU-with-compat targets we care about.- return toWGPUCompressedFormat(format) != WGPUTextureFormat_Undefined;+ if (toWGPUCompressedFormat(format) == WGPUTextureFormat_Undefined) return false;+ // Native: the host passes the adapter, so query it for real — and it requests+ // exactly the supported compression families at device creation, so "adapter+ // has" == "device can create". Without an adapter handle (the web WebGPU+ // build) assume the ETC2 core baseline.+ if (!adapter_) return toWGPUCompressedFormat(format) != WGPUTextureFormat_Undefined;+ return wgpuAdapterHasFeature(adapter_, compressionFeatureFor(format)) != 0;}// =============================================================================diff --git a/src/esengine/renderer/webgpu/WebGPUMappings.hpp b/src/esengine/renderer/webgpu/WebGPUMappings.hppindex 5fd08771a..498015768 100644--- a/src/esengine/renderer/webgpu/WebGPUMappings.hpp+++ b/src/esengine/renderer/webgpu/WebGPUMappings.hpp@@ -181,6 +181,44 @@ inline WGPUTextureFormat toWGPUCompressedFormat(GfxCompressedFormat fmt) {}}+/** Block footprint of a compressed format: writeTexture's bytesPerRow/rowsPerImage+ * count blocks, not pixels. BC/ETC2 are 4x4; ASTC's block matches its name. */+struct CompressedBlockInfo {+ u32 blockWidth;+ u32 blockHeight;+ u32 bytesPerBlock;+};+inline CompressedBlockInfo compressedBlockInfo(GfxCompressedFormat fmt) {+ switch (fmt) {+ case GfxCompressedFormat::S3TC_DXT1: return {4, 4, 8}; // BC1+ case GfxCompressedFormat::ETC2_RGB8: return {4, 4, 8};+ case GfxCompressedFormat::ASTC_8x8: return {8, 8, 16};+ case GfxCompressedFormat::S3TC_DXT5:+ case GfxCompressedFormat::S3TC_DXT5_SRGB: return {4, 4, 16}; // BC3+ case GfxCompressedFormat::ETC2_RGBA8:+ case GfxCompressedFormat::ETC2_RGBA8_SRGB: return {4, 4, 16};+ case GfxCompressedFormat::ASTC_4x4:+ case GfxCompressedFormat::ASTC_4x4_SRGB:+ default: return {4, 4, 16};+ }+}++/** The device feature that gates a compressed-format family (BC / ETC2 / ASTC). */+inline WGPUFeatureName compressionFeatureFor(GfxCompressedFormat fmt) {+ switch (fmt) {+ case GfxCompressedFormat::S3TC_DXT1:+ case GfxCompressedFormat::S3TC_DXT5:+ case GfxCompressedFormat::S3TC_DXT5_SRGB: return WGPUFeatureName_TextureCompressionBC;+ case GfxCompressedFormat::ASTC_4x4:+ case GfxCompressedFormat::ASTC_8x8:+ case GfxCompressedFormat::ASTC_4x4_SRGB: return WGPUFeatureName_TextureCompressionASTC;+ case GfxCompressedFormat::ETC2_RGB8:+ case GfxCompressedFormat::ETC2_RGBA8:+ case GfxCompressedFormat::ETC2_RGBA8_SRGB:+ default: return WGPUFeatureName_TextureCompressionETC2;+ }+}+inline WGPUFilterMode toWGPUFilter(TextureFilter filter) {return filter == TextureFilter::Nearest ? WGPUFilterMode_Nearest : WGPUFilterMode_Linear;}diff --git a/src/esengine/resource/ResourceManager.cpp b/src/esengine/resource/ResourceManager.cppindex c64942531..41fba21de 100644--- a/src/esengine/resource/ResourceManager.cpp+++ b/src/esengine/resource/ResourceManager.cpp@@ -192,6 +192,19 @@ TextureHandle ResourceManager::createTexture(u32 width, u32 height, ConstSpan<u8return textures_.add(std::move(texture), "", bytes);}+TextureHandle ResourceManager::createCompressedTexture(u32 width, u32 height,+ GfxCompressedFormat format, ConstSpan<u8> data) {+ if (!device_) return {};+ auto texture = Texture::createCompressed(*device_, width, height, format,+ std::span<const u8>(data.data(), data.size()));+ if (!texture) {+ ES_LOG_ERROR("Failed to create compressed texture");+ return TextureHandle();+ }+ // Residency cost is the on-GPU compressed size, not the RGBA expansion.+ return textures_.add(std::move(texture), "", data.size());+}+TextureHandle ResourceManager::loadTexture(const std::string& path) {auto cached = textures_.findByPath(path);if (cached.isValid()) {diff --git a/src/esengine/resource/ResourceManager.hpp b/src/esengine/resource/ResourceManager.hppindex c8eff913f..5251f99c7 100644--- a/src/esengine/resource/ResourceManager.hpp+++ b/src/esengine/resource/ResourceManager.hpp@@ -220,6 +220,16 @@ public:TextureHandle createTexture(u32 width, u32 height, ConstSpan<u8> pixels,TextureFormat format, bool flipY = false);+ /**+ * @brief Creates a block-compressed texture (KTX2 → ETC2/ASTC/BC), uploading+ * the pre-compressed blocks for mip level 0. Tracked like any texture;+ * its residency cost is the real (compressed) byte size.+ * @param data Compressed block data.+ * @return Handle to the texture, or invalid handle on failure.+ */+ TextureHandle createCompressedTexture(u32 width, u32 height, GfxCompressedFormat format,+ ConstSpan<u8> data);+/*** @brief Loads a texture from file (with caching)* @param path Path to the image file