Skip to main content

ObjectRef

Struct ObjectRef 

Source
pub struct ObjectRef(/* private fields */);
Expand description

One node of the scene graph: three.js’ Object3D reference, a newtype over Rc<RefCell<Object3D>>.

Every inherent method here is the port of a three.js Object3D method that reads or writes parent/children; the transform-only methods stay inherent methods on Object3D itself. They live on the handle rather than on &mut Object3D because every one of them needs to reach outside the object it is called on — up to the parent or down into the children — which a &mut Object3D cannot do.

ObjectRef derefs to RefCell<Object3D>, so node.borrow() and node.borrow_mut() reach the object exactly as they did when ObjectRef was a type alias.

Implementations§

Source§

impl ObjectRef

Source

pub fn new(object: Object3D) -> Self

object, moved into a fresh scene-graph node.

Source

pub fn ptr_eq(a: &ObjectRef, b: &ObjectRef) -> bool

a === b: whether two handles are the same object. Was Rc::ptr_eq.

Source

pub fn downgrade(&self) -> WeakObjectRef

The weak handle Object3D.parent holds.

Source

pub fn as_ptr(&self) -> *const RefCell<Object3D>

The address of the object, for a consumer keying a cache on identity. Note that an address is only unique among live nodes — see docs/scene-graph.md, “Identity and eviction”; object.id is the collision-free key the renderer itself uses.

Source

pub fn parent(&self) -> Option<ObjectRef>

Object3D.parent, upgraded.

Source

pub fn children(&self) -> Vec<ObjectRef>

Object3D.children, cloned (cheap: a Vec of Rcs). Cloning is what lets a traversal run without holding a borrow on the parent.

Source

pub fn add(&self, object: &ObjectRef) -> &Self

Object3D.add( object ).

Source

pub fn remove(&self, object: &ObjectRef) -> &Self

Object3D.remove( object ).

Source

pub fn remove_from_parent(&self) -> &Self

Object3D.removeFromParent().

Source

pub fn clear(&self) -> &Self

Object3D.clear().

Source

pub fn attach(&self, object: &ObjectRef) -> &Self

Object3D.attach( object ).

Source

