Custom Geometry

Introduction

This section describes how to use PhysX’s Custom Geometry feature.

The purpose of the Custom Geometry feature is to allow the creation of application specific collision geometries (e.g. a voxel map) that can seamlessly interact with the PhysX’s built-in geometry types. Any custom geometry is represented by the PxCustomGeometry class in the PhysX SDK. The constructor of the class expects a reference to an object implementing the PxCustomGeometry::Callbacks virtual interface.

This is how an example of a custom geometry usage could look like:

gVoxelMap = gPhysics->createRigidStatic(PxTransform(PxIdentity));
gVoxelMapCallbacks = new VoxelMapCallbacks();
gVoxelMapGeometry = PxCustomGeometry(*gVoxelMapCallbacks);
PxRigidActorExt::createExclusiveShape(*gVoxelMap, gVoxelMapGeometry, *gDefaultMaterial);
gScene->addActor(*gVoxelMap);

Every custom geometry type needs to implement all or some functions of the callbacks interface in order to enable the functionality required for the application.

Note: Custom geometry only stores a reference to the callback object; multiple custom geometries can maintain a reference to the same callback object; managing a callback object’s lifetime is the user’s responsibility.

Custom Geometry Callbacks

A custom callbacks class inherited from the PxCustomGeometry::Callbacks interface will need to implement 9 virtual functions, serving to provide following functionality:

Custom Type

PhysX doesn’t use Custom Geometry’s Custom Type, but it may be useful for users to identify a custom geometry object if they have more than one type of custom geometry in their application. The function PxCustomGeometry::Callbacks::getCustomType() returns a custom type unique to each implementation. The custom type is set using the macros DECLARE_CUSTOM_GEOMETRY_TYPE and IMPLEMENT_CUSTOM_GEOMETRY_TYPE.

// VoxelMap.h

struct VoxelMapCallbacks : PxCustomGeometry::Callbacks
{
    DECLARE_CUSTOM_GEOMETRY_TYPE
    ...
};

// VoxelMap.cpp

#include "VoxelMap.h"

IMPLEMENT_CUSTOM_GEOMETRY_TYPE(VoxelMapCallbacks)

...

// Test if custom geometry is a voxel map
if (gCustomGeometry.getCustomType() != VoxelMapCallbacks::TYPE())
    return false;

Collision Detection

To enable collision detection for a custom geometry, the following virtual functions need to be implemented:

PxBounds3 PxCustomGeometry::Callbacks::getLocalBounds(const PxGeometry& geometry) const;

PxCustomGeometry::Callbacks::getLocalBounds() is used to determine overlapping bounds in BroadPhase.

bool PxCustomGeometry::Callbacks::generateContacts(const PxGeometry& geom0, const PxGeometry& geom1,
        const PxTransform& pose0, const PxTransform& pose1,
        const PxReal contactDistance, const PxReal meshContactMargin, const PxReal toleranceLength,
        PxContactBuffer& contactBuffer) const;

PxCustomGeometry::Callbacks::generateContacts() is used for exact contact points computation in NarrowPhase.

bool PxCustomGeometry::Callbacks::usePersistentContactManifold(const PxGeometry& geometry,
        PxReal& breakingThreshold) const;

PxCustomGeometry::Callbacks::usePersistentContactManifold() should return true if the geometry has complex structure and may generate many (more than 32) contact points.

Note: Cutom Geometry is CPU-only yet, and thus can not interact with the GPU-only features like soft bodies or particles.

Scene Queries

These 4 functions will allow the geometry to participate in scene queries:

PxBounds3 PxCustomGeometry::Callbacks::getLocalBounds(const PxGeometry& geometry) const;

PxCustomGeometry::Callbacks::getLocalBounds() is used for preliminary testing.

PxU32 PxCustomGeometry::Callbacks::raycast(const PxVec3& origin, const PxVec3& unitDir,
        const PxGeometry& geom, const PxTransform& pose, PxReal maxDist, PxHitFlags hitFlags,
        PxU32 maxHits, PxGeomRaycastHit* rayHits, PxU32 stride,
        PxRaycastThreadContext* threadContext) const;

PxCustomGeometry::Callbacks::raycast() is used for raycast queries against the geometry.

bool PxCustomGeometry::Callbacks::overlap(const PxGeometry& geom0, const PxTransform& pose0,
        const PxGeometry& geom1, const PxTransform& pose1,
        PxOverlapThreadContext* threadContext) const;

PxCustomGeometry::Callbacks::overlap() is used for overlap queries against the geometry.

bool PxCustomGeometry::Callbacks::sweep(const PxVec3& unitDir, const PxReal maxDist,
        const PxGeometry& geom0, const PxTransform& pose0, const PxGeometry& geom1,
        const PxTransform& pose1, PxGeomSweepHit& sweepHit, PxHitFlags hitFlags,
        const PxReal inflation, PxSweepThreadContext* threadContext) const;

PxCustomGeometry::Callbacks::sweep() is used for sweep queries against the geometry.

Debug Visualization

Users can implement this function to have their custom geometry drawn in PhysX’s debug visualization.

void PxCustomGeometry::Callbacks::visualize(const PxGeometry& geometry, PxRenderOutput& out,
        const PxTransform& absPose, const PxBounds3& cullbox) const;

PxCustomGeometry::Callbacks::visualize() is used for debug visualization of the geometry.

Mass Properties Computation

To enable automatic dynamic rigid body mass computation.

void PxCustomGeometry::Callbacks::computeMassProperties(const PxGeometry& geometry,
        PxMassProperties& massProperties) const;

PxCustomGeometry::Callbacks::computeMassProperties() for the geometry that can be used with dynamic rigid bodies.

Extensions

PhysXExtensions module’s PxCustomGeometryExt API provides two pre-made custom geometry callbacks classes.

Pre-made callbacks classes