oZone3D.Net - Demoniak3D Developer Guide

The <primitive> node

Function

The primitive node allows to define auxiliary objects that help building 3d scenes. The majority of the primitives can only be displayed in wire (with no lighting neither texture application). Primitives can be used to show a light location or can be considered as reference objects for the obstacles of a particles system.

General syntax

<primitive
	name=""
	material_name=""
	texturing="TRUE"
	shape_type="BOX"
	render="TRUE"
	auto_spin="FALSE"
	billboarding="FALSE"
	lighting="FALSE"
	normalize="FALSE"
	nx_add_to_physics_engine="FALSE"
	display_tripod="FALSE"
	auto_update_direction="FALSE"
	position_ref_object="" >

	<alpha_test_params 
		active="FALSE" 
		func="CMP_FUNC_GREATER" 
		ref="0.5" />
		
	<blending_params 
		active="FALSE" 
		src_factor="BLENDING_FACTOR_SRC_ALPHA" 
		dst_factor="BLENDING_FACTOR_ONE_MINUS_SRC_ALPHA" />

	<box 
		width="20.0" 
		height="20.0" 
		depth="20.0" 
		texture_name="" 
		u_offset="0.0" 
		v_offset="0.0"  />
	
	<color 
		r="1.0" 
		g="1.0" 
		b="1.0" 
		a="1.0" />
	
	<disc 
		outer_radius="20.0" 
		inner_radius="0.0" 
		slices="6" />
		
	<triangle 
		index="0.0" 
		x="0.0" 
		y="0.0" 
		z="0.0" 
		r="0.0" 
		g="0.0" 
		b="0.0" />
		
	
	<line 
		x_start="-20.0" 
		y_start="-20.0" 
		z_start="-20.0" 
		x_end="20.0" 
		y_end="20.0" 
		z_end="20.0" />
	
	<orientation 
		ang="0.0" 
		x="0.0" 
		y="1.0" 
		z="0.0" />

	<plane 
		width="20.0" 
		height="20.0" 
		texture_name="" 
		u_offset="0.0" 
		v_offset="0.0"  />
	
	<position 
		x="0.0" 
		y="0.0" 
		z="0.0" />
	
	<quad 
		width="20.0" 
		height="20.0" 
		billboarding="FALSE" 
		texture_name="" 
		u_offset="0.0" 
		v_offset="0.0"  />
	
	<sphere 
		outer_radius="20.0" 
		inner_radius="0.0" 
		slices="6" />
	
	<spin_values 
		x="0.0" 
		y="0.0" 
		z="0.0" />
		
	<nx_linear_velocity 
		x="0.0" 
		y="0.0" 
		z="0.0" 
		damping="0.5" 
		sleep_threshold="0.14*0.14" />

	<nx_angular_velocity 
		x="0.0" 
		y="0.0" 
		z="0.0" 
		damping="0.5" 
		sleep_threshold="0.15*0.15" />
		
	<nx_misc_data 
		mass="0.0" 
		desnity="0.0" 
		actor_type="DYNAMIC" />
		
		
</primitive>

primitive element

primitive is the xml tag that defines a primitive node.

Attributes:

