Struct 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()))
    }));
}

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) -> LoadedAsset<A>

where A: Asset,

“Finishes” this context by populating the final Asset value.

pub fn path(&self) -> &Path

Gets the source path for this load context.

Examples found in repository

examples/asset/asset_decompression.rs (line 49)

    async fn load(
        &self,
        reader: &mut dyn Reader,
        _settings: &(),
        load_context: &mut LoadContext<'_>,
    ) -> Result<Self::Asset, Self::Error> {
        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
            .loader()
            .with_unknown_type()
            .immediate()
            .with_reader(&mut reader)
            .load(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 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 fn loader(&mut self) -> NestedLoader<'a, '_, StaticTyped, Deferred>

Create a builder for loading nested assets in this context.

Examples found in repository

examples/asset/processing/asset_processing.rs (line 153)

    async fn load(
        &self,
        reader: &mut dyn Reader,
        _settings: &Self::Settings,
        load_context: &mut LoadContext<'_>,
    ) -> Result<CoolText, Self::Error> {
        let mut bytes = Vec::new();
        reader.read_to_end(&mut bytes).await?;
        let ron: CoolTextRon = ron::de::from_bytes(&bytes)?;
        let mut base_text = ron.text;
        for embedded in ron.embedded_dependencies {
            let loaded = load_context
                .loader()
                .immediate()
                .load::<Text>(&embedded)
                .await?;
            base_text.push_str(&loaded.get().0);
        }
        for (path, settings_override) in ron.dependencies_with_settings {
            let loaded = load_context
                .loader()
                .with_settings(move |settings| {
                    *settings = settings_override.clone();
                })
                .immediate()
                .load::<Text>(&path)
                .await?;
            base_text.push_str(&loaded.get().0);
        }
        Ok(CoolText {
            text: base_text,
            dependencies: ron
                .dependencies
                .iter()
                .map(|p| load_context.load(p))
                .collect(),
        })
    }

examples/asset/asset_decompression.rs (line 75)

    async fn load(
        &self,
        reader: &mut dyn Reader,
        _settings: &(),
        load_context: &mut LoadContext<'_>,
    ) -> Result<Self::Asset, Self::Error> {
        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
            .loader()
            .with_unknown_type()
            .immediate()
            .with_reader(&mut reader)
            .load(contained_path)
            .await?;

        Ok(GzAsset { uncompressed })
    }

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.

If you need to override asset settings, asset type, or load directly, please see LoadContext::loader.

Examples found in repository

examples/asset/processing/asset_processing.rs (line 175)

    async fn load(
        &self,
        reader: &mut dyn Reader,
        _settings: &Self::Settings,
        load_context: &mut LoadContext<'_>,
    ) -> Result<CoolText, Self::Error> {
        let mut bytes = Vec::new();
        reader.read_to_end(&mut bytes).await?;
        let ron: CoolTextRon = ron::de::from_bytes(&bytes)?;
        let mut base_text = ron.text;
        for embedded in ron.embedded_dependencies {
            let loaded = load_context
                .loader()
                .immediate()
                .load::<Text>(&embedded)
                .await?;
            base_text.push_str(&loaded.get().0);
        }
        for (path, settings_override) in ron.dependencies_with_settings {
            let loaded = load_context
                .loader()
                .with_settings(move |settings| {
                    *settings = settings_override.clone();
                })
                .immediate()
                .load::<Text>(&path)
                .await?;
            base_text.push_str(&loaded.get().0);
        }
        Ok(CoolText {
            text: base_text,
            dependencies: ron
                .dependencies
                .iter()
                .map(|p| load_context.load(p))
                .collect(),
        })
    }