Intersections

Unigine has different methods to detect intersections. Intersection is a generic point of the defined area (or line) and an object. This article describes different types of intersections and their usage.

So, there are three main types of intersections:

World intersection - an intersection with objects and nodes. The search of intersections performs by using engine.world functions.
Physics intersection - an intersection with shapes and collision objects. The search of intersections performs by using engine.physics functions.
Game intersection - an intersection with obstacles. The search of intersections performs by using engine.game functions.

Shape and Object classes have their own getIntersection() functions. They are used for detecting intersections with the specific shape or the specific surface of the object.

All of the intersection functions, except for the Object.getIntersection() function, use world coordinates.

By using different engine.world functions you can find world intersections. You can find objects and nodes that intersect bounds of the specified bounding volume or find the first intersection of the object with the invisible tracing line. There are 3 groups of world intersection functions:

Functions to find nodes within a bounding volume.
Functions to find objects within a bounding volume or intersected with a traced line.
Functions to find first intersected object with a traced line.

Intersection with Nodes

To find the intersection of nodes with bounds of the specified volume, you should use these 2 functions:

engine.world.getIntersectionNodeVariables() to find all the nodes (or nodes of specified type) that intersect bounds of the specified volume: BoundBox, BoundFrustum, BoundSphere. This function finds nodes which have set user variables.
engine.world.getIntersectionNodes() functions to find all the nodes (or nodes of specified type) in within a given bounding volume: BoundBox, BoundFrustum, BoundSphere.

The picture above shows how the engine.world.getIntersection() function detects the nodes that intersect with the bounds of the BoundBox volume.

These functions return the amount of found nodes as an integer value and save the data in the ret[] array which you can pass to the function as an argument.

Usage Example

The following example shows how you can get the intersection nodes by using the engine.world.getIntersectionNodes() function. It is supposed that you already have a world containing nodes and you have the BoundBox instance with the specified size. This code is taken from the world script's update() method. In this example the function checks if there is a node of any type inside the specified BoundBox object. The executing sequence is the following:

Define an array for output values and a BoundBox instance.
Check, if there is an intersection with a node. The engine.world.getIntersectionNodes() function returns an integer value: the amount of found nodes.
In this example, when the node intersects with the BoundBox, console shows the information about that node. If there is no intersected node, console shows another message.

Source code(UnigineScript)

/* ... */
// It is supposed that you have these variables in your code:
// a BoundBox instance
BoundBox boundBox;
// Array for the result
int resultArray[0];


/* ... */
/* this part is from update() method */
// check if there is any node inside the BoundBox 
int result = engine.world.getIntersectionNodes(boundBox, -1, resultArray);

// if there is an intersection, do the following in a loop:
if(result != 0)
{	
	// get the size of the array and perform a for loop 
	forloop(int i=0; resultArray.size())
	{
		// get the Node from the array and show its name and type in console
		Node node = resultArray[i];
		log.message("node %i is : %s %i\n", i, node.getName(), node.getType() );
	}
}
else
{
	log.message("sorry, but your intersection is in another castle!\n");
}
/* ... */

Intersection with Objects

engine.world class functions have 2 overloaded functions to get objects with and without user data. Intersection is performed with surfaces (polygons):

The picture above shows how the engine.world.getIntersection() function detects the objects that intersect with the bounds of the BoundBox volume.

All these functions return the amount of found objects as an integer value and save the data in the ret[] array which you can pass to the function as an argument. You can pass the start (vec3 p0) and the end (vec3 p1) point of the intersecting line or pass the variable v (BoundBox, BoundFrustum, BoundSphere) to get the intersection of objects with a line or with a bounding volume, respectively.

Usage Example

The following example shows how you can get the intersected objects by using the engine.world.getIntersectionObjects() function. It is supposed that you already have a world containing objects. This code is taken from the world script's update() method. In this example we specify a line from the point of the camera (vec3 p0) to the point of the mouse pointer (vec3 p1). The executing sequence is the following:

Define an array for output values. Also define and initialize two points (p0 and p1) by using the Unigine::getPlayerMouseDirection() function from core/scripts/utils.h.
Check, if there is an intersection with an object. The engine.world.getIntersectionObjects() function returns an integer value: the amount of found nodes.
In this example, when the object intersects with the traced line, console shows the information about that object.

Source code(UnigineScript)

#include <core/scripts/utils.h>
/* ... */
// it is supposed that you have this variable in your code:
// array for the result
int resultArray[0];

/* ... */

// define two vec3 coordinates
vec3 p0,p1;
// get the mouse direction from camera (p0) to the cursor pointer (p1)
Unigine::getPlayerMouseDirection(p0,p1);

// check if there is any node inside the BoundBox 
int result = engine.world.getIntersectionObjects(p0, p1, resultArray);

// if there is an intersection, do the following in a loop:
if(result != 0)
{	
	// get the size of the array
	// perform a loop from 0 up to the size of the array 
	// to show the information about all objects
	forloop(int i=0; resultArray.size())
	{
		// get the Object from the array and show its material name and type in console
		Object object = resultArray[i];
		log.message("object %i is : %s %i\n", i, object.getMaterialName(0), object.getType() );
	}
}
/* ... */

First Intersected Object

The engine.world.getIntersection() function is used to find the nearest intersected object with the traced line. You should specify the start point and the end point of the line, and the function detects if there are any object on the way of this line.

The picture above shows how the engine.world.getIntersection() function detects the object that intersects with the line.

This function detects intersection with surfaces (polygons) of mesh and terrain objects. But there are some conditions to detect the intersection with the surface:

A per-surface Intersection flag is enabled.
Notice
You can set this flag to the object's surface by using the Object.setIntersection() function.
An Intersection option of the property in the Properties window is enabled.
Notice
You can enable this property by using the Property.setIntersection() function.
A surface is enabled.
A surface has an assigned material.
A surface has an assigned property.

The engine.world.getIntersection() function is overloaded and receives 4 or 5 arguments:

vec3 p0 - the start point coordinates of the trace line.
vec3 p1 - the end point coordinates of the trace line.
int mask - the intersection mask. Use the intersection mask to find object only with specified intersection mask.
int exclude[] - the list of objects IDs to exclude.
variable v - The function returns an intersected object which is the nearest to the start point (p0). Information about the intersection will be presented in variable which you pass to the function as an argument:
- WorldIntersection intersection - The WorldIntersection class instance. By using this class you can get the intersection point (coordinates), the index of the intersected triangle of the object and the index of the intersected surface.
- WorldIntersectionNormal normal - The WorldIntersectionNormal class instance. By using this class you can get only the the normal of the intersection point.
- WorldIntersectionTexCoord texcoord - The WorldIntersectionTexCoord class instance. By using this class you can get only the texture coordinates of the intersection point.
Notice
Passing NULL instead of the intersection query object will perform fast intersection algorithm without the closest intersection point searching.

Thus, to exclude some objects you should use these methods:

Use an intersection mask. An intersection is found only if an object is matching the intersection mask.
Specify the list of objects IDs to exclude and pass to the function as an argument.

Usage Example

The following example shows how you can get the intersection information by using the WorldIntersection class. It is supposed that you already have a world containing objects. This code is taken from the world script's update() method. In this example we specify a line from the point of the camera (vec3 p0) to the point of the mouse pointer (vec3 p1). The executing sequence is the following:

Define and initialize two points (p0 and p1) by using the Unigine::getPlayerMouseDirection() function from core/scripts/utils.h.
Create an instance of the WorldIntersection class to get the intersection information.
Check, if there is an intersection with an object. The engine.world.getIntersection() function returns an intersected object when the object intersects with the traced line.
In this example, when the object intersects with the traced line, all the surfaces of the intersected object change their material parameters. The WorldIntersection class instance gets the coordinates of the intersection point, the index of the surface and the index of the intersected triangle. You can get all these fields by using getIndex(), getPoint() and getSurface() functions

