qphysicsworld.cpp File Reference

(8873fe54156c641f57aa50ace88f14779bd929da)

#include "qphysicsworld_p.h"
#include "physxnode/qabstractphysxnode_p.h"
#include "physxnode/qphysxworld_p.h"
#include "qabstractphysicsnode_p.h"
#include "qdebugdrawhelper_p.h"
#include "qphysicsutils_p.h"
#include "joints/qjoint_p.h"
#include "qstaticphysxobjects_p.h"
#include "qboxshape_p.h"
#include "qsphereshape_p.h"
#include "qconvexmeshshape_p.h"
#include "qtrianglemeshshape_p.h"
#include "qcharactercontroller_p.h"
#include "qcapsuleshape_p.h"
#include "qplaneshape_p.h"
#include "qheightfieldshape_p.h"
#include "qtriggerbody_p.h"
#include "PxPhysicsAPI.h"
#include "cooking/PxCooking.h"
#include <foundation/PxSimpleTypes.h>
#include <QtQuick/private/qquickframeanimation_p.h>
#include <QtQuick3D/private/qquick3dobject_p.h>
#include <QtQuick3D/private/qquick3dnode_p.h>
#include <QtQuick3D/private/qquick3dmodel_p.h>
#include <QtQuick3D/private/qquick3dprincipledmaterial_p.h>
#include <QtQuick3DUtils/private/qssgutils_p.h>
#include <QtCore/qvarlengtharray.h>
#include <QtGui/qquaternion.h>
#include <QtEnvironmentVariables>
#include "qphysicsworld.moc"

Include dependency graph for qphysicsworld.cpp:

Go to the source code of this file.

Classes
class	FrameAnimator
struct	QWorldManager

Functions
QT_BEGIN_NAMESPACE	Q_LOGGING_CATEGORY (lcQuick3dPhysics, "qt.quick3d.physics")
	\qmltype PhysicsWorld \inqmlmodule QtQuick3D.Physics
static bool	validateQuery (const physx::PxScene *scene, bool includeStatic, bool includeDynamic)
static bool	raycastImpl (const physx::PxScene *scene, const QVector3D &origin, const QVector3D &direction, float maxDistance, bool includeStatic, bool includeDynamic, physx::PxRaycastCallback &hitCallback, physx::PxHitFlags hitFlags, physx::PxQueryFlags extraQueryFlags={})
static const physx::PxGeometry *	validateQueryShape (const physx::PxScene *scene, QAbstractCollisionShape *shape, bool includeStatic, bool includeDynamic)
static bool	sweepImpl (const physx::PxScene *scene, QAbstractCollisionShape *shape, const QVector3D &direction, float maxDistance, bool includeStatic, bool includeDynamic, physx::PxSweepCallback &hitCallback, physx::PxHitFlags hitFlags, physx::PxQueryFlags extraQueryFlags={})
static bool	overlapImpl (const physx::PxScene *scene, QAbstractCollisionShape *shape, bool includeStatic, bool includeDynamic, physx::PxOverlapCallback &hitCallback, physx::PxQueryFlags extraQueryFlags={})
static void	collectPhysicsNodes (QQuick3DObject *node, QList< QAbstractPhysicsNode * > &nodes)

Variables
static const QString	qtPhysicsTimingsFile = qEnvironmentVariable("QT_PHYSICS_TIMINGS_FILE")
static QWorldManager	worldManager = QWorldManager {}

Function Documentation

collectPhysicsNodes()

void collectPhysicsNodes ( QQuick3DObject * node, QList< QAbstractPhysicsNode * > & nodes )

static

Definition at line 1483 of file qphysicsworld.cpp.

overlapImpl()

bool overlapImpl ( const physx::PxScene * scene, QAbstractCollisionShape * shape, bool includeStatic, bool includeDynamic, physx::PxOverlapCallback & hitCallback, physx::PxQueryFlags extraQueryFlags = {} )

static

Definition at line 724 of file qphysicsworld.cpp.

