Trait gdnative::object::GodotObject
source · pub unsafe trait GodotObject: Sized + Sealed {
type Memory: Memory;
fn class_name() -> &'static str;
fn null() -> Null<Self> { ... }
fn new() -> Ref<Self, Unique>
where
Self: Instanciable,
{ ... }
fn cast<T>(&self) -> Option<&T>
where
T: GodotObject + SubClass<Self>,
{ ... }
fn upcast<T>(&self) -> &T
where
T: GodotObject,
Self: SubClass<T>,
{ ... }
unsafe fn assume_shared(&self) -> Ref<Self, Shared>
where
Self: Sized,
{ ... }
unsafe fn assume_thread_local(&self) -> Ref<Self, ThreadLocal>
where
Self: Sized + GodotObject<Memory = RefCounted>,
{ ... }
unsafe fn assume_unique(&self) -> Ref<Self, Unique>
where
Self: Sized,
{ ... }
unsafe fn try_from_instance_id<'a>(
id: i64
) -> Option<TRef<'a, Self, Shared>> { ... }
unsafe fn from_instance_id<'a>(id: i64) -> TRef<'a, Self, Shared> { ... }
}Expand description
Trait for Godot API objects. This trait is sealed, and implemented for generated wrapper types.
Bare GodotObject references, like &Node, can be used safely, but do not track thread
access states, which limits their usefulness to some extent. It’s not, for example, possible
to pass a &Node into an API method because it might have came from a Unique reference.
As such, it’s usually better to use Ref and TRefs whenever possible.
For convenience. it’s possible to use bare references as owner arguments in exported
methods when using NativeScript, but the limitations above should be kept in mind. See
the OwnerArg for more information.
IF it’s ever needed to obtain persistent references out of bare references, the assume_
methods can be used.
Required Associated Types§
Required Methods§
fn class_name() -> &'static str
Provided Methods§
sourcefn null() -> Null<Self>
fn null() -> Null<Self>
Creates an explicitly null reference of Self as a method argument. This makes type
inference easier for the compiler compared to Option.
sourcefn new() -> Ref<Self, Unique>where
Self: Instanciable,
fn new() -> Ref<Self, Unique>where
Self: Instanciable,
Creates a new instance of Self using a zero-argument constructor, as a Unique
reference.
sourcefn cast<T>(&self) -> Option<&T>where
T: GodotObject + SubClass<Self>,
fn cast<T>(&self) -> Option<&T>where
T: GodotObject + SubClass<Self>,
Performs a dynamic reference downcast to target type.
The cast method can only be used for downcasts. For statically casting to a
supertype, use upcast instead.
This method is only for conversion between engine types. To downcast to a NativeScript
type from its base type, see Ref::cast_instance and TRef::cast_instance.
sourcefn upcast<T>(&self) -> &Twhere
T: GodotObject,
Self: SubClass<T>,
fn upcast<T>(&self) -> &Twhere
T: GodotObject,
Self: SubClass<T>,
Performs a static reference upcast to a supertype that is guaranteed to be valid.
This is guaranteed to be a no-op at runtime.
Creates a persistent reference to the same Godot object with shared thread access.
Safety
There must not be any Unique or ThreadLocal references of the object when this
is called. This causes undefined behavior otherwise.
sourceunsafe fn assume_thread_local(&self) -> Ref<Self, ThreadLocal>where
Self: Sized + GodotObject<Memory = RefCounted>,
unsafe fn assume_thread_local(&self) -> Ref<Self, ThreadLocal>where
Self: Sized + GodotObject<Memory = RefCounted>,
Creates a persistent reference to the same Godot object with thread-local thread access.
Safety
There must not be any Unique or Shared references of the object when this
is called. This causes undefined behavior otherwise.
sourceunsafe fn assume_unique(&self) -> Ref<Self, Unique>where
Self: Sized,
unsafe fn assume_unique(&self) -> Ref<Self, Unique>where
Self: Sized,
Creates a persistent reference to the same Godot object with unique access.
Safety
Use with care. Unique is a very strong assumption that can easily be
violated. Only use this when you are absolutely sure you have the only reference.
There must be no other references of the object when this is called. This causes undefined behavior otherwise.
sourceunsafe fn try_from_instance_id<'a>(id: i64) -> Option<TRef<'a, Self, Shared>>
unsafe fn try_from_instance_id<'a>(id: i64) -> Option<TRef<'a, Self, Shared>>
Recovers a instance ID previously returned by Object::get_instance_id if the object is
still alive. See also TRef::try_from_instance_id.
Safety
During the entirety of 'a, the thread from which try_from_instance_id is called must
have exclusive access to the underlying object, if it is still alive.
sourceunsafe fn from_instance_id<'a>(id: i64) -> TRef<'a, Self, Shared>
unsafe fn from_instance_id<'a>(id: i64) -> TRef<'a, Self, Shared>
Recovers a instance ID previously returned by Object::get_instance_id if the object is
still alive, and panics otherwise. This does NOT guarantee that the resulting
reference is safe to use.
Panics
Panics if the given id refers to a destroyed object. For a non-panicking version, see
try_from_instance_id.
Safety
During the entirety of 'a, the thread from which try_from_instance_id is called must
have exclusive access to the underlying object, if it is still alive.