Getting Started
Migrating to UNIGINE 2.0
C++ API Migration
UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
Usage Examples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins

Object Class

An object with a set of surfaces to represent geometry. Rendering materials are assigned per object surface. An object can be assigned a physical body.

See Also

Object Class

This class inherits from Node

Members


int findSurface (string name)

Searches for a surface with a given name.

Arguments

  • string name - Name of the surface.

Return value

Surface ID number or -1, if nothing is found.

void flushBodyTransform ()

Forces to set the transformations of the body for the node.

BodyRigid getBodyRigid ()

Returns a rigid body assigned to the object.

Return value

Rigid body assigned to the object or NULL (0), if no body is assigned or the body is not rigid.

Body getBody ()

Returns a physical body assigned to the object.

Return value

Body assigned to the object or NULL (0), if no body is assigned.

BoundBox getBoundBox (int surface)

Returns a bounding box of a given surface.

Arguments

  • int surface - Surface number in range from 0 to the total number of surfaces.

Return value

Bounding box.

BoundSphere getBoundSphere (int surface)

Returns a bounding sphere of a given surface.

Arguments

  • int surface - Surface number in range from 0 to the total number of surfaces.

Return value

Bounding sphere.

int getCastShadow (int surface)

Returns a value indicating if a given surface casts shadows from non-world lights.

Arguments

  • int surface - ID number of the surface.

Return value

Positive number if shadows are cast by the surface.

int getCastWorldShadow (int surface)

Returns a value indicating if a given surface casts shadows from world lights.

Arguments

  • int surface - ID number of the surface.

Return value

Positive number if world shadows are cast by the surface.

int getCollisionMask (int surface)

Returns a collision mask of a given surface. Two objects collide, if they both have matching masks.

Arguments

  • int surface - ID number of the surface.

Return value

Integer, each bit of which is a mask.

int getCollision (int surface)

Returns a value indicating if collisions with a given surface are calculated.

Arguments

  • int surface - ID number of the surface.

Return value

Positive number if collisions with the surface are calculated; otherwise 0.

int getIntersectionMask (int surface)

Returns an intersection mask of a given surface.

Arguments

  • int surface - ID number of the surface.

Return value

Integer, each bit of which is a mask.

int getIntersection (int surface)

Returns a value indicating if a given surface can be intersected.

Arguments

  • int surface - ID number of the surface.

Return value

Positive number if the surface can be intersected; otherwise 0.

int getIntersection (vec3 p0, vec3 p1, variable v, int surface)

Performs tracing from the p0 point to the p1 point to find out if the specific object with the specific surface index intersects the line. This function detects intersection with surfaces (polygons) of objects. An intersection is found only if an object is matching the intersection mask.

Notice
Local coordinates are used for this function.

Depending on the variable passed as the third argument, the result can be presented as the ObjectIntersection, ObjectIntersectionNormal or ObjectIntersectionTexCoord node.

Intersections with the surface can be found only if the following conditions are fulfilled:

  1. A per-surface Intersection flag is enabled.
  2. An Intersection option of the property in the Properties window is enabled.
  3. A surface is enabled.
  4. A surface has an assigned material.
  5. A surface has an assigned property.

Usage Example

As the function uses local coordinates, you should care about the changing them to world coordinates, if you make transformations of the object. The following example shows how you should change getPlayerMouseDirection() from the <utils.h> file. We take the transformation of the object and pass it to the getPlayerMouseDirection() function as an argument.

