C API Reference#

The full C API is defined in these headers:

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

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 or velocities when link state must reflect the new generalized state before the next simulation step. Pass a live OVPHYSX_QUERY_TARGET_ARTICULATION query to select the articulations and POSITION and/or VELOCITY flags. The Python method is PhysX.update_articulations_kinematic(), and the experimental C++ wrapper is PhysX::updateArticulationsKinematic(). The C and C++ calls return a task receipt; wait for it before using updated link poses. Python waits internally and returns None, raising any execution failure; its scope argument creates the articulation query. The native operation currently executes inline. It 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_start_recording(
ovphysx_instance_handle_t handle,
const ovphysx_omnipvd_destination_t *destination,
)#

Deprecated forwarding exports introduced in 0.6 and retained in 0.7.

ovphysx_result_t ovphysx_stop_recording(
ovphysx_instance_handle_t handle,
)#
ovphysx_result_t ovphysx_is_recording(
ovphysx_instance_handle_t handle,
bool *out_is_recording,
)#
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(
ovphysx_instance_handle_t *out_handle,
)#

Create a new instance with default instance configuration.

Set process-global configuration before this call. After creation, instance configuration may be changed with ovphysx_set_config() until the instance attaches a stage.

Parameters:

out_handle – [out] New owned instance handle.

Returns:

OVPHYSX_API_SUCCESS, OVPHYSX_API_INVALID_ARGUMENT when out_handle is NULL, or OVPHYSX_API_ERROR when lifecycle/runtime initialization fails.

ovphysx_result_t ovphysx_destroy_instance(
ovphysx_instance_handle_t handle,
)#

Destroy an ovphysx instance and release per-instance resources.

Per-instance destruction leaves the process lifecycle active. Call ovphysx_shutdown after destroying the final handle to drain the direct PhysX runtime and clear that lifecycle token.

#include <ovphysx/ovphysx.h>

static ovphysx_result_t destroy_owned_instance(ovphysx_instance_handle_t handle)
{
    return 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_INVALID_STATE is retryable: admission rejected before teardown; the handle, attachment and caller ownership remain live. Close companion leases or finish pending work/transitions before retrying.

  • OVPHYSX_API_ERROR if the handle is not registered or destruction fails. An unregistered handle is rejected before teardown and does not affect registered instances or process-global asynchronous state. No error string is returned. Consult logs for other destruction failures.

Parameters:

handle – ovphysx handle to destroy.

Returns:

ovphysx_result_t with status and error info.

Post:

On success, the handle is unregistered and its resources are released. A repeated call for that already-unregistered value returns OVPHYSX_API_ERROR before teardown and has no effect on registered instances or process-global asynchronous state.

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.

On every successful return, including when live handles remain, shutdown flushes Carbonite’s buffered records, stops accepting application-callback delivery, and drains accepted callbacks. When runtime teardown occurs, the barrier includes its final log producer. The callback and its user-data resources may then be released. Accepted callbacks must not wait indefinitely on the thread performing shutdown.

Static runtime mode

With no live handles, shutdown drains the direct PhysX runtime. On Linux it also releases the SDK-owned Carbonite framework and private cooking cache. Windows retains the framework until process exit for safe dependency DLL teardown; private cache removal after datastore shutdown is best-effort. A framework populated by a foreign host remains owned by that host. If live handles remain, callers still own them and the direct runtime remains available only for their explicit destruction. Continued stepping or other instance work after shutdown is unsupported, and destruction-time records are not delivered to the application callback disabled by shutdown.

Returns:

  • OVPHYSX_API_SUCCESS on success.

  • OVPHYSX_API_INVALID_STATE is retryable: retained companion service leases still prevent shutdown. The lifecycle token remains live.

  • OVPHYSX_API_ERROR if called without a matching ovphysx_initialize.

  • OVPHYSX_API_ERROR if called from the application log callback. 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_global_config_key_t key,
ovphysx_config_value_t value,
)#

Set process-global configuration.

Environment overrides remain authoritative. Startup-only keys must be set before the first successful instance creation. Later writes return OVPHYSX_API_INVALID_STATE without changing the value, even after all instances are destroyed, until ovphysx_shutdown() succeeds with no live instances.

ovphysx_result_t ovphysx_get_global_config(
ovphysx_global_config_key_t key,
ovphysx_config_value_t *out_value,
)#

Read the effective process-global configuration value.

ovphysx_result_t ovphysx_set_config(
ovphysx_instance_handle_t instance,
ovphysx_config_key_t key,
ovphysx_config_value_t value,
)#

Set configuration retained by one instance.

Current instance keys are pre-attach: changing them after a stage is attached returns OVPHYSX_API_INVALID_STATE and preserves the prior value.

ovphysx_result_t ovphysx_get_config(
ovphysx_instance_handle_t instance,
ovphysx_config_key_t key,
ovphysx_config_value_t *out_value,
)#

Read configuration retained by one instance.

ovphysx_result_t ovphysx_ovd_start_recording(
ovphysx_instance_handle_t handle,
const ovphysx_omnipvd_destination_t *destination,
)#

Start an OVD recording session.

The call is synchronous. A FILE destination is an exact path. A TCP destination connects to a ready listener. Validation and stream-open failures may be retried. Only one recording may be active in the shared runtime: another start returns OVPHYSX_API_INVALID_STATE without replacing its destination. After a successful stop, another FILE or TCP session may be started. Late start requires a live physics stage in the shared runtime. Before its first attach and between detach and reattach it returns OVPHYSX_API_INVALID_STATE.

Make the shared runtime OVD recording capable by setting OVPHYSX_GLOBAL_CONFIG_OVD_RECORDING_CAPABLE to true with ovphysx_set_global_config() before the first ovphysx_create_instance(). The key defaults to false. Capability alone does not start recording; attach a physics stage and call this function with the desired destination. Pass ovphysx_config_value_bool(true), declared in ovphysx_config.h. A default, incapable runtime returns OVPHYSX_API_INVALID_STATE with an error naming the capability key. Unsupported platforms retain OVPHYSX_API_NOT_IMPLEMENTED.

Creation and attachment never start recording. After reattach, the runtime remains dormant until this function is called. Call it before the first simulation step to capture the initial state and every simulation frame.

Parameters:

  • handle – Instance requesting the recording session.

  • destination – FILE or TCP destination borrowed for this call.

Returns:

OVPHYSX_API_SUCCESS, OVPHYSX_API_INVALID_ARGUMENT for an invalid destination, OVPHYSX_API_INVALID_STATE when the runtime is not recording-capable, the shared runtime has no live physics stage, or recording is active, OVPHYSX_API_NOT_IMPLEMENTED on an unsupported platform, or OVPHYSX_API_ERROR when the destination cannot be opened or sampling cannot start.

ovphysx_result_t ovphysx_ovd_stop_recording(
ovphysx_instance_handle_t handle,
)#

Stop and finalize the active recording.

The handle that started the session owns it. A peer handle is inactive and cannot stop the owner’s session. A successful owner stop permits a later recording session to start.

Returns:

OVPHYSX_API_SUCCESS, OVPHYSX_API_INVALID_STATE when this handle owns no active recording (including while a peer owns the globally active session), or OVPHYSX_API_ERROR when stop/finalization fails.

ovphysx_result_t ovphysx_ovd_is_recording(
ovphysx_instance_handle_t handle,
bool *out_is_recording,
)#

Query whether this instance owns the active recording.

A peer reports false while another instance owns the shared runtime’s active recording.

Parameters:

  • handle – Valid instance handle.

  • out_is_recording – [out] Receives true only while sampling is active.

ovphysx_enqueue_result_t ovphysx_attach_ovstage(
ovphysx_instance_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):

  • Application to physics (control in): the application authors dirty control attributes into ovstage (drive:force, drive:velocity, drive:position_target, physics:mass, physics:gravityMagnitude, physics:gravityDirection, and so on) at ordinals it chooses, then calls ovphysx_update_from_ovstage to drain that ordinal range into the running simulation. ovphysx_step then integrates.

  • Physics to application (output out): ovphysx_step does not author simulation output back into the Stage on its own. The application 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. That ordinal is never covered by update_from_ovstage, 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 application-owned output writeback via the read API. For direct control without going through ovstage, use the session write API (ovphysx_write). The legacy tensor bindings remain available for the same purpose but are deprecated.

The attachment is init-style. Call it once per instance, before any ovphysx_step(). Replacing the attached Stage requires successful completion of ovphysx_detach_ovstage() first.

Returns a task receipt. Execution may finish inline; admission success does not establish that attachment succeeded. Collect the task with ovphysx_wait_task() before using the attachment outside instance stream order. Earlier tasks finish execution first, without collecting their outcomes.

#include <ovphysx/ovphysx.h>

static ovphysx_enqueue_result_t attach_caller_owned_stage(
    ovphysx_instance_handle_t handle,
    ovstage_instance_t* stage,
    ovstage_ordinal_t read_ordinal)
{
    return ovphysx_attach_ovstage(handle, stage, read_ordinal);
}
Errors

Admission rejects an invalid handle, null stage, or zero read_ordinal with OVPHYSX_API_INVALID_ARGUMENT, and an already-attached instance or unavailable runtime API with OVPHYSX_API_ERROR. The schema guard also rejects admission with OVPHYSX_API_ERROR if ovstage reports a missing PhysX schema family after USD schema definitions were built, including by population or export, unless the guard is disabled (see below). Rejected receipts have no task identity; the schema guard takes no Stage ownership and changes no attachment. Runtime attach failures, including unreadable schema data and mismatched tolerance scales, belong to the accepted task and are reported by its wait.

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.

Note

Each instance holds at most one live ovstage attach. Several instances may be attached at the same time. Attaching on one instance does not detach another. Detach or destroy only affects that instance’s attachment. The same ovstage instance cannot be attached twice. Process-wide limits still apply: one hard CPU-only mode, one SDK tolerance scale, and recording transitions that need every attached instance idle.

Note

The application owns schema registration. Separately install physx-usd-schemas and pass both module resource directories to ovstage_population_register_usd_schemas() before the first USD schema read, including population or export, in each process and worker. Population drops attributes of schemas it cannot resolve, including authored PhysX settings. This call checks both plugin families, physxSchema and omniUsdPhysicsDeformableSchema, once ovstage has built its USD schema registry. If ovstage reports either family missing, this and every later attach in the process fail by default. Restart and register before populating or exporting; late registration cannot repair the registry. A procedural Stage attached while USD schema definitions remain unbuilt skips the family check and leaves it active for later attaches. After population or export builds the definitions, the check applies even to procedural Stages. A registration another USD consumer made unobservable to ovstage cannot be detected. Nor can the guard identify schema families registered late before its first check: catching a late registration’s OVSTAGE_ERROR_OP_FAILED can let a later attach succeed with missing data. Always restart after a registration- ordering error; attach success does not prove schemas were available during population. The legacy create-time Carbonite setting /ovphysx/schemas/requireRegistration = false downgrades refusal to a warning and permits attach without repairing lost data; its default is true. The guard neither locates nor installs schema resources.

Note

