6.24. Graphics Interoperability
This section describes the graphics interoperability functions of the CUDA runtime application programming interface.
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 )
-
Map graphics resources for access by CUDA.
Parameters
- count
- - Number of resources to map
- resources
- - Resources to map for CUDA
- stream
- - Stream for synchronization
Description
Maps the count graphics resources in resources for access by CUDA.
The resources in resources may be accessed by CUDA until they are unmapped. The graphics API from which resources were registered 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 graphics calls issued before cudaGraphicsMapResources() will complete before any subsequent CUDA work issued in stream begins.
If resources contains any duplicate entries then cudaErrorInvalidResourceHandle is returned. If any of resources are presently mapped for access by CUDA then cudaErrorUnknown is returned.
Note:-
This function uses standard default stream semantics.
-
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:
cudaGraphicsResourceGetMappedPointer, cudaGraphicsSubResourceGetMappedArray, cudaGraphicsUnmapResources, cuGraphicsMapResources
- __host__ cudaError_t cudaGraphicsResourceGetMappedMipmappedArray ( cudaMipmappedArray_t* mipmappedArray, cudaGraphicsResource_t resource )
-
Get a mipmapped array through which to access a mapped graphics resource.
Parameters
- mipmappedArray
- - Returned mipmapped array through which resource may be accessed
- resource
- - Mapped resource to access
Description
Returns in *mipmappedArray a mipmapped array through which the mapped graphics resource resource may be accessed. The value set in mipmappedArray may change every time that resource is mapped.
If resource is not a texture then it cannot be accessed via an array and cudaErrorUnknown is returned. If resource is not mapped then cudaErrorUnknown is returned.
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:
cudaGraphicsResourceGetMappedPointer, cuGraphicsResourceGetMappedMipmappedArray
- __host__ cudaError_t cudaGraphicsResourceGetMappedPointer ( void** devPtr, size_t* size, cudaGraphicsResource_t resource )
-
Get an device pointer through which to access a mapped graphics resource.
Parameters
- devPtr
- - Returned pointer through which resource may be accessed
- size
- - Returned size of the buffer accessible starting at *devPtr
- resource
- - Mapped resource to access
Description
Returns in *devPtr a pointer through which the mapped graphics resource resource may be accessed. Returns in *size the size of the memory in bytes which may be accessed from that pointer. The value set in devPtr may change every time that resource is mapped.
If resource is not a buffer then it cannot be accessed via a pointer and cudaErrorUnknown is returned. If resource is not mapped then cudaErrorUnknown is returned. *
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:
cudaGraphicsMapResources, cudaGraphicsSubResourceGetMappedArray, cuGraphicsResourceGetMappedPointer
- __host__ cudaError_t cudaGraphicsResourceSetMapFlags ( cudaGraphicsResource_t resource, unsigned int flags )
-
Set usage flags for mapping a graphics resource.
Parameters
- resource
- - Registered resource to set flags for
- flags
- - Parameters for resource mapping
Description
Set flags for mapping the graphics resource resource.
Changes to flags will take effect the next time resource is mapped. The flags argument may be any of the following:
-
cudaGraphicsMapFlagsNone: Specifies no hints about how resource will be used. It is therefore assumed that CUDA may read from or write to resource.
-
cudaGraphicsMapFlagsReadOnly: Specifies that CUDA will not write to resource.
-
cudaGraphicsMapFlagsWriteDiscard: Specifies CUDA will not read from resource and will write over the entire contents of resource, so none of the data previously stored in resource will be preserved.
If resource is presently mapped for access by CUDA then cudaErrorUnknown is returned. If flags is not one of the above values then cudaErrorInvalidValue is returned.
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:
- __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.
Parameters
- 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
Description
Returns in *array an array through which the subresource of the mapped graphics resource resource which corresponds to array index arrayIndex and mipmap level mipLevel may be accessed. The value set in array may change every time that resource is mapped.
If resource is not a texture then it cannot be accessed via an array and cudaErrorUnknown is returned. If arrayIndex is not a valid array index for resource then cudaErrorInvalidValue is returned. If mipLevel is not a valid mipmap level for resource then cudaErrorInvalidValue is returned. If resource is not mapped then cudaErrorUnknown is returned.
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:
cudaGraphicsResourceGetMappedPointer, cuGraphicsSubResourceGetMappedArray
- __host__ cudaError_t cudaGraphicsUnmapResources ( int count, cudaGraphicsResource_t* resources, cudaStream_t stream = 0 )
-
Unmap graphics resources.
Parameters
- count
- - Number of resources to unmap
- resources
- - Resources to unmap
- stream
- - Stream for synchronization
Description
Unmaps the count graphics resources in resources.
Once unmapped, the resources in resources may not be accessed by CUDA until they are mapped again.
This function provides the synchronization guarantee that any CUDA work issued in stream before cudaGraphicsUnmapResources() will complete before any subsequently issued graphics work begins.
If resources contains any duplicate entries then cudaErrorInvalidResourceHandle is returned. If any of resources are not presently mapped for access by CUDA then cudaErrorUnknown is returned.
Note:-
This function uses standard default stream semantics.
-
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:
- __host__ cudaError_t cudaGraphicsUnregisterResource ( cudaGraphicsResource_t resource )
-
Unregisters a graphics resource for access by CUDA.
Parameters
- resource
- - Resource to unregister
Description
Unregisters the graphics resource resource so it is not accessible by CUDA unless registered again.
If resource is invalid then cudaErrorInvalidResourceHandle is returned.
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.
-
Use of the handle after this call is undefined behavior.
See also:
cudaGraphicsD3D9RegisterResource, cudaGraphicsD3D10RegisterResource, cudaGraphicsD3D11RegisterResource, cudaGraphicsGLRegisterBuffer, cudaGraphicsGLRegisterImage, cuGraphicsUnregisterResource