Node

public class Node

Known Direct Subclasses AnchorNode, AugmentedFaceNode, BaseTransformableNode, Camera, SkeletonNode, Sun AnchorNode Node that is automatically positioned in world space based on an ARCore Anchor.  AugmentedFaceNode Node used to render visual effects on a face with ARCore's AugmentedFace feature.  BaseTransformableNode Base class for nodes that can be transformed using gestures from TransformationSystem.  Camera Represents a virtual camera, which determines the perspective through which the scene is viewed.  SkeletonNode A Node that provides mappings between the bones of a skinned ModelRenderable and a set of Nodes.  Sun Represents the "sun" - the default directional light in the scene.

Known Indirect Subclasses TransformableNode TransformableNode Node that can be selected, translated, rotated, and scaled using gestures from TransformationSystem.

A Node represents a transformation within the scene graph's hierarchy. It can contain a renderable for the rendering engine to render.

Each node can have an arbitrary number of child nodes and one parent. The parent may be another node, or the scene.

Nested Classes

interface	Node.LifecycleListener		Interface definition for callbacks to be invoked when node lifecycle events occur.
interface	Node.OnTapListener		Interface definition for a callback to be invoked when a node is tapped.
interface	Node.OnTouchListener		Interface definition for a callback to be invoked when a touch event is dispatched to this node.
interface	Node.TransformChangedListener		Interface definition for callbacks to be invoked when the transformation of the node changes.

Public Constructors

Node() Creates a node with no parent.

Public Methods

void	addLifecycleListener(Node.LifecycleListener lifecycleListener) Adds a listener that will be called when node lifecycle events occur.
void	addTransformChangedListener(Node.TransformChangedListener transformChangedListener) Adds a listener that will be called when the node's transformation changes.
void	callOnHierarchy(Consumer<Node> consumer) Traverses the hierarchy and call a method on each node (including this node).
Node	findInHierarchy(Predicate<Node> condition) Traverses the hierarchy to find the first node (including this node) that meets a condition.
final Vector3	getBack() Gets the world-space back vector (+z) of this node.
CollisionShape	getCollisionShape() Gets the shape to use for collisions with this node.
final Vector3	getDown() Gets the world-space down vector (-y) of this node.
final Vector3	getForward() Gets the world-space forward vector (-z) of this node.
final Vector3	getLeft() Gets the world-space left vector (-x) of this node.
Light	getLight() Gets the current light, which is mutable.
final Vector3	getLocalPosition() Gets a copy of the nodes position relative to its parent (local-space).
final Quaternion	getLocalRotation() Gets a copy of the nodes rotation relative to its parent (local-space).
final Vector3	getLocalScale() Gets a copy of the nodes scale relative to its parent (local-space).
final String	getName() Returns the name of the node.
final Node	getParent() Returns the parent of this node.
Renderable	getRenderable() Gets the renderable to display for this node.
final Vector3	getRight() Gets the world-space right vector (+x) of this node.
final Scene	getScene() Returns the scene that this node is part of, null if it isn't part of any scene.
final Vector3	getUp() Gets the world-space up vector (+y) of this node.
final Vector3	getWorldPosition() Get a copy of the nodes world-space position.
final Quaternion	getWorldRotation() Gets a copy of the nodes world-space rotation.
final Vector3	getWorldScale() Gets a copy of the nodes world-space scale.
final boolean	isActive() Returns true if the node is active.
final boolean	isDescendantOf(NodeParent ancestor) Checks whether the given node parent is an ancestor of this node recursively.
final boolean	isEnabled() Gets the enabled state of this node.
boolean	isTopLevel() Returns true if this node is top level.
final Vector3	localToWorldDirection(Vector3 direction) Converts a direction from the local-space of this node to world-space.
final Vector3	localToWorldPoint(Vector3 point) Converts a point in the local-space of this node to world-space.
void	onActivate() Handles when this node becomes active.
void	onDeactivate() Handles when this node becomes inactivate.
boolean	onTouchEvent(HitTestResult hitTestResult, MotionEvent motionEvent) Handles when this node is touched.
void	onTransformChange(Node originatingNode) Handles when this node's transformation is changed.
void	onUpdate(FrameTime frameTime) Handles when this node is updated.
void	removeLifecycleListener(Node.LifecycleListener lifecycleListener) Removes a listener that will be called when node lifecycle events occur.
void	removeTransformChangedListener(Node.TransformChangedListener transformChangedListener) Removes a listener that will be called when the node's transformation changes.
void	setCollisionShape(CollisionShape collisionShape) Sets the shape to used to detect collisions for this Node.
final void	setEnabled(boolean enabled) Sets the enabled state of this node.
void	setLight(Light light) Sets the Light to display.
void	setLocalPosition(Vector3 position) Sets the position of this node relative to its parent (local-space).
void	setLocalRotation(Quaternion rotation) Sets the rotation of this node relative to its parent (local-space).
void	setLocalScale(Vector3 scale) Sets the scale of this node relative to its parent (local-space).
final void	setLookDirection(Vector3 lookDirection) Sets the direction that the node is looking at in world-space.
final void	setLookDirection(Vector3 lookDirection, Vector3 upDirection) Sets the direction that the node is looking at in world-space.
final void	setName(String name) Sets the name of this node.
void	setOnTapListener(Node.OnTapListener onTapListener) Registers a callback to be invoked when this node is tapped.
void	setOnTouchListener(Node.OnTouchListener onTouchListener) Registers a callback to be invoked when a touch event is dispatched to this node.
void	setParent(NodeParent parent) Changes the parent node of this node.
void	setRenderable(Renderable renderable) Sets the Renderable to display for this node.
void	setWorldPosition(Vector3 position) Sets the world-space position of this node.
void	setWorldRotation(Quaternion rotation) Sets the world-space rotation of this node.
void	setWorldScale(Vector3 scale) Sets the world-space scale of this node.
String	toString()
final Vector3	worldToLocalDirection(Vector3 direction) Converts a direction from world-space to the local-space of this node.
final Vector3	worldToLocalPoint(Vector3 point) Converts a point in world-space to the local-space of this node.

