Struct SCNReferenceNode

#[repr(C)]
pub struct SCNReferenceNode { /* private fields */ }

Available on crate features SCNNode and SCNReferenceNode only.

Node that references an external file.

See also Apple’s documentation

Implementations

impl SCNReferenceNode

pub unsafe fn initWithURL( this: Allocated<Self>, reference_url: &NSURL, ) -> Option<Retained<Self>>

Creates a reference node with a url.

pub unsafe fn initWithCoder( this: Allocated<Self>, a_decoder: &NSCoder, ) -> Option<Retained<Self>>

Support coding and decoding via NSKeyedArchiver.

pub unsafe fn referenceNodeWithURL( reference_url: &NSURL, ) -> Option<Retained<Self>>

Creates a reference node with a url.

pub unsafe fn referenceURL(&self) -> Retained<NSURL>

Specifies the url to resolve.

pub unsafe fn setReferenceURL(&self, reference_url: &NSURL)

Setter for referenceURL.

pub unsafe fn loadingPolicy(&self) -> SCNReferenceLoadingPolicy

Specifies when to load the reference. see SCNReferenceLoadingPolicy above. Defaults to SCNReferenceLoadingPolicyImmediately.

pub unsafe fn setLoadingPolicy(&self, loading_policy: SCNReferenceLoadingPolicy)

Setter for loadingPolicy.

pub unsafe fn load(&self)

Force the reference to be loaded if it hasn’t been loaded already. The resolved nodes will be added as child nodes of the receiver.

pub unsafe fn unload(&self)

Remove the child nodes and mark as unloaded.

pub unsafe fn isLoaded(&self) -> bool

Indicates whether the referenced URL has been loaded.

impl SCNReferenceNode

Methods declared on superclass SCNNode.

pub unsafe fn node() -> Retained<Self>

Creates and initializes a node instance.

impl SCNReferenceNode

Methods declared on superclass NSObject.

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn new() -> Retained<Self>

Methods from Deref<Target = SCNNode>

pub unsafe fn addAudioPlayer(&self, player: &SCNAudioPlayer)

Available on crate feature SCNAudioSource only.

Add an audio player to the node and starts playing it right away.

pub unsafe fn removeAllAudioPlayers(&self)

Available on crate feature SCNAudioSource only.

Remove all audio players from this node and stop playing them.

pub unsafe fn removeAudioPlayer(&self, player: &SCNAudioPlayer)

Available on crate feature SCNAudioSource only.

Remove the given audio player from this node and stop playing it.

pub unsafe fn audioPlayers(&self) -> Retained<NSArray<SCNAudioPlayer>>

Available on crate feature SCNAudioSource only.

Get an array with all the audio players connected and playing on this node.

pub unsafe fn clone(&self) -> Retained<Self>

Returns a copy of the receiver. The returned instance is autoreleased.

The copy is recursive: every child node will be cloned, too. For a non-recursive copy, use copy instead. The copied nodes will share their attached objects (light, geometry, camera, …) with the original instances; if you want, for example, to change the materials of the copy independently of the original object, you’ll have to copy the geometry of the node separately.

pub unsafe fn flattenedClone(&self) -> Retained<Self>

pub unsafe fn name(&self) -> Option<Retained<NSString>>

Determines the name of the receiver.

pub unsafe fn setName(&self, name: Option<&NSString>)

Setter for name.

pub unsafe fn light(&self) -> Option<Retained<SCNLight>>

Available on crate feature SCNLight only.

Determines the light attached to the receiver.

pub unsafe fn setLight(&self, light: Option<&SCNLight>)

Available on crate feature SCNLight only.

Setter for light.

pub unsafe fn camera(&self) -> Option<Retained<SCNCamera>>

Available on crate feature SCNCamera only.

Determines the camera attached to the receiver.

pub unsafe fn setCamera(&self, camera: Option<&SCNCamera>)

Available on crate feature SCNCamera only.

Setter for camera.

pub unsafe fn geometry(&self) -> Option<Retained<SCNGeometry>>

