Unigine::Shape Class

Header:

#include <UniginePhysics.h>

This class creates collision shapes that approximate the finite volume of physical bodies and allow them to collide. Shapes are assigned to a body and are positioned in its local coordinates.

Methods:

Name	Description View: Sort by:
getArea	Returns areas of shape projections on three axes: x, y, and z.
setBody	Sets a body, to which the shape belongs.
getBody	Returns the body, to which the shape belongs.
setBodyShapeTransform	Sets a transformation matrix for the shape (in the coordinates of the body).
getBodyShapeTransform	Returns the transformation matrix of the shape (in the coordinates of the body).
getCenterOfMass	Returns local coordinates of the center of mass of the shape.
setCollisionMask	Sets a collision mask for the shape.
getCollisionMask	Returns the collision mask of the actor.
setContinuous	Enables or disables continuous collision detection for spheres or capsules.
isContinuous	Returns a value indicating if continuous collision detection for spheres or capsules is enabled.
setDensity	Sets density of a shape.
getDensity	Returns the current density of a shape.
setEnabled	Enables or disables physical interactions with the shape.
isEnabled	Returns a value indicating if physical interactions with the shape are enabled.
isEnabledSelf	Returns a value indicating if the shape is enabled.
setExclusionMask	Sets an bit mask to prevent collisions of the shape with other ones.
getExclusionMask	Returns the bit mask that prevents collisions of the shape with other ones.
setFriction	Sets a friction of the shape surface.
getFriction	Returns the friction of the shape surface.
setID	Sets the unique ID for the shape.
getID	Returns the unique ID of the shape.
getInertia	Returns a matrix that represents inertia tensor describing the resistance of the body to rotation in different directions.
setPhysicsIntersectionMask	Sets a physics intersection mask for the shape.
getPhysicsIntersectionMask	Returns a physics intersection mask of the shape.
setMass	Sets a mass of the shape.
getMass	Returns the mass of the shape.
setName	Sets the name of the shape.
getName	Returns the name of the shape.
getNumber	Returns the number of shape instances.
setRestitution	Sets a restitution of the shape surface.
getRestitution	Returns the restitution of the shape surface.
isIdentity	Returns a value indicating if the shape has a scale equal to 1 and no rotation.
setTransform	Sets a transformation matrix for the shape of the object (in world coordinates).
getTransform	Returns the transformation matrix of the shape of the object (in world coordinates).
getType	Returns the type of the shape.
getTypeName	Returns the name of the shape type.
getVolume	Returns the volume of the shape.
getCollision	Performs collision check for the shape and puts information on all contacts to the output buffer.
getIntersection	Performs tracing from the p0 point to the p1 point to find a shape intersected by this line.
setPosition	Sets shape position.
getPosition	Returns the current shape position of the object, in world coordinates.
getTypeName	Returns the name of a shape type with a given ID.
setVelocity	Sets a new velocity vector for the shape.
getVelocity	Returns the current velocity vector of the shape.
clone	Clones the shape.
renderVisualizer	Renders the shape.
saveState	Saves the state of a given node into a binary stream.
restoreState	Restores the state of a given node from a binary stream.
swap	Swaps the shapes saving the pointers.
createShape	Creates a new shape of the specified type.

Shape Class

Enums

TYPE#

Name	Description
SHAPE_SPHERE = 0	Sphere.
SHAPE_CAPSULE = 1	Capsule.
SHAPE_CYLINDER = 2	Cylinder.
SHAPE_BOX = 3	Box.
SHAPE_CONVEX = 4	Convex hull.
NUM_SHAPES = 5

Members

Math::vec3 getArea ( ) #

Returns areas of shape projections on three axes: x, y, and z.

Return value

A triple of projection areas.

void setBody ( const Ptr<Body> & body ) #

Sets a body, to which the shape belongs.

Arguments

const Ptr<Body> & body - Body, to which the shape belongs.

Ptr<Body> getBody ( ) #

Returns the body, to which the shape belongs.

Return value

Body, to which the shape belongs.

void setBodyShapeTransform ( const Math::mat4 & transform ) #

