This module contains common structure that you will use on a regular basis while building an NRG application. On this page you find information about the events and inputs as well as other commonly used global constants and enumerations. In this page you will also get more information about event system, learn how to create them and to retrieve the data available when they happen.
See Also
Scene,
RenderLayer,
Camera,
Object,
Region,
Sensor,
Geometry,
SoundSource ParticleSystem,
ParticleEmitter,
Particles,
Material,
Video,
Action,
Channel ActionController,
ActionClip,
Sequence,
Strip,
WorldContact,
Sfx
KeyCode
Special keyboard keycode definitions.
fShift: Shift key (left or right).fCtrl: The control key.fAlt: Either left or right Alt key.fCommand: Command key on Mac OSX for PC usually the "Windows" key.fCapsLock: Caps lock.fArrowUp: The up arrow.fArrowDown: The down arrow.fArrowLeft: The left arrow.fArrowRight: The right arrow.fPageUp: The page up key.fPageDown: The page down key.fHome: The home key.fEnd: The end key.fEject: The eject key (typically found on Mac keyboards)
Example
Lua
-- You can access a specific Key flag value like this:
print( "The value of fArrowUp is " .. Application.KeyCode.fArrowUp )
State
Constant values representing the available playback state.
kStop: The current playback state is set to stop.kPlay: The resource is playing and updating.kPause: The resource is on standby waiting to be resumed (kPlay) or stopped (kStop)kStep: Step once then the resource state is set to kPause.kRecord: Special state only used by the editor when recording Curve or Track.kIdle: The initial state of a LvmThread which put it throttling reducing overhead until it gets started.
Example
Lua
-- To access a State constant you can type something like this:
print( "The value of kPlay is " .. Application.State.kPlay )
Orientation
The current screen orientation (only apply when the host is a mobile platform).
kPortrait: Default position of the device.kFlipped: Portrait flipped a 180 degree.kLandscapeRight: Portrait rotated at 90 degree.kLandscapeLeft: Portrait rotated at -90 degree
Example
Lua
-- Print the different orientations in degree.
print( "Portrait:" .. Application.Orientation.kPortrait )
print( "Flipped:" .. Application.Orientation.kFlipped )
print( "LandscapeRight:" .. Application.Orientation.kLandscapeRight )
print( "LandscapeLeft:" .. Application.Orientation.kLandscapeLeft )
Touche
This structure allows you to gain realtime information about the current touches (mobile) or mouse (desktop) currently interacting with the screen.
Static Variables
| Name | Description |
start | The normalized coordinate of the touche or pointer starting point. ** |
Declaration Example
-- In a script attached to the Application handler.
function OnTouchesBegan()
-- Get the current viewport size.
local viewport = Gfx:GetViewport()
-- Print the absolute and normalized starting point of the touche. Since
-- the event is a "pointer" specific event we can use the keyword "this"
-- which will represent the current touche.
print( "X:" .. this.start.x * viewport.width .. " " ..
"Y:" .. this.start.y * viewport.height .. " " ..
"nX:" .. this.start.x .. " " ..
"nY:" .. this.start.y )
end
void OnTouchesBegan( void ) {
// Get the current viewport size.
const quad viewport = GfxGetViewport();
// Print the absolute and normalized starting point of the first touche.
printf( "X: %f Y: %f nX: %f nY: %f\n", App->event.touche_array[ 0 ].start.x * viewport.width,
App->event.touche_array[ 0 ].start.y * viewport.height,
App->event.touche_array[ 0 ].start.x,
App->event.touche_array[ 0 ].start.y );
}
// Somewhere in your plugin add the event and connect the callback function.
HandlerAddEvent( &App->handler, kOnTouchesBegan, OnTouchesBegan );
|
location | The current location of the pointer in normalized screen coordinate. ** |
Declaration Example
-- In a script attached to the Application handler.
function OnTouchesMoved()
-- Get the current viewport size.
local viewport = Gfx:GetViewport()
-- Print all the touches and their locations.
for i=0,( event.touche_count - 1 ) do
local t = App:GetTouche( i )
print( "Touche#" .. i .. ": " .. t.location.x * viewport.width .. ", " ..
t.location.y * viewport.height )
end
end
void OnTouchesMoved( void ) {
// Get the current viewport size.
const quad viewport = GfxGetViewport();
// Print all the touches and their locations.
for( int i = 0; i < App->event.touche_count; ++i ) {
printf( "Touche#%d: %f, %f\n", i,
App->event.touche_array[ i ].location.x * viewport.width,
App->event.touche_array[ i ].location.y * viewport.height );
}
}
// Somewhere in your plugin add the event and connect the callback function.
HandlerAddEvent( &App->handler, kOnTouchesMoved, OnTouchesMoved );
|
delta | Represent the difference between the current location and the previous. ** |
Declaration Example
-- In a script attached to the Application handler.
function OnTouchesMoved()
-- Get the current viewport size.
local viewport = Gfx:GetViewport()
-- Print how fast the current touche have moved since its last recorded location
-- in pixel relative to the current viewport size.
print( "Touche Delta:" .. this.delta.x * viewport.width .. ", " ..
this.delta.y * viewport.height )
end
void OnTouchesMoved( void ) {
// Get the current viewport size.
const quad viewport = GfxGetViewport();
// Print how fast the first touche have moved since its last recorded location
// in pixel relative to the current viewport size.
printf( "Touche Delta: %f, %f\n", App->event.touche_array[ 0 ].delta.x * viewport.width,
App->event.touche_array[ 0 ].delta.y * viewport.height );
}
// Somewhere in your plugin add the event and connect the callback function.
HandlerAddEvent( &App->handler, kOnTouchesMoved, OnTouchesMoved );
|
app_time | The application time when the touche began. ** |
Declaration Example
-- In a script attached to the Application handler.
function OnTouchesMoved()
-- Get the current viewport size.
local viewport = Gfx:GetViewport()
-- List for how long each touche(s) have been pressed.
for i=0,( event.touche_count - 1 ) do
print( "Touche#" .. i .. " Time: " .. App.stats.app_time -
App:GetTouche( i ).app_time )
end
end
void OnTouchesMoved( void ) {
// Print for how long the first touche have been pressed.
printf( "Touche Time: %f\n", App->stats.app_time -
App->event.touche_array[ 0 ].app_time );
}
// Somewhere in your plugin add the event and connect the callback function.
HandlerAddEvent( &App->handler, kOnTouchesMoved, OnTouchesMoved );
|
modifier | Only apply for desktop; this allows you to determine which mouse button have been pressed. ** |
Declaration Example
-- In a script attached to the Application handler.
function OnTouchesBegan()
-- Print which mouse button have been pressed.
print( "Mouse Button:" .. this.modifier )
end
void OnTouchesBegan( void ) {
// Print the first mouse button modifier.
printf( "Mouse Button:%d\n", App->event.touche_array[ 0 ].modifier );
}
// Somewhere in your plugin add the event and connect the callback function.
HandlerAddEvent( &App->handler, kOnTouchesMoved, OnTouchesMoved );
|
- Note
- All mouse/touches coordinates are normalized for a question of compatibility among remote desktops and mobile devices (see Client). To restore the original position of the touche on screen multiply the X and Y coordinate with the current event viewport width and height.
Gamepad
Gives you access to manage the information comming from the gamepad(s) connected to your device. By default the system support up to 4 gamepad connected simultaneously; and each gamepad can have up to 32 buttons and up to 6 axis.
Static Variables
| Name | Description |
name | The identifier of the gamepad. ** |
Declaration Example
-- In a script attached to the Application handler.
function OnGamepad()
if( this.name ~= nil ) then
print( "Gamepad#" .. event.gamepad_index .. " plugged: " .. this.name )
else
print( "Gamepad#" .. event.gamepad_index .. " unplugged." )
end
end
void OnGamepad( void ) {
// Detect if a gamepad is plugged or unplugged.
if( App->event.gamepad[ App->event.gamepad_index ].name[ 0 ] ) {
printf( "Gamepad#%d plugged: %s\n", App->event.gamepad_index,
App->event.gamepad[ App->event.gamepad_index ].name );
}
else {
printf( "Gamepad#%d unplugged.", App->event.gamepad_index );
}
}
// Somewhere in your plugin add the event and connect the callback function.
HandlerAddEvent( &App->handler, kOnGamepad, OnGamepad );
|
button_mask | A mask where each bit represent which button have been pressed or release (up to 32 buttons). ** |
Declaration Example
-- In a script attached to the Application handler.
function OnGamepadButtons()
-- Exit the function if no button is pressed.
if( this.button_mask == 0 ) then
return
end
-- Since this is a gamepad specific event we can use the keyword
-- "this" which represent the current gamepad that receive the
-- event. In this example you'll print the current button mask and
-- learn how to evaluate if a certain button is pressed.
print( "Gamepad: " .. this.name )
print( "Button Mask: " .. this.button_mask )
-- Check which button is/are pressed using the bit module.
for i=0,31 do
if( bit.band(this.button_mask,bit.lshift(1,i)) ~= 0 ) then
print( "Button #" .. i .. " is pressed!" )
end
end
end
void OnGamepadButtons( void ) {
// Exit the function if no button is pressed.
if( !App->event.gamepad[ App->event.gamepad_index ].button_mask )
{ return; }
// Use the gamepad_index to access the gamepad that trigger the
// event; in this example you'll print the current button mask and
// learn how to evaluate if a certain button is pressed.
printf( "Gamepad: %s\n" , App->event.gamepad[ App->event.gamepad_index ].name );
printf( "Button Mask: %d\n", App->event.gamepad[ App->event.gamepad_index ].button_mask );
// Check which button is/are pressed using bitwise operation.
for( int i = 0; i < 32; ++i ) {
if( App->event.gamepad[ App->event.gamepad_index ].button_mask & ( 1 << i ) ) {
printf( "Button #%d is pressed!\n", i );
}
}
}
// Somewhere in your plugin add the event and connect the callback function.
HandlerAddEvent( &App->handler, kOnGamepadButtons, OnGamepadButtons );
|
axis | Retrieve the value of the gamepad axis (up to 4). ** |
Declaration Example
-- In a script attached to the Application handler.
function OnGamepadAxis()
-- List the value of each gamepad axis.
print("Gamepad: " .. this.name )
print("Axis0: " .. this.axis0) -- Usually the left analog stick left/right direction
print("Axis1: " .. this.axis1) -- Usually the left analog stick up/down direction
print("Axis2: " .. this.axis2) -- Usually the right analog stick left/right direction
print("Axis3: " .. this.axis3) -- Usually the right analog stick up/down direction
print("")
end
void OnGamepadAxis( void ) {
// List the value of each gamepad axis for the current gamepad.
printf("Gamepad: %s\n", App->event.gamepad[ App->event.gamepad_index ].name );
printf("Axis0: %f\n", App->event.gamepad[ App->event.gamepad_index ].axis0 );
printf("Axis1: %f\n", App->event.gamepad[ App->event.gamepad_index ].axis1 );
printf("Axis2: %f\n", App->event.gamepad[ App->event.gamepad_index ].axis2 );
printf("Axis3: %f\n", App->event.gamepad[ App->event.gamepad_index ].axis3 );
}
// Somewhere in your plugin add the event and connect the callback function.
HandlerAddEvent( &App->handler, kOnGamepadAxis, OnGamepadAxis );
|
Functions
| Name | Description |
IsButtonPressed | Helper function to determine if a specific button on the gamepad is pressed. * |
Declaration bool IsButtonPressed( unsigned char index ) Parameters
index: The button index to test (clamped to 0~31; 32 buttons).
Return Value
true if the button on the gamepad specified by index is pressed else return false.
Example
Lua -- On a script attached to the Application handler.
local button_masks = { 0, 0, 0, 0 } -- Max. 4 gamepads.
function OnGamepadButtons()
-- Show another technique to check if a specific button on
-- the gamepad is pressed or released.
local idx = event.gamepad_index
local joy = App:GetGamepad( idx )
print( "Gamepad: " .. joy.name )
print( "Button Mask: " .. joy.button_mask )
-- In Lua index start a 1
print( "Previous Mask: " .. button_masks[ idx + 1 ] )
-- Check which button pressed and which one have been released.
for i=0,31 do -- Max. 32 buttons.
if( joy:IsButtonPressed( i ) == true ) then
print( "Button #" .. ( i + 1 ) .. " is pressed!" )
elseif( bit.band(button_masks[ idx + 1 ],bit.lshift(1,i)) ~= 0 ) then
print( "Button #" .. ( i + 1 ) .. " released!" )
end
end
button_masks[ idx + 1 ] = joy.button_mask
print("")
end
|
AppEvent
Structure that allows you to retrieve the current states and variables of an Application EventType. You can then use theses variables at runtime to build the logic and dynamic aspects of your application.
Static Variables
| Name | Description |
type | The EventType type. |
Declaration
|
material_pass | The current material pass number (see Material). |
Declaration unsigned char material_pass |
framebuffer_pass | The current framebuffer pass number (see FrameBuffer). |
Declaration unsigned char framebuffer_pass |
scene | The current Scene available within the boundary of the event. |
Declaration - Attention
- Not all events have a
scene when they are triggered; in example application EventType such as kOnGamepad or kOnKeyboard occur at the beginning of the frame when no scene is currently available.
|
renderlayer | The current RenderLayer in use when the event occur. |
Declaration
|
camera | The active Camera in use when the event occur. |
Declaration
|
object | The active Object in use when the event occur. |
Declaration
|
video | Video structure responsible for the current event trigger. |
Declaration
|
action | The Action structure that trigger the event. |
Declaration
|
actioncontroller | The ActionController involved in the function callback. |
Declaration ActionController *actioncontroller |
sequence | Current Sequence associated with the active callback. |
Declaration
|
material | The current Material in use by the callback. |
Declaration
|
actor | The Actor involved in the Region event. |
Declaration
|
sensor | The active Sensor that trigger a kOnProximity event. |
Declaration
|
particleemitter | The active ParticleEmitter responsible of trigerring the callback. |
Declaration ParticleEmitter *particleemitter </tr
|
channel | Active Channel in used by the current event. |
Declaration
|
actionclip | The ActionClip that trigger the current event. |
Declaration
|
strip | The specific Strip part of the current Sequence callback. |
Declaration
|
lod_index | Represent the current lod index of the geometry that is currently drawing. |
Declaration
|
face | The current FaceType of the Probe beeing processed. |
Declaration
|
actuator_index | Current Channel actuator index used by the callback. |
Declaration
|
particles | The current Particles data attached to the event triggered by the ParticleEmitter. |
Declaration
|
contact | Structure containing detailed information about the current physics collision. |
Declaration
|
touche_count | Amount of touches on screen or active mouse button pressed. |
Declaration
|
accelerometer | Acceleration vector of the device (updated directly from mobile device accelerometer). |
Declaration
|
gyroscope | The action rotational movement of the device (updated directly from the gyroscope of the mobile device). |
Declaration
|
gamepad_index | Index of the gamepad the trigger an event. |
Declaration unsigned char gamepad_index |
key_pressed | Determine if a key is pressed or not during a keyboard key event. |
Declaration
|
Variables
| Name | Description |
key_code | The keycode of the keyboard key that trigger the current event. |
Declaration
|
tap_count | Number of times a touche or a mouse button have been clicked. |
Declaration
|
Key
Static Variables
| Name | Description |
pressed | Current state of the key; either true or false. |
Declaration
|
app_time | The last application time a press for change occur. |
| Declaration |
AppStats
This structure gives you access to the internal statistics that are gather over frames while rendering. The information contained in this structure vary from the frame rate, to the different sync. and rendering time that are updated during rendering and updates. All time values are represented as follow: 1.0 = 1 sec.
Static Variables
| Name | Description |
fps | The amount of frames per seconds rendered on screen. |
Declaration
|
frame | Total amount of frames drawed on screen.. |
Declaration
|
frame_time | The average frame rendering time (since the last fps update). |
| Declaration |
Variables
| Name | Description |
delta_time | Represent the amount of time it took to draw the previous frame. |
Declaration
|
app_time | The application time since the App:Start() function was called. |
Declaration
|
time_scale | Control the scale of the application delta time. |
Declaration
|
last_sync | The absolute time in milliseconds when the last frame was synced. |
Declaration
|
Listener
This structure contains the data related to the current listener (the one who hear the sounds). The listener is used in conjunction with the Sfx subsystem to determine where in space the sounds are heard from. The listener is usually set to be the player or the camera obeject following the action but it can be set to any Object location.
Static Variables
| Name | Description |
gain | Value use to represent the internal volume of the listener. |
Declaration Range 0.0 to 10.0 \note This value have nothing to do with the device internal or external
speaker/headphone volume; this volume of the device have to be set independently.
In addition the default value is 1.0 which represent full unbiased volume.
</td>
|
object | The current Object assigned to be the listener. |
Declaration
|
velocity | The velocity of the object set as listener. |
Declaration - Note
- If
auto_velocity is set to false this value have to be updated manually by the user; else the internal system will use the current listener Object velocity.
|
auto_velocity | Control wether or not the velocity of the listener Object should be calculated automatically. |
Declaration
|
mute | Quick and convenient variable to mute the listener volume. |
Declaration
|
