[Merged by Bors] - Doc bevy sprite

crates/bevy_sprite/src/bundle.rs

@@ -38,7 +38,7 @@ impl Default for SpriteBundle {
 /// to as a `TextureAtlas`)
 #[derive(Bundle, Clone, Default)]
 pub struct SpriteSheetBundle {
-    /// The specific sprite from the texture atlas to be drawn
+    /// The specific sprite from the texture atlas to be drawn, defaulting to the first sprite in the texture atlas.
     pub sprite: TextureAtlasSprite,
     /// A handle to the texture atlas that holds the sprite images
     pub texture_atlas: Handle<TextureAtlas>,

crates/bevy_sprite/src/dynamic_texture_atlas_builder.rs

@@ -4,19 +4,31 @@ use bevy_math::{IVec2, Rect, Vec2};
 use bevy_render::texture::{Image, TextureFormatPixelInfo};
 use guillotiere::{size2, Allocation, AtlasAllocator};
 
+/// Helper utility to update [`TextureAtlas`] on the fly.
+///
+/// Helpful in cases when texture is created highly dynamic,
+/// e.g: font glyph texture, only render for letters to be rendered.
 pub struct DynamicTextureAtlasBuilder {
-    pub atlas_allocator: AtlasAllocator,
-    pub padding: i32,
+    atlas_allocator: AtlasAllocator,
+    padding: i32,
 }
 
 impl DynamicTextureAtlasBuilder {
+    /// Create a new [`DynamicTextureAtlasBuilder`]
+    ///
+    /// # Arguments
+    ///
+    /// * `size` - total size for the atlas
+    /// * `padding` - padding between textures in the atlas
     pub fn new(size: Vec2, padding: i32) -> Self {
         Self {
             atlas_allocator: AtlasAllocator::new(to_size2(size)),
             padding,
         }
     }
 
+    /// Add a new texture to [`TextureAtlas`].
+    /// It is user's responsibility to pass in the correct [`TextureAtlas`]
     pub fn add_texture(
         &mut self,
         texture_atlas: &mut TextureAtlas,
@@ -38,29 +50,6 @@ impl DynamicTextureAtlasBuilder {
         }
     }
 
-    // fn resize(
-    //     &mut self,
-    //     texture_atlas: &mut TextureAtlas,
-    //     textures: &mut Assets<Texture>,
-    //     size: Vec2,
-    // ) {
-    //     let new_size2 = to_size2(new_size);
-    //     self.atlas_texture = Texture::new_fill(new_size, &[0,0,0,0]);
-    //     let change_list = self.atlas_allocator.resize_and_rearrange(new_size2);
-
-    //     for change in change_list.changes {
-    //         if let Some(changed_texture_handle) = self.allocation_textures.remove(&change.old.id)
-    // {             let changed_texture = textures.get(&changed_texture_handle).unwrap();
-    //             self.place_texture(change.new, changed_texture_handle, changed_texture);
-    //         }
-    //     }
-
-    //     for failure in change_list.failures {
-    //         let failed_texture = self.allocation_textures.remove(&failure.id).unwrap();
-    //         queued_textures.push(failed_texture);
-    //     }
-    // }
-
     fn place_texture(
         &mut self,
         atlas_texture: &mut Image,

crates/bevy_sprite/src/texture_atlas.rs

@@ -19,18 +19,24 @@ pub struct TextureAtlas {
     pub size: Vec2,
     /// The specific areas of the atlas where each texture can be found
     pub textures: Vec<Rect>,
-    pub texture_handles: Option<HashMap<Handle<Image>, usize>>,
+    /// Mapping from texture handle to index
+    pub(crate) texture_handles: Option<HashMap<Handle<Image>, usize>>,
 }
 
 #[derive(Component, Debug, Clone, Reflect)]
 pub struct TextureAtlasSprite {
+    /// The tint color used to draw the sprite, defaulting to [`Color::WHITE`]
     pub color: Color,
+    /// Texture index in [`TextureAtlas`]
     pub index: usize,
+    /// Whether flip the sprite in x axis
     pub flip_x: bool,
+    /// Whether flip the sprite in y axis
     pub flip_y: bool,
     /// An optional custom size for the sprite that will be used when rendering, instead of the size
-    /// of the sprite's image in the atlas
+    /// of the sprite's image in the atlas. The sprite will be scaled.
     pub custom_size: Option<Vec2>,
+    /// [`Anchor`] point of the sprite in the world
     pub anchor: Anchor,
 }
 
@@ -48,6 +54,8 @@ impl Default for TextureAtlasSprite {
 }
 
 impl TextureAtlasSprite {
+    /// Create a new [`TextureAtlasSprite`] with a sprite index,
+    /// it should be valid in corresponding [`TextureAtlas`]
     pub fn new(index: usize) -> TextureAtlasSprite {
         Self {
             index,
@@ -57,7 +65,7 @@ impl TextureAtlasSprite {
 }
 
 impl TextureAtlas {
-    /// Create a new `TextureAtlas` that has a texture, but does not have
+    /// Create a new [`TextureAtlas`] that has a texture, but does not have
     /// any individual sprites specified
     pub fn new_empty(texture: Handle<Image>, dimensions: Vec2) -> Self {
         Self {
@@ -68,10 +76,10 @@ impl TextureAtlas {
         }
     }
 
-    /// Generate a `TextureAtlas` by splitting a texture into a grid where each
+    /// Generate a [`TextureAtlas`] by splitting a texture into a grid where each
     /// `tile_size` by `tile_size` grid-cell is one of the textures in the
     /// atlas. Grid cells are separated by some `padding`, and the grid starts
-    /// at `offset` pixels from the top left corner. Resulting `TextureAtlas` is
+    /// at `offset` pixels from the top left corner. Resulting [`TextureAtlas`] is
     /// indexed left to right, top to bottom.
     pub fn from_grid(
         texture: Handle<Image>,
@@ -116,8 +124,8 @@ impl TextureAtlas {
         }
     }
 
-    /// Add a sprite to the list of textures in the `TextureAtlas`
-    /// returns an index to the texture which can be used with `TextureAtlasSprite`
+    /// Add a sprite to the list of textures in the [`TextureAtlas`]
+    /// returns an index to the texture which can be used with [`TextureAtlasSprite`]
     ///
     /// # Arguments
     ///
@@ -128,15 +136,17 @@ impl TextureAtlas {
         self.textures.len() - 1
     }
 
-    /// How many textures are in the `TextureAtlas`
+    /// How many textures are in the [`TextureAtlas`]
     pub fn len(&self) -> usize {
         self.textures.len()
     }
 
+    /// Returns `true` if there are no textures in the [`TextureAtlas`]
     pub fn is_empty(&self) -> bool {
         self.textures.is_empty()
     }
 
+    /// Returns the index if texture in the [`TextureAtlas`]
     pub fn get_texture_index(&self, texture: &Handle<Image>) -> Option<usize> {
         self.texture_handles
             .as_ref()