UI Texture Atlas support

Cargo.toml

@@ -481,6 +481,10 @@ path = "examples/ui/text_debug.rs"
 name = "ui"
 path = "examples/ui/ui.rs"
 
+[[example]]
+name = "button_with_atlas"
+path = "examples/ui/button_with_atlas.rs"
+
 # Window
 [[example]]
 name = "clear_color"

crates/bevy_ui/src/entity.rs

@@ -2,7 +2,8 @@
 
 use crate::{
  widget::{Button, ImageMode},
- CalculatedSize, FocusPolicy, Interaction, Node, Style, UiColor, UiImage, CAMERA_UI,
+ CalculatedSize, FocusPolicy, Interaction, Node, Style, UiColor, UiImage, UiTextureAtlas,
+ CAMERA_UI,
 };
 use bevy_ecs::bundle::Bundle;
 use bevy_render::{
@@ -54,6 +55,29 @@ pub struct ImageBundle {
  pub visibility: Visibility,
 }
 
+/// A UI node that is an image with texture sheet
+#[derive(Bundle, Clone, Debug, Default)]
+pub struct ImageSheetBundle {
+ /// Describes the size of the node
+ pub node: Node,
+ /// Describes the style including flexbox settings
+ pub style: Style,
+ /// Configures how the image should scale
+ pub image_mode: ImageMode,
+ /// The calculated size based on the given image
+ pub calculated_size: CalculatedSize,
+ /// The color of the node
+ pub color: UiColor,
+ /// The texture atlas of the node
+ pub texture_atlas: UiTextureAtlas,
+ /// The transform of the node
+ pub transform: Transform,
+ /// The global transform of the node
+ pub global_transform: GlobalTransform,
+ /// Describes the visibility properties of the node
+ pub visibility: Visibility,
+}
+
 /// A UI node that is text
 #[derive(Bundle, Clone, Debug)]
 pub struct TextBundle {
@@ -132,6 +156,48 @@ impl Default for ButtonBundle {
  }
 }
 
+/// A UI node that is a button with a texture sheet
+#[derive(Bundle, Clone, Debug)]
+pub struct ButtonSheetBundle {
+ /// Describes the size of the node
+ pub node: Node,
+ /// Marker component that signals this node is a button
+ pub button: Button,
+ /// Describes the style including flexbox settings
+ pub style: Style,
+ /// Describes whether and how the button has been interacted with by the input
+ pub interaction: Interaction,
+ /// Whether this node should block interaction with lower nodes
+ pub focus_policy: FocusPolicy,
+ /// The color of the node
+ pub color: UiColor,
+ /// The texture atlas of the node
+ pub texture_atlas: UiTextureAtlas,
+ /// The transform of the node
+ pub transform: Transform,
+ /// The global transform of the node
+ pub global_transform: GlobalTransform,
+ /// Describes the visibility properties of the node
+ pub visibility: Visibility,
+}
+
+impl Default for ButtonSheetBundle {
+ fn default() -> Self {
+ Self {
+ button: Button,
+ interaction: Default::default(),
+ focus_policy: Default::default(),
+ node: Default::default(),
+ style: Default::default(),
+ color: Default::default(),
+ texture_atlas: Default::default(),
+ transform: Default::default(),
+ global_transform: Default::default(),
+ visibility: Default::default(),
+ }
+ }
+}
+
 /// The camera that is needed to see UI elements
 #[derive(Bundle, Debug)]
 pub struct UiCameraBundle {

crates/bevy_ui/src/lib.rs

@@ -69,6 +69,7 @@ impl Plugin for UiPlugin {
  .register_type::<Style>()
  .register_type::<UiColor>()
  .register_type::<UiImage>()
+ .register_type::<UiTextureAtlas>()
  .register_type::<Val>()
  .register_type::<widget::Button>()
  .register_type::<widget::ImageMode>()
@@ -85,6 +86,10 @@ impl Plugin for UiPlugin {
  CoreStage::PostUpdate,
  widget::image_node_system.before(UiSystem::Flex),
  )
+ .add_system_to_stage(
+ CoreStage::PostUpdate,
+ widget::image_sheet_node_system.before(UiSystem::Flex),
+ )
  .add_system_to_stage(
  CoreStage::PostUpdate,
  flex_node_system

crates/bevy_ui/src/render/mod.rs

@@ -34,7 +34,7 @@ use bevy_window::Windows;
 
 use bytemuck::{Pod, Zeroable};
 
-use crate::{CalculatedClip, Node, UiColor, UiImage};
+use crate::{CalculatedClip, Node, UiColor, UiImage, UiTextureAtlas};
 
 pub mod node {
  pub const UI_PASS_DRIVER: &str = "ui_pass_driver";
@@ -82,12 +82,22 @@ pub fn build_ui_render(app: &mut App) {
  .add_system_to_stage(RenderStage::Extract, extract_ui_camera_phases)
  .add_system_to_stage(
  RenderStage::Extract,
+ // This system is the first of `RenderStage::Extract` it is responsible for both:
+ // - Extracting Ui Nodes
+ // - Clearing the `ExtractedUiNodes` resource between frames.
+ //
+ // If you add extra systems they must all come after this system (see the label)
+ // and only add extra `ExtractedUiNode` to the resource.
  extract_uinodes.label(RenderUiSystem::ExtractNode),
  )
  .add_system_to_stage(
  RenderStage::Extract,
  extract_text_uinodes.after(RenderUiSystem::ExtractNode),
  )
+ .add_system_to_stage(
+ RenderStage::Extract,
+ extract_atlas_uinodes.after(RenderUiSystem::ExtractNode),
+ )
  .add_system_to_stage(RenderStage::Prepare, prepare_uinodes)
  .add_system_to_stage(RenderStage::Queue, queue_uinodes)
  .add_system_to_stage(RenderStage::PhaseSort, sort_phase_system::<TransparentUi>);
@@ -148,9 +158,11 @@ pub fn extract_uinodes(
  )>,
 ) {
  let mut extracted_uinodes = render_world.get_resource_mut::<ExtractedUiNodes>().unwrap();
+ // Resource clearing
  extracted_uinodes.uinodes.clear();
  for (uinode, transform, color, image, visibility, clip) in uinode_query.iter() {
- if !visibility.is_visible {
+ // Skips if the node is not visible or if its size is set to zero (e.g. when a parent is set to `Display::None`)
+ if !visibility.is_visible || uinode.size == Vec2::ZERO {
  continue;
  }
  let image = image.0.clone_weak();
@@ -172,6 +184,61 @@ pub fn extract_uinodes(
  }
 }
 
+pub fn extract_atlas_uinodes(
+ mut render_world: ResMut<RenderWorld>,
+ texture_atlases: Res<Assets<TextureAtlas>>,
+ images: Res<Assets<Image>>,
+ uinode_query: Query<(
+ &Node,
+ &GlobalTransform,
+ Option<&UiColor>,
+ &UiTextureAtlas,
+ &Visibility,
+ Option<&CalculatedClip>,
+ )>,
+) {
+ let mut extracted_uinodes = render_world.get_resource_mut::<ExtractedUiNodes>().unwrap();
+ for (uinode, transform, color, ui_atlas, visibility, clip) in uinode_query.iter() {
+ // Skips if the node is not visible or if its size is set to zero (e.g. when a parent is set to `Display::None`)
+ if !visibility.is_visible || uinode.size == Vec2::ZERO {
+ continue;
+ }
+ let atlas = texture_atlases
+ .get(ui_atlas.atlas.clone_weak())
+ .unwrap_or_else(|| {
+ panic!(
+ "Failed to retrieve `TextureAtlas` from handle {:?}",
+ ui_atlas.atlas
+ )
+ });
+ // Skip loading images
+ if !images.contains(atlas.texture.clone_weak()) {
+ continue;
+ }
+ let image = atlas.texture.clone_weak();
+ let atlas_size = Some(atlas.size);
+ let color = color.map_or(Color::default(), |c| c.0);
+ let rect = atlas
+ .textures
+ .get(ui_atlas.index)
+ .copied()
+ .unwrap_or_else(|| {
+ panic!(
+ "TextureAtlas {:?} as no texture at index {}",
+ ui_atlas.atlas, ui_atlas.index
+ )
+ });
+ extracted_uinodes.uinodes.push(ExtractedUiNode {
+ transform: transform.compute_matrix(),
+ color,
+ rect,
+ image,
+ atlas_size,
+ clip: clip.map(|clip| clip.clip),
+ });
+ }
+}
+
 pub fn extract_text_uinodes(
  mut render_world: ResMut<RenderWorld>,
  texture_atlases: Res<Assets<TextureAtlas>>,
@@ -195,11 +262,8 @@ pub fn extract_text_uinodes(
  };
 
  for (entity, uinode, transform, text, visibility, clip) in uinode_query.iter() {
- if !visibility.is_visible {
- continue;
- }
- // Skip if size is set to zero (e.g. when a parent is set to `Display::None`)
- if uinode.size == Vec2::ZERO {
+ // Skips if the node is not visible or if its size is set to zero (e.g. when a parent is set to `Display::None`)
+ if !visibility.is_visible || uinode.size == Vec2::ZERO {
  continue;
  }
  if let Some(text_layout) = text_pipeline.get_glyphs(&entity) {

crates/bevy_ui/src/ui_node.rs

@@ -6,6 +6,7 @@ use bevy_render::{
  color::Color,
  texture::{Image, DEFAULT_IMAGE_HANDLE},
 };
+use bevy_sprite::TextureAtlas;
 use serde::{Deserialize, Serialize};
 use std::ops::{Add, AddAssign};
 
@@ -384,6 +385,22 @@ impl From<Handle<Image>> for UiImage {
  }
 }
 
+/// The texture atlas of the node
+#[derive(Component, Clone, Debug, Default, Reflect)]
+#[reflect(Component)]
+pub struct UiTextureAtlas {
+ /// Texture atlas index
+ pub index: usize,
+ /// Texture atlas handle
+ pub atlas: Handle<TextureAtlas>,
+}
+
+impl From<Handle<TextureAtlas>> for UiTextureAtlas {
+ fn from(atlas: Handle<TextureAtlas>) -> Self {
+ Self { index: 0, atlas }
+ }
+}
+
 /// The calculated clip of the node
 #[derive(Component, Default, Copy, Clone, Debug, Reflect)]
 #[reflect(Component)]

crates/bevy_ui/src/widget/image.rs

@@ -1,4 +1,4 @@
-use crate::{CalculatedSize, UiImage};
+use crate::{CalculatedSize, UiImage, UiTextureAtlas};
 use bevy_asset::Assets;
 use bevy_ecs::{
  component::Component,
@@ -9,6 +9,7 @@ use bevy_ecs::{
 use bevy_math::Size;
 use bevy_reflect::{Reflect, ReflectDeserialize};
 use bevy_render::texture::Image;
+use bevy_sprite::TextureAtlas;
 use serde::{Deserialize, Serialize};
 
 /// Describes how to resize the Image node
@@ -43,3 +44,28 @@ pub fn image_node_system(
  }
  }
 }
+
+/// Updates calculated size of the node based on the texture atlas provided
+pub fn image_sheet_node_system(
+ texture_atlases: Res<Assets<TextureAtlas>>,
+ mut query: Query<(&mut CalculatedSize, &UiTextureAtlas), With<ImageMode>>,
+) {
+ for (mut calculated_size, ui_atlas) in query.iter_mut() {
+ if let Some(atlas) = texture_atlases.get(ui_atlas.atlas.clone_weak()) {
+ let rect = atlas.textures.get(ui_atlas.index).unwrap_or_else(|| {
+ panic!(
+ "TextureAtlas {:?} as no texture at index {}",
+ ui_atlas.atlas, ui_atlas.index
+ )
+ });
+ let size = Size {
+ width: rect.width(),
+ height: rect.height(),
+ };
+ // Update only if size has changed to avoid needless layout calculations
+ if size != calculated_size.size {
+ calculated_size.size = size;
+ }
+ }
+ }
+}

examples/README.md

@@ -243,6 +243,7 @@ Example | File | Description
 Example | File | Description
 --- | --- | ---
 `button` | [`ui/button.rs`](./ui/button.rs) | Illustrates creating and updating a button
+`button_with_atlas` | [`ui/button_with_atlas.rs`](./ui/button_with_atlas.rs) | Illustrates creating and updating a button with a texture atlas
 `font_atlas_debug` | [`ui/font_atlas_debug.rs`](./ui/font_atlas_debug.rs) | Illustrates how FontAtlases are populated (used to optimize text rendering internally)
 `text` | [`ui/text.rs`](./ui/text.rs) | Illustrates creating and updating text
 `text_debug` | [`ui/text_debug.rs`](./ui/text_debug.rs) | An example for debugging text layout