pub fn add_event_listener( &self, ty: SceneEventType, listener: impl Fn(&SceneEvent, &ObjectRef) + 'static, ) -> ListenerHandle

EventDispatcher.addEventListener( type, listener ): listener is called with every event of type ty dispatched on this object, and with the object itself (three’s event.target). The returned handle stands for the listener in remove_event_listener and has_event_listener.

Source

pub fn has_event_listener( &self, ty: SceneEventType, handle: ListenerHandle, ) -> bool

EventDispatcher.hasEventListener( type, listener ).

Source

pub fn remove_event_listener(&self, ty: SceneEventType, handle: ListenerHandle)

EventDispatcher.removeEventListener( type, listener ). A handle that is not registered for ty is ignored, as three ignores an unknown listener. Safe to call from inside a listener, on itself or any other: a dispatch already under way still calls every listener it started with.

Source

pub fn dispatch_event(&self, event: &SceneEvent)

EventDispatcher.dispatchEvent( event ): calls every listener of the event’s type, in the order they were added, with this node as the target. The list is copied first and no borrow of the object is held during the calls, so a listener may borrow the node, change the tree (which dispatches again) or add and remove listeners.

Source

pub fn get_object_by_id(&self, id: u32) -> Option<ObjectRef>

Object3D.getObjectById( id ).

Source

pub fn get_object_by_name(&self, name: &str) -> Option<ObjectRef>

Object3D.getObjectByName( name ).

Source

pub fn get_object_by_property( &self, test: &dyn Fn(&Object3D) -> bool, ) -> Option<ObjectRef>

Object3D.getObjectByProperty( name, value ). Rust has no dynamic property lookup, so the property test is a predicate.

Source

pub fn get_objects_by_property( &self, test: &dyn Fn(&Object3D) -> bool, ) -> Vec<ObjectRef>

Object3D.getObjectsByProperty( name, value, result ).

Source

pub fn traverse(&self, callback: &mut dyn FnMut(&ObjectRef))

Object3D.traverse( callback ).

Source

pub fn traverse_visible(&self, callback: &mut dyn FnMut(&ObjectRef))

Object3D.traverseVisible( callback ).

Source

pub fn traverse_ancestors(&self, callback: &mut dyn FnMut(&ObjectRef))

Object3D.traverseAncestors( callback ).

Source

pub fn update_matrix_world(&self, force: bool)

Object3D.updateMatrixWorld( force ).

Source

pub fn update_world_matrix(&self, update_parents: bool, update_children: bool)

Object3D.updateWorldMatrix( updateParents, updateChildren ).

Source

pub fn get_world_position(&self) -> Vector3

Object3D.getWorldPosition( target ).

Source

pub fn get_world_quaternion(&self) -> Quaternion

Object3D.getWorldQuaternion( target ).

Source

pub fn get_world_scale(&self) -> Vector3

Object3D.getWorldScale( target ).

Source

pub fn get_world_direction(&self) -> Vector3

Object3D.getWorldDirection( target ).

Source

pub fn local_to_world(&self, vector: &mut Vector3)

Object3D.localToWorld( vector ).

Source

pub fn world_to_local(&self, vector: &mut Vector3)

Object3D.worldToLocal( vector ).

Source

pub fn look_at(&self, target: &Vector3)

Object3D.lookAt( vector ), parent rotation included.

Source

pub fn apply_matrix4(&self, m: &Matrix4)

Object3D.applyMatrix4( matrix ) — the inherent method, reached through the cell so attach() can use it.

Source§

impl ObjectRef

Source

pub fn raycast(&self, raycaster: &Raycaster, intersects: &mut Vec<Intersection>)

object.raycast( raycaster, intersects ) — push this object’s hits (unsorted) onto intersects. Dispatches on the subclass in the payload; an object that draws nothing has nothing to hit.

Methods from Deref<Target = RefCell<Object3D>>§

1.24.0 · Source

pub fn replace(&self, t: T) -> T

Replaces the wrapped value with a new one, returning the old value, without deinitializing either one.

This function corresponds to std::mem::replace.

§Panics

Panics if the value is currently borrowed.

§Examples
use std::cell::RefCell;
let cell = RefCell::new(5);
let old_value = cell.replace(6);
assert_eq!(old_value, 5);
assert_eq!(cell, RefCell::new(6));
1.35.0 · Source

pub fn replace_with<F>(&self, f: F) -> T
where F: FnOnce(&mut T) -> T,

Replaces the wrapped value with a new one computed from f, returning the old value, without deinitializing either one.

§Panics

Panics if the value is currently borrowed.

§Examples
use std::cell::RefCell;
let cell = RefCell::new(5);
let old_value = cell.replace_with(|&mut old| old + 1);
assert_eq!(old_value, 5);
assert_eq!(cell, RefCell::new(6));
1.24.0 · Source

pub fn swap(&self, other: &RefCell<T>)

Swaps the wrapped value of self with the wrapped value of other, without deinitializing either one.

This function corresponds to std::mem::swap.

§Panics

Panics if the value in either RefCell is currently borrowed, or if self and other point to the same RefCell.

§Examples
use std::cell::RefCell;
let c = RefCell::new(5);
let d = RefCell::new(6);
c.swap(&d);
assert_eq!(c, RefCell::new(6));
assert_eq!(d, RefCell::new(5));
1.0.0 · Source

pub fn borrow(&self) -> Ref<'_, T>

Immutably borrows the wrapped value.

The borrow lasts until the returned Ref exits scope. Multiple immutable borrows can be taken out at the same time.

§Panics

Panics if the value is currently mutably borrowed. For a non-panicking variant, use try_borrow.

§Examples
use std::cell::RefCell;

let c = RefCell::new(5);

let borrowed_five = c.borrow();
let borrowed_five2 = c.borrow();

An example of panic:

ⓘ
use std::cell::RefCell;

let c = RefCell::new(5);

let m = c.borrow_mut();
let b = c.borrow(); // this causes a panic
1.13.0 · Source

pub fn try_borrow(&self) -> Result<Ref<'_, T>, BorrowError>

Immutably borrows the wrapped value, returning an error if the value is currently mutably borrowed.

The borrow lasts until the returned Ref exits scope. Multiple immutable borrows can be taken out at the same time.

This is the non-panicking variant of borrow.

§Examples
use std::cell::RefCell;

let c = RefCell::new(5);

{
    let m = c.borrow_mut();
    assert!(c.try_borrow().is_err());
}

{
    let m = c.borrow();
    assert!(c.try_borrow().is_ok());
}
1.0.0 · Source

pub fn borrow_mut(&self) -> RefMut<'_, T>

Mutably borrows the wrapped value.

The borrow lasts until the returned RefMut or all RefMuts derived from it exit scope. The value cannot be borrowed while this borrow is active.

§Panics

Panics if the value is currently borrowed. For a non-panicking variant, use try_borrow_mut.

§Examples
use std::cell::RefCell;

let c = RefCell::new("hello".to_owned());

*c.borrow_mut() = "bonjour".to_owned();

assert_eq!(&*c.borrow(), "bonjour");

An example of panic:

ⓘ
use std::cell::RefCell;

let c = RefCell::new(5);
let m = c.borrow();

let b = c.borrow_mut(); // this causes a panic
1.13.0 · Source

pub fn try_borrow_mut(&self) -> Result<RefMut<'_, T>, BorrowMutError>

Mutably borrows the wrapped value, returning an error if the value is currently borrowed.

The borrow lasts until the returned RefMut or all RefMuts derived from it exit scope. The value cannot be borrowed while this borrow is active.

This is the non-panicking variant of borrow_mut.

§Examples
use std::cell::RefCell;

let c = RefCell::new(5);

{
    let m = c.borrow();
    assert!(c.try_borrow_mut().is_err());
}

assert!(c.try_borrow_mut().is_ok());
1.12.0 · Source

pub fn as_ptr(&self) -> *mut T

Returns a raw pointer to the underlying data in this cell.

§Examples
use std::cell::RefCell;

let c = RefCell::new(5);

let ptr = c.as_ptr();
1.37.0 · Source

pub unsafe fn try_borrow_unguarded(&self) -> Result<&T, BorrowError>

Immutably borrows the wrapped value, returning an error if the value is currently mutably borrowed.

§Safety

Unlike RefCell::borrow, this method is unsafe because it does not return a Ref, thus leaving the borrow flag untouched. Mutably borrowing the RefCell while the reference returned by this method is alive is undefined behavior.

§Examples
use std::cell::RefCell;

let c = RefCell::new(5);

{
    let m = c.borrow_mut();
    assert!(unsafe { c.try_borrow_unguarded() }.is_err());
}

{
    let m = c.borrow();
    assert!(unsafe { c.try_borrow_unguarded() }.is_ok());
}
1.50.0 · Source

pub fn take(&self) -> T

Takes the wrapped value, leaving Default::default() in its place.

§Panics

Panics if the value is currently borrowed.

§Examples
use std::cell::RefCell;

let c = RefCell::new(5);
let five = c.take();

assert_eq!(five, 5);
assert_eq!(c.into_inner(), 0);

Trait Implementations§

Source§

impl Clone for ObjectRef

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for ObjectRef

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Deref for ObjectRef

Source§

type Target = RefCell<Object3D>

The resulting type after dereferencing.
Source§

fn deref(&self) -> &Self::Target

Dereferences the value.

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<P, T> Receiver for P
where P: Deref<Target = T> + ?Sized, T: ?Sized,

Source§

type Target = T

🔬This is a nightly-only experimental API. (arbitrary_self_types)
The target type on which the method may be called.
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.