Source code (UnigineScript)
int getPlayerMouseDirection(Vec3 &p0,Vec3 &p1,mat4 transform = mat4_identity) {

	Player player = getPlayer();
	if(player == NULL) return 0;
	int width = engine.app.getWidth();
	int height = engine.app.getHeight();
	int mouse_x = engine.app.getMouseX();
	int mouse_y = engine.app.getMouseY();
	mat4 projection = player.getProjection();
	// translate to world coordinates
	mat4 imodelview = inverse(transform) * player.getIModelview() * inverse(player.getOffset());
	#ifdef HAS_APP_WALL
		if(engine.wall.getWidth() > 1 || engine.wall.getHeight() > 1) {
			int wall_x = clamp(engine.wall.getPrimaryX() + mouse_x / width - (mouse_x < 0),0,engine.wall.getWidth() - 1);
			int wall_y = clamp(engine.wall.getPrimaryY() + mouse_y / height - (mouse_y < 0),0,engine.wall.getHeight() - 1);
			projection = engine.wall.getProjection(wall_x,wall_y);
			imodelview = inverse(engine.wall.getModelview(wall_x,wall_y));
			mouse_x -= width * (wall_x - engine.wall.getPrimaryX());
			mouse_y -= height * (wall_y - engine.wall.getPrimaryY());
		}
	#elif HAS_APP_PROJECTION
		if(engine.projection.getWidth() > 1) {
			int wall_x = clamp(engine.projection.getPrimary() + mouse_x / width - (mouse_x < 0),0,engine.projection.getWidth() - 1);
			projection = engine.projection.getProjection(wall_x);
			imodelview = inverse(engine.projection.getModelview(wall_x));
			mouse_x -= width * (wall_x - engine.projection.getPrimary());
		}
	#elif HAS_APP_SURROUND || HAS_APP_3D_SURROUND
		int wall_x = clamp(1 + mouse_x / width - (mouse_x < 0),0,2);
		projection = engine.surround.getProjection(wall_x);
		imodelview = inverse(engine.surround.getModelview(wall_x));
		mouse_x -= width * (wall_x - 1);
	#endif
	projection.m00 *= float(height) / width;
	float x = -(float(mouse_x) / width * 2.0f - 1.0f + projection.m02) / projection.m00;
	float y = (float(mouse_y) / height * 2.0f - 1.0f + projection.m12) / projection.m11;
	if(projection.m32 == -1.0f) {
		p0 = imodelview.m03m13m23;
		p1 = imodelview * Vec3(x,y,1.0f);
	} else {
		p0 = imodelview * Vec3(-x,-y,-1.0f);
		p1 = imodelview * Vec3(-x,-y,1.0f);
	}
	p1 = p0 - normalize(p1 - p0) * player.getZFar();
	return 1;
}
                	

In the update() method we get the mouse direction and pass current transformation of the mesh to the getPlayerMouseDirection() function. The executing sequence is the following:

  • Define and initialize two points (p0 and p1) by using the getPlayerMouseDirection() function.
  • Create an instance of the ObjectIntersection class to get the intersection information.
  • Check, if there is a intersection with the object. The getIntersection() function saves the data about the intersection into the ObjectIntersection class instance. After that console shows the index of the intersected triangle.
Source code (UnigineScript)
/* ... */
// define two vec3 coordinates
Vec3 p0, p1;
// get the mouse direction from camera (p0) to cursor pointer (p1) 
// and pass mesh transformation to the getPlayerMouseDirection() function
getPlayerMouseDirection(p0, p1, mesh.getWorldTransform());
	
// create the instance of the PhysicsIntersection object to save the result
ObjectIntersection intersection = new ObjectIntersection();
// get the result of intersection of the traced line with surface of the mesh
int result = mesh.getIntersection(p0, p1, intersection, 0);
//  if the intersection has been occurred, show the message in console 
if(result) 		
{
	log.message("intersected triangle number:%s \n", typeinfo(intersection.getIndex()));
}
	
/* ... */
                

Arguments

  • vec3 p0 - Start point coordinates.
  • vec3 p1 - End point coordinates.
  • variable v - Variable used to control which type of intersection object will be returned:
  • int surface - Surface number.

Return value

Reference to the first intersected object, if found; otherwise - 0.

int getLightMask (int surface)

Returns a light mask of a given surface. A surface is illuminated by a light source, if they both have corresponding masks.

Arguments

  • int surface - ID number of the surface.

Return value

Integer, each bit of which is a mask.

Material getMaterialInherit (int surface)

Inherits the surface material (i.e. creates a material instance). Modifications made in a new material instance will not affect the source material.

Arguments

  • int surface - ID number of the surface.

Return value

The inherited material.

string getMaterialName (int surface)

Returns the name of a material applied to a given surface.

Arguments

  • int surface - ID number of the surface.

Return value

Material name.

vec4 getMaterialParameter (string parameter, int surface)

Returns a value of a given parameter of the surface material.

Arguments

  • string parameter - Name of the parameter.
  • int surface - ID number of the surface.

Return value

Value of the parameter.

int getMaterialState (string state, int surface)

Returns a state value of a given surface material.

Arguments

  • string state - Material state name.
  • int surface - ID number of the surface.

Return value

State value.

string getMaterialTexture (string texture, int surface)

Returns a path to a given texture of a given surface material.

Arguments

  • string texture - Material texture name.
  • int surface - ID number of the surface.

Return value

Path to the texture file.

Material getMaterial (int surface)

Returns a material used for a given surface.

Arguments

  • int surface - ID number of the surface.

Return value

Material used for the surface.

float getMaxFadeDistance (int surface)

Returns a maximum fade-out distance, across which the surface smoothly becomes invisible due to the alpha fading. It is counted starting from the maximum visibility distance value.

Arguments

  • int surface - ID number of the surface.

Return value

Distance value, in units.

int getMaxParent (int surface)

Returns the number of hierarchy levels up to the reference object, which is used to measure the maximum visible distance:
  • 0 is the current surface
  • 1 is the object to which the surface belongs
  • higher values are to move higher up the hierarchy to node parents

Arguments

  • int surface - ID number of the surface.

Return value

Number of hierarchy levels.

float getMaxVisibleDistance (int surface)

Returns a maximum visibility distance, starting at which the surface begins to fade out until becomes completely invisible.

Arguments

  • int surface - ID number of the surface.

Return value

Distance value, in units.

float getMinFadeDistance (int surface)

Returns a minimum fade-in distance, across which the surface smoothly becomes visible due to the alpha fading. It is counted starting from the minimum visibility distance value.

Arguments

  • int surface - ID number of the surface.

Return value

Distance value, in units.

int getMinParent (int surface)

Returns the number of hierarchy levels up to the reference object, which is used to measure the minimum visible distance:
  • 0 is the current surface
  • 1 is the object to which the surface belongs
  • higher values are to move higher up the hierarchy to node parents

Arguments

  • int surface - ID number of the surface.

Return value

Number of hierarchy levels.

float getMinVisibleDistance (int surface)

Returns a minimum visibility distance, starting at which the surface begins to fade in and then becomes completely visible.

Arguments

  • int surface - ID number of the surface.

Return value

Distance value, in units.

int getNumSurfaces ()

Returns the number of surfaces of the object.

Return value

Number of surfaces.

int getNumTriangles (int surface)

Returns the number of triangles comprising a given surface.

Arguments

  • int surface - ID number of the surface.

Return value

Number of triangles.

int getParent (int surface)

Returns the parent surface of a given surface.

Arguments

  • int surface - ID number of the surface.

Return value

ID number of the parent surface.

Property getPropertyInherit (int surface)

Inherits the property for the specific object. All transformations done to the inherited property will not affect the reference one.

Arguments

  • int surface - ID number of the surface.

Return value

The inherited property.

string getPropertyName (int surface)

Returns the name of a property applied to a given surface.

Arguments

  • int surface - ID number of the surface.

Return value

Property name.

variable getPropertyParameter (string parameter, int surface)

Returns a value of a given parameter of the surface property.

Arguments

  • string parameter - Name of the parameter.
  • int surface - ID number of the surface.

Return value

Value of the parameter. Either int, float or string.

int getPropertyState (string state, int surface)

Returns a state value of a given surface property.

Arguments

  • string state - Material state name.
  • int surface - ID number of the surface.

Return value

State value.

Property getProperty (int surface)

Returns a property defined for a given surface.

Arguments

  • int surface - ID number of the surface.

Return value

Property used for the surface.

string getSurfaceName (int surface)

Returns the name of a given surface.

Arguments

  • int surface - ID number of the surface.

Return value

Name of the surface.

int getViewportMask (int surface)

Returns the current bit mask for rendering into the viewport. The object surface is rendered, if its mask matches the player's and light source's ones. The material mask should also match.

Arguments

  • int surface - ID number of the surface.

Return value

Integer, each bit of which is a mask.

BoundBox getWorldBoundBox (int surface)

Returns the world bounding box of a given surface.

Arguments

  • int surface - Surface number in range from 0 to the total number of surfaces.

Return value

Bounding box.

BoundSphere getWorldBoundSphere (int surface)

