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 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 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 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)

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 customizable PBR material to the glTF document

This function allows you to create a fully customizable PBR (Physically Based Rendering) material with control over base color, metallic factor, roughness factor, and double-sided rendering.

Parameters

• name - Optional name for the material
• base_color - Optional RGBA color array [r, g, b, a] where each component is in range 0.0-1.0
• metallic_factor - Optional metallic property (0.0 = non-metal, 1.0 = metal)
• roughness_factor - Optional roughness property (0.0 = smooth, 1.0 = rough)
• double_sided - Optional flag to enable double-sided rendering

Returns

The index of the created material in the glTF document

Examples

use mesh_tools::GltfBuilder;
 
let mut builder = GltfBuilder::new();
 
// Create a shiny blue metal material
let blue_metal = builder.add_material(
    Some("Blue Metal".to_string()),
    Some([0.1, 0.2, 0.8, 1.0]),  // Blue color
    Some(0.9),                    // Highly metallic
    Some(0.2),                    // Low roughness (shiny)
    Some(false)                   // Single-sided
);
 
// Create a rough plastic material
let red_plastic = builder.add_material(
    Some("Red Plastic".to_string()),
    Some([0.8, 0.1, 0.1, 1.0]),  // Red color
    Some(0.0),                    // Non-metallic
    Some(0.8),                    // High roughness
    Some(true)                    // Double-sided
);
 
// Create a simple material with defaults for some properties
let green_material = builder.add_material(
    Some("Green".to_string()),
    Some([0.1, 0.8, 0.1, 1.0]),  // Green color
    None,                         // Default metallic factor
    None,                         // Default roughness factor
    None                          // Default single-sided
);
 
// Use the material with a mesh
let cube = builder.create_box(1.0, Some(blue_metal));

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

impl GltfBuilder

pub fn add_specular_glossiness_material( &mut self, name: Option<String>, diffuse_factor: Option<[f32; 4]>, diffuse_texture: Option<usize>, specular_factor: Option<[f32; 3]>, glossiness_factor: Option<f32>, specular_glossiness_texture: Option<usize>, normal_texture: Option<usize>, occlusion_texture: Option<usize>, emissive_texture: Option<usize>, emissive_factor: Option<[f32; 3]>, alpha_mode: Option<String>, alpha_cutoff: Option<f32>, double_sided: Option<bool>, ) -> usize

Add a material using the specular-glossiness workflow to the glTF document

This function allows you to create a PBR material using the specular-glossiness workflow as defined in the KHR_materials_pbrSpecularGlossiness extension.

Parameters

• name - Optional name for the material
• diffuse_factor - Optional RGBA diffuse color array [r, g, b, a] where each component is in range 0.0-1.0
• diffuse_texture - Optional index of a texture containing diffuse color values
• specular_factor - Optional RGB specular color array [r, g, b] where each component is in range 0.0-1.0
• glossiness_factor - Optional glossiness value in range 0.0-1.0 (0.0 = rough, 1.0 = smooth)
• specular_glossiness_texture - Optional index of a texture containing specular and glossiness values
• normal_texture - Optional index of a normal map texture
• occlusion_texture - Optional index of an occlusion map texture
• emissive_texture - Optional index of an emissive map texture
• emissive_factor - Optional RGB emissive color array [r, g, b] where each component is in range 0.0-1.0
• alpha_mode - Optional alpha rendering mode (“OPAQUE”, “MASK”, or “BLEND”)
• alpha_cutoff - Optional alpha cutoff value for “MASK” mode
• double_sided - Optional flag to enable double-sided rendering

Returns

The index of the created material in the glTF document

pub fn create_specular_material( &mut self, name: Option<String>, diffuse_color: [f32; 4], specular_color: [f32; 3], glossiness: f32, ) -> usize

Create a simple specular material with the specified diffuse and specular colors

Parameters

• name - Optional name for the material
• diffuse_color - RGBA diffuse color array [r, g, b, a]
• specular_color - RGB specular color array [r, g, b]
• glossiness - Glossiness value between 0.0 (rough) and 1.0 (smooth)

Returns

The index of the created material in the glTF document

impl GltfBuilder

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

Add an animation to the glTF

Arguments

• name - Optional name for the animation

Returns

The index of the created animation

pub fn add_animation_sampler( &mut self, animation_index: usize, input_accessor: usize, output_accessor: usize, interpolation: InterpolationType, ) -> usize

Add a sampler to an animation

Arguments

• animation_index - The index of the animation to add the sampler to
• input_accessor - The accessor containing keyframe timestamps (in seconds)
• output_accessor - The accessor containing output values
• interpolation - The interpolation method

Returns

The index of the created sampler within the animation

pub fn add_animation_channel( &mut self, animation_index: usize, sampler_index: usize, target_node: usize, target_path: AnimationPath, ) -> usize

Add a channel to an animation

Arguments

• animation_index - The index of the animation to add the channel to
• sampler_index - The index of the sampler within the animation
• target_node - The index of the node being animated
• target_path - The property being animated (translation, rotation, scale, weights)

Returns

The index of the created channel within the animation

pub fn create_translation_animation( &mut self, animation_index: usize, node_index: usize, timestamps: Vec<f32>, translations: Vec<[f32; 3]>, interpolation: InterpolationType, ) -> (usize, usize)

Create translation keyframes for an animation

Arguments

• animation_index - The index of the animation
• node_index - The index of the target node
• timestamps - Vector of keyframe timestamps (in seconds)
• translations - Vector of translation values ([x, y, z] for each keyframe)
• interpolation - The interpolation method

Returns

The indices of the created channel and sampler

pub fn create_rotation_animation( &mut self, animation_index: usize, node_index: usize, timestamps: Vec<f32>, rotations: Vec<[f32; 4]>, interpolation: InterpolationType, ) -> (usize, usize)

Create rotation keyframes for an animation

Arguments

• animation_index - The index of the animation
• node_index - The index of the target node
• timestamps - Vector of keyframe timestamps (in seconds)
• rotations - Vector of rotation quaternions ([x, y, z, w] for each keyframe)
• interpolation - The interpolation method

Returns

The indices of the created channel and sampler

pub fn create_scale_animation( &mut self, animation_index: usize, node_index: usize, timestamps: Vec<f32>, scales: Vec<[f32; 3]>, interpolation: InterpolationType, ) -> (usize, usize)

Create scale keyframes for an animation

Arguments

• animation_index - The index of the animation
• node_index - The index of the target node
• timestamps - Vector of keyframe timestamps (in seconds)
• scales - Vector of scale values ([x, y, z] for each keyframe)
• interpolation - The interpolation method

Returns

The indices of the created channel and sampler