Struct bevy::asset::LoadContext

pub struct LoadContext<'a> { /* private fields */ }

A context that provides access to assets in AssetLoaders, tracks dependencies, and collects asset load state. Any asset state accessed by LoadContext will be tracked and stored for use in dependency events and asset preprocessing.

Implementations

impl<'a> LoadContext<'a>

pub fn begin_labeled_asset(&self) -> LoadContext<'_>

Begins a new labeled asset load. Use the returned LoadContext to load dependencies for the new asset and call LoadContext::finish to finalize the asset load. When finished, make sure you call LoadContext::add_labeled_asset to add the results back to the parent context. Prefer LoadContext::labeled_asset_scope when possible, which will automatically add the labeled LoadContext back to the parent context. LoadContext::begin_labeled_asset exists largely to enable parallel asset loading.

See AssetPath for more on labeled assets.

let mut handles = Vec::new();
for i in 0..2 {
    let mut labeled = load_context.begin_labeled_asset();
    handles.push(std::thread::spawn(move || {
        (i.to_string(), labeled.finish(Image::default(), None))
    }));
}
for handle in handles {
    let (label, loaded_asset) = handle.join().unwrap();
    load_context.add_loaded_labeled_asset(label, loaded_asset);
}

pub fn labeled_asset_scope<A>( &mut self, label: String, load: impl FnOnce(&mut LoadContext<'_>) -> A ) -> Handle<A>

where A: Asset,

Creates a new LoadContext for the given label. The load function is responsible for loading an Asset of type A. load will be called immediately and the result will be used to finalize the LoadContext, resulting in a new LoadedAsset, which is registered under the label label.

This exists to remove the need to manually call LoadContext::begin_labeled_asset and then manually register the result with LoadContext::add_labeled_asset.

See AssetPath for more on labeled assets.

pub fn add_labeled_asset<A>(&mut self, label: String, asset: A) -> Handle<A>

where A: Asset,

This will add the given asset as a “labeled Asset” with the label label.

Warning

This will not assign dependencies to the given asset. If adding an asset with dependencies generated from calls such as LoadContext::load, use LoadContext::labeled_asset_scope or LoadContext::begin_labeled_asset to generate a new LoadContext to track the dependencies for the labeled asset.

See AssetPath for more on labeled assets.

pub fn add_loaded_labeled_asset<A>( &mut self, label: impl Into<CowArc<'static, str>>, loaded_asset: LoadedAsset<A> ) -> Handle<A>

where A: Asset,

Add a LoadedAsset that is a “labeled sub asset” of the root path of this load context. This can be used in combination with LoadContext::begin_labeled_asset to parallelize sub asset loading.

See AssetPath for more on labeled assets.

pub fn has_labeled_asset<'b>(&self, label: impl Into<CowArc<'b, str>>) -> bool

Returns true if an asset with the label label exists in this context.

See AssetPath for more on labeled assets.

pub fn finish<A>( self, value: A, meta: Option<Box<dyn AssetMetaDyn>> ) -> LoadedAsset<A>

where A: Asset,

“Finishes” this context by populating the final Asset value (and the erased AssetMeta value, if it exists). The relevant asset metadata collected in this context will be stored in the returned LoadedAsset.

pub fn path(&self) -> &Path

Gets the source path for this load context.

Examples found in repository

examples/asset/asset_decompression.rs (line 52)

    fn load<'a>(
        &'a self,
        reader: &'a mut Reader,
        _settings: &'a (),
        load_context: &'a mut LoadContext,
    ) -> BoxedFuture<'a, Result<Self::Asset, Self::Error>> {
        Box::pin(async move {
            let compressed_path = load_context.path();
            let file_name = compressed_path
                .file_name()
                .ok_or(GzAssetLoaderError::IndeterminateFilePath)?
                .to_string_lossy();
            let uncompressed_file_name = file_name
                .strip_suffix(".gz")
                .ok_or(GzAssetLoaderError::IndeterminateFilePath)?;
            let contained_path = compressed_path.join(uncompressed_file_name);

            let mut bytes_compressed = Vec::new();

            reader.read_to_end(&mut bytes_compressed).await?;

            let mut decoder = GzDecoder::new(bytes_compressed.as_slice());

            let mut bytes_uncompressed = Vec::new();

            decoder.read_to_end(&mut bytes_uncompressed)?;

            // Now that we have decompressed the asset, let's pass it back to the
            // context to continue loading

            let mut reader = VecReader::new(bytes_uncompressed);

            let uncompressed = load_context
                .load_direct_with_reader(&mut reader, contained_path)
                .await?;

            Ok(GzAsset { uncompressed })
        })
    }

