[Native] Load single-file .dds/.ktx/.ktx2 cubemaps on the native engine by bkaradzic-microsoft · Pull Request #18560 · BabylonJS/Babylon.js

bkaradzic-microsoft · 2026-06-10T23:00:35Z

[Native] Load single-file `.dds`/`.ktx`/`.ktx2` cubemaps on the native engine

Problem

The native engine overrides createCubeTexture (nativeEngine.cubeTexture.pure.ts) and only
handles two cases: a single .env file, and an array of six face files. A single self-contained
cubemap container — .dds / .ktx / .ktx2, the format produced by
CubeTexture.CreateFromPrefilteredData(...) — falls through to:

throw new Error("Cannot load cubemap because 6 files were not defined");

So prefiltered-environment scenes (PBR IBL) that reference a single .dds cannot load it on
native at all.

This path was never wired because the generic WebGL loader route isn't usable on native: the
engine's _uploadDataToTextureDirectly / _uploadCompressedDataToTextureDirectly (and cube
_readTexturePixels) are unimplemented there — native uploads via its own command path, and the
.env branch worked only because .env ships pre-split faces plus baked spherical harmonics.

Fix

Route a single-URL container cubemap to the native engine, which decodes it (bimg already supports
DDS/KTX/KTX2 cube containers) and, when polynomials are requested, returns the spherical-harmonics
coefficients it computed from the top mip. The diffuse-IBL spherical polynomial is then set on the
texture from those coefficients.

nativeEngine.cubeTexture.pure.ts: in the non-.env branch, keep the existing six-file path,
and add a branch for a single-URL container — fetch the bytes (or use the provided buffer),
call engine.loadCubeTexture(resource, [buffer], ...), and on success set
_sphericalPolynomial from the returned coefficients (when createPolynomials was requested).
nativeInterfaces.ts: loadCubeTexture's onSuccess now optionally carries the spherical
polynomial coefficients ((sphericalPolynomial?: Float32Array) => void); the existing six-file
caller ignores them.

No change to the .env or six-file paths.

Pairs with a Babylon Native NativeEngine change that implements the single-buffer cube decode
(via bimg) and the spherical-harmonics computation from the top mip. This JS change requires that
native support to be present.

Testing

Validated on Babylon Native (Win32 / D3D11) with the Playground validation suite: six previously
unloadable prefiltered-environment .dds PBR scenes now load and render correctly, matching their
reference images. The computed spherical-harmonics integration is correct (total solid angle = 4π).

Related PRs & landing order

Babylon.js (engine / TS): [Native] Load single-file .dds/.ktx/.ktx2 cubemaps on the native engine #18560
BabylonNative (C++ engine + test re-enable): NativeEngine: load single-file .dds/.ktx/.ktx2 cubemaps + spherical harmonics (re-enables 7 tests) BabylonNative#1748

Co-dependent; land in this order:

Babylon.js [Native] Load single-file .dds/.ktx/.ktx2 cubemaps on the native engine #18560 first — adds the single-URL container cube dispatch + spherical-harmonics wiring; no WebGL behavior change.
A babylonjs npm release ships that TS change.
BabylonNative Canvas2D: fix Sprite2D boundingBox not updated #1748 last — bumps the bundled babylonjs and re-enables the 6 prefiltered-.dds PBR validation tests, which only pass once the paired JS is present in the bundled engine. The folded-in blur-cube-with-the-effect-renderer test additionally requires [Native] Honor depthCullingState.depthTest on the native engine #18558 to be in the same babylonjs release.

bjsplat · 2026-06-10T23:02:09Z

Please make sure to label your PR with "bug", "new feature" or "breaking change" label(s).
To prevent this PR from going to the changelog marked it with the "skip changelog" label.

bjsplat · 2026-06-10T23:45:46Z

Please make sure to label your PR with "bug", "new feature" or "breaking change" label(s).
To prevent this PR from going to the changelog marked it with the "skip changelog" label.

bjsplat · 2026-06-11T00:05:02Z

Snapshot stored with reference name:
refs/pull/18560/merge

Test environment:
https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/refs/pull/18560/merge/index.html

To test a playground add it to the URL, for example:

https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/refs/pull/18560/merge/index.html#WGZLGJ#4600

Links to test your changes to core in the published versions of the Babylon tools (does not contain changes you made to the tools themselves):

https://playground.babylonjs.com/?snapshot=refs/pull/18560/merge
https://sandbox.babylonjs.com/?snapshot=refs/pull/18560/merge
https://gui.babylonjs.com/?snapshot=refs/pull/18560/merge
https://nme.babylonjs.com/?snapshot=refs/pull/18560/merge

