Add CUDA-Graphics (OpenGL) interop support to cuda.core

[rparolin]

Summary

Adds CUDA-Graphics (OpenGL) interoperability support to cuda.core, enabling zero-copy sharing of GPU memory between CUDA compute kernels and OpenGL graphics renderers.

• GraphicsResource — Cython extension class for registering and managing OpenGL buffers/images with CUDA. Supports from_gl_buffer() and from_gl_image() factory methods, map()/unmap() with context manager support, and automatic resource cleanup via close().
• GraphicsRegisterFlags — IntEnum for controlling registration behavior (NONE, READ_ONLY, WRITE_DISCARD, SURFACE_LOAD_STORE, TEXTURE_GATHER).
• C++ handle layer — GraphicsResourceHandle (shared_ptr with custom deleter) integrated into the existing resource handle infrastructure.
• Example — gl_interop_plasma.py: real-time plasma effect rendered by a CUDA kernel directly into an OpenGL PBO, displayed via pyglet.
• Tests — Comprehensive test suite covering registration, map/unmap, context manager, error handling, idempotent close, and GC behavior.

New Public API

import ctypes
from OpenGL import GL as gl
from cuda.core import GraphicsResource, GraphicsRegisterFlags

# Create an OpenGL Pixel Buffer Object (PBO) — GPU memory owned by OpenGL
pbo = ctypes.c_uint(0)
gl.glGenBuffers(1, ctypes.byref(pbo))
gl.glBindBuffer(gl.GL_PIXEL_UNPACK_BUFFER, pbo.value)
nbytes = width * height * 4  # RGBA, 1 byte per channel
gl.glBufferData(gl.GL_PIXEL_UNPACK_BUFFER, nbytes, None, gl.GL_DYNAMIC_DRAW)
pbo_id = pbo.value

# Register the PBO with CUDA for zero-copy access
resource = GraphicsResource.from_gl_buffer(pbo_id, flags=GraphicsRegisterFlags.WRITE_DISCARD)

# Map for CUDA kernel access (context manager auto-unmaps)
with resource.map(stream=stream) as buf:
    launch(stream, config, kernel, buf.handle, width, height, time)

# Cleanup
resource.close()

Files Changed

File	Description
_graphics.pyx / _graphics.pxd	New Cython module with GraphicsResource and GraphicsRegisterFlags
_cpp/resource_handles.cpp / .hpp	GraphicsResourceHandle creation + cuGraphicsUnregisterResource function pointer
_resource_handles.pxd / .pyx	Type alias and function pointer initialization for graphics handles
__init__.py	Export GraphicsResource and GraphicsRegisterFlags
tests/test_graphics.py	Test suite (~350 lines)
examples/gl_interop_plasma.py	Full working example (~410 lines)
pixi.toml / pixi.lock	Added pyglet test dependency

Screenshot

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[Andy-Jost]

optional: you could make the unmap more reliable (and avoid the duplicated calls to cuGraphicsUnmapResources) by making this into a resource, similar to the handle.

[copy-pr-bot]

Auto-sync is disabled for ready for review pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[rparolin]

/ok to test

[github-actions]

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-1608/
https://nvidia.github.io/cuda-python/pr-preview/pr-1608/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-1608/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-1608/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

[leofang]

@jakirkham as the original requester of #241, would it be possible for you to review and provide us your feedbacks here? 🙂

[rparolin]

/ok to test

[leofang]

Drive-by comment: In Python we tend not to use enums. I think in this case accepting a str like register_option="readonly" is already good enough.