oZone3D.Net - Demoniak3D Developer Guide

Demoniak3D/LUA API: General functions

These functions are not specific to 3d graphics programming but perform useful tasks, such as getting the elapsed time, displaying a dialog box, opening HTML pages, etc...

HYP_GetHyperionVersion
HYP_DrawText
HYP_GetElapsedTime
HYP_GetElapsedTimeSeconds
HYP_GetElapsedTimeMilliSeconds
HYP_GetElapsedTimeMicroSeconds
HYP_GetTimeStep
HYP_GetBaseDir
HYP_GetHyperionDir
HYP_MsgBox
HYP_OpenHTML
HYP_StopApp
HYP_Wait
HYP_GetGCModelString
HYP_GetGCVendorString
HYP_IsATI
HYP_IsNVIDIA
HYP_Project3DTo2D
HYP_Project2DTo3D

HYP_DrawText

HYP_DrawText allows to display text through a LUA script. The frame of reference for the position of the beginning of the text is that of the screen: the (0, 0) coordinate represents the left upper corner of the 3d window.

Syntax

HYP_DrawText( x, y, r, g, b, text );

x - [INTEGER] - X position of the beginning of the text.
y - [INTEGER] - Y position of the beginning of the text.
r - [CLAMPED_REAL] - red component of the text color.
g - [CLAMPED_REAL] - green component of the text color.
b - [CLAMPED_REAL] - blue component of the text color.
text - [STR255] - text to display.

Example

-- test de HYP_GetElapsedTime.
str = "Time: " .. HYP_GetElapsedTime() .. " ms";
HYP_DrawText( 10, 100, 1.0, 1.0, 1.0, str );

HYP_GetElapsedTime

HYP_GetElapsedTime allows to get the elapsed time in milliseconds since the beginning of the XML Hyperion script.

Syntax

elapsed_time_milli_sec = HYP_GetElapsedTime();

HYP_GetElapsedTimeSeconds

HYP_GetElapsedTimeSeconds allows to get the elapsed time in seconds since the beginning of the XML Hyperion script.

Syntax

elapsed_time_sec = HYP_GetElapsedTimeSeconds();

HYP_GetElapsedTimeMilliSeconds

HYP_GetElapsedTimeMilliSeconds allows to get the elapsed time in milliseconds since the beginning of the XML Hyperion script.

Syntax

elapsed_time_milli_sec = HYP_GetElapsedTimeMilliSeconds();

HYP_GetElapsedTimeMicroSeconds

HYP_GetElapsedTimeMicroSeconds allows to get the elapsed time in microseconds since the beginning of the XML Hyperion script.

Syntax

elapsed_time_micro_sec = HYP_GetElapsedTimeMicroSeconds();

HYP_GetTimeStep

HYP_GetTimeStep allows to get the elapsed time between 2 consecutive frames in seconds. Useful to get physics simulation time step.

Syntax

time_step = HYP_GetTimeStep();

HYP_MsgBox

HYP_MsgBox allows to display a dialog box with a message. This function accepts two types of message:

the first displays the box with a title and a text.
the second displays only the text with a default title which is "Hyperion Info".

Syntax

HYP_MsgBox( title, text );
HYP_MsgBox( text );

title - [STR255] - dialog box title.
text - [STR2047] - dialog box body.

Example

-- test de HYP_MsgBox.
text = "Picked Object Name = " .. HYP_GetScenePickedObjectName();
HYP_MsgBox( "Scene Picking", text );
...

HYP_OpenHTML

HYP_OpenHTML allows to open a HTML page (locally or on the Internet). This function has two working types:

there is an argument: it is then the URL (Internet address) to open with the default browser.
there are two arguments: the first indicates the location of the browser, and the second that of the URL.

Currently, in the one argument type, only the Explorer and FireFox browsers are supported.

Syntax

HYP_OpenHTML( url );
HYP_OpenHTML( browser, url );

url - [STR255] - url.
browser - [STR255] - browser location.

Example

-- test de HYP_OpenHTML.
HYP_OpenHTML( "http://www.ozone3d.net" );

