Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-11-22 04:33:37 +00:00
Code Issues Projects Releases Packages Wiki Activity

Add sprite and mesh alteration examples (#15298)

Browse source 
# Objective

Add examples for manipulating sprites and meshes by either mutating the
handle or direct manipulation of the asset, as described in #15056.

Closes #3130.

(The previous PR suffered a Git-tastrophe, and was unceremoniously
closed, sry! 😅 )

---------

Co-authored-by: Jan Hohenheim <jan@hohenheim.ch>
This commit is contained in:
Rich Churcher 2024-09-22 13:18:40 +12:00 committed by GitHub
parent 02a9ed4b0b
commit e3b6b125a0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 425 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
Cargo.toml
View file

@ -1354,6 +1354,28 @@ category = "Application"
wasm = false
# Assets
[[example]]
name = "alter_mesh"
path = "examples/asset/alter_mesh.rs"
doc-scrape-examples = true
[package.metadata.example.alter_mesh]
name = "Alter Mesh"
description = "Shows how to modify the underlying asset of a Mesh after spawning."
category = "Assets"
wasm = false
[[example]]
name = "alter_sprite"
path = "examples/asset/alter_sprite.rs"
doc-scrape-examples = true
[package.metadata.example.alter_sprite]
name = "Alter Sprite"
description = "Shows how to modify texture assets after spawning."
category = "Assets"
wasm = false
[[example]]
name = "asset_loading"
path = "examples/asset/asset_loading.rs"

2
examples/README.md
View file

@ -219,6 +219,8 @@ Example | Description
Example | Description
--- | ---
[Alter Mesh](../examples/asset/alter_mesh.rs) | Shows how to modify the underlying asset of a Mesh after spawning.
[Alter Sprite](../examples/asset/alter_sprite.rs) | Shows how to modify texture assets after spawning.
[Asset Decompression](../examples/asset/asset_decompression.rs) | Demonstrates loading a compressed asset
[Asset Loading](../examples/asset/asset_loading.rs) | Demonstrates various methods to load assets
[Asset Processing](../examples/asset/processing/asset_processing.rs) | Demonstrates how to process and load custom assets

237
examples/asset/alter_mesh.rs Normal file
View file

@ -0,0 +1,237 @@
//! Shows how to modify mesh assets after spawning.
use bevy::{
gltf::GltfLoaderSettings, input::common_conditions::input_just_pressed, prelude::*,
render::mesh::VertexAttributeValues, render::render_asset::RenderAssetUsages,
};
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, (setup, spawn_text))
.add_systems(
Update,
alter_handle.run_if(input_just_pressed(KeyCode::Space)),
)
.add_systems(
Update,
alter_mesh.run_if(input_just_pressed(KeyCode::Enter)),
)
.run();
}
#[derive(Component, Debug)]
enum Shape {
Cube,
Sphere,
}
impl Shape {
fn get_model_path(&self) -> String {
match self {
Shape::Cube => "models/cube/cube.gltf".into(),
Shape::Sphere => "models/sphere/sphere.gltf".into(),
}
}
fn set_next_variant(&mut self) {
*self = match self {
Shape::Cube => Shape::Sphere,
Shape::Sphere => Shape::Cube,
}
}
}
#[derive(Component, Debug)]
struct Left;
fn setup(
mut commands: Commands,
asset_server: Res<AssetServer>,
mut materials: ResMut<Assets<StandardMaterial>>,
) {
let left_shape = Shape::Cube;
let right_shape = Shape::Cube;
// In normal use, you can call `asset_server.load`, however see below for an explanation of
// `RenderAssetUsages`.
let left_shape_model = asset_server.load_with_settings(
GltfAssetLabel::Primitive {
mesh: 0,
// This field stores an index to this primitive in its parent mesh. In this case, we
// want the first one. You might also have seen the syntax:
//
// models/cube/cube.gltf#Scene0
//
// which accomplishes the same thing.
primitive: 0,
}
.from_asset(left_shape.get_model_path()),
// `RenderAssetUsages::all()` is already the default, so the line below could be omitted.
// It's helpful to know it exists, however.
//
// `RenderAssetUsages` tell Bevy whether to keep the data around:
// - for the GPU (`RenderAssetUsages::RENDER_WORLD`),
// - for the CPU (`RenderAssetUsages::MAIN_WORLD`),
// - or both.
// `RENDER_WORLD` is necessary to render the mesh, `MAIN_WORLD` is necessary to inspect
// and modify the mesh (via `ResMut<Assets<Mesh>>`).
//
// Since most games will not need to modify meshes at runtime, many developers opt to pass
// only `RENDER_WORLD`. This is more memory efficient, as we don't need to keep the mesh in
// RAM. For this example however, this would not work, as we need to inspect and modify the
// mesh at runtime.
|settings: &mut GltfLoaderSettings| settings.load_meshes = RenderAssetUsages::all(),
);
// Here, we rely on the default loader settings to achieve a similar result to the above.
let right_shape_model = asset_server.load(
GltfAssetLabel::Primitive {
mesh: 0,
primitive: 0,
}
.from_asset(right_shape.get_model_path()),
);
// Add a material asset directly to the materials storage
let material_handle = materials.add(StandardMaterial {
base_color: Color::srgb(0.6, 0.8, 0.6),
..default()
});
commands.spawn((
Left,
Name::new("Left Shape"),
PbrBundle {
mesh: left_shape_model,
material: material_handle.clone(),
transform: Transform::from_xyz(-3.0, 0.0, 0.0),
..default()
},
left_shape,
));
commands.spawn((
Name::new("Right Shape"),
PbrBundle {
mesh: right_shape_model,
material: material_handle,
transform: Transform::from_xyz(3.0, 0.0, 0.0),
..default()
},
right_shape,
));
commands.spawn((
Name::new("Point Light"),
PointLightBundle {
transform: Transform::from_xyz(4.0, 5.0, 4.0),
..default()
},
));
commands.spawn((
Name::new("Camera"),
Camera3dBundle {
transform: Transform::from_xyz(0.0, 3.0, 20.0).looking_at(Vec3::ZERO, Vec3::Y),
..default()
},
));
}
fn spawn_text(mut commands: Commands) {
commands
.spawn((
Name::new("Instructions"),
NodeBundle {
style: Style {
align_items: AlignItems::Start,
flex_direction: FlexDirection::Column,
justify_content: JustifyContent::Start,
width: Val::Percent(100.),
..default()
},
..default()
},
))
.with_children(|parent| {
parent.spawn(TextBundle::from_section(
"Space: swap meshes by mutating a Handle<Mesh>",
TextStyle::default(),
));
parent.spawn(TextBundle::from_section(
"Return: mutate the mesh itself, changing all copies of it",
TextStyle::default(),
));
});
}
fn alter_handle(
asset_server: Res<AssetServer>,
mut right_shape: Query<(&mut Handle<Mesh>, &mut Shape), Without<Left>>,
) {
// Mesh handles, like other parts of the ECS, can be queried as mutable and modified at
// runtime. We only spawned one shape without the `Left` marker component.
let Ok((mut handle, mut shape)) = right_shape.get_single_mut() else {
return;
};
// Switch to a new Shape variant
shape.set_next_variant();
// Modify the handle associated with the Shape on the right side. Note that we will only
// have to load the same path from storage media once: repeated attempts will re-use the
// asset.
*handle = asset_server.load(
GltfAssetLabel::Primitive {
mesh: 0,
primitive: 0,
}
.from_asset(shape.get_model_path()),
);
}
fn alter_mesh(
mut is_mesh_scaled: Local<bool>,
left_shape: Query<&Handle<Mesh>, With<Left>>,
mut meshes: ResMut<Assets<Mesh>>,
) {
// It's convenient to retrieve the asset handle stored with the shape on the left. However,
// we could just as easily have retained this in a resource or a dedicated component.
let Ok(handle) = left_shape.get_single() else {
return;
};
// Obtain a mutable reference to the Mesh asset.
let Some(mesh) = meshes.get_mut(handle) else {
return;
};
// Now we can directly manipulate vertices on the mesh. Here, we're just scaling in and out
// for demonstration purposes. This will affect all entities currently using the asset.
//
// To do this, we need to grab the stored attributes of each vertex. `Float32x3` just describes
// the format in which the attributes will be read: each position consists of an array of three
// f32 corresponding to x, y, and z.
//
// `ATTRIBUTE_POSITION` is a constant indicating that we want to know where the vertex is
// located in space (as opposed to which way its normal is facing, vertex color, or other
// details).
if let Some(VertexAttributeValues::Float32x3(positions)) =
mesh.attribute_mut(Mesh::ATTRIBUTE_POSITION)
{
// Check a Local value (which only this system can make use of) to determine if we're
// currently scaled up or not.
let scale_factor = if *is_mesh_scaled { 0.5 } else { 2.0 };
for position in positions.iter_mut() {
// Apply the scale factor to each of x, y, and z.
position[0] *= scale_factor;
position[1] *= scale_factor;
position[2] *= scale_factor;
}
// Flip the local value to reverse the behaviour next time the key is pressed.
*is_mesh_scaled = !*is_mesh_scaled;
}
}