Source code(UnigineScript)

#include <core/scripts/utils.h>
/* ... */
// define two vec3 coordinates
vec3 p0,p1;
// get the mouse direction from camera (p0) to the cursor pointer (p1)
Unigine::getPlayerMouseDirection(p0,p1);

// create an instance of the WorldIntersection class to get the result
WorldIntersection intersection = new WorldIntersection();

// create an instance for intersected object
Object object = engine.world.getIntersection(p0,p1,1,intersection);

// if the intersection has been occurred, change the parameter and the texture of the object's material
if(object != NULL)
{
  forloop(int i=0; object.getNumSurfaces())
  {
    object.setMaterialParameter("diffuse_color", vec4(1.0f, 0.0f, 0.0f, 1.0f),i);
    object.setMaterialTexture("diffuse","", i);
    
    // show intersection details in console
    log.message("point: %s index: %i surface: %i \n", typeinfo(intersection.getPoint()), intersection.getIndex(), intersection.getSurface());
  }

}
/* ... */

Physics intersection function detects the intersection with a shape of bodies. If the object has no body, this function detects intersection with surfaces (polygons) of the object with intersection flag. When you need to find the intersection with the shape of the object (not with polygons), engine.physics intersection function is the best way to get it.

The picture above shows how the engine.physics.getIntersection() function detects the shape that intersects with the line.

There are 2 engine.physics functions to find physics intersections:

These functions performs tracing from the start p0 point to the end p1 point to find a collision object (or a shape) located on that line. Functions use world space coordinates.

The engine.physics.getIntersection() function is overloaded and receives 4 or 5 arguments:

vec3 p0 - the start point coordinates of the trace line.
vec3 p1 - the end point coordinates of the trace line.
int mask - the intersection mask. Use the intersection mask to find object only with specified intersection mask.
int exclude[] - the list of objects IDs to exclude, all these objects will be ignored.
variable v - The function returns an intersected object which is the nearest to the start point (p0). Information about the intersection will be presented in variable which you pass to the function as an argument:
- PhysicsIntersection intersection - The PhysicsIntersection class instance. By using this class you can get the intersection point (coordinates), the index of the intersected surface and the intersection Shape.
- WorldIntersectionNormal normal - The PhysicsIntersectionNormal class instance. By using this class you can get only the the normal of the intersection point.
Notice
Passing NULL instead of the intersection query object will perform fast intersection algorithm without the closest intersection point searching.

Thus, to exclude some obstacles you should use these methods:

Use an intersection mask. An intersection is found only if an object is matching the intersection mask, otherwise it is ignored.
Specify the list of objects to exclude and pass to the function as an argument.

Usage Example

The following example shows how you can get the intersection information by using the PhysicsIntersection class. In this example we specify a line from the point of the camera (vec3 p0) to the point of the mouse pointer (vec3 p1). The executing sequence is the following:

Define and initialize two points (p0 and p1) by using the Unigine::getPlayerMouseDirection() function from core/scripts/utils.h.
Create an instance of the PhysicsIntersection class to get the intersection information.
Check, if there is an intersection with an object with a shape or a collision object. The engine.physics.getIntersection() function returns an intersected object when the object intersects with the traced line.
In this example, when the object intersects with the traced line, all the surfaces of the intersected object change their material parameters. If the object has a shape, its information will be shown in console. The PhysicsIntersection class instance gets the coordinates of the intersection point, the index of the surface and the Shape class object. You can get all these fields by using getShape(), getPoint() and getSurface() functions

Source code(UnigineScript)

#include <core/scripts/utils.h>
/* ... */
// define two vec3 coordinates
vec3 p0,p1;
// get the mouse direction from camera (p0) to the cursor pointer (p1)
Unigine::getPlayerMouseDirection(p0,p1);

