Home

Welcome to the gvox wiki!

Gvox provides two APIs you may be concerned with, the consumer API and the adapter API

Gvox is a library designed to provide a parsing and serializing interface for various voxel formats. It provides some simple general types you will use in order to interface with both the consumer API and the adapter API, so getting familiar with them now is sensible.

First are the

Integer constants and Enums

GvoxResult

GvoxResult is an enum that can be retrieved consumer-side, and can be emitted from the adapter-side:

typedef enum {
    GVOX_RESULT_SUCCESS = 0,
    GVOX_RESULT_ERROR_UNKNOWN = -1,
    GVOX_RESULT_ERROR_INVALID_PARAMETER = -2,

    GVOX_RESULT_ERROR_INPUT_ADAPTER = -3,
    GVOX_RESULT_ERROR_OUTPUT_ADAPTER = -4,
    GVOX_RESULT_ERROR_PARSE_ADAPTER = -5,
    GVOX_RESULT_ERROR_SERIALIZE_ADAPTER = -6,

    GVOX_RESULT_ERROR_PARSE_ADAPTER_INVALID_INPUT = -7,
    GVOX_RESULT_ERROR_PARSE_ADAPTER_REQUESTED_CHANNEL_NOT_PRESENT = -8,
    GVOX_RESULT_ERROR_SERIALIZE_ADAPTER_UNREPRESENTABLE_DATA = -9,
} GvoxResult;

There are also identifiers to signify channel IDs within voxel structures:

GVOX_CHANNEL_ID

#define GVOX_CHANNEL_ID_COLOR 0
#define GVOX_CHANNEL_ID_NORMAL 1
#define GVOX_CHANNEL_ID_MATERIAL_ID 2
#define GVOX_CHANNEL_ID_ROUGHNESS 3
#define GVOX_CHANNEL_ID_METALNESS 4
#define GVOX_CHANNEL_ID_TRANSPARENCY 5
#define GVOX_CHANNEL_ID_IOR 6
#define GVOX_CHANNEL_ID_EMISSIVITY 7
#define GVOX_CHANNEL_ID_HARDNESS 8
// [9-23] Reserved for future standard IDs
#define GVOX_CHANNEL_ID_LAST_STANDARD 23
// [24-31] Reserved for format-specific data
#define GVOX_CHANNEL_ID_LAST 31

There are only 32 unique channel IDs for the purpose of being able to pack their presence in a single u32. The first 24 are "Standard" channels, so that inter-communication between formats is standardized. The last 8 bits available are reserved for user-defined usage. A potential good use for one/two of these would be a pointer or data offset to coms sort of block-specific data. This means that there can be 32 channels of u32 data, which is 128 bytes of per-voxel data. If your voxels are exceeding the restrictions of a 1024-bit integer, I think you might want to rethink your data - but let me know if you think this could be an issue for you.

Since they're meant to be bit-fielded, there are helper definitions for each channel bit-mask:

GVOX_CHANNEL_BIT

#define GVOX_CHANNEL_BIT_COLOR (1 << GVOX_CHANNEL_ID_COLOR)
#define GVOX_CHANNEL_BIT_NORMAL (1 << GVOX_CHANNEL_ID_NORMAL)
#define GVOX_CHANNEL_BIT_MATERIAL_ID (1 << GVOX_CHANNEL_ID_MATERIAL_ID)
#define GVOX_CHANNEL_BIT_ROUGHNESS (1 << GVOX_CHANNEL_ID_ROUGHNESS)
#define GVOX_CHANNEL_BIT_METALNESS (1 << GVOX_CHANNEL_ID_METALNESS)
#define GVOX_CHANNEL_BIT_TRANSPARENCY (1 << GVOX_CHANNEL_ID_TRANSPARENCY)
#define GVOX_CHANNEL_BIT_IOR (1 << GVOX_CHANNEL_ID_IOR)
#define GVOX_CHANNEL_BIT_EMISSIVITY (1 << GVOX_CHANNEL_ID_EMISSIVITY)
#define GVOX_CHANNEL_BIT_HARDNESS (1 << GVOX_CHANNEL_ID_HARDNESS)
#define GVOX_CHANNEL_BIT_LAST_STANDARD (1 << GVOX_CHANNEL_ID_LAST_STANDARD)
#define GVOX_CHANNEL_BIT_LAST (1 << GVOX_CHANNEL_ID_LAST)

Lastly, there are flags used to describe voxel regions. Currently, there is only 1 flag:

GVOX_REGION_FLAG

#define GVOX_REGION_FLAG_UNIFORM 0x00000001

"Uniform" means that every voxel in that region has the same value within the requested range and channels.

Now let's move on to the

Structs

For now, there are just a couple of common structs to be familiar with.

GvoxOffset3D

GvoxOffset3D is meant to designate a relative offset within a voxel volume. It is most commonly used to designate a voxel-space coordinate relative to the global origin.

typedef struct {
    int32_t x;
    int32_t y;
    int32_t z;
} GvoxOffset3D;

GvoxExtent3D

GvoxExtent3D is more straightforward, in that it's meant to designate the size of a voxel volume.

typedef struct {
    uint32_t x;
    uint32_t y;
    uint32_t z;
} GvoxExtent3D;

GvoxRegionRange

Lastly, we have GvoxRegionRange, which is just the combination of the previous two in order to designate a sub-volume within another volume. This is usually just the global voxel-space volume, which means the offset is usually relative to the global origin.

typedef struct {
    GvoxOffset3D offset;
    GvoxExtent3D extent;
} GvoxRegionRange;