/cuda-interop

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: LicenseRef-NvidiaProprietary
#
# NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
# property and proprietary rights in and to this material, related
# documentation and any modifications thereto. Any use, reproduction,
# disclosure or distribution of this material and related documentation
# without an express license agreement from NVIDIA CORPORATION or
# its affiliates is strictly prohibited.
name: cuda-interop
description: >
  GPU interop patterns for CUDA arrays, timeline semaphores, Vulkan shared memory,
  and MIG-safe CUDA-to-Vulkan device matching.
  Use when user asks about CUDA interop, GPU rendering pipelines, Vulkan interop,
  shared memory, timeline semaphores, MIG, or multi-GPU output routing.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - cuda
  - interop
  - mig
  - multi-gpu
tools:
  - Read
  - Grep

CUDA Interop

When to Use

Use this skill when the user asks about CUDA interop, GPU rendering pipelines, Vulkan interop, shared memory, or timeline semaphores.

Inputs

Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.

• Target API surface: Python, C/C++, USD, or a combination.
• Interop path: render output to linear CUDA memory, render output to CUDA array, attribute mapping to CUDA, or Vulkan external memory.
• RenderProduct/RenderVar or attribute target, CUDA device expectations, stream/event handles, and ownership boundaries.
• Tensor/image shape, dtype, synchronization points, and whether the consumer expects linear memory or array/image memory.
• Repository source snippets referenced below. Treat these snippets as the API source of truth.

Prerequisites

• Use an ovrtx checkout that contains the referenced examples and docs tests.
• Read the relevant `> **Source:**` snippet before writing or explaining API usage.
• Confirm whether the requested path needs linear CUDA memory (`Device.CUDA` / `OVRTX_MAP_DEVICE_TYPE_CUDA`), a CUDA array (`Device.CUDA_ARRAY` / `OVRTX_MAP_DEVICE_TYPE_CUDA_ARRAY`), or Vulkan shared memory.
• Use `reading-render-output` for CPU readback or non-interop render output mapping.

Instructions

1. Identify whether the workflow maps render output to CUDA memory, maps output to a CUDA array, writes attributes from CUDA memory, or coordinates CUDA with Vulkan. 2. Read the source snippet for the exact map/unmap path before choosing between linear CUDA memory and a CUDA array; both selectors exist in C (`OVRTX_MAP_DEVICE_TYPE_CUDA`, `OVRTX_MAP_DEVICE_TYPE_CUDA_ARRAY`) and in Python (`Device.CUDA`, `Device.CUDA_ARRAY`). 3. Preserve the synchronization contract: wait on ovrtx-provided CUDA events before reading, record CUDA work completion events before unmapping, and use `sync_stream` only for the auto-sync path. 4. For Vulkan interop, keep external-memory ownership, timeline semaphore ordering, and double-buffer lifetimes aligned with the full `vulkan-interop` example. 5. When changing code, run the CUDA render-output or Vulkan interop example/test that owns the snippet whenever practical. 6. Select a Vulkan device by comparing `cuDeviceGetUuid_v2()` for the configured or mapped CUDA ordinal with `VkPhysicalDeviceIDProperties::deviceUUID`. Do not use PCI identity, `cudaDeviceProp::uuid`, or legacy `cuDeviceGetUuid()` for MIG selection.

Output Format

• For explanations, cite the relevant API names, source snippets, and caveats.
• For code changes, summarize the files changed, snippets affected, and validation run.

Scripts

This skill has no scripts.

Limitations

• The referenced snippets remain the source of truth; update or add tested snippets before documenting new API usage.
• On Linux, the CUDA stream/event synchronization in this skill is subject to a known driver scheduling interaction. Windows is unaffected. Refer to `docs/core/cuda_vulkan_scheduling.rst`.

Overview

ovrtx renders on the GPU and can provide output as CUDA device memory or as a CUDA array (zero-copy). Both are reachable from C and from Python. For advanced pipelines (e.g., Vulkan display, custom CUDA post-processing), you need to handle CUDA synchronization correctly to avoid race conditions between ovrtx's internal GPU work and your own.

Python

Map render output to CUDA

> **Source:** `tests/docs/python/test_camera_sensors.py` snippet `doc-map-render-output-cuda`

Map attribute to CUDA for Warp kernel writes

> **Source:** `tests/docs/python/test_attribute_bindings.py` snippet `doc-map-attribute-cuda`

Map render output as CUDA array (zero-copy)

`device=Device.CUDA_ARRAY` takes the same zero-copy image path as the C API: ovrtx hands back the render target's CUDA array instead of copying it into linear memory. The array is an opaque image handle, so the DLTensor reports an opaque-handle dtype and **no DLPack consumer can read it** — `np.from_dlpack(rv)`, `.numpy()`, and Warp DLPack ingest all fail or are meaningless here. Read the handle from `tensor.cuda_array`.

`tensor.cuda_array` raises if the tensor is linear memory rather than an array, which is what distinguishes it from reading the raw `dl.data` field yourself. Use `rv["<tensor_name>"]` when the render variable carries several tensors.

> **Source:** `tests/docs/python/test_camera_sensors.py` snippet `doc-map-render-output-cuda-array`

**Reading the handle is your CUDA work, not ovrtx's.** ovrtx exposes the handle as a plain `int` and intentionally ships no Python-CUDA bridge to dereference it. Pick an existing one:

• **Warp 1.15+** (recommended, and what the ovrtx test suite uses): `wp.Texture2D(cuda_array=tensor.cuda_array)` aliases the array without taking ownership and infers extent/dtype from it, then `texture.copy_to(wp_array_or_numpy)` copies the pixels out, or `wp.texture_sample()` samples it inside