Unigine::Physics Class

Header:

#include <UniginePhysics.h>

List of functions:

Controls the simulation of physics. For more information on principles and implementation of physics in real-time rendering, see the articles Execution Sequence, Physics and Simulation of Physics.

Physics Class

Members

Physics * get()

Returns a pointer to the existing physics instance.

Return value

Pointer to the existing physics instance.

void setAngularDamping(float damping)

Updates the current angular damping value.

Arguments

float damping - New angular damping. If a negative value is provided, 0 will be used instead.

float getAngularDamping()

Returns the current angular damping value.

Return value

Angular damping.

Ptr<Body> getBody(int id)

Returns a body with a given ID.

Arguments

int id - Body ID.

Return value

Body with a given ID or NULL (0), if there is no body with a given ID.

int isBody(int id)

Checks if a body with a given ID exists.

Arguments

int id - Body ID.

Return value

1 if a body with a given ID exists; otherwise, 0.

float getBroadTime()

Returns the duration of the broad phase, during which potentially colliding objects are found.

Return value

The broad phase duration value, milliseconds.

void setBudget(float budget)

Sets the physics simulation budget. Physics isn't simulated when time is out of the budget.

Arguments

float budget - The budget value in seconds.

float getBudget()

Returns the physics simulation budget. Physics isn't simulated when time is out of the budget.

Return value

The budget value in seconds. The default value is 1/20.

void setData(const char * data)

Sets user data associated with the world. In the *.world file, the data is set in the data tag.

Arguments

const char * data - New user data.

const char * getData()

Returns user string data associated with the world. This string is written directly into the data tag of the *.world file.

Return value

User string data.

void setDistance(float distance)

Updates a distance after which the physics will not be simulated.

Arguments

float distance - Distance in units.

float getDistance()

Returns a distance after which the physics will not be simulated.

Return value

Distance in units.

void setEnabled(int enable)

Enables or disables physics simulation.

Arguments

int enable - 1 to enable physics, 0 to disable it.

int isEnabled()

Returns a value indicating if physics simulation is enabled. The default is 1.

Return value

1 if physics is enabled; otherwise, 0.

void setFixed(int fixed)

Sets a flag to synchronize rendering FPS to physics one. Such FPS limitation allows to calculate physics each rendered frame (rather then interpolate it when this flag is set to 0). In this mode, there are no twitching of physical objects if they have non-linear velocities. If the rendering FPS is lower than the physics one, this flag has no effect.

Arguments

int fixed - 1 to cap rendering FPS to physics one; 0 to interpolate physics if rendering FPS is higher.

int isFixed()

Returns a flag indicating if rendering FPS is synchronized to physics one. Such FPS limitation allows to calculate physics each rendered frame (rather then interpolate it when this flag is set to 0). In this mode, there are no twitching of physical objects if they have non-linear velocities. If the rendering FPS is lower than the physics one, this flag has no effect.

Return value

Returns 1 if the rendering FPS is synchronized to physics one; 0 if the physics is interpolated if rendering FPS is higher.

int getFrame()

Returns the current frame of physics update.

Return value

Frame number.

void setFrozenAngularVelocity(float velocity)

Updates the angular velocity threshold for freezing object simulation. If the object angular velocity remains lower than this threshold during the number of Frozen frames (together with linear one), it stops to be updated.

Arguments

float velocity - New "freeze" angular velocity. If a negative value is provided, 0 will be used instead.

float getFrozenAngularVelocity()

Returns the current angular velocity threshold for freezing object simulation. An object stops to be updated if its angular velocity remains lower than this threshold during the number of Frozen frames (together with linear one).

Return value

"Freeze" angular velocity.

void setFrozenLinearVelocity(float velocity)

Updates the linear velocity threshold for freezing object simulation. If the object linear velocity remains lower than this threshold during the number of Frozen frames (together with angular one), it stops to be updated.

Arguments

float velocity - New "freeze" linear velocity. If a negative value is provided, 0 will be used instead.

