oZone3D.Net - Demoniak3D Developer Guide

The <scene> node

Function

The purpose of the scene node is to install the general framework of a 3d scene : background color, window size, display of various informations. The scene is the main node since it is inside the 3d scene that everything takes place. The scene has also another fundamental role: it offers the absolute frame of reference (also called world coordinates) which makes it possible to position the different objects.

General Syntax

<scene
	name=""
	archive_filename=""
	screenshots_dir=""
	display_fps="FALSE"
	show_ref_grid="FALSE"
	vsync="TRUE"
	clear_color_buffer="TRUE"
	use_ppu="TRUE"
	use_window_offset="TRUE"
	warm_up_caches_cycles="1"
	nx_physics_simulation="FALSE"
	nx_collision_detection="TRUE"
	display_elapsed_time="FALSE" 
	display_texture_memory_occupation="FALSE" 
	display_all_statistics="FALSE" 
	display_hyperion_logo="TRUE"
	make_screenshots="FALSE"
	dump_lua_vm_stack="FALSE"  >
	
	
	<background_color
		r="0.3" 
		g="0.3" 
		b="0.3" />
		
	<infos_color
		r="1.0" 
		g="1.0" 
		b="0.0" />
		
	
	<background_image
		image="" />

	<check_hardware_caps
		glsl="FALSE" 
		dot3="FALSE" 
		cube_mapping="FALSE"
		vbo="FALSE"
		shader_model_1_1="FALSE"
		shader_model_2_0="FALSE"
		shader_model_3_0="FALSE"
		shader_model_4_0="FALSE" 
		num_texture_units="2" 
		s3tc="FALSE" 
		nvidia="FALSE" 
		ati="FALSE" 
		npot_rect="FALSE" 
		npot="FALSE" 
		fbo="FALSE" 
		fp_tex="FALSE" 
		vs_tex_samplers="0" 
		pvs_tex_samplers="4" 
		ati_3dc="FALSE" 
		error_message="FALSE" />
		
	
	<fog
		color_r="1.0" 
		color_g="1.0" 
		color_b="1.0" 
		color_a="1.0" 
		type="EXP2" 
		start="0.0" 
		end="1.0" 
		density="0.002" 
		active="FALSE" />
	
	<global_ambient_light
		r="0.1" 
		g="0.1" 
		b="0.1" 
		a="1.0" />
	
	<infos
		title="Title: Hyperion Demo" 
		author="Author: The oZone3D Team" 
		date="Date: Unknown" 
		description="Description: Hyperion Demo" />
	
	<picking
		active="FALSE" 
		script="" />

	<window_size
		width="1024" 
		height="768" 
		width_offset="0" 
		height_offset="0" 
		fullscreen="FALSE" />
		
	<ref_grid_color
		r="0.4" 
		g="0.4" 
		b="0.4" />
		
	<wait_screen
		image="" />
		
	<nx_gravity
		x="0.0" 
		y="-9.81" 
		z="0.0" />
		
	<nv_sli 
		active="TRUE" 
		mode="AFR" />		
		
</scene>

scene element

scene is the xml tag that defines a scene node.

Attributes:

