Struct assets_manager::AssetCache
source · pub struct AssetCache<S = FileSystem> { /* private fields */ }
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());
}
Implementations§
source§impl AssetCache<FileSystem>
impl AssetCache<FileSystem>
sourcepub fn new<P: AsRef<Path>>(path: P) -> Result<AssetCache<FileSystem>>
pub fn new<P: AsRef<Path>>(path: P) -> Result<AssetCache<FileSystem>>
Creates a cache that loads assets from the given directory.
§Errors
An error will be returned if path
is not valid readable directory.
source§impl<S: Source> AssetCache<S>
impl<S: Source> AssetCache<S>
sourcepub fn with_source(source: S) -> AssetCache<S>
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.
sourcepub fn without_hot_reloading(source: S) -> AssetCache<S>
pub fn without_hot_reloading(source: S) -> AssetCache<S>
Creates a cache that loads assets from the given source.
sourcepub fn raw_source(&self) -> &S
pub fn raw_source(&self) -> &S
Returns a reference to the cache’s Source
.
sourcepub fn no_record<T, F: FnOnce() -> T>(&self, f: F) -> T
pub fn no_record<T, F: FnOnce() -> T>(&self, f: F) -> T
Temporarily prevent Compound
dependencies to be recorded.
See AnyCache::no_record
for more details.
sourcepub fn load<T: Compound>(&self, id: &str) -> Result<&Handle<T>, Error>
pub fn load<T: Compound>(&self, id: &str) -> Result<&Handle<T>, Error>
Loads an asset.
See AnyCache::load
for more details.
sourcepub fn load_expect<T: Compound>(&self, id: &str) -> &Handle<T>
pub fn load_expect<T: Compound>(&self, id: &str) -> &Handle<T>
Loads an asset and panic if an error happens.
See AnyCache::load_expect
for more details.
sourcepub fn get_cached<T: Storable>(&self, id: &str) -> Option<&Handle<T>>
pub fn get_cached<T: Storable>(&self, id: &str) -> Option<&Handle<T>>
Gets a value from the cache.
See AnyCache::get_cached
for more details.
sourcepub fn get_or_insert<T: Storable>(&self, id: &str, default: T) -> &Handle<T>
pub fn get_or_insert<T: Storable>(&self, id: &str, default: T) -> &Handle<T>
Gets a value from the cache or inserts one.
See AnyCache::get_or_insert
for more details.
sourcepub fn contains<T: Storable>(&self, id: &str) -> bool
pub fn contains<T: Storable>(&self, id: &str) -> bool
Returns true
if the cache contains the specified asset.
See AnyCache::contains
for more details.
sourcepub fn load_dir<T: DirLoadable>(
&self,
id: &str
) -> Result<&Handle<Directory<T>>, Error>
pub fn load_dir<T: DirLoadable>( &self, id: &str ) -> Result<&Handle<Directory<T>>, Error>
Loads a directory.
See AnyCache::load_dir
for more details.
sourcepub fn load_rec_dir<T: DirLoadable>(
&self,
id: &str
) -> Result<&Handle<RecursiveDirectory<T>>, Error>
pub fn load_rec_dir<T: DirLoadable>( &self, id: &str ) -> Result<&Handle<RecursiveDirectory<T>>, Error>
Loads a directory.
See AnyCache::load_dir
for more details.
sourcepub fn load_owned<T: Compound>(&self, id: &str) -> Result<T, Error>
pub fn load_owned<T: Compound>(&self, id: &str) -> Result<T, Error>
Loads an owned version of an asset.
See AnyCache::load_owned
for more details.
sourcepub fn as_any_cache(&self) -> AnyCache<'_>
pub fn as_any_cache(&self) -> AnyCache<'_>
Converts to an AnyCache
.
source§impl<S: Source> AssetCache<S>
impl<S: Source> AssetCache<S>
sourcepub fn remove<T: Storable>(&mut self, id: &str) -> bool
pub fn remove<T: Storable>(&mut self, id: &str) -> bool
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.
source§impl<S> AssetCache<S>
impl<S> AssetCache<S>
sourcepub fn hot_reload(&self)
Available on crate feature hot-reloading
only.
pub fn hot_reload(&self)
hot-reloading
only.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.
sourcepub fn enhance_hot_reloading(&'static self)
Available on crate feature hot-reloading
only.
pub fn enhance_hot_reloading(&'static self)
hot-reloading
only.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.
Trait Implementations§
source§impl<'a, S: Source> AsAnyCache<'a> for &'a AssetCache<S>
impl<'a, S: Source> AsAnyCache<'a> for &'a AssetCache<S>
source§fn as_any_cache(&self) -> AnyCache<'a>
fn as_any_cache(&self) -> AnyCache<'a>
AnyCache
.