Sets a transformation matrix for the shape (in the coordinates of the body). This matrix describes position and orientation of the shape. This method is identical to setShapeTransform().

Arguments

const Math::mat4 & transform - Transformation matrix

Math::mat4 getBodyShapeTransform ( ) #

Returns the transformation matrix of the shape (in the coordinates of the body). This matrix describes position and orientation of the shape. This method is identical to getShapeTransform().

Return value

Transformation matrix

Math::vec3 getCenterOfMass ( ) #

Returns local coordinates of the center of mass of the shape.

Return value

Coordinates of the center of mass.

int getCollision ( Vector< Ptr<ShapeContact> > & contacts, float ifps ) #

Performs collision check for the shape and puts information on all contacts to the output buffer.

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

The surface is enabled.
Per-surface Collision flag is enabled.
The surface has a material assigned.

Notice

The shape must be enabled.

Arguments

Vector< Ptr<ShapeContact> > & contacts - Output buffer containing information on all detected physical contacts for the shape (if any). Information on each contact can be handled via the ShapeContact class.
float ifps - Inverse FPS value.

Return value

1 if collisions are found; otherwise, 0.

int getCollision ( const Ptr<Object> & object, Vector< Ptr<ShapeContact> > & contacts, float ifps ) #

Performs collision check for the shape and puts information on all contacts and contact object to the output buffer.

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

The surface is enabled.
Per-surface Collision flag is enabled.
The surface has a material assigned.

Notice

The shape must be enabled.

Arguments

const Ptr<Object> & object - Object to be ignored when detecting collisions. This parameter is used when it is necessary to ignore collisions of the shape with the object it belongs to.
Vector< Ptr<ShapeContact> > & contacts - Output buffer containing information on all detected physical contacts for the shape (if any). Information on each contact can be handled via the ShapeContact class.
float ifps - Inverse FPS value.

Return value

1 if collisions are found; otherwise, 0.

void setCollisionMask ( int mask ) #

Sets a collision mask for the shape. Two objects collide if they both have matching masks. See also details on additional collision exclusion mask.

Arguments

int mask - Integer, each bit of which is a mask.

int getCollisionMask ( ) #

Returns the collision mask of the actor. Two objects collide if they both have matching masks.See also details on additional collision exclusion mask.

Return value

Integer, each bit of which is a mask.

void setContinuous ( int continuous ) #

Enables or disables continuous collision detection for spheres or capsules. Enabled CDD incurs almost no performance penalty. Disabling CCD allows to avoid physics artifacts, if there are any.

Arguments

int continuous - Positive value to enable CCD; 0 to disable.

int isContinuous ( ) #

Returns a value indicating if continuous collision detection for spheres or capsules is enabled. Enabled CCD incurs almost no performance penalty. Disabling CCD allows to avoid physics artifacts, if there are any.

Return value

1 if CCD is enabled; otherwise, 0.

void setDensity ( float density ) #

Sets density of a shape. Changing the density influences the mass, that is computed by multiplying shape volume by density.

Arguments

float density - Density value. If a negative value is provided, 0 will be used instead.

float getDensity ( ) #

Returns the current density of a shape.

Return value

Density value.

void setEnabled ( int enable ) #

Enables or disables physical interactions with the shape.

Arguments

int enable - Positive number to enable physical interactions, 0 to disable them.

int isEnabled ( ) #

Returns a value indicating if physical interactions with the shape are enabled.

Return value

1 if physical interactions with the shape are enabled; otherwise, 0.

int isEnabledSelf ( ) #

Returns a value indicating if the shape is enabled.

Return value

1 if the shape is enabled; otherwise, 0.

void setExclusionMask ( int mask ) #

Sets an bit mask to prevent collisions of the shape with other ones. This mask is independent of the collision mask. For shapes with matching collision masks not to collide, at least one bit of their exclusion mask should match.

Arguments

int mask - Integer, each bit of which is a mask.

int getExclusionMask ( ) #

Returns the bit mask that prevents collisions of the shape with other ones. This mask is independent of the collision mask. For shape with matching collision masks not to collide, at least one bit of their exclusion mask should match.

Return value

Integer, each bit of which is a mask.

void setFriction ( float friction ) #

Sets a friction of the shape surface.