Returns the world bounding sphere of a given surface.

Arguments

  • int surface - Surface number in range from 0 to the total number of surfaces.

Return value

Bounding sphere.

int isEnabled (int surface)

Returns a value indicating if a given surface is enabled.

Arguments

  • int surface - ID number of the surface.

Return value

Positive number if the surface is enabled; otherwise, 0.

int isFolded (int surface)

Returns a value indicating if surface's children are displayed or minimized in the surface hierarchy.

Arguments

  • int surface - Surface ID to minimize its children.

Return value

Positive number if surface's children are hidden in the surface hierarchy; otherwise, 0.

int isMaterialInherited (int surface)

Returns a value indicating if a given surface material is inherited (instanced). Modifications made in a material instance do not affect the source material.

Arguments

  • int surface - ID number of the surface.

Return value

Positive number if the material is inherited; otherwise, 0.

int isPropertyInherited (int surface)

Returns a value indicating if a given property is inherited.

Arguments

  • int surface - ID number of the surface.

Return value

Positive number if the property is inherited; otherwise, 0.

void setBody (Body body)

Assigns a physical body to the object.

Arguments

  • Body body - Physical body.

void setCastShadow (int mode, int surface)

Sets a value indicating if a given surface should cast shadows from non-world lights.

Arguments

  • int mode - Positive number to let the surface cast shadows, 0 no to let.
  • int surface - ID number of the surface.

void setCastWorldShadow (int mode, int surface)

Sets a value indicating if a given surface should cast shadows from world lights.

Arguments

  • int mode - Positive number to let the surface cast world shadows, 0 no to let.
  • int surface - ID number of the surface.

void setCollisionMask (int mask, int surface)

Sets a collision mask for a given surface. Two objects collide, if they both have matching masks.

Arguments

  • int mask - Integer, each bit of which is a mask.
  • int surface - ID number of the surface.

void setCollision (int mode, int surface)

Enables or disables collisions with a given surface.

Arguments

  • int mode - Positive number to enable collisions with the surface; otherwise 0.
  • int surface - ID number of the surface.

void setEnabled (int mode, int surface)

Enables or disables a given surface.

Arguments

  • int mode - Positive number to enable the surface, 0 to disable it.
  • int surface - ID number of the surface.

void setFolded (int fold, int surface)

Shows or minimizes surface's children in the surface hierarchy.

Arguments

  • int fold - Positive number to minimize surface's children, 0 to expand the hierarchy.
  • int surface - Surface ID to minimize its children.

void setIntersectionMask (int mask, int surface)

Sets an intersection mask for a given surface.

Arguments

  • int mask - Integer, each bit of which is a mask.
  • int surface - ID number of the surface.

void setIntersection (int mode, int surface)

Enables or disables intersections with a given surface.

Arguments

  • int mode - Positive number to enable intersections with the surface; otherwise 0.
  • int surface - ID number of the surface.

void setLightMask (int mask, int surface)

Sets a light mask for a given surface. A surface is illuminated by a light source, if they both have corresponding masks.

Arguments

  • int mask - Integer, each bit of which is a mask.
  • int surface - ID number of the surface.

void setMaterialParameter (string parameter, vec4 value, int surface)

Sets a value of a given parameter of the surface material.

Arguments

  • string parameter - Name of the parameter.
  • vec4 value - Value of the parameter.
  • int surface - ID number of the surface.

void setMaterialState (string state, int value, int surface)

Sets a state value for a given surface material.

Arguments

  • string state - Material state name.
  • int value - State value.
  • int surface - ID number of the surface.

void setMaterialTexture (string texture, string path, int surface)

Sets a path to a given texture of a given surface material.

Arguments

  • string texture - Material texture name.
  • string path - Path to the texture file.
  • int surface - ID number of the surface.

void setMaterial (string material, variable surface)

Sets a material for specified surfaces.

Arguments

  • string material - Name of the new material.
  • variable surface - ID number of the surface (int) or pattern (string with a regular expression), against which surface names will be matched.

void setMaxFadeDistance (float distance, int surface)

Updates a maximum fade-out distance, across which the surface smoothly becomes invisible due to the alpha fading. It is counted starting from the maximum visibility distance value.