-- test de HYP_OpenHTML.
HYP_OpenHTML( "C:\\Program Files\\mozilla firefox\\firefox.exe", 
"http://www.ozone3d.net" );
HYP_OpenHTML( "C:\\Program Files\\Internet Explorer\\iexplore.exe",
"http://www.ozone3d.net" );

...

HYP_StopApp

HYP_StopApp allows to stop the script in progress and to quit Hyperion.

Syntax

HYP_StopApp();

Example

-- test HYP_StopApp.
HYP_StopApp();

HYP_Wait

HYP_Wait allows to make a pause whose duration is expressed in milliseconds.

Syntax

HYP_Wait( delay );

delay - [INTEGER] - delay in milliseconds.

Example

-- test de HYP_Wait.
-- 1 second:
HYP_Wait( 1000 );
...

Hyperion - Reference Guide
Copyright (C)2004-2005 The oZone3D Team - All rights reserved
http://www.oZone3D.Net

HYP_GetBaseDir

HYP_GetBaseDir allows to retrieve the base directory of the demo main XML script. This function is useful in order to specify the path to a file in LUA scripts.

Syntax

base_dir = HYP_GetBaseDir();

base_dir - [STR255] - base directory.

Exemple

file = io.open( HYP_GetBaseDir() .. "/data/squelette.can", "r");

HYP_GetHyperionDir

HYP_GetHyperionDir allows to retrieve the base directory of Hyperion. This function is useful in order to specify the path to the hyperion_lua_host_api_defines.lua file for instance.

Syntax

base_dir = HYP_GetHyperionDir();

base_dir - [STR255] - base directory.

Exemple

dofile( HYP_GetHyperionDir() .. "/hyperion_lua_host_api_defines.lua" );

HYP_GetGCModelString

HYP_GetGCModelString allows to retrieve the graphics controller model name. For nVidia, the string will look like "GeForce 7800 GT/PCI/SSE2" and for ATI, it will look like "RADEON X700 x86/MMX/3DNow!/SSE2".

Syntax

gc_model = HYP_GetGCModelString();

gc_model - [STR127] - graphics card model.

HYP_GetGCVendorString

HYP_GetGCVendorString allows to retrieve the graphics chipset vendor name. For nVidia, the string will look like "NVIDIA Corporation" and for ATI, it will look like "ATI Technologies Inc".

Syntax

vendor = HYP_GetGCVendorString();

vendor - [STR127] - vendor name.

HYP_IsATI

HYP_IsATI allows to check if the graphics chipset is from ATI.

Syntax

result = HYP_IsATI();

result - [INTEGER] - 1 if ATI else 0.

HYP_IsNVIDIA

HYP_IsNVIDIA allows to check if the graphics chipset is from nVidia.

Syntax

result = HYP_IsNVIDIA();

result - [INTEGER] - 1 if nVidia else 0.

HYP_Project3DTo2D

HYP_Project3DTo2D projects a 3D point in world coordinates into a 2D point in screen coordinates. The screen space is as follows:

+Y
|
|
|
|
+------------ +X
0,0

Syntax

screen_x, screen_y = HYP_Project3DTo2D( pos_x, pos_y, pos_z );

pos_x, pos_y, pos_z - [REAL] - position in 3D world coordinates.
screen_x, screen_y - [INTEGER] - position in screen coordinates.

HYP_Project2DTo3D

HYP_Project2DTo3D projects a 2D point in screen coordinates into a 3D point in world coordinates. The screen space is as follows:

+Y
|
|
|
|
+------------ +X
0,0

Syntax

pos_x, pos_y, pos_z = HYP_Project2DTo3D( screen_x, screen_y );

pos_x, pos_y, pos_z - [REAL] - position in 3D world coordinates.
screen_x, screen_y - [INTEGER] - position in screen coordinates.

HYP_GetHyperionVersion

HYP_GetHyperionVersion allows to get the current version of Hyperion. Example: 1.16.0: 1 is the major version, 16 is the minor version and 0 is the patch version.

Syntax

ver_major, ver_minot, ver_patch = HYP_GetHyperionVersion();

ver_major - [INTEGER] - major version number
ver_minor - [INTEGER] - minor version number
ver_patch - [INTEGER] - patch version number