pub fn asset_path(&self) -> &AssetPath<'static>

Gets the source asset path for this load context.

pub async fn read_asset_bytes<'b, 'c>( &'b mut self, path: impl Into<AssetPath<'c>> ) -> Result<Vec<u8>, ReadAssetBytesError>

Reads the asset at the given path and returns its bytes

pub fn load<'b, A>(&mut self, path: impl Into<AssetPath<'b>>) -> Handle<A>

where A: Asset,

Retrieves a handle for the asset at the given path and adds that path as a dependency of the asset. If the current context is a normal AssetServer::load, an actual asset load will be kicked off immediately, which ensures the load happens as soon as possible. “Normal loads” kicked from within a normal Bevy App will generally configure the context to kick off loads immediately.
If the current context is configured to not load dependencies automatically (ex: AssetProcessor), a load will not be kicked off automatically. It is then the calling context’s responsibility to begin a load if necessary.

pub fn load_untyped<'b>( &mut self, path: impl Into<AssetPath<'b>> ) -> Handle<LoadedUntypedAsset>

Retrieves a handle for the asset at the given path and adds that path as a dependency of the asset without knowing its type.

pub fn load_with_settings<'b, A, S>( &mut self, path: impl Into<AssetPath<'b>>, settings: impl Fn(&mut S) + Send + Sync + 'static ) -> Handle<A>

where A: Asset, S: Settings + Default,

Loads the Asset of type A at the given path with the given AssetLoader::Settings settings S. This is a “deferred” load. If the settings type S does not match the settings expected by A’s asset loader, an error will be printed to the log and the asset load will fail.

pub fn get_label_handle<'b, A>( &mut self, label: impl Into<CowArc<'b, str>> ) -> Handle<A>

where A: Asset,

Returns a handle to an asset of type A with the label label. This LoadContext must produce an asset of the given type and the given label or the dependencies of this asset will never be considered “fully loaded”. However you can call this method before or after adding the labeled asset.

pub async fn load_direct<'b>( &mut self, path: impl Into<AssetPath<'b>> ) -> Result<ErasedLoadedAsset, LoadDirectError>

Loads the asset at the given path directly. This is an async function that will wait until the asset is fully loaded before returning. Use this if you need the value of another asset in order to load the current asset. For example, if you are deriving a new asset from the referenced asset, or you are building a collection of assets. This will add the path as a “load dependency”.

If the current loader is used in a Process “asset preprocessor”, such as a LoadTransformAndSave preprocessor, changing a “load dependency” will result in re-processing of the asset.

pub async fn load_direct_with_reader<'b>( &mut self, reader: &mut (dyn AsyncRead + Unpin + Send + Sync), path: impl Into<AssetPath<'b>> ) -> Result<ErasedLoadedAsset, LoadDirectError>

Loads the asset at the given path directly from the provided reader. This is an async function that will wait until the asset is fully loaded before returning. Use this if you need the value of another asset in order to load the current asset, and that value comes from your Reader. For example, if you are deriving a new asset from the referenced asset, or you are building a collection of assets. This will add the path as a “load dependency”.

If the current loader is used in a Process “asset preprocessor”, such as a LoadTransformAndSave preprocessor, changing a “load dependency” will result in re-processing of the asset.

Examples found in repository

examples/asset/asset_decompression.rs (line 78)

    fn load<'a>(
        &'a self,
        reader: &'a mut Reader,
        _settings: &'a (),
        load_context: &'a mut LoadContext,
    ) -> BoxedFuture<'a, Result<Self::Asset, Self::Error>> {
        Box::pin(async move {
            let compressed_path = load_context.path();
            let file_name = compressed_path
                .file_name()
                .ok_or(GzAssetLoaderError::IndeterminateFilePath)?
                .to_string_lossy();
            let uncompressed_file_name = file_name
                .strip_suffix(".gz")
                .ok_or(GzAssetLoaderError::IndeterminateFilePath)?;
            let contained_path = compressed_path.join(uncompressed_file_name);

            let mut bytes_compressed = Vec::new();

            reader.read_to_end(&mut bytes_compressed).await?;

            let mut decoder = GzDecoder::new(bytes_compressed.as_slice());

            let mut bytes_uncompressed = Vec::new();

            decoder.read_to_end(&mut bytes_uncompressed)?;

            // Now that we have decompressed the asset, let's pass it back to the
            // context to continue loading

            let mut reader = VecReader::new(bytes_uncompressed);

            let uncompressed = load_context
                .load_direct_with_reader(&mut reader, contained_path)
                .await?;

            Ok(GzAsset { uncompressed })
        })
    }