Struct GltfBuilder

pub struct GltfBuilder {
    pub gltf: Gltf,
    pub buffer_data: Vec<u8>,
}

The main builder for creating and exporting glTF models

GltfBuilder provides methods for:

• Creating primitive shapes (box, sphere, plane, etc.)
• Creating and managing materials
• Creating scene hierarchies with nodes
• Managing buffer data for vertex attributes
• Exporting to glTF and GLB formats

Fields

gltf: Gltf

buffer_data: Vec<u8>

Implementations

impl GltfBuilder

pub fn new() -> Self

Create a new glTF builder

pub fn add_scene( &mut self, name: Option<String>, nodes: Option<Vec<usize>>, ) -> usize

Add a scene to the glTF document

pub fn add_node( &mut self, name: Option<String>, mesh: Option<usize>, translation: Option<[f32; 3]>, rotation: Option<[f32; 4]>, scale: Option<[f32; 3]>, ) -> usize

Add a node to the glTF document

pub fn add_node_with_children( &mut self, name: Option<String>, mesh: Option<usize>, translation: Option<[f32; 3]>, rotation: Option<[f32; 4]>, scale: Option<[f32; 3]>, children: Vec<usize>, ) -> usize

Add a node with a list of children to the glTF document

pub fn add_child_to_node( &mut self, parent_index: usize, child_index: usize, ) -> Result<()>

Add a child to an existing node

pub fn create_node_hierarchy( &mut self, parent_name: Option<String>, parent_translation: Option<[f32; 3]>, parent_rotation: Option<[f32; 4]>, parent_scale: Option<[f32; 3]>, child_indices: Vec<usize>, ) -> usize

Create a parent node with multiple child nodes

pub fn add_mesh( &mut self, name: Option<String>, primitives: Vec<Primitive>, ) -> usize

Add a mesh to the glTF document

pub fn add_accessor( &mut self, buffer_view: usize, component_type: usize, count: usize, type_: String, byte_offset: Option<usize>, min: Option<Vec<f32>>, max: Option<Vec<f32>>, ) -> usize

Add an accessor to the glTF document

pub fn add_buffer_view( &mut self, byte_offset: usize, byte_length: usize, target: Option<usize>, ) -> usize

Add a buffer view to the glTF document

pub fn add_buffer_data(&mut self, data: &[u8]) -> (usize, usize)

Add binary data to the buffer and return the byte offset

pub fn export_glb(&self, path: &str) -> Result<()>

Export the glTF as a GLB file

impl GltfBuilder

pub fn create_box(&mut self, size: f32) -> usize

Create a simple cubic box mesh with the specified size

This method creates a cube centered at the origin with equal dimensions on all sides. The cube has properly generated normals and texture coordinates for each face.

Parameters

• size - The length of each side of the cube

Returns

The index of the created mesh in the glTF document’s meshes array

Example

use mesh_tools::GltfBuilder;
let mut builder = GltfBuilder::new();
let box_mesh = builder.create_box(2.0); // Creates a 2x2x2 cube

pub fn create_box_with_material( &mut self, size: f32, material: Option<usize>, ) -> usize

Create a box with the specified material

pub fn create_custom_mesh( &mut self, name: Option<String>, positions: &[Point3<f32>], indices: &[Triangle], normals: Option<Vec<Vector3<f32>>>, texcoords: Option<Vec<Vec<Vector2<f32>>>>, material: Option<usize>, ) -> usize

Create a mesh with custom geometry and UV mapping

Parameters

• name - Optional name for the mesh
• positions - Vertex positions as Vec<Point3>
• indices - List of triangles, each containing three vertex indices
• normals - Optional vertex normals as Vec<Vector3>
• texcoords - Optional array of UV coordinate sets, each as Vec<Vector2>. The first set becomes TEXCOORD_0, the second TEXCOORD_1, etc.
• material - Optional material index to use for the mesh

Returns

The index of the created mesh

