@babylonjs/core 9.13.0 → 9.14.0

package/Engines/engine.d.ts

@@ -1561,6 +1561,119 @@ var OffscreenCanvasRenderingContext2D: {
     new (): OffscreenCanvasRenderingContext2D;
 };
 
+/* eslint-disable @typescript-eslint/naming-convention */
+/* eslint-disable no-var */
+// Type definitions for the WICG HTML-in-Canvas proposal (https://github.com/WICG/html-in-canvas).
+// These augment the standard DOM, WebGL and WebGPU types so Babylon can consume the API - whether
+// provided natively (behind chrome://flags/#canvas-draw-element) or by the three-html-render polyfill -
+// without TypeScript errors. The proposal is experimental; signatures track the explainer IDL and
+// may change.
+
+/**
+ * A transferable snapshot of a rendered element, produced by `HTMLCanvasElement.captureElementImage`.
+ */
+interface ElementImage {
+    readonly width: number;
+    readonly height: number;
+    close(): void;
+}
+
+var ElementImage: {
+    prototype: ElementImage;
+    new (): ElementImage;
+};
+
+/**
+ * Source rectangle and sizing configuration for `WebGLRenderingContext.texElementImage2D`.
+ */
+interface WebGLCopyElementImageConfig {
+    sx?: number;
+    sy?: number;
+    swidth?: number;
+    sheight?: number;
+    width?: number;
+    height?: number;
+}
+
+/**
+ * Event dispatched on a `<canvas layoutsubtree>` when the rendering of one of its children changes.
+ */
+interface PaintEvent extends Event {
+    readonly changedElements: ReadonlyArray<Element>;
+}
+
+interface HTMLCanvasElementEventMap {
+    paint: PaintEvent;
+}
+
+interface HTMLCanvasElement {
+    /** Opts canvas descendants into layout and hit testing so they can be drawn into the canvas. */
+    layoutSubtree: boolean;
+    /** Fired when the rendering of any canvas child has changed. */
+    onpaint: ((this: HTMLCanvasElement, ev: PaintEvent) => any) | null;
+    /** Requests a single `paint` event on the next rendering update, even if nothing changed. */
+    requestPaint(): void;
+    /** Captures a transferable snapshot of the given element. */
+    captureElementImage(element: Element): ElementImage;
+    /** Returns the CSS transform that keeps the element's DOM location in sync with its drawn location. */
+    getElementTransform(element: Element | ElementImage, drawTransform: DOMMatrix): DOMMatrix;
+}
+
+interface CanvasRenderingContext2D {
+    drawElementImage(element: Element | ElementImage, dx: number, dy: number): DOMMatrix;
+    drawElementImage(element: Element | ElementImage, dx: number, dy: number, dwidth: number, dheight: number): DOMMatrix;
+    drawElementImage(
+        element: Element | ElementImage,
+        sx: number,
+        sy: number,
+        swidth: number,
+        sheight: number,
+        dx: number,
+        dy: number,
+        dwidth?: number,
+        dheight?: number
+    ): DOMMatrix;
+}
+
+interface WebGLRenderingContext {
+    /** Uploads a rendered element (or snapshot) into the currently bound 2D texture (current WICG signature). */
+    texElementImage2D(target: number, internalformat: number, element: Element | ElementImage, config?: WebGLCopyElementImageConfig): void;
+    /** Legacy texImage2D-shaped overload still shipped by some Chrome Canary builds. */
+    texElementImage2D(target: number, level: number, internalformat: number, format: number, type: number, element: Element | ElementImage): void;
+}
+
+interface WebGL2RenderingContext {
+    /** Uploads a rendered element (or snapshot) into the currently bound 2D texture (current WICG signature). */
+    texElementImage2D(target: number, internalformat: number, element: Element | ElementImage, config?: WebGLCopyElementImageConfig): void;
+    /** Legacy texImage2D-shaped overload still shipped by some Chrome Canary builds. */
+    texElementImage2D(target: number, level: number, internalformat: number, format: number, type: number, element: Element | ElementImage): void;
+}
+
+/**
+ * Source descriptor for `GPUQueue.copyElementImageToTexture`.
+ */
+interface GPUCopyElementImageSource {
+    source: Element | ElementImage;
+    sx?: number;
+    sy?: number;
+    swidth?: number;
+    sheight?: number;
+}
+
+/**
+ * Destination descriptor for `GPUQueue.copyElementImageToTexture`.
+ */
+interface GPUCopyElementImageDestination {
+    destination: GPUCopyExternalImageDestInfo;
+    width?: number;
+    height?: number;
+}
+
+interface GPUQueue {
+    /** Uploads a rendered element (or snapshot) into a destination GPU texture. */
+    copyElementImageToTexture(source: GPUCopyElementImageSource, destination: GPUCopyElementImageDestination): void;
+}
+
 /* eslint-disable no-var */
 /* eslint-disable @typescript-eslint/naming-convention */
 // Mixins

