Skip to main content
`Ctrl`+`K`

# C API Reference

The full C API is defined in these headers:

- `include/ovphysx/ovphysx.h` – API functions

- `include/ovphysx/ovphysx_types.h` – types and enums

- `include/ovphysx/ovphysx_config.h` – typed config entry builders

C++ convenience wrappers (experimental, C++17):

- `include/ovphysx/experimental/ovphysx.hpp` – RAII instance wrapper

- `include/ovphysx/experimental/Helpers.hpp` – RAII helpers (WaitResult, etc.)

- `include/ovphysx/experimental/TensorBinding.hpp` – RAII tensor binding wrapper

For rendered documentation with full descriptions, refer to the built HTML docs.

## C API Functions

### Articulation Kinematic Update

Use `ovphysx_update_articulations_kinematic()` after writing articulation DOF positions when link-pose tensors must reflect the new joint positions before the next simulation step. The Python method is `PhysX.update_articulations_kinematic()`, and the experimental C++ wrapper is `PhysX::updateArticulationsKinematic()`. The operation is synchronous and updates articulation forward kinematics only; after any required first GPU warmup, it does not run a normal simulation step or collision/contact processing.

Functions

ovphysx_result_t ovphysx_initialize(void)

  Initialize process-global ovphysx lifecycle state.

  Returns:

    - OVPHYSX_API_SUCCESS if lifecycle state was initialized.

    - OVPHYSX_API_ERROR if lifecycle state is already initialized, or on x86_64 if the host CPU or OS does not expose AVX (required by pre-built x86_64 binaries).

ovphysx_result_t ovphysx_create_instance(

  const ovphysx_create_args *create_args,
  ovphysx_handle_t *out_handle,

)

  Create a new ovphysx instance.

  Initialize create_args with OVPHYSX_CREATE_ARGS_DEFAULT for sensible defaults:

      ovphysx_set_log_level(OVPHYSX_LOG_VERBOSE);  // optional: default is WARNING
      ovphysx_initialize();
      ovphysx_create_args args = OVPHYSX_CREATE_ARGS_DEFAULT;
      ovphysx_handle_t handle = OVPHYSX_INVALID_HANDLE;
      ovphysx_result_t r = ovphysx_create_instance(&args, &handle);

  Side Effects

    Loads runtime components and initializes process-level state.

  Threading

    Safe to call from any thread. The resulting handle is not thread-safe for concurrent use.

  Ownership

    Caller owns the instance handle and must destroy it.

  Errors

    - OVPHYSX_API_INVALID_ARGUMENT on null required pointers, inconsistent config_entries / config_entry_count, or invalid active_cuda_gpus

    - OVPHYSX_API_ERROR if ovphysx_initialize() is not active, or for other initialization failures

  Note

  active_cuda_gpus restricts which GPU ordinals are available for this instance. Per-scene device selection (CPU vs GPU dynamics) is owned by PhysX via physxScene:enableGPUDynamics in the USD stage. Use ovphysx_set_cpu_mode() before creating any instance to force process-wide CPU-only mode.

  Parameters:

    - create_args – Configuration for the ovphysx instance (must not be NULL). If config_entry_count is nonzero, config_entries must not be NULL.

    - out_handle – [out] ovphysx handle (must not be NULL).

  Returns:

    ovphysx_result_t with status and error info.

  Pre:

    create_args != NULL, out_handle != NULL.

  Post:

    On success, *out_handle is a valid handle that must be destroyed with ovphysx_destroy_instance().

  Post:

    With an active lifecycle, if config_entries is NULL and config_entry_count is nonzero, *out_handle is unchanged.

ovphysx_result_t ovphysx_set_cpu_mode(bool cpu_only)

  Force process-wide CPU-only mode.

  To guarantee that no CUDA driver is touched for the lifetime of the process, set this to true before the first instance is ever created. All subsequent PhysX scenes will use CPU dynamics regardless of their USD physxScene:enableGPUDynamics setting. For per-scene CPU control without this flag, author each scene explicitly (physxScene:enableGPUDynamics=false + physxScene:broadphaseType=”MBP”).

  Requires that no instances are active. Returns OVPHYSX_API_ERROR if any instances currently exist, or if attempting to set false after true has been applied. CPU-only mode is sticky as soon as a call setting it to true succeeds.

ovphysx_result_t ovphysx_register_schema_paths(void)

  Register ovphysx USD schema/plugin discovery paths before runtime initialization.

  This is intended for applications that share a namespaced OpenUSD runtime between multiple subsystems, such as ovphysx and ovrtx. USD’s schema registry is populated only once for the process, so every subsystem that contributes schema/plugin paths must publish them before the registry is first consulted, typically before the first USD stage is opened.

  The function appends ovphysx’s bundled USD plugin root to the namespaced USD plugin-path environment variable, `OV_PXR_PLUGINPATH_2511`. It preserves existing entries and does not modify `PXR_PLUGINPATH_NAME`.

  Notes:

  - Safe to call before ovphysx_create_instance().

  - Idempotent; the first successful call performs registration, subsequent calls are no-ops.

  - Failed calls do not mark registration complete, so callers may fix the installation or `OVPHYSX_LIB` override and retry.

  - This function does not initialize ovphysx, load USD, acquire Carbonite, or open a stage.

  - Calling this after USD has already populated its schema registry has no retroactive effect.

  Returns:

    - OVPHYSX_API_SUCCESS if the schema/plugin paths were registered successfully.

    - OVPHYSX_API_ERROR if registration failed. Use ovphysx_get_last_error() for details.

ovphysx_result_t ovphysx_destroy_instance(ovphysx_handle_t handle)

  Destroy an ovphysx instance and release per-instance resources.

  Carbonite and the static PhysX runtime stay resident until process exit.

      ovphysx_destroy_instance(handle);

  Side Effects

    Releases internal resources, plugins, and cached data for this instance.

  Threading

    Do not destroy an instance while it is in use on other threads.

  Ownership

    After destruction, any bindings created by this instance are invalid.

  Errors

    - OVPHYSX_API_ERROR if destruction fails. No error string is returned; consult logs.

  Parameters:

    handle – ovphysx handle to destroy.

  Returns:

    ovphysx_result_t with status and error info.

  Pre:

    handle must be a valid instance handle.

  Post:

    The handle is invalid and must not be reused.

ovphysx_result_t ovphysx_shutdown(void)

  Clear the ovphysx process-lifecycle token.

  Clears the process-global initialized state set by ovphysx_initialize. It does not destroy live handles and does not balance ovphysx_create_instance; callers must destroy every handle explicitly with ovphysx_destroy_instance.

  Must be paired with a prior ovphysx_initialize call. Call once when the application is done with the current process-lifecycle scope. After shutdown, callers must invoke ovphysx_initialize again before creating another instance.

  Static runtime mode

    Static ovphysx keeps Carbonite, the direct PhysX runtime, and OmniClient resident until process exit. This avoids re-entering plugin teardown from application shutdown paths.

  Returns:

    - OVPHYSX_API_SUCCESS on success.

    - OVPHYSX_API_ERROR if called without a matching ovphysx_initialize. Use ovphysx_get_last_error() for details.

void ovphysx_get_version(

  uint32_t *out_major,
  uint32_t *out_minor,
  uint32_t *out_patch,

)

  Get runtime version of the library.

  Useful for checking ABI compatibility between headers and shared library. For compile-time version macros, include `ovphysx/version.h`.

  Parameters:

    - out_major – [out] Major version (must not be NULL)

    - out_minor – [out] Minor version (must not be NULL)

    - out_patch – [out] Patch version (must not be NULL)

const char *ovphysx_get_version_string(void)

  Get version as string (e.g., “0.1.0”).

  Returns:

    Version string with static storage duration (valid for lifetime of process, do not free).

ovphysx_result_t ovphysx_set_global_config(

  ovphysx_config_entry_t entry,

)

  Set a typed global config entry at runtime (process-global).

  IMPORTANT: Config is PROCESS-GLOBAL. Changes affect all ovphysx instances in the current process. Configure before creating instances or loading USD for predictable behavior.

  Use the builder functions in ovphysx_config.h for convenient construction:

      #include "ovphysx/ovphysx_config.h"
      ovphysx_set_global_config(ovphysx_config_entry_num_threads(4));
      ovphysx_set_global_config(ovphysx_config_entry_disable_contact_processing(true));
      // Escape hatch for arbitrary Carbonite paths:
      ovphysx_set_global_config(ovphysx_config_entry_carbonite(
          OVPHYSX_LITERAL("/physics/updateToUsd"), OVPHYSX_LITERAL("false")));

  Parameters:

    entry – Typed config entry to apply.

  Returns:

    ovphysx_result_t with status and error info.

ovphysx_result_t ovphysx_get_global_config_bool(

  ovphysx_config_bool_t key,
  bool *out_value,

)

  Get a boolean config value.

  Parameters:

    - key – Boolean config key.

    - out_value – [out] Current value.

  Returns:

    ovphysx_result_t with status and error info.

ovphysx_result_t ovphysx_get_global_config_int32(

  ovphysx_config_int32_t key,
  int32_t *out_value,

)

  Get an int32 config value.

  Parameters:

    - key – Int32 config key.

    - out_value – [out] Current value.

  Returns:

    ovphysx_result_t with status and error info.

ovphysx_result_t ovphysx_get_global_config_float(

  ovphysx_config_float_t key,
  float *out_value,

)

  Get a float config value.

  Parameters:

    - key – Float config key.

    - out_value – [out] Current value.

  Returns:

    ovphysx_result_t with status and error info.

ovphysx_result_t ovphysx_get_global_config_string(

  ovphysx_config_string_t key,
  ovphysx_string_t *value_out,
  size_t *out_required_size,

)

  Get a string config value into a user-provided buffer.

  Parameters:

    - key – String config key.

    - value_out – [in/out] String with pre-allocated buffer (ptr+length).

    - out_required_size – [out] Required buffer size including null terminator.

  Returns:

    ovphysx_result_t with status and error info.

ovphysx_enqueue_result_t ovphysx_reset_stage(ovphysx_handle_t handle)

ovphysx_result_t ovphysx_attach_ovstage(

  ovphysx_handle_t handle,
  ovstage_instance_t *stage,
  ovstage_ordinal_t read_ordinal,

)

  Attach an ovstage Stage as the orchestration data surface.

  Once attached, the orchestration contract is explicit and application-owned in both directions (the application owns ordinal advancement):

  - app → physics (control in): the app authors dirty control attributes into ovstage (drive:force, drive:velocity, drive:position_target, physics:mass, physics:gravityMagnitude, physics:gravityDirection, …) at ordinals it chooses, then calls ovphysx_update_from_ovstage to drain that ordinal range into the running simulation. ovphysx_step then integrates.

  - physics → app (output out): ovphysx_step does not author simulation output back into the Stage on its own. The app reads the step’s output with ovphysx_read / ovphysx_fetch_read_next and writes it back into ovstage at a separate, higher (physics-output) ordinal — the ordinal that update_from_ovstage never covers, so physics never reprocesses its own writes. See the ordinal-coupling section on ovphysx_query.

  This is one consistent model: initial parse at attach, explicit control updates via update_from_ovstage, and app-owned output writeback via the read API. ovphysx tensor bindings remain available as a perf escape hatch for callers that need direct control without going through ovstage.

  The attachment is init-style — call once per instance, before any ovphysx_step(). Replacing the attached Stage requires ovphysx_detach_ovstage() first.

      // A caller-owned ovstage instance, kept alive until ovphysx_detach_ovstage().
      ovstage_instance_t* stage = my_ovstage_instance;
      ovphysx_result_t r = ovphysx_attach_ovstage(handle, stage, read_ordinal);

  Errors

    - OVPHYSX_API_INVALID_ARGUMENT if stage is null

    - OVPHYSX_API_ERROR if already attached or the runtime attach fails

  Note

  Not thread-safe per instance. Like the rest of the per-instance API, the caller must serialize ovphysx_attach_ovstage() against any other call on the same handle; the already-attached check and the attach are not internally locked against concurrent foreground callers.

  Parameters:

    - handle – ovphysx instance handle.

    - stage – Caller-owned ovstage Stage (`ovstage_instance_t*`).

    - read_ordinal – Caller-owned sealed ovstage ordinal the initial scene parse reads at. The application owns ordinal advancement; this is the starting point (subsequent edits are drained via ovphysx_update_from_ovstage()).

  Pre:

    handle is valid; ovphysx is not already attached to a Stage; stage is non-null.

  Pre:

    stage outlives the attachment. ovphysx captures this pointer and dereferences it on every ovphysx_update_from_ovstage() until ovphysx_detach_ovstage(); destroying the Stage between attach and detach is undefined behavior, not a recoverable error.

  Post:

    On success, subsequent ovphysx_update_from_ovstage() calls observe committed Stage writes through the runtime ovstage backend.

ovphysx_result_t ovphysx_update_from_ovstage(

  ovphysx_handle_t handle,
  ovstage_ordinal_range_t range,

)

  Pull and apply committed ovstage edits over an explicit ordinal range.

  The caller is the producer that advanced ovstage ordinals and therefore owns the range boundaries, passed as ovstage’s own `ovstage_ordinal_range_t`. With `has_start_ordinal == true` the closed range `[start_ordinal, end_ordinal]` is drained; with `has_start_ordinal == false` only `end_ordinal` is drained (the single-ordinal form). The selected changes are drained through the active ovstage change feed and applied to the running simulation.

  Errors

    - OVPHYSX_API_INVALID_ARGUMENT for an invalid range or handle

    - OVPHYSX_API_ERROR if no ovstage is attached or the range drain fails

  Note

  The initial `read_ordinal` was already parsed by ovphysx_attach_ovstage(). Normal incremental updates select only later ordinals; including it replays initial scene changes rather than only the new delta.

  Parameters:

    - handle – ovphysx instance handle.

    - range – ovstage ordinal range to drain (see ovstage_ordinal_range_t).

  Pre:

    `handle` is valid; ovphysx_attach_ovstage succeeded.

  Pre:

    when `range.has_start_ordinal`, `range.start_ordinal <= range.end_ordinal`.

  Pre:

    All selected writes are sealed by a completed write-floor operation covering `range.end_ordinal`. Waiting for `ovstage_population_apply_usd_changes()` only completes population; it does not advance the write floor.

ovphysx_result_t ovphysx_detach_ovstage(ovphysx_handle_t handle)

  Detach the currently-attached ovstage Stage.

  Idempotent: calling on an unattached instance is a no-op success. Clears registered interests and any output-buffer registrations, so a subsequent ovphysx_attach_ovstage() to a different Stage starts clean. After detach, stage-dependent calls such as ovphysx_update_from_ovstage() and ovphysx_step() fail until a Stage is attached again. Detach invalidates the stage’s tensor and contact views. Do not read or write existing bindings; destroy them and create replacements after attaching and realizing a stage again.

  Errors

    - OVPHYSX_API_ERROR for internal failures

  Parameters:

    handle – ovphysx instance handle.

  Pre:

    handle is valid.

  Post:

    On success, ovphysx is unattached.

ovphysx_result_t ovphysx_query(

  ovphysx_handle_t handle,
  ovphysx_sim_object_type_t object_type,
  ovphysx_object_scope_t scope,
  ovphysx_query_handle_t *out_query,

)

  Open a query over the simulation’s output objects of one simulated type.

  Mirrors the ovstage read idiom: the query is a handle (not a list). The matched prims come back per group at read time as the interned ovstage_read_group_t::prims.list (resolve via ovphysx_query_shared_dictionary or feed straight into the ovstage write path). Discover the produced attributes / total prim count with ovphysx_fetch_query_result. Pair every successful query with ovphysx_release_query.

  This read is ovstage-native and only meaningful when an ovstage Stage is attached (ovphysx_attach_ovstage); under any other attach it returns 0 objects.

ovphysx_result_t ovphysx_fetch_query_result(

  ovphysx_handle_t handle,
  ovphysx_query_handle_t query,
  ovstage_query_result_t *out_result,

)

  Fetch a query’s discovery summary (attributes + total prim count).

  Fills ovstage’s own `ovstage_query_result_t`. Its `attributes` array lists the interned attribute tokens the matched objects produce (resolve via ovphysx_query_shared_dictionary, or feed straight back into ovphysx_read as `ovx_string_or_token_t` tokens); the array is owned by the query and valid until ovphysx_release_query. `total_prim_count == 0` is the empty-match case.

  Errors

    - OVPHYSX_API_INVALID_ARGUMENT if out_result is null

    - OVPHYSX_API_ERROR for a bad query handle / no ovstage attached

  Parameters:

    - handle – ovphysx instance handle.

    - query – Query handle from ovphysx_query.

    - out_result – [out] Receives the discovery summary.

  Returns:

    ovphysx_result_t.

ovphysx_result_t ovphysx_query_shared_dictionary(

  ovphysx_handle_t handle,
  ovphysx_query_handle_t query,
  void **out_dictionary,

)

  Get the shared ovstage path dictionary backing a query.

  This is NOT an ovphysx-owned dictionary. The returned pointer is the attached ovstage source’s own `path_dictionary_instance_t*` — the very dictionary that interned this query’s `prim_list` handles and `attribute` tokens, AND the dictionary the ovstage write path interns into. Because read and write share it, a group’s `attribute` token / `prim_list` handle can be fed straight back into the ovstage write path with no rebuild and no string round-trip; you only need this accessor when you want to resolve a token to a human-readable string or to intern a derived name (e.g. renaming output to “sim:<name>”).

  The pointer is declared in `<ovx/path_dictionary/path_dictionary.h>` and surfaced here as an opaque `void*` (that header defines C++-only inline helpers, so it is deliberately not pulled into this C surface). Owned by the runtime; do not free. Returns NULL for a non-ovstage backend.

  Errors

    - OVPHYSX_API_INVALID_ARGUMENT if out_dictionary is null

    - OVPHYSX_API_ERROR for a bad query handle / no ovstage attached

  Parameters:

    - handle – ovphysx instance handle.

    - query – Query handle from ovphysx_query.

    - out_dictionary – [out] Receives the opaque dictionary pointer (NULL if none).

  Returns:

    ovphysx_result_t.

ovphysx_result_t ovphysx_read(

  ovphysx_handle_t handle,
  ovphysx_query_handle_t query,
  const ovx_string_or_token_t *attributes,
  size_t attribute_count,
  ovphysx_read_handle_t *out_read,

)

  Read named output attributes for a query into typed column groups.

  Opens a read session over `query` for the requested attributes, each given as an `ovx_string_or_token_t` — a string name (see OVPHYSX_ATTR_*) OR an interned token (e.g. from ovphysx_fetch_query_result, fed straight back with no token→string round-trip). Iterate the result with ovphysx_fetch_read_next, release each consumed group with ovphysx_release_group, and release the session with ovphysx_release_read. Names not produced by the queried type are skipped.

ovphysx_result_t ovphysx_fetch_read_next(

  ovphysx_handle_t handle,
  ovphysx_read_handle_t read,
  const ovstage_read_group_t **out_group,

)

  Fetch the next output column group from a read session.

  On success points `*out_group` at the next `ovstage_read_group_t` and returns OVPHYSX_API_SUCCESS. Returns OVPHYSX_API_END_OF_ITERATION (NOT an error) once all groups have been consumed — `*out_group` is then NULL. Any other status is a real error (`*out_group` NULL).

  The group is producer-owned (the caller does not allocate it): the returned `ovstage_read_group_t` pointer is a borrow valid until ovphysx_release_group is called for that group’s `read_group_id`, or the session is released.

  Group lifetime (authoritative): the struct AND its borrowed `data.tensors` / `data.index_map` / `data.mask` / `prims.list` stay valid until ovphysx_release_group for that `read_group_id` (or ovphysx_release_read, which releases all). Fetching further groups does NOT invalidate earlier ones, and an intervening ovphysx_step does NOT invalidate a live group (the runtime gathers each column into session-owned storage at read time). Copy any tensor you need to outlive the group’s release.

  Errors

    - OVPHYSX_API_INVALID_ARGUMENT if out_group is null

    - OVPHYSX_API_ERROR for a bad read handle

  Parameters:

    - handle – ovphysx instance handle.

    - read – Read-session handle from ovphysx_read.

    - out_group – [out] Receives a borrowed `ovstage_read_group_t*` for the next group (NULL at end of iteration or on error).

  Returns:

    ovphysx_result_t: SUCCESS (group filled), END_OF_ITERATION (done), else error.

  Pre:

    handle and read are valid; out_group is non-null.

ovphysx_result_t ovphysx_release_group(

  ovphysx_handle_t handle,
  ovphysx_read_handle_t read,
  ovstage_read_group_id_t group_id,

)

  Release one fetched group’s borrowed storage.

  Releases the column / prim storage pinned by ovphysx_fetch_read_next for `group_id` (an `ovstage_read_group_t::read_group_id`). After this the group’s tensors / index_map / prims.list must not be dereferenced.

  Parameters:

    - handle – ovphysx instance handle.

    - read – Read-session handle the group came from.

    - group_id – The group’s `ovstage_read_group_t::read_group_id`.

  Returns:

    ovphysx_result_t. Idempotent for an already-released / unknown id.

ovphysx_result_t ovphysx_release_read(

  ovphysx_handle_t handle,
  ovphysx_read_handle_t read,

)

  Release a read session (and every borrowed group it still owns).

  Parameters:

    - handle – ovphysx instance handle.

    - read – Read-session handle from ovphysx_read.

  Returns:

    ovphysx_result_t. Idempotent for an already-released / unknown handle.

ovphysx_result_t ovphysx_release_query(

  ovphysx_handle_t handle,
  ovphysx_query_handle_t query,

)

  Release an output query.

  Parameters:

    - handle – ovphysx instance handle.

    - query – Query handle from ovphysx_query.

  Returns:

    ovphysx_result_t. Idempotent for an already-released / unknown handle.

