VoxelBuffer

Inherits: Reference

3D grid storing voxel data.

Description:

This contains dense voxels data storage (every single cell holds data, there is no sparse optimization of space). Works like a normal 3D grid containing a voxel value in each cell. Organized in channels of configurable bit depth. Values can be interpreted either as unsigned integers or normalized floats. See enum Depth for more information.

Arbitrary metadata can also be stored, either for the whole buffer, or per-voxel, at higher cost. This metadata can get saved and loaded along voxels, however you must make sure the data is serializable (i.e it should not contain nodes or arbitrary objects).

Methods:

Return Signature
void clear ( )
void clear_voxel_metadata ( )
void clear_voxel_metadata_in_area ( Vector3 min_pos, Vector3 max_pos )
void copy_channel_from ( VoxelBuffer other, int channel )
void copy_channel_from_area ( VoxelBuffer other, Vector3 src_min, Vector3 src_max, Vector3 dst_min, int channel )
void copy_voxel_metadata_in_area ( VoxelBuffer src_buffer, Vector3 src_min_pos, Vector3 src_max_pos, Vector3 dst_min_pos )
void create ( int sx, int sy, int sz )
void downscale_to ( VoxelBuffer dst, Vector3 src_min, Vector3 src_max, Vector3 dst_min ) const
void fill ( int value, int channel=0 )
void fill_area ( int value, Vector3 min, Vector3 max, int channel=0 )
void fill_f ( float value, int channel=0 )
void for_each_voxel_metadata ( FuncRef callback ) const
void for_each_voxel_metadata_in_area ( FuncRef callback, Vector3 min_pos, Vector3 max_pos )
Variant get_block_metadata ( ) const
int get_channel_compression ( int channel ) const
int get_channel_depth ( int channel ) const
Vector3 get_size ( ) const
int get_size_x ( ) const
int get_size_y ( ) const
int get_size_z ( ) const
int get_voxel ( int x, int y, int z, int channel=0 ) const
float get_voxel_f ( int x, int y, int z, int channel=0 ) const
Variant get_voxel_metadata ( Vector3 pos ) const
VoxelTool get_voxel_tool ( )
bool is_uniform ( int channel ) const
void optimize ( )
void set_block_metadata ( Variant meta )
void set_channel_depth ( int channel, int depth )
void set_voxel ( int value, int x, int y, int z, int channel=0 )
void set_voxel_f ( float value, int x, int y, int z, int channel=0 )
void set_voxel_metadata ( Vector3 pos, Variant value )
void set_voxel_v ( int value, Vector3 pos, int channel=0 )

Enumerations:

enum ChannelId:

  • CHANNEL_TYPE = 0 --- Channel used to store voxel types. Used by [VoxelMesherBlocky].
  • CHANNEL_SDF = 1 --- Channel used to store SDF data (signed distance field). Used by [VoxelMesherTransvoxel] and other smooth meshers. Values should preferably be accessed as floats. Negative values are below the isosurface (inside matter), and positive values are above the surface (outside matter).
  • CHANNEL_COLOR = 2 --- Channel used to store color data. Used by [VoxelMesherCubes].
  • CHANNEL_INDICES = 3
  • CHANNEL_WEIGHTS = 4
  • CHANNEL_DATA5 = 5 --- Free channel. Not used by the engine yet.
  • CHANNEL_DATA6 = 6 --- Free channel. Not used by the engine yet.
  • CHANNEL_DATA7 = 7 --- Free channel. Not used by the engine yet.
  • MAX_CHANNELS = 8 --- Maximum number of channels a [VoxelBuffer] can have.

enum Depth:

  • DEPTH_8_BIT = 0 --- Voxels will be stored with 8 bits. Raw values will range from 0 to 255, and float values will be normalized between -1 and 1 (but will still take 255 possible values). Values outside the range will be clamped. If you use this for smooth voxels, you may take care of scaling SDF data with a small number like 0.1 to reduce precision artifacts.
  • DEPTH_16_BIT = 1 --- Voxels will be stored with 16 bits. Raw values will range from 0 to 65,535, and float values will be normalized between -1 and 1 (but will still take 65535 possible values). Values outside the range will be clamped.
  • DEPTH_32_BIT = 2 --- Voxels will be stored with 32 bits. Raw values will range from 0 to 4,294,967,295, and float values will use regular IEEE 754 representation (float).
  • DEPTH_64_BIT = 3 --- Voxels will be stored with 64 bits. Raw values will range from 0 to 18,446,744,073,709,551,615, and float values will use regular IEEE 754 representation (double).
  • DEPTH_COUNT = 4 --- How many depth configuration there are.

