mod document;
mod material;
mod parser;
#[cfg(test)]
mod tests;
use std::collections::HashMap;
pub use document::{decode_data_uri, Accessor, Document, ImageSource};
pub use material::{
constants as texture_constants, Assoc, GltfMaterial, GltfTexture, ImageData, MaterialType,
Param,
};
pub use parser::{
sanitize_node_name, three_attribute_name, world_matrix, CameraParams, GltfClip, GltfGeometry,
GltfObject, GltfOptions, GltfParser, GltfSkeleton, GltfTrack, ImageRequest, Instances,
LightParams, ObjectType, Record, TrackInterpolation, TrackKind,
};
use crate::animation::{AnimationClip, Interpolation, KeyframeTrack, TrackTarget};
use crate::core::{Bone, ObjectArena, ObjectId, Skeleton};
use crate::loaders::json::Value;
use crate::math::{Matrix4, Quaternion, Vector3};
use crate::scene::Scene;
pub type GltfImages = HashMap<usize, (u32, u32, Vec<u8>)>;
#[derive(Debug)]
pub enum GltfError {
Json(&'static str),
BadMagic,
UnsupportedVersion,
UnsupportedAttribute(String),
MissingField(&'static str),
BadBase64,
BadAccessor,
UnsupportedExtension(String),
Draco(super::draco::DracoError),
Message(String),
}
impl GltfError {
pub fn msg(m: impl Into<String>) -> Self {
GltfError::Message(m.into())
}
}
impl std::fmt::Display for GltfError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
GltfError::Json(e) => write!(f, "THREE.GLTFLoader: invalid JSON ({e})"),
GltfError::BadMagic => write!(f, "THREE.GLTFLoader: Unsupported glTF-Binary header."),
GltfError::UnsupportedVersion => {
write!(
f,
"THREE.GLTFLoader: Unsupported asset. glTF versions >=2.0 are supported."
)
}
GltfError::UnsupportedAttribute(a) => {
write!(f, "THREE.GLTFLoader: unsupported attribute {a}")
}
GltfError::MissingField(m) => write!(f, "THREE.GLTFLoader: missing {m}"),
GltfError::BadBase64 => write!(f, "THREE.GLTFLoader: invalid base64 in a data URI"),
GltfError::BadAccessor => write!(f, "THREE.GLTFLoader: invalid accessor"),
GltfError::UnsupportedExtension(e) => {
write!(
f,
"THREE.GLTFLoader: required extension \"{e}\" is not supported"
)
}
GltfError::Draco(e) => write!(f, "THREE.GLTFLoader: KHR_draco_mesh_compression: {e:?}"),
GltfError::Message(m) => f.write_str(m),
}
}
}
impl std::error::Error for GltfError {}
impl From<super::draco::DracoError> for GltfError {
fn from(e: super::draco::DracoError) -> Self {
GltfError::Draco(e)
}
}
pub struct GltfScene {
pub roots: Vec<ObjectId>,
pub arena: ObjectArena,
pub animations: Vec<AnimationClip>,
pub skeletons: Vec<Skeleton>,
pub extras: HashMap<ObjectId, Value>,
}
pub struct GltfLoader;
impl GltfLoader {
pub fn parse_glb_with_images(
bytes: &[u8],
images: &GltfImages,
) -> Result<GltfScene, GltfError> {
let doc = Document::from_bytes(bytes)?;
if !doc.is_glb {
return Err(GltfError::BadMagic);
}
load(doc, images)
}
pub fn parse_glb(bytes: &[u8]) -> Result<GltfScene, GltfError> {
Self::parse_glb_with_images(bytes, &HashMap::new())
}
pub fn parse_gltf(
json_str: &str,
external_buffers: &HashMap<usize, Vec<u8>>,
) -> Result<GltfScene, GltfError> {
Self::parse_gltf_with_images(json_str, external_buffers, &HashMap::new())
}
pub fn parse_gltf_with_images(
json_str: &str,
external_buffers: &HashMap<usize, Vec<u8>>,
images: &GltfImages,
) -> Result<GltfScene, GltfError> {
let mut doc = Document::from_parts(json_str.to_string(), None, false)?;
for (i, b) in external_buffers {
doc.set_buffer(*i, b.clone());
}
load(doc, images)
}
#[cfg(test)]
pub(crate) fn build_for_test(
root: &crate::loaders::json::Value,
) -> Result<GltfScene, GltfError> {
let doc = Document::from_parts(root.to_json(), None, false)?;
load(doc, &HashMap::new())
}
}
pub fn supply_images(parser: &mut GltfParser, images: &GltfImages) -> Result<(), GltfError> {
loop {
let pending = parser.pending_images()?;
if pending.is_empty() {
return Ok(());
}
for req in pending {
if let Some((w, h, data)) = images.get(&req.index) {
parser.set_image_rgba(req.index, *w, *h, data.clone());
} else if let Some(bytes) = &req.source.bytes {
if !parser.set_image_bytes(req.index, bytes) {
parser.set_image_failed(
req.index,
format!("no decoder here for {}", req.source.mime_type),
);
}
} else {
parser.set_image_failed(req.index, "external image not supplied".into());
}
}
}
}
fn load(doc: Document, images: &GltfImages) -> Result<GltfScene, GltfError> {
let mut parser = GltfParser::new(doc, GltfOptions::default())?;
supply_images(&mut parser, images)?;
let mut arena = ObjectArena::new();
parser.parse(&mut arena)?;
let mut roots = Vec::new();
if let Some(scene) = parser.default_scene() {
let id = parser.objects[scene].id;
roots = arena
.get(id)
.map(|n| n.children.clone())
.unwrap_or_default();
arena.delete(id);
} else if parser.scenes.is_empty() {
let n = document::count(parser.root(), "nodes");
let mut nodes = Vec::new();
for i in 0..n {
if let Some(o) = parser.load(&mut arena, "node", i)? {
nodes.push(parser.objects[o].id);
}
}
roots = nodes
.into_iter()
.filter(|id| arena.get(*id).is_some_and(|n| n.parent.is_none()))
.collect();
}
let skeletons = parser
.skeletons
.iter()
.map(|s| {
Skeleton::new(
s.bones
.iter()
.zip(&s.inverses)
.map(|(&b, inv)| Bone {
node: parser.objects[b].id,
inverse_bind: Matrix4 { elements: *inv },
})
.collect(),
)
})
.collect();
let animations = parser
.animations
.iter()
.flatten()
.map(|&c| legacy_clip(&parser, &parser.clips[c]))
.collect();
let extras = parser
.objects
.iter()
.filter(|o| o.user_data.as_object().is_some_and(|ud| !ud.is_empty()))
.map(|o| (o.id, o.user_data.clone()))
.collect();
Ok(GltfScene {
roots,
arena,
animations,
skeletons,
extras,
})
}
fn legacy_clip(parser: &GltfParser, clip: &GltfClip) -> AnimationClip {
let mut tracks = Vec::new();
for t in &clip.tracks {
let object = parser.objects[t.target].id;
let interp = match t.interpolation {
TrackInterpolation::Step => Interpolation::Step,
TrackInterpolation::CubicSpline => Interpolation::Cubic,
TrackInterpolation::Linear => Interpolation::Linear,
};
let cubic = t.interpolation == TrackInterpolation::CubicSpline;
let keys = t.times.len();
let vertices = |size: usize| -> Vec<f32> {
if !cubic {
return t.values.to_vec();
}
(0..keys)
.flat_map(|k| {
t.values
.get(k * size * 3 + size..k * size * 3 + 2 * size)
.unwrap_or(&[])
.to_vec()
})
.collect()
};
let track = match t.path.as_str() {
"translation" | "scale" => {
let vs = vertices(3)
.as_chunks::<3>()
.0
.iter()
.map(|c| Vector3::new(c[0], c[1], c[2]))
.collect();
let target = if t.path == "scale" {
TrackTarget::Scale
} else {
TrackTarget::Position
};
Some(KeyframeTrack::vector(object, target, t.times.to_vec(), vs))
}
"rotation" => {
let vs = vertices(4)
.as_chunks::<4>()
.0
.iter()
.map(|c| Quaternion::new(c[0], c[1], c[2], c[3]))
.collect();
Some(KeyframeTrack::quaternion(
object,
TrackTarget::Quaternion,
t.times.to_vec(),
vs,
))
}
"weights" => {
let per_key = if cubic { 3 } else { 1 };
let morph_count = (t.values.len() / (keys.max(1) * per_key)).max(1);
for mi in 0..morph_count {
let mut vs = Vec::with_capacity(keys * per_key);
for k in 0..keys {
for part in 0..per_key {
if let Some(&v) = t
.values
.get(k * morph_count * per_key + part * morph_count + mi)
{
vs.push(v);
}
}
}
let mut s = KeyframeTrack::scalar(
object,
TrackTarget::MorphWeight { index: mi },
t.times.to_vec(),
vs,
);
s.interpolation = interp;
tracks.push(s);
}
None
}
_ => None,
};
if let Some(mut track) = track {
track.interpolation = interp;
tracks.push(track);
}
}
AnimationClip::new(clip.name.clone(), clip.duration(), tracks)
}
pub fn add_to_scene(scene: &mut Scene, loaded: GltfScene) -> Vec<ObjectId> {
add_to_scene_mapped(scene, loaded).0
}
pub fn add_to_scene_mapped(
scene: &mut Scene,
loaded: GltfScene,
) -> (Vec<ObjectId>, HashMap<ObjectId, ObjectId>) {
let mut remap: HashMap<ObjectId, ObjectId> = HashMap::new();
let all: Vec<(ObjectId, crate::core::Object3D)> = loaded
.arena
.nodes
.iter()
.map(|(k, v)| (k, v.clone()))
.collect();
for (old, mut obj) in all {
obj.parent = None;
obj.children.clear();
let new = scene.arena.insert(obj);
remap.insert(old, new);
}
for new in remap.values() {
if let Some(crate::core::ObjectKind::SkinnedMesh(sm)) =
scene.arena.get_mut(*new).map(|n| &mut n.kind)
{
let bones = sm
.skeleton
.bones
.iter()
.map(|b| Bone {
node: remap.get(&b.node).copied().unwrap_or(b.node),
inverse_bind: b.inverse_bind,
})
.collect();
sm.skeleton = std::sync::Arc::new(Skeleton::new(bones));
}
}
let snapshot: Vec<(ObjectId, Vec<ObjectId>)> = loaded
.arena
.nodes
.iter()
.map(|(k, v)| (k, v.children.clone()))
.collect();
for (old_parent, children) in snapshot {
let new_parent = remap[&old_parent];
for c in children {
if let Some(nc) = remap.get(&c) {
scene.arena.add_child(new_parent, *nc);
}
}
}
let mut roots = Vec::new();
for r in loaded.roots {
if let Some(nr) = remap.get(&r) {
scene.arena.add_child(scene.root, *nr);
roots.push(*nr);
}
}
(roots, remap)
}