ovphysx_enqueue_result_t ovphysx_clone(

  ovphysx_handle_t handle,
  ovphysx_string_t source_path_in_usd,
  ovphysx_string_t *target_paths,
  uint32_t num_target_paths,
  const float *parent_transforms,
  const uint32_t *env_ids,

)

  Clone the subtree under the source path to one or more target paths in the internal physics representation (USD untouched).

  The source path must exist in the stage. The target paths must not already exist in the stage.

  Clones are created in the internal representation only (USD file will not be modified) and immediately participate in physics simulation. Backed by the PhysX SDK replicator, so cloned articulations are real articulations. Optimized for RL mass replication (1000s of instances). This is the clone entrypoint for both standalone callers and callers using an ovstage Stage (ovphysx_attach_ovstage).

      // Clone whole environments (one target per environment; NULL transforms co-locate on the source).
      ovphysx_string_t targets[2] = { ovphysx_cstr("/World/env1"), ovphysx_cstr("/World/env2") };
      ovphysx_enqueue_result_t r = ovphysx_clone(handle, ovphysx_cstr("/World/env0"), targets, 2, NULL, NULL);
      // To assemble one environment from several calls (heterogeneous ClonePlan), pass the same
      // env_ids in each call so its objects share a runtime environment.

  Side Effects

    Adds live PhysX objects keyed by each target path. No USD or runtime-stage prims are authored.

  Ownership

    The target_paths array is read during the call; caller retains ownership.

  Errors

    - OVPHYSX_API_INVALID_ARGUMENT for invalid or duplicate targets, or a call after GPU warmup / the first step

    - OVPHYSX_API_ERROR if no ovstage is attached or the clone fails

  Note

  Cross-environment collision isolation uses PhysX environment ids under GPU dynamics + GPU broadphase, controlled by `/ovphysx/clone/useEnvIds` (default on, per-process). The source holds env id 0 and clones get 1..N, so co-located clones (NULL parent_transforms) are isolated from the source too. USD collision groups/filtering authored before cloning still work for finer control. Pass `env_ids` when one logical environment is assembled from several clone calls, so its objects share an id.

  Note

  Replication executes inline. On success, the returned operation index is already complete; ovphysx_wait_op() remains valid and returns immediately.

  Parameters:

    - handle – PhysX instance handle

    - source_path_in_usd – Path to the source subtree to clone (must exist)

    - target_paths – Array of target paths to clone to (must not exist)

    - num_target_paths – Number of target paths to clone to

    - parent_transforms – World pose of each copy’s parent. Flat [num_target_paths x 7] floats: (px, py, pz, qx, qy, qz, qw), quaternion imaginary-first (OVPHYSX_TENSOR_RIGID_BODY_POSE_F32, identity = (0,0,0,1)). Each body keeps its pose relative to the source’s parent (world = parent_transforms[i] * inverse(source_parent) * source_body). Pass NULL to co-locate every copy on the source.

    - env_ids – Optional logical environment id per target ([num_target_paths] uint32). Stable across calls: a shared id maps to one runtime environment (clones sharing it collide, isolated from others). Ids must be < 0x00FFFFFF (runtime id is env_ids[i] + 1). Pass NULL for automatic per-call numbering.

  Returns:

    ovphysx_enqueue_result_t with status and operation index for the clone. On failure, call ovphysx_get_last_error() on the same thread for the error message.

  Pre:

    handle must be valid; an ovstage source is attached via ovphysx_attach_ovstage.

  Pre:

    source_path_in_usd must exist; target_paths must be valid, unique, and disjoint &#8212; a target that reuses, contains, or is contained by another target or an earlier clone’s target on this attach is rejected (it would create duplicate actors).

  Pre:

    Must be called before the first ovphysx_step() / ovphysx_step_sync() / ovphysx_step_n_sync() call. Violating this is rejected with OVPHYSX_API_INVALID_ARGUMENT in both CPU and GPU mode.

  Pre:

    Must also be called before warmup_gpu(), but this precondition is currently GPU-only: in hard CPU mode warmup_gpu() is a no-op, so clone-after-warmup still succeeds on CPU today. Cloning after GPU warmup reallocates GPU buffers and would corrupt already-initialised state, hence the rejection on GPU.

  Post:

    Cloned physics objects are live when this call returns successfully.

ovphysx_enqueue_result_t ovphysx_step(

  ovphysx_handle_t handle,
  float step_dt,

)

ovphysx_result_t ovphysx_step_sync(

  ovphysx_handle_t handle,
  float step_dt,

)

  Synchronous step: simulate one physics timestep and wait for completion in a single call.

  Functionally equivalent to ovphysx_step() followed by ovphysx_wait_op() on the returned operation index, but bypasses the async event machinery entirely (mutex acquisitions, operation map insert/lookup/cleanup). This is a measurable performance improvement for the common synchronous use case: in IsaacLab RL training at 4096 environments, step_sync saves ~0.2 ms per substep compared to step() + wait_op(), recovering roughly 5-6% of total throughput.

  Use this whenever you step and immediately wait for results (i.e. you do not overlap GPU simulation with CPU work between dispatch and fetch).

  The simulation time is tracked internally; each step advances it by step_dt.

  Parameters:

    - handle – Physics instance handle.

    - step_dt – Timestep [s].

  Returns:

    ovphysx_result_t with OVPHYSX_API_SUCCESS on success.

ovphysx_result_t ovphysx_step_n_sync(

  ovphysx_handle_t handle,
  int32_t n_steps,
  float step_dt,

)

  Run n_steps consecutive physics steps in a single C call.

  Step i is executed with duration step_dt at the internally-tracked simulation time + i * step_dt. This saves (n_steps-1) ctypes round-trips for workloads that use decimation (one RL step = multiple physics steps). The internal counter advances by n_steps * step_dt.

  Parameters:

    - handle – Physics instance handle.

    - n_steps – Number of steps to run (must be > 0).

    - step_dt – Duration of each step [s].

  Returns:

    ovphysx_result_t with OVPHYSX_API_SUCCESS on success.

ovphysx_result_t ovphysx_update_articulations_kinematic(

  ovphysx_handle_t handle,

)

  Recompute articulation link transforms from the current articulation generalized coordinates without running a normal simulation step.

  This is a synchronous kinematic forward-kinematics update. It is useful after writing articulation DOF positions through TensorBindingsAPI and before reading link pose tensors in the same frame.

  GPU MODE WARNING: On the first GPU kinematic update after loading USD, an automatic warmup simulation step may be performed to initialize PhysX DirectGPU buffers. See GPU tensor auto-warmup note.

  Once GPU warmup is complete, the FK refresh itself does not run collision detection, integration, solver work, or contact generation.

  Parameters:

    handle – Physics instance handle.

  Returns:

    ovphysx_result_t with OVPHYSX_API_SUCCESS on success.

