A transformable object in a Scene hierarchy. More...

#include <a3d/scene/Node.h>

Inherits std::enable_shared_from_this< Node >.

Public Types
enum class	DebugOptions : uint32_t { None = 0 , ShowHighlightBox = 1 << 0 , ShowHighlightTint = 1 << 1 }
	Debug visualization options associated with a node. More...

Public Member Functions
	Node ()
	Creates an empty node with an identity transform. More...

	Node (const std::string &name)
	Creates a node with `name` and an identity transform. More...

	Node (const std::shared_ptr< Mesh > &mesh)
	Creates a node containing `mesh` and an identity transform. More...

	Node (const std::shared_ptr< Light > &light)
	Creates a node containing `light` and an identity transform. More...

	Node (const std::shared_ptr< Camera > &camera)
	Creates a node containing `camera` and an identity transform. More...

const std::optional< std::string > &	name () const
	Returns the optional node name. More...

void	name (const std::string &name)
	Sets the node name. More...

const std::shared_ptr< Light > &	light () const
	Returns the light attached to this node, or nullptr if none is attached. More...

void	light (const std::shared_ptr< Light > &light)
	Replaces the light attached to this node; nullptr removes it. More...

const std::shared_ptr< Camera > &	camera () const
	Returns the camera attached to this node, or nullptr if none is attached. More...

void	camera (const std::shared_ptr< Camera > &camera)
	Replaces the camera attached to this node; nullptr removes it. More...

const std::shared_ptr< Mesh > &	mesh () const
	Returns the mesh attached to this node, or nullptr if none is attached. More...

void	mesh (const std::shared_ptr< Mesh > &mesh)
	Replaces the mesh attached to this node. More...

const math::vec3 &	position () const
	Returns the node position in parent coordinates. More...

void	position (const math::vec3 &position)
	Sets the node position in parent coordinates. More...

math::vec4	rotation () const
	Returns the node rotation in parent coordinates. More...

void	rotation (const math::vec3 &axis, float angle)
	Sets the node rotation from `axis` and `angle` in radians. More...

math::vec3	eulerAngles () const
	Returns the node Euler angles in parent coordinates as pitch, yaw, and roll in radians. More...

void	eulerAngles (const math::vec3 &angles)
	Sets the node Euler angles as pitch, yaw, and roll in radians. More...

const math::quat &	orientation () const
	Returns the node orientation in parent coordinates as a quaternion. More...

void	orientation (const math::quat &orientation)
	Sets the node orientation in parent coordinates. More...

const math::vec3 &	scale () const
	Returns the node scale relative to its parent. More...

void	scale (const math::vec3 &scale)
	Sets the node scale relative to its parent. More...

math::vec3	forward () const
	Returns the node's local -Z axis expressed in parent coordinates. More...

math::vec3	up () const
	Returns the node's local +Y axis expressed in parent coordinates. More...

math::vec3	right () const
	Returns the node's local +X axis expressed in parent coordinates. More...

math::mat4	transform () const
	Returns the node transform from local coordinates to parent coordinates. More...

void	transform (const math::mat4 &transform)
	Sets the node transform from local coordinates to parent coordinates. More...

math::vec3	worldPosition () const
	Returns the node position in world coordinates. More...

math::vec4	worldRotation () const
	Returns the node world rotation. More...

math::vec3	worldEulerAngles () const
	Returns the node world Euler angles as pitch, yaw, and roll in radians. More...

math::quat	worldOrientation () const
	Returns the node orientation in world coordinates. More...

math::vec3	worldScale () const
	Returns the effective node scale in world coordinates. More...

math::vec3	worldForward () const
	Returns the node's local -Z axis expressed in world coordinates. More...

math::vec3	worldUp () const
	Returns the node's local +Y axis expressed in world coordinates. More...

math::vec3	worldRight () const
	Returns the node's local +X axis expressed in world coordinates. More...

math::mat4	worldTransform () const
	Returns the transform from this node's local coordinates to world coordinates. More...

math::vec3	convertFrom (const math::vec3 &pos, const Node &from)
	Converts `pos` from `from` local coordinates into this node's local coordinates. More...

math::vec3	convertTo (const math::vec3 &pos, const Node &to)
	Converts `pos` from this node's local coordinates into `to` local coordinates. More...

math::mat4	convertFrom (const math::mat4 &t, const Node &from)
	Converts `t` from `from` local coordinates into this node's local coordinates. More...

math::mat4	convertTo (const math::mat4 &t, const Node &to)
	Converts `t` from this node's local coordinates into `to` local coordinates. More...

void	addChild (const std::shared_ptr< Node > &node)
	Adds `node` as a child of this node. More...

void	addChildren (const std::vector< std::shared_ptr< Node > > &nodes)
	Adds each node in `nodes` as a child. More...