name - [STR127] - name of the node. This name will make it possible to refer this node throughout the XML script.
archive_filename - [STR255] - access path to the ZIP file containing all the data of the demo. It is a very useful functionality which makes it possible to gather all the mediae and their directories within a same and single file. However there are some small limitations: animated textures (*.AVI) are not supported in the zip file and the 3d models must be in the *.o3mdl format (if not, models will neither be accessed nor loaded from the zip file).
display_fps - [BOOLEAN] - displays (TRUE) or hides (FALSE) the FPS (Frames Per Second) - default value: FALSE
The FPS (Frames Per Second) is the number of times per second a scene is redrawn and displayed on the the screen. It is an excellent indicator of the performances of the host machine and the weight of the scene: the higher the FPS is, the better it is!
show_ref_grid - [BOOLEAN] - displays (TRUE) or hides (FALSE) the grid of reference. This grid is located in the XZ plan at Y=0. Very useful to find one's way in the 3d environment - default value: FALSE
vsync - [BOOLEAN] - enables (TRUE) or disables (FALSE) the vertical synchronization. The vertical synchronization or VSYNC limits the frame rate to the value of the vertical screen refresh rate set in Windows: 60, 70, 72, 75, 85 or 100Hz. That makes it possible to synchronize the scene rendering with the VSYNC signal . This gives a nice, stable and neat rendering output. When VSYNC is disabled, the scene is rendered at the max of times possible and on can get FPS values which merrily exceed :100, 220, 482, 800...depending on the graphic controller. Of course these values correspond to scenes that are not too heavy - default value: TRUE
clear_color_buffer - [BOOLEAN] - enables (TRUE) or disables (FALSE) the initialization of the framebuffer (or colorbuffer) at the beginning of each frame. Generally, clear_color_buffer is set to TRUE in order to get for each new frame the colors buffer initialized with the color specified with the < background_color > tag. In some cases like for the skybox, the performance could be increased by not initializing the color buffer since the background color will never be visible - default value: TRUE
use_ppu - [BOOLEAN] - allows to use the PhysX card if it is present - default value: TRUE
use_window_offset - [BOOLEAN] - allows to use the offset values specified in window_size element - default value: TRUE
warm_up_caches_cycles - [INTEGER] - specifies the number of rendering to perform without updating the frame buffer. This number of rendering makes it possible to initialize all the internal caches (CPU, 3d engine, graphics controller). Usual value for performaing a benchmark is around 10 or 20 - default value: 1.
display_elapsed_time - [BOOLEAN] - displays (TRUE) or hides (FALSE) the elapsed time (in milliseconds) since the launching of the current script - default value: FALSE
display_texture_memory_occupation - [BOOLEAN] - displays (TRUE) or hides (FALSE) the quantity (in kilobytes) of textures that are loaded on the graphics controller - default value: FALSE
display_all_statistics - [BOOLEAN] - displays (TRUE) or hides (FALSE) all the available information (elapsed time, texture memory, number of rendered meshes, etc...) - default value: FALSE
screenshots_dir - [STR255] - specifies the destination directory for screenshots. Please refer to the HYP_MakeScreenshot function for more information.
nx_physics_simulation - [BOOLEAN] - enables (TRUE) or disables (FALSE) the physical engine (NovodeX Physics Engine) - default value: FALSE
nx_collision_detection - [BOOLEAN] - enables (TRUE) or disables (FALSE) the collision detection within level the physical engine (NovodeX Physics Engine) - default value: TRUE
display_hyperion_logo - [BOOLEAN] - enables (TRUE) or disables (FALSE) the rendering of the Hyperion's logo in the left-down corner of the 3D window - default value: TRUE
dump_lua_vm_stack - [BOOLEAN] - enables (TRUE) or disables (FALSE) the dump of LUA assert() and error() stack. The dump is written in a file called hyperion_lua_stack_dump.txt in the Hyperion's root directory. This option is available in commercial version only - default value: FALSE
make_screenshots - [BOOLEAN] - enables (TRUE) or disables (FALSE) the screenshot for every frame. The destination directory is specified by the screenshots_dir attribute - default value: FALSE

picking element

picking enables objects picking in the scene. The picking allows objects selection with the mouse in a 3d scene. Only mesh type objects can be picked. A LUA scripting code is associated with the picking and allows to perform any kinf of logic. The HYP_GetScenePickedObjectName() function of the Hyperion/LUA API makes it possible to get the name of the picked mesh.

Attributes:

active - [BOOLEAN] - enables (TRUE) or disables (FALSE) the picking - default value: FALSE
script - [STR255] - specifies the name of the script file which will be carried out with each picking. Full script file name relatively to the XML script file.

wait_screen element

wait_screen makes it possible to display a waiting image while loading the demo.

Attributes:

image - [STR255] - specifies the access path to the texture (or image) file.

window_size element

window_size makes it possible to specify the size of the client zone of the application in window mode or fullscreen mode.

Attributes:

width - [INTEGER] - width of the window in pixels - default value: 1024
height - [INTEGER] - height of the window in pixels - default value: 768
width_offset - [INTEGER] - X-offset of the window position. Not valid in fullscreen mode - default value: 0
height_offset - [INTEGER] - Y-offset of the window position. Not valid in fullscreen mode - default value: 0
fullscreen - [BOOLEAN] - switches from windowed to fullscreen mode - default value: FALSE

Remarks

In fullscreen mode, only some resolutions are valid and are dependent of your graphics card. The following resolutions are valid in most of cases:

320x200
640x480
800x600
1024x768
1280x1024
1600x1200
1920x1200

infos element

infos specifies information about the scene: the creation date, the author, the title, the description.

Attributes:

author - [STR127] - scene author - default value: "Author: The oZone3D Team"
date - [STR127] - creation date of the scene - default value: "Date: Unknown"
title - [STR127] - title of the scene - default value: "Title: Hyperion Demo"
description - [STR4095] - scene description - default value: "Description: Hyperion Demo"

infos_color element

infos_color specifies the color of the text used to display information such as the FPS, elapsed time, camera position, etc...

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: 0.0

background_color element

background_color specifies the background color of the scene.

Attributes:

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

global_ambient_light element

global_ambient_light specifies the color of the total ambient light of the scene.

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

background_image element

background_image specifies the name of a basic image. This image fills all the surface of the client zone. It cannot hide any object. Up to 100 basic images can be loaded by successive calls using the scene_background_image attribute. To display an unspecified background image will require LUA scripting using the HYP_ActiveBkgImage() function of the Hyperion/LUA API. Useful to build up a slideshow.