float getFrozenLinearVelocity()

Returns the current linear velocity threshold for freezing object simulation. An object stops to be updated if its linear velocity remains lower than this threshold during the number of Frozen frames (together with angular one).

Return value

"Freeze" linear velocity.

void setGravity(const Math::vec3 & gravity)

Updates the current gravity value.

Arguments

const Math::vec3 & gravity - New gravity.

Math::vec3 getGravity()

Returns the current gravity value.

Return value

Gravity.

void setIFps(float ifps)

Updates a frame duration. In fact, this function updates the FPS count used to calculate physics.

Arguments

float ifps - Frame duration (1/FPS).

float getIFps()

Returns a physics frame duration.

Return value

Frame duration (1 / FPS).

float getIntegrateTime()

Returns the duration of the integrate phase, in which physics simulation results are applied to bodies.

Return value

An integrate phase duration value, milliseconds.

Ptr<Object> getIntersection(const Math::Vec3 & p0, const Math::Vec3 & p1, int mask, const Vector< Ptr<Node> > & exclude, const Ptr<PhysicsIntersection> & intersection)

Performs tracing from the p0 point to the p1 point to find a collision object located on that line. If an object is assigned a body, intersection occurs with its shape. If an object has no body, this function detects intersection with surfaces (polygons) of objects with intersection flag set. Intersection is found only for objects with a matching mask if their ID is not found in the exclude list. Intersection is Intersection does not work for disabled objects.

Notice
						This function uses world space coordinates.
					

Arguments

const Math::Vec3 & p0 - Line start point coordinates.
const Math::Vec3 & p1 - Line end point coordinates.
int mask - Intersection mask. If 0 is passed, the function will return NULL.
const Vector< Ptr<Node> > & exclude - Array of nodes to be excluded.
const Ptr<PhysicsIntersection> & intersection - PhysicsIntersection class instance containing intersection data.

Return value

The first intersected object, if found; otherwise, 0.

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

Notice
						This function uses world space coordinates.
					

Arguments

const Math::Vec3 & p0 - Line start point coordinates.
const Math::Vec3 & p1 - Line end point coordinates.
int mask - Intersection mask. If 0 is passed, the function will return NULL.
const Ptr<PhysicsIntersection> & intersection - PhysicsIntersection class instance containing intersection data.

Return value

The first intersected object, if found; otherwise, 0.

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

Notice
						This function uses world space coordinates.
					

Arguments

const Math::Vec3 & p0 - Line start point coordinates.
const Math::Vec3 & p1 - Line end point coordinates.
int mask - Intersection mask. If 0 is passed, the function will return NULL.
const Ptr<PhysicsIntersectionNormal> & intersection - PhysicsIntersectionNormal class instance containing intersection data.

Return value

The first intersected object, if found; otherwise, 0.

Ptr<Object> getIntersection(const Math::Vec3 & p0, const Math::Vec3 & p1, int mask, const Vector< Ptr<Node> > & exclude, const Ptr<PhysicsIntersectionNormal> & intersection)

Notice
						This function uses world space coordinates.
					

Arguments

const Math::Vec3 & p0 - Line start point coordinates.
const Math::Vec3 & p1 - Line end point coordinates.
int mask - Intersection mask. If 0 is passed, the function will return NULL.
const Vector< Ptr<Node> > & exclude - Array of nodes to be excluded.
const Ptr<PhysicsIntersectionNormal> & intersection - PhysicsIntersectionNormal class instance containing intersection data.

Return value

The first intersected object, if found; otherwise, 0.

Ptr<Joint> getJoint(int id)

Returns a joint with a given ID.

Arguments

int id - Joint ID.

Return value

Joint with a given ID or NULL (0), if there is no joint with a given ID.

int isJoint(int id)

Checks if a joint with a given ID exists.

Arguments

int id - Joint ID.

Return value

1 if a joint with a given ID exists; otherwise, 0.

void setLinearDamping(float damping)

