#include <stdint.h>
#include <stdio.h>

Typedefs
typedef struct VxfFile	VxfFile
	Opaque struct representing an opened MagicaVoxel vox file.

Enumerations
enum	VxfError { VXF_SUCCESS = 0 , VXF_ERROR_FILE_OPEN = 1 , VXF_ERROR_FILE_READ = 2 , VXF_ERROR_FILE_SEEK = 3 , VXF_ERROR_UNRECOGNIZED_FILE_FORMAT = 4 , VXF_ERROR_UNEXPECTED_EOF = 5 , VXF_ERROR_INVALID_FILE_STRUCTURE = 6 , VXF_ERROR_INVALID_SCENE = 7 , VXF_ERROR_OUT_OF_MEMORY = 8 , VXF_ERROR_INVALID_ARGUMENT = 9 }
	Error codes for open and read functions. More...

Functions
VxfFile *	vxf_open_file (const char filename, VxfError error)
	Opens a MagicaVoxel vox file from a filename.

VxfFile *	vxf_open_stream (FILE stream, VxfError error)
	Opens a MagicaVoxel vox file from a stdio file stream.

VxfFile *	vxf_open_memory (size_t size, const char buffer[], VxfError *error)
	Opens a MagicaVoxel vox file from a memory buffer.

void	vxf_calculate_bounds (const VxfFile *vf, int32_t xyz_min[3], int32_t xyz_max[3])
	Calculates the bounding box of the voxel data.

uintmax_t	vxf_count_voxels (const VxfFile *vf)
	Counts the total number of voxels in the file.

void	vxf_get_palette (const VxfFile *vf, uint8_t rgba_buf[256][4])
	Retrieves the color palette.

size_t	vxf_read_xyz_rgba (VxfFile vf, size_t max_count, int32_t xyz_buf[][3], uint8_t rgba_buf[][4], VxfError error)
	Reads voxel positions and RGBA colors.

size_t	vxf_read_xyz_coloridx (VxfFile vf, size_t max_count, int32_t xyz_buf[][3], uint8_t coloridx_buf[], VxfError error)
	Reads voxel positions and color indices.

void	vxf_close (VxfFile *vf)
	Destroys a VxfFile instance.

const char *	vxf_error_string (VxfError error)
	Converts an error code to a human-readable string.

Typedef Documentation

◆ VxfFile

typedef struct VxfFile VxfFile

Opaque struct representing an opened MagicaVoxel vox file.

Allocated by vxf_open_file, vxf_open_stream or vxf_open_memory. Has to be freed by calling vxf_close.

Enumeration Type Documentation

◆ VxfError

enum VxfError

Error codes for open and read functions.

Enumerator
VXF_SUCCESS	Operation successful.
VXF_ERROR_FILE_OPEN	Failed to open input file.
VXF_ERROR_FILE_READ	Failed to read from input stream.
VXF_ERROR_FILE_SEEK	Input stream is not seekable.
VXF_ERROR_UNRECOGNIZED_FILE_FORMAT	Unrecognized file format.
VXF_ERROR_UNEXPECTED_EOF	Unexpected end of input.
VXF_ERROR_INVALID_FILE_STRUCTURE	Invalid vox file structure.
VXF_ERROR_INVALID_SCENE	Invalid scene graph.
VXF_ERROR_OUT_OF_MEMORY	Out of memory or size overflow.
VXF_ERROR_INVALID_ARGUMENT	Invalid argument provided.

Function Documentation

◆ vxf_calculate_bounds()

void vxf_calculate_bounds	(	const VxfFile *	vf,
		int32_t	xyz_min[3],
		int32_t	xyz_max[3]
	)

Calculates the bounding box of the voxel data.

Calculate minimum and maximum values of voxel coordinates based in the model sizes and transforms of the vox scene.

Parameters

[in]	vf	VxfFile instance.
[out]	xyz_min	Minimum x, y, z coordinates of the bounding box.
[out]	xyz_max	Maximum x, y, z coordinates of the bounding box.

◆ vxf_close()

void vxf_close ( VxfFile * vf )

Destroys a VxfFile instance.

If the instance was created via vxf_open_file, the file is closed. If the instance was created via vxf_open_file, the passed stream is not closed.

Parameters

[in] vf VxfFile instance.

◆ vxf_count_voxels()

uintmax_t vxf_count_voxels ( const VxfFile * vf )

Counts the total number of voxels in the file.

The result should be equal to the number of voxels returned by repeated calls to the vxf_read_xyz_rgba and vxf_read_xyz_coloridx functions.*

Parameters

[in] vf VxfFile instance.

Returns: Total number of voxels.

◆ vxf_error_string()

const char * vxf_error_string ( VxfError error )

