[Native] Add cube render target support to the native engine (#18561)

Paired native PR: BabylonJS/BabylonNative#1750

## What

Adds cube render target support to the Babylon Native engine. Previously
the
native engine had no `createRenderTargetCubeTexture` override and
`bindFramebuffer(faceIndex)` threw, so any feature that renders into a
cube map
— `ReflectionProbe`, point-light cube shadow maps — fell through to the
WebGL
code path and dereferenced the null `_gl` context (`TEXTURE_CUBE_MAP
undefined`).

## Changes (`packages/dev/core/src/Engines`)

- `thinNativeEngine.pure.ts`
- `createRenderTargetCubeTexture`: creates a native cube color texture
and one
framebuffer per face (the native side binds the matching cube layer).
- `bindFramebuffer`: binds the per-face framebuffer for cube render
targets.
- `generateMipMapsForCubemap`: no-op on Native — bgfx auto-generates the
mip
    chain on render-target resolve, the same way 2D RTTs get their mips.
- `Native/nativeRenderTargetWrapper.ts`: tracks per-face framebuffers
and
  releases them on dispose.
- `Native/nativeInterfaces.ts`: threads the cube/layer params through
  `initializeTexture` and `createFrameBuffer`.

## Paired native change

Requires the matching BabylonNative C++ change (cube color texture +
per-face
attachment). Draft until both land.

## Testing

Built `babylon.max.js` and ran the BabylonNative Playground validation
suite
(D3D11). The "Shadows with instances" tests (left/right handed), which
previously crashed, now pass; the ReflectionProbe and point-light-shadow
scenes
render with correct geometry and orientation.

---

## Related PRs & landing order

- **Babylon.js (engine / TS):**
#18561
- **BabylonNative (C++ engine + test re-enable):**
BabylonJS/BabylonNative#1750

Co-dependent; land in this order:
1. **Babylon.js #18561 first** — adds the cube render-target TS
overrides; no WebGL behavior change.
2. A **`babylonjs` npm release** ships that TS change.
3. **BabylonNative #1750 last** — bumps the bundled `babylonjs` and
re-enables the 2 `Shadows with instances` (left/right handed) validation
tests, which only pass once the paired JS is present in the bundled
engine.

---------

Co-authored-by: Branimir Karadzic <branimirkaradzic@gmail.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

packages/dev/core/src/Engines/Native/nativeInterfaces.ts

@@ -61,7 +61,17 @@ export interface INativeEngine {
     getAttributes(shaderProgram: NativeProgram, attributeNames: string[]): number[];
 
     createTexture(): NativeTexture;
-    initializeTexture(texture: NativeTexture, width: number, height: number, hasMips: boolean, format: number, renderTarget: boolean, srgb: boolean, samples: number): void;
+    initializeTexture(
+        texture: NativeTexture,
+        width: number,
+        height: number,
+        hasMips: boolean,
+        format: number,
+        renderTarget: boolean,
+        srgb: boolean,
+        samples: number,
+        isCube?: boolean
+    ): void;
     loadTexture(texture: NativeTexture, data: ArrayBufferView, generateMips: boolean, invertY: boolean, srgb: boolean, onSuccess: () => void, onError: () => void): void;
     loadRawTexture(texture: NativeTexture, data: ArrayBufferView, width: number, height: number, format: number, generateMips: boolean, invertY: boolean): void;
     loadRawTexture2DArray(
@@ -101,7 +111,8 @@ export interface INativeEngine {
         height: number,
         generateStencilBuffer: boolean,
         generateDepthBuffer: boolean,
-        samples: number
+        samples: number,
+        layer?: number
     ): NativeFramebuffer;
 
     getRenderWidth(): number;

packages/dev/core/src/Engines/Native/nativeRenderTargetWrapper.ts

@@ -11,6 +11,9 @@ export class NativeRenderTargetWrapper extends RenderTargetWrapper {
     private __framebuffer: Nullable<NativeFramebuffer> = null;
     // eslint-disable-next-line @typescript-eslint/naming-convention
     private __framebufferDepthStencil: Nullable<NativeFramebuffer> = null;
+    // Per-face framebuffers for cube render targets (index = cube face 0..5).
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    private __framebuffers: Nullable<NativeFramebuffer[]> = null;
 
     public get _framebuffer(): Nullable<NativeFramebuffer> {
         return this.__framebuffer;
@@ -23,6 +26,21 @@ export class NativeRenderTargetWrapper extends RenderTargetWrapper {
         this.__framebuffer = framebuffer;
     }
 
+    public get _framebuffers(): Nullable<NativeFramebuffer[]> {
+        return this.__framebuffers;
+    }
+
+    public set _framebuffers(framebuffers: Nullable<NativeFramebuffer[]>) {
+        if (this.__framebuffers) {
+            for (const framebuffer of this.__framebuffers) {
+                this._engine._releaseFramebufferObjects(framebuffer);
+            }
+        }
+        this.__framebuffers = framebuffers;
+        // Keep _framebuffer pointing at face 0 so single-target code paths still work.
+        this.__framebuffer = framebuffers ? framebuffers[0] : null;
+    }
+
     public get _framebufferDepthStencil(): Nullable<NativeFramebuffer> {
         return this.__framebufferDepthStencil;
     }
@@ -40,7 +58,13 @@ export class NativeRenderTargetWrapper extends RenderTargetWrapper {
     }
 
     public override dispose(disposeOnlyFramebuffers = false): void {
-        this._framebuffer = null;
+        if (this.__framebuffers) {
+            // Releases all six per-face framebuffers (face 0 is aliased by __framebuffer, so
+            // clear that alias here without releasing it again).
+            this._framebuffers = null;
+        } else {
+            this._framebuffer = null;
+        }
         this._framebufferDepthStencil = null;
 
         super.dispose(disposeOnlyFramebuffers);

packages/dev/core/src/Engines/thinNativeEngine.pure.ts

@@ -2359,6 +2359,90 @@ export class ThinNativeEngine extends ThinEngine {
         return rtWrapper;
     }
 
+    public override createRenderTargetCubeTexture(size: number, options?: RenderTargetCreationOptions): RenderTargetWrapper {
+        const rtWrapper = this._createHardwareRenderTargetWrapper(false, true, size) as NativeRenderTargetWrapper;
+
+        let generateDepthBuffer = true;
+        let generateStencilBuffer = false;
+        let generateMipMaps = false;
+        let type = Constants.TEXTURETYPE_UNSIGNED_BYTE;
+        let samplingMode = Constants.TEXTURE_TRILINEAR_SAMPLINGMODE;
+        let format = Constants.TEXTUREFORMAT_RGBA;
+        let samples = 1;
+        let label: string | undefined;
+        if (options !== undefined && typeof options === "object") {
+            generateDepthBuffer = options.generateDepthBuffer ?? true;
+            generateStencilBuffer = !!options.generateStencilBuffer;
+            generateMipMaps = !!options.generateMipMaps;
+            type = options.type ?? Constants.TEXTURETYPE_UNSIGNED_BYTE;
+            samplingMode = options.samplingMode ?? Constants.TEXTURE_TRILINEAR_SAMPLINGMODE;
+            format = options.format ?? Constants.TEXTUREFORMAT_RGBA;
+            samples = options.samples ?? 1;
+            label = options.label;
+        }
+
+        // Match _createInternalTexture: float/half-float RTTs that the platform can't linearly filter fall
+        // back to NEAREST so the cube RTT never carries an unsupported sampling mode.
+        if (type === Constants.TEXTURETYPE_FLOAT && !this._caps.textureFloatLinearFiltering) {
+            samplingMode = Constants.TEXTURE_NEAREST_SAMPLINGMODE;
+        } else if (type === Constants.TEXTURETYPE_HALF_FLOAT && !this._caps.textureHalfFloatLinearFiltering) {
+            samplingMode = Constants.TEXTURE_NEAREST_SAMPLINGMODE;
+        }
+        if (type === Constants.TEXTURETYPE_FLOAT && !this._caps.textureFloat) {
+            type = Constants.TEXTURETYPE_UNSIGNED_BYTE;
+            Logger.Warn("Float textures are not supported. Type forced to TEXTURETYPE_UNSIGNED_BYTE");
+        }
+
+        const texture = new InternalTexture(this, InternalTextureSource.RenderTarget);
+        texture.isCube = true;
+        texture.baseWidth = size;
+        texture.baseHeight = size;
+        texture.width = size;
+        texture.height = size;
+        texture.isReady = true;
+        texture.samples = samples;
+        texture.generateMipMaps = generateMipMaps;
+        texture.samplingMode = samplingMode;
+        texture.type = type;
+        texture.format = format;
+        texture.label = label;
+
+        const nativeTexture = texture._hardwareTexture!.underlyingResource;
+        const nativeTextureFormat = getNativeTextureFormat(format, type);
+        // See the createRenderTargetTexture MSAA/mips note: avoid the mips + samples combo on bgfx.
+        const hasMips = samples > 1 ? false : generateMipMaps;
+        this._engine.initializeTexture(nativeTexture, size, size, hasMips, nativeTextureFormat, /*renderTarget*/ true, /*srgb*/ false, samples, /*isCube*/ true);
+        this._setTextureSampling(nativeTexture, getNativeSamplingMode(samplingMode));
+
+        // The native engine cannot render to all six faces through one framebuffer, so create one
+        // framebuffer per face (the C++ side binds the matching cube layer); bindFramebuffer(faceIndex)
+        // then selects the right one.
+        const framebuffers: NativeFramebuffer[] = [];
+        for (let face = 0; face < 6; face++) {
+            framebuffers.push(this._engine.createFrameBuffer(nativeTexture, size, size, generateStencilBuffer, generateDepthBuffer, samples, face));
+        }
+
+        rtWrapper._framebuffers = framebuffers;
+        rtWrapper._generateDepthBuffer = generateDepthBuffer;
+        rtWrapper._generateStencilBuffer = generateStencilBuffer;
+        rtWrapper._samples = samples;
+
+        rtWrapper.setTextures(texture);
+
+        // Track the hand-built cube RTT texture the same way _createInternalTexture tracks 2D textures so it
+        // participates in engine-wide lifecycle management (dispose iteration, context rebuild, stats).
+        this._internalTexturesCache.push(texture);
+
+        return rtWrapper;
+    }
+
+    public override generateMipMapsForCubemap(_texture: InternalTexture, _unbind = true): void {
+        // The WebGL path rebinds gl.TEXTURE_CUBE_MAP and calls gl.generateMipmap; both deref _gl, which is
+        // null on Native. bgfx auto-generates the mip chain when a render target texture created with mips is
+        // resolved (the same way 2D RTTs get their mips here -- unBindFramebuffer issues no explicit mipgen),
+        // so this is a no-op on Native.
+    }
+
     public override updateRenderTargetTextureSampleCount(rtWrapper: RenderTargetWrapper, samples: number): number {
         if (rtWrapper.samples === samples) {
             return samples;
@@ -2404,19 +2488,51 @@ export class ThinNativeEngine extends ThinEngine {
         // underlying bgfx resource has 1 mip level. Remove this guard once a fixed bgfx is in stable BN npm.
         const hasMips = samples > 1 ? false : texture.generateMipMaps;
         const nativeTextureFormat = getNativeTextureFormat(texture.format, texture.type);
-        this._engine.initializeTexture(nativeTexture, texture.baseWidth, texture.baseHeight, hasMips, nativeTextureFormat, /*renderTarget*/ true, texture._useSRGBBuffer, samples);
-
-        // NativeRenderTargetWrapper._framebuffer setter releases the old framebuffer before assigning,
-        // so no manual _releaseFramebufferObjects call is needed (and would double-delete the handle).
-        nativeRTWrapper._framebuffer = this._engine.createFrameBuffer(
+        const isCube = texture.isCube;
+        this._engine.initializeTexture(
             nativeTexture,
             texture.baseWidth,
             texture.baseHeight,
-            rtWrapper._generateStencilBuffer,
-            rtWrapper._generateDepthBuffer,
-            samples
+            hasMips,
+            nativeTextureFormat,
+            /*renderTarget*/ true,
+            texture._useSRGBBuffer,
+            samples,
+            isCube
         );
 
+        if (isCube) {
+            // Cube RTTs render through one framebuffer per face (see createRenderTargetCubeTexture). The
+            // underlying bgfx handle was just rotated, so recreate all six attachments; the _framebuffers
+            // setter releases the stale ones and keeps _framebuffer aliased to face 0 for single-target paths.
+            const framebuffers: NativeFramebuffer[] = [];
+            for (let face = 0; face < 6; face++) {
+                framebuffers.push(
+                    this._engine.createFrameBuffer(
+                        nativeTexture,
+                        texture.baseWidth,
+                        texture.baseHeight,
+                        rtWrapper._generateStencilBuffer,
+                        rtWrapper._generateDepthBuffer,
+                        samples,
+                        face
+                    )
+                );
+            }
+            nativeRTWrapper._framebuffers = framebuffers;
+        } else {
+            // NativeRenderTargetWrapper._framebuffer setter releases the old framebuffer before assigning,
+            // so no manual _releaseFramebufferObjects call is needed (and would double-delete the handle).
+            nativeRTWrapper._framebuffer = this._engine.createFrameBuffer(
+                nativeTexture,
+                texture.baseWidth,
+                texture.baseHeight,
+                rtWrapper._generateStencilBuffer,
+                rtWrapper._generateDepthBuffer,
+                samples
+            );
+        }
+
         rtWrapper._samples = samples;
         texture.samples = samples;
         return samples;
@@ -2440,15 +2556,16 @@ export class ThinNativeEngine extends ThinEngine {
 
         this._currentRenderTarget = texture;
 
-        if (faceIndex) {
-            throw new Error("Cuboid frame buffers are not yet supported in NativeEngine.");
-        }
-
         if (requiredWidth || requiredHeight) {
             throw new Error("Required width/height for frame buffers not yet supported in NativeEngine.");
         }
 
-        if (nativeRTWrapper._framebufferDepthStencil) {
+        if (nativeRTWrapper._framebuffers) {
+            // Cube render target: bind the framebuffer for the requested face.
+            this._bindUnboundFramebuffer(nativeRTWrapper._framebuffers[faceIndex ?? 0]);
+        } else if (faceIndex) {
+            throw new Error("Cuboid frame buffers are not yet supported in NativeEngine.");
+        } else if (nativeRTWrapper._framebufferDepthStencil) {
             this._bindUnboundFramebuffer(nativeRTWrapper._framebufferDepthStencil);
         } else {
             this._bindUnboundFramebuffer(nativeRTWrapper._framebuffer);