Protected Methods

final boolean	canAddChild(Node child, StringBuilder failureReason)
final void	onAddChild(Node child)
final void	onRemoveChild(Node child)

Inherited Methods

From class com.google.ar.sceneform.NodeParent

final void	addChild(Node child) Adds a node as a child of this NodeParent.
void	callOnHierarchy(Consumer<Node> consumer) Traverse the hierarchy and call a method on each node.
boolean	canAddChild(Node child, StringBuilder failureReason)
Node	findByName(String name) Traverse the hierarchy to find the first node with a given name.
Node	findInHierarchy(Predicate<Node> condition) Traverse the hierarchy to find the first node that meets a condition.
final List<Node>	getChildren() Returns an immutable list of this parent's children.
void	onAddChild(Node child)
void	onRemoveChild(Node child)
final void	removeChild(Node child) Removes a node from the children of this NodeParent.

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

Public Constructors

public Node ()

Creates a node with no parent.

Public Methods

public void addLifecycleListener (Node.LifecycleListener lifecycleListener)

Adds a listener that will be called when node lifecycle events occur. The listeners will be called in the order in which they were added.

Parameters

lifecycleListener

public void addTransformChangedListener (Node.TransformChangedListener transformChangedListener)

Adds a listener that will be called when the node's transformation changes.

Parameters

transformChangedListener

public void callOnHierarchy (Consumer<Node> consumer)

Traverses the hierarchy and call a method on each node (including this node). Traversal is depth first.

Parameters

consumer	the method to call on each node

public Node findInHierarchy (Predicate<Node> condition)

Traverses the hierarchy to find the first node (including this node) that meets a condition. Once the predicate is met, the traversal stops. Traversal is depth first.

Parameters

condition	predicate the defines the conditions of the node to search for.

Returns

• the first node that matches the conditions of the predicate, otherwise null is returned

public final Vector3 getBack ()

Gets the world-space back vector (+z) of this node.

Returns

• a new vector that represents the node's back direction in world-space

public CollisionShape getCollisionShape ()

Gets the shape to use for collisions with this node. If the shape is null and setRenderable(Renderable) is set, then getCollisionShape() is used to detect collisions for this Node.

Returns

• represents a geometric shape, i.e. sphere, box, convex hull.

See Also

• hitTest(Ray)
• hitTestAll(Ray)
• overlapTest(Node)
• overlapTestAll(Node)

public final Vector3 getDown ()

Gets the world-space down vector (-y) of this node.

Returns

• a new vector that represents the node's down direction in world-space

public final Vector3 getForward ()