// create the instance of the PhysicsIntersection object to save the result
PhysicsIntersection intersection = new PhysicsIntersection();
// create an instance for intersected object and check the intersection
Object object = engine.physics.getIntersection(p0,p1,1,intersection);

// if the intersection has been occurred, change the parameter 
// and the texture of the object's material    
if(object != NULL)
{
  forloop(int i=0; object.getNumSurfaces())
  {
    object.setMaterialParameter("diffuse_color", vec4(1.0f, 0.0f, 0.0f, 1.0f),i);
    object.setMaterialTexture("diffuse","", i);
  }
  
  // if the intersected object has a shape, show the information about the intersection   
  Shape shape = intersection.getShape();
  if (shape != NULL)
  {
    log.message("physics intersection info: point: %s shape: %s surface: %i \n", typeinfo(intersection.getPoint()), typeinfo(shape.getType()), intersection.getSurface());
  }
}
/* ... */

You can check the intersection with obstacles by using the engine.game.getIntersection() function. This function creates an invisible cylinder between two points and check if an obstacle is presented inside of it.

The picture above shows how the engine.game.getIntersection() function detects the obstacle that intersects with the cylinder.

The function returns an intersected obstacle which is the nearest to the start point (p0). Information about the intersection will be presented in the GameIntersection class instance which you pass to the function as an argument. The GameIntersection class instance saves the intersection point which is the nearest to the start (p0) point.

The engine.game.getIntersection() function is overloaded and receives 5 or 6 arguments:

vec3 p0 - the start point coordinates.
vec3 p1 - the end point coordinates.
float radius - the end point coordinates.
int mask - the obstacle intersection mask. Use the intersection mask to find object only with specified intersection mask.
int exclude[] - the list of obstacles to exclude.
GameIntersection intersection - The function returns an intersected obstacle which is the nearest to the start point (p0). Information about the intersection will be presented in the GameIntersection class instance which you pass to the function as an argument.
Notice
Passing NULL instead of the intersection query object will perform fast intersection algorithm without the closest intersection point searching.

Thus, to exclude some obstacles you should use these methods:

Use an obstacle intersection mask. An intersection is found only if an object is matching the intersection mask, otherwise it is ignored.
Specify the list of obstacles to exclude and pass to the function as an argument.

Usage Example

The following example shows how you can get the intersection point (vec3) of the cylinder between two points with an obstacle. In this example we specify a cylinder from the point of the camera (vec3 p0) to the point of the mouse pointer (vec3 p1) with the specified radius. The executing sequence is the following:

Define and initialize two points (p0 and p1) by using the Unigine::getPlayerMouseDirection() function from core/scripts/utils.h.
Create an instance of the GameIntersection class to get the intersection point coordinates.
Check, if there is an intersection with an obstacle. The engine.game.getIntersection() function returns an intersected obstacle when the obstacle appears in the area of the cylinder.
After that GameIntersection instance gets the point of the nearest intersection point and you can get it by using the getPoint() function.

Source code(UnigineScript)

#include <core/scripts/utils.h>
/* ... */
// define two vec3 coordinates
vec3 p0,p1;
// get the mouse direction from camera (p0) to the cursor pointer (p1)
Unigine::getPlayerMouseDirection(p0,p1);

// create an instance of the GameIntersection class
GameIntersection intersection = new GameIntersection();
 
// try to get the intersection with an obstacle.
// cylinder has radius 0.1f, intersection mask equals to 1
Obstacle obstacle = engine.game.getIntersection(p0,p1,0.1f, 1, intersection);

// check, if the intersection of mouse direction with any obstacle was occurred;
if(obstacle !=NULL)
{
  // show the coordinates of the intersection in console 
  log.message("The intersection with obstacle was here: %s\n", typeinfo(intersection.getPoint()));
}
/* ... */

In This Article:

World Intersection

Intersection with Nodes

Usage Example

Intersection with Objects

Usage Example

First Intersected Object

Usage Example

Physics Intersection

Usage Example

Game Intersection

Usage Example