group node

Summary

The group node is used for grouping nodes in the scene together.

For more information see the XML reference entry for group.

Constructor

group.new([id])

The parameter id is optional. If specified the node will be given this id.

Example C.14. Use of group constructor

<scene>
	<script type="text/x-lua">

		-- create a new group and add it to the scene
		mygroup = group.new()
		scene:appendNode(mygroup)
		
		-- create a new object and add it to the group that we
		-- have just created
		myplane = object.new("primitives://plane.aro")
		mygroup:appendNode(myplane)
		
	</script>
	
</scene>

Functions

Functions common to nodes that group nodes

node:appendNode( newchild )

Adds the passed node to this group in the scene.

Example C.15. Use of appendNode

<scene>
	<script type="text/x-lua">
		
		myplane = object.new("primitives://plane.aro")
		
		mygroup = scene:getById("mygroup")
		mygroup:appendNode(myplane)
		
	</script>
	
	<group id="mygroup">
		<!-- object will be added here by script -->
	</group>
	
</scene>


node:replaceChildren( newchild )

Removes all children from this group and replaces them with the passed node.

Example C.16. Use of replaceChildren

<scene>
	<script type="text/x-lua">
		
		myplane = object.new("primitives://plane.aro")
		
		mygroup = scene:getById("mygroup")
		mygroup:replaceChildren(myplane)
		
	</script>
	
	<group id="mygroup">
		
		<!-- this object will be removed by script -->
		<object type="primitives://plane.aro" color="1 0 0 1"/>
		
	</group>
	
</scene>


Functions common to transformable nodes

pos graphnode:getPosition()

Returns a table of 3 values - x, y, and z.

Example C.17. Use of getPosition

<scene>
	<script type="text/x-lua">
		
		myplane = scene:getById("myplane")
		pos = myplace:getPosition()
		x = pos[1]
		y = pos[2]
		z = pos[3]
		
	</script>
	<object id="myplane" type="primitives://plane.aro" position="1.2 -0.2 0.1"/>
</scene>


rot graphnode:getRotation()

Returns a table of 3 values - yaw, pitch and roll, in degrees.

Example C.18. Use of getRotation

<scene>
	<script type="text/x-lua">
		
		myplane = scene:getById("myplane")
		rot = myplace:getRotation()
		yaw = rot[1]
		pitch = rot[2]
		roll = rot[3]
		
	</script>
	<object id="myplane" type="primitives://plane.aro" rotation="90 240 45"/>
</scene>


sca graphnode:getScale()

Returns a table of 3 values - x-scale, y-scale and z-scale.

Example C.19. Use of getScale

<scene>
	<script type="text/x-lua">
		
		myplane = scene:getById("myplane")
		scale = myplace:getScale()
		x = scale[1]
		y = scale[2]
		z = scale[3]
		
	</script>
	<object id="myplane" type="primitives://plane.aro" scale="0.5 0.4 1"/>
</scene>


boolean transformablenode:isBillboard()

Returns whether the node is billboarded (always faces the camera) or not.

boolean transformablenode:isFillDepthBuffer()

Returns true if the node fills the depth buffer during rendering; otherwise returns false.

transformablenode:setBillboard( true or false )

Pass true or false to indicate if node should be displayed in a billboard fashion (always facing the camera) or not.

transformablenode:setFillDepthBuffer( true or false )

Pass true or false to indicate if node should fill the depth buffer during rendering.

node:setPosition( pos )

Sets the position of the node. Pass a 3-element table with entries { x, y, z }.

Example C.20. Use of setPosition

<scene>
	<script type="text/x-lua">
		
		myplane = scene:getById("myplane")
		
		--          x     y    z
		newpos = { 1.5, -0.2, 0.1 } 
		myplane:setPosition(newpos)
		
	</script>
	<object id="myplane" type="primitives://plane.aro"/>
</scene>


node:setScale( sca )

Sets the scale of the node. Pass a 3-element table with entries { x, y, z }.

Example C.21. Use of setScale

<scene>
	<script type="text/x-lua">
		
		myplane = scene:getById("myplane")
		
		--            x     y    z
		newscale = { 1.5, -0.2, 0.1 } 
		myplane:setScale(newscale)
		
	</script>
	<object id="myplane" type="primitives://plane.aro"/>
</scene>


node:setRelativeTo( val )

Pass either transformablenode.PARENT, transformablenode.CAMERA or transformablenode.SCREEN to indicate whether the transformation properties (position, scale and rotation) of the node are relative to its parent node, to the screen, or to the camera. For more information see Viewport-relative content.

Example C.22. Use of setRelativeTo

<scene>
	<script type="text/x-lua">
		
		myplane = scene:getById("myplane")
		 
		myplane:setRelativeTo(transformablenode.SCREEN)
		
	</script>
	<object id="myplane" type="primitives://plane.aro"/>
</scene>


node:setRotation( rot )

Sets the rotation of the node. Pass a 3-element table with entries { yaw, pitch, roll }, in degrees.

Example C.23. Use of setRotation

<scene>
	<script type="text/x-lua">
		
		myplane = scene:getById("myplane")
		
		--         yaw  pitch  roll
		newrot = { 90,  140,   45 } 
		myplane:setRotation(newrot)
		
	</script>
	<object id="myplane" type="primitives://plane.aro"/>
</scene>


Functions common to nodes

col graphnode:getColor()

Returns a table of 4 values - red, green, blue and alpha (transparency) between 0.0 and 1.0.

Example C.24. Use of getColor

<scene>
	<script type="text/x-lua">
		
		myplane = scene:getById("myplane")
		cols = myplace:getColor()
		red = cols[1]
		green = cols[2]
		blue = cols[3]
		alpha = cols[4]
		
	</script>
	<object id="myplane" type="primitives://plane.aro" color="0.5 1 1 0.75"/>
</scene>


boolean graphnode:isVisible()

Returns true if the node is set to visible, or false otherwise.

graphnode:setColor( col )

Sets the color of the node. Pass a 4-element table with entries { red, green, blue, alpha }. Values are expressed between 0.0 and 1.0.

Example C.25. Use of setColor

<scene>
	<script type="text/x-lua">
		
		myplane = scene:getById("myplane")
		
		--         r    g   b    a
		newcol = { 0.1, 1, 0.5, 0.25 } 
		myplane:setColor(newcol)
		
	</script>
	<object id="myplane" type="primitives://plane.aro"/>
</scene>


graphnode:setVisible( true or false )

Sets the visibility of the node. Invisible nodes are not displayed and do not respond to events e.g. onhover, onclickdown etc.