» Back To Index
Demoniak3D/LUA API: Scene handling library
The
HYP_Scene performs general operations on the scene.
HYP_Scene.ActiveBkgImage
HYP_Scene.SetBackgroundColor
HYP_Scene.EnableFog
HYP_Scene.DisableFog
HYP_Scene.Render
HYP_Scene.SetRenderTarget
HYP_Scene.SetRenderTargetTexture
HYP_Scene.AddObject
HYP_Scene.DisableGroup
HYP_Scene.EnableGroup
HYP_Scene.RemoveObject
HYP_Scene.PickMesh
HYP_Scene.FboGetDefault
HYP_Scene.FboBind
HYP_Scene.FboSetRenderDestination
HYP_Scene.FboAttachTexture
HYP_Scene.FboAllocReadBufferRgba32f
HYP_Scene.FboFreeReadBufferRgba32f
HYP_Scene.FboGetValueReadBufferRgba32f
HYP_Scene.NvSliGetNumGpus
HYP_Scene.NvSliSetState
HYP_Scene.NvSliGetState
HYP_Scene.NvSliSetMode
HYP_Scene.NvSliGetMode
HYP_Scene.GetRayOriginAndDirection
HYP_Scene.LoadXml
HYP_Scene.GetWindowSize
HYP_Scene.CastRay
CastRay
CastRay allows to cast a ray to check collision against scene meshes.
Syntax
id, cx, cy, cz, face, time = HYP_Scene.CastRay(px, py, pz, dx, dy, dz);
- px, py, pz - [REAL] - ray origin in world coords.
- dx, dy, dz - [REAL] - ray direction in world coords.
- id - [INTEGER] - mesh identifier or -1 if no collision.
- cx, cy, cz - [REAL] - collision point in world coords.
- face - [INTEGER] - mesh collision face.
- time - [INTEGER] - collision time. time=0 is localized at the ray origin.
NvSliGetNumGpus
NvSliGetNumGpus allows to get the number of SLI GPUs.
Syntax
num_sli_gpus = HYP_Scene.NvSliGetNumGpus();
- num_sli_gpus - [INTEGER] - number of SLI GPUs.
NvSliSetState
NvSliSetState allows to enable or disable the SLI mode of nVidia graphics controllers.
Syntaxe
HYP_Scene.NvSliSetState( state );
- state - [INTEGER] - enable (1) or disable (0) SLI.
NvSliGetState
NvSliGetState allows to get the SLI state.
Syntaxe
state = HYP_Scene.NvSliGetState();
- state - [INTEGER] - SLI enabled (1) or disabled (0).
NvSliSetMode
NvSliSetMode allows to set the frame rendering mode when the SLI is enabled.
Syntaxe
HYP_Scene.NvSliSetMode( mode );
- mode - [INTEGER] - frame rendering mode. The following values are valid:
- 0 (AUTO_SELECT)
- 1 (AFR)
- 2 (SFR)
- 4 (COMPATIBILITY)
NvSliGetMode
NvSliGetMode allows to get the current frame rendering mode when SLI is enabled.
Syntaxe
mode = HYP_Scene.NvSliGetMode();
- mode - [INTEGER] - frame rendering mode. The following values are valid:
- 0 (AUTO_SELECT)
- 1 (AFR)
- 2 (SFR)
- 4 (COMPATIBILITY)
FboGetDefault
FboGetDefault allows to retrieve the numeric identifier of the default Hyperion FBO.
Syntaxe
fbo = HYP_Scene.FboGetDefault();
- fbo - [INTEGER] - numeric identifier of the default FBO. If fbo equals to 0, then the craphics controller does not support FBO (Frame Buffer Object).
FboBind
FboBind allows to bind (or activate) the specified FBO. This new FBO will replace normal frame buffer for all writing and reading operations
in buffers (color, depth and stencil).
Syntaxe
HYP_Scene.FboBind( fbo );
- fbo - [INTEGER] - numeric identifier of the FBO to be bind. if fbo is equal to 0, the windowed normal frame buffer is re-enabled.
FboSetRenderDestination
FboSetRenderDestination allows to specify which color buffer of the currently bound fbo will be used for all writing operations.
Syntaxe
HYP_Scene.FboSetRenderDestination( buffer );
- buffer - [INTEGER] - color buffer numeric identifier:
- FBO_COLOR_ATTACHMENT0 = 0 - default value
- FBO_COLOR_ATTACHMENT1 = 1
- FBO_COLOR_ATTACHMENT2 = 2
- FBO_COLOR_ATTACHMENT3 = 3
Example
fbo = HYP_Scene.FboGetDefault();
HYP_Scene.FboBind( fbo );
FBO_COLOR_ATTACHMENT1 = 1;
HYP_Scene.FboSetRenderDestination( FBO_COLOR_ATTACHMENT1 );
HYP_Scene.FboBind( 0 );
FboAttachTexture
FboAttachTexture allows to attach a texture to the currently bound FBO.
Syntaxe
HYP_Scene.FboAttachTexture( texture_name | tid, attach_point );
- texture_name - [STR127] - texture name.
- tid - [INTEGER] - texture numeric identifier.
- attach_point - [INTEGER] - attachment point into the FBO:
- FBO_COLOR_ATTACHMENT0 = 0
- FBO_COLOR_ATTACHMENT1 = 1
- FBO_COLOR_ATTACHMENT2 = 2
- FBO_COLOR_ATTACHMENT3 = 3
Example
fbo = HYP_Scene.FboGetDefault();
HYP_Scene.FboBind( fbo );
FBO_COLOR_ATTACHMENT0 = 0;
HYP_Scene.FboAttachTexture( "my_rtt_tex", FBO_COLOR_ATTACHMENT0 );
HYP_Scene.FboBind( 0 );
FboAllocReadBufferRgba32f
FboAllocReadBufferRgba32f allocates the memory and initializes it with data from one of the currently bound FBO color buffers.
Syntaxe
HYP_Scene.FboAllocReadBufferRgba32f( buffer_source, w, h );
- buffer_source - [INTEGER] - numeric identifier of the buffer:
- FBO_COLOR_ATTACHMENT0 = 0
- FBO_COLOR_ATTACHMENT1 = 1
- FBO_COLOR_ATTACHMENT2 = 2
- FBO_COLOR_ATTACHMENT3 = 3
- w - [INTEGER] - buffer width. Correspond to width of texture that is attached to.
- h - [INTEGER] - buffer height. Correspond to height of texture that is attached to.
FboFreeReadBufferRgba32f
FboFreeReadBufferRgba32f frees the memory previously allocated by FboAllocReadBufferRgba32f().
Syntaxe
HYP_Scene.FboFreeReadBufferRgba32f();
FboGetValueReadBufferRgba32f
FboGetValueReadBufferRgba32f reads the data from the buffer allocated and initilized by FboAllocReadBufferRgba32f().
Syntaxe
r, g, b, a = HYP_Scene.FboGetValueReadBufferRgba32f( offset );
- offset - [INTEGER] - offset dans le buffer de la donnée à lire. L'offset est compris entre 0 et texture_width*texture_height.
- r - [REAL] - data value stored in the red channel in format IEEE 754 (32 bits on nVidia and 24 bits on ATI).
- g - [REAL] - data value stored in the green channel in format IEEE 754 (32 bits on nVidia and 24 bits on ATI).
- b - [REAL] - data value stored in the bleue channel in format IEEE 754 (32 bits on nVidia and 24 bits on ATI).
- a - [REAL] - data value stored in the alpha channel in format IEEE 754 (32 bits on nVidia and 24 bits on ATI).
Example
-- Active Hyperion default frame buffer.
--
fbo = HYP_Scene.FboGetDefault();
HYP_Scene.FboBind( fbo );
--
-- Do here some code to update color buffer 0.
--
-- Alloc memory for reading.
--
FBO_COLOR_ATTACHMENT0 = 0;
w = 256;
h = 256;
HYP_Scene.FboAllocReadBufferRgba32f( FBO_COLOR_ATTACHMENT0, w, h );
-- Read color buffer 0.
--
offset = 0;
size = tex_width * tex_height;
while( offset < size ) do
r, g, b, a = HYP_Scene.FboGetValueReadBufferRgba32f( offset );
--
-- Do here something with r, g, b and a.
--
offset = offset + 1;
end
-- Free memory
--
HYP_Scene.FboFreeReadBufferRgba32f();
-- Restore window frame buffer.
--
HYP_Scene.FboBind( 0 );
PickMesh
PickMesh allows to make mesh picking, i.e. to get the identifier of the first mesh being under
the cursor of the mouse. In the case of the HYP_PickMesh() function, the mesh identifier is simply the
name of the mesh.
Syntax
mesh_name = HYP_Scene.PickMesh();
- mesh_name - [STR127] - name of the selected mesh.
If no mesh is selected, HYP_PickMesh returns the empty string "".
AddObject
AddObject allows to add to the scene tree an object created with a lua scripting code (with HYP_Object.Clone()
or another function).
Syntax
HYP_Scene.AddObject( object_name|object_id );
- object_name - [STR127] - character string representing the name of the object as specified in the XML script by the "name" attribute.
- object_id - [INTEGER] - identifier of the object returned by functions such as HYP_CloneModel().
Remark
The HYP_Object.Clone() function automatically adds the clone into the scene.
RemoveObject
RemoveObject allows possible to remove an object from the scene tree.
This object can then be added as a child to another object with the HYP_Object.AddChild() function.
Syntax
HYP_Scene.RemoveObject( object_name|object_id );
- object_name - [STR127] - character string representing the name of the object as specified in the XML script by the "name" attribute.
- object_id - [INTEGER] - identifier of the object returned by functions such as HYP_CloneModel().
EnableGroup
EnableGroup allows to activate all the objects that belong to a same group.
Syntax
HYP_Scene.EnableGroup( group_name );
- group_name - [STR127] - character string representing the name of the group as specified in the XML
script by the group attribute within the different nodes (audio, mesh, primitive, etc...).
Example
HYP_Scene.EnableGroup( "objects_room1" );
DisableGroup
DisableGroup allows to disable all the objects belonging to a group.
Syntax
HYP_Scene.DisableGroup( group_name );
- group_name - [STR127] - character string representing the name of the group as specified
in the XML script by the group attribute in he different nodes (audio, mesh, primitive, etc...).
Render
Render allows to perform a scene rendering in a specified target by using the
HYP_Scene.SetRenderTarget() function.
Syntax
HYP_Scene.Render();
Example
-- Render to texture example:
--
RENDER_TARGET_COLOR_BUFFER = 1;
RENDER_TARGET_TEXTURE = 2;
HYP_Scene.SetRenderTarget( RENDER_TARGET_TEXTURE );
HYP_Scene.SetRenderTargetTexture( "myRTT_Tex" );
HYP_Scene.Render();
-- Restore default render target.
--
HYP_Scene.SetRenderTarget( RENDER_TARGET_COLOR_BUFFER );
SetRenderTarget
SetRenderTarget allows to change the background color of the 3d scene.
Syntax
HYP_Scene.SetRenderTarget( target );
- target - [INTEGER] - destination of the scene rendering output:
- target=1 : rendering in the color-buffer (default value)
- target=2 : rendering in a 2d texture. In this case, the 2d texture must be specified by
the SetRenderTargetTexture() function.
SetRenderTargetTexture
SetRenderTargetTexture allows to specify the texture in which the scene will be rendered
when calling the HYP_Scene.SetRenderTarget() function featuring "target=2".
Syntax
HYP_Scene.SetRenderTargetTexture( texture_name );
- texture_name - [STR127] - name of the texture as specified by the attribute name in the XML script.
SetBackgroundColor
SetBackgroundColor allows to change the background color of the 3d scene.
Syntax
HYP_Scene.SetBackgroundColor( r, g, b );
- r - [CLAMPED_REAL] - red component of the color. Float value ranging between 0.0 and 1.0.
- g - [CLAMPED_REAL] - green component of the color. Float value ranging between 0.0 and 1.0.
- b - [CLAMPED_REAL] - blue component of the color. Float value ranging between 0.0 and 1.0.
Example
HYP_Scene.SetBackgroundColor( 0.2, 0.2, 0.3 );
ActiveBkgImage
ActiveBkgImage allows to activate a basic image among those which were loaded in the scene node using the scene_background_image instruction.
Syntax
HYP_Scene.ActiveBkgImage( index );
- index - [INTEGER] - index of the basic image to activate. The first image has the index 0 and the last the index N-1 (Nmax=100).
Example
-- Activation de la 3eme image.
HYP_Scene.ActiveBkgImage( 2 );
EnableFog
EnableFog allows to activate the fog. The fog parameters must beforehand be initialized in the scene node
(see the
fog element).
Syntax
HYP_Scene.EnableFog();
DisableFog
DisableFog allows to disable the fog.
Syntax
HYP_Scene.DisableFog();
GetRayOriginAndDirection
GetRayOriginAndDirection returns the ray cast into the scene from a position on the screen.
The screen space is as follows:
+Y
|
|
|
|
+------------ +X
0,0
Syntaxe
ray_orig_x, ray_orig_y, ray_orig_z,
ray_dir_x, ray_dir_y, ray_dir_z =
HYP_Scene.GetRayOriginAndDirection( screen_x, screen_y );
- screen_x, screen_y - [INTEGER] - position in screen coordinates.
- ray_orig_x, ray_orig_y, ray_orig_z - [REAL] - origin of the ray in the scene.
- ray_dir_x, ray_dir_y, ray_dir_z - [REAL] - direction of the ray in the scene.
LoadXml
LoadXml allows to load a new xml scene file. Useful to split a demo in several parts or to chain several demos.
Syntaxe
HYP_Scene.LoadXml( filename );
- filename - [STR255] - name of the xml file relative to the current xml script.
GetWindowSize
GetWindowSize allows to retrieve the size of the 3D window.
Syntax
w, h = HYP_Scene.GetWindowSize();
- w - [INTEGER] - window width.
- h - [INTEGER] - window height.
