gvox-rs

Safe, high-level Rust API for the GVOX voxel data library

This library supplies an idiomatic Rust abstraction over the GVOX C API. It provides type safety, memory safety, and thread safety without any significant deviation from the C library's design. For more information on the API's design, see the GVOX Wiki.

Below is a simple example which demonstrates how to create adapter contexts and utilize them to convert a .gvox file to colored text console output. For additional examples, see the tests in src/tests.rs.

const BYTES: &[u8] = include_bytes!("palette.gvox");
let mut o_buffer = Box::default();

{
    let gvox_ctx = gvox_rs::Context::new();

    let o_config = gvox_rs::adapters::ByteBufferOutputAdapterConfig::from(&mut o_buffer);

    let s_config = gvox_rs::adapters::ColoredTextSerializeAdapterConfig {
        downscale_factor: 1,
        downscale_mode: gvox_rs::adapters::ColoredTextSerializeAdapterDownscaleMode::Nearest,
        non_color_max_value: 5,
    };

    let mut i_ctx = gvox_ctx.get_adapter::<gvox_rs::Input, gvox_rs::adapters::ByteBuffer>()
        .expect("Failed to get byte buffer input adapter.").create_adapter_context(BYTES)
        .expect("Failed to create adapter context.");

    let mut o_ctx = gvox_ctx.get_adapter::<gvox_rs::Output, gvox_rs::adapters::ByteBuffer>()
        .expect("Failed to get byte buffer input adapter.").create_adapter_context(o_config)
        .expect("Failed to create adapter context.");
    
    let mut p_ctx = gvox_ctx.get_adapter::<gvox_rs::Parse, gvox_rs::adapters::GvoxPalette>()
        .expect("Failed to get byte buffer input adapter.").create_adapter_context(())
        .expect("Failed to create adapter context.");

    let mut s_ctx = gvox_ctx.get_adapter::<gvox_rs::Serialize, gvox_rs::adapters::ColoredText>()
        .expect("Failed to get byte buffer input adapter.").create_adapter_context(s_config)
        .expect("Failed to create adapter context.");

    let region = gvox_rs::RegionRange {
        offset: gvox_rs::Offset3D {
            x: -4,
            y: -4,
            z: -4,
        },
        extent: gvox_rs::Extent3D { x: 8, y: 8, z: 8 },
    };

    gvox_rs::blit_region(
        &mut i_ctx,
        &mut o_ctx,
        &mut p_ctx,
        &mut s_ctx,
        &region,
        gvox_rs::ChannelId::COLOR | gvox_rs::ChannelId::NORMAL | gvox_rs::ChannelId::MATERIAL_ID,
    ).expect("Error while translating.");
}

assert_eq!(22228, o_buffer.len(), "Buffer output length did not match expected.");
println!("{}", std::str::from_utf8(&o_buffer).expect("Bad string slice."));

Building

For now, you must have the following things installed to build the repository.

• A C++ compiler
• CMake (3.21 or higher)
• Ninja build
• vcpkg (plus the VCPKG_ROOT environment variable)
• The latest WASI_SDK (if you are building for WASM) These are necessary because the gvox-rs library is built on the gvox-sys library (subfolder), which is generated via bindgen in order to create language bindings to the C API of Gvox. See the Gvox README for more info!