pub fn create_simple_mesh( &mut self, name: Option<String>, positions: &[Point3<f32>], indices: &[Triangle], normals: Option<Vec<Vector3<f32>>>, texcoords: Option<Vec<Vector2<f32>>>, material: Option<usize>, ) -> usize

Create a mesh with custom geometry and single UV channel using nalgebra types

Simplified version of create_custom_mesh for the common case of a single UV channel, but using proper 3D math types instead of raw float arrays.

Parameters

• name - Optional name for the mesh
• positions - Vertex positions as &Point3
• indices - List of triangles using the Triangle struct
• normals - Optional vertex normals as Vec<Vector3>
• texcoords - Optional UV coordinates as Vec<Vector2>
• material - Optional material index to use for the mesh

Returns

The index of the created mesh

pub fn create_plane( &mut self, width: f32, depth: f32, width_segments: usize, depth_segments: usize, material: Option<usize>, ) -> usize

Create a flat plane mesh with subdivisions

This method creates a flat rectangular plane on the XZ plane (with Y as up). The plane is centered at the origin and can be subdivided into a grid of triangles. Subdividing the plane is useful for terrain or deformation effects.

Parameters

• width - Width of the plane along X axis
• depth - Depth of the plane along Z axis
• width_segments - Number of subdivisions along width (min: 1)
• depth_segments - Number of subdivisions along depth (min: 1)
• material - Optional material index to use for the mesh

Returns

The index of the created mesh in the glTF document’s meshes array

Example

use mesh_tools::GltfBuilder;
let mut builder = GltfBuilder::new();
 
// Create a material
let ground_material = builder.create_basic_material(
    Some("Ground".to_string()),
    [0.5, 0.5, 0.5, 1.0]
);
 
// Create a 10x10 ground plane with 20x20 grid subdivisions
let ground_mesh = builder.create_plane(10.0, 10.0, 20, 20, Some(ground_material));

pub fn create_sphere( &mut self, radius: f32, width_segments: usize, height_segments: usize, material: Option<usize>, ) -> usize

Create a sphere mesh with specified radius and resolution

This method creates a UV-mapped sphere centered at the origin. The sphere is generated using latitude/longitude segmentation, with vertices distributed evenly around the surface.

Parameters

• radius - Radius of the sphere
• width_segments - Number of horizontal subdivisions (longitude lines, min: 3)
• height_segments - Number of vertical subdivisions (latitude lines, min: 2)
• material - Optional material index to use for the mesh

Returns

The index of the created mesh in the glTF document’s meshes array

Example

use mesh_tools::GltfBuilder;
let mut builder = GltfBuilder::new();
 
// Create a red material
let red_material = builder.create_basic_material(
    Some("Red".to_string()),
    [1.0, 0.0, 0.0, 1.0]
);
 
// Create a high-detail red sphere with radius 2.0
let sphere_mesh = builder.create_sphere(2.0, 32, 16, Some(red_material));

pub fn create_cylinder( &mut self, radius_top: f32, radius_bottom: f32, height: f32, radial_segments: usize, height_segments: usize, open_ended: bool, material: Option<usize>, ) -> usize

Create a cylinder mesh with customizable dimensions

This method creates a cylinder or a truncated cone (when top and bottom radii differ). The cylinder is centered at the origin and extends along the Y axis. The cylinder can be open-ended (without caps) or closed with caps.

Parameters

• radius_top - Radius at the top of the cylinder
• radius_bottom - Radius at the bottom of the cylinder
• height - Height of the cylinder along the Y axis
• radial_segments - Number of subdivisions around the circumference (min: 3)
• height_segments - Number of subdivisions along the height (min: 1)
• open_ended - When true, the cylinder has no top or bottom caps
• material - Optional material index to use for the mesh

Returns

The index of the created mesh in the glTF document’s meshes array

Example

use mesh_tools::GltfBuilder;
let mut builder = GltfBuilder::new();
 
// Create a blue material
let blue_material = builder.create_basic_material(
    Some("Blue".to_string()),
    [0.0, 0.0, 0.8, 1.0]
);
 
