Direct GPU API

Introduction

The direct GPU API provides a direct access to GPU data of a PhysX scene. The functions in this API enable batched direct access to GPU data for PxRigidDynamic, PxArticulationReducedCoordinate and PxShape objects. This allows interoperation with GPU post- and preprocessing to implement more efficient CPU-GPU data copying based on the specific needs of the application.

Using Direct GPU API

To use this API, PxSceneFlag::eENABLE_DIRECT_GPU_API flag needs to be raised, in combination with PxSceneFlag::eENABLE_GPU_DYNAMICS flag and PxBroadPhaseType::eGPU broad phase type.

PxSceneDesc sceneDesc(gPhysics->getTolerancesScale());
...
sceneDesc.flags |= PxSceneFlag::eENABLE_DIRECT_GPU_API;
sceneDesc.flags |= PxSceneFlag::eENABLE_GPU_DYNAMICS;
sceneDesc.broadPhaseType = PxBroadPhaseType::eGPU;
...
gScene = gPhysics->createScene(sceneDesc);

Note

These options are immutable and cannot be changed after the scene has been created.

To access the scene’s GPU data, the user should retrieve PxDirectGPUAPI instance, using the PxScene::getDirectGPUAPI() function, and then call one of PxDirectGPUAPI’s member functions, specifying the address of a GPU buffer to read from or write to, the indices of the actors to visit, and the type of data to set, get, or compute.

// allocate memory for the indices of all bodies
CUdeviceptr indexDevice = CUdeviceptr(NULL);
const size_t indexSize = sizeof(PxRigidDynamicGPUIndex) * nbBodies;
cuMemAlloc(&indexDevice, indexSize);
PxRigidDynamicGPUIndex* indexHost = NULL;
cuMemAllocHost((void**)&indexHost, indexSize);

// populate host index data
for(PxU32 i = 0; i < nbBodies; ++i)
        indexHost[i] = bodies[i]->getGPUIndex();

// transfer and apply:
cuMemcpyHtoD(indexDevice, (void*)indexHost, indexSize);

// allocate memory for the bodies' poses
CUdeviceptr poseDataDevice = CUdeviceptr(NULL);
const size_t poseDataSize = nbBodies * sizeof(PxTransform);
cuMemAlloc(&poseDataDevice, poseDataSize);

// retrieve the bodies' poses
gScene->getDirectGPUAPI().getRigidDynamicData((void*)poseDataDevice, (const PxRigidDynamicGPUIndex*)indexDevice,
        PxRigidDynamicGPUAPIReadType::eGLOBAL_POSE, nbBodies);

Note

Using this direct GPU API will disable the existing CPU-based API for all the data exposed in the direct GPU API. For any API function that does not have a counterpart in this direct GPU API, the existing API will continue to work.

Direct GPU API limitations

Due to the internal architecture of the GPU-accelerated parts of PhysX, using this API comes with caveats:

• All GPU-CPU copying for data exposed in this API will be disabled. This means that the existing CPU-based API will return outdated data, and any setters for data exposed in the interface will not work. On the other hand, significant speedups can be achieved because of the reduced amount of GPU-CPU memory copying.

• Disabled GPU-CPU copying also results in following CPU-only features to not work properly, so they shouldn’t be used

  • All Joints except D6 Joint that has a GPU Constraint shader

  • Scene Queries as it relies of CPU-based API

  • Custom Geometry for the same reason

  • Advanced Collision Detection will not report contact points and friction anchors data

  • To be continued

• Due to the internal architecture of the GPU-accelerated PhysX, this API will only work after a first simulation step has been taken. The reason for this is that the PxScene first needs to know all the actors it will have to simulate, and setup the sizes of the GPU-based structures. For setup, the existing CPU API should be used.

Note

Due to the fact that this API is exposing low-level data, we do reserve the right to change this API without deprecation in case of changes in the internal implementations.