Scenes that author Newton newton:* attributes also need the separately installed Newton USD schema (https://github.com/newton-physics/newton-usd-schemas) registered the same way; ovphysx reads those attributes as fallbacks for the PhysX spellings and does not ship that schema. Python’s PhysX.attach_ovstage() separately checks its registration and emits a warning when it cannot verify it. The C API performs no Newton check. The legacy create-time config entry /ovphysx/schemas/warnMissingNewtonSchema = false silences only the Python Newton warning, not the native PhysX registration guard.

Parameters:

  • handle – ovphysx instance handle.

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

  • read_ordinal – Caller-owned ordinal at which the initial scan’s required physics data is sealed. Must be non-zero: 0 is reserved as the runtime’s internal “use payload attach-time ordinal” sentinel. The application owns ordinal advancement. 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, and read_ordinal is non-zero.

Pre:

stage and its sealed read_ordinal data remain valid through task completion. After successful attach, stage outlives the attachment, through successful detach completion. Destroying an attached Stage is undefined behavior. A failed attach may leave an attachment if rollback fails; check ovphysx_is_stage_attached() before releasing the Stage.

Post:

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

ovphysx_enqueue_result_t ovphysx_update_from_ovstage(
ovphysx_instance_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.

Returns a task receipt. The range value is copied; the caller-owned Stage and the selected sealed data must remain valid until task completion. Successful completion makes the updates visible to subsequent work. Earlier execution is drained without collecting its outcomes. This operation may execute inline; collect its own outcome with ovphysx_wait_task().

Ordinals at or below the latest successfully consumed ordinal are skipped. A range containing only consumed ordinals is a successful no-op. An overlapping range applies only its unread suffix. The initial read_ordinal is consumed by ovphysx_attach_ovstage(), so replaying it does not recreate the attach population or emit object-change notifications. Population authored and sealed at later ordinals is applied normally.

Errors

Admission rejects an invalid range or handle with OVPHYSX_API_INVALID_ARGUMENT, and a missing attachment or runtime API with OVPHYSX_API_ERROR. Runtime range drain failures belong to the accepted task. Failed updates need not be atomic; do not assume that no edits were applied or blindly replay the range.

Parameters:

  • handle – ovphysx instance handle.

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

Pre:

handle is valid and the attach task completed successfully.

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_enqueue_result_t ovphysx_detach_ovstage(
ovphysx_instance_handle_t handle,
)#

Detach the currently-attached ovstage Stage.

Returns a task receipt, including for an idempotent no-op on an unattached instance. Execution may finish inline; collect the outcome with ovphysx_wait_task(). Earlier execution finishes without collecting its outcomes. Successful task completion ends this instance’s Stage ownership. Keep the Stage alive until then, and longer if other users still own it. A failed detach can retain attachment ownership after partially retiring resources; ovphysx_is_stage_attached() is an ownership diagnostic, not a readiness check.

This is teardown, not restoration of initial poses. Instance configuration and the private simulation-time counter are preserved. 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. Detach stops and finalizes an active OmniPVD recording started by this instance or when it removes the last live attachment. A peer-owned recording continues while another attachment remains live. After reattach, recording remains dormant until ovphysx_ovd_start_recording() is called.

Errors

Admission rejects invalid handles with OVPHYSX_API_INVALID_ARGUMENT. OVPHYSX_API_INVALID_STATE is retryable admission failure: attachment and write storage remain owned. Finish companion work or transitions and retry. Failures after teardown starts belong to the accepted task; collect them before deciding whether to retry or destroy the instance.

Parameters:

handle – ovphysx instance handle.

Pre:

handle is valid.

Post:

On successful task completion, ovphysx is unattached.

ovphysx_result_t ovphysx_is_stage_attached(
ovphysx_instance_handle_t instance_handle,
const void *stage,
bool *out_attached,
)#

Report whether this instance currently owns an attached stage.

Does not wait for simulation or validate existing resources, including resources from an earlier attachment of the same stage. This synchronous metadata snapshot neither creates a task nor collects outcomes. Wait for a lifecycle task first when its final state is needed. A false snapshot during pending attach does not permit Stage destruction, and true does not establish readiness. Serialize all calls on an instance.

Errors

  • OVPHYSX_API_INVALID_ARGUMENT if out_attached is NULL or instance_handle is invalid

Parameters:

  • instance_handle – ovphysx instance handle.

  • stage – NULL to check for any attachment, or a caller-owned stage pointer to compare with the current attachment. Never dereferenced.

  • out_attached – [out] True when a stage is attached and matches the supplied candidate (if any); false when detached, different, or on failure.

ovphysx_enqueue_result_t ovphysx_query(
ovphysx_instance_handle_t handle,
ovphysx_query_target_t object_type,
ovphysx_object_scope_t scope,
ovphysx_query_handle_t *out_query,
ovstage_query_result_t *out_summary,
)#

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 the attached Stage’s get_path_dictionary route or feed straight into the ovstage write path). Discover the produced attributes / total prim count with the optional query result. Pair every successful query with ovphysx_release_query.

An ovstage Stage must be attached (ovphysx_attach_ovstage).

Query, read, write, fetch, commit, and release return task receipts. The receipt reports admission only; wait for its task and check the task result before using outputs or starting an operation that depends on it. Keep input arrays, string storage, and output slots alive until task completion. These operations currently execute inline. The task contract does not promise that they will always finish before returning.

A successful task makes host outputs ready. CUDA columns retain the event contract below; task completion does not replace their readiness event. Rejected submissions have no task and do not consume resources. Accepted release submissions transfer cleanup to the SDK: stop using the resource immediately, even if waiting later reports failure. The SDK retains or quarantines storage whose safe release could not be established.

Resource handles belong to the instance that created them. A live handle from another instance returns OVPHYSX_API_NOT_FOUND. Releases of absent handles are successful no-ops when the supplied instance is valid.

ovphysx_enqueue_result_t ovphysx_query_selection(
ovphysx_instance_handle_t handle,
ovphysx_query_target_t object_type,
const ovphysx_query_selection_t *selection,
ovphysx_query_handle_t *out_query,
ovstage_query_result_t *out_summary,
)#

Open a query narrowed to a prim-set selection (ADR-0025).

Like ovphysx_query, but the objects of object_type are narrowed to selection &#8212; an explicit list of native prim-path handles OR a glob pattern &#8212; instead of a scope. The selection narrows BOTH the read and a write opened over the returned query &#8212; narrowing the query narrows the write, with no separate write-side call. A glob matches prims through the same resolver a tensor binding uses; an explicit list names prims directly by the handles the caller resolved. Either way the query keeps the objects of object_type whose prim is selected, and an OVPHYSX_QUERY_TARGET_ARTICULATION query also keeps each articulation one of whose links or joints is selected, as an articulation tensor binding does. Other types are not widened: OVPHYSX_QUERY_TARGET_RIGID_BODY does not cover articulation links (OVPHYSX_QUERY_TARGET_ARTICULATION_LINK does), and a link, joint or tendon query keeps only the members whose own prim is selected.

selection->pattern is an absolute path pattern (it starts with /), matched one path level per /-separated component: * and ? match within one name, ** spans any number of levels, and character classes and alternation pass through. The last component is searched at any depth below what the earlier components matched, unless it is a bare * or the pattern contains **. The complete rules, with examples, are on the “Path patterns” page of the ovphysx documentation (docs/read_write/path_patterns.md).

A selected query has no scope: it always covers every selected object of the type (the OVPHYSX_SCOPE_ALL set), including objects the solver did not move last step. It therefore stays valid across steps until a structural change, and a write opened over it never skips a selected object for being asleep. For only the objects that moved, use ovphysx_query with OVPHYSX_SCOPE_ACTIVE.

OVPHYSX_QUERY_TARGET_DEBUG_RENDER is not a prim set. This call rejects it with OVPHYSX_API_INVALID_ARGUMENT and “invalid object type”. Use ovphysx_query for that instance target.

selection is REQUIRED (non-NULL): the whole (type, scope) set is ovphysx_query. selection->prim_paths are interned ovx_primpath_t handles (see ovphysx_query_selection_t), NOT strings. prim_paths wins over pattern when both are set; they are never combined. A selection that resolves to no object of the queried type is a valid empty query &#8212; the optional query result reports total_prim_count == 0 and the first ovphysx_read fetch is end-of-iteration.

After acceptance, receipt.status is OVPHYSX_API_SUCCESS. Query construction failures are reported as OVPHYSX_API_ERROR by ovphysx_wait_task.

Errors

Rejection (receipt.status, no task):

  • OVPHYSX_API_INVALID_ARGUMENT if handle or object_type is invalid (including OVPHYSX_QUERY_TARGET_DEBUG_RENDER), out_query or selection is NULL, the selection provides neither prim_paths nor a pattern, prim_paths is NULL with a non-zero prim_paths_count, prim_paths contains OVX_INVALID_PRIMPATH, or the pattern does not start with /, contains an embedded NUL byte, or has a component exceeding the length limit.

  • OVPHYSX_API_ERROR if no ovstage is attached, the query backend is unavailable, pending simulation cannot be finished, or task creation fails.

Note

Selection narrows both the read and the write for every writable object type; a selected write that admits no prim of the queried type is a valid empty write, not an error.

Parameters:

  • handle – ovphysx instance handle.

  • object_type – Object type to query (see ovphysx_query).

  • selection – Prim-set selection (must be non-NULL; NULL returns OVPHYSX_API_INVALID_ARGUMENT).

  • out_query – [out] Nonzero and usable only after successful task completion.

  • out_summary – Optional creation-time discovery snapshot, as on ovphysx_query. Retain selection and output storage until task completion.

Returns:

ovphysx_enqueue_result_t (an enqueue receipt; wait on it with ovphysx_wait_task).

ovphysx_enqueue_result_t ovphysx_query_contacts(
ovphysx_instance_handle_t handle,
const ovphysx_contact_sensor_selection_t *selections,
uint32_t selection_count,
uint32_t filters_per_sensor,
ovphysx_query_handle_t *out_query,
ovstage_query_result_t *out_summary,
)#

Open a contact query: contact sensors with per-sensor filters (ADR-0044).

A OVPHYSX_QUERY_TARGET_CONTACT_SENSOR query whose rows are the bodies &#8212; and, on CPU simulation or GPU dynamics with CPU readback, colliders carrying PhysxContactReportAPI &#8212; the selections select, in selection order then match order, each paired with filters_per_sensor filter objects. Read it with ovphysx_read like any query. The filters are what the filtered contact attributes are measured against; the unfiltered ones (net forces) read the same on this query as on ovphysx_query.

Resolved once, when the query opens, with the contact binding’s rules: a body already matched by an earlier selection is not repeated, and each filter selection must match one object (shared by every sensor of its selection) or exactly one object per sensor (paired by position). Like the contact-sensor type, a selected body is a row only while it reports contacts (it or its articulation carries PhysxContactReportAPI); on CPU simulation or GPU dynamics with CPU readback a selected collider carrying the schema is a row too, host-only (a DirectGPU scene has no separate child-collider rows), and a body row overlaps its collider rows, so do not sum net forces or count contacts across them. A contact query has no scope, and a selection matching nothing adds no rows.

The schema on a separate child collider enables sensor selection, not reporting for its owning body. Enable reporting on the body, owning articulation link, or articulation root as well to avoid depending on reports from the other actor in each pair. The child remains a row but reads zero when neither actor reports matching contacts. Configure reporting settings on the reporting actor or articulation root. A standalone static collider is its own actor and enables reporting on CPU simulation and GPU dynamics with CPU readback; on DirectGPU its sensor row remains but reads zero force.

Errors

  • OVPHYSX_API_INVALID_ARGUMENT, before a task is created, if out_query or selections is NULL, selection_count is 0, a selection’s filters is NULL while filters_per_sensor is not 0, filters_per_sensor exceeds 21845, or any selection is invalid as for ovphysx_query_selection

  • OVPHYSX_API_ERROR if no ovstage is attached

  • OVPHYSX_API_ERROR, reported by ovphysx_wait_task, for a filter selection whose match count is neither 1 nor the selection’s sensor count, or a sensor whose filters name one object twice; the message names the selection, the filter and both counts

Parameters:

  • handle – ovphysx instance handle.

  • selections – selection_count sensor selections with their filters.

  • selection_count – Number of sensor selections (at least 1).

  • filters_per_sensor – Filter selections per sensor selection (0 for none, at most 21845).

  • out_query – [out] Nonzero and usable only after successful task completion.

  • out_summary – Optional creation-time discovery snapshot, as on ovphysx_query. Retain selections, their input buffers and output slots until task completion.

Returns:

ovphysx_enqueue_result_t (an enqueue receipt; wait on it with ovphysx_wait_task).

ovphysx_enqueue_result_t ovphysx_read(
ovphysx_instance_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,
ovphysx_read_result_t *out_summary,
)#

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_* in ovphysx_attributes.h) OR an interned token (e.g. from the optional query result, fed straight back with no token-to-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 and reported in the optional summary. Duplicate canonical requests and unresolvable tokens fail the task; tokens take precedence over strings. Already-known backend failures fail open without publishing a session.

ovphysx_enqueue_result_t ovphysx_fetch_read_next(
ovphysx_instance_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.

After successful task completion, *out_group points at the next ovstage_read_group_t, or is NULL at end of iteration. End of iteration is an ordinary successful task. A failed task leaves *out_group NULL and must not be treated as end of iteration. Keep out_group alive until completion.

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 returned group struct and its stage-derived prims.list stay valid until ovphysx_release_group for that read_group_id (or ovphysx_release_read, which releases all). The numeric storage is owned by the read session instead: data.tensors, every tensor’s shape and data, prims.index_map, data.index_map, data.mask, and data.cuda_sync.wait_event stay valid until ovphysx_release_read. Fetching further groups and an intervening ovphysx_step do NOT invalidate either lifetime (the runtime gathers each column into session-owned storage at read time). Numeric snapshots also survive stage detach until session release or instance destruction. Detach invalidates the stage dictionary and its prim-list handles; do not resolve those handles after detaching.

A device (kDLCUDA) column additionally has a readiness contract: it is handed over before its producing work has necessarily completed. Wait on group.data.cuda_sync.wait_event before reading it from a non-default stream using CUDA’s cuStreamWaitEvent or cudaStreamWaitEvent. See ovphysx_read for the full rule. Validity and readiness are separate: the borrow above means the memory may still be read, the event means the values in it are final.

A failure already known during gathering fails read creation. A later fetch can still fail, for example if the attachment was invalidated. Check task completion before interpreting a NULL group as the end of iteration. Already-fetched numeric snapshots retain their session lifetime.

After acceptance, receipt.status is OVPHYSX_API_SUCCESS. Backend fetch failures are reported as OVPHYSX_API_ERROR by ovphysx_wait_task; end of iteration is successful completion with a NULL group.

Errors

Rejection (receipt.status, no task):

  • OVPHYSX_API_INVALID_ARGUMENT if handle is invalid or out_group is null.

  • OVPHYSX_API_NOT_FOUND if read is absent, released, or belongs to another instance.

  • OVPHYSX_API_ERROR if the read backend is unavailable or task creation fails.

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:

Admission receipt. After successful task completion, NULL means done.

Pre:

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

ovphysx_enqueue_result_t ovphysx_release_group(
ovphysx_instance_handle_t handle,
ovphysx_read_handle_t read,
ovstage_read_group_id_t group_id,
)#

Release one fetched group’s borrowed storage.

Releases the stage-derived prim-list storage pinned by ovphysx_fetch_read_next for group_id (an ovstage_read_group_t::read_group_id). After this the group struct and prims.list must not be dereferenced. Tensor, prim-index-map, data-index-map, mask, and CUDA-event storage belongs to the read session and remains valid until ovphysx_release_read.

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:

Admission receipt. Accepted release ends the group borrow immediately. An already-released or unknown id is a successful no-op.

ovphysx_enqueue_result_t ovphysx_release_read(
ovphysx_instance_handle_t handle,
ovphysx_read_handle_t read,
)#

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

Finish all external CPU and CUDA consumers before submitting release or destroying the instance. The SDK waits for its own producing work before reclaiming device storage; it has no completion token for work launched by the caller. Accepted release ends all session borrows and transfers cleanup responsibility to the SDK.

Parameters:

  • handle – ovphysx instance handle.

  • read – Read-session handle from ovphysx_read.

Returns:

Admission receipt. An absent handle is a successful no-op for a valid instance. Wait to observe cleanup failures; do not retry accepted releases.

ovphysx_enqueue_result_t ovphysx_write(
ovphysx_instance_handle_t handle,
ovphysx_query_handle_t query,
const ovx_string_or_token_t *attributes,
size_t attribute_count,
ovphysx_write_handle_t *out_write,
ovphysx_write_result_t *out_summary,
)#

Open a write session for an array of named attributes.

The application-to-physics direction, the mirror of ovphysx_read. It reuses that query verbatim and adds no selection of its own: the session reaches exactly the set query matched, and there is no index, mask or prim-list parameter anywhere on this surface.

Each fetched group identifies its original request index through ovphysx_fetched_write_group_t::attribute_index, even when attributes have identical tensor shapes. Attributes are planned in request order. Commit order is chosen by the caller and no transactional rollback is provided. All names are validated before publishing a session. Canonical duplicates, including string/token aliases, and unsupported/read-only writes fail the creation task. A valid request with no matching objects is an empty session. Token ids take precedence over strings and must belong to the owning Stage dictionary; an unresolvable token fails rather than falling back to a string.

The write’s attribute vocabulary is its own: a name accepted here need not be one ovphysx_read emits, since write-only control inputs such as forces and wrenches have no read counterpart. Request attributes by semantic name; each fetched group’s request index identifies that name even when its storage is an instancer array.

ovphysx_enqueue_result_t ovphysx_fetch_write_next(
ovphysx_instance_handle_t handle,
ovphysx_write_handle_t write,
ovphysx_fetched_write_group_t *out_group,
)#

Fetch the next writable group from a write session.

After successful task completion, out_group->group points at the next ovstage_map_group_t, or is NULL at end of iteration. End of iteration is an ordinary successful task. A failed task leaves out_group->group NULL and must not be treated as end of iteration. Keep out_group alive until completion.

The group is producer-owned (the caller does not allocate it) and handed back as a const borrow. const is correct even on the write path: the group is a DESCRIPTOR the caller reads, describing BUFFERS the caller fills through data.tensors[i].data, which const permits since it does not propagate through pointer members. No field of the struct is the caller’s to assign, and tensor shape, dtype and device are dictated by the implementation.

Group storage stays valid until that group is committed or its write session is released, independent of further fetches. Detach and instance destruction retire write sessions. An intervening ovphysx_step does not invalidate a live group.

After acceptance, receipt.status is OVPHYSX_API_SUCCESS. Backend fetch failures are reported as OVPHYSX_API_ERROR by ovphysx_wait_task; end of iteration is successful completion with a NULL group.

Errors

Rejection (receipt.status, no task):

  • OVPHYSX_API_INVALID_ARGUMENT if handle is invalid or out_group is null.

  • OVPHYSX_API_NOT_FOUND if write is absent, released, or belongs to another instance.

  • OVPHYSX_API_ERROR if the write backend is unavailable or task creation fails.

Parameters:

  • handle – ovphysx instance handle.

  • write – Write-session handle from ovphysx_write.

  • out_group – [out] Receives the borrowed group and original request index. EOF is group == NULL and attribute_index == SIZE_MAX after successful task completion. Failed completion is never EOF.

Returns:

Admission receipt. After successful task completion, NULL means done.

Pre:

handle and write are valid and out_group is non-null.

ovphysx_enqueue_result_t ovphysx_commit_group(
ovphysx_instance_handle_t handle,
ovphysx_write_handle_t write,
const ovstage_map_group_t *group,
ovstage_cuda_sync_t write_done_sync,
)#

Commit a filled group, transferring ownership of its data to physics.

The caller must have filled EVERY mapped entry. There is no fill-mask, so a partially filled group publishes whatever its unfilled entries contain. To write fewer prims, query fewer. A live group belonging to this session is spent when accepted for publication, including when publication fails. Stop using its mapped pointers once the submission is accepted. A rejected submission leaves ownership with the caller. An invalid, foreign, or already-spent pointer fails the task without publishing or consuming another session’s group. Dereferencing them is undefined behavior rather than a checked error, since a raw data.tensors[i].data access makes no API call the runtime could reject.

ovphysx_enqueue_result_t ovphysx_release_write(
ovphysx_instance_handle_t handle,
ovphysx_write_handle_t write,
)#

Release a write session, discarding anything uncommitted.

Uncommitted groups are discarded. Finish all external CPU and CUDA work that fills those groups before submitting release: this call takes no producer completion token. Committed groups are not rolled back; the SDK waits for its own device work before reclaiming their storage. Once release is accepted, all session borrows end and cleanup belongs to the SDK, including after failure.

Parameters:

  • handle – ovphysx instance handle.

  • write – Write-session handle from ovphysx_write.

Returns:

Admission receipt. An absent handle is a successful no-op for a valid instance. Wait to observe cleanup failures; do not retry accepted releases.

ovphysx_result_t ovphysx_writability(
ovphysx_query_target_t object_type,
const ovx_string_or_token_t *attribute,
ovphysx_writability_t *out_writability,
)#

Ask whether an attribute can be written on an object type, and how.

The programmatic answer to a question that is otherwise only documented in prose, keyed on the SAME (object type, attribute) the write path takes (ovphysx_write resolves the object type through its query and names the attribute). This reports the API’s supported read/write vocabulary. Its scene-independent classification table is maintained separately and tested against runtime session admission.

Scene-independent: writability is a property of the write API, not of any live scene, so this needs no instance, query or step. A name the object type does not accept comes back OVPHYSX_WRITABILITY_UNCLASSIFIED, and ovphysx_write rejects it. Such a name is a gap to close, never an invitation to try the write anyway.

Errors

  • OVPHYSX_API_INVALID_ARGUMENT if out_writability or attribute is null, if attribute carries no string name (a token-only key), or if object_type is outside ovphysx_query_target_t (so an unknown type is distinguishable from a valid type that does not accept the name, which returns OVPHYSX_WRITABILITY_UNCLASSIFIED)

Parameters:

  • object_type – Object type the attribute would be written on (ovphysx_query’s selector), e.g. OVPHYSX_QUERY_TARGET_RIGID_BODY.

  • attribute – Attribute name (see the OVPHYSX_ATTR_* macros in ovphysx_attributes.h), as the string field of an ovx_string_or_token_t. STRING-ONLY: an interned-token-only key is rejected, because resolving a token needs a path dictionary this scene-free query does not have.

  • out_writability – [out] Receives the classification.

Returns:

ovphysx_result_t.

ovphysx_enqueue_result_t ovphysx_release_query(
ovphysx_instance_handle_t handle,
ovphysx_query_handle_t query,
)#

Release an output query.

Parameters:

  • handle – ovphysx instance handle.

  • query – Query handle from ovphysx_query.

Returns:

Admission receipt. An absent handle is a successful no-op for a valid instance. Wait to observe cleanup failures; do not retry accepted releases.

ovphysx_enqueue_result_t ovphysx_clone(
ovphysx_instance_handle_t handle,
ovphysx_string_t source_path_in_usd,
ovphysx_string_t *target_paths,
uint32_t num_target_paths,
const float *anchor_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 (the USD file is not 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).

#include <ovphysx/ovphysx.h>

static ovphysx_enqueue_result_t clone_two_environments(ovphysx_instance_handle_t handle)
{
    ovphysx_string_t targets[2] = {
        ovphysx_cstr("/World/env1"),
        ovphysx_cstr("/World/env2"),
    };
    return 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. The caller retains ownership.

Errors

  • OVPHYSX_API_INVALID_ARGUMENT for invalid or duplicate targets, or a call after 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 anchor_transforms) are isolated from the source too. Environment ids do not isolate clones in CPU mode: co-located CPU clones share one collision space, so use spatially disjoint anchor_transforms. The runtime emits a warning through the Carbonite log stream when env ids are requested but GPU dynamics or GPU broadphase is unavailable. Register ovphysx_set_log_callback() to receive it programmatically. 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. An accepted task is already terminal when this call returns. ovphysx_wait_task() immediately collects its outcome.

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

  • anchor_transforms – Absolute world pose of each target subtree root. Entry i anchors the exact subtree at target_paths[i]. 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)). Descendants keep their poses relative to the source subtree root (target_object_world = anchor_transforms[i] * inverse(source_root_world) * source_object_world). Pass NULL to co-locate every copy on the source. Co-location is collision-isolated only under GPU dynamics + GPU broadphase. Use spatially disjoint transforms in CPU mode.

  • 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:

Admission status and task identity. Rejection has zero identity; accepted execution failure is reported by a wait. On rejection, call ovphysx_get_last_error() on the same thread for the error message.

Pre:

handle must be valid.

Pre:

source_path_in_usd must exist and target_paths must be valid and unique.

Pre:

Must be called before ovphysx_warmup() or the first simulation step. Multiple ovphysx_clone() calls per attach are allowed in CPU and GPU mode while all of them precede warmup / first step. To clone after that point, use ovphysx_detach_ovstage() and reattach the source stage first. On GPU, cloning later would reallocate DirectGPU buffers and corrupt initialized state.

Post:

Cloned physics objects are live when the accepted task succeeds.

ovphysx_enqueue_result_t ovphysx_step(
ovphysx_instance_handle_t handle,
float step_dt,
)#

Enqueue an asynchronous physics simulation step.

The simulation time is tracked internally. Each step advances it by step_dt. The timestep is passed through without clamping or substepping. The caller is responsible for choosing a timestep appropriate for the simulation.

PhysX CUDA-context failures after admission are reported by the task wait, with a retained CUDA diagnostic even when logging is disabled.

Side Effects

Mutates physics state and may trigger internal events and callbacks.

Threading

Must not be called concurrently on the same instance without external synchronization.

Errors

  • OVPHYSX_API_INVALID_ARGUMENT for invalid inputs

  • OVPHYSX_API_ERROR for internal failures

#include <ovphysx/ovphysx.h>

static ovphysx_enqueue_result_t step_one_frame(ovphysx_instance_handle_t handle)
{
    return ovphysx_step(handle, 1.0f / 60.0f);
}
Parameters:

  • handle – ovphysx instance

  • step_dt – Finite, nonnegative simulation timestep in seconds

Returns:

ovphysx_enqueue_result_t with admission status and instance/task identity

Pre:

handle must be a valid instance handle.

Post:

Simulation advances by step_dt when the op completes.

ovphysx_result_t ovphysx_step_sync(
ovphysx_instance_handle_t handle,
float step_dt,
)#

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

This step does not create a task receipt. Earlier asynchronous work is completed first, without collecting its outcomes. Those receipts remain available to ovphysx_wait_task() or ovphysx_wait_all().

Use this whenever the caller steps and immediately waits for results, that is, does 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 – Finite, nonnegative timestep [s], passed through as in ovphysx_step().

Returns:

ovphysx_result_t with OVPHYSX_API_SUCCESS on success. A PhysX CUDA-context error returns OVPHYSX_API_ERROR; retrieve its diagnostic with ovphysx_get_last_error(), even when logging is disabled. A recoverable capacity-overflow report alone does not fail the call.

ovphysx_result_t ovphysx_warmup(ovphysx_instance_handle_t handle)#

Explicitly run the warmup step (optional, synchronous).

On first use, a real simulation step with a minimal timestep (~1ns) is run to initialize PhysX structures and disable per-step Fabric sync overhead. This is done automatically by legacy tensor-binding reads (auto-warmup). Session reads through ovphysx_read() do not auto-warm; call this explicitly to control when the latency occurs.

Works in both CPU and GPU mode. In GPU mode, this also populates DirectGPU buffers.

IMPORTANT: The warmup advances simulation state (positions may change infinitesimally). It is NOT a “dry run”. For deterministic initial conditions, call this before reading initial tensor state.

This function is idempotent. Calling it multiple times has no effect after the first successful call (per stage). Warmup state resets when the stage changes through detach and attach.

#include <ovphysx/ovphysx.h>

static ovphysx_result_t warm_up_instance(ovphysx_instance_handle_t handle)
{
    return ovphysx_warmup(handle);
}
Side Effects

Advances simulation by a minimal timestep on first call. Disables per-step Fabric sync (enabling direct TensorAPI mode).

Errors

  • OVPHYSX_API_ERROR for internal failures

Parameters:

handle – Instance handle

Returns:

ovphysx_result_t

Pre:

handle must be valid.

Post:

Warmup completed for the active stage.

ovphysx_enqueue_result_t ovphysx_update_articulations_kinematic(
ovphysx_instance_handle_t handle,
ovphysx_query_handle_t query,
uint32_t flags,
)#

Recompute articulation link transforms and/or velocities for the whole articulations selected by a physics-output query, without running a normal simulation step.

The query must select OVPHYSX_QUERY_TARGET_ARTICULATION. A query from ovphysx_query_selection updates only the articulations its selection names, through their root, a link or a joint; every other articulation is left unchanged.

The returned receipt reports admission. Wait for successful task completion before reading the updated link state. The update currently executes inline. It is useful after writing articulation DOF positions (through the session write API, ovphysx_write, or the deprecated tensor bindings) and before reading link pose tensors in the same frame.

NOTE: On the first GPU kinematic update after loading USD, an automatic warmup simulation step may be performed to initialize PhysX structures. See the tensor auto-warmup note in ovphysx_legacy.h.

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.

  • query – Live query owned by handle and selecting OVPHYSX_QUERY_TARGET_ARTICULATION. Membership is evaluated when the task executes.

  • flags – Bitwise OR of ovphysx_articulation_kinematic_flag_t. Zero is a successful no-op after validating the query. Non-DirectGPU scenes honor the component mask. DirectGPU’s native refresh may update both components for either supported nonzero mask.

Returns:

Admission receipt. Lazy attach, warmup, and backend failures are reported by waiting for the accepted task.

ovphysx_result_t ovphysx_subscribe_object_changes(
ovphysx_instance_handle_t handle,
const ovphysx_object_change_callbacks_t *callbacks,
ovphysx_subscription_id_t *out_subscription,
)#

Native PhysX addresses are the read-only physxPointer column (OVPHYSX_ATTR_PHYSX_POINTER).

Query the matching ovphysx_query_target_t and read that attribute. There is no dedicated pointer lookup. Subscribe to PhysX object create/destroy notifications.

Pair with a physxPointer read 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; it is unusable after that return. On a bulk teardown the caller MUST drop every cached pointer before returning from the all-objects callback. On a creation notification the caller should mark the prim path as dirty in its own cache and read physxPointer for the new address ONLY after the triggering synchronous call returns, or after ovphysx_wait_task() returns for async work, never from inside the callback itself (see Threading below).

Subscriptions are per-instance. Callbacks fire only while this handle’s own attachment is live. A peer instance does not receive this instance’s events, and cannot unsubscribe this instance’s subscription.

Lifecycle: callbacks fire for changes that occur during simulation and ovphysx_detach_ovstage()’s bulk teardown. The initial object population from ovstage attach/update is NOT notified, since the caller already has that state from setup. ovphysx_clone() does NOT fire object_created notifications. Pointer caches that need to track cloned objects must be refreshed after ovphysx_wait_task() returns on the clone operation. These notifications stay callbacks; they are not query or read records.

Threading: callbacks may fire from internal worker threads. Do NOT call other ovphysx APIs from inside a callback. Defer that until the triggering synchronous call returns, or until ovphysx_wait_task() 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:

  • handle – [in] Instance that owns the subscription.

  • callbacks – [in] Pointer to the callback set. The struct is copied internally, so 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_instance_handle_t handle,
ovphysx_subscription_id_t subscription,
)#

