From 6852a23e1d4666f03709cb6687fdd47e19f25b22 Mon Sep 17 00:00:00 2001 From: Kanabenki Date: Mon, 2 Oct 2023 12:14:11 +0200 Subject: [PATCH] Finish documenting `bevy_gltf` --- crates/bevy_gltf/src/lib.rs | 41 ++++++++++++++++++++++++++++++++++ crates/bevy_gltf/src/loader.rs | 23 ++++++++++++++++++- 2 files changed, 63 insertions(+), 1 deletion(-) diff --git a/crates/bevy_gltf/src/lib.rs b/crates/bevy_gltf/src/lib.rs index 8474ab66e77c7..559c8ae3c8e63 100644 --- a/crates/bevy_gltf/src/lib.rs +++ b/crates/bevy_gltf/src/lib.rs @@ -1,4 +1,9 @@ +//! Plugin providing an [`AssetLoader`](bevy_asset::AssetLoader) and type definitions +//! for loading glTF 2.0 (a standard 3D scene definition format) files in Bevy. +//! +//! The [glTF 2.0 specification](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html) defines the format of the glTF files. #![allow(clippy::type_complexity)] +#![warn(missing_docs)] #[cfg(feature = "bevy_animation")] use bevy_animation::AnimationClip; @@ -27,6 +32,11 @@ pub struct GltfPlugin { } impl GltfPlugin { + /// Register a custom vertex attribute so that it is recognized when loading a glTF file with the [`GltfLoader`]. + /// + /// `name` must be the attribute name as found in the glTF data, which must start with an underscore. + /// See [this section of the glTF specification](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#meshes-overview) + /// for additional details on custom attributes. pub fn add_custom_vertex_attribute( mut self, name: &str, @@ -64,50 +74,81 @@ impl Plugin for GltfPlugin { /// Representation of a loaded glTF file. #[derive(Asset, Debug, TypePath)] pub struct Gltf { + /// All scenes loaded from the glTF file. pub scenes: Vec>, + /// Named scenes loaded from the glTF file. pub named_scenes: HashMap>, + /// All meshes loaded from the glTF file. pub meshes: Vec>, + /// Named meshes loaded from the glTF file. pub named_meshes: HashMap>, + /// All materials loaded from the glTF file. pub materials: Vec>, + /// Named materials loaded from the glTF file. pub named_materials: HashMap>, + /// All nodes loaded from the glTF file. pub nodes: Vec>, + /// Named nodes loaded from the glTF file. pub named_nodes: HashMap>, + /// Default scene to be displayed. pub default_scene: Option>, + /// All animations loaded from the glTF file. #[cfg(feature = "bevy_animation")] pub animations: Vec>, + /// Named animations loaded from the glTF file. #[cfg(feature = "bevy_animation")] pub named_animations: HashMap>, } /// A glTF node with all of its child nodes, its [`GltfMesh`], /// [`Transform`](bevy_transform::prelude::Transform) and an optional [`GltfExtras`]. +/// +/// See [the relevant glTF specification section](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#reference-node). #[derive(Asset, Debug, Clone, TypePath)] pub struct GltfNode { + /// Direct children of the node. pub children: Vec, + /// Mesh of the node. pub mesh: Option>, + /// Local transform. pub transform: bevy_transform::prelude::Transform, + /// Additional data. pub extras: Option, } /// A glTF mesh, which may consist of multiple [`GltfPrimitives`](GltfPrimitive) /// and an optional [`GltfExtras`]. +/// +/// See [the relevant glTF specification section](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#reference-mesh). #[derive(Asset, Debug, Clone, TypePath)] pub struct GltfMesh { + /// Primitives of the glTF mesh. pub primitives: Vec, + /// Additional data. pub extras: Option, } /// Part of a [`GltfMesh`] that consists of a [`Mesh`], an optional [`StandardMaterial`] and [`GltfExtras`]. +/// +/// See [the relevant glTF specification section](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#reference-mesh-primitive). #[derive(Asset, Debug, Clone, TypePath)] pub struct GltfPrimitive { + /// Topology to be rendered. pub mesh: Handle, + /// Material to apply to the `mesh`. pub material: Option>, + /// Additional data. pub extras: Option, + /// Additional data of the `material`. pub material_extras: Option, } +/// Additional untyped data that can be present on most glTF types. +/// +/// See [the relevant glTF specification section](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#reference-extras). #[derive(Clone, Debug, Reflect, Default, Component)] #[reflect(Component)] pub struct GltfExtras { + /// Content of the extra data. pub value: String, } diff --git a/crates/bevy_gltf/src/loader.rs b/crates/bevy_gltf/src/loader.rs index c00edd77eabeb..322bee5b7254c 100644 --- a/crates/bevy_gltf/src/loader.rs +++ b/crates/bevy_gltf/src/loader.rs @@ -49,35 +49,56 @@ use thiserror::Error; /// An error that occurs when loading a glTF file. #[derive(Error, Debug)] pub enum GltfError { + /// Unsupported primitive mode. #[error("unsupported primitive mode")] - UnsupportedPrimitive { mode: Mode }, + UnsupportedPrimitive { + /// The primitive mode. + mode: Mode, + }, + /// Invalid glTF file. #[error("invalid glTF file: {0}")] Gltf(#[from] gltf::Error), + /// Binary blob is missing. #[error("binary blob is missing")] MissingBlob, + /// Decoding the base64 mesh data failed. #[error("failed to decode base64 mesh data")] Base64Decode(#[from] base64::DecodeError), + /// Unsupported buffer format. #[error("unsupported buffer format")] BufferFormatUnsupported, + /// Invalid image mime type. #[error("invalid image mime type: {0}")] InvalidImageMimeType(String), + /// Error when loading a texture. Might be due to a disabled image file format feature. #[error("You may need to add the feature for the file format: {0}")] ImageError(#[from] TextureError), + /// Failed to read bytes from an asset path. #[error("failed to read bytes from an asset path: {0}")] ReadAssetBytesError(#[from] ReadAssetBytesError), + /// Failed to load asset from an asset path. #[error("failed to load asset from an asset path: {0}")] AssetLoadError(#[from] AssetLoadError), + /// Missing sampler for an animation. #[error("Missing sampler for animation {0}")] MissingAnimationSampler(usize), + /// Failed to generate tangents. #[error("failed to generate tangents: {0}")] GenerateTangentsError(#[from] bevy_render::mesh::GenerateTangentsError), + /// Failed to generate morph targets. #[error("failed to generate morph targets: {0}")] MorphTarget(#[from] bevy_render::mesh::morph::MorphBuildError), } /// Loads glTF files with all of their data as their corresponding bevy representations. pub struct GltfLoader { + /// List of compressed image formats handled by the loader. pub supported_compressed_formats: CompressedImageFormats, + /// Custom vertex attributes that will be recognized when loading a glTF file. + /// + /// Keys must be the attribute names as found in the glTF data, which must start with an underscore. + /// See [this section of the glTF specification](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#meshes-overview) + /// for additional details on custom attributes. pub custom_vertex_attributes: HashMap, }