Is this page helpful?

IPrimDataReader#

Fully qualified name: isaacsim::core::experimental::prims::IPrimDataReader

struct IPrimDataReader#

Factory interface for creating typed read-only prim data views.

Carbonite plugin interface that creates typed views for XformPrim, RigidPrim, and Articulation data. Views provide compile-time safety: only getters valid for the view type are available.

Supports both PhysX (direct C++ TensorApi) and Newton (Python callback) backends transparently.

For multi-plugin usage, prefer acquiring and using IPrimDataReaderManager so lifecycle initialization is centralized across sensors/nodes. In new call sites, initialize() should be treated as manager-owned API surface.

Threading: All methods must be called from the main thread (the same thread that drives the simulation). Getter callbacks registered on views may be invoked from physics step callbacks on that thread.

View lifetime: Pointers returned by create*View() are owned by the plugin. They remain valid until removeView() is called for the same viewId, or until a generation change (detectable via getGeneration()). Consumers should snapshot the generation when creating a view and recheck before dereferencing cached pointers.

Public Functions

virtual void initialize(long stageId, int deviceOrdinal) = 0#

Initialize the reader with the current USD stage and simulation device.

Each call destroys all existing views, recreates the internal PhysX simulation view, and increments the generation counter. This is required because PhysX invalidates simulation views on timeline stop/play even when the stageId is unchanged. Consumers must recreate their views after each initialize() call. Prefer calling IPrimDataReaderManager::ensureInitialized() instead of calling this directly from sensor/node plugins.

Parameters:

  • stageId – Fabric stage ID (from UsdUtilsStageCache).

  • deviceOrdinal – CUDA device ordinal (-1 for CPU, >=0 for GPU).

virtual void shutdown() = 0#

Shut down the reader, destroying all views and freeing all buffers.

virtual IXformDataView *createXformView(
const char *viewId,
const char **paths,
size_t numPaths,
const char *engineType,
) = 0#

Create a typed XformPrim data view.

Parameters:

  • viewId – Unique string identifier for this view.

  • paths – Array of prim path strings (may include regex patterns).

  • numPaths – Number of paths in the array.

  • engineType – Physics engine backend: “physx” or “newton”.

Returns:

Pointer to view, owned by the plugin. Valid until removeView() or shutdown().

virtual IRigidBodyDataView *createRigidBodyView(
const char *viewId,
const char **paths,
size_t numPaths,
const char *engineType,
) = 0#

Create a typed RigidPrim data view (includes XformPrim getters).

Parameters:

  • viewId – Unique string identifier for this view.

  • paths – Array of prim path strings.

  • numPaths – Number of paths in the array.

  • engineType – Physics engine backend: “physx” or “newton”.

Returns:

Pointer to view, owned by the plugin. Valid until removeView() or shutdown().

virtual IArticulationDataView *createArticulationView(
const char *viewId,
const char **paths,
size_t numPaths,
const char *engineType,
) = 0#

Create a typed Articulation data view (includes XformPrim getters).

Parameters:

  • viewId – Unique string identifier for this view.

  • paths – Array of prim path strings.

  • numPaths – Number of paths in the array.

  • engineType – Physics engine backend: “physx” or “newton”.

Returns:

Pointer to view, owned by the plugin. Valid until removeView() or shutdown().

virtual void removeView(const char *viewId) = 0#

Destroy a view and free its buffers.

Parameters:

viewId – Identifier of the view to remove.

virtual void setArticulationDofMetadata(
const char *viewId,
const char **names,
size_t numNames,
const uint8_t *types,
size_t numTypes,
) = 0#

Set DOF names and types for an articulation view (used by Newton backend from Python).

Parameters:

  • viewId – Identifier of the articulation view.

  • names – Array of DOF name C-strings.

  • numNames – Number of names.

  • types – Array of DOF types (0 = rotation, 1 = translation).

  • numTypes – Number of types.

virtual uint64_t getGeneration() const = 0#

Monotonically increasing counter incremented on each initialize() call.

Consumers can snapshot this value when creating views and compare later to detect whether the underlying simulation view has been recreated, which invalidates all previously returned data view pointers.

virtual long getStageId() const = 0#

Get the Fabric stage ID passed to the last initialize() call.

Returns:

Stage ID, or 0 if not yet initialized.

virtual int getDeviceOrdinal() const = 0#

Get the effective CUDA device ordinal.

After initialize(), this reflects the device ordinal reported by the underlying simulation view (which may differ from the value originally passed to initialize()).

Returns:

CUDA device ordinal (>=0 for GPU, -1 for CPU).

virtual bool enableContactReporting(const char *bodyPath) = 0#

Enable contact reporting for a rigid body on the simulation side.

Applies PhysxContactReportAPI (threshold=0, sleepThreshold=0) so that subsequent getContactReport() calls return data for this body. Idempotent. For local PhysX: modifies the USD stage directly. For remote: forwards to the World Simulator via gRPC. For Newton: no-op (returns true).

Parameters:

bodyPath – USD path to the rigid body prim.

Returns:

true on success, false on error.

virtual bool getContactReport(
const char **bodyPaths,
size_t numPaths,
ContactReportData *outReport,
) = 0#

Get the full contact report filtered to the specified body paths.

Returns a two-level structure: events (one per body pair, including LOST events with zero contact points) containing contact points. Pointers in the returned ContactReportData are owned by the reader and valid until the next call to getContactReport() or reader re-initialization. For local PhysX: calls IPhysxSimulation::getFullContactReport(). For remote: fetches via gRPC from the World Simulator. For Newton: returns empty report (contact sensor not supported via this path).

Parameters:

  • bodyPaths – Array of rigid body prim path strings to filter for.

  • numPaths – Number of paths in the array.

  • outReport – Receives the contact report data.

Returns:

true if the query succeeded (report may still have zero events), false on error.