Unsubscribe from PhysX object change notifications.

Stops delivery of further notifications for the given subscription ID. OVPHYSX_API_SUCCESS does not return while one of this subscription’s callbacks is still running. After that return the subscription ID is consumed and must not be reused, and user_data will not be touched again by this subscription.

Calling this from inside any object-change callback returns OVPHYSX_API_INVALID_STATE and leaves the subscription active. That check follows the Carbonite task when the callback is running as one, and the native thread otherwise. Another task on the same worker is not inside the callback. The dispatch snapshot retains every subscriber until that callback returns, so waiting would deadlock. Unsubscribe again after it returns.

Idempotency: passing an already-unsubscribed or unknown subscription ID returns OVPHYSX_API_NOT_FOUND. A subscription owned by another instance also returns OVPHYSX_API_NOT_FOUND and leaves that subscription active. OVPHYSX_INVALID_SUBSCRIPTION_ID is rejected with OVPHYSX_API_INVALID_ARGUMENT. NOT_FOUND is not a drain barrier: only SUCCESS means in-flight callbacks for that subscription have finished.

Parameters:

  • handle – Instance that owns the subscription.

  • subscription – Subscription ID returned from ovphysx_subscribe_object_changes().

Returns:

OVPHYSX_API_SUCCESS on success, or an error status.

ovphysx_result_t ovphysx_wait_task(
ovphysx_instance_handle_t handle,
ovphysx_enqueue_result_t task,
ovphysx_timeout_t timeout_ns,
ovphysx_wait_task_result_t *out_wait_result,
)#

Collect the terminal outcome of one accepted task.

Reports and acknowledges only the given task, including when earlier work must finish to preserve execution ordering. Uncollected failures of other tasks remain available to their own wait or ovphysx_wait_all(). A terminal outcome is single-use; another wait returns NOT_FOUND. Timeout leaves the unfinished task retryable and returns its receipt in pending_task.

The timeout bounds readiness. Zero polls once; OVPHYSX_TIMEOUT_INFINITE waits indefinitely. Readiness observed at the deadline wins. Synchronous finalization can extend wall-clock duration beyond the readiness timeout.

#include <ovphysx/ovphysx.h>

static ovphysx_result_t collect_task(
    ovphysx_instance_handle_t handle, ovphysx_enqueue_result_t task)
{
    ovphysx_wait_task_result_t result = {0};
    ovphysx_result_t status = ovphysx_wait_task(
        handle, task, OVPHYSX_TIMEOUT_INFINITE, &result);
    ovphysx_destroy_wait_task_result(&result);
    return status;
}
Ownership

Failed receipts and borrowed messages belong to out_wait_result until ovphysx_destroy_wait_task_result(). Do not modify the returned fields, free error_tasks separately, or shallow-copy the result. Allocation failure leaves an empty destructible output and terminal outcomes uncollected, so callers can retry.

Threading

Calls on one instance must be externally serialized, including waits and error lookup. Serialized calls may move between threads.

Parameters:

  • handle – Owning instance. Validated before other arguments.

  • task – Copyable successful-admission receipt from a task producer.

  • timeout_ns – Readiness timeout in nanoseconds.

  • out_wait_result – [out] Non-null zero-initialized result. Nonempty reuse is rejected without overwriting it. Destroy after processing.

Returns:

SUCCESS for successful completion, ERROR for an execution or internal failure, TIMEOUT for unfinished work, INVALID_ARGUMENT for a zero/rejected/wrong-instance receipt or invalid output, NOT_FOUND for an invalid instance or a never-issued/already-collected task.

ovphysx_result_t ovphysx_wait_all(
ovphysx_instance_handle_t handle,
ovphysx_timeout_t timeout_ns,
ovphysx_wait_task_result_t *out_wait_result,
)#

Collect uncollected tasks accepted at call entry, in submission order.

Uses one readiness deadline for the entire call. Stops at the earliest unfinished task when that deadline expires; later outcomes stay uncollected. Earlier completed failures are returned in error_tasks even on TIMEOUT, which takes precedence over ERROR. Successful terminal outcomes are collected too. A discarded original receipt does not discard its failure. Empty and repeated wait-all calls succeed when no uncollected task remains.

Validation, ownership and timeout rules match ovphysx_wait_task(). An all-zero pending_task means no task remains pending within this call’s cutoff.

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 a stable empty string if the last call succeeded.

#include <ovphysx/ovphysx.h>
#include <stdio.h>

int main(void)
{
    ovphysx_result_t result = ovphysx_initialize();
    if (result.status != OVPHYSX_API_SUCCESS) {
        ovphysx_string_t error = ovphysx_get_last_error();
        if (error.length != 0)
            fprintf(stderr, "Error: %.*s\n", (int)error.length, error.ptr);
        return 1;
    }
    return ovphysx_shutdown().status == OVPHYSX_API_SUCCESS ? 0 : 1;
}
Threading

Thread-local storage. Safe to call from any thread.

Returns:

Error message, or {“”, 0} on success. ptr is always non-NULL and ptr[length] is ‘\0’.

ovphysx_string_t ovphysx_get_last_task_error(
ovphysx_instance_handle_t handle,
ovphysx_enqueue_result_t task,
)#

Borrow a collected task’s error from its live wait-result.

Lookup is read-only and never acknowledges work. A missing retained cause returns {“”, 0}. An invalid instance or zero/rejected/wrong-instance receipt also sets the immediate diagnostic retrieved by ovphysx_get_last_error(). The string survives unrelated waits and instance destruction until the owning wait-result is destroyed. A fresh lookup requires a live instance. ptr is always non-NULL and ptr[length] is ‘\0’.

void ovphysx_destroy_wait_task_result(
ovphysx_wait_task_result_t *result,
)#

Release wait-result storage and zero every field.

Accepts NULL and already-cleaned results. Safe after instance teardown; retained messages and receipts own no simulation or CUDA resources. A non-NULL result must be zero-initialized or produced by a task wait with its returned fields unchanged. Never free error_tasks separately.

ovphysx_result_t ovphysx_set_log_callback(
ovphysx_log_level_t min_severity,
const ovphysx_string_t *channel_filter,
ovphysx_log_callback_t callback,
void *user_data,
)#

Set or disable the application log callback.

One callback may be registered. Calling again publishes the replacement for newly accepted messages, then waits for the prior registration’s in-flight invocations before returning. Passing NULL for callback immediately stops accepting delivery and drains the prior registration. Once set, the callback pointer and resources reachable through user_data must remain valid until a later replacing or disabling call, or a successful ovphysx_shutdown(), returns. This includes shutdown with live handles retained only for explicit destruction. During replacement, accepted invocations of the old registration may overlap invocations of the newly published registration. Invocations within each registration remain serialized. min_severity applies to every record in the observed process log stream. Records from the library-owned omni_physx_sdk, omni.physx, and ovphysx_internal sources are also subject to the source threshold configured by OVPHYSX_GLOBAL_CONFIG_LOG_LEVEL. OVPHYSX_LOG_DEFAULT uses WARNING.

channel_filter is optional. It is a comma-separated list of channel=level rules. ASCII whitespace around entries, channels, and levels is ignored, and level names are case-insensitive. A rule matches any channel beginning with its raw prefix. Rules are considered in declaration order. The longest matching prefix wins, and a later rule wins ties between equal-length matching prefixes. An empty filter uses min_severity for every channel.

Note

The callback may be invoked from any thread, but invocations for the active registration are serialized.

Note

The callback observes Carbonite’s process log stream. The channel parameter identifies the emitting source for application filtering.

Note

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

Note

An OVPHYSX_API_ERROR after valid arguments may be reported after the replacement was published. Conservatively keep callback and user_data alive until a later successful replace, disable, or shutdown drains the slot.

Parameters:

  • min_severity – Minimum delivered severity.

  • channel_filter – Optional non-owning filter view, copied by the call.

  • callback – Callback function, or NULL to disable.

  • user_data – Opaque pointer forwarded to every callback invocation.

Returns:

ovphysx_result_t with status.

Post:

Invalid arguments leave the prior registration unchanged.

ovphysx_result_t ovphysx_flush_log(ovphysx_timeout_t timeout_ns)#

Wait for application-callback deliveries accepted before this call.

This is an exact barrier for records already handed to ovphysx by Carbonite. If the host enabled Carbonite asynchronous logging, records still buffered upstream have not yet been accepted and are outside this barrier. Successful ovphysx_shutdown() flushes that upstream buffer before disabling and draining the callback.

Parameters:

timeout_ns – Maximum wait in nanoseconds. OVPHYSX_TIMEOUT_POLL polls. OVPHYSX_TIMEOUT_INFINITE waits indefinitely.

Returns:

OVPHYSX_API_SUCCESS when drained, OVPHYSX_API_TIMEOUT on timeout, or OVPHYSX_API_ERROR when called from a log callback.

Geometry Queries#

Questions asked of the scene’s collision geometry at your own inputs. Declared in ovphysx_geometry_query.h; include it alongside ovphysx.h, which does not include it.

Use ovphysx_evaluate_sdf_shapes() to evaluate signed distance fields at your own points. Pass a live OVPHYSX_QUERY_TARGET_SDF_SHAPE query, a points tensor [N, Q, 3] and an output tensor [N, Q, 4] (gradient, then signed distance), float32 on the scene’s CUDA device, plus the producer handoff for the points, as for ovphysx_commit_group. The output is written when the task completes. The Python method is PhysX.evaluate_sdf_shapes(), which opens and releases the query itself and waits internally; the experimental C++ wrapper is PhysX::evaluateSdfShapes(). See SDF shapes for rows, frame and device requirements.

Functions

ovphysx_enqueue_result_t ovphysx_evaluate_sdf_shapes(
ovphysx_instance_handle_t handle,
ovphysx_query_handle_t query,
const DLTensor *points,
DLTensor *out,
ovstage_cuda_sync_t points_ready,
)#

Evaluate the signed distance fields of the SDF shapes a query selects.

The successor of the deprecated SDF view (ovphysx_create_sdf_view / ovphysx_evaluate_sdf), on the session query. Open the query with type OVPHYSX_QUERY_TARGET_SDF_SHAPE: its rows are the collision shapes the SDF view accepts &#8212; a prim carrying PhysicsCollisionAPI and PhysxSDFMeshCollisionAPI whose shape is a triangle mesh with an SDF, runtime clones included. A query from ovphysx_query_selection orders its rows as its selection: explicit prim handles in the order given, a pattern in the same matcher order the SDF view used; a whole-set query orders them as the runtime stores them. A selected prim that is not an SDF shape is skipped, with a warning, as the SDF view skipped it.

For each row i and point j, out[i][j] receives the gradient (x, y, z) and then the signed distance at points[i][j], negative inside. Points and gradients are in the shape’s mesh-local space &#8212; the unscaled frame of the mesh’s vertices &#8212; and no transform is applied. Q, the points per shape, is read from the tensors on every call. A point outside the shape’s SDF grid (the mesh bounds padded by the SDF margin) is evaluated, not refused, as by the SDF view: its distance is the SDF value at the nearest grid point plus the distance to the grid, a positive upper bound, and its gradient points away from the shape.

Evaluation needs a DirectGPU scene, all the rows in one scene, at most 65535 rows &#8212; PhysX launches its SDF evaluation with one CUDA grid row per shape &#8212; and at most 2^31 - 1 points in all (N x Q), which PhysX indexes in 32-bit arithmetic. It also needs the scene to have simulated since its physics objects were last created or released, because PhysX uploads shape data to the GPU only when it simulates. On the first evaluation after loading USD, an automatic warmup simulation step may be performed, as for the SDF view; after that the call never steps, so step once after such a change before evaluating. out is complete once the task has completed.

Legacy C API#

Deprecated families. ovphysx.h includes this header so existing includes keep compiling.

Functions

ovphysx_result_t ovphysx_create_instance_with_args(
const ovphysx_create_args *create_args,
ovphysx_instance_handle_t *out_handle,
)#

Deprecated:

active_cuda_gpus uses ovphysx_create_instance() then ovphysx_set_config(). Other scoped keys use ovphysx_set_global_config() before create, including OVPHYSX_GLOBAL_CONFIG_OVD_RECORDING_CAPABLE. Carbonite tasking/TBB pool sizes stay on this create-args path. Retired OVD configuration entries return OVPHYSX_API_INVALID_ARGUMENT.

ovphysx_result_t ovphysx_set_global_config_entry(
ovphysx_config_entry_t entry,
)#

Deprecated:

Keys that have a scoped replacement use ovphysx_set_global_config(). OVD recording capability uses OVPHYSX_GLOBAL_CONFIG_OVD_RECORDING_CAPABLE. Carbonite tasking/TBB pool sizes stay on this entry. Retired OVD configuration entries return OVPHYSX_API_INVALID_ARGUMENT.

ovphysx_result_t ovphysx_get_global_config_bool(
ovphysx_config_bool_t key,
bool *out_value,
)#

Deprecated:

Use ovphysx_get_global_config(). Retired OVD slots return OVPHYSX_API_INVALID_ARGUMENT with migration guidance.

ovphysx_result_t ovphysx_get_global_config_int32(
ovphysx_config_int32_t key,
int32_t *out_value,
)#

Deprecated:

