Struct veloren_common_assets::AssetCache

pub struct AssetCache<S = FileSystem> {
    pub(crate) reloader: Option<HotReloader>,
    pub(crate) assets: AssetMap,
    source: S,
}

Expand description

The main structure of this crate, used to cache assets.

It uses interior mutability, so assets can be added in the cache without requiring a mutable reference, but one is required to remove an asset.

Within the cache, assets are identified with their type and a string. This string is constructed from the asset path, replacing / by . and removing the extension. Given that, you cannot use . in your file names except for the extension.

Note: Using symbolic or hard links within the cached directory can lead to surprising behavior (especially with hot-reloading), and thus should be avoided.

Example

use assets_manager::{Asset, AssetCache, loader};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Point {
    x: i32,
    y: i32,
}

impl Asset for Point {
    const EXTENSION: &'static str = "ron";
    type Loader = loader::RonLoader;
}

// Create a cache
let cache = AssetCache::new("assets")?;

// Get an asset from the file `assets/common/position.ron`
let point_handle = cache.load::<Point>("common.position")?;

// Read it
let point = point_handle.read();
println!("Loaded position: {:?}", point);

// Release the lock
drop(point);

// Use hot-reloading
loop {
    cache.hot_reload();
    println!("Position: {:?}", point_handle.read());
}

Fields§

§reloader: Option<HotReloader>§assets: AssetMap§source: S

Implementations§

§

impl AssetCache

pub fn new(path: P) -> Result<AssetCache, Error>
where P: AsRef<Path>,

Creates a cache that loads assets from the given directory.

Errors

An error will be returned if path is not valid readable directory.

§

impl<S> AssetCache<S>
where S: Source,

pub fn with_source(source: S) -> AssetCache<S>

Creates a cache that loads assets from the given source and tries to start hot-reloading (if feature hot-reloading is used).

If hot-reloading fails to start, an error is logged.

pub fn without_hot_reloading(source: S) -> AssetCache<S>

Creates a cache that loads assets from the given source.

pub fn raw_source(&self) -> &S

Returns a reference to the cache’s Source.

pub fn no_record<T, F>(&self, f: F) -> T
where F: FnOnce() -> T,

Temporarily prevent Compound dependencies to be recorded.

See AnyCache::no_record for more details.

pub fn load<T>(&self, id: &str) -> Result<&Handle<T>, Error>
where T: Compound,

Loads an asset.

See AnyCache::load for more details.

pub fn load_expect<T>(&self, id: &str) -> &Handle<T>
where T: Compound,

Loads an asset and panic if an error happens.

See AnyCache::load_expect for more details.

pub fn get_cached<T>(&self, id: &str) -> Option<&Handle<T>>
where T: Storable,

Gets a value from the cache.

See AnyCache::get_cached for more details.

pub fn get_or_insert<T>(&self, id: &str, default: T) -> &Handle<T>
where T: Storable,

Gets a value from the cache or inserts one.

See AnyCache::get_or_insert for more details.

pub fn contains<T>(&self, id: &str) -> bool
where T: Storable,

Returns true if the cache contains the specified asset.

See AnyCache::contains for more details.

pub fn load_dir<T>(&self, id: &str) -> Result<&Handle<Directory<T>>, Error>
where T: DirLoadable,

Loads a directory.

See AnyCache::load_dir for more details.

pub fn load_rec_dir<T>( &self, id: &str ) -> Result<&Handle<RecursiveDirectory<T>>, Error>
where T: DirLoadable,

Loads a directory.

See AnyCache::load_dir for more details.

pub fn load_owned<T>(&self, id: &str) -> Result<T, Error>
where T: Compound,

Loads an owned version of an asset.

See AnyCache::load_owned for more details.

pub fn as_any_cache(&self) -> AnyCache<'_>

Converts to an AnyCache.

§

impl<S> AssetCache<S>
where S: Source,

pub fn remove<T>(&mut self, id: &str) -> bool
where T: Storable,

Removes an asset from the cache, and returns whether it was present in the cache.

Note that you need a mutable reference to the cache, so you cannot have any [Handle], [AssetReadGuard], etc when you call this function.

pub fn take<T>(&mut self, id: &str) -> Option<T>
where T: Storable,

Takes ownership on a cached asset.

The corresponding asset is removed from the cache.

pub fn clear(&mut self)

Clears the cache.

Removes all cached assets and directories.

§

impl<S> AssetCache<S>
where S: Source + Sync,

pub fn hot_reload(&self)

Reloads changed assets.

This function is typically called within a loop.

If an error occurs while reloading an asset, a warning will be logged and the asset will be left unchanged.

This function blocks the current thread until all changed assets are reloaded, but it does not perform any I/O. However, it needs to lock some assets for writing, so you must not have any [AssetReadGuard] from the given AssetCache, or you might experience deadlocks. You are free to keep [Handle]s, though.

If self.source() was created without hot-reloading or if it failed to start, this function is a no-op.

pub fn enhance_hot_reloading(&'static self)

Enhances hot-reloading.

Having a 'static reference to the cache enables some optimizations, which you can take advantage of with this function. If an AssetCache is behind a 'static reference, you should always prefer using this function over hot_reload.

You only have to call this function once for it to take effect. After calling this function, subsequent calls to hot_reload and to this function have no effect.

If self.source() was created without hot-reloading or if it failed to start, this function is a no-op.