name - [STR127] - name of the node. This name will make it possible to refer this node throughout the XML script.
render - [BOOLEAN] - displays (TRUE) or hides (FALSE) the tripod of the gizmo - default value: TRUE
material_name - [STR127] - name of the material to be applied to this primitive. If this name is not specified, a default name by will be automatically generated. If this name is specified, it will refer to a material node in the XML code.
texturing - [BOOLEAN] - enables (TRUE) or disables (FALSE) the texture application on the primitive - default value: TRUE
auto_spin - [BOOLEAN] - enables (TRUE) or disables (FALSE) rotation around the axiss of the object local reference mark. The values of the rotation angles must be specified with the <spin_values> tag - default value: FALSE
lighting - [BOOLEAN] - enables (TRUE) or disables (FALSE) lighting calculations - default value: FALSE
normalize - [BOOLEAN] - enables (TRUE) or disables (FALSE) the standardization of the vertices normals after the HYP_SetObjectScale function has been used - default value: FALSE
shape_type - [ENUM] - primitive basic shape:
- POINT: 3d point (vertex) defined by a position and a color. The position of the point is specified by the <position... /> XML element and the color with <color.../>
- LINE: line in the 3d space defined by 2 endpoints : one starting vertex and one ending vertex
- TRIANGLE: triangle formed by three 3d points (vertices), each point being defined by a position and a color
- DISC: disc made of line segments. This number of segments is the slice of the disc
- SPHERE: sphere made of a number of discs
- PLANE: 3d plane which can be defined according to the X and Z axis
- QUAD: 3d plane which can be defined according to the X and Y axis. A quad is different from a plane because it provides the billboarding property
- BOX: 3d box that may be defined with its 3 dimensions
position_ref_object - [STR127] - makes it possible to associate the position of this primitive to that of another object called the "reference object"
group - [STR127] - name of the group in which to add the current node. A group makes it possible to control it behavior of several objects in a single way
nx_add_to_physics_engine - [BOOLEAN] - makes it possible to add (TRUE) or not add (FALSE) this object in the scene of the physical simulation engine. This makes sense only if the physical engine (NovodeX) is available and if it has been activated in the scene node - default value: FALSE
display_tripod - [BOOLEAN] - displays (TRUE) or hides (FALSE) the local reference mark of the mesh - default value: FALSE
Remark: The axis of the tripod are represented by the following colors:
- X axis: red
- Y axis: green
- Z axis: blue
auto_update_direction - [BOOLEAN] - enables (TRUE) or disables (FALSE) the automatic update of the object's local reference mark (tripod) direction (Z axis) - default value: FALSE

alpha_test_params element

alpha_test_params makes it possible to set the parameters for the alpha-test hardware.

Attributes:

active - [BOOLEAN] - enables or disables the alpha test - default value: FALSE
func - [ENUM] - alpha comparison function. The following symbolic constant are accepted:
- CMP_FUNC_NEVER: the test never passes.
- CMP_FUNC_LESS: the test passes if the alpha value is smaller than the reference value.
- CMP_FUNC_LESS_OR_EQUAL: the test passes if the alpha value is smaller or equal to the reference value.
- CMP_FUNC_GREATER: the test passes if the alpha value is greater than the reference value - default value
- CMP_FUNC_GREATER_OR_EQUAL: the test passes if the alpha value is greater or equal to the reference value.
- CMP_FUNC_EQUAL: the test passes if the alpha value is equal to the reference value.
- CMP_FUNC_NOT_EQUAL: the test passes if the alpha value is different from the reference value.
- CMP_FUNC_ALWAYS: the test always passes.
ref - [CLAMPED_REAL] - reference value with which the entering alpha value is compared. This reference value must lie between 0.0 and 1.0 - default value: 0.5

blending_params element

blending_params makes it possible to set the parameters for the blending (mixture) of the colors.

Attributes:

