Enum Handle 

pub enum Handle<A>
where
    A: Asset,
{
    Strong(Arc<StrongHandle>),
    Weak(AssetId<A>),
}

A handle to a specific Asset of type A. Handles act as abstract “references” to assets, whose data are stored in the Assets<A> resource, avoiding the need to store multiple copies of the same data.

If a Handle is Handle::Strong, the Asset will be kept alive until the Handle is dropped. If a Handle is Handle::Weak, it does not necessarily reference a live Asset, nor will it keep assets alive.

Modifying a handle will change which existing asset is referenced, but modifying the asset (by mutating the Assets resource) will change the asset for all handles referencing it.

Handle can be cloned. If a Handle::Strong is cloned, the referenced Asset will not be freed until all instances of the Handle are dropped.

Handle::Strong, via StrongHandle also provides access to useful Asset metadata, such as the AssetPath (if it exists).

Variants

Strong(Arc<StrongHandle>)

A “strong” reference to a live (or loading) Asset. If a Handle is Handle::Strong, the Asset will be kept alive until the Handle is dropped. Strong handles also provide access to additional asset metadata.

Weak(AssetId<A>)

A “weak” reference to an Asset. If a Handle is Handle::Weak, it does not necessarily reference a live Asset, nor will it keep assets alive.

Implementations

impl<A> Handle<A>

where A: Asset,

pub const fn weak_from_u128(value: u128) -> Handle<A>

👎Deprecated since 0.16.0: use the weak_handle! macro with a UUID string instead

Create a new Handle::Weak with the given u128 encoding of a Uuid.

pub fn id(&self) -> AssetId<A>

Returns the AssetId of this Asset.

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

Returns the path if this is (1) a strong handle and (2) the asset has a path

pub fn is_weak(&self) -> bool

Returns true if this is a weak handle.

pub fn is_strong(&self) -> bool

Returns true if this is a strong handle.

pub fn clone_weak(&self) -> Handle<A>

Creates a Handle::Weak clone of this Handle, which will not keep the referenced Asset alive.

pub fn untyped(self) -> UntypedHandle

Converts this Handle to an “untyped” / “generic-less” UntypedHandle, which stores the Asset type information inside UntypedHandle. This will return UntypedHandle::Strong for Handle::Strong and UntypedHandle::Weak for Handle::Weak.

Trait Implementations

impl<T> Clone for Handle<T>

where T: Asset,

fn clone(&self) -> Handle<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<A> Debug for Handle<A>

where A: Asset,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<A> Default for Handle<A>

where A: Asset,

fn default() -> Handle<A>

Returns the “default value” for a type.

impl<A> Enum for Handle<A>

