use std::path::Path;
use glam::{Mat4, Quat, Vec3};
use gltf::accessor::{DataType, Dimensions};
use gltf::animation::Property;
use super::asset::{Asset, Material, Result, Vertex};
use super::deformation;
use super::images::Image;
use super::load_budget::{Budget, MAX_LOAD_BYTES};
use material::read_material;
use meshes::{batch, ignored_attribute, read_node};
use rig::Rigging;
mod material;
mod meshes;
mod rig;
#[cfg(test)]
mod rig_tests;
mod sources;
#[cfg(all(test, not(target_arch = "wasm32")))]
mod tests;
#[derive(Clone, Copy, Default)]
pub struct LoadOptions<'a> {
pub emissive_strength_cap: Option<f32>,
#[allow(clippy::type_complexity)]
pub images: Option<&'a (dyn Fn(GltfImage<'_>) -> Result<ImageSource> + Sync)>,
#[allow(clippy::type_complexity)]
pub nodes: Option<&'a (dyn Fn(Option<&str>) -> bool + Sync)>,
}
impl std::fmt::Debug for LoadOptions<'_> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("LoadOptions")
.field("emissive_strength_cap", &self.emissive_strength_cap)
.field("images", &self.images.map(|_| "Fn"))
.field("nodes", &self.nodes.map(|_| "Fn"))
.finish()
}
}
#[derive(Clone, Copy, Debug)]
pub struct GltfImage<'a> {
pub index: usize,
pub name: Option<&'a str>,
pub uri: Option<&'a str>,
}
#[derive(Clone, Debug)]
pub enum ImageSource {
Decode,
Supplied(Image),
}
pub fn load(path: &Path) -> Result<Asset> {
load_with_options(path, LoadOptions::default())
}
pub fn load_with_options(path: &Path, options: LoadOptions<'_>) -> Result<Asset> {
load_inner(path, options).map_err(|error| format!("{}: {error}", path.display()).into())
}
fn load_inner(path: &Path, options: LoadOptions<'_>) -> Result<Asset> {
check(options)?;
let mut budget = Budget::new();
let bytes = budget.read_file(path, None)?;
let (document, buffers) = import(&bytes, path.parent(), &mut budget).map_err(|error| {
format!("glTF import failed: {error}; check referenced files and re-export valid glTF from the Blender source")
})?;
decode(document, &buffers, path.parent(), options, &mut budget)
}
pub fn load_slice(bytes: &[u8]) -> Result<Asset> {
load_slice_with_options(bytes, LoadOptions::default())
}
pub fn load_slice_with_options(bytes: &[u8], options: LoadOptions<'_>) -> Result<Asset> {
check(options)?;
let mut budget = Budget::new();
budget.charge(bytes.len() as u64)?;
let (document, buffers) = import(bytes, None, &mut budget)
.map_err(|error| format!("embedded glTF import failed: {error}"))?;
decode(document, &buffers, None, options, &mut budget)
}
fn check(options: LoadOptions<'_>) -> Result<()> {
if options
.emissive_strength_cap
.is_some_and(|cap| !cap.is_finite() || cap < 0.0)
{
return Err("emissive strength cap must be finite and nonnegative".into());
}
Ok(())
}
const SUPPORTED_EXTENSIONS: [&str; 13] = [
"KHR_materials_anisotropy",
"KHR_materials_clearcoat",
"KHR_materials_diffuse_transmission",
"KHR_materials_dispersion",
"KHR_materials_emissive_strength",
"KHR_materials_ior",
"KHR_materials_iridescence",
"KHR_materials_sheen",
"KHR_materials_specular",
"KHR_materials_transmission",
"KHR_materials_unlit",
"KHR_materials_volume",
"EXT_materials_bump",
];
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Ignored {
Extension(String),
OcclusionMap { material: usize },
SpecularMap { material: usize },
Image { image: usize },
Attribute {
mesh: usize,
primitive: usize,
name: String,
},
}
fn import(
bytes: &[u8],
base: Option<&Path>,
budget: &mut Budget,
) -> Result<(gltf::Document, Vec<gltf::buffer::Data>)> {
if bytes.starts_with(b"glTF") {
let length = bytes
.get(8..12)
.and_then(|length| <[u8; 4]>::try_from(length).ok())
.map(u32::from_le_bytes);
if length.is_none_or(|length| length < 12) {
return Err("the GLB header is truncated or declares a length below its own 12 bytes; re-export valid glTF".into());
}
}
let glb = bytes
.starts_with(b"glTF")
.then(|| gltf::binary::Glb::from_slice(bytes))
.transpose()?;
let json = glb.as_ref().map_or(bytes, |glb| glb.json.as_ref());
let mut root: gltf::json::Root = serde_json::from_slice(json)?;
if let Some(extension) = root
.extensions_required
.iter()
.find(|extension| !SUPPORTED_EXTENSIONS.contains(&extension.as_str()))
{
return Err(format!("the file requires glTF extension {extension}, which SGL3D does not support; bake it into the export or add renderer support").into());
}
check_root(&root)?;
root.extensions_required.clear();
let document = gltf::Document::from_json(root)?;
let blob = glb.as_ref().and_then(|glb| glb.bin.as_deref());
let buffers = sources::buffers(&document, base, blob, budget)?;
Ok((document, buffers))
}
fn check_root(root: &gltf::json::Root) -> Result<()> {
use gltf::json::validation::Checked;
for (mesh, data) in root.meshes.iter().enumerate() {
for (primitive, data) in data.primitives.iter().enumerate() {
for (attribute, accessor) in &data.attributes {
if accessor.value() >= root.accessors.len() {
return Err(format!("mesh {mesh} primitive {primitive} attribute {attribute:?}: accessor {} is out of range", accessor.value()).into());
}
}
for (target, data) in data.targets.iter().flatten().enumerate() {
for (attribute, accessor) in [
("POSITION", data.positions),
("NORMAL", data.normals),
("TANGENT", data.tangents),
] {
if let Some(accessor) = accessor
&& accessor.value() >= root.accessors.len()
{
return Err(format!("mesh {mesh} primitive {primitive} morph target {target} {attribute}: accessor {} is out of range", accessor.value()).into());
}
}
}
}
}
for (animation, data) in root.animations.iter().enumerate() {
for (channel, data) in data.channels.iter().enumerate() {
if data.target.node.value() >= root.nodes.len() {
return Err(format!(
"animation {animation} channel {channel}: target node {} is out of range",
data.target.node.value()
)
.into());
}
if !matches!(data.target.path, Checked::Valid(_)) {
return Err(format!(
"animation {animation} channel {channel}: invalid target path"
)
.into());
}
}
}
for (image, data) in root.images.iter().enumerate() {
if data.uri.is_some() == data.buffer_view.is_some() {
return Err(
format!("image {image}: exactly one of uri and bufferView is required").into(),
);
}
if data.buffer_view.is_some() && data.mime_type.is_none() {
return Err(format!("image {image}: bufferView requires mimeType").into());
}
}
Ok(())
}
fn read_images(
document: &gltf::Document,
buffers: &[gltf::buffer::Data],
base: Option<&Path>,
options: LoadOptions<'_>,
materials: &[Material],
ignored: &mut Vec<Ignored>,
budgets: (&mut Budget, &mut Budget),
) -> Result<Vec<Image>> {
let (budget, decoded_budget) = budgets;
let mut sampled = vec![false; document.images().len()];
for image in materials.iter().flat_map(sampled_images) {
sampled[image] = true;
}
document
.images()
.map(|image| {
let index = image.index();
if !sampled[index] {
ignored.push(Ignored::Image { image: index });
return Ok(Image::Rgba8(image::RgbaImage::new(1, 1)));
}
let file = match image.source() {
gltf::image::Source::Uri { uri, .. } if !uri.starts_with("data:") => Some(uri),
_ => None,
};
let source = match options.images {
None => ImageSource::Decode,
Some(sources) => sources(GltfImage {
index,
name: image.name(),
uri: file,
})
.map_err(|error| format!("image {index}: {error}"))?,
};
match source {
ImageSource::Supplied(supplied) => Ok(supplied),
ImageSource::Decode => {
if let gltf::image::Source::View { view, .. } = image.source()
&& !in_buffer(&view)
{
return Err(format!("image {index}'s buffer view does not fit its buffer; re-export valid glTF").into());
}
let data = sources::image(image.source(), base, buffers, budget, decoded_budget)
.map_err(|error| format!("image {index} import failed: {error}; check referenced files and re-export valid glTF from the Blender source"))?;
Ok(Image::Rgba8(data.into_rgba8()))
}
}
})
.collect()
}
fn sampled_images(material: &Material) -> Vec<usize> {
let mut images: Vec<usize> = material.texture_indices().into_iter().flatten().collect();
if let Some(occlusion) = material
.occlusion_texture
.filter(|_| !material.packed_occlusion())
&& let Some(slot) = images.iter().position(|&image| image == occlusion)
{
images.swap_remove(slot);
}
images
}
fn decode(
document: gltf::Document,
buffers: &[gltf::buffer::Data],
base: Option<&Path>,
options: LoadOptions<'_>,
budget: &mut Budget,
) -> Result<Asset> {
let scene = document
.default_scene()
.or_else(|| document.scenes().next())
.ok_or("GLB contains no scene")?;
let parents = rig::parents(&document)?;
let mut decoded_budget = Budget::new();
decoded_budget.charge(check_scene(&document, &scene, &parents)?)?;
let mut ignored: Vec<Ignored> = document
.extensions_used()
.filter(|extension| !SUPPORTED_EXTENSIONS.contains(extension))
.map(|extension| Ignored::Extension(extension.to_owned()))
.collect();
let mut materials = document
.materials()
.enumerate()
.map(|(index, material)| {
let strength = material.emissive_strength().unwrap_or(1.0);
let mut result = read_material(material, &document, index, &mut ignored)?;
if let Some(cap) = options.emissive_strength_cap
&& strength > cap
{
result.emissive = result.emissive.map(|value| value * cap / strength);
}
Ok(result)
})
.collect::<Result<Vec<_>>>()?;
let images = read_images(
&document,
buffers,
base,
options,
&materials,
&mut ignored,
(budget, &mut decoded_budget),
)?;
for mesh in document.meshes() {
for primitive in mesh.primitives() {
ignored.extend(
primitive
.attributes()
.filter(|(semantic, _)| ignored_attribute(semantic))
.map(|(semantic, _)| Ignored::Attribute {
mesh: mesh.index(),
primitive: primitive.index(),
name: semantic.to_string(),
}),
);
}
}
let default_material = materials.len();
materials.push(Material::default());
let buffer_bytes = buffers.iter().map(|buffer| buffer.0.len()).sum();
let mut rigging = Rigging::new(&document, &parents, (buffers, buffer_bytes))?;
let include_node = options.nodes.unwrap_or(&|_| true);
let mut meshes = Vec::new();
for node in scene.nodes() {
read_node(
node,
Mat4::IDENTITY,
(buffers, buffer_bytes),
(default_material, &materials),
&mut rigging,
&mut meshes,
include_node,
)?;
}
if meshes.is_empty() {
return Err("scene has no triangle meshes".into());
}
Ok(Asset {
meshes: batch(meshes, materials.len()),
materials,
images,
rig: rigging.rig,
ignored,
})
}
fn check_scene(
document: &gltf::Document,
scene: &gltf::Scene<'_>,
parents: &[Option<usize>],
) -> Result<u64> {
let mut listed = vec![false; parents.len()];
for node in scene.nodes().map(|node| node.index()) {
if std::mem::replace(&mut listed[node], true) {
return Err(format!(
"scene {} lists root node {node} more than once; re-export valid glTF",
scene.index()
)
.into());
}
if let Some(parent) = parents[node] {
return Err(format!("scene {} lists node {node} as a root, but node {parent} is its parent; re-export valid glTF", scene.index()).into());
}
}
load_bytes(document, scene).ok_or_else(|| format!("scene {}'s meshes (once for each node that uses them), skins and animation clips would take more than the {MAX_LOAD_BYTES} bytes one load may; split the asset", scene.index()).into())
}
fn load_bytes(document: &gltf::Document, scene: &gltf::Scene<'_>) -> Option<u64> {
use std::mem::size_of;
let bytes = |count: usize, size: usize| (count.max(1) as u64).checked_mul(size as u64);
let mut mesh_nodes = Vec::new();
let mut nodes: Vec<gltf::Node<'_>> = scene.nodes().collect();
while let Some(node) = nodes.pop() {
nodes.extend(node.children());
if node.mesh().is_some() {
mesh_nodes.push(node);
}
}
let primitives = mesh_nodes.iter().flat_map(|node| {
let vertex = size_of::<Vertex>()
+ node
.skin()
.map_or(0, |_| size_of::<deformation::Influence>());
let primitives = node.mesh().into_iter().flat_map(|mesh| mesh.primitives());
primitives.map(move |primitive| {
let vertices = primitive
.get(&gltf::Semantic::Positions)
.map_or(0, |positions| positions.count());
let indices = primitive
.indices()
.map_or(vertices, |indices| indices.count());
let deltas = bytes(vertices, size_of::<deformation::MorphDelta>())?
.checked_mul(primitive.morph_targets().count() as u64)?;
bytes(vertices, vertex)?
.checked_add(bytes(indices, size_of::<u32>())?)?
.checked_add(deltas)
})
});
let skins = document
.skins()
.map(|skin| bytes(skin.joints().count(), size_of::<deformation::Joint>()));
let channels = document
.animations()
.flat_map(|animation| animation.channels())
.map(|channel| {
let value = match channel.target().property() {
Property::Translation | Property::Scale => size_of::<Vec3>(),
Property::Rotation => size_of::<Quat>(),
Property::MorphTargetWeights => size_of::<f32>(),
};
let sampler = channel.sampler();
bytes(sampler.input().count(), size_of::<f32>())?
.checked_add(bytes(sampler.output().count(), value)?)
});
primitives
.chain(skins)
.chain(channels)
.try_fold(0u64, |total, bytes| {
total
.checked_add(bytes?)
.filter(|&total| total <= MAX_LOAD_BYTES)
})
}
fn check_accessor(
accessor: &gltf::Accessor<'_>,
what: &str,
types: &[DataType],
shapes: &[Dimensions],
count: Option<usize>,
(buffers, buffer_bytes): (&[gltf::buffer::Data], usize),
) -> Result<()> {
let index = accessor.index();
let (data_type, shape) = (accessor.data_type(), accessor.dimensions());
if !types.contains(&data_type) || !shapes.contains(&shape) {
return Err(format!("{what} accessor {index} holds {data_type:?} {shape:?}, where glTF allows {types:?} {shapes:?}; re-export valid glTF").into());
}
let sparse = accessor.sparse();
if accessor.count() == 0 || sparse.as_ref().is_some_and(|sparse| sparse.count() == 0) {
return Err(
format!("{what} accessor {index} has no elements; re-export valid glTF").into(),
);
}
let elements = accessor.count();
if let Some(count) = count
&& elements != count
{
return Err(format!("{what} accessor {index} has {elements} elements where its use needs {count}; re-export valid glTF").into());
}
if count.is_none()
&& accessor.view().is_none()
&& elements
.checked_mul(accessor.size())
.is_none_or(|bytes| bytes > buffer_bytes)
{
return Err(format!("{what} accessor {index} has {elements} elements without a buffer view, more than the file's {buffer_bytes} buffer bytes would hold; re-export valid glTF").into());
}
let size = accessor.size();
let within = accessor
.view()
.is_none_or(|view| fits(&view, accessor.offset(), accessor.count(), size))
&& sparse.as_ref().is_none_or(|sparse| {
let (indices, values) = (sparse.indices(), sparse.values());
fits(
&indices.view(),
indices.offset(),
sparse.count(),
indices.index_type().size(),
) && fits(&values.view(), values.offset(), sparse.count(), size)
});
if !within {
return Err(format!(
"{what} accessor {index} does not fit its buffer view and buffer; re-export valid glTF"
)
.into());
}
if let Some(sparse) = sparse {
use gltf::accessor::sparse::IndexType;
use gltf::accessor::util::{ItemIter, SparseIndicesIter};
let indices = sparse.indices();
let view = indices.view();
let stride = view.stride().unwrap_or(indices.index_type().size());
let bytes = &buffers[view.buffer().index()].0
[view.offset() + indices.offset()..view.offset() + view.length()];
let indices = match indices.index_type() {
IndexType::U8 => SparseIndicesIter::U8(ItemIter::new(bytes, stride)),
IndexType::U16 => SparseIndicesIter::U16(ItemIter::new(bytes, stride)),
IndexType::U32 => SparseIndicesIter::U32(ItemIter::new(bytes, stride)),
};
let mut previous = None;
for sparse_index in indices.take(sparse.count()) {
if sparse_index as usize >= elements
|| previous.is_some_and(|previous| sparse_index <= previous)
{
return Err(format!("{what} accessor {index} has sparse indices that are not strictly increasing and below its {elements} elements; re-export valid glTF").into());
}
previous = Some(sparse_index);
}
}
Ok(())
}
fn fits(view: &gltf::buffer::View<'_>, offset: usize, count: usize, size: usize) -> bool {
let stride = view.stride().unwrap_or(size);
in_buffer(view)
&& stride >= size
&& count
.checked_sub(1)
.and_then(|last| last.checked_mul(stride))
.and_then(|start| start.checked_add(offset))
.and_then(|start| start.checked_add(size))
.is_some_and(|end| end <= view.length())
}
fn in_buffer(view: &gltf::buffer::View<'_>) -> bool {
view.offset()
.checked_add(view.length())
.is_some_and(|end| end <= view.buffer().length())
}