/** * The contents of the `.voxel.json` file splat-transform writes, which describes the voxels of * its `.voxel.bin` file. See {@link VoxelOccupancy}. */ export type VoxelOccupancyMetadata = { /** * - The version of the voxel format. */ version: string; /** * - The size of a voxel, in world units. */ voxelResolution: number; /** * - The number of voxels along each axis of a block of the octree. */ leafSize: number; /** * - The depth of the octree. */ treeDepth: number; /** * - The number of nodes of the octree, a 32 bit word each. */ nodeCount: number; /** * - The number of 32 bit words of the voxel masks of the blocks. */ leafDataCount: number; /** * - The bounds of the voxel grid, in the * space of the voxels. */ gridBounds: { min: number[]; max: number[]; }; }; /** * The solid voxels of a scene, which * [splat-transform](https://github.com/playcanvas/splat-transform) generates from a gaussian splat * in its voxel format: a grid of voxels, each of them either solid or empty, written as a * `.voxel.json` file and a `.voxel.bin` file. A VoxelOccupancy answers queries on the CPU, such as * whether a position is inside a solid voxel, or where a ray hits the first one, for collision * logic such as character controllers to be built on. It also provides the voxels as a texture, * for shaders to query them on the GPU. * * The voxels are kept in the sparse octree they are stored in, which takes a fraction of the * memory of the full grid. The queries take positions in the space of the voxel data, which is the * space of the gaussian splat they were generated from, rotated by 180 degrees around the Z axis. * That is the usual rotation of a splat entity, so a splat entity rotated by it, and not otherwise * transformed, lines up with the voxels. * * The voxels outside of the grid are empty. * * @category Graphics */ export class VoxelOccupancy { /** * Creates a new VoxelOccupancy from the two files splat-transform writes, which load as a json * asset and a binary asset. * * @param {VoxelOccupancyMetadata} metadata - The contents of the `.voxel.json` file. * @param {ArrayBuffer} data - The contents of the `.voxel.bin` file. * @example * const voxels = new VoxelOccupancy(jsonAsset.resource, binaryAsset.resource); * if (voxels.isSolid(entity.getPosition())) { * console.log('inside a wall'); * } */ constructor(metadata: VoxelOccupancyMetadata, data: ArrayBuffer); /** * The octree nodes. * * @type {Uint32Array} * @private */ private _nodes; /** * The voxel masks of the mixed blocks, two 32 bit words for each. * * @type {Uint32Array} * @private */ private _leafData; /** * The depth of the octree, its leaves are the blocks. * * @type {number} * @private */ private _treeDepth; /** * The number of blocks the root of the octree spans along each axis. It can span fewer blocks * than the grid: splat-transform ends the octree at a smaller root when its occupied blocks * all fit in it, and the blocks outside of the root are empty. * * @type {number} * @private */ private _rootSpan; /** @private */ private _voxelSize; /** @private */ private _bounds; /** @private */ private _min; /** @private */ private _gridSize; /** @private */ private _nx; /** @private */ private _ny; /** @private */ private _nz; /** @private */ private _nbx; /** @private */ private _nby; /** @private */ private _nbz; /** * The texture of the voxels, created on request. * * @type {Texture|null} * @private */ private _texture; /** * Frees the texture of the voxels. */ destroy(): void; /** * Gets the size of a voxel, in world units. * * @type {number} */ get voxelSize(): number; /** * Gets the bounds of the grid of voxels. Do not modify it. * * @type {BoundingBox} */ get bounds(): BoundingBox; /** * Gets the number of voxels of the grid along each axis. Do not modify it. * * @type {Vec3} */ get gridSize(): Vec3; /** * Finds the block of voxels at the given block coordinates, which must be inside the grid. The * blocks outside of the root of the octree are empty. * * @param {number} bx - The x coordinate of the block. * @param {number} by - The y coordinate of the block. * @param {number} bz - The z coordinate of the block. * @returns {number} BLOCK_EMPTY, BLOCK_SOLID, or the index of the masks of a mixed block. * @private */ private _findBlock; /** * Reads the masks of a block of 4x4x4 voxels. The voxel at (x, y, z) within the block is bit * `x + y * 4 + z * 16` of the 64 bit mask, of which `out[0]` holds the low 32 bits and * `out[1]` the high 32 bits. A block outside the grid is empty. * * @param {number} bx - The x coordinate of the block, the x coordinate of its voxels divided * by 4. * @param {number} by - The y coordinate of the block. * @param {number} bz - The z coordinate of the block. * @param {Uint32Array|number[]} out - Receives the two masks. * @returns {Uint32Array|number[]} The out array. */ readBlock(bx: number, by: number, bz: number, out: Uint32Array | number[]): Uint32Array | number[]; /** * Tests whether the voxel at the given voxel coordinates is solid, for the queries working on * the grid, such as stepping between neighboring voxels. See {@link isSolid} for positions. * * @param {number} ix - The x coordinate of the voxel. * @param {number} iy - The y coordinate of the voxel. * @param {number} iz - The z coordinate of the voxel. * @returns {boolean} True if the voxel is solid, false if it is empty or outside the grid. */ isVoxelSolid(ix: number, iy: number, iz: number): boolean; /** * Tests whether a position is inside a solid voxel. * * @param {Vec3} position - The position, in the space of the voxels. * @returns {boolean} True if the voxel at the position is solid. * @example * if (voxels.isSolid(position)) { * position.copy(previousPosition); * } */ isSolid(position: Vec3): boolean; /** * Finds the first solid voxel along a ray. A ray starting inside a solid voxel hits it at its * origin. * * @param {Ray} ray - The ray, in the space of the voxels. Its direction must be normalized. * @param {number} [maxDistance] - The distance along the ray to search to. Defaults to * Infinity. * @param {Vec3} [point] - Receives the position where the ray enters the solid voxel. * @param {Vec3} [normal] - Receives the normal of the face of the voxel the ray enters through, * or the reversed direction of the ray when it starts inside the voxel. * @returns {boolean} True if the ray hits a solid voxel. * @example * camera.camera.screenToWorld(x, y, camera.camera.nearClip, ray.origin); * camera.camera.screenToWorld(x, y, camera.camera.farClip, ray.direction); * ray.direction.sub(ray.origin).normalize(); * if (voxels.raycast(ray, 100, hitPoint, hitNormal)) { * marker.setPosition(hitPoint); * } */ raycast(ray: Ray, maxDistance?: number, point?: Vec3, normal?: Vec3): boolean; /** * Gets the texture of the voxels, for shaders to query them. It is a volume texture of the * format {@link PIXELFORMAT_RG32U}, with a texel for each block of 4x4x4 voxels, the size of * {@link gridSize} divided by 4. The red channel of a texel holds the low 32 bits and the green * channel the high 32 bits of the mask of its block, see {@link readBlock}. It is sampled with * nearest filtering, and would usually be read with `textureLoad` in WGSL and `texelFetch` in * GLSL. A shader finds the voxel at a position like this: * * ```wgsl * let voxel = vec3i(floor((position - gridMin) / voxelSize)); * let masks = textureLoad(voxels, voxel >> vec3u(2u), 0).rg; * let bit = u32((voxel.x & 3) | ((voxel.y & 3) << 2) | ((voxel.z & 3) << 4)); * let solid = ((select(masks.x, masks.y, bit >= 32u) >> (bit & 31u)) & 1u) != 0u; * ``` * * ```glsl * ivec3 voxel = ivec3(floor((position - gridMin) / voxelSize)); * uvec2 masks = texelFetch(voxels, voxel >> 2, 0).rg; * int bit = (voxel.x & 3) | ((voxel.y & 3) << 2) | ((voxel.z & 3) << 4); * bool solid = (((bit < 32 ? masks.x : masks.y) >> (bit & 31)) & 1u) != 0u; * ``` * * The voxels outside of the grid are empty, which the shader tests for separately. * * The texture is created on the first call, and is owned by the VoxelOccupancy, which destroys * it in {@link destroy}. It holds no copy of the voxels in CPU memory, as the voxels are * written to it again from the octree when the graphics device is restored after it was lost. * * @param {GraphicsDevice} device - The graphics device. * @returns {Texture} The texture. */ getTexture(device: GraphicsDevice): Texture; /** * Writes the voxels to the texture. The full grid of blocks is only needed for the upload, so * the texture releases it once uploaded. * * @private */ private _uploadTexture; /** * Writes the masks of all blocks of the octree to the full grid of blocks. * * @param {Uint32Array} blocks - The grid of blocks, two 32 bit words for each, ordered by x, * then y, then z. The empty blocks are not written to. * @private */ private _decodeBlocks; } import { BoundingBox } from '../../core/shape/bounding-box.js'; import { Vec3 } from '../../core/math/vec3.js'; import type { Ray } from '../../core/shape/ray.js'; import type { GraphicsDevice } from '../../platform/graphics/graphics-device.js'; import { Texture } from '../../platform/graphics/texture.js';