To test the snapshot in the playground with a playground ID add it after the snapshot query string:

https://playground.babylonjs.com/?snapshot=refs/pull/18560/merge#BCU1XR#0

If you made changes to the sandbox or playground in this PR, additional comments will be generated soon containing links to the dev versions of those tools.

bjsplat · 2026-06-11T00:08:40Z

Interaction tests

https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/refs/pull/18560/merge/testResults/interactionplaywright/index.html

bjsplat · 2026-06-11T00:21:34Z

Visualization tests for WebGPU

https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/refs/pull/18560/merge/testResults/webgpuplaywright/index.html

bjsplat · 2026-06-11T00:23:25Z

🟢 Memory Leak Test Results

13 passed, 0 leaked out of 13 scenarios

🟢 All memory leak tests passed — no leaks detected.

Passed Scenarios (13)

Scenario	Package
Core Feature Stack	@babylonjs/core
Core Rendering Materials Shadows Stack	@babylonjs/core
Core Textures Render Targets PostProcess Stack	@babylonjs/core
GUI Fullscreen UI Controls	@babylonjs/gui
GUI Mesh ADT Controls	@babylonjs/gui
Loaders Boombox Import	@babylonjs/loaders
Loaders OBJ Direct Load	@babylonjs/loaders
Loaders STL Direct Load	@babylonjs/loaders
Materials Library Stack	@babylonjs/materials
Serializers glTF Export	@babylonjs/serializers
Serializers GLB Export	@babylonjs/serializers
PostProcesses Digital Rain Stack	@babylonjs/post-processes
Procedural Textures Stack	@babylonjs/procedural-textures

bjsplat · 2026-06-11T00:24:32Z

WebGL2 visualization test reporter:

https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/refs/pull/18560/merge/testResults/webgl2playwright/index.html

bjsplat · 2026-06-11T00:32:15Z

⚡ Performance Test Results

🟢 All performance tests passed — no regressions detected.

…armonics loadCubeTexture now accepts a single self-contained cubemap container (all six faces + mips), decoded via bimg::imageParse, and uploads sides 0-5 x mips. ComputeCubeSphericalPolynomial derives the diffuse-IBL spherical harmonics from the top-mip faces (port of CubeMapToSphericalPolynomialTools) and returns the polynomial coefficients to JS. This is done natively because the WebGL upload and cube-readback paths are unimplemented on native and .dds stores no SH. Re-enables 6 prefiltered-environment PBR validation tests. Pairs with BabylonJS/Babylon.js#18560 (native createCubeTexture dispatch for single-URL containers). Depends on a babylonjs dependency bump including it. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The native createCubeTexture override only handled a single .env file or six face files; a single self-contained cubemap container (.dds/.ktx/.ktx2, as produced by CubeTexture.CreateFromPrefilteredData) threw "Cannot load cubemap because 6 files were not defined". The generic WebGL loader route is unusable on native (its texture-upload and cube-readback entry points are unimplemented). Route a single-URL container cubemap to engine.loadCubeTexture with the raw buffer; the native engine decodes it (bimg) and, when polynomials are requested, returns spherical-harmonics coefficients computed from the top mip, which are set as the texture's spherical polynomial. loadCubeTexture's onSuccess now optionally carries those coefficients. The .env and six-file paths are unchanged. Pairs with a Babylon Native NativeEngine change implementing the single-buffer cube decode and spherical-harmonics computation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…d onSuccess The six-file path passed the Promise resolve directly, which is not assignable to the widened onSuccess signature (sphericalPolynomial?: Float32Array). Wrap with () => resolve() / () => reject(new Error(...)). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

bjsplat · 2026-06-17T00:16:59Z

Interaction tests

https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/refs/pull/18560/merge/testResults/interactionplaywright/index.html

bjsplat · 2026-06-17T00:30:06Z

WebGL2 visualization test reporter:

https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/refs/pull/18560/merge/testResults/webgl2playwright/index.html

bkaradzic-microsoft · 2026-06-17T00:30:51Z

