oZone3D.Net - Demoniak3D Developer Guide

The <hud> node

Function

The hud node makes it possible to define 2d elements always displayed on the foreground (as if they were stuck to the camera). Hud comes from " Head Up Display ". The majority of the games uses it to render the scores, the ammunition or standards of living. It is relatively significant for the finalization of a scene. Moreover almost all tutorials delivered with Demoniak3D integrate one or more Huds.

<hud
	name=""
	render="TRUE"
	texturing="TRUE"
	material_name=""
	auto_spin="FALSE" >

	<alpha_test_params 
		active="FALSE" 
		func="CMP_FUNC_GREATER" 
		ref="0.5" />

	<position
		x="0.0" 
		y="0.0" />
	
	<size
		width="320" 
		height="200" />
		
	<spin_values
		x="0.0" 
		y="0.0" 
		z="0.0" />
		

	<texture
		texture_unit="0" 
		texture_name="" 
		u_tile="1.0" 
		v_tile="1.0" 
		u_offset="0" 
		v_offset="0" 
		u_move="0" 
		v_move="0" />

	<vertex_color
		index="0" 
		r="1.0" 
		g="1.0" 
		b="1.0" 
		a="1.0"  />
		
	<blending_params 
		active="FALSE" 
		src_factor="BLENDING_FACTOR_SRC_ALPHA" 
		dst_factor="BLENDING_FACTOR_ONE_MINUS_SRC_ALPHA" />
		
</hud>

hud element

hud is the xml tag that defines a hud node.

Attributes:

name - [STR127] - node name. This name will make it possible to refer this node throughout the XML script.
material_name - [STR127] - name of the material to be assigned to this hud. If this name is not specified, a default name will be automtically generated. If this name is specified, it references the material node in the XML code.
texturing - [BOOLEAN] - enables (TRUE) or disables (FALSE) texture application on the hud - default value: TRUE
blending - [BOOLEAN] - enables (TRUE) or disables (FALSE) the colors mixture - default value: FALSE
blending_src_factor - [ENUM] - specifies the blending source factor - default value: BLENDING_FACTOR_SRC_ALPHA
blending_dst_factor specifies the blending 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 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) (default value)
- 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)
Note: The mixture of the colors will be effective only if the blending is activated.
blending_dst_factor - [ENUM] - specifies the blending destination factor. Please refer to blending_src_factor to check the acceptable values - default value: BLENDING_FACTOR_ONE
render - [BOOLEAN] - enables (TRUE) or disables (FALSE) the HUD rendering - default value: TRUE
group - [STR127] - name of the group wherre you can add the current node. A group makes it possible to control the behavior of several objects in a single way.

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

position element

position specifies X and Y position of the hud center. The frame of reference is the oZone3D one, where the (0, 0) coordinates are in the center of the 3d client zone, the x axis is directed from left to right and the Y axis from the bottom to the top.

Attributes:

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

texture element

texture makes it possible to apply a texture and to specify the parameters for this texture.

Attributes:

texture_unit - [INTEGER] - texture unit to be used for the texture. Integer value included between 0 et 3 - default value: 0
texture_name - [STR127] - name of the used texture.
u_tile - [REAL] - tiling factor for the U coordinate - default value: 1.0
v_tile - [REAL] - tiling factor for the V coordinate - default value: 1.0
u_offset - [REAL] - shift of the U coordinate - default value: 0.0
v_offset - [REAL] - shift of the V coordinate - default value: 0.0
u_move - [REAL] - U coordinate increment at each frame - default value: 0.0
v_move - [REAL] - V coordinate increment at each frame - default value: 0.0

spin_values element

Specifies the rotation angles around the X, Y and Z axis. At each frame, the HUD rotation angles are incremented by the specified values. But in the case of a HUD element, only the animation around the axis of Z has a direction.

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

Remark

The previous values take effect only if the auto_spin attribute is set to "TRUE".

vertex_color element

vertex_color specifies the new color to be applied to one of the four vertices which defines the HUD. In a hud, the four vertices are indexed as follows:

2 +----------------------+ 3
  |                      |
  |                      |
  |                      |
  |                      |
  |                      |
0 +----------------------+ 1

Attributes:

index - [INTEGER] - index of the vertex to be changed. Value ranging between 0 and 3 - default value: 0
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

size element

size makes it possible to set the hud dimensions.

Attributes:

width - [INTEGER] - width of the hud in pixels - default value: 320
height - [INTEGER] - height of the hud in pixels - default value: 200

Example

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<hyperion version="1.0" >
	<scene name="myScene" show_ref_grid="FALSE" >
		<background_color r="0.0" g="0.0" b="0.0" />
	</scene>
	<camera name="myCamera" />
	<texture name="bglass" filename="bglass.tga" pixel_format="RGBA" />
	<hud name="vitre" 
	    blending="TRUE"  
		blending_src_factor="BLENDING_FACTOR_SRC_ALPHA"
        blending_dst_factor="BLENDING_FACTOR_ONE" >
		<texture texture_name="bglass" texture_unit="0" />
	</hud>
</hyperion>