Converts an error code to a human-readable string.

Parameters

[in] error Error code to convert.

Returns: Static string describing the error.

◆ vxf_get_palette()

void vxf_get_palette	(	const VxfFile *	vf,
		uint8_t	rgba_buf[256][4]
	)

Retrieves the color palette.

If the vox file does not contain a palette (RGBA) chunk, the default palette is returned. The actual palette entries start at index 1 like in MagicaVoxel; color 0 is always set to {0,0,0,0}.

Parameters

[in]	vf	VxfFile instance, or NULL to return the default palette.
[out]	rgba_buf	Buffer to store 256 RGBA color entries (256 * 4 bytes).

◆ vxf_open_file()

VxfFile * vxf_open_file	(	const char *	filename,
		VxfError *	error
	)

Opens a MagicaVoxel vox file from a filename.

The file must be seekable and will be kept open until vxf_close is called.

Parameters

[in]	filename	Path to the vox file.
[out]	error	Where to store the error code. May be NULL.

Returns: Pointer to a new VxfFile instance on success, NULL on failure.

◆ vxf_open_memory()

VxfFile * vxf_open_memory	(	size_t	size,
		const char	buffer[],
		VxfError *	error
	)

Opens a MagicaVoxel vox file from a memory buffer.

The buffer must remain accessible until vxf_close is called.

Parameters

[in]	size	Size of the buffer.
[in]	buffer	Memory buffer containing vox file data.
[out]	error	Where to store the error code. May be NULL.

Returns: Pointer to a new VxfFile instance on success, NULL on failure.

◆ vxf_open_stream()

VxfFile * vxf_open_stream	(	FILE *	stream,
		VxfError *	error
	)

Opens a MagicaVoxel vox file from a stdio file stream.

The stream must be a seekable binary stream (e.g. openend with fopen(..., "rb")), ist must remain open and must ust be used from outside the library until vxf_close is called.

Parameters

[in]	stream	Stream to read from.
[out]	error	Where to store the error code. May be NULL.

Returns: Pointer to a new VxfFile instance on success, NULL on failure.

◆ vxf_read_xyz_coloridx()

size_t vxf_read_xyz_coloridx	(	VxfFile *	vf,
		size_t	max_count,
		int32_t	xyz_buf[][3],
		uint8_t	coloridx_buf[],
		VxfError *	error
	)

Reads voxel positions and color indices.

Like vxf_read_xyz_rgba, but instead of directly returning the RGBA colors, returns the palette color index for each voxelof each voxel's color. The color indices are valid indices for the palette returned by vxf_get_palette. Color indices should usually be in the 1 to 255 range, but might be 0 values can theoretically be stored.

Parameters

[in]	vf	VxfFile instance.
[in]	max_count	Maximum number of voxels to read.
[out]	xyz_buf	Buffer for voxel x, y, z coordinates.
[out]	coloridx_buf	Buffer for voxel color indices.
[out]	error	Where to store the error code. May be NULL.

Returns: Number of voxels read into the buffers, which can be less than max_count or 0 if the end of the list of available voxels has been reached; 0 if an error has occurred.

◆ vxf_read_xyz_rgba()

size_t vxf_read_xyz_rgba	(	VxfFile *	vf,
		size_t	max_count,
		int32_t	xyz_buf[][3],
		uint8_t	rgba_buf[][4],
		VxfError *	error
	)

Reads voxel positions and RGBA colors.

Can be called repeatedly to read all the voxels of the vox scene, i.e. voxels from all model instances of the scene. The returned coordinates are in the global coordinate system. Model instances that are hidden or assigned to hidden layers are not returned. The same Voxels may be returned multiple times with possibly different coordinates if there are multiple instances of a model in the scene.

The passed buffers must be large enough for max_count voxels.

Parameters

[in]	vf	VxfFile instance.
[in]	max_count	Maximum number of voxels to read.
[out]	xyz_buf	Buffer for voxel x, y, z coordinates.
[out]	rgba_buf	Buffer for voxel RGBA colors.
[out]	error	Where to store the error code. May be NULL.

Returns: Number of voxels read into the buffers, which can be less than max_count or 0 if the end of the list of available voxels has been reached; 0 if an error has occurred.

Typedefs

Enumerations

Functions

Typedef Documentation

◆ VxfFile

Enumeration Type Documentation

◆ VxfError

Function Documentation

◆ vxf_calculate_bounds()

◆ vxf_close()

◆ vxf_count_voxels()

◆ vxf_error_string()

◆ vxf_get_palette()

◆ vxf_open_file()

◆ vxf_open_memory()

◆ vxf_open_stream()

◆ vxf_read_xyz_coloridx()

◆ vxf_read_xyz_rgba()