Q_LOGGING_CATEGORY()

QT_BEGIN_NAMESPACE Q_LOGGING_CATEGORY	(	lcQuick3dPhysics	,
		"qt.quick3d.physics"	)

\qmltype PhysicsWorld \inqmlmodule QtQuick3D.Physics

Since

6.4

Controls the physics simulation.

The PhysicsWorld type controls the physics simulation. This node is used to create an instance of the physics world as well as define its properties. There can only be one physics world. All collision nodes in the qml will get added automatically to the physics world.

\qmlproperty vector3d PhysicsWorld::gravity This property defines the gravity vector of the physics world. The default value is (0, -981, 0). Set the value to {Qt.vector3d(0, -9.81, 0)} if your unit of measurement is meters and you are simulating Earth gravity.

\qmlproperty bool PhysicsWorld::running This property starts or stops the physical simulation. The default value is true.

\qmlproperty bool PhysicsWorld::forceDebugDraw This property enables debug drawing of all active shapes in the physics world. The default value is false.

\qmlproperty bool PhysicsWorld::enableCCD

Deprecated

[6.13] Use DynamicRigidBody::ccd instead.

This property enables continuous collision detection globally for every dynamic body in the scene that does not explicitly set its own \l DynamicRigidBody::ccd mode. It reduces the risk of fast-moving bodies passing through geometry at high velocities (also known as tunnelling).

For non-kinematic dynamic bodies, enabling this property uses sweep-based CCD. For kinematic bodies, it automatically uses speculative CCD, as sweep-based CCD is not supported for them.

Continuous collision detection can also be configured per body via \l DynamicRigidBody::ccd, which avoids paying its performance cost for objects that do not need it.

Warning

Using trigger bodies with CCD enabled is not supported and can result in missing or false trigger reports.

\default false

See also

DynamicRigidBody::ccd

\qmlproperty real PhysicsWorld::typicalLength This property defines the approximate size of objects in the simulation. This is used to estimate certain length-related tolerances. Objects much smaller or much larger than this size may not behave properly. The default value is 100.

Range: {[0, inf]}

\qmlproperty real PhysicsWorld::typicalSpeed This property defines the typical magnitude of velocities of objects in simulation. This is used to estimate whether a contact should be treated as bouncing or resting based on its impact velocity, and a kinetic energy threshold below which the simulation may put objects to sleep.

For normal physical environments, a good choice is the approximate speed of an object falling under gravity for one second. The default value is 1000.

Range: {[0, inf]}

\qmlproperty real PhysicsWorld::defaultDensity This property defines the default density of dynamic objects, measured in kilograms per cubic unit. This is equal to the weight of a cube with side 1.

The default value is 0.001, corresponding to 1 g/cm³: the density of water. If your unit of measurement is meters, a good value would be 1000. Note that only positive values are allowed.

Range: {(0, inf]}

\qmlproperty Node PhysicsWorld::viewport This property defines the viewport where debug components will be drawn if \l{forceDebugDraw} is enabled. If unset the \l{scene} node will be used.

See also

forceDebugDraw, scene

\qmlproperty real PhysicsWorld::minimumTimestep This property defines the minimum simulation timestep in milliseconds. The default value is {1}.

Range: {[0, maximumTimestep]}

Note

The simulation timestep works in lockstep with the rendering, meaning a new simulation frame will only be started after a rendered frame has completed. This means that at most one simulation frame will run per rendered frame.

\qmlproperty real PhysicsWorld::maximumTimestep This property defines the maximum simulation timestep in milliseconds. The default value is {33.333}.

Range: {[0, inf]}

Note

The simulation timestep works in lockstep with the rendering, meaning a new simulation frame will only be started after a rendered frame has completed. This means that at most one simulation frame will run per rendered frame.

\qmlproperty Node PhysicsWorld::scene

This property defines the top-most Node that contains all the nodes of the physical simulation. All physics objects that are an ancestor of this node will be seen as part of this PhysicsWorld.

Note

Using the same scene node for several PhysicsWorld is unsupported.