Use ovphysx_get_global_config(). Retired OVD slots return OVPHYSX_API_INVALID_ARGUMENT with migration guidance.

ovphysx_result_t ovphysx_get_global_config_float(
ovphysx_config_float_t key,
float *out_value,
)#

Deprecated:

Use ovphysx_get_global_config().

ovphysx_result_t ovphysx_get_global_config_string(
ovphysx_config_string_t key,
ovphysx_string_t *value_out,
size_t *out_required_size,
)#

Deprecated:

Use ovphysx_get_global_config(). Retired OVD slots return OVPHYSX_API_INVALID_ARGUMENT with migration guidance.

ovphysx_result_t ovphysx_set_cpu_mode(bool cpu_only)#

Deprecated:

Use OVPHYSX_GLOBAL_CONFIG_CPU_ONLY with ovphysx_set_global_config().

ovphysx_result_t ovphysx_get_cpu_mode(bool *out_cpu_only)#

Deprecated:

Use OVPHYSX_GLOBAL_CONFIG_CPU_ONLY with ovphysx_get_global_config().

ovphysx_result_t ovphysx_set_log_level(uint32_t level)#

Deprecated:

Use OVPHYSX_GLOBAL_CONFIG_LOG_LEVEL with ovphysx_set_global_config().

uint32_t ovphysx_get_log_level(void)#

Deprecated:

Use OVPHYSX_GLOBAL_CONFIG_LOG_LEVEL with ovphysx_get_global_config().

ovphysx_result_t ovphysx_enable_default_log_output(bool enable)#

Deprecated:

Use OVPHYSX_GLOBAL_CONFIG_DEFAULT_LOG_OUTPUT with ovphysx_set_global_config().

