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 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:¶
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 ChannelMask:
- CHANNEL_TYPE_BIT = 1 --- Bitmask with one bit set at the position corresponding to CHANNEL_TYPE.
- CHANNEL_SDF_BIT = 2 --- Bitmask with one bit set at the position corresponding to CHANNEL_SDF.
- CHANNEL_COLOR_BIT = 4 --- Bitmask with one bit set at the position corresponding to CHANNEL_COLOR.
- CHANNEL_INDICES_BIT = 8 --- Bitmask with one bit set at the position corresponding to CHANNEL_INDICES.
- CHANNEL_WEIGHTS_BIT = 16 --- Bitmask with one bit set at the position corresponding to CHANNEL_WEIGHTS.
- CHANNEL_DATA5_BIT = 32 --- Bitmask with one bit set at the position corresponding to CHANNEL_DATA5.
- CHANNEL_DATA6_BIT = 64 --- Bitmask with one bit set at the position corresponding to CHANNEL_DATA6.
- CHANNEL_DATA7_BIT = 128 --- Bitmask with one bit set at the position corresponding to CHANNEL_DATA7.
- ALL_CHANNELS_MASK = 255 --- Bitmask with all channel bits set.
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 --- Uses Godot's default memory allocator (at time of writing, it is
malloc). Preferred for occasional buffers with uncommon size, or very large size. - ALLOCATOR_POOL = 1 --- Uses a pool allocator. Can be faster than the default allocator buffers are created very frequently with similar size. This memory will remain allocated after use, under the assumption that other buffers will need it soon after. Does not support very large buffers (greater than 2 megabytes)
- ALLOCATOR_COUNT = 2
Constants:¶
- MAX_SIZE = 65535 --- Maximum size a buffer can have when serialized. Buffers that contain uniform-compressed voxels can reach it, but in practice, the limit is much lower and depends on available memory.
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.
ImageTexture3D create_3d_texture_from_sdf_zxy( Format output_format )¶
Creates a 3D texture from the SDF channel.
If output_format is a 8-bit pixel format, the texture will contain normalized signed distances, where 0.5 is the isolevel, 0 is the furthest away under surface, and 1 is the furthest away above surface.
Only 16-bit SDF channel is supported.
Only Image.FORMAT_R8 and Image.FORMAT_L8 output formats are suported.
Note: when sampling this texture in a shader, you need to swizzle 3D coordinates with .yxz. This is how voxels are internally stored, and this function does not change this convention.
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 decompress_channel( int channel )¶
If the given channel is currently compressed, decompresses it so that all voxel values are individually stored in full. This will use more memory.
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.
Allocator get_allocator( )¶
Gets which memory allocator is used by this buffer.
Variant get_block_metadata( )¶
Gets metadata associated to this VoxelBuffer.
PackedByteArray get_channel_as_byte_array( ChannelId channel_index )¶
Gets voxel data from a channel as uncompressed raw bytes. Check Depth for information about the data format.
Note: if the channel is compressed, it will be decompressed on the fly into the returned array. If you want a different behavior in this case, check get_channel_compression before calling this method.
Compression get_channel_compression( int channel )¶
Gets which compression mode the specified channel has.
Depth 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.
int get_voxel_v( Vector3i pos, int channel=0 )¶
Gets the raw value of a voxel within this buffer.
bool is_uniform( int channel )¶
Checks if every voxel within a channel has the same value.
void mirror( Axis axis )¶
Mirrors voxel values along the specified axis.
void op_add_buffer_f( VoxelBuffer other, ChannelId channel )¶
Computes the sum of corresponding voxels between the current buffer and the other buffer, and stores the result in the current buffer. Voxels are interpreted as signed distances (usually the CHANNEL_SDF channel).
void op_max_buffer_f( VoxelBuffer other, ChannelId channel )¶
Computes the maximum of corresponding voxels between the current buffer and the other buffer, and stores the result in the current buffer. Voxels are interpreted as signed distances (usually the CHANNEL_SDF channel).
void op_min_buffer_f( VoxelBuffer other, ChannelId channel )¶
Computes the minimum of corresponding voxels between the current buffer and the other buffer, and stores the result in the current buffer. Voxels are interpreted as signed distances (usually the CHANNEL_SDF channel).
void op_mul_buffer_f( VoxelBuffer other, ChannelId channel )¶
Computes the multiplication of corresponding voxels between the current buffer and the other buffer, and stores the result in the current buffer. Voxels are interpreted as signed distances (usually the CHANNEL_SDF channel).
void op_mul_value_f( float other, ChannelId channel )¶
Multiplies every voxels in the buffer by the given value. Voxels are interpreted as signed distances (usually the CHANNEL_SDF channel).
void op_select_less_src_f_dst_i_values( VoxelBuffer src, ChannelId src_channel, float threshold, int value_if_less, int value_if_more, ChannelId dst_channel )¶
For every voxel in the source buffer, if the value is lower than a threshold, set the corresponding voxel in the current buffer to a specific integer value, or another value otherwise. Voxels in the source buffer are interpreted as signed distances (usually the CHANNEL_SDF channel).
void op_sub_buffer_f( VoxelBuffer other, ChannelId channel )¶
Computes the subtraction of corresponding voxels between the current buffer and the other buffer (current - other), and stores the result in the current buffer. Voxels are interpreted as signed distances (usually the CHANNEL_SDF channel).
void remap_values( int channel, PackedInt32Array map )¶
Remaps integer values in a channel using the passed map lookup table. Each index in map corresponds to an original value, and will be replaced by map[original].
void rotate_90( Axis axis, int turns )¶
Rotates voxel values by 90 degrees along the specified axis. 1 turn is 90 degrees, 2 turns is 180 degrees, 3 turns is 270 degrees (or -90), 4 turns does nothing. Negative turns go in the other direction. This may also rotate the size of the buffer, if it isn't cubic.
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, Depth depth )¶
Changes the bit depth of a given channel. This controls the range of values a channel can hold. See Depth for more information.
void set_channel_from_byte_array( ChannelId channel_index, PackedByteArray data )¶
Overwrites the contents of a channel from raw voxel data. Check Depth for information about the expected data format.
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 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. Passing null will erase 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_voxel_v( int value, Vector3i pos, int channel=0 )¶
(This method has no documentation)
void update_3d_texture_from_sdf_zxy( ImageTexture3D existing_texture )¶
Updates an existing 3D texture from the SDF channel. See create_3d_texture_from_sdf_zxy for more information.
Generated on Jan 26, 2026