\qmlsignal PhysicsWorld::frameDone(float timestep)

Since

6.5

This signal is emitted when the physical simulation is done simulating a frame. The timestep parameter is how long in milliseconds the timestep was in the simulation.

\qmlproperty int PhysicsWorld::numThreads

Since

6.7

This property defines the number of threads used for the physical simulation. This is how the range of values are interpreted:

\table \header

• Value
• Range
• Description \row
• Negative
• {[-inf, -1]}
• Automatic thread count. The application will try to query the number of threads from the system. \row
• Zero
• {{0}}
• No threading, simulation will run sequentially. \row
• Positive
• {[1, 256]}
• Specific thread count. Values above 256 are clamped. \endtable

The default value is {-1}, meaning automatic thread count.

Note

Once the scene has started running it is not possible to change the number of threads.

\qmlproperty bool PhysicsWorld::reportKinematicKinematicCollisions

Since

6.7

This property controls if collisions between pairs of {kinematic} dynamic rigid bodies will trigger a contact report.

The default value is {false}.

Note

Once the scene has started running it is not possible to change this setting.

See also

PhysicsWorld::reportStaticKinematicCollisions

DynamicRigidBody

PhysicsNode::bodyContact

\qmlproperty bool PhysicsWorld::reportStaticKinematicCollisions

Since

6.7

This property controls if collisions between a static rigid body and a {kinematic} dynamic rigid body will trigger a contact report.

The default value is {false}.

Note

Once the scene has started running it is not possible to change this setting.

See also

PhysicsWorld::reportKinematicKinematicCollisions

StaticRigidBody

DynamicRigidBody

PhysicsNode::bodyContact

\qmlproperty QueryStructure PhysicsWorld::staticQueryStructure

Since

6.13

The spatial pruning structure type used to accelerate scene queries (raycasts, sweeps, overlaps - used in CharacterController and a {kinematic} dynamic rigid body) against static actors in the physics scene. It has no effect on rigid-body contact/collision detection during simulation.

The following values are available:

\value PhysicsWorld.StaticTree Uses a pre-baked static AABB tree. Offers maximum scene query performance with zero per-frame management overhead. Best for fully static, immutable scenes. Inserting or removing objects at runtime causes heavy scene rebuilds and frame spikes. \value PhysicsWorld.DynamicTree Uses a dynamic self-balancing AABB tree. Allows fast, local runtime insertion (logarithmic time) and removal of static objects without freezing the frame. Ideal for seamless open-world streaming where static chunks are loaded dynamically.

\default PhysicsWorld.DynamicTree

Note

Once the scene has started running it is not possible to change this setting.

PhysicsWorld.NoStructure is not supported for staticQueryStructure

See also

PhysicsWorld::dynamicQueryStructure

\qmlproperty QueryStructure PhysicsWorld::dynamicQueryStructure

Since

6.13

The spatial pruning structure type used to accelerate scene queries (raycasts, sweeps, overlaps - used in CharacterController and a {kinematic} dynamic rigid body) against dynamic actors in the physics scene. It has no effect on rigid-body contact/collision detection during simulation.

The following values are available:

\value PhysicsWorld.NoStructure Disables the scene query acceleration structure for dynamic actors. Eliminates CPU overhead for tree maintenance when objects move, spawn, or are destroyed. Scene queries will fall back to a linear search. Ideal when scene queries are not needed for dynamic objects. \value PhysicsWorld.StaticTree Uses a static AABB tree. Offers faster scene queries for dynamic actors, but updating the tree when objects move or spawn is very expensive. Best when dynamic actors rarely move or spend most of their time sleeping. \value PhysicsWorld.DynamicTree Uses a dynamic self-balancing AABB tree. Allows fast, local runtime insertion (logarithmic time), movement, and removal of dynamic objects without freezing the frame. Ideal for active scenes with frequently moving or spawning dynamic actors.

\default PhysicsWorld.DynamicTree

Note

Once the scene has started running it is not possible to change this setting.

