oZone3D.Net - Demoniak3D Developer Guide

The <camera> element

Function

The camera node is one of the most important nodes of the Hyperion XML script. It makes it possible to specify the entity by which the 3d scene can be seen. A camera is mainly defined by a position in the 3D space, a point of vision (lookat), a field of vision (fov) and by clipping planes (near and far clipping plane). Several cameras can be declared, but only the one which has an active state (camera_active_state) will be taken into account. Other cameras can also be activated with a LUA scripting code (or other scripting languages: Python, etc...).

By default, Hyperion creates a camera of the "FLY" type : this camera makes it possible to move anywhere in the 3d scene.

General syntax

<camera
	name=""
	navigation_mode="FLY"
	active="TRUE"
	fov="60.0"
	mouse_move_speed="0.25"
	mouse_wheel_speed="100.0"
	keyboard_speed="100.0"
	display_position="FALSE"
	display_view_direction="FALSE"
	display_orientation="FALSE"
	motion_path=""
	play_motion_path="FALSE"
	motion_path_time_offset="0.0"
	motion_path_time_step="0.01"
	display_motion_path_curve="FALSE"
	display_motion_path_tangents="FALSE"
	near_plane="1.0"
	far_plane="4000.0"
	target_object=""
	frustum_culling_test_shape="BOUNDING_SPHERE"
	inertia="TRUE"
	linear_speed="100.0"
	inertia_linear_damping="500.0"
	widescreen="FALSE" >
	
	
	<add_child
		name="" />
	

	<limit_position
		x_min="-10000.0" 
		y_min="-10000.0" 
		z_min="-10000.0" 
		x_max="10000.0" 
		y_max="10000.0" 
		z_max="10000.0"  />
		
	<limit_angle
		pitch_min="-80.0" 
		pitch_max="80.0" />
	

	<lookat
		x="0.0" 
		y="0.0" 
		z="0.0" 
		w="1.0" />
		
	<orientation
		pitch="0.0" 
		yaw="0.0" 
		roll="0.0" />
		
	<bkg_color
		r="0.0" 
		g="0.0" 
		b="0.0" />

	<position
		x="0.0" 
		y="100.0" 
		z="150.0" />

	<up
		x="0.0" 
		y="1.0" 
		z="0.0" />

	<viewport
		x="0.0" 
		y="0.0" 
		width="1024" 
		height="768" />
</camera>

camera

camera is the xml tag that defines a camera node.

Attributes:

active - [BOOLEAN] - enables (TRUE) or disables (FALSE) the camera - default value: TRUE
far_plane - [REAL] - camera distance from the far clipping plane on the Z axis. Objects located behind this plane will not be displayed - default value: 4000.0
fov - [REAL] - specifies the Field Of View in degrees - default value: 60.0
display_motion_path_curve - [BOOLEAN] - enables (TRUE) or disables (FALSE - default) the display of the motion path - default value: FALSE
display_motion_path_tangents - [BOOLEAN] - enables (TRUE) or disables (FALSE - default) the display of the motion path tangents - default value: FALSE
display_position - [BOOLEAN] - enables (TRUE) or disables (FALSE - default) the display of the camera position in the <X Y Z> form. Information is displayed in the upper left part of the 3d client zone - default value: FALSE
display_view_direction - [BOOLEAN] - enables (TRUE) or disables (FALSE - default) the display of the camera view vector in the <X Y Z> form. Information is displayed in the upper left part of the 3d client zone - default value: FALSE
display_orientation - [BOOLEAN] - enables (TRUE) or disables (FALSE - default) the display of the camera orientation in the form of the Euler's angles <pitch yaw roll>. Information is displayed in the upper left part of the 3d client zone - default value: FALSE
keyboard_speed - [REAL] - keyboard sensitivity for backward, forward and strafe - default value: 100.0
motion_path - [STR127] - name of the motion path. This name must refer to a valid motion_path node.
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
motion_path_time_step - [REAL] - makes it possible to control the animation speed by specifying the time increment along the motion-path. Time is standardized along the motion-path, i.e. the time value is 0.0 for the first keyframe and 1.0 for the last one. - default value: 0.01
mouse_wheel_speed - [REAL] - sensitivity of the mouse wheel for backward and forward - default value: 100.0
mouse_move_speed - [REAL] - sensitivity of the mouse movement for rotations - default value: 0.25
name - [STR127] - name of the node. This name will make it possible to refer to this node throughout the XML script.
navigation_mode: - [ENUM] - navigation mode of the camera - default value: FLY
The following values are accepted:
- WALK: allows to move only in the X-Z plan.
- EXAMINE: moves the camera around a sphere whose center is positioned with the <camera_lookat> element. In this mode, the camera cannot enter the 10.0 units radius sphere that is centered in the <camera_lookat> values.
- FLY: allows to move anywhere in the scene. In this mode, pressing the [Ctrl]+[Left_Mouse] keys allows to make a strafe (or pan). Default value.
- DOOM_LIKE: similar to the the FLY mode, except that there is no need to press anymore the mouse left button to turn the camera. In this mode, the mouse cursor is automatically hidden.
- QUAKE_LIKE: similar to the the WALK mode, except that there is no need to press anymore the mouse left button to turn the camera. In this mode, the mouse cursor is automatically hidden.
- FIXED: fixed camera without any possible displacement.
Functionalities of the keys depending on the keyboard (Swiss, French or English):
- Keyboard with a Swiss layout
  - [W]: camera forward
  - [S]: camera backward
  - [A]: camera left strafe
  - [D]: camera right strafe