Gets the world-space forward vector (-z) of this node.

Returns

• a new vector that represents the node's forward direction in world-space

public final Vector3 getLeft ()

Gets the world-space left vector (-x) of this node.

Returns

• a new vector that represents the node's left direction in world-space

public Light getLight ()

Gets the current light, which is mutable.

public final Vector3 getLocalPosition ()

Gets a copy of the nodes position relative to its parent (local-space). If isTopLevel() is true, then this is the same as getWorldPosition().

Returns

• a new vector that represents the node's local-space position

See Also

• setLocalPosition(Vector3)

public final Quaternion getLocalRotation ()

Gets a copy of the nodes rotation relative to its parent (local-space). If isTopLevel() is true, then this is the same as getWorldRotation().

Returns

• a new quaternion that represents the node's local-space rotation

See Also

• setLocalRotation(Quaternion)

public final Vector3 getLocalScale ()

Gets a copy of the nodes scale relative to its parent (local-space). If isTopLevel() is true, then this is the same as getWorldScale().

Returns

• a new vector that represents the node's local-space scale

See Also

• setLocalScale(Vector3)

public final String getName ()

Returns the name of the node. The default value is "Node".

public final Node getParent ()

Returns the parent of this node. If this Node has a parent, and that parent is a Node or Node subclass, then this function returns the parent as a Node. Returns null if the parent is a Scene, use getScene() to retrieve the parent instead.

Returns

• the parent as a Node, if the parent is a Node.

public Renderable getRenderable ()

Gets the renderable to display for this node.

Returns

• renderable to display for this node

public final Vector3 getRight ()

Gets the world-space right vector (+x) of this node.

Returns

• a new vector that represents the node's right direction in world-space

public final Scene getScene ()

Returns the scene that this node is part of, null if it isn't part of any scene. A node is part of a scene if its highest level ancestor is a Scene

public final Vector3 getUp ()

Gets the world-space up vector (+y) of this node.

Returns

• a new vector that represents the node's up direction in world-space

public final Vector3 getWorldPosition ()

Get a copy of the nodes world-space position.

Returns

• a new vector that represents the node's world-space position

See Also

• setWorldPosition(Vector3)

public final Quaternion getWorldRotation ()

Gets a copy of the nodes world-space rotation.

Returns

• a new quaternion that represents the node's world-space rotation

See Also

• setWorldRotation(Quaternion)

public final Vector3 getWorldScale ()

Gets a copy of the nodes world-space scale. Some precision will be lost if the node is skewed.

Returns

• a new vector that represents the node's world-space scale

See Also

• setWorldScale(Vector3)

public final boolean isActive ()

Returns true if the node is active. A node is considered active if it meets ALL of the following conditions:

• The node is part of a scene.
• the node's parent is active.
• The node is enabled.

An active Node has the following behavior:

• The node's onUpdate(FrameTime) function will be called every frame.
• The node's getRenderable() will be rendered.
• The node's getCollisionShape() will be checked in calls to Scene.hitTest.
• The node's onTouchEvent(HitTestResult, MotionEvent) function will be called when the node is touched.

Returns

• the node's active status

See Also

• onActivate()
• onDeactivate()

public final boolean isDescendantOf (NodeParent ancestor)

Checks whether the given node parent is an ancestor of this node recursively.

Parameters

ancestor	the node parent to check

Returns

• true if the node is an ancestor of this node

public final boolean isEnabled ()

Gets the enabled state of this node. Note that a Node may be enabled but still inactive if it isn't part of the scene or if its parent is inactive.

Returns

• the node's enabled status.

See Also

• isActive()

public boolean isTopLevel ()

Returns true if this node is top level. A node is considered top level if it has no parent or if the parent is the scene.

Returns

• true if the node is top level

public final Vector3 localToWorldDirection (Vector3 direction)

Converts a direction from the local-space of this node to world-space. Not impacted by the position or scale of the node.

Parameters

direction	the direction in local-space to convert

Returns

• a new vector that represents the direction in world-space

public final Vector3 localToWorldPoint (Vector3 point)

Converts a point in the local-space of this node to world-space.

Parameters

point	the point in local-space to convert

Returns

• a new vector that represents the point in world-space

public void onActivate ()

Handles when this node becomes active. A Node is active if it's enabled, part of a scene, and its parent is active.

Override to perform any setup that needs to occur when the node is activated.

