cuda.core.GraphicsResource#

class cuda.core.GraphicsResource#

RAII wrapper for a CUDA graphics resource (CUgraphicsResource).

A GraphicsResource represents an OpenGL buffer or image that has been registered for access by CUDA. This enables zero-copy sharing of GPU data between CUDA compute kernels and graphics renderers.

Mapping the resource returns a Buffer whose lifetime controls when the graphics resource is unmapped. This keeps stream-ordered cleanup tied to the mapped pointer itself rather than to mutable state on the GraphicsResource object.

The resource is automatically unregistered when close() is called or when the object is garbage collected.

GraphicsResource objects should not be instantiated directly. Use the factory classmethods from_gl_buffer() or from_gl_image().

Examples

Register an OpenGL VBO, map it to get a buffer, and write to it from CUDA:

resource = GraphicsResource.from_gl_buffer(vbo)

with resource.map(stream=s) as buf:
    view = StridedMemoryView.from_buffer(buf, shape=(256,), dtype=np.float32)
    # view.ptr is a CUDA device pointer into the GL buffer

Or scope registration separately from mapping:

with GraphicsResource.from_gl_buffer(vbo) as resource:
    with resource.map(stream=s) as buf:
        # ... launch kernels using buf.handle, buf.size ...
        pass

Methods

__init__(*args, **kwargs)#
close(self, stream=None)#

Unregister this graphics resource from CUDA.

If the resource is currently mapped, it is unmapped first. After closing, the resource cannot be used again.

Parameters:

stream (Stream, optional) – Optional override for the stream used to close the currently mapped buffer, if one exists.

classmethod from_gl_buffer(
cls,
int gl_buffer,
*,
flags=None,
stream=None,
) → GraphicsResource#

Register an OpenGL buffer object for CUDA access.

Parameters:

  • gl_buffer (int) – The OpenGL buffer name (GLuint) to register.

  • flags (str or sequence of str, optional) – Registration flags specifying intended usage. Accepted values: "none", "read_only", "write_discard", "surface_load_store", "texture_gather". Multiple flags can be combined by passing a sequence (e.g., ("surface_load_store", "read_only")). Defaults to None (no flags).

  • stream (Stream, optional) –

    If provided, the resource can be used directly as a context manager and it will be mapped on entry:

    with GraphicsResource.from_gl_buffer(vbo, stream=s) as buf:
    view = StridedMemoryView.from_buffer(buf, shape=(256,), dtype=np.float32)

    If omitted, the returned resource can still be used as a context manager to scope registration and automatic cleanup:

    with GraphicsResource.from_gl_buffer(vbo) as resource:
    with resource.map(stream=s) as buf:
        ...

Returns:

A new graphics resource wrapping the registered GL buffer. The returned resource can be used as a context manager. If stream was given, entering maps the resource and yields a Buffer; otherwise entering yields the GraphicsResource itself and closes it on exit.

Return type:

GraphicsResource

Raises:

  • CUDAError – If the registration fails (e.g., no current GL context, invalid buffer name, or operating system error).

  • ValueError – If an unknown flag string is provided.

classmethod from_gl_image(
cls,
int image,
int target,
*,
flags=None,
) → GraphicsResource#

Register an OpenGL texture or renderbuffer for CUDA access.

Parameters:

  • image (int) – The OpenGL texture or renderbuffer name (GLuint) to register.

  • target (int) – The OpenGL target type (e.g., GL_TEXTURE_2D).

  • flags (str or sequence of str, optional) – Registration flags specifying intended usage. Accepted values: "none", "read_only", "write_discard", "surface_load_store", "texture_gather". Multiple flags can be combined by passing a sequence (e.g., ("surface_load_store", "read_only")). Defaults to None (no flags).

Returns:

A new graphics resource wrapping the registered GL image.

Return type:

GraphicsResource

Raises:

  • CUDAError – If the registration fails.

  • ValueError – If an unknown flag string is provided.

map(
self,
*,
Stream stream: Stream | None = None,
) → Buffer#

Map this graphics resource for CUDA access.

After mapping, a CUDA device pointer into the underlying graphics memory is available as a Buffer.

Can be used as a context manager for automatic unmapping:

with resource.map(stream=s) as buf:
    # use buf.handle, buf.size, etc.
# automatically unmapped here
Parameters:

stream (Stream, optional) – The CUDA stream on which to perform the mapping. If None, the current default stream is used.

Returns:

A buffer whose lifetime controls when the graphics resource is unmapped.

Return type:

Buffer

Raises:

  • RuntimeError – If the resource is already mapped or has been closed.

  • CUDAError – If the mapping fails.

unmap(self, *, Stream stream: Stream | None = None)#

Unmap this graphics resource, releasing it back to the graphics API.

After unmapping, the Buffer previously returned by map() must not be used.

Parameters:

stream (Stream, optional) – If provided, overrides the stream that will be used when the mapped buffer is closed. Otherwise the mapping stream is reused.

Raises:

  • RuntimeError – If the resource is not currently mapped or has been closed.

  • CUDAError – If the unmapping fails.

Attributes

handle#

int

The raw CUgraphicsResource handle as a Python int.

Type:

GraphicsResource.handle

is_mapped#

bool

Whether the resource is currently mapped for CUDA access.

Type:

GraphicsResource.is_mapped

resource_handle#

int

Alias for handle.

Type:

GraphicsResource.resource_handle