Arguments

float friction - Friction of the shape surface. If a negative value is provided, 0 will be used instead.

float getFriction ( ) #

Returns the friction of the shape surface.

Return value

Friction of the shape surface.

void setID ( int id ) #

Sets the unique ID for the shape.

Arguments

int id - Unique ID.

int getID ( ) #

Returns the unique ID of the shape.

Return value

Unique ID.

Math::mat3 getInertia ( ) #

Returns a matrix that represents inertia tensor describing the resistance of the body to rotation in different directions. It is determined by the distribution of mass throughout the body volume.

Return value

Inertia tensor.

int getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, const Ptr<PhysicsIntersectionNormal> & intersection ) #

Performs tracing from the p0 point to the p1 point to find a shape intersected by this line. Intersection is found only for objects with a matching intersection mask.

Notice

World space coordinates are used for this function.

Arguments

const Math::Vec3 & p0 - Start point of the line.
const Math::Vec3 & p1 - End point of the line.
const Ptr<PhysicsIntersectionNormal> & intersection - PhysicsIntersectionNormal class instance containing intersection information

Return value

1 if an intersection was detected; otherwise - 0.

int getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, const Ptr<PhysicsIntersection> & intersection ) #

Performs tracing from the p0 point to the p1 point to find a shape intersected by this line. Intersection is found only for objects with a matching intersection mask.

Notice

World space coordinates are used for this function.

Usage Example

The following example shows how you can get the intersection information by using the PhysicsIntersection class. In this example the line is an invisible traced line from the point of the camera (vec3 p0) to the point of the mouse pointer (vec3 p1). It is supposed that you have a dynamic mesh with a body and a shape assigned. The executing sequence is the following:

Define and initialize two points (p0 and p1) by using the Player::getDirectionFromScreen() function.
Create an instance of the PhysicsIntersection class to get the information of the intersection point.
Check, if there is a intersection with a shape and save the result in the integer variable.
In this example, if there is an intersection of mouse direction with a shape, the PhysicsIntersection class instance gets the intersection point. The result is shown in the console.

Source code (C++)

/* ... */
// initialize points of the mouse direction
Vec3 p0, p1;

// get the current player (camera)
PlayerPtr player = Game::getPlayer();
if (player.get() == NULL)
	return 0;
// get width and height of the current application window
int width = App::getWidth();
int height = App::getHeight();
// get the current X and Y coordinates of the mouse pointer
int mouse_x = App::getMouseX();
int mouse_y = App::getMouseY();
// get the mouse direction from the player's position (p0) to the mouse cursor pointer (p1)
player->getDirectionFromScreen(p0, p1, mouse_x, mouse_y, width, height);

// create the instance of the PhysicsIntersection object to save the information about the intersection
PhysicsIntersectionPtr intersection = PhysicsIntersection::create();
// create an integer variable to check the result of intersection
int result = 0;
result = shape->getIntersection(p0, p1, intersection);
// if there was an intersection, show the message in console
if (result != 0)
{
	Log::message("Intersection point: (%f %f %f) \n", intersection->getPoint().x, intersection->getPoint().y, intersection->getPoint().z);
}
/* ... */

Arguments

const Math::Vec3 & p0 - Start point of the line.
const Math::Vec3 & p1 - End point of the line.
const Ptr<PhysicsIntersection> & intersection - PhysicsIntersection class instance containing intersection information.

Return value

1 if an intersection was detected; otherwise - 0.

int getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, Math::Vec3 * ret_point, Math::vec3 * ret_normal ) #

Performs tracing from the p0 point to the p1 point to find a shape intersected by this line. Intersection is found only for objects with a matching intersection mask.

Notice

World space coordinates are used for this function.

Arguments

const Math::Vec3 & p0 - Start point of the line (in world coordinates).
const Math::Vec3 & p1 - End point of the line (in world coordinates).
Math::Vec3 * ret_point - Container to which contact point coordinates (if any) shall be put (in world coordinate system).
Math::vec3 * ret_normal - Container to which contact point normal coordinates (if any) shall be put (in world coordinate system).

Return value

1 if an intersection was detected; otherwise - 0.

