---
name: tensor-bindings-gpu
description: Read and write physics simulation data on GPU using CUDA device pointers and DLPack tensors. Use when you need GPU-to-GPU tensor exchange (no CPU staging) for high-throughput RL or robotics workloads.
---

# Tensor Bindings: GPU Read and Write

GPU tensor bindings use the PhysX DirectGPU API for direct CUDA access to PhysX simulation buffers.
USD is still used to load the scene and resolve prim path patterns, but the tensor data path does not go through USD.

## C sample (CUDA)

The GPU tensor bindings sample uses `cuda_runtime.h` for device memory allocation and wraps those device pointers in DLPack `DLTensor` structs for:
- `ovphysx_read_tensor_binding()`
- `ovphysx_write_tensor_binding()`

Full sample:
- `samples/c_samples/tensor_bindings_gpu_c/main.c` (SDK)

Key pattern (simplified from the sample):

```c
// Allocate GPU buffer (cudaMalloc) and wrap it in a DLTensor.
// See the sample for how count/components/d_buffer/args are obtained.
int32_t device_id = args.gpu_index;
int64_t shape[2] = { (int64_t)count, (int64_t)components };
DLTensor tensor = {
    .data = d_buffer,
    .device = { kDLCUDA, device_id },
    .ndim = 2,
    .dtype = { kDLFloat, 32, 1 },
    .shape = shape,
    .strides = NULL,       // C-contiguous
    .byte_offset = 0
};

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

## Python with PyTorch

```python
import torch
from ovphysx import PhysX
from ovphysx.types import TensorType

physx = PhysX(device="gpu")
physx.add_usd("scene.usda")
physx.wait_all()

binding = physx.create_tensor_binding(
    pattern="/World/envs/env*/box",
    tensor_type=TensorType.RIGID_BODY_POSE,
)

# Read into a PyTorch CUDA tensor via DLPack
output = torch.zeros(binding.shape, dtype=torch.float32, device="cuda")
binding.read(output)
```

## Important notes

- Device mode (`cpu` vs `gpu`) is set at `PhysX()` creation and is process-global.
- DLPack interop works with PyTorch and other objects implementing the `__dlpack__` protocol.
- Masked writes are supported on GPU as well via `ovphysx_write_tensor_binding_masked()` / `binding.write(..., mask=...)`.

## References

- Docs: `docs/developer_guide.md`
- C sample: `samples/c_samples/tensor_bindings_gpu_c/main.c` (SDK)