enum Compression:

  • COMPRESSION_NONE = 0 --- The channel is not compressed. Every value is stored individually inside an array in memory.
  • COMPRESSION_UNIFORM = 1 --- All voxels of the channel have the same value, so they are stored as one single value, to save space.
  • COMPRESSION_COUNT = 2 --- How many compression modes there are.

Constants:

  • MAX_SIZE = 65535

Method Descriptions

Erases all contents of the buffer and resets its size to zero. Channel depths and default values are preserved.

  • void clear_voxel_metadata( )

Erases all per-voxel metadata.

Erases per-voxel metadata within the specified area.

Copies all values from the channel of another VoxelBuffer into the same channel for the current buffer. The depth formats must match.

Copies values from a channel's sub-region of another VoxelBuffer into the same channel for the current buffer, at a specific location. The depth formats must match.

If corners of the area represent a negative-size area, they will be sorted back.

If coordinates are entirely or partially out of bounds, they will be clipped automatically.

Copying across the same buffer to overlapping areas is not supported. You may use an intermediary buffer in this case.

Copies per-voxel metadata from a sub-region of another VoxelBuffer into the the current buffer, at a specific location. Values will be a shallow copy.

If corners of the area represent a negative-size area, they will be sorted back.

If coordinates are entirely or partially out of bounds, they will be clipped automatically.

Copying across the same buffer to overlapping areas is not supported. You may use an intermediary buffer in this case.

Clears the buffer and gives it the specified size.

Produces a downscaled version of this buffer, by a factor of 2, without any form of interpolation (i.e using nearest-neighbor).

Metadata is not copied.

Fills one channel of this buffer with a specific raw value.

Fills an area of a channel in this buffer with a specific raw value.

Fills one channel of this buffer with a specific float value.

Executes a function on every voxel in this buffer which have associated metadata.

Executes a function on every voxel in this buffer which have associated metadata, within the specified area.

Gets metadata associated to this VoxelBuffer.

  • int get_channel_compression( int channel )

Gets which compression mode the specified channel has.

  • int get_channel_depth( int channel )

Gets which bit depth the specified channel has.

Gets the 3D size of the buffer in voxels.

  • int get_size_x( )

Gets how many voxels the buffer contains across the X axis.

  • int get_size_y( )

Gets how many voxels the buffer contains across the Y axis.

  • int get_size_z( )

Gets how many voxels the buffer contains across the Z axis.

Gets the raw value of a voxel within this buffer.

Gets the float value of a voxel within this buffer. You may use this function if you work with SDF volumes (smooth voxels).

Gets the metadata attached to a specific voxel in this buffer.

Constructs a VoxelTool instance bound to this buffer. This provides access to some extra common functions.

Checks if every voxel within a channel has the same value.

Sets arbitrary data on this buffer. Old data is replaced. Note, this is separate storage from per-voxel metadata.

If this VoxelBuffer is saved, this metadata will also be saved along voxels, so make sure the data supports serialization (i.e you can't put nodes or arbitrary objects in it).

  • void set_channel_depth( int channel, int depth )

Changes the bit depth of a given channel. This controls the range of values a channel can hold. See enum VoxelBuffer.Depth for more information.

Sets the raw value of a voxel. If you use smooth voxels, you may prefer using method set_voxel_f.

Sets the float value of a voxel. This method should be used if you work on SDF data (smooth voxels).

Attaches arbitrary data on a specific voxel. Old data is replaced.

If this VoxelBuffer is saved, this metadata will also be saved along voxels, so make sure the data supports serialization (i.e you can't put nodes or arbitrary objects in it).

Generated on May 31, 2021