Node3D
¶
Node3D is the base class of 3D nodes.
Node3D implements functionality common to all 3D nodes, such as rendering, layouting, and hit testing.
To create UI graphs, use classes derived from Node3D, such as TextBlock3D, EmptyNode3D, and StackLayout3D.
To create a 3D node, call a create function that returns an ObjectRef, which contains an owning reference to a corresponding KanziObject.
-- Create an EmptyNode3D.
local emptyNodeRef = EmptyNode3D:create("Node Name")
-- Access the referenced EmptyNode3D object. This is optional, because in Lua API calls, you can use ObjectRef instead of KanziObject.
local emptyNode = emptyNodeRef:get()
Each node has its own type of create function.
Node initialization happens within the create function, after constructing the node.
Kanzi arranges nodes in a tree that you can think of as a directed acyclic graph with no loops. Each node can have multiple children but only one parent.
The root node of the node tree is always a 2D node. The root node does not have a parent, and it is usually of type Screen.
The Viewport2D node serves as a window to a 3D scene graph that Kanzi displays in the viewport area. A Viewport2D node must have a child Scene node as the root of the 3D scene graph. The child nodes of the Scene node are Node3D nodes.
You can manipulate the node tree by adding children to nodes:
-- Add a previously created Empty Node to the context node of the script.
contextNode:addChild(emptyNode)
You can remove child nodes from a parent node.
-- Remove the previously added child node from the context node of the script.
contextNode:removeChild(emptyNode)
Parents take ownership, and hold a reference to the children.
-- Release a Lua reference. Kanzi passes the ownership to the parent node.
emptyNodeRef = nil
-- The reference is kept alive by Lua until garbage collected. You can optionally force Lua garbage collection.
collectgarbage()
collectgarbage()
You can iterate over the node tree by using iterators.
for node in contextNode:iterateChildren() do
print(node:getProperty(Node.NameProperty))
end
While you are iterating over the node tree, modifying it is not safe.
for node in contextNode:iterateChildren() do
contextNode:addChild(emptyNode) -- Bad. Will crash Kanzi Engine.
end
You can also iterate the node tree from a node by enumerating its children.
local count = contextNode:getChildCount()
for i = 0, count - 1 do
local node = contextNode:getChild(i)
print(node:getProperty(Node.NameProperty))
end
Finding nodes in the node tree is inherited from the Node base class. You can look for nodes using a path.
local childNode = contextNode:lookupNode("./Child/GrandChild")
The paths a relative to the node where you perform the lookup. You can also move up the tree.
local parentNode = contextNode:lookupNode("..")
If lookup fails, Kanzi returns nil.
Inherits properties and message types from Node3DMetadata.
| addChild() | Adds a child node |
| insertChild() | Adds a child node for an object node to the given index |
| removeChild() | Removes child node |
| removeChildAtIndex() | Removes the child node at the given index |
| removeAllChildren() | Removes all child nodes |
| getChild() | Returns a child node at the given index |
| getChildCount() | Returns a total amount of child nodes |
| getChildIndex() | Returns the index of a child in an object node |
| hasChild() | Returns whether the given node is a child of this node |
| moveToBack() | Repositions the node as the first node of its parent, so that this child node is drawn first |
| moveToFront() | Repositions the node as the last node of its parent, so that the child node is drawn last |
| iterateChildren() | Returns an iterator used to iterate over children of this node |
| getCoreDesiredSize() | Returns the core desired size of a 3D node |
| setCoreDesiredSize() | Sets the core desired size of a 3D node |
| getDesiredSize() | Returns the desired size of a 3D node |
| setDesiredSize() | Sets the desired size of a 3D node |
| getAllocatedSize() | Returns the allocated size of a 3D node |
| setAllocatedSize() | Sets the allocated size of a 3D node |
| getActualSize() | Returns the actual size of a 3D node |
| setActualSize() | Sets the actual size of a 3D node |
| setLayoutBoundingBoxSize() | Sets the size of the bounding box of a 3D node |
| getLayoutBoundingBoxMin() | Returns the minimum coordinates of the bounding box of a 3D node |
| getLayoutBoundingBoxMax() | Returns the maximum coordinates of the bounding box of a 3D node |
| getAllocatedOffset() | Returns the allocated offset of a 3D node |
| setAllocatedOffset() | Sets the allocated offset of a 3D node |
| getStretchScale() | Returns the stretch scale of a 3D node |
| setStretchScale() | Sets the stretch scale of a 3D node |
| getPivotOffset() | Returns the pivot offset of a 3D node |
| setPivotOffset() | Sets the pivot offset of a 3D node |
| getSize() | Returns the size of a 3D node |
| getMaximumBoundingBoxCoordinates() | Returns the maximum coordinates for the bounding volume of a 3D node |
| getMinimumBoundingBoxCoordinates() | Returns the minimum coordinates for the bounding volume of a 3D node |
| getArrangeTransformation() | Returns the layout transformation of a 3D node |
| setArrangeTransformation() | Sets the layout transformation of a 3D node |
| isPrimitiveLayout() | Indicates whether a 3D node has primitive layout behavior |
| getLookAtTarget() | |
| getPositionConstraintTarget() | |
| getOrientationConstraintTarget() | |
| getFaceToCameraTarget() | |
| lookAt() | Sets node transformation so that the node is in a given position turned toward a given point |
| layoutUp() | Returns the direction toward which the y axis of a 3D node grows |
| isValidLayoutSize() | Returns whether a given size is a valid layout size |
| unboundedLayoutSize() | Returns an unbounded layout size |
| isUnboundedLayoutSize() | Returns whether a layout size is an unbounded layout size |
| replaceUnboundedLayoutSize() | Replaces any elements in an unbounded layout size with the corresponding elements of a given size |
| replaceUnboundedLayoutSizeWithZero() | Replaces any elements in an unbounded layout size with zero |
Adds a child node.
Adding a 3D node node as a child of a 2D node is only allowed when you add a Scene node to a Viewport2D node. A Screen node can have only one child that must be a 2D node.
| child | (Node3D) | A node to add. |
Adds a child node for an object node to the given index.
Adding a 3D node node as a child of a 2D node is only allowed when you add a Scene node to a Viewport2D node. A Screen node can have only one child that must be a 2D node.
| index | (number) | An index at which the child node needs to be inserted. |
| child | (Node3D) | A node to add. |
Removes child node.
Removing a child node from the node tree can destroy the node. This makes the corresponding Lua KanziObject object stale. You cannot use stale objects in Kanzi Lua calls. If you want to keep a removed node alive after removal, create an ObjectRef for that node.
-- Get the child node and create an owning reference for it.
local childNode = contextNode:lookupNode("Child")
local childNodeRef = contextNode:tryCreateReference()
-- Remove child node from the node tree.
contextNode:removeChild(childNode)
-- You still can use the child node even after removal from the node tree.
local siblingNode = contextNode:lookupNode("../Sibling")
siblingNode:addChild(childNode)
| child | (Node) | A child node to remove. |
Removes the child node at the given index.
| index | (number) | An index of the child node to remove. |
Removes all child nodes.
Returns a child node at the given index.
| index | (number) | An index of the child node. |
| (Node3D) | A child node at the given index. |
Returns a total amount of child nodes.
| (number) | The number of child nodes of the node. |
Returns the index of a child in an object node.
| child | (Node) | A child node whose index to retrieve. |
| (number) | An index of the child node. |
Returns whether the given node is a child of this node.
| (boolean) | If the given node is a child of this node, true, otherwise false. |
Repositions the node as the first node of its parent, so that this child node is drawn first.
Repositions the node as the last node of its parent, so that the child node is drawn last.
Returns an iterator used to iterate over children of this node.
Returns the core desired size of a 3D node.
| (Vector3) |
Sets the core desired size of a 3D node.
| value | (Vector3) |
Returns the desired size of a 3D node.
| (Vector3) |
Sets the desired size of a 3D node.
| value | (Vector3) |
Returns the allocated size of a 3D node.
| (Vector3) |
Sets the allocated size of a 3D node.
| value | (Vector3) |
Returns the actual size of a 3D node.
| (Vector3) |
Sets the actual size of a 3D node.
| value | (Vector3) |
Sets the size of the bounding box of a 3D node.
| bboxMin | (Vector3) | |
| bboxMax | (Vector3) |
Returns the minimum coordinates of the bounding box of a 3D node.
| (Vector3) |
Returns the maximum coordinates of the bounding box of a 3D node.
| (Vector3) |
Returns the allocated offset of a 3D node.
| (Vector3) |
Sets the allocated offset of a 3D node.
| value | (Vector3) |
Returns the stretch scale of a 3D node.
| (Vector3) |
Sets the stretch scale of a 3D node.
| value | (Vector3) |
Returns the pivot offset of a 3D node.
| (Vector3) |
Sets the pivot offset of a 3D node.
| value | (Vector3) |
Returns the size of a 3D node.
| (Vector3) |
Returns the maximum coordinates for the bounding volume of a 3D node.
| (Vector3) |
Returns the minimum coordinates for the bounding volume of a 3D node.
| (Vector3) |
Returns the layout transformation of a 3D node.
| (Matrix4x4) |
Sets the layout transformation of a 3D node.
| value | (Matrix4x4) | The layout transformation matrix. |
Indicates whether a 3D node has primitive layout behavior.
| (boolean) | If the 3D node has primitive layout behavior, true, otherwise false. |
| (Node3D or nil) |
| (Node3D or nil) |
| (Node3D or nil) |
| (Node3D or nil) |
Sets node transformation so that the node is in a given position turned toward a given point.
| position | (Vector3) | The translation to apply to the node. |
| lookAtPoint | (Vector3) | The point toward which the node turns. |
| upVector | (Vector3) | The up vector to set for the node. |
Returns the direction toward which the y axis of a 3D node grows.
| (number) | The direction of the y axis. |
Returns whether a given size is a valid layout size. A size is valid if all its elements are valid layout values.
| size | (Vector3) | The size to check. |
| (boolean) | If the size is a valid layout size, true, otherwise false. |
Returns an unbounded layout size.
| (Vector3) | Unbounded layout size. |
Returns whether a layout size is an unbounded layout size. A layout size is unbounded if any of its elements are unbounded layout values.
| layoutSize | (Vector3) | The layout size to check. |
| (boolean) | If the layout size is unbounded, true, otherwise false. |
Replaces any elements in an unbounded layout size with the corresponding elements of a given size.
| layoutSize | (Vector3) | The layout size to check. |
| resetSize | (Vector3) | The size with whose elements to replace the unbounded value elements of the layout size. |
| (Vector3) | The layoutSize with its unbounded value elements replaced with the elements of resetSize. |
Replaces any elements in an unbounded layout size with zero.
| layoutSize | (Vector3) | The layout size to check. |
| (Vector3) | The layoutSize with its unbounded value elements replaced with zeroes. |