ovphysx_result_t ovphysx_create_tensor_binding(
ovphysx_instance_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 physics-object path 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 objects. Runtime-only clone paths are eligible even when no USD prim is authored at the path. Each call returns an independent handle. Destroying one binding does not invalidate another binding for the same objects. A new binding selects the currently eligible realized objects even while older bindings remain alive.

If the pattern matches zero physics objects, 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 physics objects 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_detach_ovstage(), 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() and ovphysx_step_sync() do not invalidate bindings.

#include <ovphysx/ovphysx_legacy.h>

static ovphysx_result_t create_pose_binding(
    ovphysx_instance_handle_t handle,
    ovphysx_tensor_binding_handle_t* out_binding)
{
    ovphysx_tensor_binding_desc_t desc = {
        .pattern = OVPHYSX_LITERAL("/World/robot*"),
        .tensor_type = OVPHYSX_TENSOR_RIGID_BODY_POSE_F32,
    };
    return ovphysx_create_tensor_binding(handle, &desc, out_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

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_read (reads) and ovphysx_write (writes) instead.

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 retains native resources until explicitly destroyed via ovphysx_destroy_tensor_binding(), or until the parent instance is destroyed. Stage detach 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_instance_handle_t handle,
ovphysx_tensor_binding_handle_t binding_handle,
)#

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

#include <ovphysx/ovphysx_legacy.h>

static ovphysx_result_t destroy_binding(
    ovphysx_instance_handle_t handle,
    ovphysx_tensor_binding_handle_t binding)
{
    return 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

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_read (reads) and ovphysx_write (writes) instead.

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_instance_handle_t handle,
ovphysx_tensor_binding_handle_t binding_handle,
ovphysx_tensor_spec_t *out_spec,
)#

Get the tensor layout specification for a binding.

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.

#include <ovphysx/ovphysx_legacy.h>

static ovphysx_result_t query_binding_spec(
    ovphysx_instance_handle_t handle,
    ovphysx_tensor_binding_handle_t binding,
    ovphysx_tensor_spec_t* out_spec)
{
    return ovphysx_get_tensor_binding_spec(handle, binding, out_spec);
}
Side Effects

None.

Errors

  • OVPHYSX_API_NOT_FOUND if binding handle is unknown

  • OVPHYSX_API_ERROR for internal failures

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_read (reads) and ovphysx_write (writes) instead.

Note

The returned specification does not include memory residency. Call ovphysx_get_tensor_binding_native_device() to query the binding’s native device.

Parameters:

  • handle – Instance handle

  • binding_handle – Tensor binding

  • out_spec – [out] Tensor dtype, rank, and shape

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_get_tensor_binding_native_device(
ovphysx_instance_handle_t handle,
ovphysx_tensor_binding_handle_t binding_handle,
DLDevice *out_device,
)#

Get the native device used by a tensor binding.

Returns the device used by the binding’s native TensorAPI read/write path: DLDevice{kDLCPU, 0} for host-resident bindings, or DLDevice{kDLCUDA, device_ordinal} for CUDA-resident bindings. CPU-only property tensors report CPU even when the simulation runs on CUDA. For kDLCUDA, device_id is the process-visible CUDA runtime ordinal used with cudaSetDevice() or a framework device such as cuda:N, not a physical PCI bus index.

This reports native residency, not every device accepted by read/write. Using the native device avoids staging when another accepted placement would require it. The value remains stable for the lifetime of a live binding. Unlike the layout-only spec getter, this is a live mapping query and rejects an invalidated simulation view.

#include <ovphysx/ovphysx_legacy.h>

static ovphysx_result_t query_binding_device(
    ovphysx_instance_handle_t handle,
    ovphysx_tensor_binding_handle_t binding,
    DLDevice* out_device)
{
    return ovphysx_get_tensor_binding_native_device(handle, binding, out_device);
}
Side Effects

None.

Synchronization

Waits for pending operations on the instance before inspecting the binding.

Errors

  • OVPHYSX_API_INVALID_ARGUMENT if out_device is NULL

  • OVPHYSX_API_NOT_FOUND if binding_handle is unknown or stale

  • OVPHYSX_API_ERROR if handle is invalid

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_read / ovphysx_write instead.

Parameters:

  • handle – Instance handle

  • binding_handle – Tensor binding

  • out_device – [out] Native DLPack device for the binding

Returns:

ovphysx_result_t

Pre:

handle, binding_handle, and out_device must be valid.

Post:

out_device is populated with the binding’s native device.

ovphysx_result_t ovphysx_read_tensor_binding(
ovphysx_instance_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.

Tensor auto-warmup note

The first tensor read or write after loading USD may perform an automatic warmup simulation step to initialize PhysX lazy structures. In GPU mode this also initializes DirectGPU buffers.

For deterministic behavior, explicitly control warmup timing by loading USD, waiting for completion, then calling ovphysx_warmup() before the first tensor read or write. To have the first observed state change happen under a chosen timestep instead, call ovphysx_step() explicitly with that dt.

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

NOTE: On the first tensor read after loading USD, an automatic warmup simulation step may be performed. See 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()

  • when CUDA is available, CPU/CUDA mismatches are staged for binding types whose storage follows the simulation device

  • CPU-only property bindings require a host-resident kDLCPU or kDLCUDAHost destination. kDLCUDA and kDLCUDAManaged destinations return OVPHYSX_API_DEVICE_MISMATCH and are not staged

  • 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.

#include <ovphysx/ovphysx_legacy.h>

static ovphysx_result_t read_binding(
    ovphysx_instance_handle_t handle,
    ovphysx_tensor_binding_handle_t binding,
    DLTensor* destination)
{
    return ovphysx_read_tensor_binding(handle, binding, destination);
}
Side Effects

May trigger warmup on first read.

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

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_read instead.

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_write_tensor_binding(
ovphysx_instance_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, so 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).

  • Inverse 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.

NOTE: On the first tensor write after loading USD, an automatic warmup simulation step may be performed to initialize PhysX structures. See tensor auto-warmup note.

This is a blocking call that completes before returning.

#include <ovphysx/ovphysx_legacy.h>

static ovphysx_result_t write_binding(
    ovphysx_instance_handle_t handle,
    ovphysx_tensor_binding_handle_t binding,
    const DLTensor* source)
{
    return ovphysx_write_tensor_binding(handle, binding, source, 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

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_write instead.

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. When CUDA is available, CPU/CUDA mismatches are staged for binding types whose storage follows the simulation device.

Pre:

For CPU-only property bindings, src_tensor and any index_tensor must use kDLCPU or kDLCUDAHost. Otherwise-valid kDLCUDA and kDLCUDAManaged tensors return OVPHYSX_API_DEVICE_MISMATCH and are not staged.

Pre:

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_instance_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.

NOTE: On the first tensor write after loading USD, an automatic warmup simulation step may be performed to initialize PhysX structures. See tensor auto-warmup note.

This is a blocking call that completes before returning.

#include <ovphysx/ovphysx_legacy.h>

static ovphysx_result_t write_masked_binding(
    ovphysx_instance_handle_t handle,
    ovphysx_tensor_binding_handle_t binding,
    const DLTensor* source,
    const DLTensor* mask)
{
    return ovphysx_write_tensor_binding_masked(
        handle, binding, source, 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

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_write instead.

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. When CUDA is available, CPU/CUDA mismatches are staged for binding types whose storage follows the simulation device.

Pre:

For CPU-only property bindings, src_tensor and mask_tensor must use kDLCPU or kDLCUDAHost. Otherwise-valid kDLCUDA and kDLCUDAManaged tensors return OVPHYSX_API_DEVICE_MISMATCH and are not staged.

Pre:

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_instance_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, so the result can be cached.

Homogeneous topology requirement: all articulations covered by this binding must have identical topology &#8212; not merely matching counts. Two articulations share a topology only when they agree on base type (fixed vs floating), dof_count, body_count, joint_count, joint types AND joint names, DOF parentage, and link leaf names. In particular, two otherwise-identical articulations whose joints differ only in name (including a difference only in length) are distinct topologies and will not bind together. This is a constraint of the native tensor backend, whose tensor shapes are fixed at binding creation time. Articulations of different topology (e.g. a 7-DOF arm and a 30-DOF humanoid, or two arms whose joints are named differently) need a separate binding each. A binding spanning heterogeneous articulations returns a non-SUCCESS status here with all-zero counts &#8212; the same signal as an empty binding &#8212; while ovphysx_get_tensor_binding_spec still reports the correct shape.

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

#include <ovphysx/ovphysx_legacy.h>
#include <stdio.h>

static ovphysx_result_t print_articulation_size(
    ovphysx_instance_handle_t handle,
    ovphysx_tensor_binding_handle_t binding)
{
    ovphysx_articulation_metadata_t metadata = {0};
    ovphysx_result_t result =
        ovphysx_get_articulation_metadata(handle, binding, &metadata);
    if (result.status == OVPHYSX_API_SUCCESS)
        printf("DOFs: %d  Links: %d\n",
               metadata.dof_count, metadata.body_count);
    return result;
}

Deprecated:

Part of the tensor-binding surface. It requires a binding handle and is removed with the binding. Its successor is the non-binding read API: read the six whole-articulation topology attributes in ovphysx_attributes.h (OVPHYSX_ATTR_DOF_COUNT, OVPHYSX_ATTR_LINK_COUNT, OVPHYSX_ATTR_JOINT_COUNT, OVPHYSX_ATTR_FIXED_TENDON_COUNT, OVPHYSX_ATTR_SPATIAL_TENDON_COUNT, OVPHYSX_ATTR_IS_FIXED_BASE) via ovphysx_read() on OVPHYSX_QUERY_TARGET_ARTICULATION, which cover this struct field-for-field. The DOF/body/joint name getters below now also have non-binding successors &#8212; see each one’s note.

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_instance_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.

Deprecated:

Binding-coupled (requires a tensor-binding handle) and removed with the tensor binding. Per-DOF identity is now served without a binding by the OVPHYSX_ATTR_DOF_JOINT_PATH macro in ovphysx_attributes.h and OVPHYSX_ATTR_DOF_AXIS_INDEX read attributes on ovphysx_read (one entry per DOF, in inverse-dynamics matrix column order): a DOF is identified by (owning joint prim, axis index) rather than a string, so an inverse-dynamics matrix column is joinable back to its joint.

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_instance_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.

Deprecated:

Binding-coupled (requires a tensor-binding handle) and removed with the tensor binding. Link names are now served without a binding as the leaf name of each OVPHYSX_QUERY_TARGET_ARTICULATION_LINK prim read by ovphysx_read &#8212; resolve the prim path through the query’s path dictionary and take its leaf.

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_instance_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.

Deprecated:

Binding-coupled (requires a tensor-binding handle) and removed with the tensor binding. For DOF-bearing joints, names are now served without a binding as the leaf name of each OVPHYSX_QUERY_TARGET_ARTICULATION_JOINT prim read by ovphysx_read &#8212; resolve the prim path through the query’s path dictionary and take its leaf. The OVPHYSX_ATTR_DOF_JOINT_PATH descriptor in ovphysx_attributes.h names the same joint prim per DOF column. A fully-locked (zero-DOF) joint has no read group, so its path is not among them; the deprecated getter listed those fixed joints too.

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_instance_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 physics-object 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 object paths in the binding’s first-dimension row order. ovphysx owns the returned string storage. String pointers remain valid until the binding is destroyed.

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_read (reads) and ovphysx_write (writes) instead.

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 the 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_instance_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 reading net contact forces and force matrices. 

#include <ovphysx/ovphysx_legacy.h>

static ovphysx_result_t create_filtered_contact_binding(
    ovphysx_instance_handle_t handle,
    ovphysx_contact_binding_handle_t* out_binding)
{
    ovphysx_string_t sensors[] = {
        ovphysx_cstr("/World/robot_0/ee"),
    };
    ovphysx_string_t filters[] = {
        ovphysx_cstr("/World/obstacles/box"),
    };
    return ovphysx_create_contact_binding(
        handle, sensors, 1, filters, 1, 256, out_binding);
}

Parameters:

  • handle – Instance handle

  • sensor_patterns – Array of physics-object path patterns matching sensor bodies. A single path component longer than 4096 characters (here or in filter_patterns) is rejected with OVPHYSX_API_INVALID_ARGUMENT.

  • sensor_patterns_count – Number of sensor patterns

  • filter_patterns – Flat array of filter object-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 – Max detailed contact/friction entries to track. Set this to a positive value before using ovphysx_read_normal_contact_data() or ovphysx_read_friction_contact_data(). 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_instance_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_instance_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_instance_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 physics-object 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.

Callers must index min(*out_count, max_paths). A short out_paths still receives a valid prefix.

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

  • out_count – [out] Total sensor-path demand, even when that exceeds max_paths

Returns:

OVPHYSX_API_SUCCESS when every sensor path was written, or OVPHYSX_API_BUFFER_TOO_SMALL when demand exceeds max_paths

ovphysx_result_t ovphysx_contact_binding_get_filter_paths(
ovphysx_instance_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 physics-object 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.

Callers must index min(*out_count, max_paths). A short out_paths still receives a valid prefix.

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

  • out_count – [out] Total filter-path demand (sensor_count * filter_count), even when that exceeds max_paths

Returns:

OVPHYSX_API_SUCCESS when every filter path was written, or OVPHYSX_API_BUFFER_TOO_SMALL when demand exceeds max_paths

ovphysx_result_t ovphysx_get_contact_binding_capacity(
ovphysx_instance_handle_t handle,
ovphysx_contact_binding_handle_t contact_handle,
uint32_t *out_max_contact_data_count,
)#

Query detailed contact/friction flat-buffer capacity.

This is the C dimension for ovphysx_read_normal_contact_data() and ovphysx_read_friction_contact_data() flat buffers. Allocate force/separation buffers as [C, 1], point/normal/friction buffers as [C, 3], and count/start-index buffers as [S, F], where C is this value and S, F come from ovphysx_get_contact_binding_spec().

Parameters:

  • handle – Instance handle

  • contact_handle – Contact binding

  • out_max_contact_data_count – [out] Max detailed contact/friction entries

Returns:

ovphysx_result_t

ovphysx_result_t ovphysx_read_contact_net_normal_forces(
ovphysx_instance_handle_t handle,
ovphysx_contact_binding_handle_t contact_handle,
DLTensor *dst_tensor,
)#

Read net normal contact forces.

dst shape: [S, 3].

Returns world-space normal forces over all reported contacts of each sensor, regardless of filters or detailed-contact capacity. Adding the result of ovphysx_read_contact_net_friction_forces() from the same simulation step yields total contact forces.

Impulse-to-force conversion uses dt from the last successful ovphysx_step() or ovphysx_step_sync() call that simulated; a zero-dt step is skipped and leaves both the contacts and the dt of the preceding positive-dt step in place. This function waits for pending SDK work before retrieving the contact forces.

ovphysx_result_t ovphysx_read_contact_net_friction_forces(
ovphysx_instance_handle_t handle,
ovphysx_contact_binding_handle_t contact_handle,
DLTensor *dst_tensor,
)#

Read net friction forces.

dst shape: [S, 3].

Sums world-space friction-anchor forces over all reported contacts of each sensor, including contacts with bodies not matched by the binding’s filter patterns. Neither filters nor detailed-contact capacity are required. Opposing anchor forces can cancel while producing torque. This vector sum does not report friction torque.

Impulse-to-force conversion uses dt from the last successful ovphysx_step() or ovphysx_step_sync() call that simulated; a zero-dt step is skipped and leaves both the contacts and the dt of the preceding positive-dt step in place. This function waits for pending SDK work before retrieving the contact forces.

ovphysx_result_t ovphysx_read_contact_normal_force_matrix(
ovphysx_instance_handle_t handle,
ovphysx_contact_binding_handle_t contact_handle,
DLTensor *dst_tensor,
)#

Read normal contact force matrix.

dst shape: [S, F, 3].

Each entry sums world-space normal forces for its sensor/filter pair, independently of detailed-contact capacity. Adding the result of ovphysx_read_contact_friction_force_matrix() from the same step yields total contact forces for the configured pairs.

Impulse-to-force conversion uses dt from the last successful ovphysx_step() or ovphysx_step_sync() call that simulated; a zero-dt step is skipped and leaves both the contacts and the dt of the preceding positive-dt step in place. This function waits for pending SDK work before retrieving the contact forces.

ovphysx_result_t ovphysx_read_contact_friction_force_matrix(
ovphysx_instance_handle_t handle,
ovphysx_contact_binding_handle_t contact_handle,
DLTensor *dst_tensor,
)#

Read friction force matrix.

dst shape: [S, F, 3].

Each entry sums world-space friction forces for its sensor/filter pair, independently of detailed-contact capacity. Only contacts with configured filter bodies contribute. Adding the normal force matrix from the same step yields total contact forces for those pairs. Individual friction forces and anchor points are available through ovphysx_read_friction_contact_data().

Impulse-to-force conversion uses dt from the last successful ovphysx_step() or ovphysx_step_sync() call that simulated; a zero-dt step is skipped and leaves both the contacts and the dt of the preceding positive-dt step in place. This function waits for pending SDK work before retrieving the contact forces.

ovphysx_result_t ovphysx_read_contact_net_forces(
ovphysx_instance_handle_t handle,
ovphysx_contact_binding_handle_t contact_handle,
DLTensor *dst_tensor,
)#

Deprecated:

Use ovphysx_read_contact_net_normal_forces(). Still returns normal forces only.

ovphysx_result_t ovphysx_read_contact_force_matrix(
ovphysx_instance_handle_t handle,
ovphysx_contact_binding_handle_t contact_handle,
DLTensor *dst_tensor,
)#

Deprecated:

Use ovphysx_read_contact_normal_force_matrix(). Still returns normal forces only.

ovphysx_result_t ovphysx_read_normal_contact_data(
ovphysx_instance_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,
uint32_t *out_required_contact_count,
)#

Read detailed normal contact data into flat buffers.

contact_force_tensor contains scalar normal forces. Multiply each scalar by the corresponding contact_normal_tensor vector to obtain the world-space normal force vector. Friction forces are returned separately by ovphysx_read_friction_contact_data().

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. Contact force magnitudes use the timestep from the last successful ovphysx_step() or ovphysx_step_sync() call that simulated; a zero-dt step is skipped and leaves the preceding step’s contacts and timestep in place.

Truncation: out_required_contact_count receives the total number of contacts produced for the step, before truncation. When that value exceeds max_contact_data_count, the function returns OVPHYSX_API_BUFFER_TOO_SMALL while still filling the flat buffers with as many contacts as fit. A pair’s count reports only contacts actually written, and its start index is clamped to max_contact_data_count, so [start, start + count) is always an in-range (possibly empty) slice. Recreate the binding with max_contact_data_count at least out_required_contact_count, step again, and retry to obtain a complete result.

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

  • out_required_contact_count – [out] Total contacts produced for the step before truncation; the capacity required for a complete read.

Returns:

OVPHYSX_API_SUCCESS when the complete result fits, OVPHYSX_API_BUFFER_TOO_SMALL when only a valid prefix was written, or another error status on failure.

ovphysx_result_t ovphysx_read_contact_data(
ovphysx_instance_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,
uint32_t *out_required_contact_count,
)#

Deprecated:

Use ovphysx_read_normal_contact_data(). Forces remain normal components only.

ovphysx_result_t ovphysx_read_friction_contact_data(
ovphysx_instance_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,
uint32_t *out_required_friction_count,
)#

Read detailed friction contact data into flat buffers.

Returns world-space friction force vectors at friction anchors. These anchors need not correspond one-to-one with the contact points from ovphysx_read_normal_contact_data(); use this read’s own counts and start indices.

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_normal_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. Friction forces use the timestep from the last successful ovphysx_step() or ovphysx_step_sync() call that simulated; a zero-dt step is skipped and leaves the preceding step’s contacts and timestep in place.

Truncation: out_required_friction_count receives the total number of friction anchors produced for the step, before truncation. When that value exceeds max_contact_data_count, the function returns OVPHYSX_API_BUFFER_TOO_SMALL while still filling the flat buffers with as many anchors as fit. A pair’s count reports only anchors actually written, and its start index is clamped to max_contact_data_count, so [start, start + count) is always an in-range (possibly empty) slice. Recreate the binding with max_contact_data_count at least out_required_friction_count, step again, and retry to obtain a complete result.

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

  • out_required_friction_count – [out] Total friction anchors produced for the step before truncation; the capacity required for a complete read.

Returns:

OVPHYSX_API_SUCCESS when the complete result fits, OVPHYSX_API_BUFFER_TOO_SMALL when only a valid prefix was written, or another error status on failure.

ovphysx_result_t ovphysx_read_friction_data(
ovphysx_instance_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,
uint32_t *out_required_friction_count,
)#

Deprecated:

Use ovphysx_read_friction_contact_data().

ovphysx_result_t ovphysx_read_raw_contact_data(
ovphysx_instance_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 *sensor_layout_tensor,
DLTensor *actor_ids_tensor,
uint32_t *out_required_contact_count,
)#

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

Filter-less variant of ovphysx_read_normal_contact_data : returns every contact involving each sensor body regardless of which other actor it collided with, plus per-contact actor-identity tensors so callers can identify both the sensor and 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

  • sensor_layout_tensor: [S, 2] int32/uint32, per sensor, column 0 is the contact count and column 1 is its start index into the flat buffers

  • actor_ids_tensor: [C, 2] int64/uint64, per contact, column 0 is the reporting sensor’s own actor id and column 1 is the actor it contacted

The two pairs that are only meaningful together are single tensors rather than separate buffers the caller has to keep in step. The four per-contact value tensors stay separate, matching ovphysx_read_normal_contact_data().

The contact binding must be created with max_contact_data_count > 0. No filter dimension is required, so filters_per_sensor may be zero. The dt for impulse-to-force conversion is taken automatically from the last successful ovphysx_step() or ovphysx_step_sync() call that simulated; a zero-dt step is skipped and leaves the preceding step’s contacts and timestep in place.

Truncation: out_required_contact_count receives the total number of contacts produced for the step, before truncation. When that value exceeds max_contact_data_count, the function returns OVPHYSX_API_BUFFER_TOO_SMALL while still filling the flat buffers with as many contacts as fit. A sensor’s count reports only contacts actually written, and its start index is clamped to max_contact_data_count, so [start, start + count) is always an in-range (possibly empty) slice. Recreate the binding with max_contact_data_count at least out_required_contact_count, step again, and retry to obtain a complete result.

Token lifetime: the uint64 tokens in actor_ids_tensor are opaque runtime actor handles, not encoded paths. Do not decode one. Resolve it with ovphysx_contact_binding_get_other_actor_paths_from_ids. They are stable for as long as the corresponding actor is alive on the attached stage, and become stale once it is removed or the stage is detached or replaced.

Parameters:

  • handle – Instance handle

  • contact_handle – Contact binding

  • out_required_contact_count – [out] Total contacts produced for the step before truncation; the capacity required for a complete read.

Returns:

OVPHYSX_API_SUCCESS when the complete result fits, OVPHYSX_API_BUFFER_TOO_SMALL when only a valid prefix was written, or another error status on failure.

ovphysx_result_t ovphysx_contact_binding_get_other_actor_paths_from_ids(
ovphysx_instance_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 physics-object paths.

Given a tensor of opaque actor IDs (a column of the actor_ids_tensor [C, 2] returned by ovphysx_read_raw_contact_data, either column, since both use the same namespace), fills out_paths with the corresponding physics-object paths in the same order. An ID of 0 yields an empty path, as does an ID that is not known to the attached stage at all.

ids_tensor must be CPU-resident (path resolution is a host operation) and C-contiguous: a column of actor_ids_tensor is a strided view, so make the slice contiguous (e.g. np.ascontiguousarray(actor_ids[:, 1])) before passing it. This is the diagnostic path. The per-contact read itself takes the whole contiguous tensor and pays no copy.

Stale IDs report as empty, not as their old path. Every non-zero ID is checked against the attached stage before it is resolved, so an actor that has since been removed comes back as an empty path rather than the path it used to name. Because the caller holds the IDs, this makes the failure explicit: for a non-zero ID an empty path means “not resolvable now”, and only ID 0 yields an empty path for a live read.

Truncation: out_count receives the length of ids_tensor. When that exceeds max_paths, the function returns OVPHYSX_API_BUFFER_TOO_SMALL while writing a valid prefix of min(*out_count, max_paths) strings.

The check is as precise as the attached backend’s notion of existence. On an ovstage attach a removed prim reports stale. On a USD stage a merely deactivated prim still resolves, because existence there follows prim validity and USD hands back a valid prim for an inactive one.

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] Length of ids_tensor (total demand). Only min(*out_count, max_paths) entries are written to out_paths.

Returns:

OVPHYSX_API_SUCCESS when the complete result fits, OVPHYSX_API_BUFFER_TOO_SMALL when only a valid prefix was written, or another error status on failure.

ovphysx_result_t ovphysx_get_object_type(
ovphysx_instance_handle_t handle,
ovphysx_string_t prim_path,
ovphysx_object_type_t *out_type,
)#

Classify an authored USD prim by its high-level TensorAPI object type.

Returns the umbrella’s view of what kind of simulation object lives at prim_path. See ovphysx_object_type_t for the taxonomy, which distinguishes standalone (OVPHYSX_OBJECT_TYPE_JOINT), custom (OVPHYSX_OBJECT_TYPE_CUSTOM_JOINT), and articulation (OVPHYSX_OBJECT_TYPE_ARTICULATION_JOINT) joints.

Native addresses for those kinds are the physxPointer column: OVPHYSX_QUERY_TARGET_JOINT, OVPHYSX_QUERY_TARGET_CUSTOM_JOINT, and OVPHYSX_QUERY_TARGET_ARTICULATION_JOINT. Object-change callbacks still report ovphysx_physx_type_t.

Paths with no classified simulation object yield OVPHYSX_OBJECT_TYPE_INVALID with OVPHYSX_API_SUCCESS (the call itself did not fail, for example because the prim is absent or has no matching TensorAPI object type). Live standalone, custom, and articulation joints at their authored prim paths must not report INVALID.

Parameters:

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

  • prim_path – Authored USD prim path (embedded NUL bytes are rejected)

  • out_type – [out] Receives the object type

Returns:

OVPHYSX_API_SUCCESS on success (including the INVALID classification above), OVPHYSX_API_INVALID_ARGUMENT if out_type is NULL or prim_path is NULL, empty, or contains an embedded NUL byte, or OVPHYSX_API_ERROR if no stage is attached or the TensorAPI simulation view cannot be created.

ovphysx_result_t ovphysx_rigid_body_view_wake_up(
ovphysx_instance_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 the actor’s eDISABLE_SIMULATION flag through the ovstage disableSimulation write (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.

Deprecated:

Binding-coupled (requires a tensor-binding handle) and removed with the tensor binding. Successor: the wake write attribute on ovphysx_write &#8212; a per-prim rigid-body sleep control (nonzero wakes, zero sleeps), supported on CPU scenes and GPU scenes with CPU readback, refused on DirectGPU. A prim-set-selected query narrows the command to those bodies.

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_instance_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.

Deprecated:

Binding-coupled (requires a tensor-binding handle) and removed with the tensor binding. Successor: the wake write attribute on ovphysx_write &#8212; a per-prim rigid-body sleep control (nonzero wakes, zero sleeps), supported on CPU scenes and GPU scenes with CPU readback, refused on DirectGPU. A prim-set-selected query narrows the command to those bodies.

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_raycast(
ovphysx_instance_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. 

#include <ovphysx/ovphysx_legacy.h>
#include <stdio.h>

static ovphysx_result_t print_closest_hit(ovphysx_instance_handle_t handle)
{
    const ovphysx_scene_query_hit_t* hits = NULL;
    uint32_t count = 0;
    const float origin[3] = {0.0f, 10.0f, 0.0f};
    const float direction[3] = {0.0f, -1.0f, 0.0f};
    ovphysx_result_t result = ovphysx_raycast(
        handle, origin, direction, 100.0f, false,
        OVPHYSX_SCENE_QUERY_MODE_CLOSEST, &hits, &count);
    if (result.status == OVPHYSX_API_SUCCESS && count > 0)
        printf("Hit at distance %f\n", hits[0].distance);
    return result;
}

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_instance_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_instance_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. 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_result_t ovphysx_scene_query_get_paths_from_ids(
ovphysx_instance_handle_t handle,
const uint64_t *ids,
uint32_t id_count,
ovphysx_string_t *out_paths,
uint32_t max_paths,
uint32_t *out_count,
)#

Resolve object-identity handles to physics-object paths.

Given an array of opaque object-identity handles produced by this API, fills out_paths with the corresponding physics-object paths in the same order. Despite the scene_query name the resolution is generic: any identity field carries the same opaque handle, so scene-query hits (collision, rigid_body, material of an ovphysx_scene_query_hit_t from ovphysx_raycast, ovphysx_sweep or ovphysx_overlap) are accepted. Contact-sensor read identities are prim-path handles; resolve those through the attached Stage’s path dictionary. IDs that cannot be resolved (a zero/sentinel id, an id from an object removed since it was reported, or a call with no active attach) yield empty paths rather than an error.

Parameters:

  • handle – Instance handle.

  • ids – Input array of opaque identity handles (see fields above).

  • id_count – Number of entries in ids.

  • out_paths – [out] Array of ovphysx_string_t to fill. ovphysx owns the returned string storage. Unlike ovphysx_contact_binding_get_other_actor_paths_from_ids, these pointers are not a per-call cache. Each is owned by the currently attached physics source and stays valid only until the next detach or re-attach. A later call to this function (against the same attach) does not invalidate a pointer returned by an earlier one. Callers that need a path to outlive a detach/re-attach must copy it.

  • max_paths – Capacity of out_paths array.

  • out_count – [out] Total number of ids in ids (== id_count). Only min(id_count, max_paths) entries are written to out_paths.

Returns:

OVPHYSX_API_SUCCESS when the complete result fits, OVPHYSX_API_BUFFER_TOO_SMALL when only a valid prefix was written. Unresolvable ids still yield empty strings; BUFFER_TOO_SMALL is only for a short out_paths, not for empty path entries.

ovphysx_result_t ovphysx_create_sdf_view(
ovphysx_instance_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.

Deprecated: use ovphysx_evaluate_sdf_shapes (ovphysx_geometry_query.h) over an OVPHYSX_QUERY_TARGET_SDF_SHAPE query, which evaluates the same shapes and takes Q from the tensors on every call.

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 implemented and create fails 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_detach_ovstage or loading a new stage) or when the instance is destroyed (via ovphysx_destroy_instance) 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_instance on the same handle.

Parameters:

  • handle – Instance handle.

  • pattern – USD-style path glob selecting SDF-enabled collision shapes, including runtime-only clones (e.g. “/World/Mesh*”). Must match at least one shape or the call returns an error. A single path component longer than 4096 characters is rejected with OVPHYSX_API_INVALID_ARGUMENT.

  • 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_instance_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_instance_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_instance_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] with 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_instance_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 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.

Defines

OVPHYSX_CREATE_ARGS_DEFAULT#

Typedefs

typedef uint64_t ovphysx_tensor_binding_handle_t#

Deprecated:

Tensor-binding handle. Use ovphysx_read / ovphysx_write sessions instead.

typedef uint64_t ovphysx_contact_binding_handle_t#
typedef uint64_t ovphysx_sdf_view_handle_t#

Enums

enum ovphysx_object_type_t#

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

Deprecated:

Returned only by ovphysx_get_object_type. Session read/write and physxPointer take ovphysx_query_target_t. ovphysx_physx_type_t is the kind carried by object-change callbacks.

Mirrors omni::physics::tensors::ObjectType. The JOINT / ARTICULATION_JOINT / CUSTOM_JOINT split mirrors ovphysx_physx_type_t’s OVPHYSX_PHYSX_TYPE_JOINT, OVPHYSX_PHYSX_TYPE_LINK_JOINT, and OVPHYSX_PHYSX_TYPE_CUSTOM_JOINT.

Values:

enumerator OVPHYSX_OBJECT_TYPE_INVALID#

No classified simulation object at the path.

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#

Reduced-coordinate articulation joint.

enumerator OVPHYSX_OBJECT_TYPE_JOINT#

Maximal-coordinate standalone joint (physx::PxJoint)

enumerator OVPHYSX_OBJECT_TYPE_CUSTOM_JOINT#

Plugin-registered custom joint (CustomPhysXJoint)

enum ovphysx_config_key_type_t#

Deprecated:

Use ovphysx_config_value_type_t.

Values:

enumerator OVPHYSX_CONFIG_KEY_TYPE_BOOL#
enumerator OVPHYSX_CONFIG_KEY_TYPE_INT32#
enumerator OVPHYSX_CONFIG_KEY_TYPE_FLOAT#
enumerator OVPHYSX_CONFIG_KEY_TYPE_STRING#
enumerator OVPHYSX_CONFIG_KEY_TYPE_CARBONITE#
enumerator OVPHYSX_CONFIG_KEY_TYPE_COUNT#
enum ovphysx_config_bool_t#

Deprecated:

Use ovphysx_global_config_key_t.

Values:

enumerator OVPHYSX_CONFIG_DISABLE_CONTACT_PROCESSING#
enumerator OVPHYSX_CONFIG_COLLISION_CONE_CUSTOM_GEOMETRY#
enumerator OVPHYSX_CONFIG_COLLISION_CYLINDER_CUSTOM_GEOMETRY#
enumerator OVPHYSX_CONFIG_BOOL_COUNT#
enum ovphysx_config_int32_t#

Deprecated:

Use ovphysx_global_config_key_t.

Values:

enumerator OVPHYSX_CONFIG_NUM_THREADS#

/persistent/physics/numThreads

enumerator OVPHYSX_CONFIG_SCENE_MULTI_GPU_MODE#
enumerator OVPHYSX_CONFIG_OVSTAGE_READ_POOL_MAX_MB#
enumerator OVPHYSX_CONFIG_PROFILER_BACKEND#
enumerator OVPHYSX_CONFIG_INT32_COUNT#
enum ovphysx_config_float_t#

Deprecated:

Use ovphysx_global_config_key_t.

Values:

enumerator OVPHYSX_CONFIG_FLOAT_COUNT#
enum ovphysx_config_string_t#

Deprecated:

Use ovphysx_global_config_key_t.

Values:

enumerator OVPHYSX_CONFIG_COOKED_COLLIDER_CACHE_DIRECTORY#
enumerator OVPHYSX_CONFIG_PROFILER_OUTPUT_PATH#
enumerator OVPHYSX_CONFIG_STRING_COUNT#
enum ovphysx_scene_query_mode_t#

Scene query mode.

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_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: Exposed view world (subspace origin removed) 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: Exposed view world (subspace origin removed) 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: Root link’s center-of-mass (mass) frame, not its actor/prim 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).

INVERSE DYNAMICS QUERY TENSORS (READ-ONLY)#

Generalized joint coordinates follow the authored USD body relationship: their sign is +1 when body0 is the articulation parent and -1 when body1 is the parent. Let S_dof contain those signs and let T=S_dof for a fixed base or T=diag(I6,S_dof) for a floating base. The returned quantities satisfy J=J_physx*T, M=T*M_physx*T, c=T*c_physx, g=T*g_physx, and [A|b]=[A_physx*T|b_physx] for the packed centroidal matrix and bias. The six floating-root coordinates and centroidal bias are unchanged. Angular generalized- coordinate dimensions use radians and receive no degree conversion. Prismatic and floating-translation dimensions retain their linear units.

OVPHYSX_TENSOR_ARTICULATION_JACOBIAN_F32 Shape: [N, R, C] where R, C come 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] where M comes 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

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_read (reads) and ovphysx_write (writes) instead.

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 in exposed view world frame

enumerator OVPHYSX_TENSOR_ARTICULATION_ROOT_VELOCITY_F32#

[N, 6] root velocities

enumerator OVPHYSX_TENSOR_ARTICULATION_MASS_CENTER_WORLD_F32#

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

enumerator OVPHYSX_TENSOR_ARTICULATION_MASS_CENTER_LOCAL_F32#

[N, 3] articulation COM in root-link mass 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)

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

Deprecated:

Use ovphysx_config_value_t and a scoped key enum.

Public Members

ovphysx_config_key_type_t key_type#
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#
union ovphysx_config_entry_t::[anonymous] key#
bool bool_value#
int32_t int32_value#
float float_value#
ovphysx_string_t string_value#
union ovphysx_config_entry_t::[anonymous] value#
struct ovphysx_config_t#
#include <include/ovphysx/ovphysx_legacy_types.h>

Deprecated:

Use scoped configuration setters.

Public Members

const ovphysx_config_entry_t *entries#
uint32_t entry_count#
struct ovphysx_create_args#
#include <include/ovphysx/ovphysx_legacy_types.h>

Deprecated:

Use ovphysx_create_instance(), then ovphysx_set_config() before attaching a stage.

Public Members

ovphysx_string_t bundled_deps_path#
const ovphysx_config_entry_t *config_entries#
uint32_t config_entry_count#
ovphysx_string_t active_cuda_gpus#
struct ovphysx_scene_query_geometry_desc_t#
#include <include/ovphysx/ovphysx_legacy_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_legacy_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. Only the object identity fields are populated.

Path fields (collision, rigid_body, material) hold an opaque omni::physics::parse::ObjectKey.handle, a runtime-assigned identity, not a uint64-encoded SdfPath. There is no client-side bit-cast that reproduces or compares against it. Resolve it to a prim path with ovphysx_scene_query_get_paths_from_ids().

Public Members

uint64_t collision#

Collision shape identity (opaque ObjectKey.handle).

uint64_t rigid_body#

Rigid body identity (opaque ObjectKey.handle).

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 identity (opaque ObjectKey.handle).

Zero for overlap.

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

Descriptor for creating a tensor binding.

A tensor binding connects physics-object paths to a tensor type, enabling bulk read/write of physics data for authored USD objects and runtime-only clones.

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

  • pattern: Path pattern such as “/World/robot*” or “/World/env[0-9]/robot”. The matching rules (*, ?, **, character classes, alternation, and the last-component rule) are on the “Path patterns” page of the ovphysx documentation (docs/read_write/path_patterns.md). [N] is not an index placeholder: it matches the letter N.

  • prim_paths: Explicit list of exact physics-object 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 physics-object 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 };

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_read (reads) and ovphysx_write (writes) instead.

Public Members

ovphysx_string_t pattern#

Physics-object path glob (ignored if prim_paths is set)

const ovphysx_string_t *prim_paths#

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

uint32_t prim_paths_count#

Number of object 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_legacy_types.h>

Tensor layout specification for DLTensor construction.

Use ovphysx_get_tensor_binding_spec() to get the exact dtype, rank, and shape needed to allocate a layout-compatible tensor. Query native memory residency separately with ovphysx_get_tensor_binding_native_device().

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) as 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)

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_read (reads) and ovphysx_write (writes) instead.

Public Members

DLDataType dtype#

DLPack data type for this tensor type.

Most bindings use float32, element-index tensors use int32, and 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_legacy_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.

Deprecated:

Produced only by the deprecated ovphysx_get_articulation_metadata. It retires with the tensor-binding surface. Its successor is the six whole-articulation topology read attributes in ovphysx_attributes.h (OVPHYSX_ATTR_DOF_COUNT, OVPHYSX_ATTR_LINK_COUNT, OVPHYSX_ATTR_JOINT_COUNT, OVPHYSX_ATTR_FIXED_TENDON_COUNT, OVPHYSX_ATTR_SPATIAL_TENDON_COUNT, OVPHYSX_ATTR_IS_FIXED_BASE), which cover these fields field-for-field via ovphysx_read().

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.

Deprecated typed-entry builders retained for source migration.

Functions

static inline ovphysx_config_entry_t ovphysx_config_entry_bool(
ovphysx_config_bool_t key,
bool value,
)#
static inline ovphysx_config_entry_t ovphysx_config_entry_int32(
ovphysx_config_int32_t key,
int32_t value,
)#
static inline ovphysx_config_entry_t ovphysx_config_entry_float(
ovphysx_config_float_t key,
float value,
)#
static inline ovphysx_config_entry_t ovphysx_config_entry_string(
ovphysx_config_string_t key,
ovphysx_string_t value,
)#
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.

The value string is converted to bool, integer, float, or string by the legacy consumer. Both borrowed strings must remain valid through the call.

static inline ovphysx_config_entry_t ovphysx_config_entry_disable_contact_processing(
bool value,
)#
static inline ovphysx_config_entry_t ovphysx_config_entry_collision_cone_custom_geometry(
bool value,
)#
static inline ovphysx_config_entry_t ovphysx_config_entry_collision_cylinder_custom_geometry(
bool value,
)#
static inline ovphysx_config_entry_t ovphysx_config_entry_num_threads(
int32_t value,
)#

Set PhysX worker count (/persistent/physics/numThreads) before scene attachment.

The default dispatcher caps it at the shared tasking pool size. 0 runs tasks inline. This setting does not resize supporting worker pools or an already attached dispatcher.

static inline ovphysx_config_entry_t ovphysx_config_entry_scene_multi_gpu_mode(
int32_t value,
)#
static inline ovphysx_config_entry_t ovphysx_config_entry_ovstage_read_pool_max_mb(
int32_t value,
)#
static inline ovphysx_config_entry_t ovphysx_config_entry_profiler_backend(
ovphysx_profiler_backend_t value,
)#
static inline ovphysx_config_entry_t ovphysx_config_entry_profiler_output_path(
ovphysx_string_t value,
)#

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_TIMEOUT_POLL#
OVPHYSX_TIMEOUT_INFINITE#
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.

Typedefs

typedef uint64_t ovphysx_instance_handle_t#

One ovphysx handle, created by ovphysx_create_instance.

Owns per-handle bookkeeping (sessions, bindings, subscriptions, op waits, debug-render cache) and at most one live ovstage attach. Several handles may be attached at once. They share process-wide services (foundation, SDK tolerance scale, hard CPU-only mode, logging, recording transport).

typedef ovphysx_instance_handle_t ovphysx_handle_t#

Deprecated 0.6 compatibility spelling; removal proposed for 0.7.

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_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_write_handle_t#

App-to-physics write session (ovphysx_write).

typedef uint64_t ovphysx_timeout_t#

Nanosecond timeout used by timeout-bearing OVPhysX APIs.

Values are nanoseconds. OVPHYSX_TIMEOUT_POLL performs one non-blocking readiness check, while OVPHYSX_TIMEOUT_INFINITE waits until completion. This local uint64_t alias is byte-identical to the shared ovx_timeout_ns_t so that it can migrate to that type without an ABI change.

typedef void (*ovphysx_log_callback_t)(ovphysx_log_level_t severity, ovphysx_string_t message, ovphysx_string_t channel, double timestamp, void *user_data)#

Log callback function type.

Called for each message that passes the callback’s severity and channel filters. Invocations for one registration are serialized.

Note

A callback implemented in C++ must not allow exceptions to cross this C ABI boundary.

Param severity:

The ovphysx_log_level_t severity of the message.

Param message:

UTF-8 message. Valid only during the callback and guaranteed null-terminated at message.ptr[message.length].

Param channel:

UTF-8 source/channel. Valid only during the callback and guaranteed null-terminated at channel.ptr[channel.length]. An unavailable channel is delivered as {“”, 0}.

Param timestamp:

Seconds since the Unix epoch. Always greater than zero.

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 read physxPointer 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 its 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 it to retain it. ptr is non-NULL and ptr[length] is ‘\0’.

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 before returning. That pointer is unusable once this callback returns. Do NOT call release() on it (ovphysx owns the lifetime).

Only fires for destructions that occur during simulation. Bulk teardown (e.g. ovphysx_detach_ovstage()) 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 and null-termination 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_detach_ovstage()). Subscribers should flush their entire pointer cache before returning. Every cached pointer is unusable once this callback returns. No per-object destruction events are delivered for this teardown.

Param user_data:

Opaque pointer passed during subscription.

Enums

enum ovphysx_writability_t#

How a tensor type may be written, asked of the API rather than read from docs.

Derived from the backend’s actual getter/setter support, NOT from the (READ-ONLY) markers in this header’s comments. Those are an incomplete index, and their absence never implied writable.

Values:

enumerator OVPHYSX_WRITABILITY_UNCLASSIFIED#

not classified.

The write API rejects it (a gap to close, not a licence)

enumerator OVPHYSX_WRITABILITY_WRITABLE#

writable with no precondition beyond the object existing

enumerator OVPHYSX_WRITABILITY_CONDITIONAL#

writable only under a stated condition.

The write reports an unmet one

enumerator OVPHYSX_WRITABILITY_WRITE_ONLY#

writable control input with no read-back through ovphysx_read

enumerator OVPHYSX_WRITABILITY_READ_ONLY#

readable only.

Writing is an error naming the type, not a silent no-op

enum ovphysx_query_target_t#

Query target type selected by ovphysx_query().

These are engine types, not a USD schema predicate.

Values are explicit, contiguous, and start at 0. Leave OVPHYSX_QUERY_TARGET_COUNT unnumbered so it stays one past the last value. Query gates treat [0, OVPHYSX_QUERY_TARGET_COUNT) as every valid target, so a gap is an unnamed target.

Add a target immediately before OVPHYSX_QUERY_TARGET_COUNT and give it the next integer. Do not insert earlier, leave a gap, or change a value that already shipped: the integer is the public query argument.

Most entries select simulated prims. OVPHYSX_QUERY_TARGET_DEBUG_RENDER does not: it is an instance target, not a prim. Further instance targets belong with it. That grouping does not reserve the tail of the enum. A later simulated type appends after those targets rather than inserting ahead of them.

Values:

enumerator OVPHYSX_QUERY_TARGET_RIGID_BODY#

dynamic rigid bodies (standalone + point-instancer instances)

enumerator OVPHYSX_QUERY_TARGET_ARTICULATION_LINK#

articulation link body transforms

enumerator OVPHYSX_QUERY_TARGET_ARTICULATION_JOINT#

articulation joint state (per-axis, one array group per joint)

enumerator OVPHYSX_QUERY_TARGET_VEHICLE_WHEEL#

vehicle wheel transforms

enumerator OVPHYSX_QUERY_TARGET_DEFORMABLE_VOLUME#

volume deformable meshes (points / velocities)

enumerator OVPHYSX_QUERY_TARGET_DEFORMABLE_SURFACE#

surface deformable meshes

enumerator OVPHYSX_QUERY_TARGET_PARTICLE_SET#

particle sets

enumerator OVPHYSX_QUERY_TARGET_FIXED_TENDON#

articulation fixed tendons (prim: joint carrying the root axis)

enumerator OVPHYSX_QUERY_TARGET_SPATIAL_TENDON#

articulation spatial tendons (prim: link carrying the root attachment)

enumerator OVPHYSX_QUERY_TARGET_ARTICULATION#

whole articulations (prim: the articulation-root API prim)

enumerator OVPHYSX_QUERY_TARGET_DEFORMABLE_MATERIAL#

deformable materials (prim: the bound Material prim)

enumerator OVPHYSX_QUERY_TARGET_CONTACT_SENSOR#

Contact-reporting bodies and colliders carrying PhysxContactReportAPI; contact forces, contacts, events.

Separate child-collider rows are available only on CPU simulation or GPU dynamics with CPU readback. DirectGPU omits separate child-collider rows; standalone static collider rows remain but read zero force. A body row aggregates its colliders’ &#8212; don’t sum across them.

enumerator OVPHYSX_QUERY_TARGET_CHARACTER_CONTROLLER#

capsule character controllers

enumerator OVPHYSX_QUERY_TARGET_VEHICLE#

whole vehicles (prim: the vehicle/chassis prim)

enumerator OVPHYSX_QUERY_TARGET_SCENE#

PxScene at the physics-scene prim.

enumerator OVPHYSX_QUERY_TARGET_PHYSX_MATERIAL#

PxMaterial (not a deformable material)

enumerator OVPHYSX_QUERY_TARGET_SHAPE#

PxShape.

enumerator OVPHYSX_QUERY_TARGET_COMPOUND_SHAPE#

compound-shape wrapper

enumerator OVPHYSX_QUERY_TARGET_RIGID_ACTOR#

PxRigidDynamic and PxRigidStatic.

enumerator OVPHYSX_QUERY_TARGET_JOINT#

standalone PxJoint

enumerator OVPHYSX_QUERY_TARGET_CUSTOM_JOINT#

plugin custom joint

enumerator OVPHYSX_QUERY_TARGET_PARTICLE_SYSTEM#

PxPBDParticleSystem.

enumerator OVPHYSX_QUERY_TARGET_PHYSICS#

process-global PxPhysics; one row, path “/”

enumerator OVPHYSX_QUERY_TARGET_DEBUG_RENDER#

this instance’s debug-render target; not a prim

enumerator OVPHYSX_QUERY_TARGET_SDF_SHAPE#

SDF collision shapes (query-only)

enumerator OVPHYSX_QUERY_TARGET_COUNT#

one past the last valid type; the range-check bound (not a type)

enum ovphysx_object_scope_t#

Output query scope.

For OVPHYSX_QUERY_TARGET_ARTICULATION, ACTIVE includes an articulation when any link is reported by its owning scene’s active-actor set. If that scene cannot report active actors, articulation awake state is the fallback. DirectGPU currently disables sleeping, so its whole-articulation ACTIVE membership is equivalent to ALL. Scene, PhysX material, shape, compound shape, rigid actor, standalone joint, custom joint, particle system, and the PxPhysics singleton have no active notion: ACTIVE matches ALL. The PxPhysics query is one row and ignores prim-set selection.

Note

Queries are reusable selectors. OVPHYSX_SCOPE_ACTIVE membership is recomputed every step and evaluated when a read or write session opens. OVPHYSX_SCOPE_ALL membership is stable across steps until a structural change (object add/remove, instancer instance-count change). Session groups capture the membership at session open. OVPHYSX_QUERY_TARGET_DEBUG_RENDER validates this argument and then ignores it. Geometry filtering for that target is its scope setting, not this query scope.

Values:

enumerator OVPHYSX_SCOPE_ALL#

every object of the type

enumerator OVPHYSX_SCOPE_ACTIVE#

type-specific active membership; see ovphysx_query

enum ovphysx_read_omission_t#

Reasons applicable selected read partitions did not produce groups.

Bits combine across partitions; they do not identify or count affected objects.

Values:

enumerator OVPHYSX_READ_OMISSION_UNSUPPORTED_ATTRIBUTE#
enumerator OVPHYSX_READ_OMISSION_UNSUPPORTED_CONFIGURATION#
enumerator OVPHYSX_READ_OMISSION_NOT_READY#
enum ovphysx_articulation_kinematic_flag_t#

Bit flags for ovphysx_update_articulations_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_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). Slots with no live point-instancer body are zero-filled in every emitted array. In particular, an all-zero orientations quaternion is the absent-slot marker; live orientations are normalized and never all zero.

    is_array decides how many tensors a group carries, and reading only tensors[0] is wrong for half of them:

    • is_array == false (a FIXED group, e.g. rigid-body position) stacks every prim into ONE tensor. tensor_count == 1, and row i belongs to prim i of prims.list.

    • is_array == true (an ARRAY group, e.g. joint state, point-instancer positions, deformable points) carries ONE TENSOR PER PRIM. tensor_count == prims.count, and tensors[i] is prim i’s own variable-length array. A joint read of 16k joints is ONE group with 16k tensors, not 16k groups. Taking tensors[0] yields the first prim’s values and no error. Element type is per attribute, in tensors[i].dtype. Do not assume f32. Most columns are {kDLFloat, 32}. The boolean flags (disableGravity, disableSimulation) and isSleeping are {kDLUInt, 8}; shapeCount is {kDLInt, 32}. dtype.lanes is the tuple width, and for a per-shape column it is the widest selected object in THAT read, so it varies between reads of the same attribute. Do not cache it.

  • residency is per attribute too. On a DirectGPU scene the simulated outputs (pose, velocity, acceleration, and whole-articulation centerOfMassWorld / centerOfMassLocal) are kDLCUDA, while authored body properties (mass, inertia, centerOfMassPosition / centerOfMassOrientation, and the flags) are kDLCPU: PhysX never writes those authored values back, so there is no device copy to read. isSleeping is also kDLCPU: DirectGPU disables sleeping, so the scene flag supplies 0. One read can therefore hand back both. Branch on tensors[i].device.device_type.

  • discovery is an ovstage_query_result_t (attributes is the interned token array, and 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 from ovphysx_attributes.h) or an interned token from discovery, no round-trip.

The queried ovphysx_query_target_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_DEFAULT#

Set-level sentinel: restore the library default (WARNING).

Never delivered

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 (library default)

enumerator OVPHYSX_LOG_ERROR#

Error messages only.

enumerator OVPHYSX_LOG_NONE#

Set-level sentinel: no logging.

Never delivered

enum ovphysx_physx_type_t#

Identifies the type of a path-bound or process-global PhysX object.

Names the PhysX kind a physxPointer read returns for the matching query object type. Object-change callbacks still pass this enum. The named constants below cover common runtime object types.

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

CustomPhysXJoint (plugin 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

COMPOUND_SHAPE returns an internal compound-shape wrapper. Use the C++ helper matching the 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_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 out_required_size

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_INVALID_STATE#

Operation is not valid in the instance’s current lifecycle state.

enum ovphysx_config_value_type_t#

Value discriminator shared by instance and process-global configuration.

Values:

enumerator OVPHYSX_CONFIG_VALUE_BOOL#
enumerator OVPHYSX_CONFIG_VALUE_INT64#
enumerator OVPHYSX_CONFIG_VALUE_DOUBLE#
enumerator OVPHYSX_CONFIG_VALUE_STRING#
enum ovphysx_global_config_key_t#

Process-global configuration keys.

Global keys occupy 0x00000000..0x0000ffff. Values in the instance-key range are always rejected even when explicitly cast to this enum.

Values:

enumerator OVPHYSX_GLOBAL_CONFIG_DISABLE_CONTACT_PROCESSING#

bool; runtime mutable

enumerator OVPHYSX_GLOBAL_CONFIG_COLLISION_CONE_CUSTOM_GEOMETRY#

bool; no stage attached; inverse of /physics/collisionApproximateCones

enumerator OVPHYSX_GLOBAL_CONFIG_COLLISION_CYLINDER_CUSTOM_GEOMETRY#

bool; no stage attached; inverse of /physics/collisionApproximateCylinders

enumerator OVPHYSX_GLOBAL_CONFIG_NUM_THREADS#

int64 in 0..255; no stage attached

enumerator OVPHYSX_GLOBAL_CONFIG_SCENE_MULTI_GPU_MODE#

int64 in 0..2; no stage attached

enumerator OVPHYSX_GLOBAL_CONFIG_OVSTAGE_READ_POOL_MAX_MB#

int64 fitting int32; runtime mutable

enumerator OVPHYSX_GLOBAL_CONFIG_PROFILER_BACKEND#

int64 ovphysx_profiler_backend_t; startup-only

enumerator OVPHYSX_GLOBAL_CONFIG_COOKED_COLLIDER_CACHE_DIRECTORY#

string; startup-only

enumerator OVPHYSX_GLOBAL_CONFIG_PROFILER_OUTPUT_PATH#

string; startup-only

enumerator OVPHYSX_GLOBAL_CONFIG_CPU_ONLY#

bool; startup-only; true is sticky

enumerator OVPHYSX_GLOBAL_CONFIG_LOG_LEVEL#

int64 ovphysx_log_level_t; runtime mutable

enumerator OVPHYSX_GLOBAL_CONFIG_DEFAULT_LOG_OUTPUT#

bool; runtime mutable

enumerator OVPHYSX_GLOBAL_CONFIG_OVD_RECORDING_CAPABLE#

bool; default false; startup-only.

Enables OVD recording capability without starting output. Attach a stage, then call ovphysx_ovd_start_recording() to record.

enum ovphysx_config_key_t#

Per-instance configuration keys.

Instance keys occupy 0x00010000..0xffff0000 so accidental casts from a global key fail validation instead of selecting another setting.

Values:

enumerator OVPHYSX_CONFIG_ACTIVE_CUDA_GPUS#

string; mutable before this instance attaches

enum ovphysx_profiler_backend_t#

Profiler backend selection used by OVPHYSX_GLOBAL_CONFIG_PROFILER_BACKEND.

Values:

enumerator OVPHYSX_PROFILER_BACKEND_NONE#
enumerator OVPHYSX_PROFILER_BACKEND_NVTX#
enumerator OVPHYSX_PROFILER_BACKEND_TRACE#
enum ovphysx_omnipvd_transport_t#

Destination transport for a late OmniPVD recording.

Values:

enumerator OVPHYSX_OMNIPVD_TRANSPORT_FILE#

Write one exact .ovd file path.

enumerator OVPHYSX_OMNIPVD_TRANSPORT_TCP#

Connect to one TCP listener.

enum ovphysx_debug_render_parameter_t#

PhysX debug-visualization parameter indices.

Mirrors omni::physx::PhysXVisualizationParameter. A static_assert in the sidecar keeps the two enums aligned. The session attribute for each index is the matching OVPHYSX_ATTR_DEBUG_* name. NONE (0) and COUNT are not parameters.

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.

Variables

const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_ENABLED#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_SCALE#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_WORLD_AXES#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_BODY_AXES#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_BODY_MASS_AXES#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_BODY_LINEAR_VELOCITY#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_BODY_ANGULAR_VELOCITY#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_CONTACT_POINT#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_CONTACT_NORMAL#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_CONTACT_ERROR#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_CONTACT_IMPULSE#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_FRICTION_POINT#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_FRICTION_NORMAL#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_FRICTION_IMPULSE#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_ACTOR_AXES#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_COLLISION_AABBS#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_COLLISION_SHAPES#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_COLLISION_AXES#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_COLLISION_COMPOUNDS#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_COLLISION_FACE_NORMALS#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_COLLISION_EDGES#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_COLLISION_STATIC_PRUNER#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_COLLISION_DYNAMIC_PRUNER#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_JOINT_LOCAL_FRAMES#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_JOINT_LIMITS#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_CULL_BOX#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_MBP_REGIONS#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_SIMULATION_MESH#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_SDF#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_CULLING_BOX#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_SCOPE#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_POINT_POSITION#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_POINT_COLOR#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_LINE_POSITION#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_LINE_COLOR#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_TRIANGLE_POSITION#
const ovx_string_or_token_t OVPHYSX_NAME_DEBUG_TRIANGLE_COLOR#
struct ovphysx_string_t#
#include <include/ovphysx/ovphysx_types.h>

String with pointer and length.

Input strings are length-prefixed views and need not be null-terminated. Strings produced by successful ovphysx calls (return values and populated out-parameters) and strings delivered to callbacks always have a non-NULL ptr and are null-terminated: ptr[length] == ‘\0’. Always use length for comparisons and when accepting input substring views. Use OVPHYSX_LITERAL(“literal”) or ovphysx_cstr() for convenient construction.

Public Members

const char *ptr#

Pointer to string data.

See the input/output contract above

size_t length#

Length in bytes.

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

Prim-set selection for ovphysx_query_selection &#8212; an explicit list of native prim-path handles OR a glob pattern, applied to BOTH the read and a write opened over the query (ADR-0025).

The selection stands in for a scope: a selected query covers every selected object of its type, sleeping ones included. prim_paths wins over pattern when both are set; they are never combined. A selection that resolves to no object of the queried type is a valid empty query (total_prim_count == 0), not an error.

prim_paths are interned ovx_primpath_t handles the caller already holds &#8212; from a read group’s prims.list (resolved through the attached Stage’s dictionary) or interned through the attached Stage’s OVX dictionary. They are NOT strings: the caller resolves paths to handles, so the runtime maps them straight to objects without re-running the glob matcher. pattern stays a string because a glob is resolved, not named. Handles are valid only for the attached Stage’s path dictionary. A handle kept after every OVStage instance was released belongs to a destroyed dictionary: it is invalid, and the runtime cannot detect it, so it may name a different prim.

Public Members

ovphysx_string_t pattern#

Path pattern (ignored if prim_paths is set); rules on the “Path patterns” docs page.

const ovx_primpath_t *prim_paths#

Explicit interned prim-path handles (NULL = use pattern)

uint32_t prim_paths_count#

Number of handles (0 = use pattern)

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

One requested read attribute, in original request order.

Public Members

ovx_token_t attribute#

Canonical token; OVX_INVALID_TOKEN for an unsupported name.

size_t group_count#

Emitted groups (batches), not objects or tensor rows.

uint32_t omission_reasons#

Bitwise OR of ovphysx_read_omission_t; may coexist with emitted groups.

Zero is not an error.

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

Immutable read-open summary.

Nested storage belongs to the read session until accepted read release or instance destruction. Detach invalidates the attachment’s dictionary use, not this summary storage. Copying this struct copies the attributes pointer, not its rows. Copy all attribute_count rows before their lifetime ends to retain them longer; copied tokens still require a valid attachment dictionary for resolution.

Public Members

size_t total_prim_count#

Matched prim identities, not emitted rows or ready GPU objects.

size_t attribute_count#

Original request length, including unsupported attributes.

const ovphysx_read_attribute_result_t *attributes#

Session-owned rows; see the lifetime above.

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

One accepted write attribute, in original request order.

Public Members

ovx_token_t attribute#

Canonical token from the attached Stage’s dictionary.

size_t group_count#

Planned groups (batches), not objects or tensor rows; no promise of commit success.

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

Immutable write-open summary.

Nested storage belongs to the write session until accepted write release, stage detach or instance destruction, whichever occurs first. Copying this struct copies the attributes pointer, not its rows. Copy all attribute_count rows before their lifetime ends to retain them longer; copied tokens still require a valid attachment dictionary for resolution.

Public Members

size_t total_prim_count#

Matched prim identities, not emitted rows or ready GPU objects.

size_t attribute_count#

Original request length.

const ovphysx_write_attribute_result_t *attributes#

Session-owned rows; see the lifetime above.

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

Writable group and its unambiguous original request index.

Public Members

const ovstage_map_group_t *group#

Original producer-owned pointer; also the commit identity.

size_t attribute_index#

Original request index, or SIZE_MAX when group is NULL.

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

One contact-sensor selection and its filters, for ovphysx_query_contacts (ADR-0044).

sensors selects sensor bodies. filters points at filters_per_sensor filter selections (NULL when that is 0): filter f must match either one object, shared by every sensor of this selection, or exactly one object per sensor, paired by position. Each selection follows the ovphysx_query_selection_t rules.

Public Members

ovphysx_query_selection_t sensors#

The sensor bodies.

const ovphysx_query_selection_t *filters#

filters_per_sensor filter selections, or NULL

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, because ovphysx copies the relevant state internally.

Threading: callbacks may fire from internal worker threads during ovphysx_step(), ovphysx_step_sync(), or ovphysx_detach_ovstage(). Do NOT call other ovphysx APIs from inside a callback (re-entrancy / deadlock risk). ovphysx_unsubscribe_object_changes() while any object-change callback is running returns OVPHYSX_API_INVALID_STATE and leaves the subscription active. That check follows the Carbonite task when the callback is running as one, and the native thread otherwise. Defer follow-up work until the triggering synchronous call returns, or until the triggering task reaches terminal completion through ovphysx_wait_task() or ovphysx_wait_all().

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_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. A task-wait TIMEOUT instead reports pending work and any collected failures in its wait result; it does not set an immediate error message.

Public Members

ovphysx_api_status_t status#

Operation status code.

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

Copyable receipt for an accepted task.

SUCCESS means admission, including work that executes inline and fails. Collect execution status with a wait. Rejected submissions have zero identity and explain the rejection through ovphysx_get_last_error() on the calling thread.

Public Members

ovphysx_api_status_t status#

Admission status.

ovphysx_op_index_t op_index#

Nonzero issued task index.

ovphysx_instance_handle_t instance#

Owning instance, zero on rejection.

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

Owned output of ovphysx_wait_task() or ovphysx_wait_all().

Initialize to zero before use; release with ovphysx_destroy_wait_task_result(). The library owns the returned fields: do not modify them, free error_tasks separately, or shallow-copy this struct. Individual error receipts may be copied; their borrowed messages remain valid until this result is destroyed, including after instance teardown.

Public Members

const ovphysx_enqueue_result_t *error_tasks#

Failed tasks in submission order.

size_t num_errors#

Number of failed tasks.

ovphysx_enqueue_result_t pending_task#

Earliest pending task; all zero if none.

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 the caller’s 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_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_value_t#
#include <include/ovphysx/ovphysx_types.h>

Tagged configuration value.

String inputs are borrowed for the duration of the call. For string getters, string_value.ptr addresses caller-owned writable storage and string_value.length is its capacity. On success length becomes the content length. On OVPHYSX_API_BUFFER_TOO_SMALL it becomes the required capacity, including the terminating NUL.

Public Members

ovphysx_config_value_type_t type#
bool bool_value#
int64_t int64_value#
double double_value#
ovphysx_string_t string_value#
union ovphysx_config_value_t::[anonymous] value#
struct ovphysx_omnipvd_destination_t#
#include <include/ovphysx/ovphysx_types.h>

Destination for ovphysx_ovd_start_recording().

FILE requires a non-empty file_path and empty/zero TCP fields. TCP requires a non-empty tcp_address, tcp_port in 1..65535, and an empty file_path. String views are borrowed only for the synchronous call and must not contain embedded NUL bytes. A zero TCP timeout leaves the socket send timeout at its platform default.

Public Members

ovphysx_omnipvd_transport_t transport#
ovphysx_string_t file_path#
ovphysx_string_t tcp_address#
uint32_t tcp_port#
int32_t tcp_timeout_ms#
struct ovphysx_debug_point_t#
#include <include/ovphysx/ovphysx_types.h>

Packed PhysX debug primitives (position plus 0xAARRGGBB colour).

The OVPHYSX_QUERY_TARGET_DEBUG_RENDER read splits each list into a position column and a color column with aligned indices. There is no index buffer.

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#

Attribute names#

OVPHYSX_ATTR_* string literals for the read and write vocabulary. Include ovphysx_attributes.h alongside ovphysx.h, which does not include it.

Defines

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.

Include this header alongside ovphysx.h. ovphysx.h does not include it.

OVPHYSX_ATTR_ORIENTATION#
OVPHYSX_ATTR_LINEAR_VELOCITY#
OVPHYSX_ATTR_ANGULAR_VELOCITY#
OVPHYSX_ATTR_LINEAR_ACCELERATION#
OVPHYSX_ATTR_ANGULAR_ACCELERATION#
OVPHYSX_ATTR_MASS#
OVPHYSX_ATTR_INVERSE_MASS#
OVPHYSX_ATTR_INERTIA#
OVPHYSX_ATTR_INVERSE_INERTIA#
OVPHYSX_ATTR_CENTER_OF_MASS_POSITION#
OVPHYSX_ATTR_CENTER_OF_MASS_ORIENTATION#
OVPHYSX_ATTR_ROOT_POSITION#
OVPHYSX_ATTR_ROOT_ORIENTATION#
OVPHYSX_ATTR_ROOT_LINEAR_VELOCITY#
OVPHYSX_ATTR_ROOT_ANGULAR_VELOCITY#
OVPHYSX_ATTR_CENTER_OF_MASS_WORLD#
OVPHYSX_ATTR_CENTER_OF_MASS_LOCAL#
OVPHYSX_ATTR_JACOBIAN#
OVPHYSX_ATTR_JACOBIAN_SHAPE#
OVPHYSX_ATTR_MASS_MATRIX#
OVPHYSX_ATTR_CORIOLIS_FORCE#
OVPHYSX_ATTR_GRAVITY_FORCE#
OVPHYSX_ATTR_CENTROIDAL_MOMENTUM#
OVPHYSX_ATTR_DISABLE_GRAVITY#
OVPHYSX_ATTR_DISABLE_SIMULATION#
OVPHYSX_ATTR_PHYSX_POINTER#
OVPHYSX_ATTR_KINEMATIC_TARGET_POSITION#
OVPHYSX_ATTR_KINEMATIC_TARGET_ORIENTATION#
OVPHYSX_ATTR_STATIC_FRICTION#
OVPHYSX_ATTR_DYNAMIC_FRICTION#
OVPHYSX_ATTR_RESTITUTION#
OVPHYSX_ATTR_CONTACT_OFFSET#
OVPHYSX_ATTR_REST_OFFSET#
OVPHYSX_ATTR_SHAPE_COUNT#
OVPHYSX_ATTR_DOF_COUNT#
OVPHYSX_ATTR_JOINT_COUNT#
OVPHYSX_ATTR_FIXED_TENDON_COUNT#
OVPHYSX_ATTR_SPATIAL_TENDON_COUNT#
OVPHYSX_ATTR_IS_FIXED_BASE#
OVPHYSX_ATTR_DOF_JOINT_PATH#
OVPHYSX_ATTR_DOF_AXIS_INDEX#
OVPHYSX_ATTR_POINTS#
OVPHYSX_ATTR_VELOCITIES#
OVPHYSX_ATTR_REST_POINTS#
OVPHYSX_ATTR_SIM_ELEMENT_INDICES#
OVPHYSX_ATTR_COLLISION_ELEMENT_INDICES#
OVPHYSX_ATTR_KINEMATIC_TARGET#
OVPHYSX_ATTR_DEFORMABLE_DYNAMIC_FRICTION#
OVPHYSX_ATTR_DEFORMABLE_YOUNGS_MODULUS#
OVPHYSX_ATTR_DEFORMABLE_POISSONS_RATIO#
OVPHYSX_ATTR_DEFORMABLE_ELASTICITY_DAMPING#
OVPHYSX_ATTR_DEFORMABLE_BENDING_STIFFNESS#
OVPHYSX_ATTR_DEFORMABLE_THICKNESS#
OVPHYSX_ATTR_DEFORMABLE_BENDING_DAMPING#
OVPHYSX_ATTR_NET_NORMAL_CONTACT_FORCE#
OVPHYSX_ATTR_NET_FRICTION_CONTACT_FORCE#
OVPHYSX_ATTR_NORMAL_CONTACT_FORCE_MATRIX#
OVPHYSX_ATTR_FRICTION_CONTACT_FORCE_MATRIX#
OVPHYSX_ATTR_FILTERED_CONTACT_FORCE#
OVPHYSX_ATTR_FILTERED_CONTACT_POINT#
OVPHYSX_ATTR_FILTERED_CONTACT_NORMAL#
OVPHYSX_ATTR_FILTERED_CONTACT_SEPARATION#
OVPHYSX_ATTR_FILTERED_CONTACT_COUNT#
OVPHYSX_ATTR_FILTERED_FRICTION_FORCE#
OVPHYSX_ATTR_FILTERED_FRICTION_POINT#
OVPHYSX_ATTR_FILTERED_FRICTION_COUNT#
OVPHYSX_ATTR_RAW_CONTACT_FORCE#
OVPHYSX_ATTR_RAW_CONTACT_POINT#
OVPHYSX_ATTR_RAW_CONTACT_NORMAL#
OVPHYSX_ATTR_RAW_CONTACT_SEPARATION#
OVPHYSX_ATTR_RAW_CONTACT_OTHER_BODY#
OVPHYSX_ATTR_CONTACT_EVENT_TYPE#
OVPHYSX_ATTR_CONTACT_EVENT_SENSOR_SIDE#
OVPHYSX_ATTR_CONTACT_EVENT_COLLIDER#
OVPHYSX_ATTR_CONTACT_EVENT_OTHER_BODY#
OVPHYSX_ATTR_CONTACT_EVENT_OTHER_COLLIDER#
OVPHYSX_ATTR_CONTACT_EVENT_PROTO_INDEX#
OVPHYSX_ATTR_CONTACT_EVENT_OTHER_PROTO_INDEX#
OVPHYSX_ATTR_CONTACT_EVENT_POINT_COUNT#
OVPHYSX_ATTR_CONTACT_EVENT_ANCHOR_COUNT#
OVPHYSX_ATTR_CONTACT_EVENT_POINT_POSITION#
OVPHYSX_ATTR_CONTACT_EVENT_POINT_NORMAL#
OVPHYSX_ATTR_CONTACT_EVENT_POINT_IMPULSE#
OVPHYSX_ATTR_CONTACT_EVENT_POINT_SEPARATION#
OVPHYSX_ATTR_CONTACT_EVENT_POINT_FACE_INDEX#
OVPHYSX_ATTR_CONTACT_EVENT_POINT_OTHER_FACE_INDEX#
OVPHYSX_ATTR_CONTACT_EVENT_POINT_MATERIAL#
OVPHYSX_ATTR_CONTACT_EVENT_POINT_OTHER_MATERIAL#
OVPHYSX_ATTR_CONTACT_EVENT_ANCHOR_POSITION#
OVPHYSX_ATTR_CONTACT_EVENT_ANCHOR_IMPULSE#
OVPHYSX_ATTR_JOINT_POSITION#
OVPHYSX_ATTR_JOINT_VELOCITY#
OVPHYSX_ATTR_JOINT_POSITION_TARGET#
OVPHYSX_ATTR_JOINT_VELOCITY_TARGET#
OVPHYSX_ATTR_JOINT_ACTUATION_FORCE#
OVPHYSX_ATTR_JOINT_PROJECTED_FORCE#
OVPHYSX_ATTR_JOINT_STIFFNESS#
OVPHYSX_ATTR_JOINT_DAMPING#
OVPHYSX_ATTR_JOINT_LIMIT#
OVPHYSX_ATTR_JOINT_MAX_VELOCITY#
OVPHYSX_ATTR_JOINT_MAX_FORCE#
OVPHYSX_ATTR_JOINT_ARMATURE#
OVPHYSX_ATTR_JOINT_STATIC_FRICTION#
OVPHYSX_ATTR_JOINT_DYNAMIC_FRICTION#
OVPHYSX_ATTR_JOINT_VISCOUS_FRICTION#
OVPHYSX_ATTR_JOINT_SPEED_EFFORT_GRADIENT#
OVPHYSX_ATTR_JOINT_MAX_ACTUATOR_VELOCITY#
OVPHYSX_ATTR_JOINT_VELOCITY_DEPENDENT_RESISTANCE#
OVPHYSX_ATTR_JOINT_DRIVE_TYPE#
OVPHYSX_ATTR_TENDON_STIFFNESS#
OVPHYSX_ATTR_TENDON_DAMPING#
OVPHYSX_ATTR_TENDON_LIMIT_STIFFNESS#
OVPHYSX_ATTR_TENDON_LIMIT#
OVPHYSX_ATTR_TENDON_REST_LENGTH#
OVPHYSX_ATTR_TENDON_OFFSET#
OVPHYSX_ATTR_IS_SLEEPING#
OVPHYSX_ATTR_FORCE#
OVPHYSX_ATTR_WRENCH#
OVPHYSX_ATTR_WAKE#
OVPHYSX_ATTR_ACCELERATOR#
OVPHYSX_ATTR_BRAKE0#
OVPHYSX_ATTR_BRAKE1#
OVPHYSX_ATTR_STEER#
OVPHYSX_ATTR_REQUESTED_GEAR#
OVPHYSX_ATTR_THRUST0#
OVPHYSX_ATTR_THRUST1#
OVPHYSX_ATTR_CLUTCH#
OVPHYSX_ATTR_CURRENT_GEAR#
OVPHYSX_ATTR_TARGET_GEAR#
OVPHYSX_ATTR_ENGINE_ROTATION_SPEED#
OVPHYSX_ATTR_AUTOMATIC_TRANSMISSION#
OVPHYSX_ATTR_GEAR_SWITCH_TIME#
OVPHYSX_ATTR_AUTOBOX_TIME_SINCE_LAST_SHIFT#
OVPHYSX_ATTR_RESET_TO_REST_STATE#
OVPHYSX_ATTR_DRIVE_TORQUE#
OVPHYSX_ATTR_BRAKE_TORQUE#
OVPHYSX_ATTR_STEER_ANGLE#
OVPHYSX_ATTR_ROTATION_SPEED#
OVPHYSX_ATTR_ROTATION_ANGLE#
OVPHYSX_ATTR_WHEEL_STEER_ANGLE#
OVPHYSX_ATTR_SUSPENSION_JOUNCE#
OVPHYSX_ATTR_SUSPENSION_FORCE#
OVPHYSX_ATTR_TIRE_FRICTION#
OVPHYSX_ATTR_TIRE_LONGITUDINAL_DIRECTION#
OVPHYSX_ATTR_TIRE_LATERAL_DIRECTION#
OVPHYSX_ATTR_TIRE_LONGITUDINAL_SLIP#
OVPHYSX_ATTR_TIRE_LATERAL_SLIP#
OVPHYSX_ATTR_TIRE_FORCE#
OVPHYSX_ATTR_IS_ON_GROUND#
OVPHYSX_ATTR_GROUND_PLANE#
OVPHYSX_ATTR_GROUND_HIT_POSITION#
OVPHYSX_ATTR_GROUND_ACTOR_PATH#
OVPHYSX_ATTR_GROUND_SHAPE_PATH#
OVPHYSX_ATTR_GROUND_MATERIAL_PATH#
OVPHYSX_ATTR_CCT_MOVE#
OVPHYSX_ATTR_DEBUG_ENABLED#
OVPHYSX_ATTR_DEBUG_SCALE#
OVPHYSX_ATTR_DEBUG_WORLD_AXES#
OVPHYSX_ATTR_DEBUG_BODY_AXES#
OVPHYSX_ATTR_DEBUG_BODY_MASS_AXES#
OVPHYSX_ATTR_DEBUG_BODY_LINEAR_VELOCITY#
OVPHYSX_ATTR_DEBUG_BODY_ANGULAR_VELOCITY#
OVPHYSX_ATTR_DEBUG_CONTACT_POINT#
OVPHYSX_ATTR_DEBUG_CONTACT_NORMAL#
OVPHYSX_ATTR_DEBUG_CONTACT_ERROR#
OVPHYSX_ATTR_DEBUG_CONTACT_IMPULSE#
OVPHYSX_ATTR_DEBUG_FRICTION_POINT#
OVPHYSX_ATTR_DEBUG_FRICTION_NORMAL#
OVPHYSX_ATTR_DEBUG_FRICTION_IMPULSE#
OVPHYSX_ATTR_DEBUG_ACTOR_AXES#
OVPHYSX_ATTR_DEBUG_COLLISION_AABBS#
OVPHYSX_ATTR_DEBUG_COLLISION_SHAPES#
OVPHYSX_ATTR_DEBUG_COLLISION_AXES#
OVPHYSX_ATTR_DEBUG_COLLISION_COMPOUNDS#
OVPHYSX_ATTR_DEBUG_COLLISION_FACE_NORMALS#
OVPHYSX_ATTR_DEBUG_COLLISION_EDGES#
OVPHYSX_ATTR_DEBUG_COLLISION_STATIC_PRUNER#
OVPHYSX_ATTR_DEBUG_COLLISION_DYNAMIC_PRUNER#
OVPHYSX_ATTR_DEBUG_JOINT_LOCAL_FRAMES#
OVPHYSX_ATTR_DEBUG_JOINT_LIMITS#
OVPHYSX_ATTR_DEBUG_CULL_BOX#
OVPHYSX_ATTR_DEBUG_MBP_REGIONS#
OVPHYSX_ATTR_DEBUG_SIMULATION_MESH#
OVPHYSX_ATTR_DEBUG_SDF#
OVPHYSX_ATTR_DEBUG_CULLING_BOX#
OVPHYSX_ATTR_DEBUG_SCOPE#
OVPHYSX_ATTR_DEBUG_POINT_POSITION#
OVPHYSX_ATTR_DEBUG_POINT_COLOR#
OVPHYSX_ATTR_DEBUG_LINE_POSITION#
OVPHYSX_ATTR_DEBUG_LINE_COLOR#
OVPHYSX_ATTR_DEBUG_TRIANGLE_POSITION#
OVPHYSX_ATTR_DEBUG_TRIANGLE_COLOR#

Scoped Config Values#

Builder functions for scoped configuration values.

Deprecated entry builders are declared in ovphysx_legacy_config.h.

Functions

static inline ovphysx_config_value_t ovphysx_config_value_bool(
bool value,
)#

Build a boolean scoped configuration value.

static inline ovphysx_config_value_t ovphysx_config_value_int64(
int64_t value,
)#

Build a signed 64-bit scoped configuration value.

static inline ovphysx_config_value_t ovphysx_config_value_double(
double value,
)#

Build a double-precision scoped configuration value.

static inline ovphysx_config_value_t ovphysx_config_value_string(
ovphysx_string_t value,
)#

Build a borrowed string scoped configuration value.

OVD Recording#

Set the global recording capability before the first successful instance creation, attach a scene, then pass an explicit destination to ovphysx_ovd_start_recording(). Start before the first simulation step to capture it. Startup configuration is removed; see the OVD migration guide. The old recording names remain deprecated forwarding exports in 0.7. The rest of the 0.6 to 0.7 source break is the migration guide.

C++ Wrappers (Experimental)#

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

namespace ovphysx#

Functions

inline ovphysx_api_status_t setGlobalConfig(
ovphysx_global_config_key_t key,
ovphysx_config_value_t value,
)#
inline ovphysx_api_status_t getGlobalConfig(
ovphysx_global_config_key_t key,
ovphysx_config_value_t &value,
)#

String keys use the same caller-owned buffer protocol as PhysX::getConfig().

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. With no live handles it drains the direct PhysX runtime. Linux also releases the SDK-owned Carbonite framework and private cache; Windows retains its framework until process exit and private-cache removal remains best-effort.

Returns:

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

inline ObjectChangeSubscription subscribeObjectChanges(
ovphysx_instance_handle_t handle,
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 per-instance: pass the owning handle. 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, so 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, so 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::detachOvstage(). Do not call other ovphysx APIs from inside a callback. Defer that work to after the next waitTask() / 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 read physxPointer 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 before returning. It is unusable once this callback returns.

std::function<void()> onAllDestroyed#

Fires BEFORE a bulk teardown (e.g. PhysX::detachOvstage()). Flush the entire pointer cache before returning. 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 ovphysx_api_status_t unsubscribe()#

Unsubscribe explicitly. Idempotent after a successful removal.

On success, or when instance teardown already removed the subscription, both m_id and m_state are cleared. user_data is safe to drop only after that success: the C unsubscribe waits until this subscription’s callbacks have returned.

OVPHYSX_API_INVALID_STATE means an object-change callback is running on this Carbonite task, or on this native thread when the callback is not a Carbonite task. The subscription stays active. Retry after that callback returns. Destroying or move-assigning the handle in that situation closes it without waiting: later callbacks are skipped, and the callback state is freed once that call has unwound, including when the callback throws.

For any other C unsubscribe failure (e.g. internal sidecar unloaded), m_state is intentionally leaked rather than freed. The C-side subscription may still hold a pointer to it. 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_instance_handle_t.

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

Provides implicit conversion to ovphysx_instance_handle_t for use with the 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 waitTask/waitAll when results are needed outside stream order.

Public Types

using SceneQueryHit = ovphysx_scene_query_hit_t#

Public Functions

explicit PhysX(ovphysx_instance_handle_t h)#

Construct from existing handle (takes ownership)

PhysX()#

Default constructor - creates null handle.

~PhysX()#

Destroy a valid instance. Close leases and finish concurrent operations first. A retryable rejection terminates; use reset() to handle and retry it before destruction.

PhysX(PhysX &&other) noexcept#

Move constructor.

PhysX &operator=(PhysX &&other) noexcept#

Move assignment swaps handles; the source owns the destination’s previous handle.

PhysX(const PhysX&) = delete#
PhysX &operator=(const PhysX&) = delete#
inline ovphysx_instance_handle_t handle() const#

Get raw handle.

inline operator ovphysx_instance_handle_t() const#

Implicit conversion to handle for use with C API.

inline explicit operator bool() const#

Check if handle is valid.

ovphysx_instance_handle_t release()#

Release ownership of handle (caller must destroy)

void reset(ovphysx_instance_handle_t h = 0)#

Destroy the current owner then adopt h. A retryable rejection throws std::runtime_error and preserves both handles; h remains caller-owned.

ovphysx_enqueue_result_t detachOvstage()#

Detach the Stage without changing simulation time; already detached is a successful no-op. Executes inline and returns a task receipt; waitTask() or waitAll() collects its outcome.

ovphysx_enqueue_result_t attachOvstage(
ovstage_instance_t *stage,
ovstage_ordinal_t read_ordinal,
)#

Attach an ovstage Stage through the top-level ovphysx API. read_ordinal selects the caller-owned sealed ordinal (must be non-zero, 0 is reserved). This instance may hold one attach. Other instances may be attached at the same time; this call does not detach them. Returns a task receipt; waitTask() or waitAll() collects its outcome.

ovphysx_enqueue_result_t updateFromOvstage(
ovstage_ordinal_range_t range,
)#

Pull and apply ovstage changes over the committed ordinal range. Returns a task receipt; waitTask() or waitAll() collects its outcome.

ovphysx_enqueue_result_t clone(
const std::string &sourcePath,
const std::vector<std::string> &targetPaths,
const float *anchorTransforms = nullptr,
const uint32_t *envIds = 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 runtime physics-object paths for cloned hierarchies (e.g., [“/World/env1”, “/World/env2”])

  • anchorTransforms – Absolute world pose of each target subtree root. Entry i anchors the exact subtree at targetPaths[i]. Flat array of [targetPaths.size() * 7] floats: (px, py, pz, qx, qy, qz, qw) per target. Descendants keep their poses relative to the source subtree root (targetObjectWorld = anchorTransforms[i] * inverse(sourceRootWorld) * sourceObjectWorld). 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.

Returns:

Admission receipt; collect execution errors with waitTask() or waitAll().

ovphysx_enqueue_result_t step(float step_dt)#

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

ovphysx_enqueue_result_t updateArticulationsKinematic(
ovphysx_query_handle_t query,
uint32_t flags,
)#

Recompute selected articulation link state; collect the task’s outcome with waitTask().

ovphysx_enqueue_result_t evaluateSdfShapes(
ovphysx_query_handle_t query,
const DLTensor *points,
DLTensor *out,
ovstage_cuda_sync_t pointsReady = {},
)#

Evaluate the SDFs of an SDF_SHAPE query’s shapes at the given points; collect the outcome with waitTask(). pointsReady is the producer handoff for points, as for ovphysx_evaluate_sdf_shapes.

physx::WaitResult waitTask(
ovphysx_enqueue_result_t task,
ovphysx_timeout_t timeout_ns = OVPHYSX_TIMEOUT_INFINITE,
)#

Collect only this task; inspect the returned status, errors and pending task.

physx::WaitResult waitAll(
ovphysx_timeout_t timeout_ns = OVPHYSX_TIMEOUT_INFINITE,
)#

Collect all uncollected tasks accepted before this call.

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 physics-object paths (matched by pattern) to a tensor type, enabling efficient bulk read/write for authored USD objects and runtime-only clones.

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_read (reads) and ovphysx_write (writes) instead.

Parameters:

  • out_binding – Receives the created TensorBinding on success

  • pattern – Physics-object path pattern (e.g., “/World/robot*”)

  • tensor_type – The type of tensor data to bind

Returns:

OVPHYSX_API_SUCCESS on success

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.

inline ovphysx_api_status_t setConfig(
ovphysx_config_key_t key,
ovphysx_config_value_t value,
)#
inline ovphysx_api_status_t getConfig(
ovphysx_config_key_t key,
ovphysx_config_value_t &value,
) const#

Get one instance value.

For string keys, initialize value as OVPHYSX_CONFIG_VALUE_STRING with caller-owned storage. A zero-capacity query returns OVPHYSX_API_BUFFER_TOO_SMALL and the required capacity.

Public Static Functions

static ovphysx_api_status_t create(PhysX &out_instance)#

Create an instance with default instance configuration.

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

Deprecated:

Set global config before create and instance config after create.

static ovphysx_api_status_t setCpuMode(bool cpuOnly)#

Deprecated:

Use setGlobalConfig(OVPHYSX_GLOBAL_CONFIG_CPU_ONLY, …).

static ovphysx_api_status_t getCpuMode(bool &outCpuOnly)#

Deprecated:

Use getGlobalConfig(OVPHYSX_GLOBAL_CONFIG_CPU_ONLY, …).

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);

Deprecated:

The tensor-binding API is deprecated. Use ovphysx_read (reads) and ovphysx_write (writes) instead. The action members below (spec/metadata/read/write/writeMasked/destroy) and the PhysX::createTensorBinding() factory carry the deprecation marker, so both creating and using a binding warn. The class type itself is left unmarked on purpose: a deprecated type warns wherever it is named, including this header’s own factory declaration, which would warn every consumer merely for including the header. Member-function markers warn only on call.

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 detachment or bound-object removal. read/write 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 nativeDevice(DLDevice &out_device) const#

Query the native DLPack device used by this binding.

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>

Move-only owner of a task wait result and its return status.

Error text remains valid until this result is destroyed, including after the instance is destroyed. A moved-from result owns no storage. Like the C API, waits require an empty result. To reuse a populated owner, explicitly release its current output with result = WaitResult{}; first.

#include <ovphysx/experimental/Helpers.hpp>
#include <iostream>

static ovphysx_api_status_t wait_and_report_errors(
    ovphysx_instance_handle_t handle,
    ovphysx_enqueue_result_t task,
    ovphysx_timeout_t timeout_ns)
{
    ovphysx::physx::WaitResult result;
    result.waitTask(handle, task, timeout_ns);
    for (size_t index = 0; index < result.errorCount(); ++index) {
        ovphysx_enqueue_result_t failed = result.errorTaskAt(index);
        ovphysx_string_t error = ovphysx_get_last_task_error(handle, failed);
        std::cerr << "Task " << failed.op_index << " failed: "
                  << std::string(error.ptr, error.length) << '\n';
    }
    return result.status();
}

Public Functions

WaitResult() = default#
inline ~WaitResult()#
inline WaitResult(WaitResult &&other) noexcept#
inline WaitResult &operator=(WaitResult &&other) noexcept#
WaitResult(const WaitResult&) = delete#
WaitResult &operator=(const WaitResult&) = delete#
inline ovphysx_api_status_t waitTask(
ovphysx_instance_handle_t handle,
ovphysx_enqueue_result_t task,
ovphysx_timeout_t timeout_ns = OVPHYSX_TIMEOUT_INFINITE,
)#
inline ovphysx_api_status_t waitAll(
ovphysx_instance_handle_t handle,
ovphysx_timeout_t timeout_ns = OVPHYSX_TIMEOUT_INFINITE,
)#
inline const ovphysx_wait_task_result_t *get() const#
inline ovphysx_api_status_t status() const#
inline bool hasErrors() const#
inline size_t errorCount() const#
inline ovphysx_enqueue_result_t pendingTask() const#
inline ovphysx_enqueue_result_t errorTaskAt(size_t index) const#
On this page