Geometry Queries

The chapter Scene Queries shows how to query a PhysX scene or rather its objects for raycast, sweep and overlap hits. However, sometimes the objects to query are known up front and only the hit location on the object surface, for example, is of interest. Sometimes those objects might not even be PhysX actors or shapes but simple geometric volumes like spheres or boxes. PhysX exposes an API for such basic query functionality through the PxGeometryQuery and PxMeshQuery interfaces.

Geometry Objects

In the following sections, the mentioned simple geometry objects will consist of two parts. One is a descriptor for the geometric shape, the other is a world transform to specify the position and rotation of the object. The former gets defined by the same class which is used for PxShape objects already, that is, PxGeometry. See Shapes and Geometries for more information on this class.


Four types of tests are offered for simple geometric volumes: raycast, sweep, and overlap tests, and penetration depth computation. Additionally, a function to compute the distance between a point and a geometry object has been added.

As an example, let us assume we are interested in knowing whether a given box hits a given sphere if the box moves a certain distance along a specified direction (and if the sphere does get hit, we would like to know the first point of contact on its surface). With the PxGeometryQuery API the code would look like this:

PxSweepHit hitInfo;
bool gotHit = PxGeometryQuery::sweep(unitDir, distance,
                                     boxGeom, boxPose,
                                     sphereGeom, spherePose,

The first two parameters of the provided method are the normalized direction and the distance of the movement. The third and fourth parameter describe the geometry object to sweep. In the example, this would be a PxBoxGeometry object and its world transform. The fifth and sixth parameter describe the geometry object to test against. This would be a PxSphereGeometry object together with its global pose, in our example. The last parameter in the code snippet will hold the hit information if the method returns true, i.e., if the box does hit the sphere on its motion path.

PxGeometryQuery::raycast(...) API function operates in one of 3 modes - returning multiple hits (if maxHits argument is > 1), returning the closest hit if maxHits = 1 and anyHit argument is false and returning any (first encountered) hit if 'anyHit' is set to true.

For limitations and detailed parameter descriptions please refer to the corresponding API documentation.


For triangle meshes and heightfields, additional functionality is provided to extract the triangles which lie inside a specified geometric volume. The following example code will show the API usage for a scenario, where the mesh triangles which lie within a given spherical volume should get detected:

PxU32 triangleIndexBuffer[bufferSize];
PxU32 startIndex = 0;
bool bufferOverflowOccured = false;
PxU32 nbTriangles = PxMeshQuery::findOverlapTriangleMesh(sphereGeom, spherePose,
                                                         meshGeom, meshPose,
                                                         triangleIndexBuffer, bufferSize,
                                                         startIndex, bufferOverflowOccured);

for(PxU32 i=0; i < nbTriangles; i++)
        PxTriangle tri;
        PxU32 vertexIndices[3];
        PxMeshQuery::getTriangle(meshGeom, meshPose, triangleIndexBuffer[i], tri, vertexIndices);

        ...  // process triangle info

The findOverlapTriangleMesh method is used to extract the indices of the triangles. The first two parameters describe the geometry object which defines the volume to look for triangles in. In the given scenario, this would be a PxSphereGeometry object and its world transform. The next two parameters specify the mesh/heightfield to test against. This would be a PxTriangleMeshGeometry object and its global pose, in this example. The fifth parameter is a user buffer to store the indices of the found triangles to, followed by a parameter holding the maximum size of this buffer. The second to last parameter can be used together with the last parameter to handle cases where the provided buffer was not large enough to store all the found triangle indices. The last parameter is a boolean which gets set to true if not all triangle indices could get stored. In that case, the method can get called once again setting the second to last parameter (startIndex) to the number of triangle indices extracted so far such that the next block of triangle indices which did not fit into the user buffer can get fetched. The following loop in the sample code then iterates over the found triangle indices and uses the getTriangle interface to translate an index to a triangle and optionally triangle vertex indices.

More in-depth information about the interface is provided in the API documentation.

Table Of Contents

Previous topic

Scene Queries

Next topic

Callbacks and Customization