CUDA Runtime API :: CUDA Toolkit Documentation

6.26. 图形互操作性

本节介绍CUDA运行时应用程序编程接口的图形互操作性功能。

Functions

__host__ cudaError_t cudaGraphicsMapResources ( int count, cudaGraphicsResource_t* resources, cudaStream_t stream = 0 ): Map graphics resources for access by CUDA.
__host__ cudaError_t cudaGraphicsResourceGetMappedMipmappedArray ( cudaMipmappedArray_t* mipmappedArray, cudaGraphicsResource_t resource ): Get a mipmapped array through which to access a mapped graphics resource.
__host__ cudaError_t cudaGraphicsResourceGetMappedPointer ( void** devPtr, size_t* size, cudaGraphicsResource_t resource ): Get an device pointer through which to access a mapped graphics resource.
__host__ cudaError_t cudaGraphicsResourceSetMapFlags ( cudaGraphicsResource_t resource, unsigned int flags ): Set usage flags for mapping a graphics resource.
__host__ cudaError_t cudaGraphicsSubResourceGetMappedArray ( cudaArray_t* array, cudaGraphicsResource_t resource, unsigned int arrayIndex, unsigned int mipLevel ): Get an array through which to access a subresource of a mapped graphics resource.
__host__ cudaError_t cudaGraphicsUnmapResources ( int count, cudaGraphicsResource_t* resources, cudaStream_t stream = 0 ): Unmap graphics resources.
__host__ cudaError_t cudaGraphicsUnregisterResource ( cudaGraphicsResource_t resource ): Unregisters a graphics resource for access by CUDA.

Functions

__host__ cudaError_t cudaGraphicsMapResources ( int count, cudaGraphicsResource_t* resources, cudaStream_t stream = 0 )

映射图形资源以供CUDA访问。

参数

count: - Number of resources to map
resources: - Resources to map for CUDA
stream: - Stream for synchronization

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorUnknown

描述

映射resources中的count个图形资源以供CUDA访问。

resources中的资源在被取消映射之前，可以被CUDA访问。在CUDA映射期间，注册resources的图形API不应访问任何资源。如果应用程序这样做，结果将是未定义的。

该函数提供同步保证，确保在cudaGraphicsMapResources()之前发出的所有图形调用都已完成，然后才会开始执行在stream中提交的任何后续CUDA工作。

如果resources包含任何重复条目，则返回cudaErrorInvalidResourceHandle。如果resources中的任何资源当前已映射供CUDA访问，则返回cudaErrorUnknown。

Note:

此函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaGraphicsResourceGetMappedPointer, cudaGraphicsSubResourceGetMappedArray, cudaGraphicsUnmapResources, cuGraphicsMapResources

__host__ cudaError_t cudaGraphicsResourceGetMappedMipmappedArray ( cudaMipmappedArray_t* mipmappedArray, cudaGraphicsResource_t resource )

获取一个mipmapped数组，用于访问映射的图形资源。

参数

mipmappedArray: - Returned mipmapped array through which resource may be accessed
resource: - Mapped resource to access

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

描述

在*mipmappedArray中返回一个mipmapped数组，通过该数组可以访问映射的图形资源resource。每次映射resource时，mipmappedArray中设置的值可能会发生变化。

如果resource不是纹理(texture)，则无法通过数组访问，并返回cudaErrorUnknown。如果resource未被映射(mapped)，则返回cudaErrorUnknown。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaGraphicsResourceGetMappedPointer, cuGraphicsResourceGetMappedMipmappedArray

__host__ cudaError_t cudaGraphicsResourceGetMappedPointer ( void** devPtr, size_t* size, cudaGraphicsResource_t resource )

获取一个设备指针，用于访问映射的图形资源。

参数

devPtr: - Returned pointer through which resource may be accessed
size: - Returned size of the buffer accessible starting at *devPtr
resource: - Mapped resource to access

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

描述

返回*devPtr指向一个指针，通过该指针可以访问映射的图形资源resource。返回*size表示可从该指针访问的内存大小（以字节为单位）。每次映射resource时，devPtr中设置的值可能会发生变化。

如果resource不是缓冲区，则无法通过指针访问，并返回cudaErrorUnknown。如果resource未被映射，则返回cudaErrorUnknown。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaGraphicsMapResources, cudaGraphicsSubResourceGetMappedArray, cuGraphicsResourceGetMappedPointer

__host__ cudaError_t cudaGraphicsResourceSetMapFlags ( cudaGraphicsResource_t resource, unsigned int flags )

设置用于映射图形资源的使用标志。

参数

resource: - Registered resource to set flags for
flags: - Parameters for resource mapping

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown,

描述

设置flags以映射图形资源resource。

对flags的修改将在下次映射resource时生效。flags参数可以是以下任意一种：

cudaGraphicsMapFlagsNone: 指定不提供关于resource使用方式的任何提示。因此假定CUDA可能会读取或写入resource。
cudaGraphicsMapFlagsReadOnly: 指定CUDA不会写入resource。
cudaGraphicsMapFlagsWriteDiscard: 指定CUDA不会从resource读取数据，而是会覆盖resource的全部内容，因此之前存储在resource中的所有数据都不会保留。

如果resource当前已映射供CUDA访问，则返回cudaErrorUnknown。如果flags不是上述值之一，则返回cudaErrorInvalidValue。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaGraphicsMapResources, cuGraphicsResourceSetMapFlags

__host__ cudaError_t cudaGraphicsSubResourceGetMappedArray ( cudaArray_t* array, cudaGraphicsResource_t resource, unsigned int arrayIndex, unsigned int mipLevel )

获取一个数组，用于访问映射图形资源的子资源。

参数

array: - Returned array through which a subresource of resource may be accessed
resource: - Mapped resource to access
arrayIndex: - Array index for array textures or cubemap face index as defined by cudaGraphicsCubeFace for cubemap textures for the subresource to access
mipLevel: - Mipmap level for the subresource to access

cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidResourceHandle, cudaErrorUnknown

描述

在*array中返回一个数组，通过该数组可以访问映射图形资源resource的子资源，该子资源对应于数组索引arrayIndex和mipmap级别mipLevel。每次映射resource时，array中设置的值可能会发生变化。

如果resource不是纹理，则无法通过数组访问，并返回cudaErrorUnknown。如果arrayIndex不是resource的有效数组索引，则返回cudaErrorInvalidValue。如果mipLevel不是resource的有效mipmap级别，则返回cudaErrorInvalidValue。如果resource未被映射，则返回cudaErrorUnknown。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaGraphicsResourceGetMappedPointer, cuGraphicsSubResourceGetMappedArray

__host__ cudaError_t cudaGraphicsUnmapResources ( int count, cudaGraphicsResource_t* resources, cudaStream_t stream = 0 )

解除图形资源映射。

参数

count: - Number of resources to unmap
resources: - Resources to unmap
stream: - Stream for synchronization

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorUnknown

描述

解除映射resources中的count个图形资源。

一旦解除映射，resources中的资源在重新映射之前将无法被CUDA访问。

此函数提供同步保证，确保在cudaGraphicsUnmapResources()之前通过stream发出的任何CUDA工作都将在后续图形工作开始前完成。

如果resources包含任何重复条目，则返回cudaErrorInvalidResourceHandle。如果resources中有任何资源当前未被CUDA映射以供访问，则返回cudaErrorUnknown。

Note:

此函数使用标准的默认流语义。
请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaGraphicsMapResources, cuGraphicsUnmapResources

__host__ cudaError_t cudaGraphicsUnregisterResource ( cudaGraphicsResource_t resource )

注销一个图形资源，使其不再被CUDA访问。

参数

resource: - Resource to unregister

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorUnknown

描述

注销图形资源resource，使其无法被CUDA访问，除非重新注册。

如果resource无效，则返回cudaErrorInvalidResourceHandle。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
在此调用后使用该句柄将导致未定义行为。

另请参阅：

cudaGraphicsD3D9RegisterResource, cudaGraphicsD3D10RegisterResource, cudaGraphicsD3D11RegisterResource, cudaGraphicsGLRegisterBuffer, cudaGraphicsGLRegisterImage, cuGraphicsUnregisterResource