- Keyboard with a French or English layout (USA)
  - [Z]: camera forward
  - [S]: camera backward
  - [Q]: camera left strafe
  - [D]: camera right strafe
near_plane - [REAL] - camera distance from the near clipping plane on the Z axis. Objects located before this plan will not be displayed. - default value: 1.0
play_motion_path - [BOOLEAN] - enables (TRUE - default) or disables (FALSE) the position animation along the motion path - default value: TRUE
target_object - [STR127] - name of the object which will be used as a camera aiming target, i.e. the object towards which is pointing the camera view vector. That makes it possible to always keep a specific object in the field of vision of the camera. This name must refer to a valid node.
frustum_culling_test_shape - [ENUM] - allows to specify the bounding volume type used in camera frustrum culling tests. The following values are accepted:
- BOUNDING_SPHERE - default value
- BOUNDING_BOX
inertia - [BOOLEAN] - enables (TRUE - default) or disable (FALSE) the handling of camera inertia for linear movements - default value: TRUE
linear_speed - [REAL] - specify the camera linear speed in units per second. Same effect as keyboard_speed - default value: 100.0
inertia_linear_damping - [REAL] - set the damping factor of linear speed in units per second - default value: 500.0
widescreen - [BOOLEAN] - enables (TRUE) or disables (FALSE - default) the 16:9 mode - default value: FALSE

add_child element

add_child makes it possible to add a child to the current camera. This allows to easily set up complex hierarchies. Any transformation (rotation or translation) of the current active camera will have repercussions on the children. This allows to set up in a very simple way a Doom-Like style demonstration where an object (for example a rifle) is attached as a child to the camera.

Attributes:

name - [STR127] - Name of the child object.

limit_angle element

limit_angle makes it possible to define the limiting rotation angles of the camera. This instruction is mainly used with the EXAMINE mode to limit the camera pitch. Very useful to limit the camera position at the ground level for example.

Attributes:

pitch_min - [REAL] - minimal angle pitch in degrees - default value: -80.0.
pitch_max - [REAL] - maximum angle pitch in degrees - default value: 80.0.

limit_position element

limit_position makes it possible to define a 3d parallelepiped which fixes the limiting volume of the camera positions in the 3d scene. This element does not have sub-elements but xml attributes.

Attributes:

x_min, y_min, z_min - [REAL] - limiting minimal position. It corresponds to the lower left corner of the parallelepiped. By default, these three values are set to -10000.0.
x_max, y_max, z_max - [REAL] - limiting maximum position. It corresponds to the upper right corner of the parallelepiped. By default, these three values are set to 10000.0.

Example

<camera name="cam" >
	<limit_position x_min="-200.0" y_min="10.0" z_min="-200.0"
                       x_max="200.0" y_max="100.0" z_max="200.0" />
</camera>

In this example, the camera will never be able to go down below y=10.0. Very useful for not crossing the ground.

lookat element

lookat makes it possible to position the camera point of vision in the 3d scene space. The lookat 4d vector can be used in two ways:

if the W coordinate is equal to 1.0: lookat represents a position in the 3d scene.
if the W coordinate is equal to 0.0: lookat represents the view direction vector.

Attributes:

x - [REAL] - X coordinate of the camera aiming point - default value: 0.0
y - [REAL] - Y coordinate of the camera aiming point - default value: 0.0
z - [REAL] - Z coordinate of the camera aiming point - default value: 0.0
w - [REAL] - W coordinate of the camera aiming point - default value: 1.0

orientation element

orientation specifies the initial orientation of the camera. But this orientation is interpreted in two ways according to the navigation mode (FLY or EXAMINE). In FLY mode, the pitch, yaw and roll angles are interpreted in a traditional way, i.e. they express a rotation around the axis of the camera local tripod. In EXAMINE mode, they express a rotation around the absolute axis of the 3d world and the roll angle is not taken into account. Moreover, in EXAMINE mode, there is from the beginning a 90.0 degrees yaw shift.

Attributes:

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

Example

<camera name="cam" navigation_mode="EXAMINE" >
	<orientation pitch="20.0" yaw="90.0" />
</camera>

This example makes it possible to initialize a camera in EXAMINE mode by taking in account the of 90.0 shift on the yaw angle.

El�ment bkg_color

bkg_color specifies the camera background color.

Attributs:

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

position element

position specifies the position in the scene 3d.

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

up element

up specifies the orientation vector of the camera.

Attributes:

x - [REAL] - X coordinate of the camera aiming point - default value: 0.0
y - [REAL] - Y coordinate of the camera aiming point - default value: 1.0
z - [REAL] - Z coordinate of the camera aiming point - default value: 0.0

viewport element

viewport specifies the screen zone where the 3d scene will be rendered. By default, the viewport adopts dimensions of the client 3d zone defined by <window_size>.

Attributes:

x - [INTEGER] - X coordinate of the bottom_left point of the viewport - default value: 0
y - [INTEGER] - Y coordinate of the bottom_left point of the viewport - default value: 0
width - [INTEGER] - width of the viewport - default value: 1024
height - [INTEGER] - height of the viewport - default value: 768