// Create a cylinder with different top and bottom radii (truncated cone)
let cylinder_mesh = builder.create_cylinder(
    0.5,   // radius top
    1.0,   // radius bottom
    2.0,   // height
    16,    // radial segments
    1,     // height segments
    false, // closed with caps
    Some(blue_material)
);

pub fn create_cone( &mut self, radius: f32, height: f32, radial_segments: usize, height_segments: usize, open_ended: bool, material: Option<usize>, ) -> usize

Create a cone mesh

Parameters

• radius - Radius at the base of the cone
• height - Height of the cone
• radial_segments - Number of subdivisions around the circumference
• height_segments - Number of subdivisions along the height
• open_ended - Whether to include the base cap
• material - Optional material index to use for the mesh

Returns

The index of the created mesh

pub fn create_torus( &mut self, radius: f32, tube: f32, radial_segments: usize, tubular_segments: usize, material: Option<usize>, ) -> usize

Create a torus (donut shape) mesh

Parameters

• radius - Distance from the center of the tube to the center of the torus
• tube - Radius of the tube
• radial_segments - Number of subdivisions around the main circle
• tubular_segments - Number of subdivisions around the tube
• material - Optional material index to use for the mesh

Returns

The index of the created mesh

pub fn create_icosahedron( &mut self, radius: f32, material: Option<usize>, ) -> usize

Create an icosahedron (20-sided polyhedron) mesh

Parameters

• radius - Radius of the circumscribed sphere
• material - Optional material index to use for the mesh

Returns

The index of the created mesh

impl GltfBuilder

pub fn add_textured_material( &mut self, name: Option<String>, base_color_texture: Option<usize>, metallic_roughness_texture: Option<usize>, normal_texture: Option<usize>, occlusion_texture: Option<usize>, emissive_texture: Option<usize>, emissive_factor: Option<[f32; 3]>, metallic_factor: Option<f32>, roughness_factor: Option<f32>, alpha_mode: Option<String>, alpha_cutoff: Option<f32>, double_sided: Option<bool>, ) -> usize

Add a material with a texture to the glTF document

pub fn create_textured_material( &mut self, name: Option<String>, base_color_texture: usize, ) -> usize

Create a basic textured material

pub fn add_image_from_dynamic_image( &mut self, name: Option<String>, image: &DynamicImage, format: TextureFormat, ) -> Result<usize>

Add an image to the glTF document from a DynamicImage using the specified format

pub fn create_default_sampler(&mut self) -> usize

Create a default texture sampler with reasonable settings

pub fn create_texture_from_image( &mut self, name: Option<String>, image: &DynamicImage, format: TextureFormat, ) -> Result<usize>

Create a default texture from a DynamicImage (uses default sampler)

pub fn create_checkerboard_texture( &mut self, width: u32, height: u32, cell_size: u32, color1: [u8; 3], color2: [u8; 3], ) -> Result<usize>

Create a checkerboard texture (for testing)

pub fn create_uv_test_texture( &mut self, width: u32, height: u32, ) -> Result<usize>

Create a UV test pattern texture (for testing)

pub fn add_sampler( &mut self, mag_filter: Option<usize>, min_filter: Option<usize>, wrap_s: Option<usize>, wrap_t: Option<usize>, ) -> usize

Add a sampler to the glTF document

pub fn add_image_from_buffer( &mut self, name: Option<String>, mime_type: String, data: &[u8], ) -> usize

Add an image to the glTF document

pub fn add_texture( &mut self, name: Option<String>, source: usize, sampler: Option<usize>, ) -> usize

Add a texture to the glTF document

impl GltfBuilder

pub fn add_material( &mut self, name: Option<String>, base_color: Option<[f32; 4]>, metallic_factor: Option<f32>, roughness_factor: Option<f32>, double_sided: Option<bool>, ) -> usize

Add a material to the glTF document

pub fn create_basic_material( &mut self, name: Option<String>, color: [f32; 4], ) -> usize

Create a basic material with the specified color

pub fn create_metallic_material( &mut self, name: Option<String>, color: [f32; 4], metallic: f32, roughness: f32, ) -> usize

Create a metallic material