Updates the current linear damping value.

Arguments

float damping - New linear damping. If a negative value is provided, 0 will be used instead.

float getLinearDamping()

Returns the current linear damping value.

Return value

Linear damping.

void setMaxAngularVelocity(float velocity)

Updates the maximum possible angular velocity.

Arguments

float velocity - New maximum velocity value. If a negative value is provided, 0 will be used instead.

float getMaxAngularVelocity()

Returns the current maximum possible angular velocity.

Return value

Maximum possible angular velocity.

void setMaxLinearVelocity(float velocity)

Updates the maximum possible linear velocity.

Arguments

float velocity - New maximum velocity value. If a negative value is provided, 0 will be used instead.

float getMaxLinearVelocity()

Returns the current maximum possible linear velocity.

Return value

Maximum possible linear velocity.

float getNarrowTime()

Returns the duration of the narrow phase, during which exact collision tests are performed.

Return value

The narrow phase duration value, milliseconds.

int getNumBodies()

Returns the number of bodies present within the physics radius.

Return value

The number of bodies.

int getNumContacts()

Returns the number of contacts within the physics radius; it includes contacts between the bodies (their shapes) and body-mesh contacts.

Return value

The number of contacts.

void setNumFrozenFrames(int frames)

Updates the number of frames, during which an object should keep certain angular and linear velocities to become frozen.

Arguments

int frames - Number of frames. If a non-positive value is provided, 1 will be used instead.

int getNumFrozenFrames()

Returns the current number of frames, during which an object should keep certain angular and linear velocities to become frozen.

Return value

Number of frames.

int getNumIslands()

Returns the number of physical islands within the physics radius that could be calculated separately. The lower this number, the less efficient multi-threading is, if enabled.

Return value

The number of physical islands.

void setNumIterations(int iterations)

Updates the number of iterations used to solve contacts and constraints. Note that if this value is too low, the precision of calculations will suffer.

Arguments

int iterations - New number of iterations. If a non-positive value is provided, 1 will be used instead.

int getNumIterations()

Returns the current number of iterations used to solve contacts and constraints.

Return value

Current number of iterations.

int getNumJoints()

Returns the number of joints within the physics radius.

Return value

The number of joints.

void setPenetrationFactor(float factor)

Updates the current penalty force factor.

Arguments

float factor - New penetration factor. 0 means no penalty force in contacts. The provided value is saturated in the range [0; 1].

float getPenetrationFactor()

Returns a penalty force factor. 0 means no penalty force in contacts. The maximum value is 1.

Return value

Current penetration factor.

void setPenetrationTolerance(float tolerance)

Updates the current penetration tolerance.

Arguments

float tolerance - New penetration tolerance. If a negative value is provided, 0 will be used instead, however, this value should be greater than 0 for stable simulation.

float getPenetrationTolerance()

Returns a value indicating how deeply one object can penetrate another.

Return value

Current penetration tolerance.

float getResponseTime()

Returns the duration value of the response phase, in which collision response is calculated and joints are solved.

Return value

A response phase duration value, milliseconds.

void setScale(float scale)

Updates a value that is used to scale a frame duration. The provided value is saturated in the range [0;16].

Arguments

float scale - Scaling factor.

float getScale()

Returns a value used to scale a frame duration.

Return value

Value to scale the frame duration.

Ptr<Shape> getShape(int id)

Returns a shape with a given ID.

Arguments

int id - Shape ID.

Return value

Shape with a given ID or NULL (0), if there is no shape with a given ID.

int isShape(int id)

Checks if a shape with a given ID exists

Arguments

int id - Shape ID.

Return value

1 if a shape with a given ID exists; otherwise, 0.

float getSimulationTime()

Returns the duration of all of the simulation phases added together.

Return value

A simulation phases duration value, milliseconds.

void setStable(int stable)

Sets a value indicating if objects are updated in a definite order or not.

Arguments

int stable - 1 to indicate that the objects are updated in a definite order; 0 to indicate that the update order may change.