See Also

• isActive()
• isEnabled()

public void onDeactivate ()

Handles when this node becomes inactivate. A Node is inactive if it's disabled, not part of a scene, or its parent is inactive.

Override to perform any setup that needs to occur when the node is deactivated.

See Also

• isActive()
• isEnabled()

public boolean onTouchEvent (HitTestResult hitTestResult, MotionEvent motionEvent)

Handles when this node is touched.

Override to perform any logic that should occur when this node is touched. The way that touch events are propagated mirrors the way touches are propagated to Android Views. This is only called when the node is active.

When an ACTION_DOWN event occurs, that represents the start of a gesture. ACTION_UP or ACTION_CANCEL represents when a gesture ends. When a gesture starts, the following is done:

• Dispatch touch events to the node that was touched as detected by hitTest(MotionEvent).
• If the node doesn't consume the event, recurse upwards through the node's parents and dispatch the touch event until one of the node's consumes the event.
• If no nodes consume the event, the gesture is ignored and subsequent events that are part of the gesture will not be passed to any nodes.
• If one of the node's consumes the event, then that node will consume all future touch events for the gesture.

When a touch event is dispatched to a node, the event is first passed to the node's Node.OnTouchListener. If the Node.OnTouchListener doesn't handle the event, it is passed to onTouchEvent(HitTestResult, MotionEvent).

Parameters

hitTestResult	Represents the node that was touched, and information about where it was touched. On ACTION_DOWN events, getNode() will always be this node or one of its children. On other events, the touch may have moved causing the getNode() to change (or possibly be null).
motionEvent	The motion event.

Returns

• True if the event was handled, false otherwise.

public void onTransformChange (Node originatingNode)

Handles when this node's transformation is changed.

The originating node is the most top-level node in the hierarchy that triggered this node to change. It will always be either the same node or one of its' parents. i.e. if node A's position is changed, then that will trigger onTransformChange(Node) to be called for all of it's children with the originatingNode being node A.

Parameters

originatingNode	the node that triggered this node's transformation to change

public void onUpdate (FrameTime frameTime)

Handles when this node is updated. A node is updated before rendering each frame. This is only called when the node is active.

Override to perform any updates that need to occur each frame.

Parameters

frameTime	provides time information for the current frame

public void removeLifecycleListener (Node.LifecycleListener lifecycleListener)

Removes a listener that will be called when node lifecycle events occur.

Parameters

lifecycleListener

public void removeTransformChangedListener (Node.TransformChangedListener transformChangedListener)

Removes a listener that will be called when the node's transformation changes.

Parameters

transformChangedListener

public void setCollisionShape (CollisionShape collisionShape)

Sets the shape to used to detect collisions for this Node. If the shape is not set and setRenderable(Renderable) is set, then getCollisionShape() is used to detect collisions for this Node.

Parameters

collisionShape	represents a geometric shape, i.e. sphere, box, convex hull. If null, this node's current collision shape will be removed.

See Also

• hitTest(Ray)
• hitTestAll(Ray)
• overlapTest(Node)
• overlapTestAll(Node)

public final void setEnabled (boolean enabled)

Sets the enabled state of this node. Note that a Node may be enabled but still inactive if it isn't part of the scene or if its parent is inactive.

Parameters

enabled	the new enabled status of the node

See Also

• isActive()

public void setLight (Light light)

Sets the Light to display. To use, first create a Light using Light.Builder. Set the parameters you care about and then attach it to the node using this function. A node may have a renderable and a light or just act as a Light.

Parameters

light	Properties of the Light to render, pass null to remove the light.

public void setLocalPosition (Vector3 position)

Sets the position of this node relative to its parent (local-space). If isTopLevel() is true, then this is the same as setWorldPosition(Vector3).

Parameters

position	The position to apply.

See Also

• getLocalPosition()

public void setLocalRotation (Quaternion rotation)

Sets the rotation of this node relative to its parent (local-space). If isTopLevel() is true, then this is the same as setWorldRotation(Quaternion).

Parameters

rotation	The rotation to apply.

See Also

• getLocalRotation()

public void setLocalScale (Vector3 scale)

Sets the scale of this node relative to its parent (local-space). If isTopLevel() is true, then this is the same as setWorldScale(Vector3).

Parameters

scale	The scale to apply.

See Also

• getLocalScale()