package/Engines/thinNativeEngine.pure.d.ts

@@ -469,6 +469,8 @@ export declare class ThinNativeEngine extends ThinEngine {
         height: number;
         depth: number;
     }, options: boolean | RenderTargetCreationOptions): RenderTargetWrapper;
+    createRenderTargetCubeTexture(size: number, options?: RenderTargetCreationOptions): RenderTargetWrapper;
+    generateMipMapsForCubemap(_texture: InternalTexture, _unbind?: boolean): void;
     updateRenderTargetTextureSampleCount(rtWrapper: RenderTargetWrapper, samples: number): number;
     updateTextureSamplingMode(samplingMode: number, texture: InternalTexture): void;
     bindFramebuffer(texture: RenderTargetWrapper, faceIndex?: number, requiredWidth?: number, requiredHeight?: number, forceFullscreenViewport?: boolean): void;

package/Engines/thinNativeEngine.pure.js

@@ -183,6 +183,10 @@ export class ThinNativeEngine extends ThinEngine {
         this._webGLVersion = 2;
         this.disableUniformBuffers = true;
         this._shaderPlatformName = "NATIVE";
+        // Babylon Native is not WebGL and has no _gl context. Report a distinct engine name (like
+        // WebGPU reports "WebGPU") so application/feature code that branches on engine.name === "WebGL"
+        // to touch the WebGL-only _gl context skips the native engine instead of dereferencing null.
+        this._name = "Native";
         // TODO: Initialize this more correctly based on the hardware capabilities.
         // Init caps
         this._caps = {
@@ -1854,6 +1858,80 @@ export class ThinNativeEngine extends ThinEngine {
         rtWrapper.setTextures(texture);
         return rtWrapper;
     }
+    createRenderTargetCubeTexture(size, options) {
+        const rtWrapper = this._createHardwareRenderTargetWrapper(false, true, size);
+        let generateDepthBuffer = true;
+        let generateStencilBuffer = false;
+        let generateMipMaps = false;
+        let type = 0;
+        let samplingMode = 3;
+        let format = 5;
+        let samples = 1;
+        let label;
+        if (options !== undefined && typeof options === "object") {
+            generateDepthBuffer = options.generateDepthBuffer ?? true;
+            generateStencilBuffer = !!options.generateStencilBuffer;
+            generateMipMaps = !!options.generateMipMaps;
+            type = options.type ?? 0;
+            samplingMode = options.samplingMode ?? 3;
+            format = options.format ?? 5;
+            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 === 1 && !this._caps.textureFloatLinearFiltering) {
+            samplingMode = 1;
+        }
+        else if (type === 2 && !this._caps.textureHalfFloatLinearFiltering) {
+            samplingMode = 1;
+        }
+        if (type === 1 && !this._caps.textureFloat) {
+            type = 0;
+            Logger.Warn("Float textures are not supported. Type forced to TEXTURETYPE_UNSIGNED_BYTE");
+        }
+        const texture = new InternalTexture(this, 5 /* 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 = [];
+        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;
+    }
+    generateMipMapsForCubemap(_texture, _unbind = true) {
+        // 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.
+    }
     updateRenderTargetTextureSampleCount(rtWrapper, samples) {
         if (rtWrapper.samples === samples) {
             return samples;
@@ -1893,10 +1971,24 @@ 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(nativeTexture, texture.baseWidth, texture.baseHeight, rtWrapper._generateStencilBuffer, rtWrapper._generateDepthBuffer, samples);
+        const isCube = texture.isCube;
+        this._engine.initializeTexture(nativeTexture, texture.baseWidth, texture.baseHeight, 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 = [];
+            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;
@@ -1914,13 +2006,17 @@ export class ThinNativeEngine extends ThinEngine {
             this.unBindFramebuffer(this._currentRenderTarget);
         }
         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 {
@@ -2137,7 +2233,17 @@ export class ThinNativeEngine extends ThinEngine {
      * @param generateMipMaps defines whether to generate mipmaps or not
      */
     updateTextureData(texture, imageData, xOffset, yOffset, width, height, faceIndex = 0, lod = 0, generateMipMaps = false) {
-        throw new Error("updateTextureData not implemented.");
+        if (!texture._hardwareTexture) {
+            return;
+        }
+        if (!this._engine.updateTextureData) {
+            throw new Error("updateTextureData not implemented.");
+        }
+        // bgfx updates the requested sub-rectangle of the existing texture (faceIndex selects the cube
+        // face / array layer, lod selects the mip level). invertY is forwarded so the native side can match
+        // the vertical orientation the base texture upload uses. Mip regeneration after a partial update is
+        // not supported on Native, so generateMipMaps is ignored (consistent with the other raw-texture paths).
+        this._engine.updateTextureData(texture._hardwareTexture.underlyingResource, imageData, xOffset, yOffset, width, height, faceIndex, lod, texture.invertY);
     }
     /**
      * @internal