oZone3D.Net - Demoniak3D Developer Guide

The <light> node

Function

The light node is the object which makes it possible to represent a dynamic light. In the case of a dynamic light, lighting calculations are completely processed at each frame and for each object that has its lighting attribute set to TRUE. Thus, the more lights there will be, the longer will be the calculations and the more the FPS will decrease. The maximum number of dynamic lights is limited by the hardware. They are generally eight. The GPU Caps Viewer utility makes it possible to know this number.

<light
	name=""
	render="FALSE"
	display_tripod="FALSE"
	auto_update_direction="FALSE"
	type="OMNI" 
	linear_att="0.0"
	constant_att="1.0"
	quadratic_att="0.0"
	radius="10000.0"
	spot_angle="30.0"
	shadow_emitter="TRUE"
	motion_path=""
	play_motion_path="TRUE"
	motion_path_time_step="0.001" 
	motion_path_time_offset="0.0"
	display_motion_path_curve="FALSE"
	display_motion_path_tangents="FALSE"
	link_to_motion_path="FALSE" >
	
	<position
		x="0.0" 
		y="0.0" 
		z="0.0" />

	<orientation
		ang="0.0" 
		x="0.0" 
		y="0.0" 
		z="0.0" 
		pitch="0.0" 
		yaw="0.0" 
		roll="0.0" />

	<ambient
		r="0.2" 
		g="0.2" 
		b="0.2" 
		a="1.0" />
	
	<diffuse
		r="1.0" 
		g="1.0" 
		b="1.0" 
		a="1.0" />
		
	<specular
		r="0.1" 
		g="0.1" 
		b="0.1" 
		a="1.0" />

</light>

light element

light is the xml tag that defines a light node.

Attributes:

name - [STR127] - name of the node. This name will make it possible to refer this node throughout the XML script.
type - [STR127] - type of light:
- OMNI: omnidirectional light or position light (default value). This type of light lights the scene in all the directions. It is defined by a position in the 3d space - default value.
- DIRECTIONAL: directional (or infinite) light. This type of light lights the scene in a particular direction. It is defined by a direction vector but does not have any position.
- SPOT: positional and directional light. This type of light lights the scene in a particular direction and from a position. It is defined by a direction vector and it has one position in the 3d scene and an aperture angle (spot cone).
render - [BOOLEAN] - enables (TRUE) or disables (FALSE) the rendering of the light position (positional light) or of its direction vector (directional light) - default value: FALSE
shadow_emitter - [BOOLEAN] - allows to specify whether the light is a source of shadow or not - default value: TRUE
display_tripod - [BOOLEAN] - display (TRUE) or hide (FALSE) the light tripod (or local reference mark). The visualization of the tripod is useful in the case of a SPOT type light for setting the direction. - default value: FALSE
auto_update_direction - [BOOLEAN] - enables (TRUE) or disables (FALSE) the automatic update of the direction (Z axis) of the object local reference mark (tripod) - default value: FALSE
constant_att - [REAL] - specifies the constant attenuation factor of the light with the distance (more precisely, the distance between the light position and a vertex). Therefore, it is obvious that attenuation factors do not apply to a DIRECTIONAL type light - default value: 1.0

Reminder: the total attenuation factor of the light is defined by:
```
		                                1.0
att_global = ---------------------------------------------------------
             constant_att + (linear_att * d) + (quadratic_att * d * d)
```
where d is the distance between the light and the vertex being processed.
linear_att - [REAL] - specifies the linear attenuation factor of the light with the distance - default value: 0.0
display_motion_path_curve - [BOOLEAN] - enables (TRUE) or disables (FALSE) the display of the motion path - default value: FALSE
display_motion_path_tangents - [BOOLEAN] - enables (TRUE) or disables (FALSE) the display of the tangents to the motion path - default value: FALSE
motion_path - [STR127] - name of the motion path to which is attached the gizmo in order to perform automatic displacements.
motion_path_time_step - [REAL] - makes it possible to control the animation speed by specifying the temporal increment along the motion-path. Time is standardized along the motion-path, i.e. time equals 0.0 for the first keyframe and 1.0 for the last one - default value: 0.001
motion_path_time_offset - [REAL] - makes it possible to control the starting time value of the animation. By default this starting value is the standardized time 0.0. This offset makes it possible to place several objects on one motion-path with a time-lag (offset) between each one of them - default value: 0.0
play_motion_path - [BOOLEAN] - enables (TRUE) or disables (FALSE) the animation of the position along one motion path - default value: TRUE
quadratic_att - [REAL] - specifies the light's quadratic attenuation factor with the distance - default value: 0.0
radius - [REAL] - specifies the maximum light range ray (in the case of a positional light). This value is used with vertexes and pixel shaders - default value: 10000.0
spot_angle - [REAL] - makes it possible to regulate the cone of light aperture. This instruction is not valid that for a SPOT type light - default value: 30.0

ambient element

ambient allows to set the ambient color of the light. Let us recall that the ambient light is a light which seems to come from everywhere at the same time. To represent it, you just have to look at the shade of an object. The color of the shade is in close relationship with the ambient light.

Attributes:

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

diffuse element

diffuse allows to regulate the diffuse component of the light. Let us recall that the diffuse light is the one which directly lights an object. There is a direct relation between the quantity of light received by a face of an object and the angle formed by the normal to this face and the light position.

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 and 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 of the color. Float value ranging between 0.0 and 1.0 - default value: 1.0

orientation element

orientation specifies the orientation of the light around an arbitrary axis in its local reference mark. This method works only for a SPOT or directionnal light type. There are 2 ways of using the attributes of this element: either by using the [ang, x, y, z] quadruplets or by using the [pitch, yaw, roll] triplets.

Attributes:

ang - [REAL] - rotation angle in degrees around the axis formed by x, y and z - 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
pitch - [REAL] - rotation angle in degrees around the X axis - default value: 0.0
yaw - [REAL] - rotation angle in degrees around the Y axis - default value: 0.0
roll - [REAL] - rotation angle in degrees around the Z axis - default value: 0.0

position element

position specifies the position of the light in the 3d scene. This instruction is valid only for an OMNI or SPOT type light.

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

specular element

specular makes it possible to set the specular component of the light. Let us recall that the specular light is person in charge for the reflections (which one calls specular reflections) on the surface of an object. Specular reflections vary with the position from the point of view and thus of the camera.

Attributes:

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