Finish documenting bevy_gltf

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<Handle<Scene>>,
+ /// Named scenes loaded from the glTF file.
  pub named_scenes: HashMap<String, Handle<Scene>>,
+ /// All meshes loaded from the glTF file.
  pub meshes: Vec<Handle<GltfMesh>>,
+ /// Named meshes loaded from the glTF file.
  pub named_meshes: HashMap<String, Handle<GltfMesh>>,
+ /// All materials loaded from the glTF file.
  pub materials: Vec<Handle<StandardMaterial>>,
+ /// Named materials loaded from the glTF file.
  pub named_materials: HashMap<String, Handle<StandardMaterial>>,
+ /// All nodes loaded from the glTF file.
  pub nodes: Vec<Handle<GltfNode>>,
+ /// Named nodes loaded from the glTF file.
  pub named_nodes: HashMap<String, Handle<GltfNode>>,
+ /// Default scene to be displayed.
  pub default_scene: Option<Handle<Scene>>,
+ /// All animations loaded from the glTF file.
  #[cfg(feature = "bevy_animation")]
  pub animations: Vec<Handle<AnimationClip>>,
+ /// Named animations loaded from the glTF file.
  #[cfg(feature = "bevy_animation")]
  pub named_animations: HashMap<String, Handle<AnimationClip>>,
 }
 
 /// 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<GltfNode>,
+ /// Mesh of the node.
  pub mesh: Option<Handle<GltfMesh>>,
+ /// Local transform.
  pub transform: bevy_transform::prelude::Transform,
+ /// Additional data.
  pub extras: Option<GltfExtras>,
 }
 
 /// 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<GltfPrimitive>,
+ /// Additional data.
  pub extras: Option<GltfExtras>,
 }
 
 /// 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<Mesh>,
+ /// Material to apply to the `mesh`.
  pub material: Option<Handle<StandardMaterial>>,
+ /// Additional data.
  pub extras: Option<GltfExtras>,
+ /// Additional data of the `material`.
  pub material_extras: Option<GltfExtras>,
 }
 
+/// 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,
 }

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<String, MeshVertexAttribute>,
 }