void setPhysicsIntersectionMask ( int mask ) #

Sets a physics intersection mask for the shape.

Arguments

int mask - Integer, each bit of which is a mask.

int getPhysicsIntersectionMask ( ) #

Returns a physics intersection mask of the shape.

Return value

Integer, each bit of which is a mask.

void setMass ( float mass ) #

Sets a mass of the shape. Changing the mass influences the density, that is computed by dividing the mass by shape volume.

NoticeIf g (Earth's gravity) equals to 9.8 m/s
						2, and 1 unit equals to 1 m, a shape with mass value of
						1 weighs 1 kg.

Arguments

float mass - Mass of the shape. If a negative value is provided, 0 will be used instead.

float getMass ( ) #

Returns the mass of the shape.

NoticeIf g (Earth's gravity) equals to 9.8 m/s
						2, and 1 unit equals to 1 m, the mass is measured in kilograms.
					

Return value

Mass of the shape.

void setName ( const char * name ) #

Sets the name of the shape.

Arguments

const char * name - Name of the shape.

const char * getName ( ) #

Returns the name of the shape.

Return value

Name of the shape.

int getNumber ( ) #

Returns the number of shape instances.

Return value

Number of shape instances.

void setRestitution ( float restitution ) #

Sets a restitution of the shape surface.

Arguments

float restitution - Restitution of the shape surface. The provided value will be saturated in the range [0; 1].

float getRestitution ( ) #

Returns the restitution of the shape surface.

Return value

Restitution of the shape surface.

void setPosition ( const Math::Vec3 & position ) #

Sets shape position. This method resets shape's velocity to 0.

Notice

This method should be called only from the object owning this shape. If the shape is owned by the body, it is highly recommended to use the setShapeTransform() method of the owning body.

Arguments

const Math::Vec3 & position - New shape's position, in world coordinates.

Math::Vec3 getPosition ( ) #

Returns the current shape position of the object, in world coordinates.

Return value

Current shape's position, in world coordinates.

int isIdentity ( ) #

Returns a value indicating if the shape has a scale equal to 1 and no rotation.

Return value

1 if the shape has a scale equal to 1 and no rotation; otherwise, 0.

void setTransform ( const Math::Mat4 & transform ) #

Sets a transformation matrix for the shape of the object (in world coordinates). This matrix describes position and orientation of the shape. This method resets shape's linear velocity to 0.

Notice

This method should be called only from the object owning this shape. If the shape is owned by the body, it is highly recommended to use the setShapeTransform() method of the owning body.

Arguments

const Math::Mat4 & transform - Transformation matrix

Math::Mat4 getTransform ( ) #

Returns the transformation matrix of the shape of the object (in world coordinates). This matrix describes position and orientation of the shape.

Return value

Transformation matrix

int getType ( ) #

Returns the type of the shape.

Return value

One of the SHAPE_* pre-defined variables.

const char * getTypeName ( ) #

Returns the name of the shape type.

Return value

Type name.

const char * getTypeName ( int type ) #

Returns the name of a shape type with a given ID.

Arguments

int type - Shape type ID. One of the SHAPE_* values.

Return value

Shape type name.

void setVelocity ( const Math::vec3 & velocity, float ifps ) #

Sets a new velocity vector for the shape.

Arguments

const Math::vec3 & velocity - Velocity vector, each component represents shape's velocity along the corresponding axis, in units per second.
float ifps - Inverse FPS value.

Math::vec3 getVelocity ( ) #

Returns the current velocity vector of the shape.

Return value

Current celocity vector, each component represents shape's velocity along the corresponding axis, in units per second.

float getVolume ( ) #

Returns the volume of the shape.

Return value

Volume of the shape in cubic units.

Ptr<Shape> clone ( ) #

Clones the shape.

Return value

Copy of the shape.

void renderVisualizer ( const Math::vec4 & color ) #

Renders the shape.

NoticeYou should enable the engine visualizer by the show_visualizer 1 console command.

Arguments

const Math::vec4 & color - Color, in which the shape will be rendered.

bool saveState ( const Ptr<Stream> & stream ) #

Saves the state of a given node into a binary stream.

If a node is a parent for other nodes, states of these child nodes need to be saved manually.
To save the state from a buffer, file or a message from a socket, make sure the stream is opened. For buffers and files, you also need to set the proper position for reading.

Example using saveState() and restoreState() methods:

Source code (C++)

// set the shape state
shape->setFriction(0.8f);

// save state
BlobPtr blob_state = Blob::create();
shape->saveState(blob_state);

// change the state
shape->setFriction(0.4f);

// restore state
blob_state->seekSet(0);       // returning the carriage to the start of the blob
shape->restoreState(blob_state);

Arguments

const Ptr<Stream> & stream - Stream to save node state data.

Return value

true if the node state is saved successfully; otherwise, false.

bool restoreState ( const Ptr<Stream> & stream ) #

Restores the state of a given node from a binary stream.

If a node is a parent for other nodes, states of these child nodes need to be restored manually.
To save the state into a buffer, file or a message from a socket, make sure the stream is opened. If necessary, you can set a position for writing for buffers and files.

Example using saveState() and restoreState() methods:

Source code (C++)

// set the shape state
shape->setFriction(0.8f);

// save state
BlobPtr blob_state = Blob::create();
shape->saveState(blob_state);

// change the state
shape->setFriction(0.4f);

// restore state
blob_state->seekSet(0);       // returning the carriage to the start of the blob
shape->restoreState(blob_state);

Arguments

const Ptr<Stream> & stream - Stream with saved node state data.

Return value

true if the node state is restored successfully; otherwise, false.

void swap ( const Ptr<Shape> & shape ) #

Swaps the shapes saving the pointers.

Arguments

const Ptr<Shape> & shape - A shape to swap.

Ptr<Shape> createShape ( int type ) #

Creates a new shape of the specified type.

Arguments

int type - Body type. One of the SHAPE_* values.

Return value

New created shape smart pointer.

Ptr<Shape> createShape ( const char * type_name ) #

Creates a new shape of the specified type.

Arguments

const char * type_name - Shape type name.

Return value

New created shape smart pointer.

Last update: 2021-12-13

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)

Unigine::Shape Class

See Also#

Methods:

Shape Class

Enums

TYPE#

Members

Math::vec3 getArea ( ) #

Return value

void setBody ( const Ptr<Body> & body ) #

Arguments

Ptr<Body> getBody ( ) #

Return value

void setBodyShapeTransform ( const Math::mat4 & transform ) #

Arguments

Math::mat4 getBodyShapeTransform ( ) #

Return value

Math::vec3 getCenterOfMass ( ) #

Return value

int getCollision ( Vector< Ptr<ShapeContact> > & contacts, float ifps ) #

Arguments

Return value

int getCollision ( const Ptr<Object> & object, Vector< Ptr<ShapeContact> > & contacts, float ifps ) #

Arguments

Return value

void setCollisionMask ( int mask ) #

Arguments

int getCollisionMask ( ) #

Return value

void setContinuous ( int continuous ) #

Arguments

int isContinuous ( ) #

Return value

void setDensity ( float density ) #

Arguments

float getDensity ( ) #

Return value

void setEnabled ( int enable ) #

Arguments

int isEnabled ( ) #

Return value

int isEnabledSelf ( ) #

Return value

void setExclusionMask ( int mask ) #

Arguments

int getExclusionMask ( ) #

Return value

void setFriction ( float friction ) #

Arguments

float getFriction ( ) #

Return value

void setID ( int id ) #

Arguments

int getID ( ) #

Return value

Math::mat3 getInertia ( ) #

Return value

int getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, const Ptr<PhysicsIntersectionNormal> & intersection ) #

Arguments

Return value

int getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, const Ptr<PhysicsIntersection> & intersection ) #

Arguments

Return value

int getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, Math::Vec3 * ret_point, Math::vec3 * ret_normal ) #

Arguments

Return value

void setPhysicsIntersectionMask ( int mask ) #

Arguments

int getPhysicsIntersectionMask ( ) #

Return value

void setMass ( float mass ) #

Arguments

float getMass ( ) #

Return value

void setName ( const char * name ) #

Arguments

const char * getName ( ) #

Return value

int getNumber ( ) #

Return value