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(native): KTX2 compressed textures (basis transcode + real GPU upload)

esengine5ad5b63726cc
diff --git a/native/CMakeLists.txt b/native/CMakeLists.txt
index 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.md
index 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 JS
thread 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.js
index 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.ktx2
new file mode 100644
index 000000000..a4727d8ea
Binary files /dev/null and b/native/host_js/green.ktx2 differ
diff --git a/native/host_js/host_core.cpp b/native/host_js/host_core.cpp
index 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* a
return 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.cpp
new file mode 100644
index 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 eshost
diff --git a/native/host_js/ktx2_decode.hpp b/native/host_js/ktx2_decode.hpp
new file mode 100644
index 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 eshost
diff --git a/native/ios/project.yml b/native/ios/project.yml
index 9278fd0a4..9bdfecc15 100644
--- a/native/ios/project.yml
+++ b/native/ios/project.yml
@@ -30,6 +30,9 @@ targets:
- path: ../host_js/beep.wav
buildPhase: resources
type: 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.md
index 9dabbb3b9..35d7f2be1 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1779,6 +1779,7 @@ createShader: (vertSrc: string, fragSrc: string) => number
createTexture: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean) => number
createTextureEx: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number) => number
createTextureFromBytes: ((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) | undefined
getBitmapFontRefCount: (handle: number) => number
getResourceStats: () => { shaderCount: number; textureCount: number; vertexBufferCount: number; indexBufferCount: number; cacheHits: number; cacheMisses: number; textureBytes: number; textureBudget: number; textureEvictableCount: number; }
getShaderRefCount: (handle: number) => number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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) => number
createTexture: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean) => number
createTextureEx: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number) => number
createTextureFromBytes: ((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) | undefined
getBitmapFontRefCount: (handle: number) => number
getResourceStats: () => { 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 — const
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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) => number
createTexture: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean) => number
createTextureEx: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number) => number
createTextureFromBytes: ((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) | undefined
getBitmapFontRefCount: (handle: number) => number
getResourceStats: () => { shaderCount: number; textureCount: number; vertexBufferCount: number; indexBufferCount: number; cacheHits: number; cacheMisses: number; textureBytes: number; textureBudget: number; textureEvictableCount: number; }
getShaderRefCount: (handle: number) => number
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 8a5393481..5d192403f 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -141,6 +141,7 @@ createShader: (vertSrc: string, fragSrc: string) => number
createTexture: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean) => number
createTextureEx: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number) => number
createTextureFromBytes: ((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) | undefined
getBitmapFontRefCount: (handle: number) => number
getResourceStats: () => { shaderCount: number; textureCount: number; vertexBufferCount: number; indexBufferCount: number; cacheHits: number; cacheMisses: number; textureBytes: number; textureBudget: number; textureEvictableCount: number; }
getShaderRefCount: (handle: number) => number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 447d36809..cf5b8cfac 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1774,6 +1774,7 @@ createShader: (vertSrc: string, fragSrc: string) => number
createTexture: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean) => number
createTextureEx: (width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number) => number
createTextureFromBytes: ((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) | undefined
getBitmapFontRefCount: (handle: number) => number
getResourceStats: () => { shaderCount: number; textureCount: number; vertexBufferCount: number; indexBufferCount: number; cacheHits: number; cacheMisses: number; textureBytes: number; textureBudget: number; textureEvictableCount: number; }
getShaderRefCount: (handle: number) => number
diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 embind
expect(sorted(ts)).toEqual(sorted(cpp.keys()));
});
diff --git a/src/esengine/renderer/Texture.cpp b/src/esengine/renderer/Texture.cpp
index 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, con
return 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.hpp
index 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 externally
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
index 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* p
return 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.hpp
index 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.cpp
index 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<u8
return 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.hpp
index 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