Closing as superseded by the loader rework (the BabylonNative#218 loader rework, BabylonJS/BabylonNative#218): implementing the native _uploadDataToTextureDirectly / _uploadCompressedDataToTextureDirectly stubs lights up the stock JS loader path on native, so the generic _DDSTextureLoader handles single-file .dds/.ktx/.ktx2 cube containers end-to-end (parse + upload + spherical-harmonics computed in JS via CubeMapToSphericalPolynomialTools.ConvertCubeMapToSphericalPolynomial). That replaces this PR's bespoke single-URL cube branch and the native->JS SH-coefficient handoff entirely. See BabylonJS/BabylonNative#1748 (comment).

bjsplat · 2026-06-17T00:35:23Z

🟢 Memory Leak Test Results

13 passed, 0 leaked out of 13 scenarios

🟢 All memory leak tests passed — no leaks detected.

Passed Scenarios (13)

Scenario	Package
Core Feature Stack	@babylonjs/core
Core Rendering Materials Shadows Stack	@babylonjs/core
Core Textures Render Targets PostProcess Stack	@babylonjs/core
GUI Fullscreen UI Controls	@babylonjs/gui
GUI Mesh ADT Controls	@babylonjs/gui
Loaders Boombox Import	@babylonjs/loaders
Loaders OBJ Direct Load	@babylonjs/loaders
Loaders STL Direct Load	@babylonjs/loaders
Materials Library Stack	@babylonjs/materials
Serializers glTF Export	@babylonjs/serializers
Serializers GLB Export	@babylonjs/serializers
PostProcesses Digital Rain Stack	@babylonjs/post-processes
Procedural Textures Stack	@babylonjs/procedural-textures

bjsplat · 2026-06-17T00:35:35Z

Visualization tests for WebGPU

https://snapshots-cvgtc2eugrd3cgfd.z01.azurefd.net/refs/pull/18560/merge/testResults/webgpuplaywright/index.html

bjsplat · 2026-06-17T01:12:55Z

⚡ Performance Test Results

🟢 All performance tests passed — no regressions detected.

…armonics loadCubeTexture now accepts a single self-contained cubemap container (all six faces + mips), decoded via bimg::imageParse, and uploads sides 0-5 x mips. ComputeCubeSphericalPolynomial derives the diffuse-IBL spherical harmonics from the top-mip faces (port of CubeMapToSphericalPolynomialTools) and returns the polynomial coefficients to JS. This is done natively because the WebGL upload and cube-readback paths are unimplemented on native and .dds stores no SH. Re-enables 6 prefiltered-environment PBR validation tests. Pairs with BabylonJS/Babylon.js#18560 (native createCubeTexture dispatch for single-URL containers). Depends on a babylonjs dependency bump including it. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

bkaradzic-microsoft mentioned this pull request Jun 10, 2026

NativeEngine: load single-file .dds/.ktx/.ktx2 cubemaps + spherical harmonics (re-enables 7 tests) BabylonJS/BabylonNative#1748

Open

This was referenced Jun 11, 2026

[Native] Combined native-engine GL fixes (depth, cube load, cube RTT, updateTextureData) #18567

Draft

Combined native-engine GL fixes (re-enables 10 validation tests) BabylonJS/BabylonNative#1752

Draft

bkaradzic-microsoft requested a review from bghgary June 16, 2026 16:01

bkaradzic and others added 2 commits June 16, 2026 16:51

bkaradzic-microsoft force-pushed the native-cube-container-loading branch from 09715d8 to 843f25c Compare June 16, 2026 23:51

bkaradzic-microsoft closed this Jun 17, 2026

Conversation

bkaradzic-microsoft commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

[Native] Load single-file .dds/.ktx/.ktx2 cubemaps on the native engine

Problem

Fix

Testing

Related PRs & landing order

Uh oh!

bjsplat commented Jun 10, 2026

Uh oh!

bjsplat commented Jun 10, 2026

Uh oh!

bjsplat commented Jun 11, 2026

Uh oh!

bjsplat commented Jun 11, 2026

Uh oh!

bjsplat commented Jun 11, 2026

Uh oh!

bjsplat commented Jun 11, 2026

🟢 Memory Leak Test Results

Uh oh!

bjsplat commented Jun 11, 2026

Uh oh!

bjsplat commented Jun 11, 2026

⚡ Performance Test Results

Uh oh!

bjsplat commented Jun 17, 2026

Uh oh!

bjsplat commented Jun 17, 2026

Uh oh!

bkaradzic-microsoft commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bjsplat commented Jun 17, 2026

🟢 Memory Leak Test Results

Uh oh!

bjsplat commented Jun 17, 2026

Uh oh!

bjsplat commented Jun 17, 2026

⚡ Performance Test Results

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bkaradzic-microsoft commented Jun 10, 2026 •

edited

Loading

[Native] Load single-file `.dds`/`.ktx`/`.ktx2` cubemaps on the native engine

bkaradzic-microsoft commented Jun 17, 2026 •

edited

Loading