active - [BOOLEAN] - enables or disables the blending - default value: FALSE
src_factor - [ENUM] - specifies the blending source factor - default value: BLENDING_FACTOR_SRC_ALPHA
blending_dst_factor specifies the destination factor in the blending equation :
C = Cs*Sf + Cd*Df
where C is the final (R, G, B, A) color, Cs the (Rs, Gs, Bs, As) source (or entering) color and Cd is the (Rd, Gd, Bd, Ad) color present in the framebuffer .
Sf is the (Sr, Sg, Sb, Sa) blending source factor and Df is the (Dr, Dg, Db, Da) blending destination factor.
- BLENDING_FACTOR_ZERO: (0 0 0 0)
- BLENDING_FACTOR_ONE: (1 1 1 1)
- BLENDING_FACTOR_SRC_ALPHA: (As, As, As, As)
- BLENDING_FACTOR_ONE_MINUS_DST_ALPHA: (1-Ad, 1-Ad, 1-Ad, 1-Ad)
- BLENDING_FACTOR_ONE_MINUS_DST_COLOR: (1-Rd, 1-Gd, 1-Bd, 1-Ad)
- BLENDING_FACTOR_ONE_MINUS_SRC_ALPHA: (1-As, 1-As, 1-As, 1-As)
- BLENDING_FACTOR_DST_COLOR: (Rd, Gd, Bd, Ad)
- BLENDING_FACTOR_DST_ALPHA: (Ad, Ad, Ad, Ad)
- BLENDING_FACTOR_SRC_COLOR: (Rs, Gs, Bs, As)
- BLENDING_FACTOR_ONE_MINUS_SRC_COLOR: (1-Rs, 1-Gs, 1-Bs, 1-As)
dst_factor - specifies the blending destination factor. Please refer to the src_factor to see the acceptable
values - default value: BLENDING_FACTOR_ONE_MINUS_SRC_ALPHA

color element

color specifies the new color to be applied to all the vertices of the primitive.

Attributes:

r - [CLAMPED_REAL] - red component of the color. Float value ranging between 0.0 and 1.0 - default value: 1.0
g - [CLAMPED_REAL] - green component of the color. Float value ranging between 0.0 et 1.0 - default value: 1.0
b - [CLAMPED_REAL] - blue component of the color. Float value ranging between 0.0 and 1.0 - default value: 1.0
a - [CLAMPED_REAL] - alpha component the color. Float value ranging between 0.0 and 1.0 - default value: 1.0

position element

position specifies the position of the object in its local reference mark.

Attributes:

x - [REAL] - X coordinate of the position - default value: 0.0
y - [REAL] - Y coordinate of the position - default value: 0.0
z - [REAL] - Z coordinate of the position - default value: 0.0

orientation element

orientation specifies the orientation of the object around an arbitrary axis in its local reference mark.

Attributes:

ang - [REAL] - Rotation angle in degrees - default value: 0.0
x - [CLAMPED_REAL] - X component of the rotation axis - default value: 0.0
y - [CLAMPED_REAL] - Y component of the rotation axis - default value: 0.0
z - [CLAMPED_REAL] - Z component of the rotation axis - default value: 0.0

Example

<primitive>
	<orientation ang="90.0" x="0.0" y="0.0" z="1.0" />
</primitive>

In this example, the primitive makes a 90.0 degrees rotation around the Z axis.

Or with the Euler angles (PYR):

<orientation pitch="0.0" yaw="0.0" roll="90.0" />

plane element

plane specifies the parameters to initialize a PLANE type primitive.

Attributes:

width - [REAL] - width of the plane - default value: 20.0
height - [REAL] - height of the plane - default value: 20.0
texture_name - [STR127] - name of the texture node to be applied to this primitive
u_offset - [REAL] - shift of the U texture coordinate - default value: 0.0
v_offset - [REAL] - shift of the V texture coordinate - default value: 0.0

triangle element

triangle specifies the parameters to initialize a TRIANGLE type primitive.

Attributes:

index - [INTEGER] - index of the vertex to be initialized - default value: 0
x - [REAL] - X coordinate of the vertex position - default value: 0.0
y - [REAL] - Y coordinate of the vertex position - default value: 0.0
z - [REAL] - Z coordinate of the vertex position - default value: 0.0
r - [CLAMPED_REAL] - red component of the vertex color - default value: 0.0
g - [CLAMPED_REAL] - green component of the vertex color - default value: 0.0
b - [CLAMPED_REAL] - blue component of the vertex color - default value: 0.0

disc element

disc specifies the parameters to initialize a DISC type primitive.

Attributes:

outer_radius - [REAL] - outer radius of the disc - default value: 20.0
inner_radius - [REAL] - inner radius of the disc - default value: 0.0
slices - [INTEGER] - number of segments along the circumference of the disc - default value: 6

sphere element

sphere specifies the parameters to initialize a SPHERE type primitive.

