@playcanvas/splat-transform/dist/lib/gpu/gpu-voxelization.d.ts

Library and CLI tool for 3D Gaussian splat format conversion and transformation

import { GraphicsDevice } from 'playcanvas';
import { DataTable } from '../data-table';
/**
 * Specification for a single batch in a multi-batch dispatch.
 */
interface BatchSpec {
    /** Offset into the concatenated index array */
    indexOffset: number;
    /** Number of Gaussian indices for this batch */
    indexCount: number;
    /** World-space minimum corner of the first block */
    blockMin: {
        x: number;
        y: number;
        z: number;
    };
    /** Number of blocks in X direction */
    numBlocksX: number;
    /** Number of blocks in Y direction */
    numBlocksY: number;
    /** Number of blocks in Z direction */
    numBlocksZ: number;
}
/**
 * Result of a multi-batch voxelization dispatch.
 */
interface MultiBatchResult {
    /**
     * Raw u32 masks for all batches.
     * For batch i, block j: masks[(i * maxBlocksPerBatch + j) * 2] = low, [+1] = high
     */
    masks: Uint32Array;
    /** Maximum blocks per batch, used for offset calculation */
    maxBlocksPerBatch: number;
}
/**
 * GPU-accelerated voxelization of Gaussian splat data.
 *
 * Uploads all Gaussian data once, then dispatches many batches in a single
 * GPU call using per-batch metadata to minimize CPU-GPU synchronization.
 *
 * Supports double-buffered pipelining via two dispatch slots: the CPU can
 * prepare the next mega-dispatch while the GPU is still executing the current one.
 */
declare class GpuVoxelization {
    private device;
    private shader;
    private bindGroupFormat;
    private gaussianBuffer;
    private slots;
    private totalGaussians;
    /** Floats per Gaussian in the interleaved buffer (16 for alignment) */
    private static readonly FLOATS_PER_GAUSSIAN;
    /** Gaussian rows per CPU staging chunk when uploading to the shared GPU buffer. */
    private static readonly UPLOAD_CHUNK_GAUSSIANS;
    /** Maximum blocks per batch (16^3 = 4096 for 4x4x4 voxel blocks in a 16-block batch) */
    static readonly MAX_BLOCKS_PER_BATCH = 4096;
    /** Number of u32 fields per BatchInfo struct */
    private static readonly BATCH_INFO_U32S;
    /** Number of dispatch slots (for double-buffered pipelining) */
    static readonly NUM_SLOTS = 2;
    /**
     * Create a GPU voxelization instance.
     *
     * @param device - PlayCanvas graphics device (must support WebGPU compute)
     */
    constructor(device: GraphicsDevice);
    /**
     * Upload all Gaussian data to GPU once.
     * Must be called before any dispatch methods.
     *
     * @param dataTable - DataTable containing all Gaussian properties
     * @param extents - DataTable containing pre-computed AABB extents (extent_x, extent_y, extent_z)
     */
    uploadAllGaussians(dataTable: DataTable, extents: DataTable): void;
    /**
     * Ensure a slot's buffer is at least the given size, growing if needed.
     *
     * @param slot - Dispatch slot to check.
     * @param bufferKey - Key of the StorageBuffer property on the slot.
     * @param sizeKey - Key of the corresponding size-tracking property.
     * @param neededSize - Minimum required buffer size in bytes.
     * @param usage - GPU buffer usage flags for the new buffer.
     * @param paramName - Compute parameter name to rebind after replacement.
     */
    private ensureSlotBuffer;
    /**
     * Submit a multi-batch dispatch on the specified slot.
     *
     * Returns a Promise that resolves when GPU results are ready. The caller
     * should NOT await immediately — do CPU work first (BVH queries, index
     * copying for the next dispatch) to overlap CPU and GPU execution.
     *
     * Use different slot indices for consecutive calls to avoid buffer conflicts.
     *
     * @param slotIndex - Which dispatch slot to use (0 or 1)
     * @param concatenatedIndices - Pre-built Uint32Array of all Gaussian indices
     * @param totalIndices - Number of valid indices in the array
     * @param batches - Per-batch metadata (index offset/count, block origin, dimensions)
     * @param voxelResolution - Size of each voxel in world units
     * @param opacityCutoff - Opacity threshold for solid voxels (0.0-1.0)
     * @returns Promise resolving to multi-batch voxelization results
     */
    submitMultiBatch(slotIndex: number, concatenatedIndices: Uint32Array, totalIndices: number, batches: BatchSpec[], voxelResolution: number, opacityCutoff: number): Promise<MultiBatchResult>;
    /**
     * Get the total number of Gaussians uploaded.
     *
     * @returns Total Gaussian count
     */
    get numGaussians(): number;
    /**
     * Destroy GPU resources.
     */
    destroy(): void;
}
export { GpuVoxelization, type BatchSpec, type MultiBatchResult };