VoxelBuffer

Inherits: RefCounted

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, fixed-point or floats. See VoxelBuffer.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 ( Vector3i min_pos, Vector3i max_pos )
void compress_uniform_channels ( )
void copy_channel_from ( VoxelBuffer other, int channel )
void copy_channel_from_area ( VoxelBuffer other, Vector3i src_min, Vector3i src_max, Vector3i dst_min, int channel )
void copy_voxel_metadata_in_area ( VoxelBuffer src_buffer, Vector3i src_min_pos, Vector3i src_max_pos, Vector3i dst_min_pos )
void create ( int sx, int sy, int sz )
Image[] debug_print_sdf_y_slices ( float scale=1.0 ) const
void downscale_to ( VoxelBuffer dst, Vector3i src_min, Vector3i src_max, Vector3i dst_min ) const
void fill ( int value, int channel=0 )
void fill_area ( int value, Vector3i min, Vector3i max, int channel=0 )
void fill_area_f ( float value, Vector3i min, Vector3i max, int channel )
void fill_f ( float value, int channel=0 )
void for_each_voxel_metadata ( Callable callback ) const
void for_each_voxel_metadata_in_area ( Callable callback, Vector3i min_pos, Vector3i max_pos )
int get_allocator ( ) const
Variant get_block_metadata ( ) const
int get_channel_compression ( int channel ) const
int get_channel_depth ( int channel ) const
Vector3i get_size ( ) 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 ( Vector3i pos ) const
VoxelTool get_voxel_tool ( )
bool is_uniform ( int channel ) const
void optimize ( ) (deprecated)
void remap_values ( int channel, PackedInt32Array map )
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 ( Vector3i pos, Variant value )
void set_voxel_v ( int value, Vector3i 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 used to store material indices. Used with smooth voxels.
  • CHANNEL_WEIGHTS = 4 --- Channel used to store material weights, when more than one index can be stored per voxel. Used with smooth voxels.
  • 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. Float values can take 255 values distributed from -10.0 to 10.0. Values outside the range will be clamped.
  • DEPTH_16_BIT = 1 --- Voxels will be stored with 16 bits. Raw values will range from 0 to 65,535. Float values can take 65,535 values distributed from -500.0 to 500.0. 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.

enum Allocator:

  • ALLOCATOR_DEFAULT = 0
  • ALLOCATOR_POOL = 1
  • ALLOCATOR_COUNT = 2

Constants:

  • MAX_SIZE = 65535

Method Descriptions

void clear( )

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.

void clear_voxel_metadata_in_area( Vector3i min_pos, Vector3i max_pos )

Erases per-voxel metadata within the specified area.

void compress_uniform_channels( )

Finds channels that have the same value in all their voxels, and reduces memory usage by storing only one value instead. This is effective for example when large parts of the terrain are filled with air.

void copy_channel_from( VoxelBuffer other, int channel )

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

void copy_channel_from_area( VoxelBuffer other, Vector3i src_min, Vector3i src_max, Vector3i dst_min, int channel )

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.

void copy_voxel_metadata_in_area( VoxelBuffer src_buffer, Vector3i src_min_pos, Vector3i src_max_pos, Vector3i dst_min_pos )

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.

void create( int sx, int sy, int sz )

Clears the buffer and gives it the specified size.

Image[] debug_print_sdf_y_slices( float scale=1.0 )

Renders the contents of the SDF channel into images where blue gradients are negative values (below surface) and yellow gradients are positive (above surface). Each image corresponds to an XZ slice of the buffer.

The scale parameter can be used to change contrast of images by scaling the SDF.

void downscale_to( VoxelBuffer dst, Vector3i src_min, Vector3i src_max, Vector3i dst_min )

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.

void fill( int value, int channel=0 )

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

void fill_area( int value, Vector3i min, Vector3i max, int channel=0 )

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

void fill_area_f( float value, Vector3i min, Vector3i max, int channel )

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

void fill_f( float value, int channel=0 )

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

void for_each_voxel_metadata( Callable callback )

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

The function's arguments must be (position: Vector3i, metadata: Variant).

IMPORTANT: inserting new or removing metadata from inside this function is not allowed.

void for_each_voxel_metadata_in_area( Callable callback, Vector3i min_pos, Vector3i max_pos )

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

IMPORTANT: inserting new or removing metadata from inside this function is not allowed.

int get_allocator( )

(This method has no documentation)

Variant get_block_metadata( )

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.

Vector3i get_size( )

Gets the 3D size of the buffer in voxels.

int get_voxel( int x, int y, int z, int channel=0 )

Gets the raw value of a voxel within this buffer.

float get_voxel_f( int x, int y, int z, int channel=0 )

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

Variant get_voxel_metadata( Vector3i pos )

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

VoxelTool get_voxel_tool( )

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

bool is_uniform( int channel )

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

void optimize( )

This method is deprecated. Use VoxelBuffer.compress_uniform_channels instead.

void remap_values( int channel, PackedInt32Array map )

(This method has no documentation)

void set_block_metadata( Variant meta )

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 VoxelBuffer.Depth for more information.

void set_voxel( int value, int x, int y, int z, int channel=0 )

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

void set_voxel_f( float value, int x, int y, int z, int channel=0 )

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

void set_voxel_metadata( Vector3i pos, Variant value )

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).

void set_voxel_v( int value, Vector3i pos, int channel=0 )

(This method has no documentation)

Generated on Apr 06, 2024