where A: Asset + TypePath, Handle<A>: Any + Send + Sync, Arc<StrongHandle>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, AssetId<A>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn field(&self, __name_param: &str) -> Option<&(dyn PartialReflect + 'static)>

Returns a reference to the value of the field (in the current variant) with the given name.

fn field_at( &self, __index_param: usize, ) -> Option<&(dyn PartialReflect + 'static)>

Returns a reference to the value of the field (in the current variant) at the given index.

fn field_mut( &mut self, __name_param: &str, ) -> Option<&mut (dyn PartialReflect + 'static)>

Returns a mutable reference to the value of the field (in the current variant) with the given name.

fn field_at_mut( &mut self, __index_param: usize, ) -> Option<&mut (dyn PartialReflect + 'static)>

Returns a mutable reference to the value of the field (in the current variant) at the given index.

fn index_of(&self, __name_param: &str) -> Option<usize>

Returns the index of the field (in the current variant) with the given name.

fn name_at(&self, __index_param: usize) -> Option<&str>

Returns the name of the field (in the current variant) with the given index.

fn iter_fields(&self) -> VariantFieldIter<'_>

Returns an iterator over the values of the current variant’s fields.

fn field_len(&self) -> usize

Returns the number of fields in the current variant.

fn variant_name(&self) -> &str

The name of the current variant.

fn variant_index(&self) -> usize

The index of the current variant.

fn variant_type(&self) -> VariantType

The type of the current variant.

fn to_dynamic_enum(&self) -> DynamicEnum

Creates a new DynamicEnum from this enum.

fn clone_dynamic(&self) -> DynamicEnum

👎Deprecated since 0.16.0: use to_dynamic_enum instead

fn is_variant(&self, variant_type: VariantType) -> bool

Returns true if the current variant’s type matches the given one.

fn variant_path(&self) -> String

Returns the full path to the current variant.

fn get_represented_enum_info(&self) -> Option<&'static EnumInfo>

Will return None if TypeInfo is not available.

impl<A> From<&Handle<A>> for AssetId<A>

where A: Asset,

fn from(value: &Handle<A>) -> AssetId<A>

Converts to this type from the input type.

impl<A> From<&mut Handle<A>> for AssetId<A>

where A: Asset,

fn from(value: &mut Handle<A>) -> AssetId<A>

Converts to this type from the input type.

impl<A> From<Handle<A>> for UntypedHandle

where A: Asset,

fn from(value: Handle<A>) -> UntypedHandle

Converts to this type from the input type.

impl From<Handle<AnimationGraph>> for AnimationGraphHandle

fn from(value: Handle<AnimationGraph>) -> AnimationGraphHandle

Converts to this type from the input type.

impl From<Handle<DynamicScene>> for DynamicSceneRoot

fn from(value: Handle<DynamicScene>) -> DynamicSceneRoot

Converts to this type from the input type.

impl From<Handle<Image>> for ColorMaterial

fn from(texture: Handle<Image>) -> ColorMaterial

Converts to this type from the input type.

impl From<Handle<Image>> for ImageNode

fn from(texture: Handle<Image>) -> ImageNode

Converts to this type from the input type.

impl From<Handle<Image>> for RenderTarget

fn from(handle: Handle<Image>) -> RenderTarget

Converts to this type from the input type.

impl From<Handle<Image>> for Sprite

fn from(image: Handle<Image>) -> Sprite

Converts to this type from the input type.

impl From<Handle<Image>> for StandardMaterial

fn from(texture: Handle<Image>) -> StandardMaterial

Converts to this type from the input type.

impl<M> From<Handle<M>> for MaterialNode<M>

where M: UiMaterial,

fn from(value: Handle<M>) -> MaterialNode<M>

Converts to this type from the input type.

impl<M> From<Handle<M>> for MeshMaterial2d<M>

where M: Material2d,

fn from(value: Handle<M>) -> MeshMaterial2d<M>

Converts to this type from the input type.

impl<M> From<Handle<M>> for MeshMaterial3d<M>

where M: Material,

fn from(value: Handle<M>) -> MeshMaterial3d<M>

Converts to this type from the input type.

impl From<Handle<Mesh>> for Mesh2d

fn from(value: Handle<Mesh>) -> Mesh2d

Converts to this type from the input type.

impl From<Handle<Mesh>> for Mesh3d

fn from(value: Handle<Mesh>) -> Mesh3d

Converts to this type from the input type.

impl From<Handle<Scene>> for SceneRoot

fn from(value: Handle<Scene>) -> SceneRoot

Converts to this type from the input type.

impl From<Handle<TextureAtlasLayout>> for TextureAtlas

fn from(texture_atlas: Handle<TextureAtlasLayout>) -> TextureAtlas

Converts to this type from the input type.

impl<A> FromReflect for Handle<A>

where A: Asset + TypePath, Handle<A>: Any + Send + Sync, Arc<StrongHandle>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, AssetId<A>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn from_reflect(__param0: &(dyn PartialReflect + 'static)) -> Option<Handle<A>>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn PartialReflect>, ) -> Result<Self, Box<dyn PartialReflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl<A> GetTypeRegistration for Handle<A>

where A: Asset + TypePath, Handle<A>: Any + Send + Sync, Arc<StrongHandle>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, AssetId<A>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

impl<A> Hash for Handle<A>

where A: Asset,

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<A> Ord for Handle<A>

where A: Asset,

fn cmp(&self, other: &Handle<A>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<A> PartialEq<Handle<A>> for UntypedHandle

where A: Asset,

fn eq(&self, other: &Handle<A>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A> PartialEq<UntypedHandle> for Handle<A>

where A: Asset,

fn eq(&self, other: &UntypedHandle) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A> PartialEq for Handle<A>

where A: Asset,

fn eq(&self, other: &Handle<A>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A> PartialOrd<Handle<A>> for UntypedHandle

where A: Asset,

fn partial_cmp(&self, other: &Handle<A>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A> PartialOrd<UntypedHandle> for Handle<A>

where A: Asset,

fn partial_cmp(&self, other: &UntypedHandle) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A> PartialOrd for Handle<A>

where A: Asset,

fn partial_cmp(&self, other: &Handle<A>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A> PartialReflect for Handle<A>

where A: Asset + TypePath, Handle<A>: Any + Send + Sync, Arc<StrongHandle>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, AssetId<A>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn try_apply( &mut self, __value_param: &(dyn PartialReflect + 'static), ) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Handle<A>>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Handle<A>>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&(dyn Reflect + 'static)>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut (dyn Reflect + 'static)>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<Handle<A>>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &(dyn PartialReflect + 'static)

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut (dyn PartialReflect + 'static)

Casts this type to a mutable, reflected value.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn reflect_partial_eq( &self, value: &(dyn PartialReflect + 'static), ) -> Option<bool>

Returns a “partial equality” comparison result.

fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Debug formatter for the value.

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

Attempts to clone Self using reflection.

fn apply(&mut self, value: &(dyn PartialReflect + 'static))

Applies a reflected value to this value.

fn clone_value(&self) -> Box<dyn PartialReflect>

👎Deprecated since 0.16.0: to clone reflected values, prefer using reflect_clone. To convert reflected values to dynamic ones, use to_dynamic.

Clones Self into its dynamic representation.

fn to_dynamic(&self) -> Box<dyn PartialReflect>

Converts this reflected value into its dynamic representation based on its kind.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl<A> Reflect for Handle<A>

where A: Asset + TypePath, Handle<A>: Any + Send + Sync, Arc<StrongHandle>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, AssetId<A>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn into_any(self: Box<Handle<A>>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &(dyn Any + 'static)

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Handle<A>>) -> Box<dyn Reflect>

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &(dyn Reflect + 'static)

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)

Casts this type to a mutable, fully-reflected value.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

impl<A> TryFrom<UntypedHandle> for Handle<A>

where A: Asset,

type Error = UntypedAssetConversionError

The type returned in the event of a conversion error.

fn try_from( value: UntypedHandle, ) -> Result<Handle<A>, <Handle<A> as TryFrom<UntypedHandle>>::Error>

Performs the conversion.

impl<A> TypePath for Handle<A>

where A: Asset + TypePath, Handle<A>: Any + Send + Sync,

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl<A> Typed for Handle<A>

where A: Asset + TypePath, Handle<A>: Any + Send + Sync, Arc<StrongHandle>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, AssetId<A>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl<A> VisitAssetDependencies for Handle<A>

where A: Asset,

fn visit_dependencies(&self, visit: &mut impl FnMut(UntypedAssetId))

impl<A> Eq for Handle<A>

where A: Asset,