Crate gvox_rs

Expand description

§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();
    gvox_ctx.register_adapter::<gvox_rs::Parse, procedural_parse::Procedural>();
    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,
        vertical: false,
    };
    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(PALETTE_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 output 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 gvox palette parse 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 colored text serialize adapter.")
        .create_adapter_context(s_config)
        .expect("Failed to create adapter context.");
    gvox_rs::blit_region(
        Some(&mut i_ctx),
        Some(&mut o_ctx),
        &mut p_ctx,
        &mut s_ctx,
        None, // Parse whole file!
        gvox_rs::ChannelId::COLOR
            | gvox_rs::ChannelId::NORMAL
            | gvox_rs::ChannelId::MATERIAL_ID,
    )
    .expect("Error while translating.");
}
assert_eq!(
    33342,
    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)

Modules§

adapters: The set of default adapters that come built-in.

Structs§

Adapter: Acts as an abstract interface over the ability to read, write, parse, and serialize voxel data.
AdapterContext: One specific instance of a configured adapter that can be used to perform blitting operations.
ChannelFlags: A set of binary flags which denotes a collection of channel IDs.
ChannelId: Identifies a specific property associated with a voxel volume.
Context: Stores the capabilities, information, and state about a set of voxel blitting operations. Adapters can be created or obtained from contexts.
Extent3D: Represents the dimensions of a volume on a 3D grid.
ExternalHandler: Marks types that which have blit callbacks handled externally.
GvoxError: Describes an error that occurred during voxel conversion operations.
Input: Marks types that read voxel input data.
InputBlitContext: Provides the ability for an input adapter to interact with other adapters during blit operations.
Offset3D: Represents an offset on a 3D grid.
Output: Marks types that write voxel output data.
OutputBlitContext: Provides the ability for an output adapter to interact with other adapters during blit operations.
Parse: Marks types that decode voxel data from a provided input stream.
ParseAdapterDetails: Describes basic info about a parse adapter
ParseBlitContext: Provides the ability for a parse adapter to interact with other adapters during blit operations.
Region: Stores data about the loaded state of a provided region of voxels.
RegionFlags: Describes the group properties of a voxel region.
RegionRange: Represents a volume on a 3D grid.
RegionRef: Describes a region of voxels and provides the ability to sample from it.
Sample: Describes a sample that is supplied by the parse adapter.
Serialize: Marks types that encode voxel data from a provided parser.
SerializeBlitContext: Provides the ability for a serialize adapter to interact with other adapters during blit operations.
Version

Enums§

BlitMode: Describes the blit mode of voxel conversion operations.
ErrorType: Describes the type of error that occurred during voxel conversion operations.

Traits§

AdapterDescriptor: Describes the layout of an adapter and its configuration type.
AdapterKind: Describes the purpose of a particular adapter.
BaseAdapterHandler: Represents the user data type that handles adapter context operations.
InputAdapterHandler: Represents the user data type that handles input adapter context operations.
NamedAdapter: Represents an adapter which may be queried by name from a context.
OutputAdapterHandler: Represents the user data type that handles output adapter context operations.
ParseAdapterHandler: Represents the user data type that handles parse adapter context operations.
SerializeAdapterHandler: Represents the user data type that handles serialize adapter context operations.

Functions§

blit_region: Copies a range of voxel data from the specified input to the specified output, parsing and then serializing the data using the provided format adapters.
blit_region_parse_driven: Does the same as blit_region, but explicitly sets the blit mode to prefer parse-driven
blit_region_serialize_driven: Does the same as blit_region, but explicitly sets the blit mode to prefer serialize-driven
get_version

Crate gvox_rsCopy item path