Add example for using .meta files (#12882)

# Objective

- Fixes #12411 
- Add an example demonstrating the usage of asset meta files.

## Solution

- Add a new example displaying a basic scene of three pixelated images
- Apply a .meta file to one of the assets setting Nearest filtering
- Use AssetServer::load_with_settings on the last one as another way to
achieve the same effect
- The result is one blurry image and two crisp images demonstrating a
common scenario in which changing settings are useful.
This commit is contained in:
Noah Emke 2024-04-08 13:10:56 -04:00 committed by GitHub
parent 08b41878d7
commit c0aa5170bc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 117 additions and 0 deletions

View file

@ -1241,6 +1241,17 @@ description = "Demonstrates various methods to load assets"
category = "Assets"
wasm = false
[[example]]
name = "asset_settings"
path = "examples/asset/asset_settings.rs"
doc-scrape-examples = true
[package.metadata.example.asset_settings]
name = "Asset Settings"
description = "Demonstrates various methods of applying settings when loading an asset"
category = "Assets"
wasm = false
[[example]]
name = "asset_decompression"
path = "examples/asset/asset_decompression.rs"

View file

@ -198,6 +198,7 @@ Example | Description
[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
[Asset Settings](../examples/asset/asset_settings.rs) | Demonstrates various methods of applying settings when loading an asset
[Custom Asset](../examples/asset/custom_asset.rs) | Implements a custom asset loader
[Custom Asset IO](../examples/asset/custom_asset_reader.rs) | Implements a custom AssetReader
[Embedded Asset](../examples/asset/embedded_asset.rs) | Embed an asset in the application binary and load it

View file

@ -0,0 +1,80 @@
//! This example demonstrates the usage of '.meta' files and [`AssetServer::load_with_settings`] to override the default settings for loading an asset
use bevy::{
prelude::*,
render::texture::{ImageLoaderSettings, ImageSampler},
};
fn main() {
App::new()
.add_plugins(
// This just tells the asset server to look in the right examples folder
DefaultPlugins.set(AssetPlugin {
file_path: "examples/asset/files".to_string(),
..Default::default()
}),
)
.add_systems(Startup, setup)
.run();
}
fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
// Without any .meta file specifying settings, the default sampler [ImagePlugin::default()] is used for loading images.
// If you are using a very small image and rendering it larger like seen here, the default linear filtering will result in a blurry image.
// Useful note: The default sampler specified by the ImagePlugin is *not* the
commands.spawn(SpriteBundle {
texture: asset_server.load("bevy_pixel_dark.png"),
sprite: Sprite {
custom_size: Some(Vec2 { x: 160.0, y: 120.0 }),
..Default::default()
},
transform: Transform::from_xyz(-100.0, 0.0, 0.0),
..Default::default()
});
// When a .meta file is added with the same name as the asset and a '.meta' extension
// you can (and must) specify all fields of the asset loader's settings for that
// particular asset, in this case [ImageLoaderSettings]. Take a look at
// examples/asset/files/bevy_pixel_dark_with_meta.png.meta
// for the format and you'll notice, the only non-default option is setting Nearest
// filtering. This tends to work much better for pixel art assets.
// A good reference when filling this out is to check out [ImageLoaderSettings::default()]
// and follow to the default implementation of each fields type.
// https://docs.rs/bevy/latest/bevy/render/texture/struct.ImageLoaderSettings.html#
commands.spawn(SpriteBundle {
texture: asset_server.load("bevy_pixel_dark_with_meta.png"),
sprite: Sprite {
custom_size: Some(Vec2 { x: 160.0, y: 120.0 }),
..Default::default()
},
transform: Transform::from_xyz(100.0, 0.0, 0.0),
..Default::default()
});
// Another option is to use the AssetServers load_with_settings function.
// With this you can specify the same settings upon loading your asset with a
// couple of differences. A big one is that you aren't required to set *every*
// setting, just modify the ones that you need. It works by passing in a function
// (in this case an anonymous closure) that takes a reference to the settings type
// that is then modified in the function.
// Do note that if you want to load the same asset with different settings, the
// settings changes from any loads after the first of the same asset will be ignored.
// This is why this one loads a differently named copy of the asset instead of using
// same one as without a .meta file.
commands.spawn(SpriteBundle {
texture: asset_server.load_with_settings(
"bevy_pixel_dark_with_settings.png",
|settings: &mut ImageLoaderSettings| {
settings.sampler = ImageSampler::nearest();
},
),
sprite: Sprite {
custom_size: Some(Vec2 { x: 160.0, y: 120.0 }),
..Default::default()
},
transform: Transform::from_xyz(0.0, 150.0, 0.0),
..Default::default()
});
commands.spawn(Camera2dBundle::default());
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 560 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 560 B

View file

@ -0,0 +1,25 @@
(
meta_format_version: "1.0",
asset: Load(
loader: "bevy_render::texture::image_loader::ImageLoader",
settings: (
format: FromExtension,
is_srgb: true,
sampler: Descriptor (ImageSamplerDescriptor(
address_mode_u: ClampToEdge,
address_mode_v: ClampToEdge,
address_mode_w: ClampToEdge,
mag_filter: Nearest,
min_filter: Nearest,
mipmap_filter: Nearest,
lod_min_clamp: 0,
lod_max_clamp: 32.0,
compare: None,
anisotropy_clamp: 1,
border_color: None,
label: None,
)),
asset_usage: RenderAssetUsages("RENDER_WORLD | MAIN_WORLD"),
),
),
)

Binary file not shown.

After

Width:  |  Height:  |  Size: 560 B