void	removeFromParent ()
	Detaches this node from its current parent, if it has one. More...

std::vector< std::shared_ptr< Node > >	children (bool resursive=false) const
	Returns this node's children. More...

std::shared_ptr< Node >	childNamed (const std::string &name, bool resursive=false) const
	Finds a child with `name`. More...

PhysicsBody *	physicsBody () const
	Returns the physics body owned by this node, or nullptr if none is attached. More...

void	physicsBody (std::unique_ptr< PhysicsBody > body)
	Replaces the physics body owned by this node; nullptr removes it. More...

bool	hidden () const
	Returns true when this node is hidden from rendering. More...

void	hidden (bool hidden)
	Sets whether this node is hidden from rendering. More...

int	renderOrder () const
	Returns the node render-order value. More...

void	renderOrder (int order)
	Sets the node render-order value. More...

DebugOptions	debugOptions () const
	Returns the enabled node debug visualization options. More...

void	debugOptions (DebugOptions options)
	Sets the enabled node debug visualization options. More...

Scene *	scene () const
	Returns the Scene containing this node, or nullptr if the node is not attached to a Scene. More...

std::weak_ptr< Node >	parent () const
	Returns the current parent, or an empty weak pointer for a root or detached node. More...

Static Public Member Functions
static std::shared_ptr< Node >	NamedNode (const std::string &name)
	Creates a new node with `name`. More...

static std::shared_ptr< Node >	MeshNode (const std::shared_ptr< Mesh > &geometry)
	Creates a new node containing `geometry`. More...

static std::shared_ptr< Node >	LightNode (const std::shared_ptr< Light > &light)
	Creates a new node containing `light`. More...

static std::shared_ptr< Node >	CameraNode (const std::shared_ptr< Camera > &camera)
	Creates a new node containing `camera`. More...

Detailed Description

A transformable object in a Scene hierarchy.

A Node may contain a Mesh, Light, Camera, and PhysicsBody, and may have child nodes. Transform properties are expressed relative to the parent; world-space accessors include the transforms of all ancestors.

Child nodes are retained with shared ownership. A node retains its parent weakly, so retaining a child does not keep its parent hierarchy alive.

Definition at line 45 of file Node.h.

Member Enumeration Documentation

◆ DebugOptions

enum class a3d::Node::DebugOptions : uint32_t

strong

Debug visualization options associated with a node.

Enumerator
None	No node debug visualization.
ShowHighlightBox	Show the node highlight box.
ShowHighlightTint	Tint the node for highlighting.

Definition at line 52 of file Node.h.

Constructor & Destructor Documentation

◆ Node() [1/5]

a3d::Node::Node ( )

Creates an empty node with an identity transform.

◆ Node() [2/5]

a3d::Node::Node ( const std::string & name )

explicit

Creates a node with name and an identity transform.

◆ Node() [3/5]

a3d::Node::Node ( const std::shared_ptr< Mesh > & mesh )

explicit

Creates a node containing mesh and an identity transform.

◆ Node() [4/5]

a3d::Node::Node ( const std::shared_ptr< Light > & light )

explicit

Creates a node containing light and an identity transform.

◆ Node() [5/5]

a3d::Node::Node ( const std::shared_ptr< Camera > & camera )

explicit

Creates a node containing camera and an identity transform.

Member Function Documentation

◆ addChild()

void a3d::Node::addChild ( const std::shared_ptr< Node > & node )

Adds node as a child of this node.

Exceptions

std::runtime_error if node is already contained in this node's subtree.

◆ addChildren()

void a3d::Node::addChildren ( const std::vector< std::shared_ptr< Node > > & nodes )

Adds each node in nodes as a child.

◆ camera() [1/2]

const std::shared_ptr< Camera > & a3d::Node::camera ( ) const

Returns the camera attached to this node, or nullptr if none is attached.

◆ camera() [2/2]

void a3d::Node::camera ( const std::shared_ptr< Camera > & camera )

Replaces the camera attached to this node; nullptr removes it.

◆ CameraNode()

static std::shared_ptr< Node > a3d::Node::CameraNode ( const std::shared_ptr< Camera > & camera )

static

Creates a new node containing camera.

◆ childNamed()

std::shared_ptr< Node > a3d::Node::childNamed	(	const std::string &	name,
		bool	resursive = `false`
	)		const

Finds a child with name.

Parameters

name	name to match.
resursive	when true, searches all descendants; otherwise searches direct children only.

Returns: The first matching child, or nullptr if no match is found.

◆ children()

std::vector< std::shared_ptr< Node > > a3d::Node::children ( bool resursive = false ) const

Returns this node's children.

Parameters

resursive when true, returns all descendants; otherwise returns direct children only.

Returns: Child nodes in hierarchy traversal order.

◆ convertFrom() [1/2]

