Event Handling Callbacks
Callback is a function wrapper representing a pointer to static and member functions which are expected to be executed with specified parameters at a certain moment. Callback can be passed as an argument to other function.
In UnigineScript callbacks are represented by function identifiers obtained using the functionid() function:
void callback_function(Node node) {
/* .. */
}
..
int callback = functionid(callback_function);Usage Example#
The following section contains the complete source code of a simple callback usage example.
world_script.usc
#include <core/unigine.h>
// This file is in UnigineScript language.
// World script, it takes effect only when the world is loaded.
int init() {
Player player = new PlayerSpectator();
player.setPosition(Vec3(0.0f,3.401f,1.5f));
player.setDirection(Vec3(0.0f,-1.0f,-0.4f));
engine.game.setPlayer(player);
int callback_id = functionid(callback_function);
call(callback_id);
return 1;
}
void callback_function() {
log.message("Callback has been fired\n");
}
// start of the main loop
int update() {
return 1;
}
int postUpdate() {
return 1;
}
int updatePhysics() {
return 1;
}
// end of the main loop
int shutdown() {
return 1;
}Practical Use#
Callbacks are widely used in event handling. A number of Unigine API members have several predefined events which can be handled by using callbacks in certain cases.
Triggers#
Triggers are used to detect changes in nodes position or state. Unigine offers three types of built-in triggers:
- NodeTrigger fires callbacks when the trigger node is enabled or the trigger node position has changed.
- WorldTrigger fires callbacks when any node (collider or not) gets inside or outside of it.
- PhysicalTrigger fires callbacks when physical objects get inside or outside of it.
Here is a simple WorldTrigger usage example:
// implement the enter callback
void enter_callback(Node node) {
if(node.getType() == NODE_OBJECT_MESH_STATIC) {
ObjectMeshStatic mesh = node_cast(node);
mesh.setMaterialState("emission",1,0);
}
}
WorldTrigger trigger;
int init() {
// create a world trigger
trigger = new WorldTrigger(vec3(3.0f));
// set the enter callback to be fired when a node enters the world trigger
trigger.setEnterCallback(functionid(enter_callback));
return 1;
}Widgets#
The widgets base class Widget allows registering callbacks for events defined in the GUI class. The following example shows how to create a WidgetButton and register a callback function for the CLICKED event:
// button clicked callback
void onButtonClicked() {
/* .. */
}
/* .. */
// getting the system GUI
Gui gui = engine.getGui();
// creating a button widget and setting its caption
widget_button = new WidgetButton(gui,"Press me");
// rearranging button size
widget_button.arrange();
// setting button position
widget_button.setPosition(10,10);
// setting onButtonClicked function to handle CLICKED event by using an intermediate redirecting function
widget_button.setCallback(GUI_CLICKED,functionid(onButtonClicked));
// adding the created button widget to the system GUI
gui.addChild(widget_button,GUI_ALIGN_OVERLAP);See Also
A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/widgets/ folder.
Physics#
You can track certain events of the physics-related Bodies and Joints:
- Body.setFrozenCallback() to track an event when a body freezes.
- Body.setPositionCallback() to track an event when a body changes its position.
- Body.setContactCallback() to track an event when a body collides with another body or collidable surface.
- Joint.setBrokenCallback() to track an event when a joint breaks.
The following sample shows the way of registering callbacks for a BodyRigid and change the color of a mesh depending on its state:
// set the node's albedo color to red on freezing event
void frozen_callback(Body body) {
Object object = body.getObject();
object.setMaterialParameterFloat4("albedo_color", vec4(1.0f, 0.0f, 0.0f, 1.0f), 0)
}
// set the node's albedo color to blue on position change event
void position_callback(Body body) {
Object object = body.getObject();
object.setMaterialParameterFloat4("albedo_color", vec4(0.0f, 0.0f, 1.0f, 1.0f), 0)
}
// set the node's albedo color to yellow on each contact
void contact_callback(Body body, int num) {
Object object = body.getObject();
object.setMaterialParameterFloat4("albedo_color", vec4(1.0f, 1.0f, 0.0f, 1.0f), 0)
}
// create a box static mesh
Mesh mesh = new Mesh();
mesh.addBoxSurface("box_0", vec3(1.0f));
ObjectMeshStatic node = new ObjectMeshStatic(mesh);
node.setMaterial("mesh_base", "*");
node.setPosition(Vec3(0, 0, 5.0f));
// add a rigid body
BodyRigid body = new BodyRigid(node);
// register callbacks for events
body.setFrozenCallback(functionid(frozen_callback));
body.setPositionCallback(functionid(position_callback));
body.setContactCallback(functionid(contact_callback));
// add a shape to the body
ShapeBox shape = new ShapeBox(body, vec3(1.0f));See Also
A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/physics/ folder:
- callbacks_00
- callbacks_01
- callbacks_02
See Also#
These are not all usage examples of event handling callbacks. The following list contains more API members supporting event handling:
- UserInterface - for handling events from widgets created by loading a UI file.
- Render - callback functions can be used to get access to buffers and matrices at intermediate stages of the rendering sequence.
- Console supports adding a callback function that will be executed when a text is output to the console.
- EditorLogic - a set of editor callback functions can be overridden for certain purposes.
- ComponentBase - there may be performed certain actions on destroying a component.
- AsyncQueue - сallback functions can be used to determine actions to be performed when certain resources are loaded.
- WorldSplineGraph provides a set of callbacks for handling actions on editing points and segments.
- Viewport - callback functions can be used to get access to buffers and matrices at intermediate stages of the rendering sequence.
Plugins: