CUDA Runtime API. API Reference Manual (vRelease Version, January 2024)

Modules

See also:

cuMemAllocAsync, cudaMallocAsync ( C++ API), cudaMallocFromPoolAsync, cudaFreeAsync,

cudaDeviceSetMemPool, cudaDeviceGetDefaultMemPool, cudaDeviceGetMemPool,

cudaMemPoolSetAccess, cudaMemPoolSetAttribute, cudaMemPoolGetAttribute

__host__cudaError_t cudaMallocFromPoolAsync (void

**ptr, size_t size, cudaMemPool_t memPool, cudaStream_t

stream)

Allocates memory from a specified pool with stream ordered semantics.

Parameters

ptr

- Returned device pointer

size

memPool

- The pool to allocate from

stream

- The stream establishing the stream ordering semantic

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorNotSupported, cudaErrorOutOfMemory

Description

Inserts an allocation operation into hStream. A pointer to the allocated memory is returned

immediately in *dptr. The allocation must not be accessed until the the allocation operation completes.

The allocation comes from the specified memory pool.

Note:

‣ The specified memory pool may be from a device different than that of the specified hStream.

‣ Basic stream ordering allows future work submitted into the same stream to use the allocation.

Stream query, stream synchronize, and CUDA events can be used to guarantee that the allocation

operation completes before work submitted in a separate stream runs.

Note:

During stream capture, this function results in the creation of an allocation node. In this case, the

allocation is owned by the graph instead of the memory pool. The memory pool's properties are used to

set the node's creation parameters.

193

Modules

See also:

cuMemAllocFromPoolAsync, cudaMallocAsync ( C++ API), cudaMallocAsync, cudaFreeAsync,

cudaDeviceGetDefaultMemPool, cudaMemPoolCreate, cudaMemPoolSetAccess,

cudaMemPoolSetAttribute

__host__cudaError_t cudaMemPoolCreate

(cudaMemPool_t *memPool, const cudaMemPoolProps

*poolProps)

Creates a memory pool.

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorNotSupported

Description

Creates a CUDA memory pool and returns the handle in pool. The poolProps determines the

properties of the pool such as the backing device and IPC capabilities.

To create a memory pool targeting a specific host NUMA node, applications must set

cudaMemPoolProps::cudaMemLocation::type to cudaMemLocationTypeHostNuma and

cudaMemPoolProps::cudaMemLocation::id must specify the NUMA ID of the host memory

node. Specifying cudaMemLocationTypeHostNumaCurrent or cudaMemLocationTypeHost

as the cudaMemPoolProps::cudaMemLocation::type will result in cudaErrorInvalidValue. By

default, the pool's memory will be accessible from the device it is allocated on. In the case of pools

created with cudaMemLocationTypeHostNuma, their default accessibility will be from the host

CPU. Applications can control the maximum size of the pool by specifying a non-zero value for

cudaMemPoolProps::maxSize. If set to 0, the maximum size of the pool will default to a system

dependent value.

Applications that intend to use CU_MEM_HANDLE_TYPE_FABRIC based memory sharing must

ensure: (1) `nvidia-caps-imex-channels` character device is created by the driver and is listed under /

proc/devices (2) have at least one IMEX channel file accessible by the user launching the application.

When exporter and importer CUDA processes have been granted access to the same IMEX channel,

they can securely share memory.

The IMEX channel security model works on a per user basis. Which means all processes under a user

can share memory if the user has access to a valid IMEX channel. When multi-user isolation is desired,

a separate IMEX channel is required for each user.

These channel files exist in /dev/nvidia-caps-imex-channels/channel* and can be created using standard

OS native calls like mknod on Linux. For example: To create channel0 with the major number from /

194

Modules

proc/devices users can execute the following command: `mknod /dev/nvidia-caps-imex-channels/

channel0 c <major number>=""> 0`

Note:

Specifying cudaMemHandleTypeNone creates a memory pool that will not support IPC.

See also:

cuMemPoolCreate, cudaDeviceSetMemPool, cudaMallocFromPoolAsync,

cudaMemPoolExportToShareableHandle, cudaDeviceGetDefaultMemPool, cudaDeviceGetMemPool

__host__cudaError_t cudaMemPoolDestroy

(cudaMemPool_t memPool)

Destroys the specified memory pool.

Returns

cudaSuccess, cudaErrorInvalidValue

Description

If any pointers obtained from this pool haven't been freed or the pool has free operations that haven't

completed when cudaMemPoolDestroy is invoked, the function will return immediately and the

resources associated with the pool will be released automatically once there are no more outstanding

allocations.

Destroying the current mempool of a device sets the default mempool of that device as the current

mempool for that device.

Note:

A device's default memory pool cannot be destroyed.

See also:

cuMemPoolDestroy, cudaFreeAsync, cudaDeviceSetMemPool, cudaDeviceGetDefaultMemPool,

cudaDeviceGetMemPool, cudaMemPoolCreate

195

Modules

__host__cudaError_t cudaMemPoolExportPointer

(cudaMemPoolPtrExportData *exportData, void *ptr)

Export data to share a memory pool allocation between processes.

Parameters

exportData

ptr

- pointer to memory being exported

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorOutOfMemory

Description

Constructs shareData_out for sharing a specific allocation from an already shared memory pool.

The recipient process can import the allocation with the cudaMemPoolImportPointer api. The data is

not a handle and may be shared through any IPC mechanism.

See also:

cuMemPoolExportPointer, cudaMemPoolExportToShareableHandle,

cudaMemPoolImportFromShareableHandle, cudaMemPoolImportPointer

__host__cudaError_t

cudaMemPoolExportToShareableHandle (void

*shareableHandle, cudaMemPool_t memPool,

cudaMemAllocationHandleType handleType, unsigned int

flags)

Exports a memory pool to the requested handle type.

Parameters

shareableHandle

memPool

handleType

- the type of handle to create

flags

- must be 0

196

Modules

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorOutOfMemory

Description

Given an IPC capable mempool, create an OS handle to share the pool with another

process. A recipient process can convert the shareable handle into a mempool with

cudaMemPoolImportFromShareableHandle. Individual pointers can then be shared with the

cudaMemPoolExportPointer and cudaMemPoolImportPointer APIs. The implementation of what the

shareable handle is and how it can be transferred is defined by the requested handle type.

Note:

: To create an IPC capable mempool, create a mempool with a CUmemAllocationHandleType other than

cudaMemHandleTypeNone.

See also:

cuMemPoolExportToShareableHandle, cudaMemPoolImportFromShareableHandle,

cudaMemPoolExportPointer, cudaMemPoolImportPointer

__host__cudaError_t cudaMemPoolGetAccess

(cudaMemAccessFlags *flags, cudaMemPool_t memPool,

cudaMemLocation *location)

Returns the accessibility of a pool from a device.

Parameters

flags

- the accessibility of the pool from the specified location

memPool

- the pool being queried

location

- the location accessing the pool

Description

Returns the accessibility of the pool's memory from the specified location.

See also:

cuMemPoolGetAccess, cudaMemPoolSetAccess

197

Modules

__host__cudaError_t cudaMemPoolGetAttribute

(cudaMemPool_t memPool, cudaMemPoolAttr attr, void

*value)

Gets attributes of a memory pool.

Parameters

memPool

attr

- The attribute to get

value

- Retrieved value

Returns

cudaSuccess, cudaErrorInvalidValue

Description

Supported attributes are:

‣ cudaMemPoolAttrReleaseThreshold: (value type = cuuint64_t) Amount of reserved memory in

bytes to hold onto before trying to release memory back to the OS. When more than the release

threshold bytes of memory are held by the memory pool, the allocator will try to release memory

back to the OS on the next call to stream, event or context synchronize. (default 0)

‣ cudaMemPoolReuseFollowEventDependencies: (value type = int) Allow cudaMallocAsync to use

memory asynchronously freed in another stream as long as a stream ordering dependency of the

allocating stream on the free action exists. Cuda events and null stream interactions can create the

required stream ordered dependencies. (default enabled)

‣ cudaMemPoolReuseAllowOpportunistic: (value type = int) Allow reuse of already completed frees

when there is no dependency between the free and allocation. (default enabled)

‣ cudaMemPoolReuseAllowInternalDependencies: (value type = int) Allow cudaMallocAsync to

insert new stream dependencies in order to establish the stream ordering required to reuse a piece

of memory released by cudaFreeAsync (default enabled).

‣ cudaMemPoolAttrReservedMemCurrent: (value type = cuuint64_t) Amount of backing memory

currently allocated for the mempool.

‣ cudaMemPoolAttrReservedMemHigh: (value type = cuuint64_t) High watermark of backing

memory allocated for the mempool since the last time it was reset.

‣ cudaMemPoolAttrUsedMemCurrent: (value type = cuuint64_t) Amount of memory from the pool

that is currently in use by the application.

‣ cudaMemPoolAttrUsedMemHigh: (value type = cuuint64_t) High watermark of the amount of

memory from the pool that was in use by the application since the last time it was reset.

198

Modules

Note:

Note that as specified by cudaStreamAddCallback no CUDA function may be called from callback.

cudaErrorNotPermitted may, but is not guaranteed to, be returned as a diagnostic in such case.

See also:

cuMemPoolGetAttribute, cudaMallocAsync, cudaFreeAsync, cudaDeviceGetDefaultMemPool,

cudaDeviceGetMemPool, cudaMemPoolCreate

__host__cudaError_t

cudaMemPoolImportFromShareableHandle

(cudaMemPool_t *memPool, void *shareableHandle,

cudaMemAllocationHandleType handleType, unsigned int

flags)

imports a memory pool from a shared handle.

Parameters

memPool

shareableHandle

handleType

- The type of handle being imported

flags

- must be 0

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorOutOfMemory

Description

Specific allocations can be imported from the imported pool with cudaMemPoolImportPointer.

Note:

Imported memory pools do not support creating new allocations. As such imported memory pools may

not be used in cudaDeviceSetMemPool or cudaMallocFromPoolAsync calls.

See also:

cuMemPoolImportFromShareableHandle, cudaMemPoolExportToShareableHandle,

cudaMemPoolExportPointer, cudaMemPoolImportPointer

199

Modules

__host__cudaError_t cudaMemPoolImportPointer

(void **ptr, cudaMemPool_t memPool,

cudaMemPoolPtrExportData *exportData)

Import a memory pool allocation from another process.

Returns

CUDA_SUCCESS, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_INITIALIZED,

CUDA_ERROR_OUT_OF_MEMORY

Description

Returns in ptr_out a pointer to the imported memory. The imported memory must not be accessed

before the allocation operation completes in the exporting process. The imported memory must be

freed from all importing processes before being freed in the exporting process. The pointer may be

freed with cudaFree or cudaFreeAsync. If cudaFreeAsync is used, the free must be completed on the

importing process before the free operation on the exporting process.

Note:

The cudaFreeAsync api may be used in the exporting process before the cudaFreeAsync operation

completes in its stream as long as the cudaFreeAsync in the exporting process specifies a stream with a

stream dependency on the importing process's cudaFreeAsync.

See also:

cuMemPoolImportPointer, cudaMemPoolExportToShareableHandle,

cudaMemPoolImportFromShareableHandle, cudaMemPoolExportPointer

__host__cudaError_t cudaMemPoolSetAccess

(cudaMemPool_t memPool, const cudaMemAccessDesc

*descList, size_t count)

Controls visibility of pools between devices.

Parameters

memPool

descList

count

- Number of descriptors in the map array.

200

Modules

Returns

cudaSuccess, cudaErrorInvalidValue

Description

See also:

cuMemPoolSetAccess, cudaMemPoolGetAccess, cudaMallocAsync, cudaFreeAsync

__host__cudaError_t cudaMemPoolSetAttribute

(cudaMemPool_t memPool, cudaMemPoolAttr attr, void

*value)

Sets attributes of a memory pool.

Parameters

memPool

attr

- The attribute to modify

value

- Pointer to the value to assign

Returns

cudaSuccess, cudaErrorInvalidValue

Description

Supported attributes are:

‣ cudaMemPoolAttrReleaseThreshold: (value type = cuuint64_t) Amount of reserved memory in

bytes to hold onto before trying to release memory back to the OS. When more than the release

threshold bytes of memory are held by the memory pool, the allocator will try to release memory

back to the OS on the next call to stream, event or context synchronize. (default 0)

‣ cudaMemPoolReuseFollowEventDependencies: (value type = int) Allow cudaMallocAsync to use

memory asynchronously freed in another stream as long as a stream ordering dependency of the

allocating stream on the free action exists. Cuda events and null stream interactions can create the

required stream ordered dependencies. (default enabled)

‣ cudaMemPoolReuseAllowOpportunistic: (value type = int) Allow reuse of already completed frees

when there is no dependency between the free and allocation. (default enabled)

‣ cudaMemPoolReuseAllowInternalDependencies: (value type = int) Allow cudaMallocAsync to

insert new stream dependencies in order to establish the stream ordering required to reuse a piece

of memory released by cudaFreeAsync (default enabled).

201

Modules

‣ cudaMemPoolAttrReservedMemHigh: (value type = cuuint64_t) Reset the high watermark that

tracks the amount of backing memory that was allocated for the memory pool. It is illegal to set

this attribute to a non-zero value.

‣ cudaMemPoolAttrUsedMemHigh: (value type = cuuint64_t) Reset the high watermark that tracks

the amount of used memory that was allocated for the memory pool. It is illegal to set this attribute

to a non-zero value.

Note:

Note that as specified by cudaStreamAddCallback no CUDA function may be called from callback.

cudaErrorNotPermitted may, but is not guaranteed to, be returned as a diagnostic in such case.

See also:

cuMemPoolSetAttribute, cudaMallocAsync, cudaFreeAsync, cudaDeviceGetDefaultMemPool,

cudaDeviceGetMemPool, cudaMemPoolCreate

__host__cudaError_t cudaMemPoolTrimTo

(cudaMemPool_t memPool, size_t minBytesToKeep)

Tries to release memory back to the OS.

Parameters

memPool

minBytesToKeep

- If the pool has less than minBytesToKeep reserved, the TrimTo operation is a no-op. Otherwise

the pool will be guaranteed to have at least minBytesToKeep bytes reserved after the operation.

Returns

cudaSuccess, cudaErrorInvalidValue

Description

Releases memory back to the OS until the pool contains fewer than minBytesToKeep reserved bytes,

or there is no more memory that the allocator can safely release. The allocator cannot release OS

allocations that back outstanding asynchronous allocations. The OS allocations may happen at different

granularity from the user allocations.

Note:

‣

: Allocations that have not been freed count as outstanding.

‣

: Allocations that have been asynchronously freed but whose completion has not been observed on

the host (eg. by a synchronize) can count as outstanding.

202

Modules

Note:

Note that as specified by cudaStreamAddCallback no CUDA function may be called from callback.

cudaErrorNotPermitted may, but is not guaranteed to, be returned as a diagnostic in such case.

See also:

cuMemPoolTrimTo, cudaMallocAsync, cudaFreeAsync, cudaDeviceGetDefaultMemPool,

cudaDeviceGetMemPool, cudaMemPoolCreate

6.14. Unified Addressing

This section describes the unified addressing functions of the CUDA runtime application programming

interface.

Overview

CUDA devices can share a unified address space with the host. For these devices there is no distinction

between a device pointer and a host pointer -- the same pointer value may be used to access memory

from the host program and from a kernel running on the device (with exceptions enumerated below).

Supported Platforms

Whether or not a device supports unified addressing may be queried by calling

cudaGetDeviceProperties() with the device property cudaDeviceProp::unifiedAddressing.

Unified addressing is automatically enabled in 64-bit processes .

Looking Up Information from Pointer Values

It is possible to look up information about the memory which backs a pointer value. For instance, one

may want to know if a pointer points to host or device memory. As another example, in the case of

device memory, one may want to know on which CUDA device the memory resides. These properties

may be queried using the function cudaPointerGetAttributes()

Since pointers are unique, it is not necessary to specify information about the pointers specified to

cudaMemcpy() and other copy functions. The copy direction cudaMemcpyDefault may be used to

specify that the CUDA runtime should infer the location of the pointer from its value.

Automatic Mapping of Host Allocated Host Memory

All host memory allocated through all devices using cudaMallocHost() and cudaHostAlloc() is always

directly accessible from all devices that support unified addressing. This is the case regardless of

whether or not the flags cudaHostAllocPortable and cudaHostAllocMapped are specified.

The pointer value through which allocated host memory may be accessed in kernels on all devices that

support unified addressing is the same as the pointer value through which that memory is accessed

203

Modules

on the host. It is not necessary to call cudaHostGetDevicePointer() to get the device pointer for these

allocations.

Note that this is not the case for memory allocated using the flag cudaHostAllocWriteCombined, as

discussed below.

Direct Access of Peer Memory

Upon enabling direct access from a device that supports unified addressing to another peer device that

supports unified addressing using cudaDeviceEnablePeerAccess() all memory allocated in the peer

device using cudaMalloc() and cudaMallocPitch() will immediately be accessible by the current device.

The device pointer value through which any peer's memory may be accessed in the current device is the

same pointer value through which that memory may be accessed from the peer device.

Exceptions, Disjoint Addressing

Not all memory may be accessed on devices through the same pointer value through which they are

accessed on the host. These exceptions are host memory registered using cudaHostRegister() and host

memory allocated using the flag cudaHostAllocWriteCombined. For these exceptions, there exists a

distinct host and device address for the memory. The device address is guaranteed to not overlap any

valid host pointer range and is guaranteed to have the same value across all devices that support unified

addressing.

This device address may be queried using cudaHostGetDevicePointer() when a device using unified

addressing is current. Either the host or the unified device pointer value may be used to refer to this

memory in cudaMemcpy() and similar functions using the cudaMemcpyDefault memory direction.

__host__cudaError_t cudaPointerGetAttributes

(cudaPointerAttributes *attributes, const void *ptr)

Returns attributes about a specified pointer.

Parameters

attributes

- Attributes for the specified pointer

ptr

- Pointer to get attributes for

Returns

cudaSuccess, cudaErrorInvalidDevice, cudaErrorInvalidValue

Description

Returns in *attributes the attributes of the pointer ptr. If pointer was not allocated in, mapped by

or registered with context supporting unified addressing cudaErrorInvalidValue is returned.

Note:

204

Modules

In CUDA 11.0 forward passing host pointer will return cudaMemoryTypeUnregistered in

cudaPointerAttributes::type and call will return cudaSuccess.

The cudaPointerAttributes structure is defined as:

‎

struct cudaPointerAttributes {

enum cudaMemoryType

type;

int device;

void *devicePointer;

void *hostPointer;

}

In this structure, the individual fields mean

‣ cudaPointerAttributes::type identifies type of memory. It can be cudaMemoryTypeUnregistered

for unregistered host memory, cudaMemoryTypeHost for registered host memory,

cudaMemoryTypeDevice for device memory or cudaMemoryTypeManaged for managed memory.

‣ device is the device against which ptr was allocated. If ptr has memory type

cudaMemoryTypeDevice then this identifies the device on which the memory referred to by ptr

physically resides. If ptr has memory type cudaMemoryTypeHost then this identifies the device

which was current when the allocation was made (and if that device is deinitialized then this

allocation will vanish with that device's state).

‣ devicePointer is the device pointer alias through which the memory referred to by ptr may be

accessed on the current device. If the memory referred to by ptr cannot be accessed directly by

the current device then this is NULL.

‣ hostPointer is the host pointer alias through which the memory referred to by ptr may be accessed

on the host. If the memory referred to by ptr cannot be accessed directly by the host then this is

NULL.

Note:

‣ Note that this function may also return cudaErrorInitializationError, cudaErrorInsufficientDriver or

cudaErrorNoDevice if this call tries to initialize internal CUDA RT state.

‣ Note that as specified by cudaStreamAddCallback no CUDA function may be called from callback.

cudaErrorNotPermitted may, but is not guaranteed to, be returned as a diagnostic in such case.

See also:

cudaGetDeviceCount, cudaGetDevice, cudaSetDevice, cudaChooseDevice, cudaInitDevice,

cuPointerGetAttributes

205

Modules

6.15. Peer Device Memory Access

This section describes the peer device memory access functions of the CUDA runtime application

programming interface.

__host__cudaError_t cudaDeviceCanAccessPeer (int

*canAccessPeer, int device, int peerDevice)

Queries if a device may directly access a peer device's memory.

Parameters

canAccessPeer

- Returned access capability

device

- Device from which allocations on peerDevice are to be directly accessed.

peerDevice

- Device on which the allocations to be directly accessed by device reside.

Returns

cudaSuccess, cudaErrorInvalidDevice

Description

Returns in *canAccessPeer a value of 1 if device device is capable of directly accessing

memory from peerDevice and 0 otherwise. If direct access of peerDevice from device is

possible, then access may be enabled by calling cudaDeviceEnablePeerAccess().

Note:

‣ Note that this function may also return error codes from previous, asynchronous launches.

‣ Note that this function may also return cudaErrorInitializationError, cudaErrorInsufficientDriver or

cudaErrorNoDevice if this call tries to initialize internal CUDA RT state.

‣ Note that as specified by cudaStreamAddCallback no CUDA function may be called from callback.

cudaErrorNotPermitted may, but is not guaranteed to, be returned as a diagnostic in such case.

See also:

cudaDeviceEnablePeerAccess, cudaDeviceDisablePeerAccess, cuDeviceCanAccessPeer

206

Modules

__host__cudaError_t cudaDeviceDisablePeerAccess (int

peerDevice)

Disables direct access to memory allocations on a peer device.

Parameters

peerDevice

- Peer device to disable direct access to

Returns

cudaSuccess, cudaErrorPeerAccessNotEnabled, cudaErrorInvalidDevice

Description

Returns cudaErrorPeerAccessNotEnabled if direct access to memory on peerDevice has not yet

been enabled from the current device.

Note:

‣ Note that this function may also return error codes from previous, asynchronous launches.

‣ Note that this function may also return cudaErrorInitializationError, cudaErrorInsufficientDriver or

cudaErrorNoDevice if this call tries to initialize internal CUDA RT state.

‣ Note that as specified by cudaStreamAddCallback no CUDA function may be called from callback.

cudaErrorNotPermitted may, but is not guaranteed to, be returned as a diagnostic in such case.

See also:

cudaDeviceCanAccessPeer, cudaDeviceEnablePeerAccess, cuCtxDisablePeerAccess

__host__cudaError_t cudaDeviceEnablePeerAccess (int

peerDevice, unsigned int flags)

Enables direct access to memory allocations on a peer device.

Parameters

peerDevice

- Peer device to enable direct access to from the current device

flags

- Reserved for future use and must be set to 0

207

Modules

Returns

cudaSuccess, cudaErrorInvalidDevice, cudaErrorPeerAccessAlreadyEnabled, cudaErrorInvalidValue

Description

On success, all allocations from peerDevice will immediately be accessible by the current device.

They will remain accessible until access is explicitly disabled using cudaDeviceDisablePeerAccess() or

either device is reset using cudaDeviceReset().

Note that access granted by this call is unidirectional and that in order to access memory on the current

device from peerDevice, a separate symmetric call to cudaDeviceEnablePeerAccess() is required.

Note that there are both device-wide and system-wide limitations per system configuration, as noted in

the CUDA Programming Guide under the section "Peer-to-Peer Memory Access".

Returns cudaErrorInvalidDevice if cudaDeviceCanAccessPeer() indicates that the current device

cannot directly access memory from peerDevice.

Returns cudaErrorPeerAccessAlreadyEnabled if direct access of peerDevice from the current

device has already been enabled.

Returns cudaErrorInvalidValue if flags is not 0.

Note:

‣ Note that this function may also return error codes from previous, asynchronous launches.

‣ Note that this function may also return cudaErrorInitializationError, cudaErrorInsufficientDriver or

cudaErrorNoDevice if this call tries to initialize internal CUDA RT state.

‣ Note that as specified by cudaStreamAddCallback no CUDA function may be called from callback.

cudaErrorNotPermitted may, but is not guaranteed to, be returned as a diagnostic in such case.

See also:

cudaDeviceCanAccessPeer, cudaDeviceDisablePeerAccess, cuCtxEnablePeerAccess

6.16. OpenGL Interoperability

This section describes the OpenGL interoperability functions of the CUDA runtime application

programming interface. Note that mapping of OpenGL resources is performed with the graphics API

agnostic, resource mapping interface described in Graphics Interopability.

enum cudaGLDeviceList

CUDA devices corresponding to the current OpenGL context

208

Modules

Values

cudaGLDeviceListAll = 1

The CUDA devices for all GPUs used by the current OpenGL context

cudaGLDeviceListCurrentFrame = 2

The CUDA devices for the GPUs used by the current OpenGL context in its currently rendering

frame

cudaGLDeviceListNextFrame = 3

The CUDA devices for the GPUs to be used by the current OpenGL context in the next frame

__host__cudaError_t cudaGLGetDevices (unsigned int

*pCudaDeviceCount, int *pCudaDevices, unsigned int

cudaDeviceCount, cudaGLDeviceList deviceList)

Gets the CUDA devices associated with the current OpenGL context.

Parameters

pCudaDeviceCount

- Returned number of CUDA devices corresponding to the current OpenGL context

pCudaDevices

- Returned CUDA devices corresponding to the current OpenGL context

cudaDeviceCount

- The size of the output device array pCudaDevices

deviceList

- The set of devices to return. This set may be cudaGLDeviceListAll for all devices,

cudaGLDeviceListCurrentFrame for the devices used to render the current frame (in SLI), or

cudaGLDeviceListNextFrame for the devices used to render the next frame (in SLI).

Returns

cudaSuccess, cudaErrorNoDevice, cudaErrorInvalidGraphicsContext, cudaErrorOperatingSystem,

cudaErrorUnknown

Description

Returns in *pCudaDeviceCount the number of CUDA-compatible devices corresponding to

the current OpenGL context. Also returns in *pCudaDevices at most cudaDeviceCount

of the CUDA-compatible devices corresponding to the current OpenGL context. If any of the

GPUs being used by the current OpenGL context are not CUDA capable then the call will return

cudaErrorNoDevice.

Note:

209

Modules

‣ This function is not supported on Mac OS X.

‣ Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnregisterResource, cudaGraphicsMapResources,

cudaGraphicsSubResourceGetMappedArray, cudaGraphicsResourceGetMappedPointer,

cuGLGetDevices

__host__cudaError_t cudaGraphicsGLRegisterBuffer

(cudaGraphicsResource **resource, GLuint buffer,

unsigned int flags)

Registers an OpenGL buffer object.

Parameters

resource

- Pointer to the returned object handle

buffer

- name of buffer object to be registered

flags

- Register flags

Returns

cudaSuccess, cudaErrorInvalidDevice, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle,

cudaErrorOperatingSystem, cudaErrorUnknown

Description

Registers the buffer object specified by buffer for access by CUDA. A handle to the registered

object is returned as resource. The register flags flags specify the intended usage, as follows:

‣ cudaGraphicsRegisterFlagsNone: Specifies no hints about how this resource will be used. It is

therefore assumed that this resource will be read from and written to by CUDA. This is the default

value.

‣ cudaGraphicsRegisterFlagsReadOnly: Specifies that CUDA will not write to this resource.

‣ cudaGraphicsRegisterFlagsWriteDiscard: Specifies that CUDA will not read from this resource

and will write over the entire contents of the resource, so none of the data previously stored in the

resource will be preserved.

Note:

210

Modules

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnregisterResource, cudaGraphicsMapResources,

cudaGraphicsResourceGetMappedPointer, cuGraphicsGLRegisterBuffer

__host__cudaError_t cudaGraphicsGLRegisterImage

(cudaGraphicsResource **resource, GLuint image,

GLenum target, unsigned int flags)

Parameters

resource

- Pointer to the returned object handle

image

- name of texture or renderbuffer object to be registered

target

- Identifies the type of object specified by image

flags

- Register flags

Returns

cudaSuccess, cudaErrorInvalidDevice, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle,

cudaErrorOperatingSystem, cudaErrorUnknown

Description

Registers the texture or renderbuffer object specified by image for access by CUDA. A handle to the

registered object is returned as resource.

target must match the type of the object, and must be one of GL_TEXTURE_2D,

GL_TEXTURE_RECTANGLE, GL_TEXTURE_CUBE_MAP, GL_TEXTURE_3D,

GL_TEXTURE_2D_ARRAY, or GL_RENDERBUFFER.

The register flags flags specify the intended usage, as follows:

‣ cudaGraphicsRegisterFlagsNone: Specifies no hints about how this resource will be used. It is

therefore assumed that this resource will be read from and written to by CUDA. This is the default

value.

‣ cudaGraphicsRegisterFlagsReadOnly: Specifies that CUDA will not write to this resource.

211

Modules

‣ cudaGraphicsRegisterFlagsWriteDiscard: Specifies that CUDA will not read from this resource

and will write over the entire contents of the resource, so none of the data previously stored in the

resource will be preserved.

‣ cudaGraphicsRegisterFlagsSurfaceLoadStore: Specifies that CUDA will bind this resource to a

surface reference.

‣ cudaGraphicsRegisterFlagsTextureGather: Specifies that CUDA will perform texture gather

operations on this resource.

The following image formats are supported. For brevity's sake, the list is abbreviated. For ex.,

{GL_R, GL_RG} X {8, 16} would expand to the following 4 formats {GL_R8, GL_R16, GL_RG8,

GL_RG16} :

‣ GL_RED, GL_RG, GL_RGBA, GL_LUMINANCE, GL_ALPHA, GL_LUMINANCE_ALPHA,

GL_INTENSITY

‣ {GL_R, GL_RG, GL_RGBA} X {8, 16, 16F, 32F, 8UI, 16UI, 32UI, 8I, 16I, 32I}

‣ {GL_LUMINANCE, GL_ALPHA, GL_LUMINANCE_ALPHA, GL_INTENSITY} X {8, 16,

16F_ARB, 32F_ARB, 8UI_EXT, 16UI_EXT, 32UI_EXT, 8I_EXT, 16I_EXT, 32I_EXT}

The following image classes are currently disallowed:

‣ Textures with borders

‣ Multisampled renderbuffers

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnregisterResource, cudaGraphicsMapResources,

cudaGraphicsSubResourceGetMappedArray, cuGraphicsGLRegisterImage

__host__cudaError_t cudaWGLGetDevice (int *device,

HGPUNV hGpu)

Gets the CUDA device associated with hGpu.

Parameters

device

- Returns the device associated with hGpu, or -1 if hGpu is not a compute device.

hGpu

- Handle to a GPU, as queried via WGL_NV_gpu_affinity

212

Modules

Returns

cudaSuccess

Description

Returns the CUDA device associated with a hGpu, if applicable.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

WGL_NV_gpu_affinity, cuWGLGetDevice

6.17. OpenGL Interoperability

[DEPRECATED]

This section describes deprecated OpenGL interoperability functionality.

enum cudaGLMapFlags

CUDA GL Map Flags

Values

cudaGLMapFlagsNone = 0

Default; Assume resource can be read/written

cudaGLMapFlagsReadOnly = 1

CUDA kernels will not write to this resource

cudaGLMapFlagsWriteDiscard = 2

CUDA kernels will only write to and will not read from this resource

__host__cudaError_t cudaGLMapBufferObject (void

**devPtr, GLuint bufObj)

Maps a buffer object for access by CUDA.

Parameters

devPtr

- Returned device pointer to CUDA object

213

Modules

bufObj

- Buffer object ID to map

Returns

cudaSuccess, cudaErrorMapBufferObjectFailed

Description

Deprecated This function is deprecated as of CUDA 3.0.

Maps the buffer object of ID bufObj into the address space of CUDA and returns in *devPtr the

base pointer of the resulting mapping. The buffer must have previously been registered by calling

cudaGLRegisterBufferObject(). While a buffer is mapped by CUDA, any OpenGL operation which

references the buffer will result in undefined behavior. The OpenGL context used to create the buffer,

or another context from the same share group, must be bound to the current thread when this is called.

All streams in the current thread are synchronized with the current GL context.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsMapResources

__host__cudaError_t cudaGLMapBufferObjectAsync (void

**devPtr, GLuint bufObj, cudaStream_t stream)

Maps a buffer object for access by CUDA.

Parameters

devPtr

- Returned device pointer to CUDA object

bufObj

- Buffer object ID to map

stream

- Stream to synchronize

Returns

cudaSuccess, cudaErrorMapBufferObjectFailed

Description

Deprecated This function is deprecated as of CUDA 3.0.

214

Modules

Maps the buffer object of ID bufObj into the address space of CUDA and returns in *devPtr the

base pointer of the resulting mapping. The buffer must have previously been registered by calling

cudaGLRegisterBufferObject(). While a buffer is mapped by CUDA, any OpenGL operation which

references the buffer will result in undefined behavior. The OpenGL context used to create the buffer,

or another context from the same share group, must be bound to the current thread when this is called.

Stream /p stream is synchronized with the current GL context.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsMapResources

__host__cudaError_t cudaGLRegisterBufferObject (GLuint

bufObj)

Registers a buffer object for access by CUDA.

Parameters

bufObj

- Buffer object ID to register

Returns

cudaSuccess, cudaErrorInitializationError

Description

Deprecated This function is deprecated as of CUDA 3.0.

Registers the buffer object of ID bufObj for access by CUDA. This function must be called before

CUDA can map the buffer object. The OpenGL context used to create the buffer, or another context

from the same share group, must be bound to the current thread when this is called.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsGLRegisterBuffer

215

Modules

__host__cudaError_t cudaGLSetBufferObjectMapFlags

(GLuint bufObj, unsigned int flags)

Set usage flags for mapping an OpenGL buffer.

Parameters

bufObj

- Registered buffer object to set flags for

flags

- Parameters for buffer mapping

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Set flags for mapping the OpenGL buffer bufObj

Changes to flags will take effect the next time bufObj is mapped. The flags argument may be any

of the following:

‣ cudaGLMapFlagsNone: Specifies no hints about how this buffer will be used. It is therefore

assumed that this buffer will be read from and written to by CUDA kernels. This is the default

value.

‣ cudaGLMapFlagsReadOnly: Specifies that CUDA kernels which access this buffer will not write

to the buffer.

‣ cudaGLMapFlagsWriteDiscard: Specifies that CUDA kernels which access this buffer will not

read from the buffer and will write over the entire contents of the buffer, so none of the data

previously stored in the buffer will be preserved.

If bufObj has not been registered for use with CUDA, then cudaErrorInvalidResourceHandle is

returned. If bufObj is presently mapped for access by CUDA, then cudaErrorUnknown is returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsResourceSetMapFlags

216

Modules

__host__cudaError_t cudaGLSetGLDevice (int device)

Sets a CUDA device to use OpenGL interoperability.

Parameters

device

- Device to use for OpenGL interoperability

Returns

cudaSuccess, cudaErrorInvalidDevice, cudaErrorSetOnActiveProcess

Description

Deprecated This function is deprecated as of CUDA 5.0.

This function is deprecated and should no longer be used. It is no longer necessary to associate a

CUDA device with an OpenGL context in order to achieve maximum interoperability performance.

This function will immediately initialize the primary context on device if needed.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsGLRegisterBuffer, cudaGraphicsGLRegisterImage

__host__cudaError_t cudaGLUnmapBufferObject (GLuint

bufObj)

Unmaps a buffer object for access by CUDA.

Parameters

bufObj

- Buffer object to unmap

Returns

cudaSuccess, cudaErrorUnmapBufferObjectFailed

Description

Deprecated This function is deprecated as of CUDA 3.0.

217

Modules

Unmaps the buffer object of ID bufObj for access by CUDA. When a buffer is unmapped, the base

address returned by cudaGLMapBufferObject() is invalid and subsequent references to the address

result in undefined behavior. The OpenGL context used to create the buffer, or another context from

the same share group, must be bound to the current thread when this is called.

All streams in the current thread are synchronized with the current GL context.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnmapResources

__host__cudaError_t cudaGLUnmapBufferObjectAsync

(GLuint bufObj, cudaStream_t stream)

Unmaps a buffer object for access by CUDA.

Parameters

bufObj

- Buffer object to unmap

stream

- Stream to synchronize

Returns

cudaSuccess, cudaErrorUnmapBufferObjectFailed

Description

Deprecated This function is deprecated as of CUDA 3.0.

Unmaps the buffer object of ID bufObj for access by CUDA. When a buffer is unmapped, the base

address returned by cudaGLMapBufferObject() is invalid and subsequent references to the address

result in undefined behavior. The OpenGL context used to create the buffer, or another context from

the same share group, must be bound to the current thread when this is called.

Stream /p stream is synchronized with the current GL context.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

218

Modules

cudaGraphicsUnmapResources

__host__cudaError_t cudaGLUnregisterBufferObject

(GLuint bufObj)

Unregisters a buffer object for access by CUDA.

Parameters

bufObj

- Buffer object to unregister

Returns

cudaSuccess

Description

Deprecated This function is deprecated as of CUDA 3.0.

Unregisters the buffer object of ID bufObj for access by CUDA and releases any CUDA resources

associated with the buffer. Once a buffer is unregistered, it may no longer be mapped by CUDA. The

GL context used to create the buffer, or another context from the same share group, must be bound to

the current thread when this is called.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnregisterResource

6.18. Direct3D 9 Interoperability

This section describes the Direct3D 9 interoperability functions of the CUDA runtime application

programming interface. Note that mapping of Direct3D 9 resources is performed with the graphics API

agnostic, resource mapping interface described in Graphics Interopability.

enum cudaD3D9DeviceList

CUDA devices corresponding to a D3D9 device

219

Modules

Values

cudaD3D9DeviceListAll = 1

The CUDA devices for all GPUs used by a D3D9 device

cudaD3D9DeviceListCurrentFrame = 2

The CUDA devices for the GPUs used by a D3D9 device in its currently rendering frame

cudaD3D9DeviceListNextFrame = 3

The CUDA devices for the GPUs to be used by a D3D9 device in the next frame

__host__cudaError_t cudaD3D9GetDevice (int *device,

const char *pszAdapterName)

Gets the device number for an adapter.

Parameters

device

- Returns the device corresponding to pszAdapterName

pszAdapterName

- D3D9 adapter to get device for

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

Description

Returns in *device the CUDA-compatible device corresponding to the adapter name

pszAdapterName obtained from EnumDisplayDevices or IDirect3D9::GetAdapterIdentifier(). If no

device on the adapter with name pszAdapterName is CUDA-compatible then the call will fail.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaD3D9SetDirect3DDevice, cudaGraphicsD3D9RegisterResource, cuD3D9GetDevice

220

Modules

__host__cudaError_t cudaD3D9GetDevices (unsigned

int *pCudaDeviceCount, int *pCudaDevices, unsigned

int cudaDeviceCount, IDirect3DDevice9 *pD3D9Device,

cudaD3D9DeviceList deviceList)

Gets the CUDA devices corresponding to a Direct3D 9 device.

Parameters

pCudaDeviceCount

- Returned number of CUDA devices corresponding to pD3D9Device

pCudaDevices

- Returned CUDA devices corresponding to pD3D9Device

cudaDeviceCount

- The size of the output device array pCudaDevices

pD3D9Device

- Direct3D 9 device to query for CUDA devices

deviceList

- The set of devices to return. This set may be cudaD3D9DeviceListAll for all devices,

cudaD3D9DeviceListCurrentFrame for the devices used to render the current frame (in SLI), or

cudaD3D9DeviceListNextFrame for the devices used to render the next frame (in SLI).

Returns

cudaSuccess, cudaErrorNoDevice, cudaErrorUnknown

Description

Returns in *pCudaDeviceCount the number of CUDA-compatible devices corresponding to the

Direct3D 9 device pD3D9Device. Also returns in *pCudaDevices at most cudaDeviceCount

of the the CUDA-compatible devices corresponding to the Direct3D 9 device pD3D9Device.

If any of the GPUs being used to render pDevice are not CUDA capable then the call will return

cudaErrorNoDevice.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnregisterResource, cudaGraphicsMapResources,

cudaGraphicsSubResourceGetMappedArray, cudaGraphicsResourceGetMappedPointer,

cuD3D9GetDevices

221

Modules

__host__cudaError_t cudaD3D9GetDirect3DDevice

(IDirect3DDevice9 **ppD3D9Device)

Gets the Direct3D device against which the current CUDA context was created.

Parameters

ppD3D9Device

- Returns the Direct3D device for this thread

Returns

cudaSuccess, cudaErrorInvalidGraphicsContext, cudaErrorUnknown

Description

Returns in *ppD3D9Device the Direct3D device against which this CUDA context was created in

cudaD3D9SetDirect3DDevice().

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaD3D9SetDirect3DDevice, cuD3D9GetDirect3DDevice

__host__cudaError_t cudaD3D9SetDirect3DDevice

(IDirect3DDevice9 *pD3D9Device, int device)

Sets the Direct3D 9 device to use for interoperability with a CUDA device.

Parameters

pD3D9Device

- Direct3D device to use for this thread

device

- The CUDA device to use. This device must be among the devices returned when querying

cudaD3D9DeviceListAll from cudaD3D9GetDevices, may be set to -1 to automatically select an

appropriate CUDA device.

Returns

cudaSuccess, cudaErrorInitializationError, cudaErrorInvalidValue, cudaErrorSetOnActiveProcess

222

Modules

Description

Records pD3D9Device as the Direct3D 9 device to use for Direct3D 9 interoperability with the

CUDA device device and sets device as the current device for the calling host thread.

This function will immediately initialize the primary context on device if needed.

If device has already been initialized then this call will fail with the error

cudaErrorSetOnActiveProcess. In this case it is necessary to reset device using cudaDeviceReset()

before Direct3D 9 interoperability on device may be enabled.

Successfully initializing CUDA interoperability with pD3D9Device will increase the internal

reference count on pD3D9Device. This reference count will be decremented when device is reset

using cudaDeviceReset().

Note that this function is never required for correct functionality. Use of this function will result in

accelerated interoperability only when the operating system is Windows Vista or Windows 7, and the

device pD3DDdevice is not an IDirect3DDevice9Ex. In all other cirumstances, this function is not

necessary.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaD3D9GetDevice, cudaGraphicsD3D9RegisterResource, cudaDeviceReset

__host__cudaError_t cudaGraphicsD3D9RegisterResource

(cudaGraphicsResource **resource, IDirect3DResource9

*pD3DResource, unsigned int flags)

Parameters

resource

- Pointer to returned resource handle

pD3DResource

- Direct3D resource to register

flags

- Parameters for resource registration

223

Modules

Returns

cudaSuccess, cudaErrorInvalidDevice, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle,

cudaErrorUnknown

Description

Registers the Direct3D 9 resource pD3DResource for access by CUDA.

If this call is successful then the application will be able to map and unmap this resource until it is

unregistered through cudaGraphicsUnregisterResource(). Also on success, this call will increase the

internal reference count on pD3DResource. This reference count will be decremented when this

resource is unregistered through cudaGraphicsUnregisterResource().

This call potentially has a high-overhead and should not be called every frame in interactive

applications.

The type of pD3DResource must be one of the following.

‣ IDirect3DVertexBuffer9: may be accessed through a device pointer

‣ IDirect3DIndexBuffer9: may be accessed through a device pointer

‣ IDirect3DSurface9: may be accessed through an array. Only stand-alone objects of type

IDirect3DSurface9 may be explicitly shared. In particular, individual mipmap levels and faces of

cube maps may not be registered directly. To access individual surfaces associated with a texture,

one must register the base texture object.

‣ IDirect3DBaseTexture9: individual surfaces on this texture may be accessed through an array.

The flags argument may be used to specify additional parameters at register time. The valid values

for this parameter are

‣ cudaGraphicsRegisterFlagsNone: Specifies no hints about how this resource will be used.

‣ cudaGraphicsRegisterFlagsSurfaceLoadStore: Specifies that CUDA will bind this resource to a

surface reference.

‣ cudaGraphicsRegisterFlagsTextureGather: Specifies that CUDA will perform texture gather

operations on this resource.

Not all Direct3D resources of the above types may be used for interoperability with CUDA. The

following are some limitations.

‣ The primary rendertarget may not be registered with CUDA.

‣ Resources allocated as shared may not be registered with CUDA.

‣ Textures which are not of a format which is 1, 2, or 4 channels of 8, 16, or 32-bit integer or

floating-point data cannot be shared.

‣ Surfaces of depth or stencil formats cannot be shared.

A complete list of supported formats is as follows:

‣ D3DFMT_L8

224

Modules

‣ D3DFMT_L16

‣ D3DFMT_A8R8G8B8

‣ D3DFMT_X8R8G8B8

‣ D3DFMT_G16R16

‣ D3DFMT_A8B8G8R8

‣ D3DFMT_A8

‣ D3DFMT_A8L8

‣ D3DFMT_Q8W8V8U8

‣ D3DFMT_V16U16

‣ D3DFMT_A16B16G16R16F

‣ D3DFMT_A16B16G16R16

‣ D3DFMT_R32F

‣ D3DFMT_G16R16F

‣ D3DFMT_A32B32G32R32F

‣ D3DFMT_G32R32F

‣ D3DFMT_R16F

If pD3DResource is of incorrect type or is already registered, then cudaErrorInvalidResourceHandle

is returned. If pD3DResource cannot be registered, then cudaErrorUnknown is returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaD3D9SetDirect3DDevice, cudaGraphicsUnregisterResource, cudaGraphicsMapResources,

cudaGraphicsSubResourceGetMappedArray, cudaGraphicsResourceGetMappedPointer,

cuGraphicsD3D9RegisterResource

6.19. Direct3D 9 Interoperability

[DEPRECATED]

This section describes deprecated Direct3D 9 interoperability functions.

enum cudaD3D9MapFlags

CUDA D3D9 Map Flags

225

Modules

Values

cudaD3D9MapFlagsNone = 0

Default; Assume resource can be read/written

cudaD3D9MapFlagsReadOnly = 1

CUDA kernels will not write to this resource

cudaD3D9MapFlagsWriteDiscard = 2

CUDA kernels will only write to and will not read from this resource

enum cudaD3D9RegisterFlags

CUDA D3D9 Register Flags

Values

cudaD3D9RegisterFlagsNone = 0

Default; Resource can be accessed througa void*

cudaD3D9RegisterFlagsArray = 1

Resource can be accessed through a CUarray*

__host__cudaError_t cudaD3D9MapResources (int count,

IDirect3DResource9 **ppResources)

Map Direct3D resources for access by CUDA.

Parameters

count

- Number of resources to map for CUDA

ppResources

- Resources to map for CUDA

Returns

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Maps the count Direct3D resources in ppResources for access by CUDA.

The resources in ppResources may be accessed in CUDA kernels until they are unmapped.

Direct3D should not access any resources while they are mapped by CUDA. If an application does so,

the results are undefined.

226

Modules

This function provides the synchronization guarantee that any Direct3D calls issued

before cudaD3D9MapResources() will complete before any CUDA kernels issued after

cudaD3D9MapResources() begin.

If any of ppResources have not been registered for use with CUDA or if ppResources contains

any duplicate entries then cudaErrorInvalidResourceHandle is returned. If any of ppResources are

presently mapped for access by CUDA then cudaErrorUnknown is returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsMapResources

__host__cudaError_t cudaD3D9RegisterResource

(IDirect3DResource9 *pResource, unsigned int flags)

Registers a Direct3D resource for access by CUDA.

Parameters

pResource

- Resource to register

flags

- Parameters for resource registration

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Registers the Direct3D resource pResource for access by CUDA.

If this call is successful, then the application will be able to map and unmap this resource until it is

unregistered through cudaD3D9UnregisterResource(). Also on success, this call will increase the

internal reference count on pResource. This reference count will be decremented when this resource

is unregistered through cudaD3D9UnregisterResource().

This call potentially has a high-overhead and should not be called every frame in interactive

applications.

The type of pResource must be one of the following.

‣ IDirect3DVertexBuffer9: No notes.

227

Modules

‣ IDirect3DIndexBuffer9: No notes.

‣ IDirect3DSurface9: Only stand-alone objects of type IDirect3DSurface9 may be explicitly shared.

In particular, individual mipmap levels and faces of cube maps may not be registered directly. To

access individual surfaces associated with a texture, one must register the base texture object.

‣ IDirect3DBaseTexture9: When a texture is registered, all surfaces associated with all mipmap

levels of all faces of the texture will be accessible to CUDA.

The flags argument specifies the mechanism through which CUDA will access the Direct3D

resource. The following value is allowed:

‣ cudaD3D9RegisterFlagsNone: Specifies that CUDA will access this resource through a

void*. The pointer, size, and pitch for each subresource of this resource may be queried

through cudaD3D9ResourceGetMappedPointer(), cudaD3D9ResourceGetMappedSize(), and

cudaD3D9ResourceGetMappedPitch() respectively. This option is valid for all resource types.

Not all Direct3D resources of the above types may be used for interoperability with CUDA. The

following are some limitations:

‣ The primary rendertarget may not be registered with CUDA.

‣ Resources allocated as shared may not be registered with CUDA.

‣ Any resources allocated in D3DPOOL_SYSTEMMEM or D3DPOOL_MANAGED may not be

registered with CUDA.

‣ Textures which are not of a format which is 1, 2, or 4 channels of 8, 16, or 32-bit integer or

floating-point data cannot be shared.

‣ Surfaces of depth or stencil formats cannot be shared.

If Direct3D interoperability is not initialized on this context, then cudaErrorInvalidDevice is returned.

If pResource is of incorrect type (e.g, is a non-stand-alone IDirect3DSurface9) or is already

registered, then cudaErrorInvalidResourceHandle is returned. If pResource cannot be registered then

cudaErrorUnknown is returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsD3D9RegisterResource

228

Modules

__host__cudaError_t cudaD3D9ResourceGetMappedArray

(cudaArray **ppArray, IDirect3DResource9 *pResource,

unsigned int face, unsigned int level)

Get an array through which to access a subresource of a Direct3D resource which has been mapped for

access by CUDA.

Parameters

ppArray

- Returned array corresponding to subresource

pResource

- Mapped resource to access

face

- Face of resource to access

level

- Level of resource to access

Returns

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Returns in *pArray an array through which the subresource of the mapped Direct3D resource

pResource, which corresponds to face and level may be accessed. The value set in pArray

may change every time that pResource is mapped.

If pResource is not registered then cudaErrorInvalidResourceHandle is returned. If

pResource was not registered with usage flags cudaD3D9RegisterFlagsArray, then

cudaErrorInvalidResourceHandle is returned. If pResource is not mapped, then cudaErrorUnknown

is returned.

For usage requirements of face and level parameters, see cudaD3D9ResourceGetMappedPointer().

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsSubResourceGetMappedArray

229

Modules

__host__cudaError_t cudaD3D9ResourceGetMappedPitch

(size_t *pPitch, size_t *pPitchSlice, IDirect3DResource9

*pResource, unsigned int face, unsigned int level)

Get the pitch of a subresource of a Direct3D resource which has been mapped for access by CUDA.

Parameters

pPitch

- Returned pitch of subresource

pPitchSlice

- Returned Z-slice pitch of subresource

pResource

- Mapped resource to access

face

- Face of resource to access

level

- Level of resource to access

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Returns in *pPitch and *pPitchSlice the pitch and Z-slice pitch of the subresource of the

mapped Direct3D resource pResource, which corresponds to face and level. The values set in

pPitch and pPitchSlice may change every time that pResource is mapped.

The pitch and Z-slice pitch values may be used to compute the location of a sample on a surface as

follows.

For a 2D surface, the byte offset of the sample at position x, y from the base pointer of the surface is:

y * pitch + (bytes per pixel) * x

For a 3D surface, the byte offset of the sample at position x, y, z from the base pointer of the surface is:

z* slicePitch + y * pitch + (bytes per pixel) * x

Both parameters pPitch and pPitchSlice are optional and may be set to NULL.

If pResource is not of type IDirect3DBaseTexture9 or one of its sub-types or if pResource

has not been registered for use with CUDA, then cudaErrorInvalidResourceHandle is returned.

If pResource was not registered with usage flags cudaD3D9RegisterFlagsNone, then

cudaErrorInvalidResourceHandle is returned. If pResource is not mapped for access by CUDA then

cudaErrorUnknown is returned.

230

Modules

For usage requirements of face and level parameters, see cudaD3D9ResourceGetMappedPointer().

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsResourceGetMappedPointer

__host__cudaError_t

cudaD3D9ResourceGetMappedPointer (void **pPointer,

IDirect3DResource9 *pResource, unsigned int face,

unsigned int level)

Get a pointer through which to access a subresource of a Direct3D resource which has been mapped for

access by CUDA.

Parameters

pPointer

- Returned pointer corresponding to subresource

pResource

- Mapped resource to access

face

- Face of resource to access

level

- Level of resource to access

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Returns in *pPointer the base pointer of the subresource of the mapped Direct3D resource

pResource, which corresponds to face and level. The value set in pPointer may change every

time that pResource is mapped.

If pResource is not registered, then cudaErrorInvalidResourceHandle is returned. If

pResource was not registered with usage flags cudaD3D9RegisterFlagsNone, then

cudaErrorInvalidResourceHandle is returned. If pResource is not mapped, then cudaErrorUnknown

is returned.

231

Modules

If pResource is of type IDirect3DCubeTexture9, then face must one of the values enumerated

by type D3DCUBEMAP_FACES. For all other types, face must be 0. If face is invalid, then

cudaErrorInvalidValue is returned.

If pResource is of type IDirect3DBaseTexture9, then level must correspond to a valid mipmap

level. Only mipmap level 0 is supported for now. For all other types level must be 0. If level is

invalid, then cudaErrorInvalidValue is returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsResourceGetMappedPointer

__host__cudaError_t cudaD3D9ResourceGetMappedSize

(size_t *pSize, IDirect3DResource9 *pResource, unsigned

int face, unsigned int level)

Get the size of a subresource of a Direct3D resource which has been mapped for access by CUDA.

Parameters

pSize

- Returned size of subresource

pResource

- Mapped resource to access

face

- Face of resource to access

level

- Level of resource to access

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Returns in *pSize the size of the subresource of the mapped Direct3D resource pResource, which

corresponds to face and level. The value set in pSize may change every time that pResource is

mapped.

If pResource has not been registered for use with CUDA then cudaErrorInvalidResourceHandle

is returned. If pResource was not registered with usage flags cudaD3D9RegisterFlagsNone, then

232

Modules

cudaErrorInvalidResourceHandle is returned. If pResource is not mapped for access by CUDA then

cudaErrorUnknown is returned.

For usage requirements of face and level parameters, see cudaD3D9ResourceGetMappedPointer().

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsResourceGetMappedPointer

__host__cudaError_t

cudaD3D9ResourceGetSurfaceDimensions

(size_t *pWidth, size_t *pHeight, size_t *pDepth,

IDirect3DResource9 *pResource, unsigned int face,

unsigned int level)

Get the dimensions of a registered Direct3D surface.

Parameters

pWidth

- Returned width of surface

pHeight

- Returned height of surface

pDepth

- Returned depth of surface

pResource

- Registered resource to access

face

- Face of resource to access

level

- Level of resource to access

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle,

Description

Deprecated This function is deprecated as of CUDA 3.0.

233

Modules

Returns in *pWidth, *pHeight, and *pDepth the dimensions of the subresource of the mapped

Direct3D resource pResource which corresponds to face and level.

Since anti-aliased surfaces may have multiple samples per pixel, it is possible that the dimensions of a

resource will be an integer factor larger than the dimensions reported by the Direct3D runtime.

The parameters pWidth, pHeight, and pDepth are optional. For 2D surfaces, the value returned in

*pDepth will be 0.

If pResource is not of type IDirect3DBaseTexture9 or IDirect3DSurface9 or if pResource has not

been registered for use with CUDA, then cudaErrorInvalidResourceHandle is returned.

For usage requirements of face and level parameters, see cudaD3D9ResourceGetMappedPointer.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsSubResourceGetMappedArray

__host__cudaError_t cudaD3D9ResourceSetMapFlags

(IDirect3DResource9 *pResource, unsigned int flags)

Set usage flags for mapping a Direct3D resource.

Parameters

pResource

- Registered resource to set flags for

flags

- Parameters for resource mapping

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Set flags for mapping the Direct3D resource pResource.

Changes to flags will take effect the next time pResource is mapped. The flags argument may be

any of the following:

‣ cudaD3D9MapFlagsNone: Specifies no hints about how this resource will be used. It is therefore

assumed that this resource will be read from and written to by CUDA kernels. This is the default

value.

234

Modules

‣ cudaD3D9MapFlagsReadOnly: Specifies that CUDA kernels which access this resource will not

write to this resource.

‣ cudaD3D9MapFlagsWriteDiscard: Specifies that CUDA kernels which access this resource will

not read from this resource and will write over the entire contents of the resource, so none of the

data previously stored in the resource will be preserved.

If pResource has not been registered for use with CUDA, then cudaErrorInvalidResourceHandle

is returned. If pResource is presently mapped for access by CUDA, then cudaErrorUnknown is

returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaInteropResourceSetMapFlags

__host__cudaError_t cudaD3D9UnmapResources (int

count, IDirect3DResource9 **ppResources)

Unmap Direct3D resources for access by CUDA.

Parameters

count

- Number of resources to unmap for CUDA

ppResources

- Resources to unmap for CUDA

Returns

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Unmaps the count Direct3D resources in ppResources.

This function provides the synchronization guarantee that any CUDA kernels issued

before cudaD3D9UnmapResources() will complete before any Direct3D calls issued after

cudaD3D9UnmapResources() begin.

If any of ppResources have not been registered for use with CUDA or if ppResources contains

any duplicate entries, then cudaErrorInvalidResourceHandle is returned. If any of ppResources are

not presently mapped for access by CUDA then cudaErrorUnknown is returned.

235

Modules

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnmapResources

__host__cudaError_t cudaD3D9UnregisterResource

(IDirect3DResource9 *pResource)

Unregisters a Direct3D resource for access by CUDA.

Parameters

pResource

- Resource to unregister

Returns

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Unregisters the Direct3D resource pResource so it is not accessible by CUDA unless registered

again.

If pResource is not registered, then cudaErrorInvalidResourceHandle is returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnregisterResource

6.20. Direct3D 10 Interoperability

This section describes the Direct3D 10 interoperability functions of the CUDA runtime application

programming interface. Note that mapping of Direct3D 10 resources is performed with the graphics

API agnostic, resource mapping interface described in Graphics Interopability.

236

Modules

enum cudaD3D10DeviceList

CUDA devices corresponding to a D3D10 device

Values

cudaD3D10DeviceListAll = 1

The CUDA devices for all GPUs used by a D3D10 device

cudaD3D10DeviceListCurrentFrame = 2

The CUDA devices for the GPUs used by a D3D10 device in its currently rendering frame

cudaD3D10DeviceListNextFrame = 3

The CUDA devices for the GPUs to be used by a D3D10 device in the next frame

__host__cudaError_t cudaD3D10GetDevice (int *device,

IDXGIAdapter *pAdapter)

Gets the device number for an adapter.

Parameters

device

- Returns the device corresponding to pAdapter

pAdapter

- D3D10 adapter to get device for

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

Description

Returns in *device the CUDA-compatible device corresponding to the adapter pAdapter obtained

from IDXGIFactory::EnumAdapters. This call will succeed only if a device on adapter pAdapter is

CUDA-compatible.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsD3D10RegisterResource, cuD3D10GetDevice

237

Modules

__host__cudaError_t cudaD3D10GetDevices (unsigned

int *pCudaDeviceCount, int *pCudaDevices, unsigned

int cudaDeviceCount, ID3D10Device *pD3D10Device,

cudaD3D10DeviceList deviceList)

Gets the CUDA devices corresponding to a Direct3D 10 device.

Parameters

pCudaDeviceCount

- Returned number of CUDA devices corresponding to pD3D10Device

pCudaDevices

- Returned CUDA devices corresponding to pD3D10Device

cudaDeviceCount

- The size of the output device array pCudaDevices

pD3D10Device

- Direct3D 10 device to query for CUDA devices

deviceList

- The set of devices to return. This set may be cudaD3D10DeviceListAll for all devices,

cudaD3D10DeviceListCurrentFrame for the devices used to render the current frame (in SLI), or

cudaD3D10DeviceListNextFrame for the devices used to render the next frame (in SLI).

Returns

cudaSuccess, cudaErrorNoDevice, cudaErrorUnknown

Description

Returns in *pCudaDeviceCount the number of CUDA-compatible devices corresponding

to the Direct3D 10 device pD3D10Device. Also returns in *pCudaDevices at most

cudaDeviceCount of the the CUDA-compatible devices corresponding to the Direct3D 10 device

pD3D10Device.

If any of the GPUs being used to render pDevice are not CUDA capable then the call will return

cudaErrorNoDevice.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

238

Modules

cudaGraphicsUnregisterResource, cudaGraphicsMapResources,

cudaGraphicsSubResourceGetMappedArray, cudaGraphicsResourceGetMappedPointer,

cuD3D10GetDevices

__host__cudaError_t

cudaGraphicsD3D10RegisterResource

(cudaGraphicsResource **resource, ID3D10Resource

*pD3DResource, unsigned int flags)

Registers a Direct3D 10 resource for access by CUDA.

Parameters

resource

- Pointer to returned resource handle

pD3DResource

- Direct3D resource to register

flags

- Parameters for resource registration

Returns

cudaSuccess, cudaErrorInvalidDevice, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle,

cudaErrorUnknown

Description

Registers the Direct3D 10 resource pD3DResource for access by CUDA.

If this call is successful, then the application will be able to map and unmap this resource until it is

unregistered through cudaGraphicsUnregisterResource(). Also on success, this call will increase the

internal reference count on pD3DResource. This reference count will be decremented when this

resource is unregistered through cudaGraphicsUnregisterResource().

This call potentially has a high-overhead and should not be called every frame in interactive

applications.

The type of pD3DResource must be one of the following.

‣ ID3D10Buffer: may be accessed via a device pointer

‣ ID3D10Texture1D: individual subresources of the texture may be accessed via arrays

‣ ID3D10Texture2D: individual subresources of the texture may be accessed via arrays

‣ ID3D10Texture3D: individual subresources of the texture may be accessed via arrays

The flags argument may be used to specify additional parameters at register time. The valid values

for this parameter are

239

Modules

‣ cudaGraphicsRegisterFlagsNone: Specifies no hints about how this resource will be used.

‣ cudaGraphicsRegisterFlagsSurfaceLoadStore: Specifies that CUDA will bind this resource to a

surface reference.

‣ cudaGraphicsRegisterFlagsTextureGather: Specifies that CUDA will perform texture gather

operations on this resource.

Not all Direct3D resources of the above types may be used for interoperability with CUDA. The

following are some limitations.

‣ The primary rendertarget may not be registered with CUDA.

‣ Textures which are not of a format which is 1, 2, or 4 channels of 8, 16, or 32-bit integer or

floating-point data cannot be shared.

‣ Surfaces of depth or stencil formats cannot be shared.

A complete list of supported DXGI formats is as follows. For compactness the notation A_{B,C,D}

represents A_B, A_C, and A_D.

‣ DXGI_FORMAT_A8_UNORM

‣ DXGI_FORMAT_B8G8R8A8_UNORM

‣ DXGI_FORMAT_B8G8R8X8_UNORM

‣ DXGI_FORMAT_R16_FLOAT

‣ DXGI_FORMAT_R16G16B16A16_{FLOAT,SINT,SNORM,UINT,UNORM}

‣ DXGI_FORMAT_R16G16_{FLOAT,SINT,SNORM,UINT,UNORM}

‣ DXGI_FORMAT_R16_{SINT,SNORM,UINT,UNORM}

‣ DXGI_FORMAT_R32_FLOAT

‣ DXGI_FORMAT_R32G32B32A32_{FLOAT,SINT,UINT}

‣ DXGI_FORMAT_R32G32_{FLOAT,SINT,UINT}

‣ DXGI_FORMAT_R32_{SINT,UINT}

‣ DXGI_FORMAT_R8G8B8A8_{SINT,SNORM,UINT,UNORM,UNORM_SRGB}

‣ DXGI_FORMAT_R8G8_{SINT,SNORM,UINT,UNORM}

‣ DXGI_FORMAT_R8_{SINT,SNORM,UINT,UNORM}

If pD3DResource is of incorrect type or is already registered, then cudaErrorInvalidResourceHandle

is returned. If pD3DResource cannot be registered, then cudaErrorUnknown is returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

240

Modules

cudaGraphicsUnregisterResource, cudaGraphicsMapResources,

cudaGraphicsSubResourceGetMappedArray, cudaGraphicsResourceGetMappedPointer,

cuGraphicsD3D10RegisterResource

6.21. Direct3D 10 Interoperability

[DEPRECATED]

This section describes deprecated Direct3D 10 interoperability functions.

enum cudaD3D10MapFlags

CUDA D3D10 Map Flags

Values

cudaD3D10MapFlagsNone = 0

Default; Assume resource can be read/written

cudaD3D10MapFlagsReadOnly = 1

CUDA kernels will not write to this resource

cudaD3D10MapFlagsWriteDiscard = 2

CUDA kernels will only write to and will not read from this resource

enum cudaD3D10RegisterFlags

CUDA D3D10 Register Flags

Values

cudaD3D10RegisterFlagsNone = 0

Default; Resource can be accessed through a void*

cudaD3D10RegisterFlagsArray = 1

Resource can be accessed through a CUarray*

__host__cudaError_t cudaD3D10GetDirect3DDevice

(ID3D10Device **ppD3D10Device)

Gets the Direct3D device against which the current CUDA context was created.

Parameters

ppD3D10Device

- Returns the Direct3D device for this thread

241

Modules

Returns

cudaSuccess, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 5.0.

This function is deprecated and should no longer be used. It is no longer necessary to associate a

CUDA device with a D3D10 device in order to achieve maximum interoperability performance.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaD3D10SetDirect3DDevice

__host__cudaError_t cudaD3D10MapResources (int count,

ID3D10Resource **ppResources)

Maps Direct3D Resources for access by CUDA.

Parameters

count

- Number of resources to map for CUDA

ppResources

- Resources to map for CUDA

Returns

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Maps the count Direct3D resources in ppResources for access by CUDA.

The resources in ppResources may be accessed in CUDA kernels until they are unmapped.

Direct3D should not access any resources while they are mapped by CUDA. If an application does so,

the results are undefined.

This function provides the synchronization guarantee that any Direct3D calls issued

before cudaD3D10MapResources() will complete before any CUDA kernels issued after

cudaD3D10MapResources() begin.

242

Modules

If any of ppResources have not been registered for use with CUDA or if ppResources contains

any duplicate entries then cudaErrorInvalidResourceHandle is returned. If any of ppResources are

presently mapped for access by CUDA then cudaErrorUnknown is returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsMapResources

__host__cudaError_t cudaD3D10RegisterResource

(ID3D10Resource *pResource, unsigned int flags)

Registers a Direct3D 10 resource for access by CUDA.

Parameters

pResource

- Resource to register

flags

- Parameters for resource registration

Returns

cudaSuccess, cudaErrorInvalidDevice, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle,

cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Registers the Direct3D resource pResource for access by CUDA.

If this call is successful, then the application will be able to map and unmap this resource until it is

unregistered through cudaD3D10UnregisterResource(). Also on success, this call will increase the

internal reference count on pResource. This reference count will be decremented when this resource

is unregistered through cudaD3D10UnregisterResource().

This call potentially has a high-overhead and should not be called every frame in interactive

applications.

The type of pResource must be one of the following:

‣ ID3D10Buffer: Cannot be used with flags set to cudaD3D10RegisterFlagsArray.

‣ ID3D10Texture1D: No restrictions.

‣ ID3D10Texture2D: No restrictions.

243

Modules

‣ ID3D10Texture3D: No restrictions.

The flags argument specifies the mechanism through which CUDA will access the Direct3D

resource. The following values are allowed.

‣ cudaD3D10RegisterFlagsNone: Specifies that CUDA will access this resource through a

void*. The pointer, size, and pitch for each subresource of this resource may be queried

through cudaD3D10ResourceGetMappedPointer(), cudaD3D10ResourceGetMappedSize(), and

cudaD3D10ResourceGetMappedPitch() respectively. This option is valid for all resource types.

‣ cudaD3D10RegisterFlagsArray: Specifies that CUDA will access this resource through a

CUarray queried on a sub-resource basis through cudaD3D10ResourceGetMappedArray().

This option is only valid for resources of type ID3D10Texture1D, ID3D10Texture2D, and

ID3D10Texture3D.

Not all Direct3D resources of the above types may be used for interoperability with CUDA. The

following are some limitations.

‣ The primary rendertarget may not be registered with CUDA.

‣ Resources allocated as shared may not be registered with CUDA.

‣ Textures which are not of a format which is 1, 2, or 4 channels of 8, 16, or 32-bit integer or

floating-point data cannot be shared.

‣ Surfaces of depth or stencil formats cannot be shared.

If Direct3D interoperability is not initialized on this context then cudaErrorInvalidDevice is returned.

If pResource is of incorrect type or is already registered then cudaErrorInvalidResourceHandle is

returned. If pResource cannot be registered then cudaErrorUnknown is returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsD3D10RegisterResource

244

Modules

__host__cudaError_t

cudaD3D10ResourceGetMappedArray (cudaArray

**ppArray, ID3D10Resource *pResource, unsigned int

subResource)

Gets an array through which to access a subresource of a Direct3D resource which has been mapped

for access by CUDA.

Parameters

ppArray

- Returned array corresponding to subresource

pResource

- Mapped resource to access

subResource

- Subresource of pResource to access

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Returns in *ppArray an array through which the subresource of the mapped Direct3D resource

pResource which corresponds to subResource may be accessed. The value set in ppArray may

change every time that pResource is mapped.

If pResource is not registered, then cudaErrorInvalidResourceHandle is returned. If

pResource was not registered with usage flags cudaD3D10RegisterFlagsArray, then

cudaErrorInvalidResourceHandle is returned. If pResource is not mapped then cudaErrorUnknown

is returned.

For usage requirements of the subResource parameter, see

cudaD3D10ResourceGetMappedPointer().

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsSubResourceGetMappedArray

245

Modules

__host__cudaError_t cudaD3D10ResourceGetMappedPitch

(size_t *pPitch, size_t *pPitchSlice, ID3D10Resource

*pResource, unsigned int subResource)

Gets the pitch of a subresource of a Direct3D resource which has been mapped for access by CUDA.

Parameters

pPitch

- Returned pitch of subresource

pPitchSlice

- Returned Z-slice pitch of subresource

pResource

- Mapped resource to access

subResource

- Subresource of pResource to access

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Returns in *pPitch and *pPitchSlice the pitch and Z-slice pitch of the subresource of the

mapped Direct3D resource pResource, which corresponds to subResource. The values set in

pPitch and pPitchSlice may change every time that pResource is mapped.

The pitch and Z-slice pitch values may be used to compute the location of a sample on a surface as

follows.

For a 2D surface, the byte offset of the sample at position x, y from the base pointer of the surface is:

y * pitch + (bytes per pixel) * x

For a 3D surface, the byte offset of the sample at position x, y, z from the base pointer of the surface is:

z* slicePitch + y * pitch + (bytes per pixel) * x

Both parameters pPitch and pPitchSlice are optional and may be set to NULL.

If pResource is not of type ID3D10Texture1D, ID3D10Texture2D, or ID3D10Texture3D, or if

pResource has not been registered for use with CUDA, then cudaErrorInvalidResourceHandle is

returned. If pResource was not registered with usage flags cudaD3D10RegisterFlagsNone, then

cudaErrorInvalidResourceHandle is returned. If pResource is not mapped for access by CUDA then

cudaErrorUnknown is returned.

For usage requirements of the subResource parameter see

cudaD3D10ResourceGetMappedPointer().

246

Modules

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsSubResourceGetMappedArray

__host__cudaError_t

cudaD3D10ResourceGetMappedPointer (void **pPointer,

ID3D10Resource *pResource, unsigned int subResource)

Gets a pointer through which to access a subresource of a Direct3D resource which has been mapped

for access by CUDA.

Parameters

pPointer

- Returned pointer corresponding to subresource

pResource

- Mapped resource to access

subResource

- Subresource of pResource to access

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Returns in *pPointer the base pointer of the subresource of the mapped Direct3D resource

pResource which corresponds to subResource. The value set in pPointer may change every

time that pResource is mapped.

If pResource is not registered, then cudaErrorInvalidResourceHandle is returned. If

pResource was not registered with usage flags cudaD3D9RegisterFlagsNone, then

cudaErrorInvalidResourceHandle is returned. If pResource is not mapped then cudaErrorUnknown

is returned.

If pResource is of type ID3D10Buffer then subResource must be 0. If pResource is of

any other type, then the value of subResource must come from the subresource calculation in

D3D10CalcSubResource().

247

Modules

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsResourceGetMappedPointer

__host__cudaError_t cudaD3D10ResourceGetMappedSize

(size_t *pSize, ID3D10Resource *pResource, unsigned int

subResource)

Gets the size of a subresource of a Direct3D resource which has been mapped for access by CUDA.

Parameters

pSize

- Returned size of subresource

pResource

- Mapped resource to access

subResource

- Subresource of pResource to access

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Returns in *pSize the size of the subresource of the mapped Direct3D resource pResource which

corresponds to subResource. The value set in pSize may change every time that pResource is

mapped.

If pResource has not been registered for use with CUDA then cudaErrorInvalidHandle is

returned. If pResource was not registered with usage flags cudaD3D10RegisterFlagsNone, then

cudaErrorInvalidResourceHandle is returned. If pResource is not mapped for access by CUDA then

cudaErrorUnknown is returned.

For usage requirements of the subResource parameter see

cudaD3D10ResourceGetMappedPointer().

Note:

Note that this function may also return error codes from previous, asynchronous launches.

248

Modules

See also:

cudaGraphicsResourceGetMappedPointer

__host__cudaError_t

cudaD3D10ResourceGetSurfaceDimensions

(size_t *pWidth, size_t *pHeight, size_t *pDepth,

ID3D10Resource *pResource, unsigned int subResource)

Gets the dimensions of a registered Direct3D surface.

Parameters

pWidth

- Returned width of surface

pHeight

- Returned height of surface

pDepth

- Returned depth of surface

pResource

- Registered resource to access

subResource

- Subresource of pResource to access

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle,

Description

Deprecated This function is deprecated as of CUDA 3.0.

Returns in *pWidth, *pHeight, and *pDepth the dimensions of the subresource of the mapped

Direct3D resource pResource which corresponds to subResource.

Since anti-aliased surfaces may have multiple samples per pixel, it is possible that the dimensions of a

resource will be an integer factor larger than the dimensions reported by the Direct3D runtime.

The parameters pWidth, pHeight, and pDepth are optional. For 2D surfaces, the value returned in

*pDepth will be 0.

If pResource is not of type ID3D10Texture1D, ID3D10Texture2D, or ID3D10Texture3D, or if

pResource has not been registered for use with CUDA, then cudaErrorInvalidHandle is returned.

For usage requirements of subResource parameters see cudaD3D10ResourceGetMappedPointer().

249

Modules

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsSubResourceGetMappedArray

__host__cudaError_t cudaD3D10ResourceSetMapFlags

(ID3D10Resource *pResource, unsigned int flags)

Set usage flags for mapping a Direct3D resource.

Parameters

pResource

- Registered resource to set flags for

flags

- Parameters for resource mapping

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown,

Description

Deprecated This function is deprecated as of CUDA 3.0.

Set usage flags for mapping the Direct3D resource pResource.

Changes to flags will take effect the next time pResource is mapped. The flags argument may be

any of the following:

‣ cudaD3D10MapFlagsNone: Specifies no hints about how this resource will be used. It is therefore

assumed that this resource will be read from and written to by CUDA kernels. This is the default

value.

‣ cudaD3D10MapFlagsReadOnly: Specifies that CUDA kernels which access this resource will not

write to this resource.

‣ cudaD3D10MapFlagsWriteDiscard: Specifies that CUDA kernels which access this resource will

not read from this resource and will write over the entire contents of the resource, so none of the

data previously stored in the resource will be preserved.

If pResource has not been registered for use with CUDA then cudaErrorInvalidHandle is returned. If

pResource is presently mapped for access by CUDA then cudaErrorUnknown is returned.

Note:

250

Modules

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsResourceSetMapFlags

__host__cudaError_t cudaD3D10SetDirect3DDevice

(ID3D10Device *pD3D10Device, int device)

Sets the Direct3D 10 device to use for interoperability with a CUDA device.

Parameters

pD3D10Device

- Direct3D device to use for interoperability

device

- The CUDA device to use. This device must be among the devices returned when querying

cudaD3D10DeviceListAll from cudaD3D10GetDevices, may be set to -1 to automatically select an

appropriate CUDA device.

Returns

cudaSuccess, cudaErrorInitializationError, cudaErrorInvalidValue, cudaErrorSetOnActiveProcess

Description

Deprecated This function is deprecated as of CUDA 5.0.

This function is deprecated and should no longer be used. It is no longer necessary to associate a

CUDA device with a D3D10 device in order to achieve maximum interoperability performance.

This function will immediately initialize the primary context on device if needed.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaD3D10GetDevice, cudaGraphicsD3D10RegisterResource, cudaDeviceReset

251

Modules

__host__cudaError_t cudaD3D10UnmapResources (int

count, ID3D10Resource **ppResources)

Unmaps Direct3D resources.

Parameters

count

- Number of resources to unmap for CUDA

ppResources

- Resources to unmap for CUDA

Returns

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Unmaps the count Direct3D resource in ppResources.

This function provides the synchronization guarantee that any CUDA kernels issued

before cudaD3D10UnmapResources() will complete before any Direct3D calls issued after

cudaD3D10UnmapResources() begin.

If any of ppResources have not been registered for use with CUDA or if ppResources contains

any duplicate entries, then cudaErrorInvalidResourceHandle is returned. If any of ppResources are

not presently mapped for access by CUDA then cudaErrorUnknown is returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnmapResources

__host__cudaError_t cudaD3D10UnregisterResource

(ID3D10Resource *pResource)

Unregisters a Direct3D resource.

Parameters

pResource

- Resource to unregister

252

Modules

Returns

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 3.0.

Unregisters the Direct3D resource resource so it is not accessible by CUDA unless registered again.

If pResource is not registered, then cudaErrorInvalidResourceHandle is returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnregisterResource

6.22. Direct3D 11 Interoperability

This section describes the Direct3D 11 interoperability functions of the CUDA runtime application

programming interface. Note that mapping of Direct3D 11 resources is performed with the graphics

API agnostic, resource mapping interface described in Graphics Interopability.

enum cudaD3D11DeviceList

CUDA devices corresponding to a D3D11 device

Values

cudaD3D11DeviceListAll = 1

The CUDA devices for all GPUs used by a D3D11 device

cudaD3D11DeviceListCurrentFrame = 2

The CUDA devices for the GPUs used by a D3D11 device in its currently rendering frame

cudaD3D11DeviceListNextFrame = 3

The CUDA devices for the GPUs to be used by a D3D11 device in the next frame

253

Modules

__host__cudaError_t cudaD3D11GetDevice (int *device,

IDXGIAdapter *pAdapter)

Gets the device number for an adapter.

Parameters

device

- Returns the device corresponding to pAdapter

pAdapter

- D3D11 adapter to get device for

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

Description

Returns in *device the CUDA-compatible device corresponding to the adapter pAdapter obtained

from IDXGIFactory::EnumAdapters. This call will succeed only if a device on adapter pAdapter is

CUDA-compatible.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnregisterResource, cudaGraphicsMapResources,

cudaGraphicsSubResourceGetMappedArray, cudaGraphicsResourceGetMappedPointer,

cuD3D11GetDevice

__host__cudaError_t cudaD3D11GetDevices (unsigned

int *pCudaDeviceCount, int *pCudaDevices, unsigned

int cudaDeviceCount, ID3D11Device *pD3D11Device,

cudaD3D11DeviceList deviceList)

Gets the CUDA devices corresponding to a Direct3D 11 device.

Parameters

pCudaDeviceCount

- Returned number of CUDA devices corresponding to pD3D11Device

254

Modules

pCudaDevices

- Returned CUDA devices corresponding to pD3D11Device

cudaDeviceCount

- The size of the output device array pCudaDevices

pD3D11Device

- Direct3D 11 device to query for CUDA devices

deviceList

- The set of devices to return. This set may be cudaD3D11DeviceListAll for all devices,

cudaD3D11DeviceListCurrentFrame for the devices used to render the current frame (in SLI), or

cudaD3D11DeviceListNextFrame for the devices used to render the next frame (in SLI).

Returns

cudaSuccess, cudaErrorNoDevice, cudaErrorUnknown

Description

Returns in *pCudaDeviceCount the number of CUDA-compatible devices corresponding

to the Direct3D 11 device pD3D11Device. Also returns in *pCudaDevices at most

cudaDeviceCount of the the CUDA-compatible devices corresponding to the Direct3D 11 device

pD3D11Device.

If any of the GPUs being used to render pDevice are not CUDA capable then the call will return

cudaErrorNoDevice.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnregisterResource, cudaGraphicsMapResources,

cudaGraphicsSubResourceGetMappedArray, cudaGraphicsResourceGetMappedPointer,

cuD3D11GetDevices

255

Modules

__host__cudaError_t

cudaGraphicsD3D11RegisterResource

(cudaGraphicsResource **resource, ID3D11Resource

*pD3DResource, unsigned int flags)

Parameters

resource

- Pointer to returned resource handle

pD3DResource

- Direct3D resource to register

flags

- Parameters for resource registration

Returns

cudaSuccess, cudaErrorInvalidDevice, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle,

cudaErrorUnknown

Description

Registers the Direct3D 11 resource pD3DResource for access by CUDA.

If this call is successful, then the application will be able to map and unmap this resource until it is

unregistered through cudaGraphicsUnregisterResource(). Also on success, this call will increase the

internal reference count on pD3DResource. This reference count will be decremented when this

resource is unregistered through cudaGraphicsUnregisterResource().

This call potentially has a high-overhead and should not be called every frame in interactive

applications.

The type of pD3DResource must be one of the following.

‣ ID3D11Buffer: may be accessed via a device pointer

‣ ID3D11Texture1D: individual subresources of the texture may be accessed via arrays

‣ ID3D11Texture2D: individual subresources of the texture may be accessed via arrays

‣ ID3D11Texture3D: individual subresources of the texture may be accessed via arrays

The flags argument may be used to specify additional parameters at register time. The valid values

for this parameter are

‣ cudaGraphicsRegisterFlagsNone: Specifies no hints about how this resource will be used.

‣ cudaGraphicsRegisterFlagsSurfaceLoadStore: Specifies that CUDA will bind this resource to a

surface reference.

256

Modules

‣ cudaGraphicsRegisterFlagsTextureGather: Specifies that CUDA will perform texture gather

operations on this resource.

Not all Direct3D resources of the above types may be used for interoperability with CUDA. The

following are some limitations.

‣ The primary rendertarget may not be registered with CUDA.

‣ Textures which are not of a format which is 1, 2, or 4 channels of 8, 16, or 32-bit integer or

floating-point data cannot be shared.

‣ Surfaces of depth or stencil formats cannot be shared.

A complete list of supported DXGI formats is as follows. For compactness the notation A_{B,C,D}

represents A_B, A_C, and A_D.

‣ DXGI_FORMAT_A8_UNORM

‣ DXGI_FORMAT_B8G8R8A8_UNORM

‣ DXGI_FORMAT_B8G8R8X8_UNORM

‣ DXGI_FORMAT_R16_FLOAT

‣ DXGI_FORMAT_R16G16B16A16_{FLOAT,SINT,SNORM,UINT,UNORM}

‣ DXGI_FORMAT_R16G16_{FLOAT,SINT,SNORM,UINT,UNORM}

‣ DXGI_FORMAT_R16_{SINT,SNORM,UINT,UNORM}

‣ DXGI_FORMAT_R32_FLOAT

‣ DXGI_FORMAT_R32G32B32A32_{FLOAT,SINT,UINT}

‣ DXGI_FORMAT_R32G32_{FLOAT,SINT,UINT}

‣ DXGI_FORMAT_R32_{SINT,UINT}

‣ DXGI_FORMAT_R8G8B8A8_{SINT,SNORM,UINT,UNORM,UNORM_SRGB}

‣ DXGI_FORMAT_R8G8_{SINT,SNORM,UINT,UNORM}

‣ DXGI_FORMAT_R8_{SINT,SNORM,UINT,UNORM}

If pD3DResource is of incorrect type or is already registered, then cudaErrorInvalidResourceHandle

is returned. If pD3DResource cannot be registered, then cudaErrorUnknown is returned.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsUnregisterResource, cudaGraphicsMapResources,

cudaGraphicsSubResourceGetMappedArray, cudaGraphicsResourceGetMappedPointer,

cuGraphicsD3D11RegisterResource

257

Modules

6.23. Direct3D 11 Interoperability

[DEPRECATED]

This section describes deprecated Direct3D 11 interoperability functions.

__host__cudaError_t cudaD3D11GetDirect3DDevice

(ID3D11Device **ppD3D11Device)

Gets the Direct3D device against which the current CUDA context was created.

Parameters

ppD3D11Device

- Returns the Direct3D device for this thread

Returns

cudaSuccess, cudaErrorUnknown

Description

Deprecated This function is deprecated as of CUDA 5.0.

This function is deprecated and should no longer be used. It is no longer necessary to associate a

CUDA device with a D3D11 device in order to achieve maximum interoperability performance.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaD3D11SetDirect3DDevice

__host__cudaError_t cudaD3D11SetDirect3DDevice

(ID3D11Device *pD3D11Device, int device)

Sets the Direct3D 11 device to use for interoperability with a CUDA device.

Parameters

pD3D11Device

- Direct3D device to use for interoperability

258

Modules

device

- The CUDA device to use. This device must be among the devices returned when querying

cudaD3D11DeviceListAll from cudaD3D11GetDevices, may be set to -1 to automatically select an

appropriate CUDA device.

Returns

cudaSuccess, cudaErrorInitializationError, cudaErrorInvalidValue, cudaErrorSetOnActiveProcess

Description

Deprecated This function is deprecated as of CUDA 5.0.

This function is deprecated and should no longer be used. It is no longer necessary to associate a

CUDA device with a D3D11 device in order to achieve maximum interoperability performance.

This function will immediately initialize the primary context on device if needed.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaD3D11GetDevice, cudaGraphicsD3D11RegisterResource, cudaDeviceReset

6.24. VDPAU Interoperability

This section describes the VDPAU interoperability functions of the CUDA runtime application

programming interface.

__host__cudaError_t

cudaGraphicsVDPAURegisterOutputSurface

(cudaGraphicsResource **resource, VdpOutputSurface

vdpSurface, unsigned int flags)

Parameters

resource

- Pointer to the returned object handle

vdpSurface

- VDPAU object to be registered

259

Modules

flags

- Map flags

Returns

cudaSuccess, cudaErrorInvalidDevice, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle,

cudaErrorUnknown

Description

Registers the VdpOutputSurface specified by vdpSurface for access by CUDA. A handle to the

registered object is returned as resource. The surface's intended usage is specified using flags, as

follows:

‣ cudaGraphicsMapFlagsNone: Specifies no hints about how this resource will be used. It is

therefore assumed that this resource will be read from and written to by CUDA. This is the default

value.

‣ cudaGraphicsMapFlagsReadOnly: Specifies that CUDA will not write to this resource.

‣ cudaGraphicsMapFlagsWriteDiscard: Specifies that CUDA will not read from this resource and

will write over the entire contents of the resource, so none of the data previously stored in the

resource will be preserved.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaVDPAUSetVDPAUDevice, cudaGraphicsUnregisterResource,

cudaGraphicsSubResourceGetMappedArray, cuGraphicsVDPAURegisterOutputSurface

__host__cudaError_t

cudaGraphicsVDPAURegisterVideoSurface

(cudaGraphicsResource **resource, VdpVideoSurface

vdpSurface, unsigned int flags)

Parameters

resource

- Pointer to the returned object handle

vdpSurface

- VDPAU object to be registered

260

Modules

flags

- Map flags

Returns

cudaSuccess, cudaErrorInvalidDevice, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle,

cudaErrorUnknown

Description

Registers the VdpVideoSurface specified by vdpSurface for access by CUDA. A handle to the

registered object is returned as resource. The surface's intended usage is specified using flags, as

follows:

‣ cudaGraphicsMapFlagsNone: Specifies no hints about how this resource will be used. It is

therefore assumed that this resource will be read from and written to by CUDA. This is the default

value.

‣ cudaGraphicsMapFlagsReadOnly: Specifies that CUDA will not write to this resource.

‣ cudaGraphicsMapFlagsWriteDiscard: Specifies that CUDA will not read from this resource and

will write over the entire contents of the resource, so none of the data previously stored in the

resource will be preserved.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaVDPAUSetVDPAUDevice, cudaGraphicsUnregisterResource,

cudaGraphicsSubResourceGetMappedArray, cuGraphicsVDPAURegisterVideoSurface

__host__cudaError_t cudaVDPAUGetDevice (int

*device, VdpDevice vdpDevice, VdpGetProcAddress

*vdpGetProcAddress)

Gets the CUDA device associated with a VdpDevice.

Parameters

device

- Returns the device associated with vdpDevice, or -1 if the device associated with vdpDevice is not

a compute device.

vdpDevice

- A VdpDevice handle

261

Modules

vdpGetProcAddress

- VDPAU's VdpGetProcAddress function pointer

Returns

cudaSuccess

Description

Returns the CUDA device associated with a VdpDevice, if applicable.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaVDPAUSetVDPAUDevice, cuVDPAUGetDevice

__host__cudaError_t cudaVDPAUSetVDPAUDevice

(int device, VdpDevice vdpDevice, VdpGetProcAddress

*vdpGetProcAddress)

Sets a CUDA device to use VDPAU interoperability.

Parameters

device

- Device to use for VDPAU interoperability

vdpDevice

- The VdpDevice to interoperate with

vdpGetProcAddress

- VDPAU's VdpGetProcAddress function pointer

Returns

cudaSuccess, cudaErrorInvalidDevice, cudaErrorSetOnActiveProcess

Description

Records vdpDevice as the VdpDevice for VDPAU interoperability with the CUDA device device

and sets device as the current device for the calling host thread.

This function will immediately initialize the primary context on device if needed.

262

Modules

If device has already been initialized then this call will fail with the error

cudaErrorSetOnActiveProcess. In this case it is necessary to reset device using cudaDeviceReset()

before VDPAU interoperability on device may be enabled.

Note:

Note that this function may also return error codes from previous, asynchronous launches.

See also:

cudaGraphicsVDPAURegisterVideoSurface, cudaGraphicsVDPAURegisterOutputSurface,

cudaDeviceReset

6.25. EGL Interoperability

This section describes the EGL interoperability functions of the CUDA runtime application

programming interface.

__host__cudaError_t

cudaEGLStreamConsumerAcquireFrame

(cudaEglStreamConnection *conn,

cudaGraphicsResource_t *pCudaResource, cudaStream_t

*pStream, unsigned int timeout)

Acquire an image frame from the EGLStream with CUDA as a consumer.

Parameters

conn

- Connection on which to acquire

pCudaResource

- CUDA resource on which the EGLStream frame will be mapped for use.

pStream

- CUDA stream for synchronization and any data migrations implied by

cudaEglResourceLocationFlags.

timeout

- Desired timeout in usec.

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown, cudaErrorLaunchTimeout

263

Modules

Description

Acquire an image frame from EGLStreamKHR. cudaGraphicsResourceGetMappedEglFrame can be

called on pCudaResource to get cudaEglFrame.

See also:

cudaEGLStreamConsumerConnect, cudaEGLStreamConsumerDisconnect,

cudaEGLStreamConsumerReleaseFrame, cuEGLStreamConsumerAcquireFrame

__host__cudaError_t cudaEGLStreamConsumerConnect

(cudaEglStreamConnection *conn, EGLStreamKHR

eglStream)

Connect CUDA to EGLStream as a consumer.

Parameters

conn

- Pointer to the returned connection handle

eglStream

- EGLStreamKHR handle

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

Description

Connect CUDA as a consumer to EGLStreamKHR specified by eglStream.

The EGLStreamKHR is an EGL object that transfers a sequence of image frames from one API to

another.

See also:

cudaEGLStreamConsumerDisconnect, cudaEGLStreamConsumerAcquireFrame,

cudaEGLStreamConsumerReleaseFrame, cuEGLStreamConsumerConnect

264

Modules

__host__cudaError_t

cudaEGLStreamConsumerConnectWithFlags

(cudaEglStreamConnection *conn, EGLStreamKHR

eglStream, unsigned int flags)

Connect CUDA to EGLStream as a consumer with given flags.

Parameters

conn

- Pointer to the returned connection handle

eglStream

- EGLStreamKHR handle

flags

- Flags denote intended location - system or video.

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

Description

Connect CUDA as a consumer to EGLStreamKHR specified by stream with specified flags

defined by cudaEglResourceLocationFlags.

The flags specify whether the consumer wants to access frames from system memory or video memory.

Default is cudaEglResourceLocationVidmem.

See also:

cudaEGLStreamConsumerDisconnect, cudaEGLStreamConsumerAcquireFrame,

cudaEGLStreamConsumerReleaseFrame, cuEGLStreamConsumerConnectWithFlags

__host__cudaError_t cudaEGLStreamConsumerDisconnect

(cudaEglStreamConnection *conn)

Disconnect CUDA as a consumer to EGLStream .

Parameters

conn

- Conection to disconnect.

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

265

Modules

Description

Disconnect CUDA as a consumer to EGLStreamKHR.

See also:

cudaEGLStreamConsumerConnect, cudaEGLStreamConsumerAcquireFrame,

cudaEGLStreamConsumerReleaseFrame, cuEGLStreamConsumerDisconnect

__host__cudaError_t

cudaEGLStreamConsumerReleaseFrame

(cudaEglStreamConnection *conn,

cudaGraphicsResource_t pCudaResource, cudaStream_t

*pStream)

Releases the last frame acquired from the EGLStream.

Parameters

conn

- Connection on which to release

pCudaResource

- CUDA resource whose corresponding frame is to be released

pStream

- CUDA stream on which release will be done.

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

Description

Release the acquired image frame specified by pCudaResource to EGLStreamKHR.

See also:

cudaEGLStreamConsumerConnect, cudaEGLStreamConsumerDisconnect,

cudaEGLStreamConsumerAcquireFrame, cuEGLStreamConsumerReleaseFrame

266

Modules

__host__cudaError_t cudaEGLStreamProducerConnect

(cudaEglStreamConnection *conn, EGLStreamKHR

eglStream, EGLint width, EGLint height)

Connect CUDA to EGLStream as a producer.

Parameters

conn

- Pointer to the returned connection handle

eglStream

- EGLStreamKHR handle

width

- width of the image to be submitted to the stream

height

- height of the image to be submitted to the stream

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

Description

Connect CUDA as a producer to EGLStreamKHR specified by stream.

The EGLStreamKHR is an EGL object that transfers a sequence of image frames from one API to

another.

See also:

cudaEGLStreamProducerDisconnect, cudaEGLStreamProducerPresentFrame,

cudaEGLStreamProducerReturnFrame, cuEGLStreamProducerConnect

__host__cudaError_t cudaEGLStreamProducerDisconnect

(cudaEglStreamConnection *conn)

Disconnect CUDA as a producer to EGLStream .

Parameters

conn

- Conection to disconnect.

Returns

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

267

CUDA Runtime API. API Reference Manual (vRelease Version, January 2024) - page 4