@onerjs/core 9.0.0 → 9.0.1

package/Engines/thinNativeEngine.pure.d.ts

@@ -9,7 +9,7 @@ import { type RenderTargetCreationOptions, type TextureSize, type DepthTextureCr
 import { type IPipelineContext } from "./IPipelineContext.js";
 import { type IMultiRenderTargetOptions } from "../Materials/Textures/multiRenderTarget.pure.js";
 import { type IColor3Like, type IColor4Like, type IViewportLike } from "../Maths/math.like.js";
-import { type ISceneLike } from "./abstractEngine.pure.js";
+import { type AbstractEngineOptions, type ISceneLike } from "./abstractEngine.pure.js";
 import { ThinEngine } from "./thinEngine.pure.js";
 import { type IMaterialContext } from "./IMaterialContext.js";
 import { type IDrawContext } from "./IDrawContext.js";
@@ -21,7 +21,7 @@ import { type INative, type INativeEngine, type NativeFramebuffer, type NativeTe
 import { NativeRenderTargetWrapper } from "./Native/nativeRenderTargetWrapper.js";
 import { type IHardwareTextureWrapper } from "../Materials/Textures/hardwareTextureWrapper.js";
 import { type _IShaderProcessingContext } from "./Processors/shaderProcessingOptions.js";
-import { type ShaderLanguage } from "../Materials/shaderLanguage.js";
+import { ShaderLanguage } from "../Materials/shaderLanguage.js";
 import { type WebGLHardwareTexture } from "./WebGL/webGLHardwareTexture.js";
 import { _TimeToken } from "../Instrumentation/timeToken.js";
 /**
@@ -50,7 +50,7 @@ declare class NativeDataBuffer extends DataBuffer {
 /**
  * Options to create the Native engine
  */
-export interface ThinNativeEngineOptions {
+export interface ThinNativeEngineOptions extends AbstractEngineOptions {
     /**
      * defines whether to adapt to the device's viewport characteristics (default: false)
      */
@@ -66,6 +66,13 @@ export declare class ThinNativeEngine extends ThinEngine {
     private _commandBufferEncoder;
     private _frameStats;
     private _boundBuffersVertexArray;
+    private _transformFeedbackBuffer;
+    private _transformFeedbackActive;
+    /**
+     * Bit i is set when color attachment i is selected by the last bindAttachments() call.
+     * Only used to mask clears (see bindAttachments).
+     */
+    private _clearAttachmentMask;
     private _currentDepthTest;
     private _depthTestEnabled;
     private _stencilTest;
@@ -85,6 +92,10 @@ export declare class ThinNativeEngine extends ThinEngine {
     private _cachedZOffsetUnits;
     private _depthWrite;
     private _fillModeWarningDisplayed;
+    private _int2Scratch;
+    private _int3Scratch;
+    private _int4Scratch;
+    private _frameGraphFramebufferRefCount;
     constructor(options?: ThinNativeEngineOptions);
     /**
      * Keeps as a separate function to use in NativeEngine
@@ -140,10 +151,12 @@ export declare class ThinNativeEngine extends ThinEngine {
     }): WebGLVertexArrayObject;
     private _deleteVertexArray;
     bindVertexArrayObject(vertexArray: WebGLVertexArrayObject): void;
+    /** @internal Native vertex arrays capture their buffers when recorded; there is no bound array buffer. */
+    bindArrayBuffer(_buffer: Nullable<DataBuffer>): void;
     releaseVertexArrayObject(vertexArray: WebGLVertexArrayObject): void;
     getAttributes(pipelineContext: IPipelineContext, attributesNames: string[]): number[];
     /**
-     * Triangle Fan and Line Loop are not supported by modern rendering API
+     * Check whether the runtime can expand primitive modes unavailable in modern rendering APIs.
      * @param fillMode  defines the primitive to use
      * @returns true if supported
      */
@@ -164,6 +177,24 @@ export declare class ThinNativeEngine extends ThinEngine {
      * @param instancesCount defines the number of instances to draw (if instantiation is enabled)
      */
     drawArraysType(fillMode: number, verticesStart: number, verticesCount: number, instancesCount?: number): void;
+    /** @internal Transform feedback objects are implicit on native; state lives on the engine. */
+    createTransformFeedback(): WebGLTransformFeedback;
+    /** @internal */
+    deleteTransformFeedback(_value: WebGLTransformFeedback): void;
+    /** @internal */
+    bindTransformFeedback(_value: Nullable<WebGLTransformFeedback>): void;
+    /** @internal */
+    bindTransformFeedbackBuffer(value: Nullable<DataBuffer>): void;
+    /** @internal Varyings are passed to the native program when it is created. */
+    setTranformFeedbackVaryings(_program: WebGLProgram, _value: string[]): void;
+    /** @internal */
+    beginTransformFeedback(_usePoints?: boolean): void;
+    /** @internal */
+    endTransformFeedback(): void;
+    /** @internal */
+    readTransformFeedbackBuffer(target: ArrayBufferView): void;
+    /** @internal Transform feedback draws never rasterize on native. */
+    setRasterizerState(_value: boolean): void;
     createPipelineContext(shaderProcessingContext: Nullable<_IShaderProcessingContext>): IPipelineContext;
     createMaterialContext(): IMaterialContext | undefined;
     createDrawContext(): IDrawContext | undefined;
@@ -171,17 +202,17 @@ export declare class ThinNativeEngine extends ThinEngine {
      * Function is not technically Async
      * @internal
      */
-    _preparePipelineContextAsync(pipelineContext: IPipelineContext, vertexSourceCode: string, fragmentSourceCode: string, createAsRaw: boolean, _rawVertexSourceCode: string, _rawFragmentSourceCode: string, _rebuildRebind: any, defines: Nullable<string>, _transformFeedbackVaryings: Nullable<string[]>, _key: string, onReady: () => void): void;
+    _preparePipelineContextAsync(pipelineContext: IPipelineContext, vertexSourceCode: string, fragmentSourceCode: string, createAsRaw: boolean, _rawVertexSourceCode: string, _rawFragmentSourceCode: string, _rebuildRebind: any, defines: Nullable<string>, transformFeedbackVaryings: Nullable<string[]>, _key: string, onReady: () => void): void;
     /**
      * @internal
      */
-    _getShaderProcessingContext(_shaderLanguage: ShaderLanguage): Nullable<_IShaderProcessingContext>;
+    _getShaderProcessingContext(shaderLanguage: ShaderLanguage): Nullable<_IShaderProcessingContext>;
     /**
      * @internal
      */
     _executeWhenRenderingStateIsCompiled(pipelineContext: IPipelineContext, action: () => void): void;
     createRawShaderProgram(): WebGLProgram;
-    createShaderProgram(pipelineContext: IPipelineContext, vertexCode: string, fragmentCode: string, defines: Nullable<string>): WebGLProgram;
+    createShaderProgram(pipelineContext: IPipelineContext, vertexCode: string, fragmentCode: string, defines: Nullable<string>, _context?: WebGLRenderingContext, transformFeedbackVaryings?: Nullable<string[]>): WebGLProgram;
     /**
      * Inline functions in shader code that are marked to be inlined
      * @param code code to inline
@@ -230,7 +261,6 @@ export declare class ThinNativeEngine extends ThinEngine {
     setDepthBuffer(enable: boolean): void;
     private _encodeDepthTest;
     private _flushDepthTestState;
-    applyStates(): void;
     /**
      * Gets a boolean indicating if depth writing is enabled
      * @returns the current depth writing state
@@ -253,6 +283,20 @@ export declare class ThinNativeEngine extends ThinEngine {
      * @returns the current color writing state
      */
     getColorWrite(): boolean;
+    /**
+     * Apply the currently pending engine states.
+     *
+     * The base ThinEngine.applyStates() flushes state by calling
+     * this._depthCullingState.apply(this._gl) (and similar for alpha/stencil), but the
+     * native engine has no WebGL context (_gl is undefined), so inheriting that path
+     * throws "Cannot read properties of undefined (reading 'depthMask')". Callers such
+     * as the depth-peeling (OIT) renderer mutate engine.depthCullingState directly and
+     * then call applyStates() expecting the change to be flushed, so reconcile the shared
+     * depth-culling state into the native command buffer here instead. Alpha and stencil
+     * states are already encoded immediately on the native side (setAlphaMode /
+     * setStencil* emit commands directly), so only the depth state needs reconciling.
+     */
+    applyStates(): void;
     private applyStencil;
     private _setStencil;
     /**
@@ -291,8 +335,8 @@ export declare class ThinNativeEngine extends ThinEngine {
      */
     setStencilFunctionReference(reference: number): void;
     /**
-     * Sets the current stencil mask
-     * @param mask defines the new stencil mask to use
+     * Sets the current stencil function mask
+     * @param mask defines the new stencil function mask to use
      */
     setStencilFunctionMask(mask: number): void;
     /**
@@ -351,7 +395,19 @@ export declare class ThinNativeEngine extends ThinEngine {
      * @see https://doc.babylonjs.com/features/featuresDeepDive/materials/advanced/transparent_rendering
      */
     setAlphaMode(mode: number, noDepthWriteChange?: boolean, targetIndex?: number): void;
+    /**
+     * Sets the current alpha blend equation (ADD / SUB / MAX / MIN / ...).
+     * Dual depth peeling (OIT) requires ALPHA_EQUATION_MAX so peel passes accumulate
+     * farthest/nearest depths. Native previously only wired blend *factors*; equations
+     * stayed at bgfx's default ADD and transparent peels never wrote useful depth.
+     * @param equation one of Constants.ALPHA_EQUATION_*
+     * @param targetIndex MRT attachment index (Native applies equation globally; kept for API parity)
+     */
+    setAlphaEquation(equation: number, targetIndex?: number): void;
     setInt(uniform: WebGLUniformLocation, int: number): boolean;
+    setInt2(uniform: Nullable<WebGLUniformLocation>, x: number, y: number): boolean;
+    setInt3(uniform: Nullable<WebGLUniformLocation>, x: number, y: number, z: number): boolean;
+    setInt4(uniform: Nullable<WebGLUniformLocation>, x: number, y: number, z: number, w: number): boolean;
     setIntArray(uniform: WebGLUniformLocation, array: Int32Array): boolean;
     setIntArray2(uniform: WebGLUniformLocation, array: Int32Array): boolean;
     setIntArray3(uniform: WebGLUniformLocation, array: Int32Array): boolean;
@@ -390,7 +446,42 @@ export declare class ThinNativeEngine extends ThinEngine {
     updateVideoTexture(texture: Nullable<InternalTexture>, video: HTMLVideoElement, invertY: boolean): void;
     createRawTexture(data: Nullable<ArrayBufferView>, width: number, height: number, format: number, generateMipMaps: boolean, invertY: boolean, samplingMode: number, compression?: Nullable<string>, type?: number, creationFlags?: number, useSRGBBuffer?: boolean): InternalTexture;
     createRawTexture2DArray(data: Nullable<ArrayBufferView>, width: number, height: number, depth: number, format: number, generateMipMaps: boolean, invertY: boolean, samplingMode: number, compression?: Nullable<string>, textureType?: number): InternalTexture;
+    createRawTexture3D(data: Nullable<ArrayBufferView>, width: number, height: number, depth: number, format: number, generateMipMaps: boolean, invertY: boolean, samplingMode: number, compression?: Nullable<string>, textureType?: number): InternalTexture;
+    updateRawTexture3D(texture: Nullable<InternalTexture>, bufferView: Nullable<ArrayBufferView>, format: number, invertY: boolean, compression?: Nullable<string>, textureType?: number): void;
     updateRawTexture(texture: Nullable<InternalTexture>, bufferView: Nullable<ArrayBufferView>, format: number, invertY: boolean, compression?: Nullable<string>, type?: number, useSRGBBuffer?: boolean): void;
+    /**
+     * Creates a raw cube texture on the native engine.
+     *
+     * The WebGL implementation (engine.rawTexture) drives the whole upload through `this._gl`, which is null
+     * on Native, so loading an HDR/`.env` cube via `createRawCubeTextureFromUrl` used to throw
+     * `Cannot read properties of undefined (reading 'FLOAT')`. This override allocates a native cube texture
+     * and uploads its faces through the bgfx `updateTextureData` path instead.
+     *
+     * Native has no 3-component float texture format, so an RGB float/half-float source (what HDRCubeTexture
+     * requests) is allocated and uploaded as RGBA; the per-face RGB->RGBA expansion happens in
+     * `updateRawCubeTexture`.
+     * @param data defines the data used to create the texture (6 faces, +X +Y +Z -X -Y -Z) or null
+     * @param size defines the size of the textures (each face is size x size)
+     * @param format defines the format of the data
+     * @param type defines the type of the data
+     * @param generateMipMaps defines if the engine should generate the mip levels
+     * @param invertY defines if data must be stored with Y axis inverted
+     * @param samplingMode defines the required sampling mode (like Texture.NEAREST_SAMPLINGMODE)
+     * @param compression defines the compression used (null by default)
+     * @returns the cube texture as an InternalTexture
+     */
+    createRawCubeTexture(data: Nullable<ArrayBufferView[]>, size: number, format: number, type: number, generateMipMaps: boolean, invertY: boolean, samplingMode: number, compression?: Nullable<string>): InternalTexture;
+    /**
+     * Updates a raw cube texture on the native engine.
+     * @param texture defines the texture to update
+     * @param data defines the data to store (6 faces, +X +Y +Z -X -Y -Z)
+     * @param format defines the data format
+     * @param type defines the type of the data
+     * @param invertY defines if data must be stored with Y axis inverted
+     * @param compression defines the compression used (null by default)
+     * @param level defines which mip level of the texture to update (0 by default)
+     */
+    updateRawCubeTexture(texture: InternalTexture, data: ArrayBufferView[], format: number, type: number, invertY: boolean, compression?: Nullable<string>, level?: number): void;
     /**
      * Usually called from Texture.ts.
      * Passed information to create a NativeTexture
@@ -444,11 +535,98 @@ export declare class ThinNativeEngine extends ThinEngine {
      * @param texture defines the new native texture handle to wrap
      */
     updateWrappedNativeTexture(internalTexture: InternalTexture, texture: NativeTexture): void;
+    /**
+     * Creates a depth/stencil texture for a render target wrapper.
+     * @param size The size of the depth texture
+     * @param options The options defining the depth texture
+     * @param rtWrapper The render target wrapper the depth texture belongs to
+     * @returns The depth/stencil texture
+     */
+    createDepthStencilTexture(size: TextureSize, options: DepthTextureCreationOptions, rtWrapper: RenderTargetWrapper): InternalTexture;
     _createDepthStencilTexture(size: TextureSize, options: DepthTextureCreationOptions, rtWrapper: RenderTargetWrapper): InternalTexture;
+    /**
+     * Builds the framebuffer(s) of a render target so they carry its sampleable depth/stencil texture. The depth
+     * texture's native handle must not be allocated yet: the first framebuffer creation allocates it.
+     * @internal
+     */
+    _attachDepthStencilTexture(nativeRTWrapper: NativeRenderTargetWrapper, texture: InternalTexture, width: number, height: number, generateStencil: boolean, samples: number): void;
+    private _recreateDepthStencilTexture;
+    /**
+     * Returns whether a render-target texture was created with mip storage, independently of generateMipMaps.
+     * @internal
+     */
+    _hasMipStorage(texture: InternalTexture): boolean;
+    private _setHasMipStorage;
+    /**
+     * Ensures a cloned render-target texture retains allocation-only mip storage.
+     * @internal
+     */
+    _ensureRenderTargetMipStorage(texture: InternalTexture): boolean;
+    /**
+     * Rebuilds native framebuffer objects after a wrapper's explicit depth attachment changes.
+     * @internal
+     */
+    _rebuildRenderTargetFramebuffersAfterDepthChange(nativeRTWrapper: NativeRenderTargetWrapper): void;
+    /**
+     * Rejects an explicit depth attachment the render target cannot use, before any attachment state is mutated.
+     * bgfx requires every framebuffer attachment to share one sample count.
+     * @internal
+     */
+    _assertDepthAttachmentCompatible(rtWrapper: NativeRenderTargetWrapper, depthSamples: number): void;
+    /**
+     * Whether the depth attachment carries stencil: an explicit depth texture decides from its own format (its handle
+     * may be unallocated after a sample-count change), otherwise the automatic depth buffer request does.
+     * @internal
+     */
+    _getDepthAttachmentStencil(rtWrapper: NativeRenderTargetWrapper): boolean;
+    /** @internal */
+    _assertVolumeDepthAttachmentSupported(depthSamples?: number, colorSamples?: number): void;
+    /**
+     * Updates a depth texture Comparison Mode and Function.
+     * @param texture The texture to set the comparison function for
+     * @param comparisonFunction The comparison function to set, 0 if no comparison required
+     */
+    updateTextureComparisonFunction(texture: InternalTexture, comparisonFunction: number): void;
+    /**
+     * Generates mipmaps for the given texture.
+     * @param _texture The texture to generate the mipmaps for.
+     */
+    generateMipmaps(_texture: InternalTexture): void;
+    /**
+     * Creates one framebuffer per layer (or cube face) of a native texture.
+     * @internal
+     */
+    _createLayerFramebuffers(nativeTexture: NativeTexture, width: number, height: number, layerCount: number, generateStencilBuffer: boolean, generateDepthBuffer: boolean, samples: number, autoGenerateMips?: boolean): NativeFramebuffer[];
+    /**
+     * Per-layer framebuffers carry their own depth/stencil attachment, either requested at creation or added by
+     * createDepthStencilTexture (see _createDepthStencilTexture), so recreate them with the same attachments.
+     * @internal
+     */
+    _getLayerFramebufferDepthStencil(rtWrapper: RenderTargetWrapper): {
+        generateDepth: boolean;
+        generateStencil: boolean;
+    };
     /**
      * @internal
      */
     _releaseFramebufferObjects(framebuffer: Nullable<NativeFramebuffer>): void;
+    /**
+     * Returns true when the given framebuffer was built by the frame graph path (_buildFrameGraphFramebuffer),
+     * i.e. it is reference-counted, shared between wrappers and rebuilt lazily on bind.
+     * @param framebuffer The framebuffer to test
+     * @returns true if the framebuffer is a frame graph framebuffer
+     * @internal
+     */
+    _isFrameGraphFramebuffer(framebuffer: NativeFramebuffer): boolean;
+    /**
+     * Lazily builds (or reuses a shared) bgfx framebuffer for a frame graph render-target wrapper whose
+     * textures were attached after creation (dontCreateTextures). All wrappers that reference the same
+     * underlying color texture share a single framebuffer, cached on that texture's hardware wrapper, so that
+     * successive passes (clear, object render, post) accumulate into the same target instead of each fresh
+     * framebuffer/view clearing it.
+     * @internal
+     */
+    private _buildFrameGraphFramebuffer;
     /**
      * @internal Engine abstraction for loading and creating an image bitmap from a given source string.
      * @param imageSource source to load the image from.
@@ -475,13 +653,18 @@ export declare class ThinNativeEngine extends ThinEngine {
     _createHardwareTexture(): IHardwareTextureWrapper;
     /** @internal */
     _createHardwareRenderTargetWrapper(isMulti: boolean, isCube: boolean, size: TextureSize): RenderTargetWrapper;
+    /**
+     * Older bgfx D3D11/D3D12/Vulkan backends share one texture descriptor between the MSAA render target and its
+     * resolve target, so requesting mips together with samples > 1 fails texture creation (BabylonNative#1714).
+     * Only keep the mip chain of a multisampled render target when the runtime reports that it supports it.
+     * @internal
+     */
+    _getRenderTargetHasMips(generateMipMaps: boolean, samples: number): boolean;
     /** @internal */
     _createInternalTexture(size: TextureSize, options: boolean | InternalTextureCreationOptions, _delayGPUTextureCreation?: boolean, source?: InternalTextureSource): InternalTexture;
-    createRenderTargetTexture(size: number | {
-        width: number;
-        height: number;
-        depth: number;
-    }, options: boolean | RenderTargetCreationOptions): RenderTargetWrapper;
+    private _createInternalCubeTexture;
+    createRenderTargetTexture(size: TextureSize, options: boolean | RenderTargetCreationOptions): RenderTargetWrapper;
+    private _createRenderTargetTexture3D;
     createRenderTargetCubeTexture(size: number, options?: RenderTargetCreationOptions): RenderTargetWrapper;
     createMultipleRenderTarget(size: TextureSize, options: IMultiRenderTargetOptions, _initializeBuffers?: boolean): RenderTargetWrapper;
     /**
@@ -494,8 +677,15 @@ export declare class ThinNativeEngine extends ThinEngine {
      * @internal
      */
     _createMultiRenderTargetFramebuffer(rtWrapper: NativeRenderTargetWrapper): void;
+    private _applyDepthTextureSampling;
+    /**
+     * Creates a multi-attachment framebuffer, falling back to a single-attachment framebuffer bound to the first
+     * color target (and its first requested layer) on older Babylon Native runtimes without createMultiFrameBuffer.
+     * @internal
+     */
+    _createNativeMultiFrameBuffer(colorTextures: NativeTexture[], width: number, height: number, generateStencilBuffer: boolean, generateDepthBuffer: boolean, samples: number, layers?: number[], explicitDepthTexture?: NativeTexture): NativeFramebuffer;
     generateMipMapsForCubemap(_texture: InternalTexture, _unbind?: boolean): void;
-    bindAttachments(_attachments: number[]): void;
+    bindAttachments(attachments: number[]): void;
     clearAttachments(color: Nullable<IColor4Like>, attachments: number[], clearColor: boolean, clearDepth: boolean, clearStencil?: boolean, stencilClearValue?: number): void;
     buildTextureLayout(textureStatus: boolean[], _backBufferLayout?: boolean): number[];
     restoreSingleAttachment(): void;
@@ -506,7 +696,13 @@ export declare class ThinNativeEngine extends ThinEngine {
     updateMultipleRenderTargetTextureSampleCount(rtWrapper: Nullable<RenderTargetWrapper>, samples: number, _initializeBuffers?: boolean): number;
     updateRenderTargetTextureSampleCount(rtWrapper: RenderTargetWrapper, samples: number): number;
     updateTextureSamplingMode(samplingMode: number, texture: InternalTexture): void;
-    bindFramebuffer(texture: RenderTargetWrapper, faceIndex?: number, requiredWidth?: number, requiredHeight?: number, forceFullscreenViewport?: boolean): void;
+    updateTextureWrappingMode(texture: InternalTexture, wrapU: Nullable<number>, wrapV?: Nullable<number>, wrapR?: Nullable<number>): void;
+    bindFramebuffer(texture: RenderTargetWrapper, faceIndex?: number, requiredWidth?: number, requiredHeight?: number, forceFullscreenViewport?: boolean, lodLevel?: number, layer?: number): void;
+    private _applyBoundViewport;
+    private _get3DLayerFramebuffer;
+    private _getCubeFaceMipFramebuffer;
+    private _isLayeredFrameGraphMRT;
+    private _bindLayeredMultiFramebuffer;
     unBindFramebuffer(texture: RenderTargetWrapper, disableGenerateMipMaps?: boolean, onBeforeUnbind?: () => void): void;
     createDynamicVertexBuffer(data: DataArray): DataBuffer;
     updateDynamicIndexBuffer(indexBuffer: DataBuffer, indices: IndicesArray, offset?: number): void;
@@ -524,6 +720,10 @@ export declare class ThinNativeEngine extends ThinEngine {
      * @internal
      */
     _bindTexture(channel: number, texture: Nullable<InternalTexture>): void;
+    /**
+     * @internal
+     */
+    _bindTextureDirectly(_target: number, _texture: Nullable<InternalTexture>, _forTextureDataUpdate?: boolean, _force?: boolean): boolean;
     /**
      * Unbind all textures
      */