164
examples/asset/alter_sprite.rs Normal file
View file

@ -0,0 +1,164 @@
//! Shows how to modify texture assets after spawning.
use bevy::{
input::common_conditions::input_just_pressed,
prelude::*,
render::{render_asset::RenderAssetUsages, texture::ImageLoaderSettings},
};
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, (setup, spawn_text))
.add_systems(
Update,
alter_handle.run_if(input_just_pressed(KeyCode::Space)),
)
.add_systems(
Update,
alter_asset.run_if(input_just_pressed(KeyCode::Enter)),
)
.run();
}
#[derive(Component, Debug)]
enum Bird {
Normal,
Logo,
}
impl Bird {
fn get_texture_path(&self) -> String {
match self {
Bird::Normal => "branding/bevy_bird_dark.png".into(),
Bird::Logo => "branding/bevy_logo_dark.png".into(),
}
}
fn set_next_variant(&mut self) {
*self = match self {
Bird::Normal => Bird::Logo,
Bird::Logo => Bird::Normal,
}
}
}
#[derive(Component, Debug)]
struct Left;
fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
let bird_left = Bird::Normal;
let bird_right = Bird::Normal;
commands.spawn(Camera2dBundle::default());
let texture_left = asset_server.load_with_settings(
bird_left.get_texture_path(),
// `RenderAssetUsages::all()` is already the default, so the line below could be omitted.
// It's helpful to know it exists, however.
//
// `RenderAssetUsages` tell Bevy whether to keep the data around:
// - for the GPU (`RenderAssetUsages::RENDER_WORLD`),
// - for the CPU (`RenderAssetUsages::MAIN_WORLD`),
// - or both.
// `RENDER_WORLD` is necessary to render the image, `MAIN_WORLD` is necessary to inspect
// and modify the image (via `ResMut<Assets<Image>>`).
//
// Since most games will not need to modify textures at runtime, many developers opt to pass
// only `RENDER_WORLD`. This is more memory efficient, as we don't need to keep the image in
// RAM. For this example however, this would not work, as we need to inspect and modify the
// image at runtime.
|settings: &mut ImageLoaderSettings| settings.asset_usage = RenderAssetUsages::all(),
);
commands.spawn((
Name::new("Bird Left"),
// This marker component ensures we can easily find either of the Birds by using With and
// Without query filters.
Left,
SpriteBundle {
texture: texture_left,
transform: Transform::from_xyz(-200.0, 0.0, 0.0),
..default()
},
bird_left,
));
commands.spawn((
Name::new("Bird Right"),
SpriteBundle {
// In contrast to the above, here we rely on the default `RenderAssetUsages` loader
// setting.
texture: asset_server.load(bird_right.get_texture_path()),
transform: Transform::from_xyz(200.0, 0.0, 0.0),
..default()
},
bird_right,
));
}
fn spawn_text(mut commands: Commands) {
commands
.spawn((
Name::new("Instructions"),
NodeBundle {
style: Style {
align_items: AlignItems::Start,
flex_direction: FlexDirection::Column,
justify_content: JustifyContent::Start,
width: Val::Percent(100.),
..default()
},
..default()
},
))
.with_children(|parent| {
parent.spawn(TextBundle::from_section(
"Space: swap image texture paths by mutating a Handle<Image>",
TextStyle::default(),
));
parent.spawn(TextBundle::from_section(
"Return: mutate the image Asset itself, changing all copies of it",
TextStyle::default(),
));
});
}
fn alter_handle(
asset_server: Res<AssetServer>,
mut right_bird: Query<(&mut Bird, &mut Handle<Image>), Without<Left>>,
) {
// Image handles, like other parts of the ECS, can be queried as mutable and modified at
// runtime. We only spawned one bird without the `Left` marker component.
let Ok((mut bird, mut handle)) = right_bird.get_single_mut() else {
return;
};
// Switch to a new Bird variant
bird.set_next_variant();
// Modify the handle associated with the Bird on the right side. Note that we will only
// have to load the same path from storage media once: repeated attempts will re-use the
// asset.
*handle = asset_server.load(bird.get_texture_path());
}
fn alter_asset(mut images: ResMut<Assets<Image>>, left_bird: Query<&Handle<Image>, With<Left>>) {
// It's convenient to retrieve the asset handle stored with the bird on the left. However,
// we could just as easily have retained this in a resource or a dedicated component.
let Ok(handle) = left_bird.get_single() else {
return;
};
// Obtain a mutable reference to the Image asset.
let Some(image) = images.get_mut(handle) else {
return;
};
for pixel in &mut image.data {
// Directly modify the asset data, which will affect all users of this asset. By
// contrast, mutating the handle (as we did above) affects only one copy. In this case,
// we'll just invert the colors, by way of demonstration. Notice that both uses of the
// asset show the change, not just the one on the left.
*pixel = 255 - *pixel;
}
}