diff --git a/crates/bevy_sprite/src/bundle.rs b/crates/bevy_sprite/src/bundle.rs index d97e1857ded21..092e5a302bb8b 100644 --- a/crates/bevy_sprite/src/bundle.rs +++ b/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 sprite at index 0. pub sprite: TextureAtlasSprite, /// A handle to the texture atlas that holds the sprite images pub texture_atlas: Handle, diff --git a/crates/bevy_sprite/src/dynamic_texture_atlas_builder.rs b/crates/bevy_sprite/src/dynamic_texture_atlas_builder.rs index 1155e0c5e23ce..18dd13a0ed8ff 100644 --- a/crates/bevy_sprite/src/dynamic_texture_atlas_builder.rs +++ b/crates/bevy_sprite/src/dynamic_texture_atlas_builder.rs @@ -4,12 +4,22 @@ 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 procedurally, +/// e.g: in a font glyph [`TextureAtlas`], only add the [`Image`] texture 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` - gap added between textures in the atlas, both in x axis and y axis pub fn new(size: Vec2, padding: i32) -> Self { Self { atlas_allocator: AtlasAllocator::new(to_size2(size)), @@ -17,6 +27,8 @@ impl DynamicTextureAtlasBuilder { } } + /// 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, - // 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, diff --git a/crates/bevy_sprite/src/texture_atlas.rs b/crates/bevy_sprite/src/texture_atlas.rs index ae9891914fe3d..d0234c132d9be 100644 --- a/crates/bevy_sprite/src/texture_atlas.rs +++ b/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, - pub texture_handles: Option, usize>>, + /// Mapping from texture handle to index + pub(crate) texture_handles: Option, 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 to flip the sprite in the X axis pub flip_x: bool, + /// Whether to flip the sprite in the 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 pub custom_size: Option, + /// [`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 the 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, 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. The resulting [`TextureAtlas`] is /// indexed left to right, top to bottom. pub fn from_grid( texture: Handle, @@ -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` + /// The number of textures 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 of the texture corresponding to the given image handle in the [`TextureAtlas`] pub fn get_texture_index(&self, texture: &Handle) -> Option { self.texture_handles .as_ref()