@babylonjs/core 9.12.1 → 9.13.0

package/Collisions/gpuPicker.d.ts

@@ -1,6 +1,7 @@
 import { ShaderLanguage } from "../Materials/shaderLanguage.js";
 import { ShaderMaterial } from "../Materials/shaderMaterial.pure.js";
 import { type IVector2Like } from "../Maths/math.like.js";
+import { Vector3 } from "../Maths/math.vector.pure.js";
 import { type AbstractMesh } from "../Meshes/abstractMesh.js";
 import { type Nullable } from "../types.js";
 /**
@@ -15,9 +16,23 @@ export interface IGPUPickingInfo {
      * Picked thin instance index
      */
     thinInstanceIndex?: number;
+    /**
+     * Picked point in world space.
+     *
+     * Only available when enableDepthPicking is true and a valid depth value can be read.
+     * Custom picking materials or special material plugins that do not write the depth attachment may return undefined.
+     */
+    pickedPoint?: Vector3;
+    /**
+     * Reconstructed normal in world space.
+     *
+     * Only available when enableDepthPicking is true and enough valid depth neighbors can be read.
+     * Custom picking materials or special material plugins that do not write the depth attachment may return undefined.
+     */
+    normal?: Vector3;
 }
 /**
- * Stores the result of a multi GPU piciking operation
+ * Stores the result of a multi GPU picking operation
  */
 export interface IGPUMultiPickingInfo {
     /**
@@ -28,14 +43,74 @@ export interface IGPUMultiPickingInfo {
      * Picked thin instance index
      */
     thinInstanceIndexes?: number[];
+    /**
+     * Picked points in world space.
+     *
+     * Only available when enableDepthPicking is true and a valid depth value can be read.
+     * Custom picking materials or special material plugins that do not write the depth attachment may return null.
+     */
+    pickedPoints?: Nullable<Vector3>[];
+    /**
+     * Reconstructed normals in world space.
+     *
+     * Only available when enableDepthPicking is true and enough valid depth neighbors can be read.
+     * Custom picking materials or special material plugins that do not write the depth attachment may return null.
+     */
+    normals?: Nullable<Vector3>[];
+}
+/**
+ * Defines how multi pick texture readbacks should be performed.
+ */
+export declare enum GPUMultiPickReadbackStrategy {
+    /**
+     * Chooses between a single rectangle readback and small per-point readbacks using the thresholds in IGPUMultiPickOptions.
+     */
+    Auto = 0,
+    /**
+     * Always reads the full bounding rectangle of the picked points. This minimizes readback calls and is best for dense point sets.
+     */
+    Rectangle = 1,
+    /**
+     * Always reads each picked point independently. This minimizes transferred pixels for sparse point sets but can be slower when many points are picked.
+     */
+    Individual = 2
+}
+/**
+ * Options used to tune multi GPU picking.
+ */
+export interface IGPUMultiPickOptions {
+    /**
+     * Defines how multi pick texture readbacks should be performed.
+     *
+     * Defaults to GPUMultiPickReadbackStrategy.Auto.
+     */
+    readbackStrategy?: GPUMultiPickReadbackStrategy;
+    /**
+     * Maximum number of in-bounds points allowed for the automatic individual readback path.
+     * This value is ignored when readbackStrategy is set to GPUMultiPickReadbackStrategy.Rectangle or GPUMultiPickReadbackStrategy.Individual.
+     *
+     * Defaults to 32.
+     */
+    maxIndividualReadbackCount?: number;
+    /**
+     * Minimum rectangle-area / individual-area ratio required before the automatic path uses individual readbacks.
+     * This value is ignored when readbackStrategy is set to GPUMultiPickReadbackStrategy.Rectangle or GPUMultiPickReadbackStrategy.Individual.
+     *
+     * Defaults to 16.
+     */
+    individualReadbackAreaRatio?: number;
 }
 /**
  * Class used to perform a picking operation using GPU
- * GPUPIcker can pick meshes, instances and thin instances
+ * GPUPicker can pick meshes, instances and thin instances
  */
 export declare class GPUPicker {
     private static readonly _AttributeName;
     private static readonly _MaxPickingId;
+    private static readonly _DepthPixelRadius;
+    private static readonly _MaxMultiPickIndividualReadbackCount;
+    private static readonly _MultiPickIndividualReadbackAreaRatio;
+    private static readonly _DepthNeighborOffsets;
     private _pickingTexture;
     private readonly _idMap;
     private readonly _thinIdMap;
@@ -47,10 +122,16 @@ export declare class GPUPicker {
     private _pickableMeshes;
     private readonly _meshMaterialMap;
     private _readbuffer;
+    private _depthReadbuffer;
+    private _depthTextureType;
+    private _isDepthTexturePacked;
+    private _useDepthPicking;
+    private _isUsingDepthPickingRenderTarget;
     private _meshRenderingCount;
     private _renderWarningIssued;
     private _renderPickingTexture;
     private _sceneBeforeRenderObserver;
+    private _pickingTextureClearObserver;
     private _pickingTextureAfterRenderObserver;
     private _nextFreeId;
     private readonly _gsPickingMaterials;
@@ -72,7 +153,22 @@ export declare class GPUPicker {
      * index is Material filling mode
      */
     get defaultRenderMaterials(): readonly Nullable<ShaderMaterial>[];
+    /**
+     * Gets or sets a boolean indicating if depth-based pickedPoint and normal reconstruction should be enabled.
+     *
+     * When disabled, GPUPicker uses the original single-color render target and shader path. When enabled, GPUPicker
+     * switches to a MultiRenderTarget and compiles the default picking shader with GPUPICKER_DEPTH to output both the
+     * picking id and the depth required to reconstruct the picked point and normal.
+     *
+     * Custom picking materials and special picking material plugins should also write the depth attachment. If they do
+     * not, GPUPicker will still try to reconstruct pickedPoint and normal from the depth target, but the returned values
+     * may be missing or incorrect.
+     */
+    get enableDepthPicking(): boolean;
+    set enableDepthPicking(value: boolean);
     private _getColorIdFromReadBuffer;
+    private _getReadBufferOffset;
+    private _createColorPickingRenderTarget;
     private _createRenderTarget;
     private _clearPickingMaterials;
     private _getPickingMaterial;
@@ -111,9 +207,10 @@ export declare class GPUPicker {
      * Execute a picking operation on multiple coordinates
      * @param xy defines the X,Y coordinates where to run the pick
      * @param disposeWhenDone defines a boolean indicating we do not want to keep resources alive (false by default)
+     * @param options defines options used to tune the multi pick readback strategy
      * @returns A promise with the picking results. Always returns an array with the same length as the number of coordinates. The mesh or null at the index where no mesh was picked.
      */
-    multiPickAsync(xy: IVector2Like[], disposeWhenDone?: boolean): Promise<Nullable<IGPUMultiPickingInfo>>;
+    multiPickAsync(xy: IVector2Like[], disposeWhenDone?: boolean, options?: IGPUMultiPickOptions): Promise<Nullable<IGPUMultiPickingInfo>>;
     /**
      * Execute a picking operation on box defined by two screen coordinates
      * @param x1 defines the X coordinate of the first corner of the box where to run the pick
@@ -121,12 +218,16 @@ export declare class GPUPicker {
      * @param x2 defines the X coordinate of the opposite corner of the box where to run the pick
      * @param y2 defines the Y coordinate of the opposite corner of the box where to run the pick
      * @param disposeWhenDone defines a boolean indicating we do not want to keep resources alive (false by default)
-     * @returns A promise with the picking results. Always returns an array with the same length as the number of coordinates. The mesh or null at the index where no mesh was picked.
+     * @returns A promise with the picking results. Contains one entry for each picked pixel in the box.
      */
     boxPickAsync(x1: number, y1: number, x2: number, y2: number, disposeWhenDone?: boolean): Promise<Nullable<IGPUMultiPickingInfo>>;
     private _getRenderInfo;
     private _prepareForPicking;
+    private _getPickingRenderRegion;
+    private _shouldUseIndividualMultiPickReadback;
     private _preparePickingBuffer;
+    private _addPickingTextureToRenderTargets;
+    private _removePickingTextureFromRenderTargets;
     private _executePickingAsync;
     private _executeMultiPickingAsync;
     private _executeBoxPickingAsync;
@@ -149,6 +250,7 @@ export declare class GPUPicker {
      */
     private _waitForPickingMaterialsReadyAsync;
     private _getMeshFromMultiplePoints;
+    private _getMeshFromReadBuffer;
     /**
      * Updates the render list with the current pickable meshes.
      */
@@ -163,6 +265,11 @@ export declare class GPUPicker {
      */
     private _createGaussianSplattingPickingMaterial;
     private _readTexturePixelsAsync;
+    private _readDepthTexturePixelsAsync;
+    private _getDepthPickingInfoAsync;
+    private _getDepthPickingInfoFromBuffer;
+    private _getDepthPointFromBufferToRef;
+    private _getDepthFromBuffer;
     /** Release the resources */
     dispose(): void;
 }