int isStable()

Returns a value indicating if objects are updated in a definite order or not. The default is 0 (the update order may change).

Return value

Returns 1 if the objects are updated in a definite order; otherwise 0.

void setTime(float time)

Forces simulation of physics for a given time. It means, until the set time elapses, physics will be calculated each physics tick (frame) that occurs depending on physics frame rate. It allows to control the starting point for physics simulation.

Example code:

Source code (UnigineScript)

int init() {
//to prevent physics from being automatically calculated with each update, set one of the following:
engine.physics.setEnabled(0)
//or
engine.physics.setScale(0)
}

int update() {
//add the time elapsed from the last physics update to the next time count cycle:
engine.physics.setTime(engine.physics.getTime()+ifps));
}

In the example, ifps is the time between frames of the renderer.

Arguments

float time - Time to continue updating physics in seconds.

float getTime()

Returns the current time that can be used when shifting between physics update frames.

Return value

Time in seconds.

float getTotalTime()

Returns the total time that both rendering and calculating of the frame took (the duration of the main loop in the application execution sequence).

Return value

The total time value, milliseconds.

float getUpdateTime()

Returns the duration of the update phase, during which the objects are prepared for their collision response to be calculated.

Return value

The update phase duration value, milliseconds.

void addUpdateNode(const Ptr<Node> & node)

Adds the node for which physical state should be updated. If a node is not added with this function, it won't be updated when out of physics simulation distance.

Arguments

const Ptr<Node> & node - Node to be updated.

void addUpdateNodes(const Vector< Ptr<Node> > & nodes)

Adds the nodes for which physical state should be updated. If nodes are not added with this function, they won't be updated when out of physics simulation distance.

Arguments

const Vector< Ptr<Node> > & nodes - Nodes to be updated.

int loadSettings(const char * name)

Loads the physics settings from a given file.

Arguments

const char * name - Path to an xml file with desired settings.

Return value

Returns 1 if the settings are loaded successfully; otherwise, 0.

int loadWorld(const Ptr<Xml> & xml)

Loads physics settings from the Xml.

Arguments

const Ptr<Xml> & xml - Xml smart pointer.

Return value

Returns 1 if settings are loaded successfully; otherwise, 0.

int removeScene(int id)

Removes the previously saved physics scene.

Arguments

int id - Buffer ID.

Return value

Returns 1 if the scene is removed successfully; otherwise, 0.

int restoreScene(int id)

Restores the previously saved physics scene from the buffer.

Arguments

int id - Buffer ID.

Return value

Returns 1 if the scene is restored successfully; otherwise, 0.

int restoreState(const Ptr<Stream> & stream)

Restores physics settings from the stream.

Warning

This function is deprecated and will be removed in the next release.

Arguments

const Ptr<Stream> & stream - Stream smart pointer.

Return value

Returns 1 if settings are restored successfully; otherwise, 0.

int saveScene()

Saves the current physics scene (physical properties of all objects) into the buffer.

Return value

Scene buffer ID.

int saveSettings(const char * name, int force = 0)

Saves the current physics settings to a given file.

Arguments

const char * name - Path to an xml file to which the settings will be saved.
int force - Forced saving of physics settings.

Return value

Returns 1 if the settings are saved successfully; otherwise, 0.

int saveState(const Ptr<Stream> & stream)

Saves physics settings into the stream.

Warning

This function is deprecated and will be removed in the next release.

Arguments

const Ptr<Stream> & stream - Stream smart pointer.

Return value

Returns 1 if settings are saved successfully; otherwise, 0.

int saveWorld(const Ptr<Xml> & xml, int force = 0)

Saves physics settings into the Xml.

Arguments

const Ptr<Xml> & xml - Xml smart pointer.
int force - Forced saving of physics settings.

Return value

Returns 1 if settings are saved successfully; otherwise, 0.

Last update: 2017-07-03

Help improve this article

Was this article helpful?

Report a problem related to this article

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