math::mat4 a3d::Node::convertFrom	(	const math::mat4 &	t,
		const Node &	from
	)

Converts t from from local coordinates into this node's local coordinates.

◆ convertFrom() [2/2]

math::vec3 a3d::Node::convertFrom	(	const math::vec3 &	pos,
		const Node &	from
	)

Converts pos from from local coordinates into this node's local coordinates.

◆ convertTo() [1/2]

math::mat4 a3d::Node::convertTo	(	const math::mat4 &	t,
		const Node &	to
	)

Converts t from this node's local coordinates into to local coordinates.

◆ convertTo() [2/2]

math::vec3 a3d::Node::convertTo	(	const math::vec3 &	pos,
		const Node &	to
	)

Converts pos from this node's local coordinates into to local coordinates.

◆ debugOptions() [1/2]

DebugOptions a3d::Node::debugOptions ( ) const

Returns the enabled node debug visualization options.

◆ debugOptions() [2/2]

void a3d::Node::debugOptions ( DebugOptions options )

Sets the enabled node debug visualization options.

◆ eulerAngles() [1/2]

math::vec3 a3d::Node::eulerAngles ( ) const

Returns the node Euler angles in parent coordinates as pitch, yaw, and roll in radians.

◆ eulerAngles() [2/2]

void a3d::Node::eulerAngles ( const math::vec3 & angles )

Sets the node Euler angles as pitch, yaw, and roll in radians.

◆ forward()

math::vec3 a3d::Node::forward ( ) const

Returns the node's local -Z axis expressed in parent coordinates.

◆ hidden() [1/2]

bool a3d::Node::hidden ( ) const

Returns true when this node is hidden from rendering.

◆ hidden() [2/2]

void a3d::Node::hidden ( bool hidden )

Sets whether this node is hidden from rendering.

◆ light() [1/2]

const std::shared_ptr< Light > & a3d::Node::light ( ) const

Returns the light attached to this node, or nullptr if none is attached.

◆ light() [2/2]

void a3d::Node::light ( const std::shared_ptr< Light > & light )

Replaces the light attached to this node; nullptr removes it.

◆ LightNode()

static std::shared_ptr< Node > a3d::Node::LightNode ( const std::shared_ptr< Light > & light )

static

Creates a new node containing light.

◆ mesh() [1/2]

const std::shared_ptr< Mesh > & a3d::Node::mesh ( ) const

Returns the mesh attached to this node, or nullptr if none is attached.

◆ mesh() [2/2]

void a3d::Node::mesh ( const std::shared_ptr< Mesh > & mesh )

Replaces the mesh attached to this node.

Passing nullptr removes the current Mesh. If this node owns a PhysicsBody whose PhysicsShape was automatically derived by A3D, the collision shape is rebuilt from the updated Mesh or node hierarchy. An explicitly assigned PhysicsShape is left unchanged.

If an explicitly assigned PhysicsShape derives from the previous Mesh, the caller must keep that Mesh alive as required by the PhysicsShape source-lifetime contract.

Exceptions

std::invalid_argument if automatic collision-shape creation is required and mesh contains no elements.

◆ MeshNode()

static std::shared_ptr< Node > a3d::Node::MeshNode ( const std::shared_ptr< Mesh > & geometry )

static

Creates a new node containing geometry.

◆ name() [1/2]

const std::optional< std::string > & a3d::Node::name ( ) const

Returns the optional node name.

◆ name() [2/2]

void a3d::Node::name ( const std::string & name )

Sets the node name.

◆ NamedNode()

static std::shared_ptr< Node > a3d::Node::NamedNode ( const std::string & name )

static

Creates a new node with name.

◆ orientation() [1/2]

const math::quat & a3d::Node::orientation ( ) const

Returns the node orientation in parent coordinates as a quaternion.

◆ orientation() [2/2]

void a3d::Node::orientation ( const math::quat & orientation )

Sets the node orientation in parent coordinates.

◆ parent()

std::weak_ptr< Node > a3d::Node::parent ( ) const

Returns the current parent, or an empty weak pointer for a root or detached node.

◆ physicsBody() [1/2]

PhysicsBody * a3d::Node::physicsBody ( ) const

Returns the physics body owned by this node, or nullptr if none is attached.

◆ physicsBody() [2/2]

void a3d::Node::physicsBody ( std::unique_ptr< PhysicsBody > body )

Replaces the physics body owned by this node; nullptr removes it.

If body has no PhysicsShape, A3D may automatically derive one from this node's Mesh or hierarchy.

Exceptions

std::invalid_argument if automatic collision-shape creation is required from a Mesh with no elements.

◆ position() [1/2]

const math::vec3 & a3d::Node::position ( ) const

Returns the node position in parent coordinates.

◆ position() [2/2]

void a3d::Node::position ( const math::vec3 & position )

Sets the node position in parent coordinates.