See also

PhysicsWorld::staticQueryStructure

\qmlmethod bool PhysicsWorld::testRaycastQuery(vector3d origin, vector3d direction, real maxDistance, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Performs a fast occlusion check along a ray without computing precise hit geometry or returning hit data.

Returns true if the ray hits a body within maxDistance; otherwise returns false. The query stops at the first body it finds, which makes it the cheapest of the raycast queries.

\list

• origin is the starting position of the ray, in world space.
• direction is the direction of the ray. It must not be a null vector and does not need to be normalized; the query normalizes it.
• maxDistance is the maximum distance along direction to cast the ray. It must be greater than 0.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

include_flags

query_exclusions

mesh_raycast_limits

See also

singleRaycastQuery, multiRaycastQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod locationHit PhysicsWorld::singleRaycastQuery(vector3d origin, vector3d direction, real maxDistance, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Casts a ray through the physics scene and returns the closest body it hits.

The ray starts at origin and extends along direction up to maxDistance. Returns a \l locationHit describing the closest intersection.

\list

• origin is the starting position of the ray, in world space.
• direction is the direction of the ray. It must not be a null vector and does not need to be normalized; the query normalizes it.
• maxDistance is the maximum distance along direction to cast the ray. It must be greater than 0.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

include_flags

hit_miss_return

query_exclusions

mesh_raycast_limits

See also

testRaycastQuery, multiRaycastQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod list<locationHit> PhysicsWorld::multiRaycastQuery(vector3d origin, vector3d direction, real maxDistance, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Casts a ray through the physics scene and returns every body it passes through, rather than stopping at the closest one.

The ray starts at origin and extends along direction up to maxDistance. Returns a \l locationHit for each body hit, or an empty list if the ray hits nothing.

\list

• origin is the starting position of the ray, in world space.
• direction is the direction of the ray. It must not be a null vector and does not need to be normalized; the query normalizes it.
• maxDistance is the maximum distance along direction to cast the ray. It must be greater than 0.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

include_flags

query_exclusions

mesh_raycast_limits

mesh_multi_intersection

unordered_hits_note

See also

testRaycastQuery, singleRaycastQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod bool PhysicsWorld::testSweepQuery(CollisionShape shape, vector3d direction, real maxDistance, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Sweeps a collision shape along a straight path and reports whether the path is obstructed, without computing precise hit geometry.

Returns true if shape hits a body before travelling maxDistance; otherwise returns false. The query stops at the first body it finds, which makes it the cheapest of the sweep queries.

\list

• shape is the \l CollisionShape to sweep through the scene.
• direction is the direction of the sweep. It must not be a null vector and does not need to be normalized; the query normalizes it.
• maxDistance is the maximum distance along direction to travel. It must be greater than 0.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

query_shape

include_flags

query_exclusions

See also

singleSweepQuery, multiSweepQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod locationHit PhysicsWorld::singleSweepQuery(CollisionShape shape, vector3d direction, real maxDistance, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Sweeps a collision shape along a straight path and returns the closest body it hits.

Returns a \l locationHit describing the closest intersection encountered along the sweep.

\list

• shape is the \l CollisionShape to sweep through the scene.
• direction is the direction of the sweep. It must not be a null vector and does not need to be normalized; the query normalizes it.
• maxDistance is the maximum distance along direction to travel. It must be greater than 0.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

query_shape

include_flags

hit_miss_return

query_exclusions

mtd_overlap_note

See also

testSweepQuery, multiSweepQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod list<locationHit> PhysicsWorld::multiSweepQuery(CollisionShape shape, vector3d direction, real maxDistance, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Sweeps a collision shape along a straight path and returns every body it passes through, rather than stopping at the closest one.

Returns a \l locationHit for each body hit, or an empty list if the sweep hits nothing.

\list

• shape is the \l CollisionShape to sweep through the scene.
• direction is the direction of the sweep. It must not be a null vector and does not need to be normalized; the query normalizes it.
• maxDistance is the maximum distance along direction to travel. It must be greater than 0.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

query_shape

include_flags

query_exclusions

mesh_multi_intersection

unordered_hits_note

mtd_overlap_note

See also

testSweepQuery, singleSweepQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod bool PhysicsWorld::testOverlapQuery(CollisionShape shape, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Reports whether any body occupies the volume of a stationary collision shape.

Returns true if shape overlaps a body; otherwise returns false. The query stops at the first body it finds and builds no hit data, which makes it the cheapest of the overlap queries.

\list

• shape is the \l CollisionShape defining the overlap volume.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

query_shape

include_flags

query_exclusions

See also

multiOverlapQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod list<queryHit> PhysicsWorld::multiOverlapQuery(CollisionShape shape, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Returns every body that overlaps the volume of a stationary collision shape.

Returns a \l queryHit for each overlapping body, or an empty list if the volume is unoccupied.

\list

• shape is the \l CollisionShape defining the overlap volume.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

query_shape

include_flags

query_exclusions

mesh_multi_intersection

unordered_hits_note

See also

testOverlapQuery, {Qt Quick 3D Physics Scene Queries}

Since

6.4

Controls the physics simulation.

The PhysicsWorld type controls the physics simulation. This node is used to create an instance of the physics world as well as define its properties. There can only be one physics world. All collision nodes in the qml will get added automatically to the physics world.

\qmlproperty vector3d PhysicsWorld::gravity This property defines the gravity vector of the physics world. The default value is (0, -981, 0). Set the value to {Qt.vector3d(0, -9.81, 0)} if your unit of measurement is meters and you are simulating Earth gravity.

\qmlproperty bool PhysicsWorld::running This property starts or stops the physical simulation. The default value is true.

\qmlproperty bool PhysicsWorld::forceDebugDraw This property enables debug drawing of all active shapes in the physics world. The default value is false.

\qmlproperty bool PhysicsWorld::enableCCD

Deprecated

[6.13] Use DynamicRigidBody::ccd instead.

This property enables continuous collision detection globally for every dynamic body in the scene that does not explicitly set its own \l DynamicRigidBody::ccd mode. It reduces the risk of fast-moving bodies passing through geometry at high velocities (also known as tunnelling).

For non-kinematic dynamic bodies, enabling this property uses sweep-based CCD. For kinematic bodies, it automatically uses speculative CCD, as sweep-based CCD is not supported for them.

Continuous collision detection can also be configured per body via \l DynamicRigidBody::ccd, which avoids paying its performance cost for objects that do not need it.

Warning

Using trigger bodies with CCD enabled is not supported and can result in missing or false trigger reports.

\default false

See also

DynamicRigidBody::ccd

\qmlproperty real PhysicsWorld::typicalLength This property defines the approximate size of objects in the simulation. This is used to estimate certain length-related tolerances. Objects much smaller or much larger than this size may not behave properly. The default value is 100.

Range: {[0, inf]}

\qmlproperty real PhysicsWorld::typicalSpeed This property defines the typical magnitude of velocities of objects in simulation. This is used to estimate whether a contact should be treated as bouncing or resting based on its impact velocity, and a kinetic energy threshold below which the simulation may put objects to sleep.

For normal physical environments, a good choice is the approximate speed of an object falling under gravity for one second. The default value is 1000.

Range: {[0, inf]}

\qmlproperty real PhysicsWorld::defaultDensity This property defines the default density of dynamic objects, measured in kilograms per cubic unit. This is equal to the weight of a cube with side 1.

The default value is 0.001, corresponding to 1 g/cm³: the density of water. If your unit of measurement is meters, a good value would be 1000. Note that only positive values are allowed.

Range: {(0, inf]}

\qmlproperty Node PhysicsWorld::viewport This property defines the viewport where debug components will be drawn if \l{forceDebugDraw} is enabled. If unset the \l{scene} node will be used.

See also

forceDebugDraw, scene

\qmlproperty real PhysicsWorld::minimumTimestep This property defines the minimum simulation timestep in milliseconds. The default value is {1}.

Range: {[0, maximumTimestep]}

Note

The simulation timestep works in lockstep with the rendering, meaning a new simulation frame will only be started after a rendered frame has completed. This means that at most one simulation frame will run per rendered frame.

\qmlproperty real PhysicsWorld::maximumTimestep This property defines the maximum simulation timestep in milliseconds. The default value is {33.333}.

Range: {[0, inf]}

Note

The simulation timestep works in lockstep with the rendering, meaning a new simulation frame will only be started after a rendered frame has completed. This means that at most one simulation frame will run per rendered frame.

\qmlproperty Node PhysicsWorld::scene

This property defines the top-most Node that contains all the nodes of the physical simulation. All physics objects that are an ancestor of this node will be seen as part of this PhysicsWorld.

Note

Using the same scene node for several PhysicsWorld is unsupported.

\qmlsignal PhysicsWorld::frameDone(float timestep)

Since

6.5

This signal is emitted when the physical simulation is done simulating a frame. The timestep parameter is how long in milliseconds the timestep was in the simulation.

\qmlproperty int PhysicsWorld::numThreads

Since

6.7

This property defines the number of threads used for the physical simulation. This is how the range of values are interpreted:

\table \header

• Value
• Range
• Description \row
• Negative
• {[-inf, -1]}
• Automatic thread count. The application will try to query the number of threads from the system. \row
• Zero
• {{0}}
• No threading, simulation will run sequentially. \row
• Positive
• {[1, 256]}
• Specific thread count. Values above 256 are clamped. \endtable

The default value is {-1}, meaning automatic thread count.

Note

Once the scene has started running it is not possible to change the number of threads.

\qmlproperty bool PhysicsWorld::reportKinematicKinematicCollisions

Since

6.7

This property controls if collisions between pairs of {kinematic} dynamic rigid bodies will trigger a contact report.

The default value is {false}.

Note

Once the scene has started running it is not possible to change this setting.

See also

PhysicsWorld::reportStaticKinematicCollisions

DynamicRigidBody

PhysicsNode::bodyContact

\qmlproperty bool PhysicsWorld::reportStaticKinematicCollisions

Since

6.7

This property controls if collisions between a static rigid body and a {kinematic} dynamic rigid body will trigger a contact report.

The default value is {false}.

Note

Once the scene has started running it is not possible to change this setting.

See also

PhysicsWorld::reportKinematicKinematicCollisions

StaticRigidBody

DynamicRigidBody

PhysicsNode::bodyContact

\qmlproperty QueryStructure PhysicsWorld::staticQueryStructure

Since

6.13

The spatial pruning structure type used to accelerate scene queries (raycasts, sweeps, overlaps - used in CharacterController and a {kinematic} dynamic rigid body) against static actors in the physics scene. It has no effect on rigid-body contact/collision detection during simulation.

The following values are available:

\value PhysicsWorld.StaticTree Uses a pre-baked static AABB tree. Offers maximum scene query performance with zero per-frame management overhead. Best for fully static, immutable scenes. Inserting or removing objects at runtime causes heavy scene rebuilds and frame spikes. \value PhysicsWorld.DynamicTree Uses a dynamic self-balancing AABB tree. Allows fast, local runtime insertion (logarithmic time) and removal of static objects without freezing the frame. Ideal for seamless open-world streaming where static chunks are loaded dynamically.

\default PhysicsWorld.DynamicTree

Note

Once the scene has started running it is not possible to change this setting.

PhysicsWorld.NoStructure is not supported for staticQueryStructure

See also

PhysicsWorld::dynamicQueryStructure

\qmlproperty QueryStructure PhysicsWorld::dynamicQueryStructure

Since

6.13

The spatial pruning structure type used to accelerate scene queries (raycasts, sweeps, overlaps - used in CharacterController and a {kinematic} dynamic rigid body) against dynamic actors in the physics scene. It has no effect on rigid-body contact/collision detection during simulation.

The following values are available:

\value PhysicsWorld.NoStructure Disables the scene query acceleration structure for dynamic actors. Eliminates CPU overhead for tree maintenance when objects move, spawn, or are destroyed. Scene queries will fall back to a linear search. Ideal when scene queries are not needed for dynamic objects. \value PhysicsWorld.StaticTree Uses a static AABB tree. Offers faster scene queries for dynamic actors, but updating the tree when objects move or spawn is very expensive. Best when dynamic actors rarely move or spend most of their time sleeping. \value PhysicsWorld.DynamicTree Uses a dynamic self-balancing AABB tree. Allows fast, local runtime insertion (logarithmic time), movement, and removal of dynamic objects without freezing the frame. Ideal for active scenes with frequently moving or spawning dynamic actors.

\default PhysicsWorld.DynamicTree

Note

Once the scene has started running it is not possible to change this setting.

See also

PhysicsWorld::staticQueryStructure

\qmlmethod bool PhysicsWorld::testRaycastQuery(vector3d origin, vector3d direction, real maxDistance, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Performs a fast occlusion check along a ray without computing precise hit geometry or returning hit data.

Returns true if the ray hits a body within maxDistance; otherwise returns false. The query stops at the first body it finds, which makes it the cheapest of the raycast queries.

\list

• origin is the starting position of the ray, in world space.
• direction is the direction of the ray. It must not be a null vector and does not need to be normalized; the query normalizes it.
• maxDistance is the maximum distance along direction to cast the ray. It must be greater than 0.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

include_flags

query_exclusions

mesh_raycast_limits

See also

singleRaycastQuery, multiRaycastQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod locationHit PhysicsWorld::singleRaycastQuery(vector3d origin, vector3d direction, real maxDistance, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Casts a ray through the physics scene and returns the closest body it hits.

The ray starts at origin and extends along direction up to maxDistance. Returns a \l locationHit describing the closest intersection.

\list

• origin is the starting position of the ray, in world space.
• direction is the direction of the ray. It must not be a null vector and does not need to be normalized; the query normalizes it.
• maxDistance is the maximum distance along direction to cast the ray. It must be greater than 0.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

include_flags

hit_miss_return

query_exclusions

mesh_raycast_limits

See also

testRaycastQuery, multiRaycastQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod list<locationHit> PhysicsWorld::multiRaycastQuery(vector3d origin, vector3d direction, real maxDistance, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Casts a ray through the physics scene and returns every body it passes through, rather than stopping at the closest one.

The ray starts at origin and extends along direction up to maxDistance. Returns a \l locationHit for each body hit, or an empty list if the ray hits nothing.

\list

• origin is the starting position of the ray, in world space.
• direction is the direction of the ray. It must not be a null vector and does not need to be normalized; the query normalizes it.
• maxDistance is the maximum distance along direction to cast the ray. It must be greater than 0.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

include_flags

query_exclusions

mesh_raycast_limits

mesh_multi_intersection

unordered_hits_note

See also

testRaycastQuery, singleRaycastQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod bool PhysicsWorld::testSweepQuery(CollisionShape shape, vector3d direction, real maxDistance, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Sweeps a collision shape along a straight path and reports whether the path is obstructed, without computing precise hit geometry.

Returns true if shape hits a body before travelling maxDistance; otherwise returns false. The query stops at the first body it finds, which makes it the cheapest of the sweep queries.

\list

• shape is the \l CollisionShape to sweep through the scene.
• direction is the direction of the sweep. It must not be a null vector and does not need to be normalized; the query normalizes it.
• maxDistance is the maximum distance along direction to travel. It must be greater than 0.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

query_shape

include_flags

query_exclusions

See also

singleSweepQuery, multiSweepQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod locationHit PhysicsWorld::singleSweepQuery(CollisionShape shape, vector3d direction, real maxDistance, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Sweeps a collision shape along a straight path and returns the closest body it hits.

Returns a \l locationHit describing the closest intersection encountered along the sweep.

\list

• shape is the \l CollisionShape to sweep through the scene.
• direction is the direction of the sweep. It must not be a null vector and does not need to be normalized; the query normalizes it.
• maxDistance is the maximum distance along direction to travel. It must be greater than 0.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

query_shape

include_flags

hit_miss_return

query_exclusions

mtd_overlap_note

See also

testSweepQuery, multiSweepQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod list<locationHit> PhysicsWorld::multiSweepQuery(CollisionShape shape, vector3d direction, real maxDistance, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Sweeps a collision shape along a straight path and returns every body it passes through, rather than stopping at the closest one.

Returns a \l locationHit for each body hit, or an empty list if the sweep hits nothing.

\list

• shape is the \l CollisionShape to sweep through the scene.
• direction is the direction of the sweep. It must not be a null vector and does not need to be normalized; the query normalizes it.
• maxDistance is the maximum distance along direction to travel. It must be greater than 0.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

query_shape

include_flags

query_exclusions

mesh_multi_intersection

unordered_hits_note

mtd_overlap_note

See also

testSweepQuery, singleSweepQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod bool PhysicsWorld::testOverlapQuery(CollisionShape shape, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Reports whether any body occupies the volume of a stationary collision shape.

Returns true if shape overlaps a body; otherwise returns false. The query stops at the first body it finds and builds no hit data, which makes it the cheapest of the overlap queries.

\list

• shape is the \l CollisionShape defining the overlap volume.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

query_shape

include_flags

query_exclusions

See also

multiOverlapQuery, {Qt Quick 3D Physics Scene Queries}

\qmlmethod list<queryHit> PhysicsWorld::multiOverlapQuery(CollisionShape shape, bool includeStatic = true, bool includeDynamic = true)

Since

6.13

Returns every body that overlaps the volume of a stationary collision shape.

Returns a \l queryHit for each overlapping body, or an empty list if the volume is unoccupied.

\list

• shape is the \l CollisionShape defining the overlap volume.
• includeStatic includes static bodies in the query when true.
• includeDynamic includes dynamic bodies in the query when true. \endlist

query_shape

include_flags

query_exclusions

mesh_multi_intersection

unordered_hits_note

See also

testOverlapQuery, {Qt Quick 3D Physics Scene Queries}

raycastImpl()

bool raycastImpl ( const physx::PxScene * scene, const QVector3D & origin, const QVector3D & direction, float maxDistance, bool includeStatic, bool includeDynamic, physx::PxRaycastCallback & hitCallback, physx::PxHitFlags hitFlags, physx::PxQueryFlags extraQueryFlags = {} )

static

Definition at line 605 of file qphysicsworld.cpp.

sweepImpl()

bool sweepImpl ( const physx::PxScene * scene, QAbstractCollisionShape * shape, const QVector3D & direction, float maxDistance, bool includeStatic, bool includeDynamic, physx::PxSweepCallback & hitCallback, physx::PxHitFlags hitFlags, physx::PxQueryFlags extraQueryFlags = {} )

static

Definition at line 679 of file qphysicsworld.cpp.

validateQuery()

bool validateQuery ( const physx::PxScene * scene, bool includeStatic, bool includeDynamic )

static

Definition at line 586 of file qphysicsworld.cpp.

Referenced by validateQueryShape().

Here is the caller graph for this function:

validateQueryShape()

const physx::PxGeometry * validateQueryShape ( const physx::PxScene * scene, QAbstractCollisionShape * shape, bool includeStatic, bool includeDynamic )

static

Definition at line 647 of file qphysicsworld.cpp.

References validateQuery().

Here is the call graph for this function:

Variable Documentation

qtPhysicsTimingsFile

const QString qtPhysicsTimingsFile = qEnvironmentVariable("QT_PHYSICS_TIMINGS_FILE")

static

Definition at line 582 of file qphysicsworld.cpp.

worldManager

QWorldManager worldManager = QWorldManager {}

static

Definition at line 884 of file qphysicsworld.cpp.