ovphysx_result_t ovphysx_create_tensor_binding(

  ovphysx_handle_t handle,
  const ovphysx_tensor_binding_desc_t *desc,
  ovphysx_tensor_binding_handle_t *out_binding_handle,

)

  Create a tensor binding for bulk data access (synchronous).

  A tensor binding connects a USD prim pattern (e.g., “/World/robot*”) to a tensor type (e.g., OVPHYSX_TENSOR_RIGID_BODY_POSE_F32), enabling efficient bulk read/write of physics data for all matching prims.

  If the pattern matches zero prims, the binding is still created successfully with element_count = 0. This lets callers treat optional scene content as an empty current result instead of an error. Empty bindings do not update when matching prims are added or recreated; destroy the old binding and create a new one after topology changes.

  Binding lifetime is tied to the currently realized physics objects. The application owns the stage lifecycle: if it will call ovphysx_reset_stage(), remove USD data containing bound objects, or otherwise replace/reparse the stage so those objects are destroyed and recreated, cached bindings should be destroyed before the lifecycle operation when practical. If a stale binding survives, only destroy it; do not read or write through it. Create replacement bindings after the operation completes. ovphysx_step(), ovphysx_step_sync(), and ovphysx_step_n_sync() do not invalidate bindings.

  Example: ovphysx_tensor_binding_desc_t desc = { .pattern = OVPHYSX_LITERAL(“/World/robot*”), // compile-time string literal .tensor_type = OVPHYSX_TENSOR_RIGID_BODY_POSE_F32 }; ovphysx_create_tensor_binding(handle, &desc, &binding);

      ovphysx_tensor_binding_handle_t binding = 0;
      ovphysx_create_tensor_binding(handle, &desc, &binding);

  Diagnostics

    Pattern bindings quiet expected TensorAPI no-match diagnostics on the simulation view used to create that binding. Explicit prim_paths keep the default error-level no-match diagnostics for typo detection. For programmatic partial-miss checks with explicit prim_paths, compare the requested paths with ovphysx_tensor_binding_get_prim_paths().

  Threading

    Do not create bindings concurrently with stage mutation.

  Side Effects

    Allocates internal binding resources.

  Errors

    - OVPHYSX_API_INVALID_ARGUMENT for invalid inputs

    - OVPHYSX_API_ERROR for internal failures

  Parameters:

    - handle – Instance handle

    - desc – Binding descriptor with pattern and tensor_type

    - out_binding_handle – [out] Binding handle on success

  Returns:

    ovphysx_result_t (synchronous - completes before returning)

  Pre:

    handle, desc, and out_binding_handle must be valid.

  Post:

    Binding handle owns native resources until explicitly destroyed via ovphysx_destroy_tensor_binding(), or until the parent instance is destroyed. Stage reset or bound-object removal invalidates the underlying TensorAPI view; destroy stale bindings and create replacements after the lifecycle operation completes.

ovphysx_result_t ovphysx_destroy_tensor_binding(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,

)

  Destroy a tensor binding and release associated resources (synchronous).

      ovphysx_destroy_tensor_binding(handle, binding);

  Side Effects

    Releases internal resources.

  Errors

    - OVPHYSX_API_NOT_FOUND if binding handle is unknown

    - OVPHYSX_API_ERROR for internal failures

  Parameters:

    - handle – Instance handle

    - binding_handle – Binding to destroy

  Returns:

    ovphysx_result_t

  Pre:

    handle and binding_handle must be valid.

  Post:

    Binding handle is invalid after call.

ovphysx_result_t ovphysx_get_tensor_binding_spec(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,
  ovphysx_tensor_spec_t *out_spec,

)

  Get complete tensor specification for a binding (preferred).

  Returns dtype, ndim, and shape needed to allocate a compatible DLTensor. This is the preferred API for constructing DLTensors correctly.

  NOTE: ovphysx_tensor_spec_t stores shape in a fixed-size int64[4] for a stable C ABI. Only the first ndim entries are meaningful; the remaining entries are always set to 0.

  See ovphysx_tensor_type_t documentation for shapes, dtype, and layouts per tensor type. Layout is always row-major contiguous (C-order). Most bindings are float32; OVPHYSX_TENSOR_DEFORMABLE_SIM_ELEMENT_INDICES_S32 is int32.

      ovphysx_tensor_spec_t spec;
      ovphysx_get_tensor_binding_spec(handle, binding, &spec);

  Side Effects

    None.

  Errors

    - OVPHYSX_API_NOT_FOUND if binding handle is unknown

    - OVPHYSX_API_ERROR for internal failures

  Parameters:

    - handle – Instance handle

    - binding_handle – Tensor binding

    - out_spec – [out] Full tensor specification

  Returns:

    ovphysx_result_t

  Pre:

    handle, binding_handle, and out_spec must be valid.

  Post:

    out_spec is populated with dtype/shape for the binding.

ovphysx_result_t ovphysx_read_tensor_binding(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,
  DLTensor *dst_tensor,

)

  The warmup is a real physics step that advances simulation time by a minimal timestep (~1ns). Physics state may change infinitesimally; this is not a dry run.

  GPU tensor auto-warmup note

    In GPU mode, the first tensor read or write after loading USD may perform an automatic warmup simulation step to initialize PhysX DirectGPU buffers.

  For deterministic behavior, explicitly control warmup timing by loading USD, waiting for completion, then calling ovphysx_warmup_gpu() before the first tensor read or write. If you want the first observed state change to happen under your chosen timestep instead, call ovphysx_step() explicitly with that dt.

  Because warmup is a real simulation step, a true “pre-warmup” GPU tensor state cannot be observed. Calling ovphysx_warmup_gpu() explicitly only makes the timing of that unavoidable step predictable. Read data from simulation into a user-provided DLTensor (synchronous).

  GPU MODE WARNING: On the first GPU tensor read after loading USD, an automatic warmup simulation step may be performed to initialize PhysX DirectGPU buffers. See GPU tensor auto-warmup note.

  DLTensor requirements:

  - MUST be pre-allocated with correct shape (use ovphysx_get_tensor_binding_spec())

  - dtype must match ovphysx_get_tensor_binding_spec()

  - device must be supported; CPU/CUDA mismatches are staged when CUDA is available, while cross-GPU ordinal mismatches and CUDA tensors in process-wide CPU-only mode return OVPHYSX_API_DEVICE_MISMATCH

  - layout must be contiguous row-major (C-order)

  This is a blocking call that completes before returning.

      ovphysx_read_tensor_binding(handle, binding, &tensor);

  Side Effects

    May trigger GPU warmup on first read in GPU mode.

  Ownership

    Caller owns dst_tensor memory.

  Errors

    - OVPHYSX_API_DEVICE_MISMATCH if tensor device is incompatible

    - OVPHYSX_API_INVALID_ARGUMENT for invalid inputs

    - OVPHYSX_API_NOT_FOUND if the binding is unknown or was invalidated by a stage change

    - OVPHYSX_API_ERROR for internal failures

  Parameters:

    - handle – Instance handle

    - binding_handle – Tensor binding

    - dst_tensor – Pre-allocated DLTensor with shape from ovphysx_get_tensor_binding_spec()

  Returns:

    ovphysx_result_t

  Pre:

    handle and binding_handle must be valid.

  Pre:

    dst_tensor must be pre-allocated, match the spec’s dtype/shape, and use a supported device.

  Post:

    dst_tensor is filled with simulation data on success.

ovphysx_result_t ovphysx_warmup_gpu(ovphysx_handle_t handle)

  Explicitly initialize GPU buffers (optional, synchronous).

  In GPU mode, PhysX DirectGPU buffers need one simulation step to initialize. This is normally done automatically on the first tensor read (auto-warmup).

  IMPORTANT: The warmup performs a real physics simulation step with a minimal timestep (~1ns). While the effect is negligible, this means:

  - Simulation state is advanced (positions may change infinitesimally)

  - This is NOT a “dry run” - it mutates physics state

  - For deterministic initial conditions, call this before reading initial state

  Call this function explicitly if you want to:

  - Control exactly when the warmup latency occurs

  - Avoid a latency spike on the first tensor read

  - Verify GPU initialization succeeded before starting your main loop

  - Ensure deterministic behavior by controlling when state mutation happens

  This function is idempotent - calling it multiple times has no effect after the first successful call (per stage). In CPU mode, this is a no-op.

  Note: Warmup state is reset when the stage changes (e.g., after ovphysx_reset_stage() or loading a new USD file). The next tensor read will trigger warmup again.

      ovphysx_warmup_gpu(handle);

  Side Effects

    Advances simulation by a minimal timestep in GPU mode.

  Errors

    - OVPHYSX_API_GPU_NOT_AVAILABLE if GPU initialization fails

    - OVPHYSX_API_ERROR for internal failures

  Parameters:

    handle – Instance handle

  Returns:

    ovphysx_result_t

  Pre:

    handle must be valid.

  Post:

    GPU warmup completed for the active stage (if in GPU mode).

ovphysx_result_t ovphysx_write_tensor_binding(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,
  const DLTensor *src_tensor,
  const DLTensor *index_tensor,

)

  Write data from a user-provided DLTensor into the simulation (synchronous).

  Not all tensor types are writable:

  - RIGID_BODY_FORCE_F32, RIGID_BODY_WRENCH_F32, ARTICULATION_LINK_WRENCH_F32 are WRITE-ONLY (external control inputs applied each step; reading them returns an error).

  - RIGID_BODY_ACCELERATION_F32, RIGID_BODY_INV_MASS_F32, RIGID_BODY_INV_INERTIA_F32 are READ-ONLY.

  - ARTICULATION_LINK_POSE_F32, ARTICULATION_LINK_VELOCITY_F32, ARTICULATION_LINK_ACCELERATION_F32 are READ-ONLY (no setter for individual link state).

  - Dynamics query tensors (JACOBIAN, MASS_MATRIX, CORIOLIS_AND_CENTRIFUGAL_FORCE, GRAVITY_FORCE, LINK_INCOMING_JOINT_FORCE, DOF_PROJECTED_JOINT_FORCE, BODY_INV_MASS, BODY_INV_INERTIA) are READ-ONLY.

  - DEFORMABLE_REST_NODAL_POSITION_F32 and DEFORMABLE_SIM_ELEMENT_INDICES_S32 are READ-ONLY.

  - DOF_ACTUATION_FORCE_F32 is read-write (not write-only). See ovphysx_tensor_type_t documentation for shapes, layouts, and read/write semantics.

  GPU MODE WARNING: On the first GPU tensor write after loading USD, an automatic warmup simulation step may be performed to initialize PhysX DirectGPU buffers. See GPU tensor auto-warmup note.

  This is a blocking call that completes before returning.

      ovphysx_write_tensor_binding(handle, binding, &tensor, NULL);

  Side Effects

    Writes control or state data into the simulation.

  Ownership

    Caller owns src_tensor and index_tensor memory.

  Errors

    - OVPHYSX_API_DEVICE_MISMATCH if tensor device is incompatible

    - OVPHYSX_API_INVALID_ARGUMENT for invalid inputs

    - OVPHYSX_API_NOT_FOUND if the binding is unknown or was invalidated by a stage change

    - OVPHYSX_API_ERROR for internal failures

  Parameters:

    - handle – Instance handle

    - binding_handle – Tensor binding

    - src_tensor – User tensor with data to write (must match ovphysx_get_tensor_binding_spec())

    - index_tensor – Optional int32[K] indices for subset write. NULL = write all.

      - When index_tensor != NULL: src_tensor must still have full shape [N, …] matching the binding spec. Only the rows specified by index_tensor are written; other rows in src_tensor are ignored.

      - Indices are 0-based into the first dimension N of the binding, and must satisfy 0 <= idx < N.

      - K (index count) must satisfy K <= N.

  Returns:

    ovphysx_result_t

  Pre:

    handle and binding_handle must be valid.

  Pre:

    src_tensor must match the spec’s dtype/shape and use a supported device. CPU/CUDA mismatches are staged when CUDA is available; cross-GPU ordinal mismatches and CUDA tensors in process-wide CPU-only mode return OVPHYSX_API_DEVICE_MISMATCH.

  Post:

    Simulation state is updated with new values.

ovphysx_result_t ovphysx_write_tensor_binding_masked(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,
  const DLTensor *src_tensor,
  const DLTensor *mask_tensor,

)

  Write data from a user-provided DLTensor into the simulation using a binary mask (synchronous).

  Only elements where mask[i] != 0 are written; other elements are left unchanged. This is the mask-based alternative to indexed writes via ovphysx_write_tensor_binding.

  GPU MODE WARNING: On the first GPU tensor write after loading USD, an automatic warmup simulation step may be performed to initialize PhysX DirectGPU buffers. See GPU tensor auto-warmup note.

  This is a blocking call that completes before returning.

      ovphysx_write_tensor_binding_masked(handle, binding, &tensor, &mask);

  Side Effects

    Writes control or state data into the simulation for selected elements.

  Ownership

    Caller owns src_tensor and mask_tensor memory.

  Errors

    - OVPHYSX_API_DEVICE_MISMATCH if tensor device is incompatible

    - OVPHYSX_API_INVALID_ARGUMENT for invalid inputs

    - OVPHYSX_API_NOT_FOUND if the binding is unknown or was invalidated by a stage change

    - OVPHYSX_API_ERROR for internal failures

  Note

  There is intentionally no corresponding read_masked function. Reads always return the full [N,…] tensor via ovphysx_read_tensor_binding(); callers that need a subset can index the result on the host/device side. This write-only mask design matches other reinforcement-learning physics APIs (e.g. Newton’s selectionAPI) where masks are used to selectively apply actions but observations are always returned in full.

  Parameters:

    - handle – Instance handle

    - binding_handle – Tensor binding

    - src_tensor – User tensor with data to write. Must be full shape [N, …] matching the dtype and shape from ovphysx_get_tensor_binding_spec().

    - mask_tensor – Binary mask selecting which elements to update. Must be 1D with shape [N] where N matches the binding’s first dimension. Dtype must be bool (kDLBool, bits=8) or uint8 (kDLUInt, bits=8).

  Returns:

    ovphysx_result_t

  Pre:

    handle and binding_handle must be valid.

  Pre:

    src_tensor must match the dtype/shape of the binding spec and use a supported device.

  Pre:

    mask_tensor must be 1D uint8/bool with length N on a supported device. CPU/CUDA mismatches are staged when CUDA is available; cross-GPU ordinal mismatches and CUDA tensors in process-wide CPU-only mode return OVPHYSX_API_DEVICE_MISMATCH.

  Post:

    Simulation state is updated for masked elements only.

ovphysx_result_t ovphysx_get_articulation_metadata(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,
  ovphysx_articulation_metadata_t *out_metadata,

)

  Get all scalar topology metadata for an articulation binding in one call.

  Fills out_metadata with dof_count, body_count, joint_count, fixed_tendon_count, spatial_tendon_count, and is_fixed_base. All values are stable for the binding lifetime; cache the result if calling more than once.

  Homogeneous topology requirement: all articulations covered by this binding must have the same topology (same dof_count, body_count, joint_count, etc.). This is a fundamental constraint of the native tensor backend &#8212; tensor shapes are fixed at binding creation time. If you need to work with articulations of different sizes (e.g. a 7-DOF arm and a 30-DOF humanoid), create a separate binding for each.

  For name arrays (DOF names, body names, joint names) use the corresponding ovphysx_articulation_get_*_names functions.

      ovphysx_articulation_metadata_t meta;
      ovphysx_get_articulation_metadata(handle, binding, &meta);
      printf("DOFs: %d  Links: %d\n", meta.dof_count, meta.body_count);

  Parameters:

    - handle – Instance handle

    - binding_handle – Tensor binding (must be an articulation binding)

    - out_metadata – [out] Caller-allocated struct to fill

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_articulation_get_dof_names(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,
  ovphysx_string_t *out_names,
  uint32_t max_names,
  uint32_t *out_count,

)

  Get DOF names for the articulation.

  String pointers remain valid until the binding is destroyed.

  Parameters:

    - handle – Instance handle

    - binding_handle – Tensor binding (must be an articulation binding)

    - out_names – [out] Array of ovphysx_string_t to fill

    - max_names – Capacity of out_names array; set to metadata.dof_count (from ovphysx_get_articulation_metadata()) to receive all names.

    - out_count – [out] Actual number of names written

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_articulation_get_body_names(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,
  ovphysx_string_t *out_names,
  uint32_t max_names,
  uint32_t *out_count,

)

  Get body (link) names for the articulation.

  String pointers remain valid until the binding is destroyed.

  Parameters:

    - handle – Instance handle

    - binding_handle – Tensor binding (must be an articulation binding)

    - out_names – [out] Array of ovphysx_string_t to fill

    - max_names – Capacity of out_names array; set to metadata.body_count (from ovphysx_get_articulation_metadata()) to receive all names.

    - out_count – [out] Actual number of names written

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_articulation_get_joint_names(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,
  ovphysx_string_t *out_names,
  uint32_t max_names,
  uint32_t *out_count,

)

  Get joint names for the articulation.

  String pointers remain valid until the binding is destroyed.

  Parameters:

    - handle – Instance handle

    - binding_handle – Tensor binding (must be an articulation binding)

    - out_names – [out] Array of ovphysx_string_t to fill

    - max_names – Capacity of out_names array; set to metadata.joint_count (from ovphysx_get_articulation_metadata()) to receive all names.

    - out_count – [out] Actual number of names written

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_tensor_binding_get_prim_paths(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,
  ovphysx_string_t *out_paths,
  uint32_t max_paths,
  uint32_t *out_count,

)

  Get resolved USD prim paths for a tensor binding.

  The returned array order matches row order for every `RIGID_BODY_*` tensor read/write on the same binding. For `ARTICULATION_*` tensor bindings, the returned paths are articulation root prim paths in the binding’s first-dimension row order. ovphysx owns the returned string storage; string pointers remain valid until the binding is destroyed.

  Parameters:

    - handle – Instance handle

    - binding_handle – Tensor binding

    - out_paths – [out] Array of ovphysx_string_t to fill

    - max_paths – Capacity of out_paths array; must be at least binding count to receive all paths.

    - out_count – [out] Actual number of paths written

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_create_contact_binding(

  ovphysx_handle_t handle,
  const ovphysx_string_t *sensor_patterns,
  uint32_t sensor_patterns_count,
  const ovphysx_string_t *filter_patterns,
  uint32_t filters_per_sensor,
  uint32_t max_contact_data_count,
  ovphysx_contact_binding_handle_t *out_handle,

)

  Create a contact binding for aggregate and detailed contact reads.

      // Track contacts on the robot end-effector against the box obstacle.
      ovphysx_string_t sensors[]  = { ovphysx_cstr("/World/robot_0/ee") };
      ovphysx_string_t filters[]  = { ovphysx_cstr("/World/obstacles/box") };
      ovphysx_contact_binding_handle_t cb;
      ovphysx_create_contact_binding(
          handle,
          sensors, 1,          // 1 sensor pattern
          filters, 1,          // 1 filter pattern per sensor
          256,                 // flat contact-data capacity
          &cb);
      // After a stepping call completes:
      // - net forces  tensor shape: [S, 3]   (S = matched sensor count)
      // - force matrix tensor shape: [S, F, 3] (F = matched filter count per sensor)

  Parameters:

    - handle – Instance handle

    - sensor_patterns – Array of USD prim path patterns matching sensor bodies

    - sensor_patterns_count – Number of sensor patterns

    - filter_patterns – Flat array of filter prim path patterns. All sensors must have the same number of filters. Total length = sensor_patterns_count * filters_per_sensor. Pass NULL with filters_per_sensor=0 for unfiltered contacts.

    - filters_per_sensor – Number of filter patterns per sensor (same for all sensors)

    - max_contact_data_count – Maximum entries in raw or detailed contact/friction flat-buffer reads. Set this to a positive value before using ovphysx_read_contact_data(), ovphysx_read_friction_data(), or ovphysx_read_raw_contact_data(). Filtered detailed reads also require filters_per_sensor > 0. Aggregate net-force reads do not need detailed contact capacity or filters.

    - out_handle – [out] Contact binding handle

  Returns:

    ovphysx_result_t

  Post:

    Binding handle is valid until explicitly destroyed via ovphysx_destroy_contact_binding(), or until the parent instance is destroyed.

ovphysx_result_t ovphysx_destroy_contact_binding(

  ovphysx_handle_t handle,
  ovphysx_contact_binding_handle_t contact_handle,

)

  Destroy a contact binding.

  Parameters:

    - handle – Instance handle

    - contact_handle – Contact binding to destroy

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_get_contact_binding_spec(

  ovphysx_handle_t handle,
  ovphysx_contact_binding_handle_t contact_handle,
  int32_t *out_sensor_count,
  int32_t *out_filter_count,

)

  Query contact view dimensions.

  Parameters:

    - handle – Instance handle

    - contact_handle – Contact binding

    - out_sensor_count – [out] Number of sensor bodies matched

    - out_filter_count – [out] Number of filter bodies per sensor

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_contact_binding_get_sensor_paths(

  ovphysx_handle_t handle,
  ovphysx_contact_binding_handle_t contact_handle,
  ovphysx_string_t *out_paths,
  uint32_t max_paths,
  uint32_t *out_count,

)

  Get resolved sensor USD prim paths for a contact binding.

  The returned array order matches row order for contact binding reads. ovphysx owns the returned string storage; string pointers remain valid until the binding is destroyed.

  Parameters:

    - handle – Instance handle

    - contact_handle – Contact binding

    - out_paths – [out] Array of ovphysx_string_t to fill

    - max_paths – Capacity of out_paths array; must be at least sensor_count to receive all sensor paths.

    - out_count – [out] Actual number of paths written

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_contact_binding_get_filter_paths(

  ovphysx_handle_t handle,
  ovphysx_contact_binding_handle_t contact_handle,
  ovphysx_string_t *out_paths,
  uint32_t max_paths,
  uint32_t *out_count,

)

  Get resolved filter USD prim paths for a contact binding.

  Paths are returned in row-major `[sensor, filter]` order with total count `sensor_count * filter_count`. ovphysx owns the returned string storage; string pointers remain valid until the binding is destroyed.

  Parameters:

    - handle – Instance handle

    - contact_handle – Contact binding

    - out_paths – [out] Array of ovphysx_string_t to fill

    - max_paths – Capacity of out_paths array; must be at least sensor_count * filter_count to receive all filter paths.

    - out_count – [out] Actual number of paths written

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_get_contact_binding_capacity(

  ovphysx_handle_t handle,
  ovphysx_contact_binding_handle_t contact_handle,
  uint32_t *out_max_contact_data_count,

)

  Query raw and detailed contact/friction flat-buffer capacity.

  This is the C dimension for `ovphysx_read_contact_data()`, `ovphysx_read_friction_data()`, and `ovphysx_read_raw_contact_data()` flat buffers. Allocate force/separation buffers as `[C, 1]` and point/normal/friction buffers as `[C, 3]`. Filtered reads use `[S, F]` count/start-index buffers; raw reads use `[S]` count/start-index buffers and `[C]` actor IDs. `S` and `F` come from `ovphysx_get_contact_binding_spec()`.

  Parameters:

    - handle – Instance handle

    - contact_handle – Contact binding

    - out_max_contact_data_count – [out] Raw or detailed contact/friction flat-buffer capacity

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_read_contact_net_forces(

  ovphysx_handle_t handle,
  ovphysx_contact_binding_handle_t contact_handle,
  DLTensor *dst_tensor,

)

  Read net contact forces.

  dst shape: [S, 3] where S = sensor_count.

  The dt for impulse-to-force conversion is taken automatically from the last successful ovphysx_step(), ovphysx_step_sync(), or ovphysx_step_n_sync() call.

  Parameters:

    - handle – Instance handle

    - contact_handle – Contact binding

    - dst_tensor – Pre-allocated DLTensor with shape [S, 3]

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_read_contact_force_matrix(

  ovphysx_handle_t handle,
  ovphysx_contact_binding_handle_t contact_handle,
  DLTensor *dst_tensor,

)

  Read contact force matrix.

  dst shape: [S, F, 3].

  The dt for impulse-to-force conversion is taken automatically from the last successful ovphysx_step(), ovphysx_step_sync(), or ovphysx_step_n_sync() call.

  Parameters:

    - handle – Instance handle

    - contact_handle – Contact binding

    - dst_tensor – Pre-allocated DLTensor with shape [S, F, 3]

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_read_contact_data(

  ovphysx_handle_t handle,
  ovphysx_contact_binding_handle_t contact_handle,
  DLTensor *contact_force_tensor,
  DLTensor *contact_point_tensor,
  DLTensor *contact_normal_tensor,
  DLTensor *contact_separation_tensor,
  DLTensor *contact_count_tensor,
  DLTensor *contact_start_indices_tensor,

)

  Read detailed contact data into flat buffers.

  Required shapes:

  - contact_force_tensor: `[C, 1]` float32

  - contact_point_tensor: `[C, 3]` float32

  - contact_normal_tensor: `[C, 3]` float32

  - contact_separation_tensor: `[C, 1]` float32

  - contact_count_tensor: `[S, F]` int32 or uint32

  - contact_start_indices_tensor: `[S, F]` int32 or uint32

  `C` is `ovphysx_get_contact_binding_capacity()`, `S` is sensor_count, and `F` is filter_count. For each `(sensor, filter)` pair, the valid detailed contact slice is: `start = start_indices[s, f]`, `count = counts[s, f]`, `data[start : start + count]`. `C` and `F` must be positive; pass a positive max_contact_data_count and filters_per_sensor > 0 when creating the binding. Count and start-index tensors may be int32 or uint32.

  If the required number of entries exceeds `C`, this function returns `OVPHYSX_API_BUFFER_TOO_SMALL`. The payload tensors must not be used, but the count and start-index tensors contain the full required layout. Set `max_contact_data_count` to the maximum element of `start_indices + counts` when recreating the binding for subsequent simulation steps. Recreating a binding does not recover the overflowing step’s payload.

  Contact force magnitudes use the timestep from the last successful ovphysx_step(), ovphysx_step_sync(), or ovphysx_step_n_sync() call.

  Parameters:

    - handle – Instance handle

    - contact_handle – Contact binding

    - contact_force_tensor – Pre-allocated contact normal force magnitudes

    - contact_point_tensor – Pre-allocated world-frame contact points

    - contact_normal_tensor – Pre-allocated world-frame contact normals

    - contact_separation_tensor – Pre-allocated contact separations

    - contact_count_tensor – Pre-allocated count matrix

    - contact_start_indices_tensor – Pre-allocated start-index matrix

  Returns:

    ovphysx_result_t. Returns `OVPHYSX_API_BUFFER_TOO_SMALL` when `C` cannot hold all entries.

ovphysx_result_t ovphysx_read_friction_data(

  ovphysx_handle_t handle,
  ovphysx_contact_binding_handle_t contact_handle,
  DLTensor *friction_force_tensor,
  DLTensor *friction_point_tensor,
  DLTensor *contact_count_tensor,
  DLTensor *contact_start_indices_tensor,

)

  Read detailed friction data into flat buffers.

  Required shapes:

  - friction_force_tensor: `[C, 3]` float32

  - friction_point_tensor: `[C, 3]` float32

  - contact_count_tensor: `[S, F]` int32 or uint32

  - contact_start_indices_tensor: `[S, F]` int32 or uint32

  `C`, `S`, and `F` have the same meanings as in `ovphysx_read_contact_data()`. For each `(sensor, filter)` pair, use the count/start-index tensors to index valid entries in the flat friction buffers. `C` and `F` must be positive; pass a positive max_contact_data_count and filters_per_sensor > 0 when creating the binding. Count and start-index tensors may be int32 or uint32.

  If the required number of entries exceeds `C`, this function returns `OVPHYSX_API_BUFFER_TOO_SMALL`. The payload tensors must not be used, but the count and start-index tensors contain the full required layout. Set `max_contact_data_count` to the maximum element of `start_indices + counts` when recreating the binding for subsequent simulation steps. Recreating a binding does not recover the overflowing step’s payload.

  Friction forces use the timestep from the last successful ovphysx_step(), ovphysx_step_sync(), or ovphysx_step_n_sync() call.

  Parameters:

    - handle – Instance handle

    - contact_handle – Contact binding

    - friction_force_tensor – Pre-allocated world-frame friction forces

    - friction_point_tensor – Pre-allocated world-frame friction points

    - contact_count_tensor – Pre-allocated count matrix

    - contact_start_indices_tensor – Pre-allocated start-index matrix

  Returns:

    ovphysx_result_t. Returns `OVPHYSX_API_BUFFER_TOO_SMALL` when `C` cannot hold all entries.

ovphysx_result_t ovphysx_read_raw_contact_data(

  ovphysx_handle_t handle,
  ovphysx_contact_binding_handle_t contact_handle,
  DLTensor *contact_force_tensor,
  DLTensor *contact_point_tensor,
  DLTensor *contact_normal_tensor,
  DLTensor *contact_separation_tensor,
  DLTensor *contact_count_tensor,
  DLTensor *contact_start_indices_tensor,
  DLTensor *other_actor_ids_tensor,

)

  Read raw (unfiltered) contact data for a contact binding.

  Filter-less variant of ovphysx_read_contact_data : returns every contact involving each sensor body regardless of which other actor it collided with, plus a per-contact “other actor ID” lookup so callers can identify the contacting body via ovphysx_contact_binding_get_other_actor_paths_from_ids.

  Required shapes (C = max_contact_data_count, S = sensor_count):

  - contact_force_tensor: `[C, 1]` float32 — contact normal force magnitude

  - contact_point_tensor: `[C, 3]` float32 — contact point in world frame

  - contact_normal_tensor: `[C, 3]` float32 — contact normal in world frame

  - contact_separation_tensor: `[C, 1]` float32 — signed separation

  - contact_count_tensor: `[S]` int32/uint32 — number of contacts per sensor

  - contact_start_indices_tensor:`[S]` int32/uint32 — flat-buffer start index per sensor

  - other_actor_ids_tensor: `[C]` int64/uint64 — opaque actor id for each contact

  The contact binding must be created with `max_contact_data_count > 0`. No filter dimension is required; `filters_per_sensor` may be zero. The dt for impulse-to-force conversion is taken automatically from the last successful ovphysx_step(), ovphysx_step_sync(), or ovphysx_step_n_sync() call.

  If the required number of entries exceeds `C`, this function returns `OVPHYSX_API_BUFFER_TOO_SMALL`. The payload tensors, including `other_actor_ids_tensor`, must not be used, but the count and start-index tensors contain the full required layout. Set `max_contact_data_count` to the maximum element of `start_indices + counts` when recreating the binding for subsequent simulation steps. Recreating a binding does not recover the overflowing step’s payload.

  Parameters:

    - handle – Instance handle

    - contact_handle – Contact binding

    - contact_force_tensor – Pre-allocated contact normal force magnitudes

    - contact_point_tensor – Pre-allocated world-frame contact points

    - contact_normal_tensor – Pre-allocated world-frame contact normals

    - contact_separation_tensor – Pre-allocated contact separations

    - contact_count_tensor – Pre-allocated per-sensor counts

    - contact_start_indices_tensor – Pre-allocated per-sensor start indices

    - other_actor_ids_tensor – Pre-allocated per-contact actor IDs

  Returns:

    ovphysx_result_t. Returns `OVPHYSX_API_BUFFER_TOO_SMALL` when `C` cannot hold all entries.

ovphysx_result_t ovphysx_contact_binding_get_other_actor_paths_from_ids(

  ovphysx_handle_t handle,
  ovphysx_contact_binding_handle_t contact_handle,
  DLTensor *ids_tensor,
  ovphysx_string_t *out_paths,
  uint32_t max_paths,
  uint32_t *out_count,

)

  Resolve actor IDs from ovphysx_read_raw_contact_data to USD prim paths.

  Given a tensor of opaque actor IDs (the `other_actor_ids_tensor` returned by ovphysx_read_raw_contact_data), fills `out_paths` with the corresponding USD prim paths in the same order. IDs whose actors cannot be resolved (e.g. removed since the step) yield empty paths.

  Parameters:

    - handle – Instance handle

    - contact_handle – Contact binding

    - ids_tensor – Input tensor of actor IDs (`[N]` int64/uint64)

    - out_paths – [out] Array of ovphysx_string_t to fill. ovphysx owns the returned string storage; pointers remain valid until the next call to this function on the same binding (which replaces the cache) or until the binding is destroyed.

    - max_paths – Capacity of `out_paths` array.

    - out_count – [out] Actual number of paths written.

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_get_contact_report(

  ovphysx_handle_t handle,
  const ovphysx_contact_event_header_t **out_event_headers,
  uint32_t *out_num_event_headers,
  const ovphysx_contact_point_t **out_contact_data,
  uint32_t *out_num_contact_data,
  const ovphysx_friction_anchor_t **out_friction_anchors,
  uint32_t *out_num_friction_anchors,

)

  Get raw contact report data for the current simulation step.

  Returns per-contact-point event data &#8212; position, normal, impulse, and separation for every contact point this step. Use this for custom contact sensors, collision debugging, or per-point force analysis.

  For aggregate force tensors (net forces or force matrices between sensor/filter body sets, delivered as DLPack tensors), see the Contact Binding API: ovphysx_create_contact_binding().

  The header array describes contact pairs (which actors/colliders are in contact); each header references a slice of the contact data array containing per-contact-point information (position, normal, impulse, separation).

  Prims involved in contacts must have `PhysxContactReportAPI` applied in the USD stage for contacts to be reported.

  Ownership: The caller does NOT own the returned arrays. They are read-only views into internal simulation buffers. Copy any data you need to keep beyond the current step.

  Pointer lifetime / invalidation: The returned pointers are valid only until the next call that advances or tears down the simulation. The following operations invalidate both arrays:

  - ovphysx_step() (the next simulation step overwrites the buffers)

  - ovphysx_reset_stage()

  - ovphysx_destroy_instance()

  Parameters:

    - handle – Instance handle.

    - out_event_headers – [out] Receives a pointer to the contact event header array (read-only, valid until next step).

    - out_num_event_headers – [out] Number of headers in the array.

    - out_contact_data – [out] Receives a pointer to the contact point array (read-only, valid until next step).

    - out_num_contact_data – [out] Number of contact point entries.

    - out_friction_anchors – [out] Optional. If non-NULL, receives a pointer to the friction anchor array. Each anchor has position[3] and impulse[3] in world space. Pass NULL to skip.

    - out_num_friction_anchors – [out] Optional. If non-NULL, receives the friction anchor count. Pass NULL to skip.

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_get_physx_ptr(

  ovphysx_handle_t handle,
  ovphysx_string_t prim_path,
  ovphysx_physx_type_t physx_type,
  void **out_ptr,

)

  Get a raw PhysX SDK object pointer by USD prim path and type.

  Returns the underlying PhysX object as an opaque `void*`. The caller must cast to the appropriate PhysX C++ type (see ovphysx_physx_type_t).

  A single function covers all PhysX object types &#8212; no per-type variants are needed.

  Pointer lifetime: Returned pointers are valid until the next call to ovphysx_reset_stage() or ovphysx_destroy(). Calls to ovphysx_step() do NOT invalidate existing pointers. Do not call `release()` on returned pointers &#8212; ovphysx owns them.

  Thread safety: PhysX APIs on returned pointers must only be called between simulation steps &#8212; specifically after wait_op() completes for the preceding step and before the next ovphysx_step() call. Calling PhysX APIs while a step is in-flight is a data race.

  Shapes: PxShape objects are reachable from a PxRigidActor pointer via `PxRigidActor::getShapes()`. You can also query them directly with `OVPHYSX_PHYSX_TYPE_SHAPE`.

  PhysX SDK headers: Casting the returned pointer requires the PhysX SDK C++ headers (e.g. `PxScene.h`, `PxRigidDynamic.h`). The ovphysx SDK ships these headers under `include/physx/`; `find_package(ovphysx)` sets `ovphysx_PHYSX_INCLUDE_DIR` to point there. No PhysX library linking is needed. ovphysx bundles PhysX 5.x &#8212; obtain matching headers from the open-source repository at https://github.com/NVIDIA-Omniverse/PhysX (same repo that contains ovphysx). Use the headers from the same commit/release as the ovphysx build to ensure ABI compatibility.

      void* scene = NULL;
      ovphysx_result_t r = ovphysx_get_physx_ptr(
          handle, OVPHYSX_LITERAL("/World/physicsScene"),
          OVPHYSX_PHYSX_TYPE_SCENE, &scene);
      if (r.status == OVPHYSX_API_SUCCESS && scene) {
          // Cast: physx::PxScene* pxScene = static_cast<physx::PxScene*>(scene);
      }

  Parameters:

    - handle – ovphysx instance handle.

    - prim_path – USD prim path (ovphysx_string_t; e.g. “/World/physicsScene”, “/World/Cube”, “/World/articulation”). Embedded NUL bytes are rejected.

    - physx_type – Which PhysX object type to look up at that path. See ovphysx_physx_type_t for the mapping to PhysX C++ types.

    - out_ptr – [out] Receives the PhysX pointer (NULL if not found).

  Returns:

    ovphysx_result_t with status and error info.

  Pre:

    A USD stage must be loaded and at least one simulation step completed (so PhysX objects exist). prim_path must be a valid absolute USD path.

ovphysx_result_t ovphysx_get_object_type(

  ovphysx_handle_t handle,
  ovphysx_string_t prim_path,
  ovphysx_object_type_t *out_type,

)

  Classify a prim by its high-level TensorAPI object type.

  Returns the umbrella’s view of what kind of simulation object lives at `prim_path`: rigid body, articulation, articulation link, articulation root link, articulation joint, or invalid. Unresolved paths yield `OVPHYSX_OBJECT_TYPE_INVALID` with `OVPHYSX_API_SUCCESS` (the call itself didn’t fail, the path just isn’t a known simulation object).

  Parameters:

    - handle – Instance handle (must have a stage attached)

    - prim_path – USD prim path (ovphysx_string_t; embedded NUL bytes are rejected)

    - out_type – [out] Receives the object type

  Returns:

    OVPHYSX_API_SUCCESS on success, or OVPHYSX_API_ERROR if no stage is attached or the TensorAPI simulation view cannot be created.

ovphysx_result_t ovphysx_articulation_update_kinematic(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,
  uint32_t flags,

)

  Force kinematic propagation of root + DOF state into link buffers for every articulation in the binding, without running a sim step.

  Mirrors PhysX SDK’s `physx::PxArticulationReducedCoordinate::updateKinematic`. The umbrella’s `SimulationView.update_articulations_kinematic()` calls this after writing dof-positions / root-transforms to flush the new state into the link buffer so the next read-back of link transforms reflects the writes without simulating.

  Parameters:

    - handle – Instance handle

    - binding_handle – Articulation tensor binding identifying the set of articulations to update.

    - flags – Bitwise OR of ovphysx_articulation_kinematic_flag_t values. Pass `OVPHYSX_ARTICULATION_KINEMATIC_POSITION` to propagate positions only, OR with VELOCITY to propagate both.

  Returns:

    OVPHYSX_API_SUCCESS on success, OVPHYSX_API_INVALID_ARGUMENT if the binding is not an articulation binding, OVPHYSX_API_ERROR on engine failure or if one or more articulations in the binding could not be resolved (e.g. removed from the live stage).

ovphysx_result_t ovphysx_rigid_body_view_wake_up(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,
  const DLTensor *indices,

)

  Wake rigid bodies in a binding.

  Mirrors PhysX SDK’s `physx::PxRigidDynamic::wakeUp`. Bodies that still have `physx::PxActorFlag::eDISABLE_SIMULATION` set are silently skipped (the engine refuses to wake disabled actors).

  Typical pair: clear OVPHYSX_TENSOR_RIGID_BODY_DISABLE_SIMULATION_BOOL on an actor (re-add to simulation), then call this to bring the actor active for the next simulate &#8212; otherwise it sits in the sleep state PhysX placed it in when the flag was first set.

  Parameters:

    - handle – Instance handle

    - binding_handle – Rigid body tensor binding identifying the set of bodies in scope.

    - indices – Optional int32 DLTensor of indices into the binding, or NULL to wake every body in the binding.

  Returns:

    OVPHYSX_API_SUCCESS, OVPHYSX_API_INVALID_ARGUMENT if the binding is not a rigid-body binding, OVPHYSX_API_NOT_FOUND if the binding has been invalidated by a stage change, OVPHYSX_API_ERROR on engine failure.

ovphysx_result_t ovphysx_rigid_body_view_sleep(

  ovphysx_handle_t handle,
  ovphysx_tensor_binding_handle_t binding_handle,
  const DLTensor *indices,

)

  Force rigid bodies in a binding to sleep.

  Mirrors PhysX SDK’s `physx::PxRigidDynamic::putToSleep`. Sets the sleep state on each body so it is excluded from the next solve unless woken by a contact or an explicit ovphysx_rigid_body_view_wake_up call. Bodies that have `physx::PxActorFlag::eDISABLE_SIMULATION` set are silently skipped.

  Parameters:

    - handle – Instance handle

    - binding_handle – Rigid body tensor binding identifying the set of bodies in scope.

    - indices – Optional int32 DLTensor of indices into the binding, or NULL to put every body in the binding to sleep.

  Returns:

    OVPHYSX_API_SUCCESS, OVPHYSX_API_INVALID_ARGUMENT if the binding is not a rigid-body binding, OVPHYSX_API_NOT_FOUND if the binding has been invalidated by a stage change, OVPHYSX_API_ERROR on engine failure.

ovphysx_result_t ovphysx_subscribe_object_changes(

  const ovphysx_object_change_callbacks_t *callbacks,
  ovphysx_subscription_id_t *out_subscription,

)

  Subscribe to PhysX object create/destroy notifications.

  Pair with ovphysx_get_physx_ptr() to manage the lifetime of cached PhysX SDK pointers. On a destruction notification the caller MUST drop the cached pointer before returning from the callback. On a creation notification the caller should mark the prim path as dirty in their own cache and call ovphysx_get_physx_ptr() to fetch the new pointer ONLY after the triggering synchronous call returns, or after ovphysx_wait_op() returns for async work &#8212; never from inside the callback itself (see Threading below).

  Subscriptions are PROCESS-GLOBAL, not per-instance. A single subscription receives events from every ovphysx instance in the process. Multi-instance callers that need to filter by stage must do so on their side &#8212; the prim_path delivered to the callback is the only identifier available. The handle parameter is intentionally absent.

  Lifecycle: callbacks fire for changes that occur during simulation and ovphysx_reset_stage()’s bulk teardown. The initial object population from ovstage attach/update is NOT notified &#8212; the caller already has that state from setup.

  Known limitation: ovphysx_clone() does NOT currently fire object_created notifications. Pointer caches that need to track cloned objects must be refreshed after ovphysx_wait_op() returns on the clone operation, not via this subscription. ovphysx_reset_stage() (and the all-objects-destroyed callback) is the supported path for bulk pointer invalidation.

  Threading: callbacks may fire from internal worker threads. Do NOT call other ovphysx APIs from inside a callback &#8212; defer that until the triggering synchronous call returns, or until ovphysx_wait_op() returns for async work. See the docstring on ovphysx_object_change_callbacks_t for the full contract.

  Failure modes:

  - OVPHYSX_API_INVALID_ARGUMENT if callbacks or out_subscription is NULL, or if every callback function pointer in the struct is NULL.

  - OVPHYSX_API_ERROR if the physics runtime is not available (e.g. no ovphysx instance has been created yet).

  On failure, *out_subscription is set to OVPHYSX_INVALID_SUBSCRIPTION_ID.

  Parameters:

    - callbacks – [in] Pointer to the callback set. The struct is copied internally; the caller does not need to keep it alive after this call returns.

    - out_subscription – [out] Receives the subscription ID on success. Pass this to ovphysx_unsubscribe_object_changes() to stop receiving notifications.

  Returns:

    OVPHYSX_API_SUCCESS on success, or an error status.

ovphysx_result_t ovphysx_unsubscribe_object_changes(

  ovphysx_subscription_id_t subscription,

)

  Unsubscribe from PhysX object change notifications.

  Stops delivery of further notifications for the given subscription ID. After this call returns the subscription ID is consumed and must not be reused.

  Idempotency: passing an already-unsubscribed or unknown subscription ID returns OVPHYSX_API_NOT_FOUND. OVPHYSX_INVALID_SUBSCRIPTION_ID is rejected with OVPHYSX_API_INVALID_ARGUMENT.

  Parameters:

    subscription – Subscription ID returned from ovphysx_subscribe_object_changes().

  Returns:

    OVPHYSX_API_SUCCESS on success, or an error status.

ovphysx_result_t ovphysx_raycast(

  ovphysx_handle_t handle,
  const float origin[3],
  const float direction[3],
  float distance,
  bool both_sides,
  ovphysx_scene_query_mode_t mode,
  const ovphysx_scene_query_hit_t **out_hits,
  uint32_t *out_count,

)

  Cast a ray and return hits.

      const ovphysx_scene_query_hit_t* hits = NULL;
      uint32_t count = 0;
      float origin[3] = {0, 10, 0};
      float dir[3]    = {0, -1, 0};
      ovphysx_raycast(handle, origin, dir, 100.0f, false,
                      OVPHYSX_SCENE_QUERY_MODE_CLOSEST, &hits, &count);
      if (count > 0) {
          printf("Hit at distance %f\n", hits[0].distance);
      }

  Parameters:

    - handle – Instance handle.

    - origin – Ray origin (world space, 3 floats).

    - direction – Normalized ray direction (3 floats).

    - distance – Maximum ray distance. Must be >= 0.

    - both_sides – If true, test both sides of mesh triangles.

    - mode – CLOSEST (0 or 1 hit), ANY (0 or 1), or ALL.

    - out_hits – [out] Receives pointer to internal hit array.

    - out_count – [out] Number of hits in the array.

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_sweep(

  ovphysx_handle_t handle,
  const ovphysx_scene_query_geometry_desc_t *geometry,
  const float direction[3],
  float distance,
  bool both_sides,
  ovphysx_scene_query_mode_t mode,
  const ovphysx_scene_query_hit_t **out_hits,
  uint32_t *out_count,

)

  Sweep a geometry shape along a direction and return hits.

  Parameters:

    - handle – Instance handle.

    - geometry – Geometry descriptor (sphere, box, or arbitrary shape).

    - direction – Normalized sweep direction (3 floats).

    - distance – Maximum sweep distance. Must be >= 0.

    - both_sides – If true, test both sides of mesh triangles.

    - mode – CLOSEST (0 or 1 hit), ANY (0 or 1), or ALL.

    - out_hits – [out] Receives pointer to internal hit array.

    - out_count – [out] Number of hits in the array.

  Returns:

    ovphysx_result_t

ovphysx_result_t ovphysx_overlap(

  ovphysx_handle_t handle,
  const ovphysx_scene_query_geometry_desc_t *geometry,
  ovphysx_scene_query_mode_t mode,
  const ovphysx_scene_query_hit_t **out_hits,
  uint32_t *out_count,

)

  Test geometry overlap against objects in the scene.

  Overlap queries do not have a direction or distance. Location fields in the hit struct (normal, position, distance, face_index, material) are zeroed &#8212; only object identity (collision, rigid_body, proto_index) is populated.

  Parameters:

    - handle – Instance handle.

    - geometry – Geometry descriptor (sphere, box, or arbitrary shape).

    - mode – ANY (0 or 1 result) or ALL. CLOSEST is treated as ALL.

    - out_hits – [out] Receives pointer to internal hit array.

    - out_count – [out] Number of hits (or overlaps) in the array.

  Returns:

    ovphysx_result_t

ovphysx_enqueue_result_t ovphysx_add_user_task(

  ovphysx_handle_t handle,
  const ovphysx_user_task_desc_t *desc,

)

ovphysx_result_t ovphysx_wait_op(

  ovphysx_handle_t handle,
  ovphysx_op_index_t op_index,
  uint64_t timeout_ns,
  ovphysx_op_wait_result_t *out_wait_result,

)

ovphysx_string_t ovphysx_get_last_error(void)

  Query the error string for the last failed API call on the calling thread.

  The returned string is valid until the next ovphysx API call on the same thread. Returns {NULL, 0} if the last call succeeded.

      ovphysx_result_t r = ovphysx_create_instance(&args, &handle);
      if (r.status != OVPHYSX_API_SUCCESS) {
          ovphysx_string_t err = ovphysx_get_last_error();
          if (err.ptr)
              fprintf(stderr, "Error: %.*s\n", (int)err.length, err.ptr);
      }

  Threading

    Thread-local storage; safe to call from any thread.

  Returns:

    ovphysx_string_t with the error message, or {NULL, 0} on success.

ovphysx_string_t ovphysx_get_last_op_error(

  ovphysx_op_index_t op_index,

)

  Query the error string for a specific failed op_index from the last wait_op call.

  After ovphysx_wait_op() reports failed operations via error_op_indices, call this function for each failed op_index to retrieve the error message. The returned string is valid until the next ovphysx_wait_op() call on the same thread.

      for (size_t i = 0; i < wait_result.num_errors; ++i) {
          ovphysx_string_t err = ovphysx_get_last_op_error(wait_result.error_op_indices[i]);
          fprintf(stderr, "Op %llu failed: %.*s\n",
                  wait_result.error_op_indices[i], (int)err.length, err.ptr);
      }

  Threading

    Thread-local storage; safe to call from any thread.

  Parameters:

    op_index – The failed operation index (from ovphysx_op_wait_result_t.error_op_indices).

  Returns:

    ovphysx_string_t with the error message, or {NULL, 0} if op_index has no error.

void ovphysx_destroy_wait_result(ovphysx_op_wait_result_t *result)

  Free the error_op_indices array in an ovphysx_op_wait_result_t.

  Call this after processing the wait result to release the dynamically allocated error_op_indices array.

      ovphysx_destroy_wait_result(&wait_result);

  Parameters:

    result – Pointer to the wait result to clean up (NULL-safe).

  Pre:

    Safe to call with NULL or already-cleaned result.

  Post:

    result->error_op_indices is NULL and num_errors is 0.

ovphysx_result_t ovphysx_set_log_level(uint32_t level)

  Set the global log level threshold.

  Messages below this level are suppressed for all outputs (console and registered callbacks). Callable at any time. If called before instance creation, the level is stored and applied when Carbonite initializes.

  Threading

    Thread-safe. Uses atomic storage internally.

  Parameters:

    level – Log level threshold (ovphysx_log_level_t). Default: OVPHYSX_LOG_WARNING. Must be between OVPHYSX_LOG_VERBOSE and OVPHYSX_LOG_NONE inclusive.

  Returns:

    ovphysx_result_t with OVPHYSX_API_SUCCESS on success, or OVPHYSX_API_INVALID_ARGUMENT if the level was out of range (no state change is applied).

uint32_t ovphysx_get_log_level(void)

  Get the current global log level threshold.

  Threading

    Thread-safe. Uses atomic load internally.

  Returns:

    The current log level (ovphysx_log_level_t).

ovphysx_result_t ovphysx_enable_default_log_output(bool enable)

  Enable or disable Carbonite’s built-in console log output.

  By default, Carbonite logs to the console (stdout/stderr). When custom callbacks are registered via ovphysx_register_log_callback(), both the built-in console output and the custom callbacks receive messages, which may cause duplicate output if the callback also writes to the console.

  Call this function with `false` to suppress the built-in console output while keeping custom callbacks active. Call with `true` to re-enable it.

  This function is independent of callback registration and the global log level &#8212; it only controls the built-in console logger.

  Callable at any time. If called before Carbonite initializes, the preference is stored and applied during initialization.

  Threading

    Thread-safe. Uses atomic storage internally.

  Parameters:

    enable – `true` to enable (default), `false` to disable.

  Returns:

    ovphysx_result_t with OVPHYSX_API_SUCCESS.

ovphysx_result_t ovphysx_register_log_callback(

  ovphysx_log_fn fn,
  void *user_data,

)

  Register a log callback.

  Multiple callbacks may be registered simultaneously. Each receives all messages at or above the global log level threshold. The caller must ensure `fn` and any resources referenced by `user_data` remain valid until ovphysx_unregister_log_callback() is called. If the callback and its resources naturally outlive the process (e.g. a static function with no user_data), calling ovphysx_unregister_log_callback() is not required.

  Registering the same `fn` and `user_data` pair twice returns OVPHYSX_API_INVALID_ARGUMENT. Use different `user_data` values to register the same function pointer multiple times.

  Note

  The callback may be invoked from any thread. The implementation is thread-safe, but the callback itself must also be thread-safe.

  Note

  Must not be called from within a log callback. Returns OVPHYSX_API_ERROR if called during callback dispatch.

  Parameters:

    - fn – Callback function pointer (must not be NULL).

    - user_data – Opaque pointer forwarded to every callback invocation (may be NULL).

  Returns:

    ovphysx_result_t with status.

ovphysx_result_t ovphysx_unregister_log_callback(

  ovphysx_log_fn fn,
  void *user_data,

)

  Unregister a previously registered log callback.

  Both `fn` and `user_data` must match the values passed to ovphysx_register_log_callback(). After this function returns, the callback is guaranteed to not be running on any thread and will never be invoked again. The caller may safely destroy the callback context.

  Note

  Must not be called from within a log callback. Returns OVPHYSX_API_ERROR if called during callback dispatch.

  Parameters:

    - fn – Callback function pointer.

    - user_data – Opaque pointer that was passed during registration (may be NULL).

  Returns:

    ovphysx_result_t with OVPHYSX_API_SUCCESS if found and removed.

ovphysx_result_t ovphysx_create_sdf_view(

  ovphysx_handle_t handle,
  ovphysx_string_t pattern,
  uint32_t max_query_points,
  ovphysx_sdf_view_handle_t *out_handle,

)

  Create an SDF shape view for shapes matching the given pattern.

  The view evaluates the signed distance field of PhysX collision shapes at caller-supplied query points. Requires a GPU instance; CPU SDF evaluation is not yet implemented and create will fail for CPU instances.

  The returned handle must be released with ovphysx_destroy_sdf_view when no longer needed. The handle is invalidated when the attached USD stage changes (ovphysx_reset_stage, ovphysx_detach_ovstage, or loading a new stage) or when the instance is destroyed (via ovphysx_destroy) even if ovphysx_destroy_sdf_view is not called explicitly. After invalidation, evaluate/get calls return OVPHYSX_API_NOT_FOUND; recreate the view after re-attaching a stage.

  Thread safety: safe to call concurrently with other ovphysx API functions on the same handle, but not concurrently with ovphysx_destroy on the same handle.

  Parameters:

    - handle – Instance handle.

    - pattern – USD glob pattern selecting SDF-enabled collision shapes (e.g. “/World/Mesh*”). Must match at least one shape or the call returns an error.

    - max_query_points – Number of query points per shape per evaluate call. Query tensors passed to ovphysx_evaluate_sdf must have Q == this value (second dimension). Must be > 0.

    - out_handle – Receives the new SDF view handle on success. Set to 0 on failure.

  Returns:

    OVPHYSX_API_SUCCESS or an error code.

ovphysx_result_t ovphysx_sdf_view_get_count(

  ovphysx_handle_t handle,
  ovphysx_sdf_view_handle_t sdf_handle,
  uint32_t *out_count,

)

  Return the number of shapes in the SDF view (N, first dimension of query tensors).

  Parameters:

    - handle – Instance handle.

    - sdf_handle – SDF view handle from ovphysx_create_sdf_view.

    - out_count – Receives the shape count on success.

  Returns:

    OVPHYSX_API_SUCCESS, OVPHYSX_API_INVALID_ARGUMENT if out_count is NULL, OVPHYSX_API_NOT_FOUND if sdf_handle is not valid.

ovphysx_result_t ovphysx_sdf_view_get_max_query_points(

  ovphysx_handle_t handle,
  ovphysx_sdf_view_handle_t sdf_handle,
  uint32_t *out_max_query_points,

)

  Return the max_query_points value this view was created with (Q, second dimension).

  Parameters:

    - handle – Instance handle.

    - sdf_handle – SDF view handle from ovphysx_create_sdf_view.

    - out_max_query_points – Receives the max query points on success.

  Returns:

    OVPHYSX_API_SUCCESS, OVPHYSX_API_INVALID_ARGUMENT if out_max_query_points is NULL, OVPHYSX_API_NOT_FOUND if sdf_handle is not valid.

ovphysx_result_t ovphysx_evaluate_sdf(

  ovphysx_handle_t handle,
  ovphysx_sdf_view_handle_t sdf_handle,
  const DLTensor *query_points,
  DLTensor *out_distances_and_gradients,

)

  Evaluate the SDF at query points and write distances + gradients.

  DLTensor requirements: query_points:

  - shape: [N, Q, 3] where N = shape count, Q == max_query_points

  - dtype: float32

  - device: GPU (kDLCUDA) out_distances_and_gradients:

  - shape: [N, Q, 4] &#8212; component layout: (grad.x, grad.y, grad.z, distance)

  - dtype: float32

  - device: same as query_points

  - must be pre-allocated with the correct shape

  Parameters:

    - handle – Instance handle.

    - sdf_handle – SDF view handle from ovphysx_create_sdf_view.

    - query_points – Query point tensor [N, Q, 3].

    - out_distances_and_gradients – Output tensor [N, Q, 4].

  Returns:

    OVPHYSX_API_SUCCESS or an error code.

ovphysx_result_t ovphysx_destroy_sdf_view(

  ovphysx_handle_t handle,
  ovphysx_sdf_view_handle_t sdf_handle,

)

  Destroy an SDF view and release its resources.

  Idempotent: returns OVPHYSX_API_SUCCESS if the view was already destroyed or removed by stage reset/detach cleanup. After this call the handle is invalid and must not be used for evaluate/read paths.

  Parameters:

    - handle – Instance handle.

    - sdf_handle – SDF view handle from ovphysx_create_sdf_view.

  Returns:

    OVPHYSX_API_SUCCESS, or OVPHYSX_API_ERROR on invalid instance handle.

ovphysx_result_t ovphysx_debug_render_enable(

  ovphysx_handle_t handle,
  bool enable,

)

  Enable or disable debug-render generation.

  Enables debug geometry for every body, shape and joint in the scene, applies the master scale and the current parameter set. Re-call after a scene rebuild or reset. Read the generated geometry with ovphysx_debug_render_get_points / _lines / _triangles.

  Parameters:

    - handle – Simulator instance (drives the attached stage).

    - enable – true to start generating debug geometry, false to stop.

  Returns:

    OVPHYSX_API_SUCCESS (also a no-op SUCCESS when the viz interface is unavailable); OVPHYSX_API_ERROR when no USD stage is attached.

ovphysx_result_t ovphysx_debug_render_set_parameter(

  ovphysx_handle_t handle,
  uint32_t param,
  float value,

)

  Set one debug-geometry parameter.

  0 disables the geometry type and a positive value enables it. For parameters whose PhysX semantics define a magnitude, that value scales the geometry together with the master scale. CONTACT_POINT and FRICTION_POINT use a positive value only as an enable gate; their marker size follows the master scale. Geometry with an inherent shape (collision shapes, bounds) is drawn at that shape’s dimensions.

  Parameters:

    - handle – Simulator instance (drives the attached stage).

    - param – One of ovphysx_debug_render_parameter_t. NONE (0) and values >= OVPHYSX_DEBUG_RENDER_PARAM_COUNT are rejected.

    - value – Finite value >= 0; 0 disables and a positive value enables.

  Returns:

    OVPHYSX_API_INVALID_ARGUMENT if param is out of range or value is non-finite or negative; OVPHYSX_API_ERROR when no USD stage is attached; otherwise OVPHYSX_API_SUCCESS (a no-op SUCCESS when debug rendering is unavailable).

ovphysx_result_t ovphysx_debug_render_set_scope_tokens(

  ovphysx_handle_t handle,
  const ovx_primpath_t *tokens,
  uint32_t count,

)

  Limit debug rendering to an exact set of interned prim paths.

  An object is in scope when its interned prim path is one of the handles (exact membership, NO prefix expansion). Build the list through the attached Stage’s path_dictionary_instance_t or from a query’s prim list; expand a hierarchy into its exact object set on the caller side (that is a helper’s job, not this call’s). count 0 clears the scope. Joints follow their attached bodies. The scope applies immediately to currently instantiated runtime objects; reapply it after runtime topology changes. Out-of-scope objects are skipped at emission.

  Requires an OVStage attached through ovphysx_attach_ovstage (the path dictionary lives there). Handles are valid only for that exact dictionary, require no per-handle release, and the scope is cleared automatically by ovphysx_detach_ovstage. Re-intern and reapply the scope after attaching a different Stage. Returns OVPHYSX_API_ERROR when the sidecar symbol, visualization slot, or attached Stage dictionary is unavailable. Scope state remains unchanged on every error.

  Parameters:

    - handle – Simulator instance (drives the attached stage).

    - tokens – Array of count interned ovx_primpath_t handles from the attached Stage’s dictionary. May be NULL when count is 0.

    - count – Number of entries; 0 clears the scope.

  Returns:

    OVPHYSX_API_INVALID_ARGUMENT when tokens is NULL with count > 0 or any token is invalid; OVPHYSX_API_ERROR when the sidecar symbol, visualization slot, or attached Stage dictionary is unavailable.

ovphysx_result_t ovphysx_debug_render_get_parameter(

  ovphysx_handle_t handle,
  uint32_t param,
  float *out_value,

)

  Read back a debug-render parameter’s value.

  Returns the value last set through ovphysx_debug_render_set_parameter, cached on the OvPhysX side (the debug-render state is process-global; 0 = off, the default before any set).

  Parameters:

    - handle – Instance handle.

    - param – One of ovphysx_debug_render_parameter_t (NONE / out-of-range rejected).

    - out_value – [out] Set to the cached value. Must be non-NULL.

  Returns:

    OVPHYSX_API_INVALID_ARGUMENT if param is NONE / out of range or out_value is NULL.

ovphysx_result_t ovphysx_debug_render_set_scale(

  ovphysx_handle_t handle,
  float scale,

)

  Set the master PhysX debug-render scale.

  Parameters:

    - handle – Simulator instance (drives the attached stage).

    - scale – Must be finite and >= 0.

  Returns:

    OVPHYSX_API_INVALID_ARGUMENT if scale is non-finite or negative; OVPHYSX_API_ERROR when no USD stage is attached; otherwise OVPHYSX_API_SUCCESS.

ovphysx_result_t ovphysx_debug_render_get_scale(

  ovphysx_handle_t handle,
  float *out_scale,

)

  Read back the master debug-render scale last set through OvPhysX (cached; defaults to 1.0 before any set).

  Parameters:

    - handle – Instance handle.

    - out_scale – [out] Set to the cached scale. Must be non-NULL.

  Returns:

    OVPHYSX_API_INVALID_ARGUMENT if out_scale is NULL.

ovphysx_result_t ovphysx_debug_render_set_culling_box(

  ovphysx_handle_t handle,
  const float min3[3],
  const float max3[3],

)

  Restrict debug-render generation to a world-space AABB.

  Parameters:

    - handle – Simulator instance (drives the attached stage).

    - min3 – Box minimum, float[3]. Must be non-NULL and finite.

    - max3 – Box maximum, float[3]. Must be non-NULL, finite, and >= min3 per axis.

  Returns:

    OVPHYSX_API_INVALID_ARGUMENT if min3/max3 is NULL, non-finite, or min > max; OVPHYSX_API_ERROR when no USD stage is attached; otherwise OVPHYSX_API_SUCCESS.

ovphysx_result_t ovphysx_debug_render_get_points(

  ovphysx_handle_t handle,
  const ovphysx_debug_point_t **out_points,
  uint32_t *out_count,

)

  Read the current debug-render point buffer (the debug geometry produced during the step).

  OvPhysX has no viewer; draw it yourself.

  Ownership / lifetime: the returned pointer aliases an OvPhysX-owned buffer and is invalidated by the next ovphysx_step() OR by any stage / scene change (ovphysx_reset_stage, ovphysx_update_from_ovstage, ovphysx_detach_ovstage, ovphysx_destroy_instance): the underlying PhysX scenes and debug buffers may be recreated. Copy out before any of those; do not hold the pointer across a step or re-attach. On success-with-no-data *out_points is set to NULL and *out_count to 0.

  Parameters:

    - handle – Instance handle.

    - out_points – [out] Set to the buffer base (NULL when empty). Must be non-NULL.

    - out_count – [out] Set to the primitive count (0 when empty). Must be non-NULL.

  Returns:

    OVPHYSX_API_INVALID_ARGUMENT if out_points or out_count is NULL; OVPHYSX_API_ERROR when no USD stage is attached; otherwise OVPHYSX_API_SUCCESS.

ovphysx_result_t ovphysx_debug_render_get_lines(

  ovphysx_handle_t handle,
  const ovphysx_debug_line_t **out_lines,
  uint32_t *out_count,

)

  Read the debug-render line buffer.

  Same ownership / lifetime + argument contract as ovphysx_debug_render_get_points.

ovphysx_result_t ovphysx_debug_render_get_triangles(

  ovphysx_handle_t handle,
  const ovphysx_debug_triangle_t **out_triangles,
  uint32_t *out_count,

)

  Read the debug-render triangle buffer.

  Same ownership / lifetime + argument contract as ovphysx_debug_render_get_points.

## C API Types

Defines

OVPHYSX_LITERAL(s)

  Create ovphysx_string_t from a string LITERAL only.

  For runtime strings (variables, user input), use ovphysx_cstr() instead.

OVPHYSX_INVALID_HANDLE

  Sentinel value representing an invalid/null ovphysx instance handle.

  Valid handles are nonzero, so 0 is reserved to indicate “no handle” or “invalid handle”. Use this when a handle parameter is required but no valid instance is available.

OVPHYSX_OP_INDEX_ALL

  Sentinel value for ovphysx_wait_op to wait for all operations submitted up to the call.

  Use this when you want to ensure all outstanding operations have completed.

OVPHYSX_ATTR_POSITION

  Canonical physics-output attribute names (semantic, not USD attribute names).

  Pass any of these to ovphysx_read(); which names a type produces is documented in the ovstage usage guide.

OVPHYSX_ATTR_ORIENTATION

OVPHYSX_ATTR_LINEAR_VELOCITY

OVPHYSX_ATTR_ANGULAR_VELOCITY

OVPHYSX_ATTR_POINTS

OVPHYSX_ATTR_VELOCITIES

OVPHYSX_ATTR_JOINT_POSITION

OVPHYSX_ATTR_JOINT_VELOCITY

OVPHYSX_INVALID_SUBSCRIPTION_ID

  Sentinel value for an invalid / unset subscription ID.

  Valid subscription IDs are never equal to this value. After calling ovphysx_subscribe_object_changes(), check the returned status code first; only use the out_subscription value when status == OVPHYSX_API_SUCCESS.

OVPHYSX_CREATE_ARGS_DEFAULT

  Default initializer for ovphysx_create_args.

Typedefs

typedef uint64_t ovphysx_handle_t

  One ovphysx simulator instance, created by ovphysx_create_instance.

  Owns its simulation and drives at most one attached USD stage; not per-stage or per-scene.

typedef uint64_t ovphysx_usd_handle_t

typedef uint64_t ovphysx_attribute_binding_handle_t

typedef uint64_t ovphysx_write_map_handle_t

typedef uint64_t ovphysx_read_map_handle_t

typedef uint64_t ovphysx_op_index_t

typedef uint64_t ovphysx_tensor_binding_handle_t

typedef uint64_t ovphysx_contact_binding_handle_t

typedef uint64_t ovphysx_query_handle_t

  Physics-output query (ovphysx_query).

typedef uint64_t ovphysx_read_handle_t

  Physics-output read session (ovphysx_read).

typedef uint64_t ovphysx_sdf_view_handle_t

typedef void (*ovphysx_log_fn)(uint32_t level, const char *message, void *user_data)

  Log callback function type.

  Called for each message that passes the global log level threshold. The caller must ensure the function pointer remains valid until ovphysx_unregister_log_callback() is called.

  Param level:

    The ovphysx_log_level_t severity of the message.

  Param message:

    The log message string (UTF-8, null-terminated). Only valid for the duration of the callback; copy it if you need to retain it after returning.

  Param user_data:

    Opaque pointer passed during registration.

typedef uint64_t ovphysx_subscription_id_t

  Subscription ID returned by ovphysx_subscribe_object_changes().

  Used to identify a subscription for later unsubscribe. Treat as opaque.

typedef void (*ovphysx_object_created_fn)(ovphysx_string_t prim_path, ovphysx_physx_type_t type, void *user_data)

  Notification when a PhysX object is created during simulation.

  Fires AFTER the object exists, so it is safe to call ovphysx_get_physx_ptr() for prim_path / type from a deferred handler.

  Only fires for creations triggered by stage edits during simulation. The initial object population from ovstage attach/update is NOT notified: the caller already has that state from their setup code. See ovphysx_subscribe_object_changes() for the full lifecycle contract.

  Param prim_path:

    Absolute USD prim path of the created object. The underlying storage is owned by ovphysx and only valid for the duration of the callback; copy if you need to retain.

  Param type:

    The PhysX object type of the created object.

  Param user_data:

    Opaque pointer passed during subscription.

typedef void (*ovphysx_object_destroyed_fn)(ovphysx_string_t prim_path, ovphysx_physx_type_t type, void *user_data)

  Notification when a PhysX object is about to be destroyed during simulation.

  Fires BEFORE the object is destroyed. Drop any cached pointer for prim_path / type at this point; do NOT call release() on it (ovphysx owns the lifetime).

  Only fires for destructions that occur during simulation. Bulk teardown (e.g. ovphysx_reset_stage()) is delivered via ovphysx_all_objects_destroyed_fn instead, not as N individual destruction notifications.

  Param prim_path:

    Absolute USD prim path of the soon-to-be-destroyed object. Same lifetime rules as ovphysx_object_created_fn.

  Param type:

    The PhysX object type that is going away.

  Param user_data:

    Opaque pointer passed during subscription.

typedef void (*ovphysx_all_objects_destroyed_fn)(void *user_data)

  Notification when ALL PhysX objects are about to be destroyed in bulk.

  Fires BEFORE the bulk teardown (e.g. on ovphysx_reset_stage()). Subscribers should flush their entire pointer cache; no per-object destruction events will be delivered for this teardown.

  Param user_data:

    Opaque pointer passed during subscription.

typedef ovphysx_result_t (*ovphysx_user_task_fn)(ovphysx_handle_t handle, ovphysx_op_index_t op_index, void *user_data)

  User task callback function type.

  Called in stream order when the task executes.

  Param handle:

    Physics handle

  Param op_index:

    Operation index of this task

  Param user_data:

    User-provided context data

  Return:

    Result status (typically OVPHYSX_API_SUCCESS)

Enums

enum ovphysx_sim_object_type_t

  Simulated object type selected by ovphysx_query().

  This is the engine’s simulated type, not a USD schema predicate.

  Values:

  enumerator OVPHYSX_OBJECT_RIGID_BODY

    dynamic rigid bodies (standalone + point-instancer instances)

  enumerator OVPHYSX_OBJECT_ARTICULATION_LINK

    articulation link body transforms

  enumerator OVPHYSX_OBJECT_ARTICULATION_JOINT

    articulation joint state (per-axis; array group per joint)

  enumerator OVPHYSX_OBJECT_VEHICLE_WHEEL

    vehicle wheel transforms

  enumerator OVPHYSX_OBJECT_DEFORMABLE_VOLUME

    volume deformable meshes (points / velocities)

  enumerator OVPHYSX_OBJECT_DEFORMABLE_SURFACE

    surface deformable meshes

  enumerator OVPHYSX_OBJECT_PARTICLE_SET

    particle sets

enum ovphysx_object_scope_t

  Output query scope.

  Note

  OVPHYSX_SCOPE_ACTIVE is SINGLE-FRAME: the active set is recomputed every step, so a query opened with it (and the groups read from it) is valid only for the step it was opened against; re-query each frame. OVPHYSX_SCOPE_ALL is stable across steps until a structural change (object add/remove, instancer instance-count change).

  Values:

  enumerator OVPHYSX_SCOPE_ALL

    every object of the type

  enumerator OVPHYSX_SCOPE_ACTIVE

    only objects the solver moved last step

enum ovphysx_log_level_t

  The physics output-read surface uses ovstage’s own types directly rather than an ovphysx mirror (so a read group feeds straight back into the ovstage write path with no repack and no translation layer):

  - a read group is an `ovstage_read_group_t` (from ovstage_api_types.h): `data.tensors[0..tensor_count)` are borrowed DLTensors (tuple width in `dtype.lanes`), `prims.list` is the interned prim set, `attribute` is the interned EMITTED attribute token, `semantic` is the authored USD role (`ovstage_attribute_semantic_t`). For this physics-output path `is_delete == false`, `prims.offset == 0`, and a point-instancer always emits the FULL instance array by-index (`data.index_map == NULL`).

  - discovery is an `ovstage_query_result_t` (`attributes` = interned token array; `total_prim_count == 0` is the valid empty-match case).

  - attribute names are `ovx_string_or_token_t` — pass a string (e.g. OVPHYSX_ATTR_POSITION) or an interned token from discovery, no round-trip.

  The queried `ovphysx_sim_object_type_t` is NOT carried on the group: a read is opened over one type, so every group belongs to the type the caller passed to ovphysx_query. Group lifetime is producer-owned (see ovphysx_fetch_read_next).

  Values:

  enumerator OVPHYSX_LOG_VERBOSE

    All messages including verbose/debug (maps to Carbonite kLevelVerbose)

  enumerator OVPHYSX_LOG_INFO

    Info, warnings, and errors.

  enumerator OVPHYSX_LOG_WARNING

    Warnings and errors (default)

  enumerator OVPHYSX_LOG_ERROR

    Error messages only.

  enumerator OVPHYSX_LOG_NONE

    No logging.

enum ovphysx_physx_type_t

  Identifies the type of PhysX object at a USD prim path.

  Used with ovphysx_get_physx_ptr() to retrieve raw PhysX SDK pointers. The named constants below cover common runtime object types. Unknown values return NULL for unrecognized path/type combinations.

  Enum value | PhysX SDK C++ type
  --- | ---
  OVPHYSX_PHYSX_TYPE_SCENE | physx::PxScene
  OVPHYSX_PHYSX_TYPE_MATERIAL | physx::PxMaterial
  OVPHYSX_PHYSX_TYPE_SHAPE | physx::PxShape
  OVPHYSX_PHYSX_TYPE_COMPOUND_SHAPE | Opaque compound-shape wrapper (see note)
  OVPHYSX_PHYSX_TYPE_ACTOR | physx::PxRigidDynamic/PxRigidStatic
  OVPHYSX_PHYSX_TYPE_JOINT | physx::PxJoint (standalone joints)
  OVPHYSX_PHYSX_TYPE_CUSTOM_JOINT | physx::PxJoint (custom joints)
  OVPHYSX_PHYSX_TYPE_ARTICULATION | physx::PxArticulationReducedCoordinate
  OVPHYSX_PHYSX_TYPE_LINK | physx::PxArticulationLink
  OVPHYSX_PHYSX_TYPE_LINK_JOINT | physx::PxArticulationJointReducedCoordinate
  OVPHYSX_PHYSX_TYPE_PARTICLE_SYSTEM | physx::PxPBDParticleSystem
  OVPHYSX_PHYSX_TYPE_PARTICLE_SET | physx::PxParticleBuffer
  OVPHYSX_PHYSX_TYPE_PHYSICS | physx::PxPhysics

  Note: COMPOUND_SHAPE returns an internal compound-shape wrapper. Use the C++ helper matching your SDK build to access the underlying physx::PxShape pointers.

  Values:

  enumerator OVPHYSX_PHYSX_TYPE_SCENE
  enumerator OVPHYSX_PHYSX_TYPE_MATERIAL
  enumerator OVPHYSX_PHYSX_TYPE_SHAPE
  enumerator OVPHYSX_PHYSX_TYPE_COMPOUND_SHAPE
  enumerator OVPHYSX_PHYSX_TYPE_ACTOR
  enumerator OVPHYSX_PHYSX_TYPE_JOINT
  enumerator OVPHYSX_PHYSX_TYPE_CUSTOM_JOINT
  enumerator OVPHYSX_PHYSX_TYPE_ARTICULATION
  enumerator OVPHYSX_PHYSX_TYPE_LINK
  enumerator OVPHYSX_PHYSX_TYPE_LINK_JOINT
  enumerator OVPHYSX_PHYSX_TYPE_PARTICLE_SYSTEM
  enumerator OVPHYSX_PHYSX_TYPE_PARTICLE_SET
  enumerator OVPHYSX_PHYSX_TYPE_PHYSICS

enum ovphysx_object_type_t

  High-level object classification for prim paths (TensorAPI-level).

  Mirrors omni::physics::tensors::ObjectType. Returned by ovphysx_get_object_type to let callers tell rigid bodies, articulations, articulation links/joints, and articulation root links apart at a path without inspecting the PhysX SDK pointer directly.

  Values:

  enumerator OVPHYSX_OBJECT_TYPE_INVALID
  enumerator OVPHYSX_OBJECT_TYPE_RIGID_BODY
  enumerator OVPHYSX_OBJECT_TYPE_ARTICULATION
  enumerator OVPHYSX_OBJECT_TYPE_ARTICULATION_LINK
  enumerator OVPHYSX_OBJECT_TYPE_ARTICULATION_ROOT_LINK
  enumerator OVPHYSX_OBJECT_TYPE_ARTICULATION_JOINT

enum ovphysx_articulation_kinematic_flag_t

  Bit flags for ovphysx_articulation_update_kinematic.

  Mirrors PxArticulationKinematicFlag::Enum. Flags may be OR’d.

  Values:

  enumerator OVPHYSX_ARTICULATION_KINEMATIC_POSITION

    Recompute link transforms from joint positions + root pose.

  enumerator OVPHYSX_ARTICULATION_KINEMATIC_VELOCITY

    Recompute link velocities from joint velocities + root velocity.

enum ovphysx_scene_query_mode_t

  Scene query mode &#8212; controls how many hits are returned.

  Values:

  enumerator OVPHYSX_SCENE_QUERY_MODE_CLOSEST

    Return the single closest hit (or none).

  enumerator OVPHYSX_SCENE_QUERY_MODE_ANY

    Return whether any hit exists (0 or 1 result).

  enumerator OVPHYSX_SCENE_QUERY_MODE_ALL

    Return all hits.

enum ovphysx_scene_query_geometry_type_t

  Geometry type for sweep and overlap queries.

  SHAPE accepts any UsdGeomGPrim path (sphere, box, capsule, cone, cylinder, mesh, etc.). For meshes the runtime uses a convex approximation internally.

  Values:

  enumerator OVPHYSX_SCENE_QUERY_GEOMETRY_SPHERE

    Sphere defined by radius + center position.

  enumerator OVPHYSX_SCENE_QUERY_GEOMETRY_BOX

    Oriented box defined by half-extents + pose.

  enumerator OVPHYSX_SCENE_QUERY_GEOMETRY_SHAPE

    Arbitrary UsdGeomGPrim identified by prim path.

enum ovphysx_api_status_t

  Values:

  enumerator OVPHYSX_API_SUCCESS

    Operation completed or enqueued successfully.

  enumerator OVPHYSX_API_ERROR

    Operation failed - check error field.

  enumerator OVPHYSX_API_TIMEOUT

    Operation timed out.

  enumerator OVPHYSX_API_NOT_IMPLEMENTED

    Feature not yet implemented.

  enumerator OVPHYSX_API_INVALID_ARGUMENT

    Invalid argument provided.

  enumerator OVPHYSX_API_NOT_FOUND

    Requested resource not found (handle unknown, binding invalidated)

  enumerator OVPHYSX_API_BUFFER_TOO_SMALL

    Caller-supplied buffer is too small; check API-specific size metadata.

  enumerator OVPHYSX_API_DEVICE_MISMATCH

    Tensor device cannot be used or staged for this binding/policy.

  enumerator OVPHYSX_API_GPU_NOT_AVAILABLE

    GPU requested but not available or CUDA init failed.

  enumerator OVPHYSX_API_END_OF_ITERATION

    Iterator exhausted (e.g.

    ovphysx_fetch_read_next past the last group) &#8212; not an error

enum ovphysx_tensor_type_t

  Tensor type identifiers for bulk GPU data access.

  Each value specifies what physical quantity the tensor represents, its shape, data type, and coordinate frame.

  Coordinate conventions:

  - All poses and velocities are in WORLD FRAME

  - DOF data (positions, velocities, targets) are in JOINT SPACE

  - Quaternions use [qx, qy, qz, qw] ordering (xyzw)

  ### RIGID BODY TENSORS

  OVPHYSX_TENSOR_RIGID_BODY_POSE_F32 Shape: [N, 7] where N = number of rigid bodies Layout: [px, py, pz, qx, qy, qz, qw] (position xyz, quaternion xyzw) Frame: World DType: float32

  OVPHYSX_TENSOR_RIGID_BODY_VELOCITY_F32 Shape: [N, 6] where N = number of rigid bodies Layout: [vx, vy, vz, wx, wy, wz] (linear xyz, angular xyz) Frame: World DType: float32

  OVPHYSX_TENSOR_RIGID_BODY_ACCELERATION_F32 Shape: [N, 6] where N = number of rigid bodies Layout: [ax, ay, az, alpha_x, alpha_y, alpha_z] (linear + angular acc) Frame: World DType: float32 Access: read-only

  ### ARTICULATION TENSORS

  OVPHYSX_TENSOR_ARTICULATION_ROOT_POSE_F32 Shape: [N, 7] where N = number of articulations Layout: [px, py, pz, qx, qy, qz, qw] Frame: World DType: float32

  OVPHYSX_TENSOR_ARTICULATION_ROOT_VELOCITY_F32 Shape: [N, 6] where N = number of articulations Layout: [vx, vy, vz, wx, wy, wz] Frame: World DType: float32

  OVPHYSX_TENSOR_ARTICULATION_MASS_CENTER_WORLD_F32 (READ-ONLY) Shape: [N, 3] where N = number of articulations Layout: [x, y, z] center of mass per articulation Frame: World DType: float32 Note: Computed from PxArticulationReducedCoordinate::computeArticulationCOM(false)

  OVPHYSX_TENSOR_ARTICULATION_MASS_CENTER_LOCAL_F32 (READ-ONLY) Shape: [N, 3] where N = number of articulations Layout: [x, y, z] center of mass per articulation Frame: Local (root link frame) DType: float32 Note: Computed from PxArticulationReducedCoordinate::computeArticulationCOM(true)

  OVPHYSX_TENSOR_ARTICULATION_CENTROIDAL_MOMENTUM_F32 (READ-ONLY) Shape: [N, 6, D + 7] where N = articulations, D = getMaxDofs() Layout: 6 spatial-momentum rows (3 linear + 3 angular) of (D + 6) matrix columns followed by 1 bias column (D + 7 total). cols [0..5] = root spatial DOFs, cols [6..D+5] = joint DOFs, col [D+6] = centroidalMomentumBias[row]. Frame: World, evaluated at the articulation COM. DType: float32 Requires: Floating-base articulations only (PhysX errors out on fixed-base). Note: Computed from PxArticulationReducedCoordinate::computeCentroidalMomentumMatrix.

  ### ARTICULATION LINK TENSORS (3D - per-link data)

  OVPHYSX_TENSOR_ARTICULATION_LINK_POSE_F32 Shape: [N, L, 7] where N = articulations, L = max links Layout: [px, py, pz, qx, qy, qz, qw] per link Frame: World DType: float32 Note: For articulations with fewer than L links, extra entries are zero-padded

  OVPHYSX_TENSOR_ARTICULATION_LINK_VELOCITY_F32 Shape: [N, L, 6] where N = articulations, L = max links Layout: [vx, vy, vz, wx, wy, wz] per link Frame: World DType: float32

  ### ARTICULATION DOF TENSORS (joint space)

  OVPHYSX_TENSOR_ARTICULATION_DOF_POSITION_F32 Shape: [N, D] where N = articulations, D = max DOFs Layout: Joint positions in articulation DOF order Units: Radians (revolute) or meters (prismatic) DType: float32 Note: For articulations with fewer than D DOFs, extra entries are zero-padded

  OVPHYSX_TENSOR_ARTICULATION_DOF_VELOCITY_F32 Shape: [N, D] Layout: Joint velocities Units: rad/s or m/s DType: float32

  OVPHYSX_TENSOR_ARTICULATION_DOF_POSITION_TARGET_F32 Shape: [N, D] Layout: Position targets for position-controlled joints DType: float32

  OVPHYSX_TENSOR_ARTICULATION_DOF_VELOCITY_TARGET_F32 Shape: [N, D] Layout: Velocity targets for velocity-controlled joints DType: float32

  OVPHYSX_TENSOR_ARTICULATION_DOF_ACTUATION_FORCE_F32 Shape: [N, D] Layout: Actuation forces/torques applied to joints. Units: N or Nm DType: float32

  NOTE: This reads the staging buffer associated with the PhysX GPU joint-force API (write-only internally). Depending on simulation settings, it may not match the solver-applied joint forces for the current step.

  ### RIGID BODY PROPERTY TENSORS (standalone non-articulated bodies)

  OVPHYSX_TENSOR_RIGID_BODY_MASS_F32 Shape: [N] where N = number of rigid bodies Layout: scalar mass per body Units: kilograms DType: float32

  OVPHYSX_TENSOR_RIGID_BODY_INV_MASS_F32 Shape: [N] where N = number of rigid bodies Layout: scalar inverse mass per body Units: 1/kg DType: float32 Access: read-only

  OVPHYSX_TENSOR_RIGID_BODY_INERTIA_F32 Shape: [N, 9] where N = number of rigid bodies Layout: row-major 3x3 inertia tensor in center-of-mass frame Units: kg*m^2 DType: float32

  OVPHYSX_TENSOR_RIGID_BODY_INV_INERTIA_F32 Shape: [N, 9] where N = number of rigid bodies Layout: row-major 3x3 inverse inertia tensor in center-of-mass frame Units: 1/(kg*m^2) DType: float32 Access: read-only

  OVPHYSX_TENSOR_RIGID_BODY_DISABLE_SIMULATION_BOOL Shape: [N] where N = number of rigid bodies Layout: per-body byte; nonzero disables simulation, zero enables. DType: bool / uint8 Access: read/write. Writes apply at runtime (engine toggles PxActorFlag::eDISABLE_SIMULATION on the underlying PxRigidActor so the body stops participating in the next solver step).

  OVPHYSX_TENSOR_RIGID_BODY_DISABLE_GRAVITY_BOOL Shape: [N] where N = number of rigid bodies Layout: per-body byte; nonzero disables gravity, zero enables. DType: bool / uint8 Access: read/write. Writes apply at runtime (engine toggles PxActorFlag::eDISABLE_GRAVITY on the underlying PxRigidActor). Reads return live PhysX actor flags (post-parse internal state only).

  OVPHYSX_TENSOR_RIGID_BODY_COM_POSE_F32 Shape: [N, 7] where N = number of rigid bodies Layout: [px, py, pz, qx, qy, qz, qw] (position xyz, quaternion xyzw) Frame: Local frame (relative to body origin) DType: float32

  ### ARTICULATION LINK ACCELERATION (READ-ONLY)

  OVPHYSX_TENSOR_ARTICULATION_LINK_ACCELERATION_F32 Shape: [N, L, 6] where N = articulations, L = max links Layout: [ax, ay, az, alpha_x, alpha_y, alpha_z] (linear + angular acc) Frame: World DType: float32

  ### ARTICULATION DOF PROPERTY TENSORS (read/write, except where noted)

  OVPHYSX_TENSOR_ARTICULATION_DOF_STIFFNESS_F32 Shape: [N, D] where N = articulations, D = max DOFs Layout: Joint stiffness values DType: float32

  OVPHYSX_TENSOR_ARTICULATION_DOF_DAMPING_F32 Shape: [N, D] Layout: Joint damping values DType: float32

  OVPHYSX_TENSOR_ARTICULATION_DOF_LIMIT_F32 Shape: [N, D, 2] Layout: (lower, upper) position limit per DOF DType: float32

  OVPHYSX_TENSOR_ARTICULATION_DOF_MAX_VELOCITY_F32 Shape: [N, D] Layout: Maximum velocity per DOF Units: rad/s or m/s DType: float32

  OVPHYSX_TENSOR_ARTICULATION_DOF_MAX_FORCE_F32 Shape: [N, D] Layout: Maximum force/torque per DOF Units: N or Nm DType: float32

  OVPHYSX_TENSOR_ARTICULATION_DOF_ARMATURE_F32 Shape: [N, D] Layout: Armature (reflected inertia) per DOF DType: float32

  OVPHYSX_TENSOR_ARTICULATION_DOF_FRICTION_PROPERTIES_F32 Shape: [N, D, 3] Layout: (static, dynamic, viscous) friction coefficients per DOF DType: float32

  OVPHYSX_TENSOR_ARTICULATION_DOF_DRIVE_MODEL_F32 Shape: [N, D, 3] Layout: (speedEffortGradient, maxActuatorVelocity, velocityDependentResistance) per DOF DType: float32 Note: only DOFs with PhysxDrivePerformanceEnvelopeAPI applied in USD accept writes; writes to other DOFs are silently dropped.

  OVPHYSX_TENSOR_ARTICULATION_DOF_DRIVE_TYPE_U8 Shape: [N, D] where N = articulations, D = max DOFs (zero-padded) Layout: per-DOF byte in solver DOF order; 0 = no drive, 1 = force, 2 = acceleration. DType: uint8 Access: read-only. Reads return the live PxArticulationDrive driveType. Trailing padded DOF columns beyond numDofs read as 0.

  ### ARTICULATION BODY PROPERTY TENSORS (read/write, except where noted)

  OVPHYSX_TENSOR_ARTICULATION_BODY_MASS_F32 Shape: [N, L] where N = articulations, L = max links Layout: Mass per link Units: kilograms DType: float32

  OVPHYSX_TENSOR_ARTICULATION_BODY_COM_POSE_F32 Shape: [N, L, 7] Layout: [px, py, pz, qx, qy, qz, qw] (COM local pose per link) Frame: Local frame (relative to link origin) DType: float32

  OVPHYSX_TENSOR_ARTICULATION_BODY_INERTIA_F32 Shape: [N, L, 9] Layout: row-major 3x3 inertia tensor in COM frame per link Units: kg*m^2 DType: float32

  OVPHYSX_TENSOR_ARTICULATION_BODY_INV_MASS_F32 (READ-ONLY) Shape: [N, L] Layout: Inverse mass (1/m) per link DType: float32

  OVPHYSX_TENSOR_ARTICULATION_BODY_INV_INERTIA_F32 (READ-ONLY) Shape: [N, L, 9] Layout: row-major 3x3 inverse inertia in COM frame per link DType: float32

  OVPHYSX_TENSOR_ARTICULATION_BODY_DISABLE_GRAVITY_BOOL Shape: [N, L] where N = articulations, L = max links (zero-padded) Layout: per-link byte in solver link order; nonzero disables gravity. DType: bool / uint8 Access: read/write. Writes apply at runtime (engine toggles PxActorFlag::eDISABLE_GRAVITY on each link actor). Trailing padded link columns beyond numLinks are ignored on write. Reads return live PhysX actor flags (post-parse internal state only).

  ### DYNAMICS QUERY TENSORS (READ-ONLY)

  OVPHYSX_TENSOR_ARTICULATION_JACOBIAN_F32 Shape: [N, R, C] &#8212; obtain R, C from getJacobianShape() Fixed-base: R = (numLinks - 1) * 6, C = numDofs Floating-base: R = (numLinks - 1) * 6 + 6, C = numDofs + 6 Floating-base columns: base 6 DOFs at indices 0..5, joint DOFs at 6..C-1 DType: float32

  OVPHYSX_TENSOR_ARTICULATION_MASS_MATRIX_F32 Shape: [N, M, M] &#8212; obtain M from getGeneralizedMassMatrixShape() Layout: Generalized (joint-space) mass matrix DType: float32

  OVPHYSX_TENSOR_ARTICULATION_CORIOLIS_AND_CENTRIFUGAL_FORCE_F32 Shape: [N, M] Layout: Combined Coriolis and centrifugal compensation forces DType: float32

  OVPHYSX_TENSOR_ARTICULATION_GRAVITY_FORCE_F32 Shape: [N, M] Layout: Gravity compensation forces DType: float32

  OVPHYSX_TENSOR_ARTICULATION_LINK_INCOMING_JOINT_FORCE_F32 Shape: [N, L, 6] Layout: [fx, fy, fz, tx, ty, tz] per link incoming joint force DType: float32

  OVPHYSX_TENSOR_ARTICULATION_DOF_PROJECTED_JOINT_FORCE_F32 Shape: [N, D] Layout: Projected joint forces per DOF DType: float32

  ### FIXED TENDON PROPERTY TENSORS (read/write, require articulation with tendons)

  OVPHYSX_TENSOR_ARTICULATION_FIXED_TENDON_STIFFNESS_F32 Shape: [N, T] where N = articulations, T = max fixed tendons Layout: Tendon stiffness DType: float32

  OVPHYSX_TENSOR_ARTICULATION_FIXED_TENDON_DAMPING_F32 Shape: [N, T] Layout: Tendon damping DType: float32

  OVPHYSX_TENSOR_ARTICULATION_FIXED_TENDON_LIMIT_STIFFNESS_F32 Shape: [N, T] Layout: Stiffness of the tendon length limit spring DType: float32

  OVPHYSX_TENSOR_ARTICULATION_FIXED_TENDON_LIMIT_F32 Shape: [N, T, 2] Layout: (lower, upper) tendon length limits DType: float32

  OVPHYSX_TENSOR_ARTICULATION_FIXED_TENDON_REST_LENGTH_F32 Shape: [N, T] Layout: Tendon rest length DType: float32

  OVPHYSX_TENSOR_ARTICULATION_FIXED_TENDON_OFFSET_F32 Shape: [N, T] Layout: Tendon offset DType: float32

  ### SPATIAL TENDON PROPERTY TENSORS (read/write, require articulation with spatial tendons)

  OVPHYSX_TENSOR_ARTICULATION_SPATIAL_TENDON_STIFFNESS_F32 Shape: [N, T] where N = articulations, T = max spatial tendons Layout: Spatial tendon stiffness DType: float32

  OVPHYSX_TENSOR_ARTICULATION_SPATIAL_TENDON_DAMPING_F32 Shape: [N, T] Layout: Spatial tendon damping DType: float32

  OVPHYSX_TENSOR_ARTICULATION_SPATIAL_TENDON_LIMIT_STIFFNESS_F32 Shape: [N, T] Layout: Stiffness of the spatial tendon length limit spring DType: float32

  OVPHYSX_TENSOR_ARTICULATION_SPATIAL_TENDON_OFFSET_F32 Shape: [N, T] Layout: Spatial tendon offset DType: float32

  ### VOLUME DEFORMABLE BODY TENSORS

  OVPHYSX_TENSOR_DEFORMABLE_SIM_NODAL_POSITION_F32 Shape: [N, V, 3] where N = deformable bodies, V = max simulation nodes Layout: simulation mesh node positions DType: float32

  OVPHYSX_TENSOR_DEFORMABLE_SIM_NODAL_VELOCITY_F32 Shape: [N, V, 3] Layout: simulation mesh node velocities DType: float32

  OVPHYSX_TENSOR_DEFORMABLE_SIM_KINEMATIC_TARGET_F32 Shape: [N, V, 4] Layout: simulation mesh kinematic targets (xyz position, flag) DType: float32

  OVPHYSX_TENSOR_DEFORMABLE_REST_NODAL_POSITION_F32 Shape: [N, R, 3] where R = max rest nodes Layout: rest mesh node positions DType: float32 Access: read-only

  OVPHYSX_TENSOR_DEFORMABLE_SIM_ELEMENT_INDICES_S32 Shape: [N, E, K] where E = max simulation elements, K = nodes per element (4 for tetmesh) Layout: simulation element node indices DType: int32 Access: read-only

  OVPHYSX_TENSOR_DEFORMABLE_COLLISION_ELEMENT_INDICES_S32 Shape: [N, F, 4] where F = max collision elements; K is always 4 (matches backend fetchData) Layout: collision element node indices (tetrahedral, 4 nodes per element) DType: int32 Access: read-only

  ### SURFACE DEFORMABLE BODY TENSORS

  OVPHYSX_TENSOR_SURFACE_DEFORMABLE_SIM_POSITION_F32 Shape: [N, V, 3] where N = surface deformable bodies, V = max simulation nodes Layout: simulation mesh node positions DType: float32

  OVPHYSX_TENSOR_SURFACE_DEFORMABLE_SIM_VELOCITY_F32 Shape: [N, V, 3] Layout: simulation mesh node velocities DType: float32

  OVPHYSX_TENSOR_SURFACE_DEFORMABLE_REST_POSITION_F32 Shape: [N, R, 3] where R = max rest nodes Layout: rest mesh node positions DType: float32 Access: read-only

  OVPHYSX_TENSOR_SURFACE_DEFORMABLE_SIM_ELEMENT_INDICES_S32 Shape: [N, E, 3] where E = max simulation elements (triangles) Layout: simulation element node indices DType: int32 Access: read-only

  ### DEFORMABLE MATERIAL TENSORS

  OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_DYNAMIC_FRICTION_F32 Shape: [M] where M = deformable materials Layout: scalar dynamic friction DType: float32

  OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_YOUNGS_MODULUS_F32 Shape: [M] Layout: scalar Young’s modulus DType: float32

  OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_POISSONS_RATIO_F32 Shape: [M] Layout: scalar Poisson’s ratio DType: float32

  OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_ELASTICITY_DAMPING_F32 Shape: [M] Layout: scalar elasticity damping (volume + surface materials) DType: float32

  OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_BENDING_STIFFNESS_F32 Shape: [M] Layout: scalar bending stiffness (surface materials only; 0.0 for volume material entries) DType: float32

  OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_THICKNESS_F32 Shape: [M] Layout: scalar thickness (surface materials only; 0.0 for volume material entries) DType: float32

  OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_BENDING_DAMPING_F32 Shape: [M] Layout: scalar bending damping (surface materials only; 0.0 for volume material entries) DType: float32

  Values:

  enumerator OVPHYSX_TENSOR_INVALID
  enumerator OVPHYSX_TENSOR_RIGID_BODY_POSE_F32

    [N, 7] poses in world frame

  enumerator OVPHYSX_TENSOR_RIGID_BODY_VELOCITY_F32

    [N, 6] velocities in world frame

  enumerator OVPHYSX_TENSOR_RIGID_BODY_ACCELERATION_F32

    [N, 6] accelerations in world frame (READ-ONLY)

  enumerator OVPHYSX_TENSOR_RIGID_BODY_MASS_F32

    [N] mass per body

  enumerator OVPHYSX_TENSOR_RIGID_BODY_INERTIA_F32

    [N, 9] row-major 3x3 inertia tensor

  enumerator OVPHYSX_TENSOR_RIGID_BODY_COM_POSE_F32

    [N, 7] COM local pose (px,py,pz,qx,qy,qz,qw)

  enumerator OVPHYSX_TENSOR_RIGID_BODY_INV_MASS_F32

    [N] inverse mass per body (READ-ONLY)

  enumerator OVPHYSX_TENSOR_RIGID_BODY_INV_INERTIA_F32

    [N, 9] inverse inertia tensor (READ-ONLY)

  enumerator OVPHYSX_TENSOR_RIGID_BODY_DISABLE_SIMULATION_BOOL

    [N] uint8/bool; nonzero disables, zero enables PxActorFlag::eDISABLE_SIMULATION at runtime

  enumerator OVPHYSX_TENSOR_ARTICULATION_ROOT_POSE_F32

    [N, 7] root poses

  enumerator OVPHYSX_TENSOR_ARTICULATION_ROOT_VELOCITY_F32

    [N, 6] root velocities

  enumerator OVPHYSX_TENSOR_ARTICULATION_MASS_CENTER_WORLD_F32

    [N, 3] articulation COM in world frame (READ-ONLY)

  enumerator OVPHYSX_TENSOR_ARTICULATION_MASS_CENTER_LOCAL_F32

    [N, 3] articulation COM in root-local frame (READ-ONLY)

  enumerator OVPHYSX_TENSOR_ARTICULATION_CENTROIDAL_MOMENTUM_F32

    [N, 6, D+7] centroidal momentum matrix + bias column; floating-base only (READ-ONLY)

  enumerator OVPHYSX_TENSOR_ARTICULATION_LINK_POSE_F32

    [N, L, 7] link poses

  enumerator OVPHYSX_TENSOR_ARTICULATION_LINK_VELOCITY_F32

    [N, L, 6] link velocities

  enumerator OVPHYSX_TENSOR_ARTICULATION_LINK_ACCELERATION_F32

    [N, L, 6] link accelerations (lin_acc xyz + ang_acc xyz), READ-ONLY

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_POSITION_F32

    [N, D] joint positions

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_VELOCITY_F32

    [N, D] joint velocities

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_POSITION_TARGET_F32

    [N, D] position targets

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_VELOCITY_TARGET_F32

    [N, D] velocity targets

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_ACTUATION_FORCE_F32

    [N, D] actuation forces

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_STIFFNESS_F32

    [N, D] joint stiffness

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_DAMPING_F32

    [N, D] joint damping

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_LIMIT_F32

    [N, D, 2] (lower, upper) per DOF

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_MAX_VELOCITY_F32

    [N, D] max velocity per DOF

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_MAX_FORCE_F32

    [N, D] max force per DOF

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_ARMATURE_F32

    [N, D] armature per DOF

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_FRICTION_PROPERTIES_F32

    [N, D, 3] (static, dynamic, viscous)

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_DRIVE_MODEL_F32

    [N, D, 3] (speedEffortGradient, maxActuatorVelocity, velocityDependentResistance)

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_DRIVE_TYPE_U8

    [N, D] uint8 drive type per DOF; 0=none, 1=force, 2=acceleration (READ-ONLY)

  enumerator OVPHYSX_TENSOR_RIGID_BODY_FORCE_F32

    External forces/wrenches - WRITE-ONLY (control inputs applied each step).

    All components are in global (world) frame, including application position.

    WRENCH layout: [fx, fy, fz, tx, ty, tz, px, py, pz]

    - (fx,fy,fz) = force vector in world frame

    - (tx,ty,tz) = torque vector in world frame

    - (px,py,pz) = force application position in world frame [N, 3] forces at center of mass

  enumerator OVPHYSX_TENSOR_RIGID_BODY_WRENCH_F32

    [N, 9] row-major: [fx,fy,fz,tx,ty,tz,px,py,pz] per body

  enumerator OVPHYSX_TENSOR_ARTICULATION_LINK_WRENCH_F32

    [N, L, 9] row-major: same layout per link

  enumerator OVPHYSX_TENSOR_ARTICULATION_BODY_MASS_F32

    [N, L] mass per link

  enumerator OVPHYSX_TENSOR_ARTICULATION_BODY_COM_POSE_F32

    [N, L, 7] COM local pose (px,py,pz,qx,qy,qz,qw)

  enumerator OVPHYSX_TENSOR_ARTICULATION_BODY_INERTIA_F32

    [N, L, 9] row-major 3x3 inertia in COM frame

  enumerator OVPHYSX_TENSOR_ARTICULATION_BODY_INV_MASS_F32

    [N, L] inverse mass (1/m) per link (READ-ONLY)

  enumerator OVPHYSX_TENSOR_ARTICULATION_BODY_INV_INERTIA_F32

    [N, L, 9] inverse inertia in COM frame (READ-ONLY)

  enumerator OVPHYSX_TENSOR_ARTICULATION_BODY_DISABLE_GRAVITY_BOOL

    [N, L] uint8/bool; nonzero disables PxActorFlag::eDISABLE_GRAVITY per link at runtime

  enumerator OVPHYSX_TENSOR_ARTICULATION_JACOBIAN_F32

    [N, R, C] from getJacobianShape().

    For fixed-base: R = (numLinks-1)*6, C = numDofs. For floating-base: R = (numLinks-1)*6 + 6, C = numDofs + 6. Floating-base columns: base 6 DOFs at indices 0..5, joint DOFs at 6..C-1.

  enumerator OVPHYSX_TENSOR_ARTICULATION_MASS_MATRIX_F32

    [N, M, M] from getGeneralizedMassMatrixShape()

  enumerator OVPHYSX_TENSOR_ARTICULATION_CORIOLIS_AND_CENTRIFUGAL_FORCE_F32

    [N, M] Coriolis + centrifugal forces (both terms, from getCoriolisAndCentrifugalCompensationForces())

  enumerator OVPHYSX_TENSOR_ARTICULATION_GRAVITY_FORCE_F32

    [N, M] gravity compensation

  enumerator OVPHYSX_TENSOR_ARTICULATION_LINK_INCOMING_JOINT_FORCE_F32

    [N, L, 6] per-link incoming joint force

  enumerator OVPHYSX_TENSOR_ARTICULATION_DOF_PROJECTED_JOINT_FORCE_F32

    [N, D] projected joint forces (READ-ONLY)

  enumerator OVPHYSX_TENSOR_ARTICULATION_FIXED_TENDON_STIFFNESS_F32

    [N, T] tendon stiffness

  enumerator OVPHYSX_TENSOR_ARTICULATION_FIXED_TENDON_DAMPING_F32

    [N, T] tendon damping

  enumerator OVPHYSX_TENSOR_ARTICULATION_FIXED_TENDON_LIMIT_STIFFNESS_F32

    [N, T] tendon limit stiffness

  enumerator OVPHYSX_TENSOR_ARTICULATION_FIXED_TENDON_LIMIT_F32

    [N, T, 2] (lower, upper) tendon limits

  enumerator OVPHYSX_TENSOR_ARTICULATION_FIXED_TENDON_REST_LENGTH_F32

    [N, T] tendon rest length

  enumerator OVPHYSX_TENSOR_ARTICULATION_FIXED_TENDON_OFFSET_F32

    [N, T] tendon offset

  enumerator OVPHYSX_TENSOR_ARTICULATION_SPATIAL_TENDON_STIFFNESS_F32

    [N, T] spatial tendon stiffness

  enumerator OVPHYSX_TENSOR_ARTICULATION_SPATIAL_TENDON_DAMPING_F32

    [N, T] spatial tendon damping

  enumerator OVPHYSX_TENSOR_ARTICULATION_SPATIAL_TENDON_LIMIT_STIFFNESS_F32

    [N, T] spatial tendon limit stiffness

  enumerator OVPHYSX_TENSOR_ARTICULATION_SPATIAL_TENDON_OFFSET_F32

    [N, T] spatial tendon offset

  enumerator OVPHYSX_TENSOR_RIGID_BODY_SHAPE_FRICTION_AND_RESTITUTION_F32

    [N, S, 3] (static friction, dynamic friction, restitution) per shape

  enumerator OVPHYSX_TENSOR_RIGID_BODY_CONTACT_OFFSET_F32

    [N, S] contact offset per shape

  enumerator OVPHYSX_TENSOR_RIGID_BODY_REST_OFFSET_F32

    [N, S] rest offset per shape

  enumerator OVPHYSX_TENSOR_RIGID_BODY_DISABLE_GRAVITY_BOOL

    [N] uint8/bool; nonzero disables PxActorFlag::eDISABLE_GRAVITY at runtime

  enumerator OVPHYSX_TENSOR_ARTICULATION_SHAPE_FRICTION_AND_RESTITUTION_F32

    [N, S, 3] (static friction, dynamic friction, restitution) per link shape

  enumerator OVPHYSX_TENSOR_ARTICULATION_CONTACT_OFFSET_F32

    [N, S] contact offset per link shape

  enumerator OVPHYSX_TENSOR_ARTICULATION_REST_OFFSET_F32

    [N, S] rest offset per link shape

  enumerator OVPHYSX_TENSOR_DEFORMABLE_SIM_NODAL_POSITION_F32

    [N, V, 3] simulation node positions

  enumerator OVPHYSX_TENSOR_DEFORMABLE_SIM_NODAL_VELOCITY_F32

    [N, V, 3] simulation node velocities

  enumerator OVPHYSX_TENSOR_DEFORMABLE_SIM_KINEMATIC_TARGET_F32

    [N, V, 4] simulation node kinematic targets (xyz, flag)

  enumerator OVPHYSX_TENSOR_DEFORMABLE_REST_NODAL_POSITION_F32

    [N, R, 3] rest node positions (READ-ONLY)

  enumerator OVPHYSX_TENSOR_DEFORMABLE_SIM_ELEMENT_INDICES_S32

    [N, E, K] simulation element indices, K=4 tetmesh (int32, READ-ONLY)

  enumerator OVPHYSX_TENSOR_DEFORMABLE_COLLISION_ELEMENT_INDICES_S32

    [N, F, 4] collision element indices, K=4 tetmesh (int32, READ-ONLY)

  enumerator OVPHYSX_TENSOR_SURFACE_DEFORMABLE_SIM_POSITION_F32

    [N, V, 3] simulation node positions

  enumerator OVPHYSX_TENSOR_SURFACE_DEFORMABLE_SIM_VELOCITY_F32

    [N, V, 3] simulation node velocities

  enumerator OVPHYSX_TENSOR_SURFACE_DEFORMABLE_REST_POSITION_F32

    [N, R, 3] rest node positions (READ-ONLY)

  enumerator OVPHYSX_TENSOR_SURFACE_DEFORMABLE_SIM_ELEMENT_INDICES_S32

    [N, E, 3] simulation element indices, K=3 trimesh (int32, READ-ONLY)

  enumerator OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_DYNAMIC_FRICTION_F32

    [M] dynamic friction

  enumerator OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_YOUNGS_MODULUS_F32

    [M] Young’s modulus

  enumerator OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_POISSONS_RATIO_F32

    [M] Poisson’s ratio

  enumerator OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_ELASTICITY_DAMPING_F32

    [M] elasticity damping (volume + surface)

  enumerator OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_BENDING_STIFFNESS_F32

    [M] bending stiffness (surface only; 0 for volume)

  enumerator OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_THICKNESS_F32

    [M] thickness (surface only; 0 for volume)

  enumerator OVPHYSX_TENSOR_DEFORMABLE_MATERIAL_BENDING_DAMPING_F32

    [M] bending damping (surface only; 0 for volume)

enum ovphysx_config_key_type_t

  Config key type discriminator - selects which key/value union members are valid.

  Values:

  enumerator OVPHYSX_CONFIG_KEY_TYPE_BOOL

    Key from ovphysx_config_bool_t, value is bool.

  enumerator OVPHYSX_CONFIG_KEY_TYPE_INT32

    Key from ovphysx_config_int32_t, value is int32_t.

  enumerator OVPHYSX_CONFIG_KEY_TYPE_FLOAT

    Key from ovphysx_config_float_t, value is float.

  enumerator OVPHYSX_CONFIG_KEY_TYPE_STRING

    Key from ovphysx_config_string_t, value is ovphysx_string_t.

  enumerator OVPHYSX_CONFIG_KEY_TYPE_CARBONITE

    Escape hatch: arbitrary Carbonite path (string key + string value)

  enumerator OVPHYSX_CONFIG_KEY_TYPE_COUNT

enum ovphysx_config_bool_t

  Boolean config keys.

  Value type: bool.

  Values:

  enumerator OVPHYSX_CONFIG_DISABLE_CONTACT_PROCESSING

    /physics/disableContactProcessing

  enumerator OVPHYSX_CONFIG_COLLISION_CONE_CUSTOM_GEOMETRY

    /physics/collisionConeCustomGeometry

  enumerator OVPHYSX_CONFIG_COLLISION_CYLINDER_CUSTOM_GEOMETRY

    /physics/collisionCylinderCustomGeometry

  enumerator OVPHYSX_CONFIG_OMNIPVD_OUTPUT_ENABLED

    /physics/omniPvdOutputEnabled

  enumerator OVPHYSX_CONFIG_BOOL_COUNT

enum ovphysx_config_int32_t

  Int32 config keys.

  Value type: int32_t.

  Values:

  enumerator OVPHYSX_CONFIG_NUM_THREADS

    /physics/numThreads

  enumerator OVPHYSX_CONFIG_SCENE_MULTI_GPU_MODE

    /physics/sceneMultiGPUMode (0=disabled, 1=all, 2=skip-first)

  enumerator OVPHYSX_CONFIG_INT32_COUNT

enum ovphysx_config_float_t

  Float config keys (reserved for future use).

  Value type: float.

  Values:

  enumerator OVPHYSX_CONFIG_FLOAT_COUNT

enum ovphysx_config_string_t

  String config keys.

  Value type: ovphysx_string_t.

  Values:

  enumerator OVPHYSX_CONFIG_OMNIPVD_OVD_RECORDING_DIRECTORY

    /persistent/physics/omniPvdOvdRecordingDirectory

  enumerator OVPHYSX_CONFIG_COOKED_COLLIDER_CACHE_DIRECTORY

    /UJITSO/datastore/localCachePath: app-provided dir for the local cooked-collider cache

  enumerator OVPHYSX_CONFIG_STRING_COUNT

enum ovphysx_debug_render_parameter_t

  PhysX debug-visualization parameters for ovphysx_debug_render_set_parameter() / _get_parameter().

  Mirrors omni::physx::PhysXVisualizationParameter &#8212; a static_assert in the sidecar TU keeps the two enums aligned, so these named constants are the stable, reorder-proof public spelling of the otherwise-opaque integer index. NONE (0) and COUNT (one-past-the-end) are NOT valid parameters: ovphysx_debug_render_set_parameter() rejects them with OVPHYSX_API_INVALID_ARGUMENT.

  Values:

  enumerator OVPHYSX_DEBUG_RENDER_PARAM_NONE
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_WORLD_AXES
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_BODY_AXES
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_BODY_MASS_AXES
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_BODY_LINEAR_VELOCITY
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_BODY_ANGULAR_VELOCITY
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_CONTACT_POINT
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_CONTACT_NORMAL
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_CONTACT_ERROR
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_CONTACT_IMPULSE
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_FRICTION_POINT
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_FRICTION_NORMAL
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_FRICTION_IMPULSE
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_ACTOR_AXES
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_COLLISION_AABBS
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_COLLISION_SHAPES
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_COLLISION_AXES
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_COLLISION_COMPOUNDS
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_COLLISION_FACE_NORMALS
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_COLLISION_EDGES
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_COLLISION_STATIC_PRUNER
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_COLLISION_DYNAMIC_PRUNER
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_JOINT_LOCAL_FRAMES
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_JOINT_LIMITS
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_CULL_BOX
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_MBP_REGIONS
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_SIMULATION_MESH
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_SDF
  enumerator OVPHYSX_DEBUG_RENDER_PARAM_COUNT

Functions

static inline ovphysx_string_t ovphysx_cstr(const char *cstr)

  Helper function to create ovphysx_string_t from a null-terminated C string.

  Returns empty string if cstr is NULL.

struct ovphysx_string_t
  #include <include/ovphysx/ovphysx_types.h>

  String with pointer and length.

  Strings are NOT guaranteed to be null-terminated. Always use the length field. Use OVPHYSX_LITERAL(“literal”) or ovphysx_cstr() for convenient construction.

  Public Members

  const char *ptr

    Pointer to string data (not guaranteed null-terminated)

  size_t length

    Length in bytes.

struct ovphysx_object_change_callbacks_t
  #include <include/ovphysx/ovphysx_types.h>

  Callback set passed to ovphysx_subscribe_object_changes().

  Any of the function-pointer fields may be NULL; ovphysx skips a NULL field rather than invoking it. The caller does NOT need to keep this struct alive after the subscribe call returns &#8212; ovphysx copies the relevant state internally.

  Threading: callbacks may fire from internal worker threads during ovphysx_step(), ovphysx_step_sync(), or ovphysx_reset_stage(). Do NOT call other ovphysx APIs from inside a callback (re-entrancy / deadlock risk). Defer follow-up work until the triggering synchronous call returns, or until the next ovphysx_wait_op() returns for async work.

  Public Members

  ovphysx_object_created_fn on_object_created

    Fired AFTER an object is created (NULL = skip).

  ovphysx_object_destroyed_fn on_object_destroyed

    Fired BEFORE an object is destroyed (NULL = skip).

  ovphysx_all_objects_destroyed_fn on_all_objects_destroyed

    Fired BEFORE a bulk teardown (NULL = skip).

  void *user_data

    Opaque pointer passed unchanged to every callback.

struct ovphysx_scene_query_geometry_desc_t
  #include <include/ovphysx/ovphysx_types.h>

  Geometry descriptor for sweep/overlap queries.

  Set `type` and fill the corresponding union member.

  Public Members

  ovphysx_scene_query_geometry_type_t type
  float radius

    Sphere radius.

  float position[3]

    Sphere center (world space).

    Box center (world space).

  struct ovphysx_scene_query_geometry_desc_t::[anonymous]::[anonymous] sphere
  float half_extent[3]

    Box half-extents.

  float rotation[4]

    Box orientation quaternion (x, y, z, w).

  struct ovphysx_scene_query_geometry_desc_t::[anonymous]::[anonymous] box
  ovphysx_string_t prim_path

    USD prim path for any UsdGeomGPrim (embedded NUL bytes are rejected).

  struct ovphysx_scene_query_geometry_desc_t::[anonymous]::[anonymous] shape
  union ovphysx_scene_query_geometry_desc_t::[anonymous] [anonymous]

struct ovphysx_scene_query_hit_t
  #include <include/ovphysx/ovphysx_types.h>

  Scene query hit result.

  Used for raycast, sweep, and overlap queries. For overlap queries the location fields (normal, position, distance, face_index, material) are zeroed &#8212; only the object identity fields are populated.

  Path fields (collision, rigid_body, material) are uint64-encoded SdfPaths matching ovphysx’s internal path encoding.

  Public Members

  uint64_t collision

    Collision shape SdfPath (uint64 encoded).

  uint64_t rigid_body

    Rigid body SdfPath (uint64 encoded).

  uint32_t proto_index

    Point instancer prototype index (0xFFFFFFFF if N/A).

  float normal[3]

    Hit normal (world space).

    Zero for overlap queries.

  float position[3]

    Hit position (world space).

    Zero for overlap queries.

  float distance

    Hit distance along ray/sweep direction.

    Zero for overlap.

  uint32_t face_index

    Triangle mesh face index.

    Zero for non-mesh hits.

  uint64_t material

    Material SdfPath (uint64 encoded).

    Zero for overlap.

struct ovphysx_result_t
  #include <include/ovphysx/ovphysx_types.h>

  Result returned by synchronous API functions.

  On failure (status != OVPHYSX_API_SUCCESS), call ovphysx_get_last_error() on the same thread to retrieve the error message.

  Public Members

  ovphysx_api_status_t status

    Operation status code.

struct ovphysx_enqueue_result_t
  #include <include/ovphysx/ovphysx_types.h>

  Result returned by asynchronous API functions.

  On failure (status != OVPHYSX_API_SUCCESS), call ovphysx_get_last_error() on the same thread to retrieve the error message.

  Public Members

  ovphysx_api_status_t status

    Operation status code.

  ovphysx_op_index_t op_index

    Operation index for async tracking.

struct ovphysx_op_wait_result_t
  #include <include/ovphysx/ovphysx_types.h>

  Result from ovphysx_wait_op() containing failed op indices and pending operation status.

  For each failed op index, call ovphysx_get_last_op_error(op_index) to retrieve the error message. Free this struct via ovphysx_destroy_wait_result().

  Public Members

  ovphysx_op_index_t *error_op_indices

    Array of op indices that failed (free via ovphysx_destroy_wait_result)

  size_t num_errors

    Number of failed op indices.

  ovphysx_op_index_t lowest_pending_op_index

    Lowest operation index still pending, 0 if all complete.

struct ovphysx_tensor_binding_desc_t
  #include <include/ovphysx/ovphysx_types.h>

  Descriptor for creating a tensor binding.

  A tensor binding connects a list of USD prim paths to a tensor type, enabling bulk read/write of physics data for all matching prims.

  Prim selection (mutually exclusive - use ONE of these):

  - pattern: Glob pattern like “/World/robot*” or “/World/env[N]/robot”

  - prim_paths: Explicit list of exact prim paths

  Precedence rules:

  1. If prim_paths != NULL AND prim_paths_count > 0, uses explicit paths

  2. Else if pattern.ptr != NULL AND pattern.length > 0, uses pattern

  3. Else returns OVPHYSX_API_INVALID_ARGUMENT

  When prim_paths is used, pattern is completely ignored (not combined).

  Example with pattern: ovphysx_tensor_binding_desc_t desc = { .pattern = OVPHYSX_LITERAL(“/World/robot*”), .tensor_type = OVPHYSX_TENSOR_RIGID_BODY_POSE_F32 };

  Example with explicit prim paths: ovphysx_string_t paths[] = { OVPHYSX_LITERAL(“/World/env1/robot”), OVPHYSX_LITERAL(“/World/env4/robot”), OVPHYSX_LITERAL(“/World/env5/robot”) }; ovphysx_tensor_binding_desc_t desc = { .prim_paths = paths, .prim_paths_count = 3, .tensor_type = OVPHYSX_TENSOR_RIGID_BODY_POSE_F32 };

  Public Members

  ovphysx_string_t pattern

    USD path glob pattern (ignored if prim_paths is set)

  const ovphysx_string_t *prim_paths

    Explicit list of exact prim paths (NULL = use pattern)

  uint32_t prim_paths_count

    Number of prim paths (0 = use pattern)

  ovphysx_tensor_type_t tensor_type

    Type of tensor data to bind.

struct ovphysx_tensor_spec_t
  #include <include/ovphysx/ovphysx_types.h>

  Complete tensor specification for DLTensor construction.

  Use ovphysx_get_tensor_binding_spec() to get the exact dtype, rank, and shape needed to allocate a compatible tensor. This is the preferred API for constructing DLTensors.

  Tensor specifications by type:

  - Rigid body pose: ndim=2, shape=[N, 7]

  - Rigid body velocity: ndim=2, shape=[N, 6]

  - Articulation root: ndim=2, shape=[N, 7] or [N, 6]

  - Articulation links: ndim=3, shape=[N, L, 7] or [N, L, 6]

  - Articulation DOF: ndim=2, shape=[N, D]

  Tensor dtype is tensor-type specific:

  - Most tensor types use float32 (kDLFloat, 32 bits, 1 lane)

  - Deformable element index tensors (DEFORMABLE_SIM_ELEMENT_INDICES_S32, DEFORMABLE_COLLISION_ELEMENT_INDICES_S32, SURFACE_DEFORMABLE_SIM_ELEMENT_INDICES_S32) use int32 (kDLInt, 32 bits, 1 lane)

  - OVPHYSX_TENSOR_RIGID_BODY_DISABLE_SIMULATION_BOOL, OVPHYSX_TENSOR_RIGID_BODY_DISABLE_GRAVITY_BOOL, and OVPHYSX_TENSOR_ARTICULATION_BODY_DISABLE_GRAVITY_BOOL use bool/uint8 (kDLUInt, 8 bits, 1 lane) &#8212; per-body/per-link byte flags.

  - OVPHYSX_TENSOR_ARTICULATION_DOF_DRIVE_TYPE_U8 also uses uint8 (kDLUInt, 8 bits, 1 lane), but as a per-DOF enum byte (0/1/2), not a flag. Always call ovphysx_get_tensor_binding_spec() and respect the returned dtype; do not assume float32.

  - Layout: row-major contiguous (C-order)

  Public Members

  DLDataType dtype

    DLPack data type for this tensor type.

    Most bindings use float32; element-index tensors use int32; disable-simulation/gravity bool bindings and the DOF drive-type enum binding use uint8. Always honor this field rather than assuming float32.

  int32_t ndim

    Number of dimensions.

  int64_t shape[4]

    Shape dimensions [dim0, dim1, dim2, 0].

struct ovphysx_articulation_metadata_t
  #include <include/ovphysx/ovphysx_types.h>

  Articulation topology metadata returned by ovphysx_get_articulation_metadata().

  All fields are read at binding-creation time and remain constant for the lifetime of the binding.

  String arrays (DOF names, body names, joint names) are NOT included here because they are variable-length and require caller-allocated buffers; use ovphysx_articulation_get_dof_names / get_body_names / get_joint_names instead.

  Public Members

  int32_t dof_count

    Number of degrees of freedom (DOFs)

  int32_t body_count

    Number of links.

  int32_t joint_count

    Number of joints.

  int32_t fixed_tendon_count

    Max fixed tendons (0 if none)

  int32_t spatial_tendon_count

    Max spatial tendons (0 if none)

  bool is_fixed_base

    True if base link is fixed in world.

struct ovphysx_cuda_sync_t
  #include <include/ovphysx/ovphysx_types.h>

  CUDA synchronization for GPU operations.

  Controls when the system accesses user memory and when completion is signaled.

  Fields: stream: CUDA stream for the operation

  - 0 = use default CUDA stream

  - ~0 (all bits set) = unspecified, system chooses

  - other = cudaStream_t cast to uintptr_t

  wait_event: CUDA event the system waits on BEFORE accessing user memory

  - 0 = no wait (system may access memory immediately during operation execution)

  - non-zero = cudaEvent_t cast to uintptr_t

  - System waits: cudaStreamWaitEvent(internal_stream, wait_event, 0)

  - Use this to ensure your GPU kernels have finished writing to buffers

  signal_event: CUDA event the system records AFTER operation completes

  - 0 = no signal

  - non-zero = cudaEvent_t cast to uintptr_t

  - System records: cudaEventRecord(signal_event, internal_stream)

  - Use this to synchronize downstream GPU work with operation completion

  See individual function documentation for operation-specific semantics.

  Public Members

  uintptr_t stream

    CUDA stream: 0=default, ~0=unspecified.

  uintptr_t wait_event

    CUDA event to wait on before accessing user memory: 0=none.

  uintptr_t signal_event

    CUDA event to record after operation completes: 0=none.

struct ovphysx_user_task_desc_t
  #include <include/ovphysx/ovphysx_types.h>

  Description for enqueueing a user task.

  Public Members

  ovphysx_user_task_fn run

    Task callback function.

  void *user_data

    User context (lifetime must be synchronized through events)

struct ovphysx_contact_event_header_t
  #include <include/ovphysx/ovphysx_types.h>

  Contact event header - describes one contact pair.

  ABI-stable contact header returned by ovphysx. Each header references a slice of the contact data array (contactDataOffset .. contactDataOffset + numContactData).

  Public Members

  int32_t type

    0 = found, 1 = lost, 2 = persist

  int64_t stageId

    USD stage ID.

  uint64_t actor0

    Actor 0 USD path (SdfPath encoded as uint64)

  uint64_t actor1

    Actor 1 USD path.

  uint64_t collider0

    Collider 0 USD path.

  uint64_t collider1

    Collider 1 USD path.

  uint32_t contactDataOffset

    Index into the contact data array.

  uint32_t numContactData

    Number of contact points for this pair.

  uint32_t frictionAnchorsDataOffset

    Index into the friction anchors array.

  uint32_t numfrictionAnchorsData

    Number of friction anchors for this pair.

  uint32_t protoIndex0

    Point instancer index (0xFFFFFFFF if N/A)

  uint32_t protoIndex1

    Point instancer index (0xFFFFFFFF if N/A)

struct ovphysx_contact_point_t
  #include <include/ovphysx/ovphysx_types.h>

  Per-contact-point data returned by ovphysx.

  position, normal, and impulse are float[3] in world space.

  Public Members

  float position[3]

    Contact position (world space)

  float normal[3]

    Contact normal.

  float impulse[3]

    Contact impulse (divide by dt for force)

  float separation

    Contact separation distance.

  uint32_t faceIndex0

    Triangle mesh face index for collider 0.

  uint32_t faceIndex1

    Triangle mesh face index for collider 1.

  uint64_t material0

    Material SdfPath for collider 0.

  uint64_t material1

    Material SdfPath for collider 1.

struct ovphysx_friction_anchor_t
  #include <include/ovphysx/ovphysx_types.h>

  Friction anchor data returned by ovphysx.

  Public Members

  float position[3]

    Anchor position (world space)

  float impulse[3]

    Friction impulse (divide by dt for force)

struct ovphysx_prim_list_t
  #include <include/ovphysx/ovphysx_types.h>

  List of USD prim paths for batch operations.

  Public Members

  const ovphysx_string_t *prim_paths

    Array of USD prim path strings.

  size_t num_paths

    Number of paths in array.

struct ovphysx_config_entry_t
  #include <include/ovphysx/ovphysx_types.h>

  A typed config entry (tagged union).

  key_type selects which member of key and value is valid. Use the builder functions in ovphysx_config.h for convenient construction.

  Public Members

  ovphysx_config_key_type_t key_type

    Discriminator.

  ovphysx_config_bool_t bool_key
  ovphysx_config_int32_t int32_key
  ovphysx_config_float_t float_key
  ovphysx_config_string_t string_key
  ovphysx_string_t carbonite_key

    For KEY_TYPE_CARBONITE: arbitrary Carbonite path.

  union ovphysx_config_entry_t::[anonymous] key
  bool bool_value
  int32_t int32_value
  float float_value
  ovphysx_string_t string_value

    For KEY_TYPE_STRING and KEY_TYPE_CARBONITE.

  union ovphysx_config_entry_t::[anonymous] value

struct ovphysx_config_t
  #include <include/ovphysx/ovphysx_types.h>

  Config array container (convenience wrapper).

  Public Members

  const ovphysx_config_entry_t *entries
  uint32_t entry_count

struct ovphysx_create_args
  #include <include/ovphysx/ovphysx_types.h>

  Configuration for creating an ovphysx instance.

  Initialize with OVPHYSX_CREATE_ARGS_DEFAULT for safe defaults.

  active_cuda_gpus restricts which GPU ordinals this instance may use. Per-scene CPU/GPU dynamics are controlled by physxScene:enableGPUDynamics in the USD stage; ovphysx never reads or writes those settings.

  To force process-wide CPU-only mode (no CUDA driver touch ever), call ovphysx_set_cpu_mode(true) before creating any instances.

  ### DirectGPU notes

  DirectGPU (eENABLE_DIRECT_GPU_API) skips GPU-to-CPU readback for faster steps. It is opt-in: set /physics/suppressReadback=true via Carbonite settings BEFORE ovphysx_create_instance. Restrictions: disables contact modification (no surface velocity, no custom contact callbacks); host-side actor accessors return stale data after DirectGPU initializes.

  Public Members

  ovphysx_string_t bundled_deps_path

    Bundled deps path: empty = runtime discovery (default: empty)

  const ovphysx_config_entry_t *config_entries

    Array of typed config entries.

  uint32_t config_entry_count

    Number of config entries.

  ovphysx_string_t active_cuda_gpus

    Comma-separated CUDA device ordinals (default: empty = GPU 0).

    Restricts which GPU ordinal(s) are used. Supported patterns:

    - Empty or “0”: single GPU 0 (default)

    - ”N”: single GPU N

    - ”-1”: PhysX default CUDA selection

    - ”0,1,…,N-1”: all N GPUs, round-robin across scenes

    - ”1,2,…,N-1”: all GPUs except first, round-robin Other patterns return OVPHYSX_API_INVALID_ARGUMENT.

struct ovphysx_debug_point_t
  #include <include/ovphysx/ovphysx_types.h>

  Debug-visualization primitives, read from ovphysx_debug_render_get_points / _lines / _triangles.

  The layout matches omni::physx DebugPoint / DebugLine / DebugTriangle (a carb::Float3 position plus a uint32 colour) so the OvPhysX debug buffer is read directly with no copy or per-element translation. Colours are 0xAARRGGBB (PhysX debug colour).

  Public Members

  float pos[3]
  uint32_t color

struct ovphysx_debug_line_t
  #include <include/ovphysx/ovphysx_types.h>

  Public Members

  float pos0[3]
  uint32_t color0
  float pos1[3]
  uint32_t color1

struct ovphysx_debug_triangle_t
  #include <include/ovphysx/ovphysx_types.h>

  Public Members

  float pos0[3]
  uint32_t color0
  float pos1[3]
  uint32_t color1
  float pos2[3]
  uint32_t color2

## Typed Config Entries

Builder functions for typed config entries.

Provides static inline helpers to construct ovphysx_config_entry_t values for use with ovphysx_create_instance() and ovphysx_set_global_config().

Pattern: generic type builders + named convenience functions per enum value. Matches the ovrtx_config.h builder pattern for API consistency.

Functions

static inline ovphysx_config_entry_t ovphysx_config_entry_bool(

  ovphysx_config_bool_t key,
  bool value,

)

  Build a config entry for a boolean setting.

static inline ovphysx_config_entry_t ovphysx_config_entry_int32(

  ovphysx_config_int32_t key,
  int32_t value,

)

  Build a config entry for an int32 setting.

static inline ovphysx_config_entry_t ovphysx_config_entry_float(

  ovphysx_config_float_t key,
  float value,

)

  Build a config entry for a float setting.

static inline ovphysx_config_entry_t ovphysx_config_entry_string(

  ovphysx_config_string_t key,
  ovphysx_string_t value,

)

  Build a config entry for a string setting.

  value.ptr must remain valid until the API call that consumes the config returns.

static inline ovphysx_config_entry_t ovphysx_config_entry_carbonite(

  ovphysx_string_t key,
  ovphysx_string_t value,

)

  Build a config entry for an arbitrary Carbonite setting (direct override).

  The key is a Carbonite settings path (e.g., “/physics/updateToUsd”) and the value is a string whose type is auto-detected at runtime: “true”/”false” → bool, integer string → int, float string → float, else string.

  Both key.ptr and value.ptr must remain valid until the API call returns.

static inline ovphysx_config_entry_t ovphysx_config_entry_disable_contact_processing(

  bool value,

)

  Enable/disable contact processing (/physics/disableContactProcessing).

static inline ovphysx_config_entry_t ovphysx_config_entry_collision_cone_custom_geometry(

  bool value,

)

  Enable/disable cone custom geometry for collisions (/physics/collisionConeCustomGeometry).

static inline ovphysx_config_entry_t ovphysx_config_entry_collision_cylinder_custom_geometry(

  bool value,

)

  Enable/disable cylinder custom geometry for collisions (/physics/collisionCylinderCustomGeometry).

static inline ovphysx_config_entry_t ovphysx_config_entry_num_threads(

  int32_t value,

)

  Set number of worker threads (/physics/numThreads).

  0 = auto.

static inline ovphysx_config_entry_t ovphysx_config_entry_scene_multi_gpu_mode(

  int32_t value,

)

  Set scene multi-GPU mode (/physics/sceneMultiGPUMode).

  0=disabled, 1=all GPUs, 2=skip first GPU.

static inline ovphysx_config_entry_t ovphysx_config_entry_omnipvd_ovd_recording_directory(

  ovphysx_string_t value,

)

  Set OmniPVD OVD recording directory (/persistent/physics/omniPvdOvdRecordingDirectory).

  Both this and omnipvd_output_enabled must be set before instance creation. When passed together in config_entries, order within the array does not matter (both are applied before the physics engine reads them). value.ptr must remain valid until the API call returns.

static inline ovphysx_config_entry_t ovphysx_config_entry_omnipvd_output_enabled(

  bool value,

)

  Enable/disable OmniPVD recording (/physics/omniPvdOutputEnabled).

  Both this and omnipvd_ovd_recording_directory must be set before instance creation. When passed together in config_entries, order within the array does not matter.

## C++ Wrappers (Experimental)

C++17 RAII wrappers and helpers in the `ovphysx` namespace.

namespace ovphysx

  Functions

  inline ovphysx_api_status_t shutdown()

    Clear the ovphysx process-lifecycle token.

    Thin wrapper for ovphysx_shutdown(). See the C header for full semantics. This does not destroy live handles; Carbonite and the static PhysX runtime remain resident until process exit.

    Returns:

      OVPHYSX_API_SUCCESS on success, OVPHYSX_API_ERROR if called without a matching ovphysx_initialize().

  inline ObjectChangeSubscription subscribeObjectChanges(
    ObjectChangeCallbacks callbacks,
  )

    Subscribe to PhysX object create/destroy notifications.

    Returns an RAII handle whose destructor calls ovphysx_unsubscribe_object_changes(). On failure (no callbacks set, internal sidecar not loaded, etc.) the returned handle satisfies `!handle.isActive()`; the underlying C call’s error is not exposed through this overload. Subscriptions are process-global &#8212; callbacks fire for events on every ovphysx instance in the process. See the docstring on ovphysx_subscribe_object_changes in ovphysx.h for the full contract.

  class CreateArgs
    #include <include/ovphysx/experimental/ovphysx.hpp>

    Safe wrapper for ovphysx_create_args.

    Default-constructs to OVPHYSX_CREATE_ARGS_DEFAULT (empty active_cuda_gpus, no config entries, empty bundled deps path). Use setters to override individual fields before passing to PhysX::create().

    Callers do not need to touch ovphysx_create_args directly — this class guarantees all fields are initialized.

    Public Functions

    CreateArgs()
    CreateArgs(const CreateArgs&)
    CreateArgs &operator=(const CreateArgs&)
    CreateArgs(CreateArgs&&) noexcept
    CreateArgs &operator=(CreateArgs&&) noexcept
    void setActiveCudaGpus(const std::string &gpus)
      Parameters:

        gpus – Comma-separated CUDA device ordinals, e.g. “0”, “0,1,2”, “1,2”. See active_cuda_gpus on ovphysx_create_args for supported patterns. CreateArgs copies the string internally; the caller does not need to keep the argument alive after this call returns.

    void setBundledDepsPath(const std::string &path)
      Parameters:

        path – Bundled deps path. CreateArgs copies the string internally; the caller does not need to keep the argument alive after this call returns.

    void setConfigEntries(
      const ovphysx_config_entry_t *entries,
      uint32_t count,
    )
      Parameters:

        - entries – Pointer to an array of config entries. The caller must keep this array valid until PhysX::create() returns — CreateArgs does not copy the data.

        - count – Number of entries in the array.

    const ovphysx_create_args &cArgs() const

      Returns a const reference to the underlying ovphysx_create_args. The reference is valid only for the lifetime of this CreateArgs object.

  struct ObjectChangeCallbacks
    #include <include/ovphysx/experimental/ovphysx.hpp>

    Callback set for ObjectChangeSubscription.

    Each callback is optional; an unset std::function is skipped rather than called. At least one of the three must be set, otherwise subscribeObjectChanges() returns an inactive ObjectChangeSubscription (check ObjectChangeSubscription::isActive() to detect this).

    Threading: callbacks may fire from internal worker threads during PhysX::step() or PhysX::reset_stage(). Do not call other ovphysx APIs from inside a callback &#8212; defer that work to after the next waitOp() / waitAll() returns.

    PhysX::clone() does NOT emit onCreated for clone-replicated objects. Refresh cached PhysX pointers after PhysX::clone() returns and PhysX::waitAll() completes, not by waiting for a callback.

    Public Members

    std::function<void(std::string_view primPath, ovphysx_physx_type_t type)> onCreated

      Fires AFTER the object is created. Safe to call PhysX::getPhysXPtr() from a deferred handler.

    std::function<void(std::string_view primPath, ovphysx_physx_type_t type)> onDestroyed

      Fires BEFORE the object is destroyed. Drop any cached pointer for primPath / type at this point.

    std::function<void()> onAllDestroyed

      Fires BEFORE a bulk teardown (e.g. PhysX::reset_stage()). Flush the entire pointer cache; no per-object onDestroyed events follow.

  class ObjectChangeSubscription
    #include <include/ovphysx/experimental/ovphysx.hpp>

    RAII subscription handle returned by subscribeObjectChanges().

    On destruction, unsubscribes via ovphysx_unsubscribe_object_changes() so the callbacks stop firing. Movable, non-copyable.

    Public Functions

    inline ObjectChangeSubscription() noexcept
    ObjectChangeSubscription(const ObjectChangeSubscription&) = delete
    ObjectChangeSubscription &operator=(
      const ObjectChangeSubscription&,
    ) = delete
    inline ObjectChangeSubscription(
      ObjectChangeSubscription &&other,
    ) noexcept
    inline ObjectChangeSubscription &operator=(
      ObjectChangeSubscription &&other,
    ) noexcept
    inline ~ObjectChangeSubscription()
    inline bool isActive() const noexcept

      Returns true if this handle owns a live subscription.

    inline ovphysx_subscription_id_t id() const noexcept

      Underlying C subscription ID (or OVPHYSX_INVALID_SUBSCRIPTION_ID if inactive).

    inline void unsubscribe()

      Unsubscribe explicitly. Idempotent.

      On success, both m_id and m_state are cleared. If the underlying C unsubscribe FAILS (e.g. internal sidecar unloaded), m_state is intentionally leaked rather than freed &#8212; the C-side subscription may still hold a pointer to it, and freeing would leave a dangling user_data for any in-flight or queued callback. m_id is still cleared so the handle is considered consumed by the caller.

    struct State
      #include <include/ovphysx/experimental/ovphysx.hpp>

      Public Members

      ObjectChangeCallbacks callbacks
  class PhysX
    #include <include/ovphysx/experimental/ovphysx.hpp>

    RAII wrapper for ovphysx_handle_t.

    Automatically calls ovphysx_destroy_instance on destruction. Move-only (non-copyable) to ensure unique ownership.

    Provides implicit conversion to ovphysx_handle_t for seamless use with C API.

    Example: ovphysx_initialize(); { CreateArgs args; PhysX physx; PhysX::create(physx, args); physx.step(0.01f); physx.waitAll(); } ovphysx_shutdown();

    Notes:

    - Use PhysX::create to obtain a valid instance; methods log and return errors if the handle is null.

    - Use waitOp/waitAll when you need results outside stream order.

    Public Types

    using ContactEventHeader = ovphysx_contact_event_header_t
    using ContactPoint = ovphysx_contact_point_t
    using FrictionAnchor = ovphysx_friction_anchor_t
    using SceneQueryHit = ovphysx_scene_query_hit_t

    Public Functions

    explicit PhysX(ovphysx_handle_t h)

      Construct from existing handle (takes ownership)

    PhysX()

      Default constructor - creates null handle.

    ~PhysX()

      Destructor - destroys instance if valid.

    PhysX(PhysX &&other) noexcept

      Move constructor.

    PhysX &operator=(PhysX &&other) noexcept

      Move assignment.

    PhysX(const PhysX&) = delete
    PhysX &operator=(const PhysX&) = delete
    inline ovphysx_handle_t handle() const

      Get raw handle.

    inline operator ovphysx_handle_t() const

      Implicit conversion to handle for use with C API.

    inline explicit operator bool() const

      Check if handle is valid.

    ovphysx_handle_t release()

      Release ownership of handle (caller must destroy)

    void reset(ovphysx_handle_t h = 0)

      Reset to new handle (destroys current if valid)

    ovphysx_api_status_t reset_stage()

      Reset the stage to empty (does not change the simulation-time counter)

    ovphysx_api_status_t attachOvstage(
      ovstage_instance_t *stage,
      ovstage_ordinal_t read_ordinal,
    )

      Attach an ovstage Stage through the top-level ovphysx API. `read_ordinal` is the caller-owned sealed ordinal the initial scene parse reads at.

    ovphysx_api_status_t updateFromOvstage(ovstage_ordinal_range_t range)

      Pull and apply ovstage changes over the committed ordinal range.

    ovphysx_api_status_t clone(
      const std::string &sourcePath,
      const std::vector<std::string> &targetPaths,
      const float *parentTransforms = nullptr,
      const uint32_t *envIds = nullptr,
      ovphysx_op_index_t *outOpIndex = nullptr,
    )

      Clone a USD prim hierarchy to create multiple runtime physics copies.

      Creates physics-optimized clones in the internal representation for high-performance simulation. The source prim must exist in the loaded USD stage and have physics properties. Replication runs inline (any returned op index is already complete), backed by the PhysX SDK replicator, so cloned articulations are real articulations.

      This is the clone entrypoint for both standalone callers and callers that populate the scene through an ovstage Stage attached via the C API `ovphysx_attach_ovstage`. Replication runs in the internal representation only (USD untouched).

      Parameters:

        - sourcePath – USD path of the source prim hierarchy (e.g., “/World/env0”)

        - targetPaths – Vector of USD paths for cloned hierarchies (e.g., [“/World/env1”, “/World/env2”])

        - parentTransforms – World pose of each copy’s parent. Flat array of [targetPaths.size() * 7] floats: (px, py, pz, qx, qy, qz, qw) per target (copy = transform * inverse(source_parent) * body). Pass nullptr to co-locate every copy on the source.

        - envIds – Optional logical environment id per target ([targetPaths.size()] uint32, each < 0x00FFFFFF; runtime id = envIds[i]+1). Stable across calls: the same id maps to the same environment, so clones sharing an id collide and stay isolated from other environments. Pass nullptr for automatic per-call numbering.

        - outOpIndex – Optional; receives the clone operation index on success (usable with waitOp()). The clone completes synchronously, so waiting is only for API uniformity.

      Returns:

        OVPHYSX_API_SUCCESS if cloning succeeded, OVPHYSX_API_ERROR on error

    ovphysx_api_status_t step(float step_dt)

      Enqueue a physics simulation step (simulation time tracked internally).

    ovphysx_api_status_t updateArticulationsKinematic()

      Recompute articulation link poses from current joint positions without stepping simulation.

    ovphysx_api_status_t addUserTask(
      const ovphysx_user_task_desc_t &desc,
      ovphysx_op_index_t &out_op_index,
    )

      Add a user task to the execution queue.

    physx::WaitResult waitOp(
      ovphysx_op_index_t op_index,
      uint64_t timeout_ns = UINT64_MAX,
    )

      Wait for a specific operation to complete.

    physx::WaitResult waitAll(uint64_t timeout_ns = UINT64_MAX)

      Wait for all pending operations to complete.

    ovphysx_api_status_t createTensorBinding(
      TensorBinding &out_binding,
      const std::string &pattern,
      ovphysx_tensor_type_t tensor_type,
    )

      Create a tensor binding for bulk physics data access.

      Creates a binding that connects USD prim paths (matched by pattern) to a tensor type, enabling efficient bulk read/write of simulation state.

      Parameters:

        - out_binding – Receives the created TensorBinding on success

        - pattern – USD prim path pattern (e.g., “/World/robot*”)

        - tensor_type – The type of tensor data to bind

      Returns:

        OVPHYSX_API_SUCCESS on success

    template<typename T>
    inline ovphysx_api_status_t getPhysXPtr(
      const std::string &primPath,
      T *&out,
    ) const

      Type-safe accessor: deduces the enum from the PhysX pointer type.

      Example: `physx::PxScene* s; physx.getPhysXPtr("/World/scene", s);` Compile error if T has no PhysXTypeFor<T> specialization.

    inline ovphysx_api_status_t getPhysXPtr(
      const std::string &primPath,
      ovphysx_physx_type_t type,
      void *&out,
    ) const

      Explicit-enum accessor for advanced use or unsupported types.

      Prefer the two-argument overload above when T is a known PhysX type.

    inline ovphysx_api_status_t getContactReport(
      const ContactEventHeader *&headers,
      uint32_t &numHeaders,
      const ContactPoint *&points,
      uint32_t &numPoints,
      const FrictionAnchor **anchors = nullptr,
      uint32_t *numAnchors = nullptr,
    ) const

      Get contact report data for the current simulation step.

      Returns typed pointers to the internal contact buffers. Data is valid until the next simulation step.

      Parameters:

        - headers – [out] Pointer to contact event header array.

        - numHeaders – [out] Number of headers.

        - points – [out] Pointer to contact point data array.

        - numPoints – [out] Number of contact point entries.

        - anchors – [out] Optional. Pointer to friction anchor array (pass nullptr to skip).

        - numAnchors – [out] Optional. Friction anchor count (pass nullptr to skip).

    inline ovphysx_api_status_t raycast(
      const float origin[3],
      const float direction[3],
      float distance,
      bool both_sides,
      ovphysx_scene_query_mode_t mode,
      const SceneQueryHit *&hits,
      uint32_t &count,
    ) const

      Cast a ray into the scene.

      Parameters:

        - origin – Ray origin (world space).

        - direction – Normalized ray direction.

        - distance – Maximum ray length.

        - both_sides – Test both sides of mesh triangles.

        - mode – CLOSEST, ANY, or ALL.

        - hits – [out] Pointer to internal hit array (valid until next scene query call).

        - count – [out] Number of hits.

    inline ovphysx_api_status_t sweep(
      const ovphysx_scene_query_geometry_desc_t &geometry,
      const float direction[3],
      float distance,
      bool both_sides,
      ovphysx_scene_query_mode_t mode,
      const SceneQueryHit *&hits,
      uint32_t &count,
    ) const

      Sweep a geometry shape through the scene.

      Parameters:

        - geometry – Geometry descriptor.

        - direction – Normalized sweep direction.

        - distance – Maximum sweep length.

        - both_sides – Test both sides of mesh triangles.

        - mode – CLOSEST, ANY, or ALL.

        - hits – [out] Pointer to internal hit array (valid until next scene query call).

        - count – [out] Number of hits.

    inline ovphysx_api_status_t overlap(
      const ovphysx_scene_query_geometry_desc_t &geometry,
      ovphysx_scene_query_mode_t mode,
      const SceneQueryHit *&hits,
      uint32_t &count,
    ) const

      Test geometry overlap against objects in the scene.

      Parameters:

        - geometry – Geometry descriptor.

        - mode – ANY or ALL. CLOSEST falls back to ALL because overlap tests have no distance ordering.

        - hits – [out] Pointer to internal hit array (valid until next scene query call).

        - count – [out] Number of overlapping objects.

    Public Static Functions

    static ovphysx_api_status_t create(
      PhysX &out_instance,
      const CreateArgs &args,
    )

      Factory method to create a PhysX instance from CreateArgs.

      This is the primary creation path. Use CreateArgs to configure device selection, GPU index, config entries, and other options.

      Example:

          ovphysx_initialize();
          {
              CreateArgs args;
              args.setConfigEntries(entries, 2);
              PhysX physx;
              auto status = PhysX::create(physx, args);
              if (status != OVPHYSX_API_SUCCESS) { ... handle error ... }
          }
          ovphysx_shutdown();

      Parameters:

        - out_instance – Receives the created PhysX instance on success.

        - args – Creation arguments (default-constructed = OVPHYSX_CREATE_ARGS_DEFAULT).

      Returns:

        OVPHYSX_API_SUCCESS on success; OVPHYSX_API_INVALID_ARGUMENT on inconsistent args (e.g. config_entry_count > 0 with null pointer).

    static ovphysx_api_status_t setCpuMode(bool cpuOnly)

      Force process-wide CPU-only mode. Must be called before any instances are active. See ovphysx_set_cpu_mode() for full semantics.

  template<typename T>
  struct PhysXTypeFor

    Traits mapping a PhysX SDK type to its ovphysx_physx_type_t enum value. Enables type-safe getPhysXPtr() overloads that auto-deduce the enum.

  template<>
  struct PhysXTypeFor<::physx::PxArticulationJointReducedCoordinate>
    #include <include/ovphysx/experimental/ovphysx.hpp>

    Public Static Attributes

    static constexpr ovphysx_physx_type_t value = OVPHYSX_PHYSX_TYPE_LINK_JOINT
  template<>
  struct PhysXTypeFor<::physx::PxArticulationLink>
    #include <include/ovphysx/experimental/ovphysx.hpp>

    Public Static Attributes

    static constexpr ovphysx_physx_type_t value = OVPHYSX_PHYSX_TYPE_LINK
  template<>
  struct PhysXTypeFor<::physx::PxArticulationReducedCoordinate>
    #include <include/ovphysx/experimental/ovphysx.hpp>

    Public Static Attributes

    static constexpr ovphysx_physx_type_t value = OVPHYSX_PHYSX_TYPE_ARTICULATION
  template<>
  struct PhysXTypeFor<::physx::PxJoint>
    #include <include/ovphysx/experimental/ovphysx.hpp>

    Public Static Attributes

    static constexpr ovphysx_physx_type_t value = OVPHYSX_PHYSX_TYPE_JOINT
  template<>
  struct PhysXTypeFor<::physx::PxMaterial>
    #include <include/ovphysx/experimental/ovphysx.hpp>

    Public Static Attributes

    static constexpr ovphysx_physx_type_t value = OVPHYSX_PHYSX_TYPE_MATERIAL
  template<>
  struct PhysXTypeFor<::physx::PxRigidActor>
    #include <include/ovphysx/experimental/ovphysx.hpp>

    Public Static Attributes

    static constexpr ovphysx_physx_type_t value = OVPHYSX_PHYSX_TYPE_ACTOR
  template<>
  struct PhysXTypeFor<::physx::PxScene>
    #include <include/ovphysx/experimental/ovphysx.hpp>

    Public Static Attributes

    static constexpr ovphysx_physx_type_t value = OVPHYSX_PHYSX_TYPE_SCENE
  template<>
  struct PhysXTypeFor<::physx::PxShape>
    #include <include/ovphysx/experimental/ovphysx.hpp>

    Public Static Attributes

    static constexpr ovphysx_physx_type_t value = OVPHYSX_PHYSX_TYPE_SHAPE
  class TensorBinding
    #include <include/ovphysx/experimental/TensorBinding.hpp>

    RAII wrapper for ovphysx_tensor_binding_handle_t.

    Automatically calls ovphysx_destroy_tensor_binding on destruction. Move-only (non-copyable) to ensure unique ownership.

    Created via PhysX::createTensorBinding(). Do not construct directly.

    Example: TensorBinding binding; physx.createTensorBinding(binding, “/World/robot”, OVPHYSX_TENSOR_ARTICULATION_DOF_POSITION_F32); binding.read(myTensor);

    Public Functions

    TensorBinding()
    ~TensorBinding()
    TensorBinding(TensorBinding &&other) noexcept
    TensorBinding &operator=(TensorBinding &&other) noexcept
    TensorBinding(const TensorBinding&) = delete
    TensorBinding &operator=(const TensorBinding&) = delete
    inline ovphysx_tensor_binding_handle_t handle() const

      Get the raw binding handle (for use with C API)

    inline explicit operator bool() const

      Check whether this wrapper currently owns a non-null binding handle. This does not query whether the underlying TensorAPI view survived a stage reset or bound-object removal; read/write will report that error.

    ovphysx_api_status_t spec(ovphysx_tensor_spec_t &out_spec) const

      Query the tensor spec (dtype, ndim, shape)

    ovphysx_api_status_t metadata(
      ovphysx_articulation_metadata_t &out_metadata,
    ) const

      Query articulation topology metadata (dof_count, body_count, joint_count, fixed_tendon_count, spatial_tendon_count, is_fixed_base). Only valid for articulation bindings; returns OVPHYSX_API_ERROR otherwise.

    ovphysx_api_status_t read(DLTensor &dst) const

      Read simulation data into a DLTensor.

    ovphysx_api_status_t write(
      const DLTensor &src,
      const DLTensor *indices = nullptr,
    ) const

      Write data from a DLTensor, optionally with an index tensor for sparse updates.

    ovphysx_api_status_t writeMasked(
      const DLTensor &src,
      const DLTensor &mask,
    ) const

      Write data from a DLTensor using a boolean mask for selective updates.

    void destroy()

      Explicitly destroy the binding (called automatically by destructor)

  namespace detail

    Functions

    inline void objectChangeCreatedTrampoline(
      ovphysx_string_t primPath,
      ovphysx_physx_type_t type,
      void *userData,
    )
    inline void objectChangeDestroyedTrampoline(
      ovphysx_string_t primPath,
      ovphysx_physx_type_t type,
      void *userData,
    )
    inline void objectChangeAllDestroyedTrampoline(void *userData)
  namespace physx
    class WaitResult
      #include <include/ovphysx/experimental/Helpers.hpp>

      RAII wrapper for ovphysx_op_wait_result_t.

      Automatically calls ovphysx_destroy_wait_result when destroyed. Use get() to pass to ovphysx_wait_op.

      Example: WaitResult wait; ovphysx_result_t r = ovphysx_wait_op(handle, op_index, timeout, wait.get());

      if (wait.hasErrors()) { for (size_t i = 0; i < wait.errorCount(); ++i) { ovphysx_string_t err = ovphysx_get_last_op_error(wait.errorOpIndexAt(i)); std::cerr << “Op “ << wait.errorOpIndexAt(i) << “ failed: “ << std::string(err.ptr, err.length) << std::endl; } } // wait result freed automatically when wait goes out of scope

      Public Functions

      inline WaitResult()
      inline ~WaitResult()
      inline WaitResult(WaitResult &&other) noexcept
      inline WaitResult &operator=(WaitResult &&other) noexcept
      WaitResult(const WaitResult&) = delete
      WaitResult &operator=(const WaitResult&) = delete
      inline ovphysx_op_wait_result_t *get()

        Get pointer to underlying result (pass to ovphysx_wait_op)

      inline const ovphysx_op_wait_result_t *get() const
      inline bool hasErrors() const

        Check if there were any errors.

      inline size_t errorCount() const

        Number of errors.

      inline ovphysx_op_index_t lowestPendingOpIndex() const

        Get lowest pending operation index (0 if all complete)

      inline ovphysx_op_index_t errorOpIndexAt(size_t i) const

        Get the failed operation index at position i.