Arguments

  • float distance - A minimum fade-out distance, in units. If a negative value is provided, 0 will be used instead.
  • int surface - ID number of the surface.

void setMaxParent (int parent, int surface)

Updates the number of hierarchy levels up to the reference object, which is used to measure the maximum visible distance:
  • 0 is the current surface
  • 1 is the object to which the surface belongs
  • higher values are to move higher up the hierarchy to node parents

Arguments

  • int parent - Number of hierarchy levels. If a negative value is provided, 0 will be used instead.
  • int surface - ID number of the surface.

void setMaxVisibleDistance (float distance, int surface)

Updates the maximum visibility distance, starting at which the surface begins to fade out until becomes completely invisible.

Arguments

  • float distance - A maximum visibility distance, in units. If a negative value is provided, 0 will be used instead.
  • int surface - ID number of the surface.

void setMinFadeDistance (float distance, int surface)

Updates a minimum fade-in distance, across which the surface smoothly becomes visible due to the alpha fading. It is counted starting from the minimum visibility distance value.

Arguments

  • float distance - A minimum fade-in distance, in units. If a negative value is provided, 0 will be used instead.
  • int surface - ID number of the surface.

void setMinParent (int parent, int surface)

Updates the number of hierarchy levels up to the reference object, which is used to measure the minimum visible distance:
  • 0 is the current surface
  • 1 is the object to which the surface belongs
  • higher values are to move higher up the hierarchy to node parents

Arguments

  • int parent - Number of hierarchy levels. If a negative value is provided, 0 will be used instead.
  • int surface - ID number of the surface.

void setMinVisibleDistance (float distance, int surface)

Updates a minimum visibility distance, starting at which the surface begins to fade in and then becomes completely visible.

Arguments

  • float distance - A minimum visibility distance, in units. If a negative value is provided, 0 will be used instead.
  • int surface - ID number of the surface.

void setParent (int parent, int surface)

Sets or clears the parent surface of a given surface.

Arguments

  • int parent - ID number of the parent surface or -1 to clear the parent.
  • int surface - ID number of the surface.

void setPropertyParameter (string parameter, variable value, int surface)

Sets a value of a given parameter of the surface property.

Arguments

  • string parameter - Name of the parameter.
  • variable value - Value of the parameter. Either int, float or string.
  • int surface - ID number of the surface.

void setPropertyState (string state, int value, int surface)

Sets a state value for a given surface property.

Arguments

  • string state - Property state name.
  • int value - State value.
  • int surface - ID number of the surface.

void setProperty (string property, variable surface)

Sets a property for specified surfaces.

Arguments

  • string property - Name of the new property.
  • variable surface - ID number of the surface (int) or pattern (string with a regular expression), against which surface names will be matched.

void setViewportMask (int mask, int surface)

Sets a bit mask for rendering into the viewport. The object surface is rendered, if its mask matches the player's and light source's ones. The material mask should also match.

Arguments

  • int mask - Integer, each bit of which is a mask.
  • int surface - ID number of the surface.

int OBJECT_DYNAMIC_ALL

Description

This flag serves to create a dynamic object or a dynamic mesh whose vertices and indices are changed every frame.
Notice
It increases performance, but memory usage also increases.

int OBJECT_DYNAMIC_INDICES

Description

This flag serves to create a dynamic object or a dynamic mesh whose indices are changed every frame.
Notice
If this flag is set, vertices of the dynamic mesh or object won't be changed.

int OBJECT_DYNAMIC_VERTEX

Description

This flag serves to create a dynamic object or a dynamic mesh whose vertices are changed every frame.
Notice
If this flag is set, indices of the dynamic mesh or object won't be changed.

int OBJECT_IMMUTABLE_ALL

Description

This flag serves to create a dynamic object or a dynamic mesh whose vertices and indices are not changed.

int OBJECT_IMMUTABLE_INDICES

Description

This flag serves to create a dynamic object or a dynamic mesh whose indices are not changed.
Notice
Vertices of the dynamic mesh or object can be changed, but this operation is costly.

int OBJECT_IMMUTABLE_VERTEX

Description

This flag serves to create a dynamic object or a dynamic mesh whose vertices are not changed.
Notice
Indices of the dynamic mesh or object can be changed, but this operation is costly.
Last update: 2017-07-03