Attributes:

image - [STR255] - Full name of the image file relatively to the XML script file.

check_hardware_caps element

check_hardware_caps makes it possible to test the hardware characteristics of the graphics controller and to stop launching the demo if the graphics board does not have those necessary capabilities. Each attribute is a boolean which indicates the capacity to be tested.

Attributes:

glsl - [BOOLEAN] - TRUE to activate the test of the OpenGL Shading Language support - default value: FALSE
dot3 - [BOOLEAN] - TRUE to activate the test of the Hardware DOT3 Bump Mapping support - default value: FALSE
cube_mapping - [BOOLEAN] - TRUE to activate the test of the Hardware Cubes Mapping support - default value: FALSE
vbo - [BOOLEAN] - TRUE to activate the test of the VBO OpenGL support - default value: FALSE
shader_model_1_1 - [BOOLEAN] - TRUE to activate the test of the shader model 1.1 - default value: FALSE
shader_model_2_0 - [BOOLEAN] - TRUE to activate the test of the shader model 2.0 - default value: FALSE
shader_model_3_0 - [BOOLEAN] - TRUE to activate the test of the shader model 3.0 - default value: FALSE
num_texture_units - [INTEGER] - indicates the minimal number of textures units that the controller must have to run the demo - default value: 2
s3tc - [BOOLEAN] - TRUE to activate the test of the compressed textures support - default value: FALSE
nvidia - [BOOLEAN] - TRUE to limit the execution of demo on nVidia graphics chipsets only - default value: FALSE
ati - [BOOLEAN] - TRUE to limit the execution of demo on ATI graphics chipsets only - default value: FALSE
npot_rect - [BOOLEAN] - TRUE to limit the execution of demo on graphics chipsets that support texture rectangles only - default value: FALSE
npot - [BOOLEAN] - TRUE to limit the execution of demo on graphics chipsets that support NPOT (Non Power Of Two) texture only - default value: FALSE
fbo - [BOOLEAN] - TRUE to limit the execution of demo on graphics chipsets that support Framebuffers Objects only - default value: FALSE
fp_tex - [BOOLEAN] - TRUE to limit the execution of demo on graphics chipsets that support floating point textures only - default value: FALSE
vs_tex_samplers - [INTEGER] - specify the mininal number of accessible texture units in a vertex shader - default value: 0
ps_tex_samplers - [INTEGER] - specify the mininal number of accessible texture units in a pixel shader - default value: 4
ati_3dc - [BOOLEAN] - TRUE to limit the execution of demo on graphics chipsets that support ATI 3Dc texture compression only - default value: FALSE
error_message - [STR511] - character string displaying a personalized error message. This message will be displayed if one of the previous tests is not valid.

fog element

fog specifies the parameters to initialize a basic fog in the 3d scene.

Attributes:

active - [BOOLEAN] - enables (TRUE) or disables (FALSE) the fog - default value: FALSE
color_r - [CLAMPED_REAL] - red component of the fog color - default value: 1.0
color_g - [CLAMPED_REAL] - green component of the fog color - default value: 1.0
color_b - [CLAMPED_REAL] - blue component of the fog color - default value: 1.0
color_a - [CLAMPED_REAL] - alpha component of the fog color - default value: 1.0
type - [ENUM] - fog type:
- EXP2: the fog has an exponential growth - default value
- EXP: the fog has an exponential growth.
- LINEAR: the fog has a linear growth.
start - [REAL] - makes it possible to specify the starting value of the fog compared to the position of the camera - default value: 0.0
end - [REAL] - makes it possible to specify the ending value of the fog compared to the position of the camer - default value: 1.0
density - [REAL] - density in the case of EXP or EXP2 type fog - default value: 0.002

Example

<scene>
	<fog active="TRUE" type="EXP2" start="0.0" end="1.0" 
    	    density="0.003" color_r="0.7" color_g="0.7" color_b="0.7" />
<scene/>

ref_grid_color element

ref_grid_color specifies the color of the reference grid in the XZ plan at Y=0.

Attributes:

r - [CLAMPED_REAL] - red component of the color - default value: 0.4
g - [CLAMPED_REAL] - green component of the color - default value: 0.4
b - [CLAMPED_REAL] - blue component of the color - default value: 0.4

nx_gravity element

nx_gravity specifies the gravity vector for physical simulations. This vector is taken into account only if the physical engine is enabled.

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

nv_sli element

nv_sli allows to control the SLI run mode of nVidia cards.

Attributes:

active - [BOOLEAN] - enables (TRUE) or disable (FALSE) the use of SLI - default value: TRUE
mode - [ENUM] - specifies the frame rendering mode of SLI. The flollowing values are valid:
- 0 (AUTO_SELECT)
- 1 (AFR) - default value
- 2 (SFR)
- 4 (COMPATIBILITY)