pub struct Handle<T>where
T: Asset,{ /* private fields */ }
Expand description
A handle into a specific Asset
of type T
.
Handles contain a unique id that corresponds to a specific asset in the Assets
collection.
Accessing the Asset
A handle is not the asset itself, but should be seen as a pointer to the asset. Modifying a
handle’s id
only modifies which asset is being pointed to. To get the actual asset, try using
Assets::get
or Assets::get_mut
.
Strong and Weak
A handle can be either “Strong” or “Weak”. Simply put: Strong handles keep the asset loaded, while Weak handles do not affect the loaded status of assets. This is due to a type of reference counting. When the number of Strong handles that exist for any given asset reach zero, the asset is dropped and becomes unloaded. In some cases, you might want a reference to an asset but don’t want to take the responsibility of keeping it loaded that comes with a Strong handle. This is where a Weak handle can be very useful.
For example, imagine you have a Sprite
component and a Collider
component. The Collider
uses
the Sprite
’s image size to check for collisions. It does so by keeping a Weak copy of the
Sprite
’s Strong handle to the image asset.
If the Sprite
is removed, its Strong handle to the image is dropped with it. And since it was the
only Strong handle for that asset, the asset is unloaded. Our Collider
component still has a Weak
handle to the unloaded asset, but it will not be able to retrieve the image data, resulting in
collisions no longer being detected for that entity.
Implementations
impl<T> Handle<T>where
T: Asset,
impl<T> Handle<T>where
T: Asset,
pub fn id(&self) -> HandleId
pub fn id(&self) -> HandleId
The ID of the asset as contained within its respective Assets
collection.
pub fn cast_weak<U>(&self) -> Handle<U>where
U: Asset,
pub fn cast_weak<U>(&self) -> Handle<U>where
U: Asset,
Recasts this handle as a weak handle of an Asset U
.
pub fn make_strong(&mut self, assets: &Assets<T>)
pub fn make_strong(&mut self, assets: &Assets<T>)
Makes this handle Strong if it wasn’t already.
This method requires the corresponding Assets
collection.
pub fn clone_weak(&self) -> Handle<T>
pub fn clone_weak(&self) -> Handle<T>
Creates a weak copy of this handle.
pub fn clone_untyped(&self) -> HandleUntyped
pub fn clone_untyped(&self) -> HandleUntyped
Creates an untyped copy of this handle.
pub fn clone_weak_untyped(&self) -> HandleUntyped
pub fn clone_weak_untyped(&self) -> HandleUntyped
Creates a weak, untyped copy of this handle.
Trait Implementations
impl<T> Component for Handle<T>where
T: Asset,
Handle<T>: 'static + Send + Sync,
impl<T> Component for Handle<T>where
T: Asset,
Handle<T>: 'static + Send + Sync,
type Storage = TableStorage
impl<T> ExtractComponent for Handle<T>where
T: Asset,
impl<T> ExtractComponent for Handle<T>where
T: Asset,
type Query = &'static Handle<T>
type Query = &'static Handle<T>
WorldQuery
to fetch the components to extract.fn extract_component(
handle: <<Handle<T> as ExtractComponent>::Query as WorldQuery>::Item<'_>
) -> Handle<T>
fn extract_component(
handle: <<Handle<T> as ExtractComponent>::Query as WorldQuery>::Item<'_>
) -> Handle<T>
impl<A> From<Handle<A>> for HandleUntypedwhere
A: Asset,
impl<A> From<Handle<A>> for HandleUntypedwhere
A: Asset,
fn from(handle: Handle<A>) -> HandleUntyped
fn from(handle: Handle<A>) -> HandleUntyped
impl From<Handle<Image>> for ColorMaterial
impl From<Handle<Image>> for ColorMaterial
fn from(texture: Handle<Image>) -> ColorMaterial
fn from(texture: Handle<Image>) -> ColorMaterial
impl From<Handle<Image>> for StandardMaterial
impl From<Handle<Image>> for StandardMaterial
fn from(texture: Handle<Image>) -> StandardMaterial
fn from(texture: Handle<Image>) -> StandardMaterial
impl From<Handle<Mesh>> for Mesh2dHandle
impl From<Handle<Mesh>> for Mesh2dHandle
fn from(handle: Handle<Mesh>) -> Mesh2dHandle
fn from(handle: Handle<Mesh>) -> Mesh2dHandle
impl<T> FromReflect for Handle<T>where
T: Asset,
HandleId: FromReflect,
impl<T> FromReflect for Handle<T>where
T: Asset,
HandleId: FromReflect,
fn from_reflect(reflect: &(dyn Reflect + 'static)) -> Option<Handle<T>>
fn from_reflect(reflect: &(dyn Reflect + 'static)) -> Option<Handle<T>>
Self
from a reflected value.impl<A> FromType<Handle<A>> for ReflectHandlewhere
A: Asset,
impl<A> FromType<Handle<A>> for ReflectHandlewhere
A: Asset,
fn from_type() -> ReflectHandle
impl<T> GetTypeRegistration for Handle<T>where
T: Asset,
impl<T> GetTypeRegistration for Handle<T>where
T: Asset,
impl<T> Ord for Handle<T>where
T: Asset,
impl<T> Ord for Handle<T>where
T: Asset,
1.21.0 · sourcefn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
1.21.0 · sourcefn min(self, other: Self) -> Selfwhere
Self: Sized,
fn min(self, other: Self) -> Selfwhere
Self: Sized,
1.50.0 · sourcefn clamp(self, min: Self, max: Self) -> Selfwhere
Self: Sized + PartialOrd<Self>,
fn clamp(self, min: Self, max: Self) -> Selfwhere
Self: Sized + PartialOrd<Self>,
impl<T> PartialOrd<Handle<T>> for Handle<T>where
T: Asset,
impl<T> PartialOrd<Handle<T>> for Handle<T>where
T: Asset,
fn partial_cmp(&self, other: &Handle<T>) -> Option<Ordering>
fn partial_cmp(&self, other: &Handle<T>) -> Option<Ordering>
1.0.0 · sourcefn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl<T> Reflect for Handle<T>where
T: Asset,
impl<T> Reflect for Handle<T>where
T: Asset,
fn get_type_info(&self) -> &'static TypeInfo
fn get_type_info(&self) -> &'static TypeInfo
fn into_any(self: Box<Handle<T>, Global>) -> Box<dyn Any + 'static, Global>
fn into_any(self: Box<Handle<T>, Global>) -> Box<dyn Any + 'static, Global>
Box<dyn Any>
.fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut dyn Any
.fn into_reflect(
self: Box<Handle<T>, Global>
) -> Box<dyn Reflect + 'static, Global>
fn into_reflect(
self: Box<Handle<T>, Global>
) -> Box<dyn Reflect + 'static, Global>
fn as_reflect(&self) -> &(dyn Reflect + 'static)
fn as_reflect(&self) -> &(dyn Reflect + 'static)
fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)
fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)
fn clone_value(&self) -> Box<dyn Reflect + 'static, Global>
fn clone_value(&self) -> Box<dyn Reflect + 'static, Global>
Reflect
trait object. Read morefn set(
&mut self,
value: Box<dyn Reflect + 'static, Global>
) -> Result<(), Box<dyn Reflect + 'static, Global>>
fn set(
&mut self,
value: Box<dyn Reflect + 'static, Global>
) -> Result<(), Box<dyn Reflect + 'static, Global>>
fn apply(&mut self, value: &(dyn Reflect + 'static))
fn apply(&mut self, value: &(dyn Reflect + 'static))
fn reflect_ref(&self) -> ReflectRef<'_>
fn reflect_ref(&self) -> ReflectRef<'_>
fn reflect_mut(&mut self) -> ReflectMut<'_>
fn reflect_mut(&mut self) -> ReflectMut<'_>
fn reflect_owned(self: Box<Handle<T>, Global>) -> ReflectOwned
fn reflect_owned(self: Box<Handle<T>, Global>) -> ReflectOwned
fn reflect_partial_eq(&self, value: &(dyn Reflect + 'static)) -> Option<bool>
fn reflect_partial_eq(&self, value: &(dyn Reflect + 'static)) -> Option<bool>
fn reflect_hash(&self) -> Option<u64>
fn reflect_hash(&self) -> Option<u64>
fn serializable(&self) -> Option<Serializable<'_>>
fn serializable(&self) -> Option<Serializable<'_>>
impl<T> Struct for Handle<T>where
T: Asset,
impl<T> Struct for Handle<T>where
T: Asset,
fn field_at_mut(&mut self, index: usize) -> Option<&mut (dyn Reflect + 'static)>
fn field_at_mut(&mut self, index: usize) -> Option<&mut (dyn Reflect + 'static)>
index
as a &mut dyn Reflect
. Read morefn iter_fields(&self) -> FieldIter<'_>ⓘ
fn iter_fields(&self) -> FieldIter<'_>ⓘ
fn clone_dynamic(&self) -> DynamicStruct
fn clone_dynamic(&self) -> DynamicStruct
DynamicStruct
.impl<T> Eq for Handle<T>where
T: Asset,
Auto Trait Implementations
impl<T> RefUnwindSafe for Handle<T>
impl<T> Send for Handle<T>
impl<T> Sync for Handle<T>
impl<T> Unpin for Handle<T>
impl<T> UnwindSafe for Handle<T>
Blanket Implementations
impl<T, U> AsBindGroupShaderType<U> for Twhere
U: ShaderType,
&'a T: for<'a> Into<U>,
impl<T, U> AsBindGroupShaderType<U> for Twhere
U: ShaderType,
&'a T: for<'a> Into<U>,
fn as_bind_group_shader_type(&self, _images: &RenderAssets<Image>) -> U
fn as_bind_group_shader_type(&self, _images: &RenderAssets<Image>) -> U
T
ShaderType
for self
. When used in AsBindGroup
derives, it is safe to assume that all images in self
exist. Read moresourceimpl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<C> Bundle for Cwhere
C: Component,
impl<C> Bundle for Cwhere
C: Component,
fn component_ids(
components: &mut Components,
storages: &mut Storages,
ids: &mut impl FnMut(ComponentId)
)
unsafe fn from_components<T, F>(ctx: &mut T, func: &mut F) -> Cwhere
F: for<'a> FnMut(&'a mut T) -> OwningPtr<'a>,
fn get_components(self, func: &mut impl FnMut(OwningPtr<'_>))
impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
. Read morefn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
. Read morefn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s. Read morefn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s. Read moresourceimpl<Q, K> Equivalent<K> for Qwhere
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
impl<Q, K> Equivalent<K> for Qwhere
Q: Eq + ?Sized,
K: Borrow<Q> + ?Sized,
sourcefn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.impl<T> FromWorld for Twhere
T: Default,
impl<T> FromWorld for Twhere
T: Default,
fn from_world(_world: &mut World) -> T
fn from_world(_world: &mut World) -> T
Self
using data from the given Worldimpl<S> GetField for Swhere
S: Struct,
impl<S> GetField for Swhere
S: Struct,
impl<T> GetPath for Twhere
T: Reflect,
impl<T> GetPath for Twhere
T: Reflect,
fn path<'r, 'p>(
&'r self,
path: &'p str
) -> Result<&'r (dyn Reflect + 'static), ReflectPathError<'p>>
fn path<'r, 'p>(
&'r self,
path: &'p str
) -> Result<&'r (dyn Reflect + 'static), ReflectPathError<'p>>
path
. Read morefn path_mut<'r, 'p>(
&'r mut self,
path: &'p str
) -> Result<&'r mut (dyn Reflect + 'static), ReflectPathError<'p>>
fn path_mut<'r, 'p>(
&'r mut self,
path: &'p str
) -> Result<&'r mut (dyn Reflect + 'static), ReflectPathError<'p>>
path
. Read morefn get_path<T, 'r, 'p>(
&'r self,
path: &'p str
) -> Result<&'r T, ReflectPathError<'p>>where
T: Reflect,
fn get_path<T, 'r, 'p>(
&'r self,
path: &'p str
) -> Result<&'r T, ReflectPathError<'p>>where
T: Reflect,
path
.fn get_path_mut<T, 'r, 'p>(
&'r mut self,
path: &'p str
) -> Result<&'r mut T, ReflectPathError<'p>>where
T: Reflect,
fn get_path_mut<T, 'r, 'p>(
&'r mut self,
path: &'p str
) -> Result<&'r mut T, ReflectPathError<'p>>where
T: Reflect,
path
. Read more