Available on crate feature SCNGeometry only.

Returns the geometry attached to the receiver.

pub unsafe fn setGeometry(&self, geometry: Option<&SCNGeometry>)

Available on crate feature SCNGeometry only.

Setter for geometry.

pub unsafe fn skinner(&self) -> Option<Retained<SCNSkinner>>

Available on crate feature SCNSkinner only.

Returns the skinner attached to the receiver.

pub unsafe fn setSkinner(&self, skinner: Option<&SCNSkinner>)

Available on crate feature SCNSkinner only.

Setter for skinner.

pub unsafe fn morpher(&self) -> Option<Retained<SCNMorpher>>

Available on crate feature SCNMorpher only.

Returns the morpher attached to the receiver.

pub unsafe fn setMorpher(&self, morpher: Option<&SCNMorpher>)

Available on crate feature SCNMorpher only.

Setter for morpher.

pub unsafe fn transform(&self) -> SCNMatrix4

Available on crate feature SceneKitTypes and crate feature objc2-quartz-core and non-watchOS only.

Determines the receiver’s transform. Animatable.

The transform is the combination of the position, rotation and scale defined below. So when the transform is set, the receiver’s position, rotation and scale are changed to match the new transform.

pub unsafe fn setTransform(&self, transform: SCNMatrix4)

Available on crate feature SceneKitTypes and crate feature objc2-quartz-core and non-watchOS only.

Setter for transform.

pub unsafe fn worldTransform(&self) -> SCNMatrix4

Available on crate feature SceneKitTypes and crate feature objc2-quartz-core and non-watchOS only.

Determines the receiver’s transform in world space (relative to the scene’s root node). Animatable.

pub unsafe fn setWorldTransform(&self, world_transform: SCNMatrix4)

Available on crate feature SceneKitTypes and crate feature objc2-quartz-core and non-watchOS only.

pub unsafe fn position(&self) -> SCNVector3

Available on crate features SceneKitTypes and objc2-core-foundation only.

Determines the receiver’s position. Animatable.

pub unsafe fn setPosition(&self, position: SCNVector3)

Available on crate features SceneKitTypes and objc2-core-foundation only.

Setter for position.

pub unsafe fn worldPosition(&self) -> SCNVector3

Available on crate features SceneKitTypes and objc2-core-foundation only.

Determines the receiver’s position in world space (relative to the scene’s root node).

pub unsafe fn setWorldPosition(&self, world_position: SCNVector3)

Available on crate features SceneKitTypes and objc2-core-foundation only.

Setter for worldPosition.

pub unsafe fn rotation(&self) -> SCNVector4

Available on crate features SceneKitTypes and objc2-core-foundation only.

Determines the receiver’s rotation. Animatable.

The rotation is axis angle rotation. The three first components are the axis, the fourth one is the rotation (in radian).

pub unsafe fn setRotation(&self, rotation: SCNVector4)

Available on crate features SceneKitTypes and objc2-core-foundation only.

Setter for rotation.

pub unsafe fn orientation(&self) -> SCNQuaternion

Available on crate features SceneKitTypes and objc2-core-foundation only.

Determines the receiver’s orientation as a unit quaternion. Animatable.

pub unsafe fn setOrientation(&self, orientation: SCNQuaternion)

Available on crate features SceneKitTypes and objc2-core-foundation only.

Setter for orientation.

pub unsafe fn worldOrientation(&self) -> SCNQuaternion

Available on crate features SceneKitTypes and objc2-core-foundation only.

Determines the receiver’s orientation in world space (relative to the scene’s root node). Animatable.

pub unsafe fn setWorldOrientation(&self, world_orientation: SCNQuaternion)

Available on crate features SceneKitTypes and objc2-core-foundation only.

Setter for worldOrientation.

pub unsafe fn eulerAngles(&self) -> SCNVector3

Available on crate features SceneKitTypes and objc2-core-foundation only.

Determines the receiver’s euler angles. Animatable.

The order of components in this vector matches the axes of rotation:

