Non-Adreno support (Xclipse/Mali): asset-transcode fallback for BCn textures

[fadi-labib]

Summary

The Android renderer currently targets Adreno GPUs only. The working path bundles Mesa Turnip (via libadrenotools) to get Vulkan 1.3 + BCn texture support. Turnip is a Qualcomm/Adreno-only driver (Mesa freedreno), so it does nothing on non-Adreno devices — notably Samsung Exynos (Xclipse) and ARM Mali. On those GPUs the stock driver does not expose BC/DXT texture compression, and the game's textures are BCn-compressed DDS, so they cannot be sampled → the game can't render correctly.

This issue tracks adding a non-Adreno fallback so Exynos/Mali devices can run the port.

Why the current path doesn't cover non-Adreno

• Turnip is Adreno-only. It cannot load on Xclipse (AMD RDNA-based) or Mali.
• Stock non-Adreno drivers lack textureCompressionBC. The game ships thousands of BC1/BC2/BC3 (DXT1/3/5) DDS textures (~2.7 GB of assets); without BCn support the GPU can't sample them.
• DXVK has no software BCn decode (established in the Phase 0 research), so the translation layer can't paper over it.

Evidence (on-device profiling)

• Galaxy S22 (Exynos, SM-S908B) = Samsung Xclipse 920 (AMD RDNA2): reports Vulkan 1.3 but textureCompressionBC = FALSE. Not Adreno → no Turnip. Renderer path unusable as-is.
• For contrast, the working device is a Tab S7+ (Snapdragon 865, Adreno 650) where the stock driver also lacks BCn, but Turnip provides it — an option not available on Xclipse/Mali.

Approach (from Phase 0 research)

The renderer chain (D3D8→DXVK→Vulkan) is fixed by determinism, so the fix is asset-side: transcode the BCn textures into a format the target GPU supports, at extract/push time (offline, on the PC), not at runtime. Two options:

1. DXT → uncompressed RGBA8 — universally supported, simplest, but 4–8× larger on disk/VRAM (BC1 is 4 bpp, BC2/3 are 8 bpp vs 32 bpp RGBA8). Memory pressure is already a concern on mobile.
2. DXT → ASTC or ETC2 — Xclipse and Mali support these natively; keeps textures compressed (reasonable size), but requires transcoding to a mobile format and the engine/DXVK accepting non-DXT textures for these assets.

Both require:

• A transcode step in the asset pipeline (extend scripts/build/android/push-assets-android.sh or an offline pre-pass) that rewrites the .big/DDS textures.
• Possibly engine texture-loader changes to accept the transcoded format on non-Adreno devices, and a device-capability check to pick Turnip (Adreno) vs. transcoded assets (non-Adreno) at boot.

Scope / effort

Large. New asset-transcode pipeline + device-capability branching + on-device validation on an Xclipse (and ideally a Mali) device. Does not touch the working Adreno/Turnip path.

References

• docs/WORKDIR/planning/ANDROID_RENDERER_RESEARCH_2026-07.md — §3 BCn support matrix, §5 route decision (require-turnip for Adreno; asset-transcode noted as the non-Adreno fallback).
• Related: Android/Turnip: two-device boot is load-bearing — single D3D device renders 3D scene black #8 (Adreno two-device boot) is a separate Adreno-only rendering issue.
• Branch: feature/android-phase3-renderer.

Impact

Unlocks the large non-Adreno Android market (Samsung Exynos/Xclipse, MediaTek/Mali). Not required for Adreno devices, which work today. Best tackled as its own project once the Adreno path is polished.

[fadi-labib]

Progress update (2026-07-08): driver-gate fixed — Xclipse now boots to the main menu

On-device work on the S22 Ultra (SM-S908B, Exynos 2200 / Xclipse 920) turned up a blocker before the BCn texture question, and fixed it.

What actually happened (not "Turnip does nothing")

The loader force-loaded Turnip unconditionally. On Xclipse, Turnip's .so loads and even resolves vkGetInstanceProcAddr — but vkEnumeratePhysicalDevices returns 0 devices (no Adreno GPU / no kgsl kernel node). DXVK logs No adapters found, then D3D8Interface::GetAdapterModeCount indexes an empty vector → hard SIGSEGV in DX8Wrapper::Find_Color_Mode during W3DDisplay::init. The loader's existing fallback only triggers when Turnip fails to load, never on 0 adapters, so it never reached the stock driver.

info:  Vulkan: opening Turnip via adrenotools (driver=vulkan.ad07xx.so)
info:  Vulkan: Found vkGetInstanceProcAddr in adrenotools/Turnip libvulkan
warn:  DXVK: No adapters found. ... A Vulkan 1.3 capable driver is required.
F/libc: Fatal signal 11 (SIGSEGV) ... GetAdapterModeCount+4

Fix (committed)

Gate Turnip on the Adreno kernel node — it talks to /dev/kgsl-3d0, which exists only on Qualcomm. When absent, skip Turnip so the loader falls through to the stock libvulkan.so:

// vulkan_loader.cpp, dxvkAndroidOpenTurnip()
if (access("/dev/kgsl-3d0", F_OK) != 0) {
  dxvk::Logger::warn("Vulkan: no Adreno kgsl node (/dev/kgsl-3d0); skipping Turnip, using stock libvulkan.so");
  return nullptr;
}

Fixes every non-Adreno device, not just Xclipse. Committed in the DXVK fork + pointer bump in the parent repo.

Result

The Xclipse stock Samsung driver (com.samsung.gamedriver.ex2200) reports Vulkan 1.3, DXVK enumerates it cleanly, and the game boots to the Zero Hour main menu at 30 FPS — menu UI, fonts, buttons all render correctly. From instant-crash to running.

info:  Device : Samsung Xclipse 920
info:  Vulkan 1.1 / 1.2 / 1.3
INFO: SDL3GameEngine::createGameLogic() -> W3DGameLogic

What remains for THIS issue (BCn)

The driver crash was masking the texture question — now we can actually see it. On the menu, the animated shell-map background renders solid black (menu chrome is fine), which is consistent with the BCn/DXT sampling gap this issue tracks (textureCompressionBC likely FALSE on Xclipse — asserted here, not yet re-queried on-device this session). In-game skirmish not yet verified. So the asset-transcode fallback described above is still the open work; this update just removes the driver blocker in front of it and gives a live device to validate against.

Next concrete step: enter a skirmish and confirm whether terrain/units render (BCn wall) vs. render correctly, and instrument VkPhysicalDeviceFeatures.textureCompressionBC on the Xclipse adapter to confirm the transcode target (RGBA8 vs ASTC/ETC2).

[fadi-labib]

Option 1 implemented (offline BC→RGBA8 loose-file overlay)

Shipped in main (d7a7a8ba7). Chose Option 1 over Option 2 because ASTC/ETC2 have no D3D8/D3D9 format token and can't pass through the D3D8→DXVK→Vulkan translation layer without invasive hacking; RGBA8 rides native A8R8G8B8.

How it works

• scripts/build/android/transcode-textures-rgba8.py — scans all .big archives, decodes each DXT1/3/5 DDS (Pillow), regenerates the full mip chain (2×2 box filter), and writes an uncompressed A8R8G8B8 DDS (BGRA byte order) to build/android-textures-rgba8/Art/Textures/…. Cached via a source-stamp; --selftest validates the writer/swizzle/mips.
• No .big repacking, no engine/DXVK changes. Loose files override archives — FileSystem::openFile (FileSystem.cpp:191) tries TheLocalFileSystem before TheArchiveFileSystem, and the game chdirs to /sdcard/GeneralsZH.
• push-assets-android.sh pushes the overlay gated on GPU: auto-detects non-Adreno (no /dev/kgsl-3d0) and only ships it there; GX_UNCOMPRESSED_TEXTURES=1|0 forces/skips. Adreno stays lean on native BCn via Turnip.

Verified on S22 Ultra (Xclipse 920)

• 3496 textures transcoded, 0 failures. Overlay ≈ 988 MB (all textures live in TexturesZH.big; W3DZH.big had none).
• Loose overrides pushed; game loads through full asset init (shaders/shell-map) with no crash and zero DDS load errors.

Residual check

Final in-game visual confirmation (esp. DXT1 1-bit-alpha cutouts like foliage) is pending an eyeball in a live skirmish. Pillow's BC1 decoder is expected to preserve punch-through alpha, but that's the one thing not yet visually confirmed.

Honest cost/benefit (unchanged)

Win = eliminates DXVK runtime BC emulation (load-time + potential per-frame GPU savings). Cost = ~1 GB extra on non-Adreno devices. No memory change (RGBA8 is the footprint DXVK already used). Auto-gated so Adreno is unaffected.

[fadi-labib]

Delivery corrected: single repacked .big, not loose files (load 5 min → 7 s)

The loose-file overlay from the first cut caused a severe load-time regression on-device (~5 minutes): /sdcard is FUSE emulated storage where opening the 3496 individual DDS files is far slower than one sequential archive read. Measured raw on the S22 Ultra:

read 3496 loose DDS:   16.6 s
read one TexturesZH.big: 0.6 s   (~30x)

Fix (01faa73f6): the transcoder now repacks TexturesZH.big — DXT DDS → uncompressed A8R8G8B8, TGA and any non-DXT copied verbatim, entry names/order preserved — and push-assets pushes that one archive to replace the stock DXT one on non-Adreno devices (and deletes the retired loose Art/ overlay so it can't shadow the archive).

Verified on S22 Ultra (Xclipse)

• Repacked TexturesZH.big: 3496 transcoded + 50 TGA verbatim, 0 failures, 1014 MB.
• Push: single file, 18.7 s @ 54 MB/s (vs the loose crawl).
• Cold launch to menu: 7 s (was ~5 min), idle after init, no crash.

Net: native RGBA8 sampling with load time better than the original (one sequential read, no BC decode). The Get_Render_Device_Count / anisotropy / kgsl-gate fixes remain unchanged. Still pending: an in-game skirmish eyeball (DXT1 cutout alpha) + FPS comparison to decide if the overlay earns its ~800 MB over plain runtime decode.