@onerjs/core 8.46.1 → 8.46.2

package/Engines/webgpuEngine.js

@@ -412,7 +412,7 @@ export class WebGPUEngine extends ThinWebGPUEngine {
             .then(async (adapter) => {
             if (!adapter) {
                 // eslint-disable-next-line no-throw-literal
-                throw "Could not retrieve a WebGPU adapter (adapter is null).";
+                throw "Could not retrieve a WebGPU adapter (adapter is null or undefined).";
             }
             else {
                 this._adapter = adapter;
@@ -2874,6 +2874,85 @@ export class WebGPUEngine extends ThinWebGPUEngine {
         this._draw(1, fillMode, verticesStart, verticesCount, instancesCount);
     }
     //------------------------------------------------------------------------------
+    //                        Async Pipeline Pre-Warming
+    //------------------------------------------------------------------------------
+    /**
+     * Asynchronously pre-creates one or more render pipelines so they are cached and ready
+     * to use without any compilation hitch when first rendered.
+     *
+     * Call this for effects and meshes that are not yet rendering but will be soon
+     * (e.g. streaming content, predicted material changes, pre-loading the next level).
+     *
+     * When passing an array, cache state is set once per entry and restored only at the end,
+     * making batch pre-warming efficient.
+     *
+     * @param options - a single options object, an array of options objects,
+     *                  or a raw GPURenderPipelineDescriptor for complete control
+     * @returns an array of Promises for the pipelines that had cache misses (empty if all were cached).
+     *          When a raw GPURenderPipelineDescriptor is provided, always returns a single-element array.
+     */
+    // eslint-disable-next-line no-restricted-syntax
+    createRenderPipelineAsync(options) {
+        // Raw GPURenderPipelineDescriptor: bypass the cache and create directly
+        if ("vertex" in options) {
+            return [this._device.createRenderPipelineAsync(options)];
+        }
+        const entries = Array.isArray(options) ? options : [options];
+        const promises = [];
+        const cache = this._cacheRenderPipeline;
+        for (const entry of entries) {
+            // Render target formats
+            cache.setColorFormat(entry.colorFormat ?? this._colorFormat);
+            cache.setDepthStencilFormat(entry.depthStencilFormat ?? this._depthTextureFormat);
+            // Vertex / index buffers from mesh
+            const geometry = entry.mesh.geometry;
+            if (!geometry) {
+                throw new Error("WebGPUEngine.createRenderPipelineAsync: mesh has no geometry to derive vertex/index buffers from.");
+            }
+            cache.setBuffers(geometry.getVertexBuffers(), geometry.getIndexBuffer(), null);
+            // Alpha / blend state
+            const alphaMode = entry.alphaMode ?? 0;
+            if (alphaMode === 0) {
+                cache.setAlphaBlendEnabled([false], 0);
+            }
+            else {
+                const prevAlphaMode = this._alphaMode[0];
+                this.setAlphaMode(alphaMode);
+                cache.setAlphaBlendEnabled(this._alphaState._alphaBlend, this._alphaState._numTargetEnabled);
+                cache.setAlphaBlendFactors(this._alphaState._blendFunctionParameters, this._alphaState._blendEquationParameters);
+                this.setAlphaMode(prevAlphaMode);
+            }
+            // Depth / stencil state
+            cache.setDepthWriteEnabled(entry.depthWrite ?? true);
+            cache.setDepthTestEnabled(entry.depthTest ?? true);
+            cache.setDepthCompare(entry.depthCompare ?? 515);
+            // Rasterization state
+            cache.setCullEnabled(entry.cullEnabled ?? true);
+            cache.setCullFace(entry.cullFace ?? 1);
+            cache.setFrontFace(entry.frontFace ?? 2);
+            // Write mask
+            cache.setWriteMask(entry.writeMask ?? 0xf);
+            // Stencil
+            cache.setStencilEnabled(entry.stencilEnabled ?? false);
+            const fillMode = entry.fillMode ?? 0;
+            const sampleCount = entry.sampleCount ?? this.currentSampleCount;
+            const promise = cache.preWarmPipeline(fillMode, entry.effect, sampleCount, 0);
+            if (promise) {
+                promises.push(promise);
+            }
+        }
+        // Restore the cache state to the engine's current tracked state once after the entire batch
+        cache.setColorFormat(this._colorFormat);
+        cache.setDepthStencilFormat(this._depthTextureFormat);
+        cache.setBuffers(this._currentVertexBuffers ?? null, this._currentIndexBuffer, this._currentOverrideVertexBuffers ?? null);
+        cache.setDepthCullingState(this._depthCullingState.cull ?? false, this._depthCullingState.frontFace ?? 2, this._depthCullingState.cullFace ?? 1, this._depthCullingState.zOffset, this._depthCullingState.zOffsetUnits, this._depthCullingState.depthTest ?? true, this._depthCullingState.depthMask ?? true, this._depthCullingState.depthFunc);
+        cache.setAlphaBlendEnabled(this._alphaState._alphaBlend, this._alphaState._numTargetEnabled);
+        cache.setAlphaBlendFactors(this._alphaState._blendFunctionParameters, this._alphaState._blendEquationParameters);
+        cache.setStencilEnabled(this._stencilStateComposer.enabled ?? false);
+        cache.setWriteMask(this._colorWrite ? 0xf : 0);
+        return promises;
+    }
+    //------------------------------------------------------------------------------
     //                              Dispose
     //------------------------------------------------------------------------------
     /**