godot_voxel/doc/source/api/VoxelBuffer.md

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_DATA3 = 3 --- Free channel. Not used by the engine yet.
• CHANNEL_DATA4 = 4 --- Free channel. Not used by the engine yet.
• 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

• 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( Vector3 min_pos, Vector3 max_pos )

Erases per-voxel metadata within the specified area.

• 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, Vector3 src_min, Vector3 src_max, Vector3 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.

• void copy_voxel_metadata_in_area( VoxelBuffer src_buffer, Vector3 src_min_pos, Vector3 src_max_pos, Vector3 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.

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

Clears the buffer and gives it the specified size.

• void downscale_to( VoxelBuffer dst, Vector3 src_min, Vector3 src_max, Vector3 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, Vector3 min, Vector3 max, int channel=0 )

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

• void fill_f( float value, int channel=0 )

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

• void for_each_voxel_metadata( FuncRef callback )

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

• void for_each_voxel_metadata_in_area( FuncRef callback, Vector3 min_pos, Vector3 max_pos )

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

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

• Vector3 get_size( )

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.

• 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( Vector3 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( )

• 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 enum 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 method 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( Vector3 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, Vector3 pos, int channel=0 )

Generated on Apr 10, 2021