Discrepancy in SDK Guide and API reference about completion tasks
zopsicle opened this issue · comments
The SDK Guide says:
A completion task is a task that executes immediately after PxScene::simulate has exited. If PhysX has been configured to use worker threads then PxScene::simulate will start simulation tasks on the worker threads and will likely exit before the worker threads have completed the work necessary to complete the scene update. […] As a consequence, a typical completion task would first need to call PxScene::fetchResults(true) to ensure that fetchResults blocks until all worker threads started during simulate() have completed their work.
I.e. the completion task is submitted just before simulate returns. (This would also mean that completion tasks are a redundant feature, as the caller could just submit the task themselves after simulate returns.)
The API reference says:
if non-NULL, this task will have its refcount incremented in simulate(), then decremented when the scene is ready to have fetchResults called. So the task will not run until the application also calls removeReference().
I.e. the completion task is not submitted before all the simulation tasks have finished. (This behavior seems actually useful, as it permits asynchronous use of the API without any blocking.)
It seems to me that the SDK Guide and the API reference disagree about when completion tasks are submitted. I guess the API reference here is correct?
The API documentation is correct. The text in the guide is misleading and needs some clarification. Thanks for the feedback.
Seems to have been fixed in the documentation for PhysX 5: https://nvidia-omniverse.github.io/PhysX/physx/5.1.0/docs/Simulation.html#completion-tasks. Thanks!