From c0aa5170bc0aa391709042161089e005260fd332 Mon Sep 17 00:00:00 2001 From: Noah Emke Date: Mon, 8 Apr 2024 13:10:56 -0400 Subject: [PATCH] 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. --- Cargo.toml | 11 +++ examples/README.md | 1 + examples/asset/asset_settings.rs | 80 ++++++++++++++++++ examples/asset/files/bevy_pixel_dark.png | Bin 0 -> 560 bytes .../asset/files/bevy_pixel_dark_with_meta.png | Bin 0 -> 560 bytes .../files/bevy_pixel_dark_with_meta.png.meta | 25 ++++++ .../files/bevy_pixel_dark_with_settings.png | Bin 0 -> 560 bytes 7 files changed, 117 insertions(+) create mode 100644 examples/asset/asset_settings.rs create mode 100644 examples/asset/files/bevy_pixel_dark.png create mode 100644 examples/asset/files/bevy_pixel_dark_with_meta.png create mode 100644 examples/asset/files/bevy_pixel_dark_with_meta.png.meta create mode 100644 examples/asset/files/bevy_pixel_dark_with_settings.png 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 0000000000000000000000000000000000000000..93fe567b34bed627273785e4a51e77a7609da20f GIT binary patch literal 560 zcmV-00?+-4P)EX>4Tx04R}tkv&MmKpe$i(`rR34t5Z6$WWauh!t_vDionYs1;guFuC*#ni!H4 z7e~Rh;NZt%)xpJCR|i)?5c~jfb8}L3krMxx6k5c1aNLh~_a1le0HIN3niU!cG~G5c zsic_8uZZDSbR&c)5)fr(8MBgEj=A{Svtpa#g^{ zF^>&skX=9cAN=mtDkdhpq(~CzdU2eO5g@z^H0zG@ee5{R6Cn5uT)|5Tqat9cEGGtSBr65hASOnhB=$rDuz%9_b>h;#z$LRx*rLNL9z`-Ff zTB7VVpLh3k_V(|YR)0T+(Q>bfaI$Ow000kAOjJbx0000004OLZ!^6XMb#>j!)NB9% z00neXPE!E?|Ns9S&?Zs<002BmL_t&tnO%!P4geqs!xpyxzgb1Z1#ayMP)8De8{3dc yq@-_BKp3VHwulJBBM{D2*jE-N)cfVpzik16`~gpZ7#hR?0000EX>4Tx04R}tkv&MmKpe$i(`rR34t5Z6$WWauh!t_vDionYs1;guFuC*#ni!H4 z7e~Rh;NZt%)xpJCR|i)?5c~jfb8}L3krMxx6k5c1aNLh~_a1le0HIN3niU!cG~G5c zsic_8uZZDSbR&c)5)fr(8MBgEj=A{Svtpa#g^{ zF^>&skX=9cAN=mtDkdhpq(~CzdU2eO5g@z^H0zG@ee5{R6Cn5uT)|5Tqat9cEGGtSBr65hASOnhB=$rDuz%9_b>h;#z$LRx*rLNL9z`-Ff zTB7VVpLh3k_V(|YR)0T+(Q>bfaI$Ow000kAOjJbx0000004OLZ!^6XMb#>j!)NB9% z00neXPE!E?|Ns9S&?Zs<002BmL_t&tnO%!P4geqs!xpyxzgb1Z1#ayMP)8De8{3dc yq@-_BKp3VHwulJBBM{D2*jE-N)cfVpzik16`~gpZ7#hR?0000EX>4Tx04R}tkv&MmKpe$i(`rR34t5Z6$WWauh!t_vDionYs1;guFuC*#ni!H4 z7e~Rh;NZt%)xpJCR|i)?5c~jfb8}L3krMxx6k5c1aNLh~_a1le0HIN3niU!cG~G5c zsic_8uZZDSbR&c)5)fr(8MBgEj=A{Svtpa#g^{ zF^>&skX=9cAN=mtDkdhpq(~CzdU2eO5g@z^H0zG@ee5{R6Cn5uT)|5Tqat9cEGGtSBr65hASOnhB=$rDuz%9_b>h;#z$LRx*rLNL9z`-Ff zTB7VVpLh3k_V(|YR)0T+(Q>bfaI$Ow000kAOjJbx0000004OLZ!^6XMb#>j!)NB9% z00neXPE!E?|Ns9S&?Zs<002BmL_t&tnO%!P4geqs!xpyxzgb1Z1#ayMP)8De8{3dc yq@-_BKp3VHwulJBBM{D2*jE-N)cfVpzik16`~gpZ7#hR?0000