1. Pitch (the x component) is the rotation about the node’s x-axis (in radians)
2. Yaw (the y component) is the rotation about the node’s y-axis (in radians)
3. Roll (the z component) is the rotation about the node’s z-axis (in radians) SceneKit applies these rotations in the reverse order of the components:
4. first roll
5. then yaw
6. then pitch

pub unsafe fn setEulerAngles(&self, euler_angles: SCNVector3)

Available on crate features SceneKitTypes and objc2-core-foundation only.

Setter for eulerAngles.

pub unsafe fn scale(&self) -> SCNVector3

Available on crate features SceneKitTypes and objc2-core-foundation only.

Determines the receiver’s scale. Animatable.

pub unsafe fn setScale(&self, scale: SCNVector3)

Available on crate features SceneKitTypes and objc2-core-foundation only.

Setter for scale.

pub unsafe fn pivot(&self) -> SCNMatrix4

Available on crate feature SceneKitTypes and crate feature objc2-quartz-core and non-watchOS only.

Determines the receiver’s pivot. Animatable.

pub unsafe fn setPivot(&self, pivot: SCNMatrix4)

Available on crate feature SceneKitTypes and crate feature objc2-quartz-core and non-watchOS only.

Setter for pivot.

pub unsafe fn isHidden(&self) -> bool

Determines whether the receiver is displayed. Defaults to NO. Animatable.

pub unsafe fn setHidden(&self, hidden: bool)

Setter for isHidden.

pub unsafe fn opacity(&self) -> CGFloat

Available on crate feature objc2-core-foundation only.

Determines the opacity of the receiver. Default is 1. Animatable.

pub unsafe fn setOpacity(&self, opacity: CGFloat)

Available on crate feature objc2-core-foundation only.

Setter for opacity.

pub unsafe fn renderingOrder(&self) -> NSInteger

Determines the rendering order of the receiver.

Nodes with greater rendering orders are rendered last. Defaults to 0.

pub unsafe fn setRenderingOrder(&self, rendering_order: NSInteger)

Setter for renderingOrder.

pub unsafe fn castsShadow(&self) -> bool

Determines if the node is rendered in shadow maps. Defaults to YES.

pub unsafe fn setCastsShadow(&self, casts_shadow: bool)

Setter for castsShadow.

pub unsafe fn movabilityHint(&self) -> SCNMovabilityHint

Communicates to SceneKit’s rendering system about how you want to move content in your scene; it does not affect your ability to change the node’s position or add animations or physics to the node. Defaults to SCNMovabilityHintFixed.

pub unsafe fn setMovabilityHint(&self, movability_hint: SCNMovabilityHint)

Setter for movabilityHint.

pub unsafe fn parentNode(&self) -> Option<Retained<SCNNode>>

Returns the parent node of the receiver.

pub unsafe fn childNodes(&self) -> Retained<NSArray<SCNNode>>

Returns the child node array of the receiver.

pub unsafe fn addChildNode(&self, child: &SCNNode)

Appends the node to the receiver’s childNodes array.

Parameter child: The node to be added to the receiver’s childNodes array.

pub unsafe fn insertChildNode_atIndex(&self, child: &SCNNode, index: NSUInteger)

Insert a node in the childNodes array at the specified index.

Parameter child: The node to insert.

Parameter index: Index in the childNodes array to insert the node.

pub unsafe fn removeFromParentNode(&self)

Removes the node from the childNodes array of the receiver’s parentNode.

pub unsafe fn replaceChildNode_with( &self, old_child: &SCNNode, new_child: &SCNNode, )

Remove `child’ from the childNode array of the receiver and insert ‘child2’ if non-nil in its position.

If the parentNode of `child’ is not the receiver, the behavior is undefined.

Parameter oldChild: The node to replace in the childNodes array.

Parameter newChild: The new node that will replace the previous one.

pub unsafe fn childNodeWithName_recursively( &self, name: &NSString, recursively: bool, ) -> Option<Retained<SCNNode>>

Returns the first node found in the node tree with the specified name.

The search uses a pre-order tree traversal.