Attributes:

outer_radius - [REAL] - outer radius of the sphere - default value: 20.0
inner_radius - [REAL] - inner radius of the sphere - default value: 0.0
slices - [INTEGER] - number of discs that make up the sphere - default value: 6

line element

line specifies the initialization parameters of a line segment.

Attributes:

x_start - [REAL] - X coordinate of the starting point - default value: -20.0
y_start - [REAL] - Y coordinate of the starting point - default value: -20.0
z_start - [REAL] - Z coordinate of the starting point - default value: -20.0
x_end - [REAL] - X coordinate of the ending point - default value: 20.0
y_end - [REAL] - Y coordinate of the ending point - default value: 20.0
z_end - [REAL] - Z coordinate of the ending point - default value: 20.0

Example

<line x_start="-40.0" y_start="-20.0" z_start="40.0"
    	 x_end="40.0" y_end="20.0" z_end="-40.0" />

quad element

quad specifies the initialization parameters of a quad (dimensions and logic states).

Attributes:

width - [REAL] - width along the x axis - default value: 20.0
height - [REAL] - height along the y axis - default value: 20.0
texture_name - [STR] - name of te texture to be applied
billboarding - [BOOLEAN] - enables (TRUE) or disables (FALSE - default) the billboarding - default value: FALSE
u_offset - [REAL] - shift of the U texture coordinate - default value: 0.0
v_offset - [REAL] - shift of the V texture coordinate - default value: 0.0

box element

box specifies the initialization parameters of a box.

Attributes:

width - [REAL] - width - default value: 20.0
height - [REAL] - height - default value: 20.0
depth - [REAL] - depth - default value: 20.0
texture_name - [STR] - name of the texture to be applied
billboarding - [BOOLEAN] - enables (TRUE) or disables (FALSE - default) the billboarding - default value: FALSE
u_offset - [REAL] - shift of the U texture coordinate - default value: 0.0
v_offset - [REAL] - shift of the V texture coordinate - default value: 0.0

spin_values element

spin_values specifies the rotation angles around the X, Y and Z axis. At each frame, the rotation angles of the primitive are incremented by the specified values. This generates an animation of the primitive by simple rotation around the 3 axis.

Attributes:

x - [REAL] - rotation angle around the X axis in degrees - default value: 0.0
y - [REAL] - rotation angle around the Y axis in degrees - default value: 0.0
z - [REAL] - rotation angle around the Z axis in degrees - default value: 0.0

nx_linear_velocity element

nx_linear_velocity allows to specify the linear velocity of an object. The speed parameters are taken into account only if the simulation physical engine has been activated in the scene node.

Attributes:

x - [REAL] - X coordinate of the gravity vector - default value: 0.0
y - [REAL] - Y coordinate of the gravity vector - default value: -9.81
z - [REAL] - Z coordinate of the gravity vector - default value: 0.0
damping - [REAL] - damping speed factor - default value: 0.5
sleep_threshold - [REAL] - sleeping threshold - default value: 0.14*0.14

nx_angular_velocity element

nx_angular_velocity makes it possible to specify the angular velocity of an object. The speed parameters are taken into account only if the physical simulation engine has been activated in the scene node.

Attributes:

x - [REAL] - X coordinate of the gravity vector - default value: 0.0
y - [REAL] - Y coordinate of the gravity vector - default value: -9.81
z - [REAL] - Z coordinate of the gravity vector - default value: 0.0
damping - [REAL] - damping speed factor - default value: 0.5
sleep_threshold - [REAL] - sleeping threshold - default value: 0.15*0.15

nx_misc_data element

nx_misc_data makes it possible to specify the angular velocity of an object. The speed parameters are taken into account only if the physical simulation engine has been activated in the scene node.

Attributes:

mass - [REAL] - mass of the object - default value: 100.0
density - [REAL] - density of the object - default value: 0.0
actor_type - [ENUM] - actor type (object):
- STATIC
- DYNAMIC - default value.
- KINEMATIC