Enum Handle

pub enum Handle<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: Asset> Handle<A>

pub const fn weak_from_u128(value: u128) -> Self

👎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) -> Self

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: Asset> Clone for Handle<T>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<A: Asset> Debug for Handle<A>

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

Formats the value using the given formatter.

impl<A: Asset> Default for Handle<A>

fn default() -> Self

Returns the “default value” for a type.

impl<A> Enum for Handle<A>

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

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

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>

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>

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>

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: Asset> From<&Handle<A>> for AssetId<A>

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

Converts to this type from the input type.

impl<A: Asset> From<&Handle<A>> for UntypedAssetId

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl<A: Asset> From<&mut Handle<A>> for UntypedAssetId

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl<A> FromReflect for Handle<A>

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

fn from_reflect(__param0: &dyn PartialReflect) -> Option<Self>

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: Asset> FromType<Handle<A>> for ReflectHandle

fn from_type() -> Self

impl<A> GetTypeRegistration for Handle<A>

where Handle<A>: Any + Send + Sync, A: TypePath + Asset, 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: Asset> Hash for Handle<A>

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

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: Asset> Ord for Handle<A>

fn cmp(&self, other: &Self) -> 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: Asset> PartialEq<Handle<A>> for UntypedHandle

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: Asset> PartialEq<UntypedHandle> for Handle<A>

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: Asset> PartialEq for Handle<A>

fn eq(&self, other: &Self) -> 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: Asset> PartialOrd<Handle<A>> for UntypedHandle

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: Asset> PartialOrd<UntypedHandle> for Handle<A>

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: Asset> PartialOrd for Handle<A>

fn partial_cmp(&self, other: &Self) -> 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 Handle<A>: Any + Send + Sync, A: TypePath + Asset, 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, ) -> 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<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Self>, ) -> 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>

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

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

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

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

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &dyn PartialReflect

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect

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) -> Option<bool>

Returns a “partial equality” comparison result.

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

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 Handle<A>: Any + Send + Sync, A: TypePath + Asset, Arc<StrongHandle>: FromReflect + TypePath + MaybeTyped + RegisterForReflection, AssetId<A>: FromReflect + TypePath + MaybeTyped + RegisterForReflection,

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

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

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

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

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

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: Asset> TryFrom<UntypedHandle> for Handle<A>

type Error = UntypedAssetConversionError

The type returned in the event of a conversion error.

fn try_from(value: UntypedHandle) -> Result<Self, Self::Error>

Performs the conversion.

impl<A> TypePath for Handle<A>

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

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 Handle<A>: Any + Send + Sync, A: TypePath + Asset, 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: Asset> VisitAssetDependencies for Handle<A>

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

impl<A: Asset> Eq for Handle<A>