◆ removeFromParent()

void a3d::Node::removeFromParent ( )

Detaches this node from its current parent, if it has one.

◆ renderOrder() [1/2]

int a3d::Node::renderOrder ( ) const

Returns the node render-order value.

◆ renderOrder() [2/2]

void a3d::Node::renderOrder ( int order )

Sets the node render-order value.

◆ right()

math::vec3 a3d::Node::right ( ) const

Returns the node's local +X axis expressed in parent coordinates.

◆ rotation() [1/2]

math::vec4 a3d::Node::rotation ( ) const

Returns the node rotation in parent coordinates.

Returns: An axis-angle vector with xyz containing the axis and w containing the angle in radians.

◆ rotation() [2/2]

void a3d::Node::rotation	(	const math::vec3 &	axis,
		float	angle
	)

Sets the node rotation from axis and angle in radians.

◆ scale() [1/2]

const math::vec3 & a3d::Node::scale ( ) const

Returns the node scale relative to its parent.

◆ scale() [2/2]

void a3d::Node::scale ( const math::vec3 & scale )

Sets the node scale relative to its parent.

◆ scene()

Scene * a3d::Node::scene ( ) const

Returns the Scene containing this node, or nullptr if the node is not attached to a Scene.

◆ transform() [1/2]

math::mat4 a3d::Node::transform ( ) const

Returns the node transform from local coordinates to parent coordinates.

◆ transform() [2/2]

void a3d::Node::transform ( const math::mat4 & transform )

Sets the node transform from local coordinates to parent coordinates.

◆ up()

math::vec3 a3d::Node::up ( ) const

Returns the node's local +Y axis expressed in parent coordinates.

◆ worldEulerAngles()

math::vec3 a3d::Node::worldEulerAngles ( ) const

Returns the node world Euler angles as pitch, yaw, and roll in radians.

◆ worldForward()

math::vec3 a3d::Node::worldForward ( ) const

Returns the node's local -Z axis expressed in world coordinates.

◆ worldOrientation()

math::quat a3d::Node::worldOrientation ( ) const

Returns the node orientation in world coordinates.

◆ worldPosition()

math::vec3 a3d::Node::worldPosition ( ) const

Returns the node position in world coordinates.

◆ worldRight()

math::vec3 a3d::Node::worldRight ( ) const

Returns the node's local +X axis expressed in world coordinates.

◆ worldRotation()

math::vec4 a3d::Node::worldRotation ( ) const

Returns the node world rotation.

Returns: An axis-angle vector with xyz containing the axis and w containing the angle in radians.

◆ worldScale()

math::vec3 a3d::Node::worldScale ( ) const

Returns the effective node scale in world coordinates.

◆ worldTransform()

math::mat4 a3d::Node::worldTransform ( ) const

Returns the transform from this node's local coordinates to world coordinates.

◆ worldUp()

math::vec3 a3d::Node::worldUp ( ) const

Returns the node's local +Y axis expressed in world coordinates.

The documentation for this class was generated from the following file:

a3d/scene/Node.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ DebugOptions

Constructor & Destructor Documentation

◆ Node() [1/5]

◆ Node() [2/5]

◆ Node() [3/5]

◆ Node() [4/5]

◆ Node() [5/5]

Member Function Documentation

◆ addChild()

◆ addChildren()

◆ camera() [1/2]

◆ camera() [2/2]

◆ CameraNode()

◆ childNamed()

◆ children()

◆ convertFrom() [1/2]

◆ convertFrom() [2/2]

◆ convertTo() [1/2]

◆ convertTo() [2/2]

◆ debugOptions() [1/2]

◆ debugOptions() [2/2]

◆ eulerAngles() [1/2]

◆ eulerAngles() [2/2]

◆ forward()

◆ hidden() [1/2]

◆ hidden() [2/2]

◆ light() [1/2]

◆ light() [2/2]

◆ LightNode()

◆ mesh() [1/2]

◆ mesh() [2/2]

◆ MeshNode()

◆ name() [1/2]

◆ name() [2/2]

◆ NamedNode()

◆ orientation() [1/2]

◆ orientation() [2/2]

◆ parent()

◆ physicsBody() [1/2]

◆ physicsBody() [2/2]

◆ position() [1/2]

◆ position() [2/2]

◆ removeFromParent()

◆ renderOrder() [1/2]

◆ renderOrder() [2/2]

◆ right()

◆ rotation() [1/2]

◆ rotation() [2/2]

◆ scale() [1/2]

◆ scale() [2/2]

◆ scene()

◆ transform() [1/2]

◆ transform() [2/2]

◆ up()

◆ worldEulerAngles()

◆ worldForward()

◆ worldOrientation()

◆ worldPosition()

◆ worldRight()

◆ worldRotation()

◆ worldScale()

◆ worldTransform()

◆ worldUp()