diff --git a/Cargo.toml b/Cargo.toml index 72305990c3..c413f232f1 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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" diff --git a/examples/README.md b/examples/README.md index aef42f6987..2ca3542bbb 100644 --- a/examples/README.md +++ b/examples/README.md @@ -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 diff --git a/examples/asset/asset_settings.rs b/examples/asset/asset_settings.rs new file mode 100644 index 0000000000..928e91778e --- /dev/null +++ b/examples/asset/asset_settings.rs @@ -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) { + // 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()); +} diff --git a/examples/asset/files/bevy_pixel_dark.png b/examples/asset/files/bevy_pixel_dark.png new file mode 100644 index 0000000000..93fe567b34 Binary files /dev/null and b/examples/asset/files/bevy_pixel_dark.png differ diff --git a/examples/asset/files/bevy_pixel_dark_with_meta.png b/examples/asset/files/bevy_pixel_dark_with_meta.png new file mode 100644 index 0000000000..93fe567b34 Binary files /dev/null and b/examples/asset/files/bevy_pixel_dark_with_meta.png differ diff --git a/examples/asset/files/bevy_pixel_dark_with_meta.png.meta b/examples/asset/files/bevy_pixel_dark_with_meta.png.meta new file mode 100644 index 0000000000..c960a4bf8c --- /dev/null +++ b/examples/asset/files/bevy_pixel_dark_with_meta.png.meta @@ -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"), + ), + ), +) \ No newline at end of file diff --git a/examples/asset/files/bevy_pixel_dark_with_settings.png b/examples/asset/files/bevy_pixel_dark_with_settings.png new file mode 100644 index 0000000000..93fe567b34 Binary files /dev/null and b/examples/asset/files/bevy_pixel_dark_with_settings.png differ