Sprite3d (bevyengine#2786)

# Objective

Make Sprites usable in 3d space.

## Solution

Rename Sprite to Sprite2d and add Sprite3d.
Add Example 3d_sprite_pipelined.

NOTE: Currently, differences between Sprite2d and Sprite3d and its rendering pipelines are minor. Implementations might diverge to greater extend with future iterations.

Author: VVishion

Cargo.toml

@@ -159,6 +159,10 @@ path = "examples/3d/3d_scene.rs"
 name = "3d_scene_pipelined"
 path = "examples/3d/3d_scene_pipelined.rs"
 
+[[example]]
+name = "3d_sprite_pipelined"
+path = "examples/3d/3d_sprite_pipelined.rs"
+
 [[example]]
 name = "cornell_box_pipelined"
 path = "examples/3d/cornell_box_pipelined.rs"

crates/bevy_internal/src/default_plugins.rs

@@ -129,7 +129,10 @@ impl PluginGroup for PipelinedDefaultPlugins {
             group.add(bevy_core_pipeline::CorePipelinePlugin::default());
 
             #[cfg(feature = "bevy_sprite2")]
-            group.add(bevy_sprite2::SpritePlugin::default());
+            group.add(bevy_sprite2::Sprite2dPlugin::default());
+
+            #[cfg(feature = "bevy_sprite2")]
+            group.add(bevy_sprite2::Sprite3dPlugin::default());
 
             #[cfg(feature = "bevy_pbr2")]
             group.add(bevy_pbr2::PbrPlugin::default());

examples/2d/pipelined_texture_atlas.rs

@@ -7,8 +7,7 @@ use bevy::{
     },
     render2::{camera::OrthographicCameraBundle, texture::Image},
     sprite2::{
-        PipelinedSpriteBundle, PipelinedSpriteSheetBundle, TextureAtlas, TextureAtlasBuilder,
-        TextureAtlasEntry,
+        Sprite2dBundle, Sprite2dSheetBundle, TextureAtlas, TextureAtlasBuilder, TextureAtlasEntry,
     },
     PipelinedDefaultPlugins,
 };
@@ -75,7 +74,7 @@ fn setup(
     // set up a scene to display our texture atlas
     commands.spawn_bundle(OrthographicCameraBundle::new_2d());
     // draw a sprite from the atlas
-    commands.spawn_bundle(PipelinedSpriteSheetBundle {
+    commands.spawn_bundle(Sprite2dSheetBundle {
         transform: Transform {
             translation: Vec3::new(150.0, 0.0, 0.0),
             scale: Vec3::splat(4.0),
@@ -86,7 +85,7 @@ fn setup(
         ..Default::default()
     });
     // draw the atlas itself
-    commands.spawn_bundle(PipelinedSpriteBundle {
+    commands.spawn_bundle(Sprite2dBundle {
         texture: texture_atlas_texture,
         transform: Transform::from_xyz(-300.0, 0.0, 0.0),
         ..Default::default()

examples/3d/3d_sprite_pipelined.rs

@@ -0,0 +1,132 @@
+use bevy::{
+    asset::LoadState,
+    ecs::query::With,
+    math::Quat,
+    prelude::{
+        App, AssetServer, Commands, HandleUntyped, Query, Res, ResMut, State, SystemSet, Time,
+        Transform,
+    },
+    render2::{camera::PerspectiveCameraBundle, texture::Image},
+    PipelinedDefaultPlugins,
+};
+
+use bevy::prelude::*;
+use bevy::sprite2::Sprite3dBundle;
+
+fn main() {
+    App::new()
+        .init_resource::<TexHandle>()
+        .add_plugins(PipelinedDefaultPlugins)
+        .add_state(AppState::Setup)
+        .add_system_set(SystemSet::on_enter(AppState::Setup).with_system(load_textures))
+        .add_system_set(SystemSet::on_update(AppState::Setup).with_system(check_textures))
+        .add_system_set(SystemSet::on_enter(AppState::Finished).with_system(setup))
+        .add_system_set(SystemSet::on_update(AppState::Finished).with_system(rotation_system))
+        .add_system_set(SystemSet::on_update(AppState::Finished).with_system(zoom_system))
+        .run();
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+enum AppState {
+    Setup,
+    Finished,
+}
+
+#[derive(Default)]
+struct TexHandle {
+    handle: Option<HandleUntyped>,
+}
+
+fn load_textures(mut tex_handle: ResMut<TexHandle>, asset_server: Res<AssetServer>) {
+    tex_handle.handle = Some(
+        asset_server
+            .load::<Image, _>("branding/icon.png")
+            .clone_untyped(),
+    );
+}
+
+fn check_textures(
+    mut state: ResMut<State<AppState>>,
+    tex_handle: ResMut<TexHandle>,
+    asset_server: Res<AssetServer>,
+) {
+    if let LoadState::Loaded = asset_server.get_load_state(tex_handle.handle.as_ref().unwrap().id) {
+        state.set(AppState::Finished).unwrap();
+    }
+}
+
+fn setup(mut commands: Commands, tex_handle: Res<TexHandle>) {
+    let entity = commands
+        .spawn_bundle(Sprite3dBundle {
+            texture: tex_handle.handle.as_ref().unwrap().clone().typed(),
+            transform: Transform::from_xyz(0.0, 0.0, 0.0),
+            ..Default::default()
+        })
+        .id();
+
+    let mut camera = PerspectiveCameraBundle::new_3d();
+    camera.transform = Transform {
+        translation: Vec3::new(0.0, 0.0, 1000.0),
+        ..Default::default()
+    };
+
+    commands.spawn_bundle(camera).insert(Rotate).insert(Zoom {
+        target: entity,
+        zooming: Zooming::In,
+    });
+}
+
+struct Rotate;
+
+fn rotation_system(time: Res<Time>, mut query: Query<&mut Transform, With<Rotate>>) {
+    for mut transform in query.iter_mut() {
+        *transform = Transform::from_rotation(Quat::from_rotation_z(
+            (4.0 * std::f32::consts::PI / 30.0) * time.delta_seconds(),
+        )) * Transform::from_rotation(Quat::from_rotation_y(
+            (4.0 * std::f32::consts::PI / 20.0) * time.delta_seconds(),
+        )) * Transform::from_rotation(Quat::from_rotation_x(
+            (4.0 * std::f32::consts::PI / 16.0) * time.delta_seconds(),
+        )) * *transform;
+    }
+}
+
+struct Zoom {
+    target: Entity,
+    zooming: Zooming,
+}
+
+enum Zooming {
+    In,
+    Out,
+}
+
+fn zoom_system(
+    time: Res<Time>,
+    mut queries: QuerySet<(
+        Query<(&mut Transform, &mut Zoom)>,
+        Query<&Transform, Without<Zoom>>,
+    )>,
+) {
+    for (mut camera_transform, mut zoom) in queries.q0_mut().iter_mut() {
+        let target_transform = queries.q1().get(zoom.target).unwrap();
+
+        let diff = camera_transform.translation - target_transform.translation;
+        let distance = diff.length();
+        let dir = diff.normalize();
+
+        match zoom.zooming {
+            Zooming::In => {
+                if distance < 100.0 {
+                    zoom.zooming = Zooming::Out;
+                }
+                camera_transform.translation = dir * (distance - 1000.0 * time.delta_seconds());
+            }
+            Zooming::Out => {
+                if distance > 5000.0 {
+                    zoom.zooming = Zooming::In;
+                }
+                camera_transform.translation = dir * (distance + 1000.0 * time.delta_seconds());
+            }
+        }
+    }
+}

examples/tools/bevymark_pipelined.rs

@@ -6,7 +6,7 @@ use bevy::{
     math::Vec3,
     prelude::{App, AssetServer, Handle, MouseButton, Transform},
     render2::{camera::OrthographicCameraBundle, color::Color, texture::Image},
-    sprite2::PipelinedSpriteBundle,
+    sprite2::Sprite2dBundle,
     window::WindowDescriptor,
     PipelinedDefaultPlugins,
 };
@@ -174,7 +174,7 @@ fn spawn_birds(
     for count in 0..spawn_count {
         let bird_z = (counter.count + count) as f32 * 0.00001;
         commands
-            .spawn_bundle(PipelinedSpriteBundle {
+            .spawn_bundle(Sprite2dBundle {
                 // material: bird_material.0.clone(),
                 texture: texture.clone(),
                 transform: Transform {

pipelined/bevy_sprite2/src/bundle.rs

@@ -1,21 +1,21 @@
 use crate::{
     texture_atlas::{TextureAtlas, TextureAtlasEntry},
-    Sprite,
+    Sprite2d, Sprite3d,
 };
 use bevy_asset::Handle;
 use bevy_ecs::bundle::Bundle;
 use bevy_render2::texture::Image;
 use bevy_transform::components::{GlobalTransform, Transform};
 
 #[derive(Bundle, Clone)]
-pub struct PipelinedSpriteBundle {
-    pub sprite: Sprite,
+pub struct Sprite2dBundle {
+    pub sprite: Sprite2d,
     pub transform: Transform,
     pub global_transform: GlobalTransform,
     pub texture: Handle<Image>,
 }
 
-impl Default for PipelinedSpriteBundle {
+impl Default for Sprite2dBundle {
     fn default() -> Self {
         Self {
             sprite: Default::default(),
@@ -29,8 +29,8 @@ impl Default for PipelinedSpriteBundle {
 /// A Bundle of components for drawing a single sprite from a sprite sheet (also referred
 /// to as a `TextureAtlas`)
 #[derive(Bundle, Clone)]
-pub struct PipelinedSpriteSheetBundle {
-    pub sprite: Sprite,
+pub struct Sprite2dSheetBundle {
+    pub sprite: Sprite2d,
     /// The specific sprite from the texture atlas to be drawn
     pub texture_atlas_entry: TextureAtlasEntry,
     /// A handle to the texture atlas that holds the sprite images
@@ -40,7 +40,52 @@ pub struct PipelinedSpriteSheetBundle {
     pub global_transform: GlobalTransform,
 }
 
-impl Default for PipelinedSpriteSheetBundle {
+impl Default for Sprite2dSheetBundle {
+    fn default() -> Self {
+        Self {
+            sprite: Default::default(),
+            texture_atlas_entry: Default::default(),
+            texture_atlas: Default::default(),
+            transform: Default::default(),
+            global_transform: Default::default(),
+        }
+    }
+}
+
+#[derive(Bundle, Clone)]
+pub struct Sprite3dBundle {
+    pub sprite: Sprite3d,
+    pub transform: Transform,
+    pub global_transform: GlobalTransform,
+    pub texture: Handle<Image>,
+}
+
+impl Default for Sprite3dBundle {
+    fn default() -> Self {
+        Self {
+            sprite: Default::default(),
+            transform: Default::default(),
+            global_transform: Default::default(),
+            texture: Default::default(),
+        }
+    }
+}
+
+/// A Bundle of components for drawing a single sprite from a sprite sheet (also referred
+/// to as a `TextureAtlas`)
+#[derive(Bundle, Clone)]
+pub struct Sprite3dSheetBundle {
+    pub sprite: Sprite3d,
+    /// The specific sprite from the texture atlas to be drawn
+    pub texture_atlas_entry: TextureAtlasEntry,
+    /// A handle to the texture atlas that holds the sprite images
+    pub texture_atlas: Handle<TextureAtlas>,
+    /// Data pertaining to how the sprite is drawn on the screen
+    pub transform: Transform,
+    pub global_transform: GlobalTransform,
+}
+
+impl Default for Sprite3dSheetBundle {
     fn default() -> Self {
         Self {
             sprite: Default::default(),

pipelined/bevy_sprite2/src/lib.rs

@@ -21,31 +21,61 @@ use bevy_render2::{
 };
 
 #[derive(Default)]
-pub struct SpritePlugin;
+pub struct Sprite2dPlugin;
 
-impl Plugin for SpritePlugin {
+impl Plugin for Sprite2dPlugin {
     fn build(&self, app: &mut App) {
-        app.add_asset::<TextureAtlas>().register_type::<Sprite>();
+        app.add_asset::<TextureAtlas>().register_type::<Sprite2d>();
         let render_app = app.sub_app(RenderApp);
         render_app
-            .init_resource::<ExtractedSprites>()
-            .add_system_to_stage(RenderStage::Extract, render::extract_atlases)
-            .add_system_to_stage(RenderStage::Extract, render::extract_sprites)
-            .add_system_to_stage(RenderStage::Prepare, render::prepare_sprites)
-            .add_system_to_stage(RenderStage::Queue, queue_sprites)
-            .init_resource::<SpriteShaders>()
-            .init_resource::<SpriteMeta>();
-        let draw_sprite = DrawSprite::new(&mut render_app.world);
+            .init_resource::<ExtractedSprites2d>()
+            .add_system_to_stage(RenderStage::Extract, render::extract_atlases_2d)
+            .add_system_to_stage(RenderStage::Extract, render::extract_sprites_2d)
+            .add_system_to_stage(RenderStage::Prepare, render::prepare_sprites_2d)
+            .add_system_to_stage(RenderStage::Queue, render::queue_sprites_2d)
+            .init_resource::<Sprite2dShaders>()
+            .init_resource::<Sprite2dMeta>();
+        let draw_sprite_2d = DrawSprite2d::new(&mut render_app.world);
         render_app
             .world
             .get_resource::<DrawFunctions>()
             .unwrap()
             .write()
-            .add(draw_sprite);
+            .add(draw_sprite_2d);
         let mut graph = render_app.world.get_resource_mut::<RenderGraph>().unwrap();
-        graph.add_node("sprite", SpriteNode);
+        graph.add_node("sprite2d", Sprite2dNode);
         graph
-            .add_node_edge("sprite", bevy_core_pipeline::node::MAIN_PASS_DEPENDENCIES)
+            .add_node_edge("sprite2d", bevy_core_pipeline::node::MAIN_PASS_DEPENDENCIES)
+            .unwrap();
+    }
+}
+
+#[derive(Default)]
+pub struct Sprite3dPlugin;
+
+impl Plugin for Sprite3dPlugin {
+    fn build(&self, app: &mut App) {
+        app.add_asset::<TextureAtlas>().register_type::<Sprite3d>();
+        let render_app = app.sub_app(RenderApp);
+        render_app
+            .init_resource::<ExtractedSprites3d>()
+            .add_system_to_stage(RenderStage::Extract, render::extract_atlases_3d)
+            .add_system_to_stage(RenderStage::Extract, render::extract_sprites_3d)
+            .add_system_to_stage(RenderStage::Prepare, render::prepare_sprites_3d)
+            .add_system_to_stage(RenderStage::Queue, render::queue_sprites_3d)
+            .init_resource::<Sprite3dShaders>()
+            .init_resource::<Sprite3dMeta>();
+        let draw_sprite_3d = DrawSprite3d::new(&mut render_app.world);
+        render_app
+            .world
+            .get_resource::<DrawFunctions>()
+            .unwrap()
+            .write()
+            .add(draw_sprite_3d);
+        let mut graph = render_app.world.get_resource_mut::<RenderGraph>().unwrap();
+        graph.add_node("sprite3d", Sprite3dNode);
+        graph
+            .add_node_edge("sprite3d", bevy_core_pipeline::node::MAIN_PASS_DEPENDENCIES)
             .unwrap();
     }
 }