Parameter name: The name of the node you are searching for.

Parameter recursively: Set to YES if you want the search to look through the sub-nodes recursively.

pub unsafe fn childNodesPassingTest( &self, predicate: &Block<dyn Fn(NonNull<SCNNode>, NonNull<Bool>) -> Bool + '_>, ) -> Retained<NSArray<SCNNode>>

Available on crate feature block2 only.

Returns the child nodes of the receiver that passes a test in a given Block.

The search is recursive and uses a pre-order tree traversal.

Parameter predicate: The block to apply to child nodes of the receiver. The block takes two arguments: “child” is a child node and “stop” is a reference to a Boolean value. The block can set the value to YES to stop further processing of the node hierarchy. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block. The Block returns a Boolean value that indicates whether “child” passed the test.

pub unsafe fn enumerateChildNodesUsingBlock( &self, block: &Block<dyn Fn(NonNull<SCNNode>, NonNull<Bool>) + '_>, )

Available on crate feature block2 only.

Executes a given block on each child node under the receiver.

The search is recursive and uses a pre-order tree traversal.

Parameter block: The block to apply to child nodes of the receiver. The block takes two arguments: “child” is a child node and “stop” is a reference to a Boolean value. The block can set the value to YES to stop further processing of the node hierarchy. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

pub unsafe fn enumerateHierarchyUsingBlock( &self, block: &Block<dyn Fn(NonNull<SCNNode>, NonNull<Bool>) + '_>, )

Available on crate feature block2 only.

Executes a given block on the receiver and its child nodes.

The search is recursive and uses a pre-order tree traversal.

Parameter block: The block to apply to the receiver and its child nodes. The block takes two arguments: “node” is a node in the hierarchy of the receiver (including the receiver) and “stop” is a reference to a Boolean value. The block can set the value to YES to stop further processing of the node hierarchy. The stop argument is an out-only argument. You should only ever set this Boolean to YES within the Block.

pub unsafe fn convertPosition_toNode( &self, position: SCNVector3, node: Option<&SCNNode>, ) -> SCNVector3

Available on crate features SceneKitTypes and objc2-core-foundation only.

Converts a position from the receiver’s coordinate system to that of the specified node.

Parameter position: A position specified in the local coordinate system of the receiver.

Parameter node: The node into whose coordinate system “position” is to be converted. If “node” is nil, this method instead converts to world coordinates.

pub unsafe fn convertPosition_fromNode( &self, position: SCNVector3, node: Option<&SCNNode>, ) -> SCNVector3

Available on crate features SceneKitTypes and objc2-core-foundation only.

Converts a position from the coordinate system of a given node to that of the receiver.

Parameter position: A position specified in the local coordinate system of “node”.

Parameter node: The node from whose coordinate system “position” is to be converted. If “node” is nil, this method instead converts from world coordinates.

pub unsafe fn convertVector_toNode( &self, vector: SCNVector3, node: Option<&SCNNode>, ) -> SCNVector3

Available on crate features SceneKitTypes and objc2-core-foundation only.

Converts a vector from the coordinate system of a given node to that of the receiver.

Parameter vector: A vector specified in the local coordinate system the receiver.

Parameter node: The node defining the space from which the vector should be transformed. If “node” is nil, this method instead converts from world coordinates.

Returns: vector transformed from receiver local space to node local space.

pub unsafe fn convertVector_fromNode( &self, vector: SCNVector3, node: Option<&SCNNode>, ) -> SCNVector3

Available on crate features SceneKitTypes and objc2-core-foundation only.

Converts a vector from the coordinate system of a given node to that of the receiver.

Parameter vector: A vector specified in the local coordinate system of “node”.

Parameter node: The node defining the space to which the vector should be transformed to. If “node” is nil, this method instead converts from world coordinates.

Returns: vector transformed from node space to reveiver local space.

pub unsafe fn convertTransform_toNode( &self, transform: SCNMatrix4, node: Option<&SCNNode>, ) -> SCNMatrix4

Available on crate feature SceneKitTypes and crate feature objc2-quartz-core and non-watchOS only.

Converts a transform from the receiver’s coordinate system to that of the specified node.

Parameter transform: A transform specified in the local coordinate system of the receiver.

Parameter node: The node into whose coordinate system “transform” is to be converted. If “node” is nil, this method instead converts to world coordinates.

pub unsafe fn convertTransform_fromNode( &self, transform: SCNMatrix4, node: Option<&SCNNode>, ) -> SCNMatrix4

Available on crate feature SceneKitTypes and crate feature objc2-quartz-core and non-watchOS only.

Converts a transform from the coordinate system of a given node to that of the receiver.

Parameter transform: A transform specified in the local coordinate system of “node”.

Parameter node: The node from whose coordinate system “transform” is to be converted. If “node” is nil, this method instead converts from world coordinates.

pub unsafe fn physicsBody(&self) -> Option<Retained<SCNPhysicsBody>>

Available on crate feature SCNPhysicsBody only.

The description of the physics body of the receiver.

Default is nil.

pub unsafe fn setPhysicsBody(&self, physics_body: Option<&SCNPhysicsBody>)

Available on crate feature SCNPhysicsBody only.

Setter for physicsBody.

pub unsafe fn physicsField(&self) -> Option<Retained<SCNPhysicsField>>

Available on crate feature SCNPhysicsField only.

The description of the physics field of the receiver.

Default is nil.

pub unsafe fn setPhysicsField(&self, physics_field: Option<&SCNPhysicsField>)

Available on crate feature SCNPhysicsField only.

Setter for physicsField.

pub unsafe fn constraints(&self) -> Option<Retained<NSArray<SCNConstraint>>>

Available on crate feature SCNConstraint only.

An array of SCNConstraint that are applied to the receiver.

Adding or removing a constraint can be implicitly animated based on the current transaction.

pub unsafe fn setConstraints( &self, constraints: Option<&NSArray<SCNConstraint>>, )

Available on crate feature SCNConstraint only.

Setter for constraints.

pub unsafe fn filters(&self) -> Option<Retained<NSArray<CIFilter>>>

Available on crate feature objc2-core-image and non-watchOS only.

An array of Core Image filters that are applied to the rendering of the receiver and its child nodes. Animatable.

Defaults to nil. Filter properties should be modified by calling setValue:forKeyPath: on each node that the filter is attached to. If the inputs of the filter are modified directly after the filter is attached to a node, the behavior is undefined.

pub unsafe fn setFilters(&self, filters: Option<&NSArray<CIFilter>>)

Available on crate feature objc2-core-image and non-watchOS only.

Setter for filters.

pub unsafe fn presentationNode(&self) -> Retained<SCNNode>

Returns the presentation node.

Returns a copy of the node containing all the properties as they were at the start of the current transaction, with any active animations applied. This gives a close approximation to the version of the node that is currently displayed. The effect of attempting to modify the returned node in any way is undefined. The returned node has no parent and no child nodes.

pub unsafe fn isPaused(&self) -> bool

Controls whether or not the node’s actions and animations are updated or paused. Defaults to NO.

pub unsafe fn setPaused(&self, paused: bool)

Setter for isPaused.

pub unsafe fn rendererDelegate( &self, ) -> Option<Retained<ProtocolObject<dyn SCNNodeRendererDelegate>>>

Specifies the receiver’s renderer delegate object.

Setting a renderer delegate prevents the SceneKit renderer from drawing the node and lets you use custom OpenGL code instead. The preferred way to customize the rendering is to tweak the material properties of the different materials of the node’s geometry. SCNMaterial conforms to the SCNShadable protocol and allows for more advanced rendering using GLSL. You would typically use a renderer delegate with a node that has no geometry and only serves as a location in space. An example would be attaching a particle system to that node and render it with custom OpenGL code.

pub unsafe fn setRendererDelegate( &self, renderer_delegate: Option<&ProtocolObject<dyn SCNNodeRendererDelegate>>, )

Setter for rendererDelegate.

pub unsafe fn hitTestWithSegmentFromPoint_toPoint_options( &self, point_a: SCNVector3, point_b: SCNVector3, options: Option<&NSDictionary<NSString, AnyObject>>, ) -> Retained<NSArray<SCNHitTestResult>>

Available on crate features SCNHitTest and SceneKitTypes and objc2-core-foundation only.

Returns an array of SCNHitTestResult for each node in the receiver’s sub tree that intersects the specified segment.

Parameter pointA: The first point of the segment relative to the receiver.

Parameter pointB: The second point of the segment relative to the receiver.

Parameter options: Optional parameters (see the “Hit test options” section in SCNSceneRenderer.h for the available options).

See SCNSceneRenderer.h for a screen-space hit testing method.

pub unsafe fn categoryBitMask(&self) -> NSUInteger

Defines what logical ‘categories’ the receiver belongs too. Defaults to 1.

Categories can be used to

1. exclude nodes from the influence of a given light (see SCNLight.categoryBitMask)
2. include/exclude nodes from render passes (see SCNTechnique.h)
3. specify which nodes to use when hit-testing (see SCNHitTestOptionCategoryBitMask)

pub unsafe fn setCategoryBitMask(&self, category_bit_mask: NSUInteger)

Setter for categoryBitMask.

pub unsafe fn worldUp(&self) -> SCNVector3

Available on crate features SceneKitTypes and objc2-core-foundation only.

The local unit Y axis (0, 1, 0) in world space.

pub unsafe fn worldRight(&self) -> SCNVector3

Available on crate features SceneKitTypes and objc2-core-foundation only.

The local unit X axis (1, 0, 0) in world space.

pub unsafe fn worldFront(&self) -> SCNVector3

Available on crate features SceneKitTypes and objc2-core-foundation only.

The local unit -Z axis (0, 0, -1) in world space.

pub unsafe fn lookAt(&self, world_target: SCNVector3)

Available on crate features SceneKitTypes and objc2-core-foundation only.

Convenience for calling lookAt:up:localFront: with worldUp set to self.worldUp and localFront [SCNNode localFront].

Parameter worldTarget: target position in world space.

pub unsafe fn lookAt_up_localFront( &self, world_target: SCNVector3, world_up: SCNVector3, local_front: SCNVector3, )

Available on crate features SceneKitTypes and objc2-core-foundation only.

Set the orientation of the node so its front vector is pointing toward a given target. Using a reference up vector in world space and a front vector in local space.

Parameter worldTarget: position in world space.

Parameter worldUp: the up vector in world space.

Parameter localFront: the front vector in local space.

pub unsafe fn localTranslateBy(&self, translation: SCNVector3)

Available on crate features SceneKitTypes and objc2-core-foundation only.

Translate the current node position along the given vector in local space.

Parameter translation: the translation in local space.

pub unsafe fn localRotateBy(&self, rotation: SCNQuaternion)

Available on crate features SceneKitTypes and objc2-core-foundation only.

Apply a the given rotation to the current one.

Parameter rotation: rotation in local space.

pub unsafe fn rotateBy_aroundTarget( &self, world_rotation: SCNQuaternion, world_target: SCNVector3, )

Available on crate features SceneKitTypes and objc2-core-foundation only.

Apply a rotation relative to a target point in parent space.

Parameter worldRotation: rotation to apply in world space.

Parameter worldTarget: position of the target in world space.

pub unsafe fn focusBehavior(&self) -> SCNNodeFocusBehavior

Controls the behavior of the receiver regarding the UIFocus system. Defaults to SCNNodeFocusBehaviorNone.

pub unsafe fn setFocusBehavior(&self, focus_behavior: SCNNodeFocusBehavior)

Setter for focusBehavior.

pub unsafe fn addParticleSystem(&self, system: &SCNParticleSystem)

Available on crate feature SCNParticleSystem only.

pub unsafe fn removeAllParticleSystems(&self)

Available on crate feature SCNParticleSystem only.

pub unsafe fn removeParticleSystem(&self, system: &SCNParticleSystem)

Available on crate feature SCNParticleSystem only.

pub unsafe fn particleSystems( &self, ) -> Option<Retained<NSArray<SCNParticleSystem>>>

Available on crate feature SCNParticleSystem only.

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for SCNReferenceNode

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for SCNReferenceNode

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<SCNNode> for SCNReferenceNode

fn as_ref(&self) -> &SCNNode

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<SCNReferenceNode> for SCNReferenceNode

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for SCNReferenceNode

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for SCNReferenceNode

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl Borrow<SCNNode> for SCNReferenceNode

fn borrow(&self) -> &SCNNode

Immutably borrows from an owned value.

impl ClassType for SCNReferenceNode

const NAME: &'static str = "SCNReferenceNode"

The name of the Objective-C class that this type represents.

type Super = SCNNode

The superclass of this class.

type ThreadKind = <<SCNReferenceNode as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl CopyingHelper for SCNReferenceNode

type Result = SCNReferenceNode

The immutable counterpart of the type, or Self if the type has no immutable counterpart.

impl Debug for SCNReferenceNode

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

Formats the value using the given formatter.

impl Deref for SCNReferenceNode

type Target = SCNNode

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for SCNReferenceNode

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 Message for SCNReferenceNode

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSCoding for SCNReferenceNode

unsafe fn encodeWithCoder(&self, coder: &NSCoder)

where Self: Sized + Message,

Available on crate feature NSCoder only.

unsafe fn initWithCoder( this: Allocated<Self>, coder: &NSCoder, ) -> Option<Retained<Self>>

where Self: Sized + Message,

Available on crate feature NSCoder only.

impl NSCopying for SCNReferenceNode

fn copy(&self) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Returns a new instance that’s a copy of the receiver.

unsafe fn copyWithZone(&self, zone: *mut NSZone) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Returns a new instance that’s a copy of the receiver.

impl NSObjectProtocol for SCNReferenceNode

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl NSSecureCoding for SCNReferenceNode

unsafe fn supportsSecureCoding() -> bool

where Self: Sized + ClassType,

impl PartialEq for SCNReferenceNode

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 RefEncode for SCNReferenceNode

const ENCODING_REF: Encoding = <SCNNode as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl SCNActionable for SCNReferenceNode

Available on crate feature SCNAction only.

unsafe fn runAction(&self, action: &SCNAction)

where Self: Sized + Message,

Adds an action to the list of actions executed by the node.

unsafe fn runAction_completionHandler( &self, action: &SCNAction, block: Option<&Block<dyn Fn()>>, )

where Self: Sized + Message,

Available on crate feature block2 only.

Adds an action to the list of actions executed by the node. Your block is called when the action completes.

unsafe fn runAction_forKey(&self, action: &SCNAction, key: Option<&NSString>)

where Self: Sized + Message,

Adds an identifiable action to the list of actions executed by the node.

unsafe fn runAction_forKey_completionHandler( &self, action: &SCNAction, key: Option<&NSString>, block: Option<&Block<dyn Fn()>>, )

where Self: Sized + Message,

Available on crate feature block2 only.

Adds an identifiable action to the list of actions executed by the node. Your block is called when the action completes.

unsafe fn hasActions(&self) -> bool

where Self: Sized + Message,

Returns a Boolean value that indicates whether the node is executing actions.

unsafe fn actionForKey(&self, key: &NSString) -> Option<Retained<SCNAction>>

where Self: Sized + Message,

Returns an action associated with a specific key.

unsafe fn removeActionForKey(&self, key: &NSString)

where Self: Sized + Message,

Removes an action associated with a specific key.

unsafe fn removeAllActions(&self)

where Self: Sized + Message,

Ends and removes all actions from the node.

unsafe fn actionKeys(&self) -> Retained<NSArray<NSString>>

where Self: Sized + Message,

Returns an array containing the keys of all actions currently attached to the receiver.

impl SCNAnimatable for SCNReferenceNode

Available on crate feature SCNAnimation only.

unsafe fn addAnimation_forKey( &self, animation: &ProtocolObject<dyn SCNAnimationProtocol>, key: Option<&NSString>, )

where Self: Sized + Message,

Adds and runs an animation

unsafe fn addAnimationPlayer_forKey( &self, player: &SCNAnimationPlayer, key: Option<&NSString>, )

where Self: Sized + Message,

Add an animation player.

unsafe fn removeAllAnimations(&self)

where Self: Sized + Message,

Remove all animations.

unsafe fn removeAllAnimationsWithBlendOutDuration(&self, duration: CGFloat)

where Self: Sized + Message,

Available on crate feature objc2-core-foundation only.

Smoothly remove all animations.

unsafe fn removeAnimationForKey(&self, key: &NSString)

where Self: Sized + Message,

Remove the animation with the given identifier.

unsafe fn removeAnimationForKey_blendOutDuration( &self, key: &NSString, duration: CGFloat, )

where Self: Sized + Message,

Available on crate feature objc2-core-foundation only.

Smoothly remove the animation with the given identifier.

unsafe fn animationKeys(&self) -> Retained<NSArray<NSString>>

where Self: Sized + Message,

Returns an array containing the keys of all animations currently attached to the receiver.

unsafe fn animationPlayerForKey( &self, key: &NSString, ) -> Option<Retained<SCNAnimationPlayer>>

where Self: Sized + Message,

Returns the animation player with the given identifier

unsafe fn removeAnimationForKey_fadeOutDuration( &self, key: &NSString, duration: CGFloat, )

where Self: Sized + Message,

👎Deprecated

Available on crate feature objc2-core-foundation only.

Smoothly remove the animation with the given identifier.

unsafe fn animationForKey( &self, key: &NSString, ) -> Option<Retained<CAAnimation>>

where Self: Sized + Message,

👎Deprecated

Available on crate feature objc2-quartz-core and non-watchOS only.

Returns the animation with the given identifier

unsafe fn pauseAnimationForKey(&self, key: &NSString)

where Self: Sized + Message,

👎Deprecated: Use -[SCNAnimationPlayer setPaused:] instead

Pause the animation with the given identifier.

unsafe fn resumeAnimationForKey(&self, key: &NSString)

where Self: Sized + Message,

👎Deprecated: Use -[SCNAnimationPlayer setPaused:] instead

Resume the animation with the given identifier.

unsafe fn setSpeed_forAnimationKey(&self, speed: CGFloat, key: &NSString)

where Self: Sized + Message,

👎Deprecated: Use -[SCNAnimationPlayer setSpeed:] instead

Available on crate feature objc2-core-foundation only.

Update the animation speed of the animation with the given identifier.

unsafe fn isAnimationForKeyPaused(&self, key: &NSString) -> bool

where Self: Sized + Message,

👎Deprecated: Use -[SCNAnimationPlayer paused] instead

Returns whether the animation for the specified identifier is paused.

impl SCNBoundingVolume for SCNReferenceNode

Available on crate feature SCNBoundingVolume only.

unsafe fn getBoundingBoxMin_max( &self, min: *mut SCNVector3, max: *mut SCNVector3, ) -> bool

where Self: Sized + Message,

Available on crate features SceneKitTypes and objc2-core-foundation only.

Fill the min and max vectors with the min and max vertex of the bounding box.

unsafe fn setBoundingBoxMin_max( &self, min: *mut SCNVector3, max: *mut SCNVector3, )

where Self: Sized + Message,

Available on crate features SceneKitTypes and objc2-core-foundation only.

Override the receiver bounding box with the min and max vectors provided (in local space of the receiver).

unsafe fn getBoundingSphereCenter_radius( &self, center: *mut SCNVector3, radius: *mut CGFloat, ) -> bool

where Self: Sized + Message,

Available on crate features SceneKitTypes and objc2-core-foundation only.

Fill the center vector with the center of the bounding sphere and store the radius of the bounding sphere in ‘radius’.

impl DowncastTarget for SCNReferenceNode

impl Eq for SCNReferenceNode