public final void setLookDirection (Vector3 lookDirection)

Sets the direction that the node is looking at in world-space. After calling this, getForward() will match the look direction passed in. World-space up (0, 1, 0) will be used to determine the orientation of the node around the direction.

Parameters

lookDirection	a vector representing the desired look direction in world-space

public final void setLookDirection (Vector3 lookDirection, Vector3 upDirection)

Sets the direction that the node is looking at in world-space. After calling this, getForward() will match the look direction passed in. The up direction will determine the orientation of the node around the direction. The look direction and up direction cannot be coincident (parallel) or the orientation will be invalid.

Parameters

lookDirection	a vector representing the desired look direction in world-space
upDirection	a vector representing a valid up vector to use, such as Vector3.up()

public final void setName (String name)

Sets the name of this node. Nodes can be found using their names. Multiple nodes may have the same name, in which case calling findByName(String) will return the first node with the given name.

Parameters

name	The name of the node.

public void setOnTapListener (Node.OnTapListener onTapListener)

Registers a callback to be invoked when this node is tapped. If there is a callback registered, then touch events will not bubble to this node's parent. If the Node.onTouchEvent is overridden and super.onTouchEvent is not called, then the tap will not occur.

Parameters

onTapListener

See Also

• Node.OnTapListener

public void setOnTouchListener (Node.OnTouchListener onTouchListener)

Registers a callback to be invoked when a touch event is dispatched to this node. The way that touch events are propagated mirrors the way touches are propagated to Android Views. This is only called when the node is active.

When an ACTION_DOWN event occurs, that represents the start of a gesture. ACTION_UP or ACTION_CANCEL represents when a gesture ends. When a gesture starts, the following is done:

• Dispatch touch events to the node that was touched as detected by hitTest(MotionEvent).
• If the node doesn't consume the event, recurse upwards through the node's parents and dispatch the touch event until one of the node's consumes the event.
• If no nodes consume the event, the gesture is ignored and subsequent events that are part of the gesture will not be passed to any nodes.
• If one of the node's consumes the event, then that node will consume all future touch events for the gesture.

When a touch event is dispatched to a node, the event is first passed to the node's Node.OnTouchListener. If the Node.OnTouchListener doesn't handle the event, it is passed to onTouchEvent(HitTestResult, MotionEvent).

Parameters

onTouchListener

See Also

• Node.OnTouchListener

public void setParent (NodeParent parent)

Changes the parent node of this node. If set to null, this node will be detached from its parent. The local position, rotation, and scale of this node will remain the same. Therefore, the world position, rotation, and scale of this node may be different after the parent changes.

The parent may be another Node or a Scene. If it is a scene, then this Node is considered top level. getParent() will return null, and getScene() will return the scene.

Parameters

parent	The new parent that this node will be a child of. If null, this node will be detached from its parent.

See Also

• getParent()
• getScene()

public void setRenderable (Renderable renderable)

Sets the Renderable to display for this node. If setCollisionShape(CollisionShape) is not set, then getCollisionShape() is used to detect collisions for this Node.

Parameters

renderable	Usually a 3D model. If null, this node's current renderable will be removed.

See Also

• ModelRenderable
• ViewRenderable

public void setWorldPosition (Vector3 position)

Sets the world-space position of this node.

Parameters

position	The position to apply.

See Also

• getWorldPosition()

public void setWorldRotation (Quaternion rotation)

Sets the world-space rotation of this node.

Parameters

rotation	The rotation to apply.

See Also

• getWorldRotation()

public void setWorldScale (Vector3 scale)

Sets the world-space scale of this node.

Parameters

scale	The scale to apply.

See Also

• getWorldScale()

public String toString ()

public final Vector3 worldToLocalDirection (Vector3 direction)

Converts a direction from world-space to the local-space of this node. Not impacted by the position or scale of the node.

Parameters

direction	the direction in world-space to convert

Returns

• a new vector that represents the direction in local-space

public final Vector3 worldToLocalPoint (Vector3 point)

Converts a point in world-space to the local-space of this node.

Parameters

point	the point in world-space to convert

Returns

• a new vector that represents the point in local-space

Protected Methods

protected final boolean canAddChild (Node child, StringBuilder failureReason)

Parameters

child
failureReason

protected final void onAddChild (Node child)

Parameters

child

protected final void onRemoveChild (Node child)

Parameters

child