CUDA Runtime API :: CUDA Toolkit Documentation

6.25. EGL互操作性

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

Functions

__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.
__host__ cudaError_t cudaEGLStreamConsumerConnect ( cudaEglStreamConnection* conn, EGLStreamKHR eglStream ): Connect CUDA to EGLStream as a consumer.
__host__ cudaError_t cudaEGLStreamConsumerConnectWithFlags ( cudaEglStreamConnection* conn, EGLStreamKHR eglStream, unsigned int flags ): Connect CUDA to EGLStream as a consumer with given flags.
__host__ cudaError_t cudaEGLStreamConsumerDisconnect ( cudaEglStreamConnection* conn ): Disconnect CUDA as a consumer to EGLStream .
__host__ cudaError_t cudaEGLStreamConsumerReleaseFrame ( cudaEglStreamConnection* conn, cudaGraphicsResource_t pCudaResource, cudaStream_t* pStream ): Releases the last frame acquired from the EGLStream.
__host__ cudaError_t cudaEGLStreamProducerConnect ( cudaEglStreamConnection* conn, EGLStreamKHR eglStream, EGLint width, EGLint height ): Connect CUDA to EGLStream as a producer.
__host__ cudaError_t cudaEGLStreamProducerDisconnect ( cudaEglStreamConnection* conn ): Disconnect CUDA as a producer to EGLStream .
__host__ cudaError_t cudaEGLStreamProducerPresentFrame ( cudaEglStreamConnection* conn, cudaEglFrame eglframe, cudaStream_t* pStream ): Present a CUDA eglFrame to the EGLStream with CUDA as a producer.
__host__ cudaError_t cudaEGLStreamProducerReturnFrame ( cudaEglStreamConnection* conn, cudaEglFrame* eglframe, cudaStream_t* pStream ): Return the CUDA eglFrame to the EGLStream last released by the consumer.
__host__ cudaError_t cudaEventCreateFromEGLSync ( cudaEvent_t* phEvent, EGLSyncKHR eglSync, unsigned int flags ): Creates an event from EGLSync object.
__host__ cudaError_t cudaGraphicsEGLRegisterImage ( cudaGraphicsResource** pCudaResource, EGLImageKHR image, unsigned int flags ): Registers an EGL image.
__host__ cudaError_t cudaGraphicsResourceGetMappedEglFrame ( cudaEglFrame* eglFrame, cudaGraphicsResource_t resource, unsigned int index, unsigned int mipLevel ): Get an eglFrame through which to access a registered EGL graphics resource.

Functions

__host__ cudaError_t cudaEGLStreamConsumerAcquireFrame ( cudaEglStreamConnection* conn, cudaGraphicsResource_t* pCudaResource, cudaStream_t* pStream, unsigned int timeout )

从EGLStream获取图像帧，使用CUDA作为消费者。

参数

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.

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown, cudaErrorLaunchTimeout

描述

从EGLStreamKHR获取图像帧。可以在pCudaResource上调用cudaGraphicsResourceGetMappedEglFrame来获取cudaEglFrame。

另请参阅：

cudaEGLStreamConsumerConnect, cudaEGLStreamConsumerDisconnect, cudaEGLStreamConsumerReleaseFrame, cuEGLStreamConsumerAcquireFrame

__host__ cudaError_t cudaEGLStreamConsumerConnect ( cudaEglStreamConnection* conn, EGLStreamKHR eglStream )

将CUDA连接到EGLStream作为消费者。

参数

conn: - Pointer to the returned connection handle
eglStream: - EGLStreamKHR handle

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

将CUDA作为消费者连接到由eglStream指定的EGLStreamKHR。

EGLStreamKHR是一种EGL对象，用于将一系列图像帧从一个API传输到另一个API。

另请参阅：

cudaEGLStreamConsumerDisconnect, cudaEGLStreamConsumerAcquireFrame, cudaEGLStreamConsumerReleaseFrame, cuEGLStreamConsumerConnect

__host__ cudaError_t cudaEGLStreamConsumerConnectWithFlags ( cudaEglStreamConnection* conn, EGLStreamKHR eglStream, unsigned int flags )

将CUDA作为消费者连接到EGLStream，并使用给定的标志。

参数

conn: - Pointer to the returned connection handle
eglStream: - EGLStreamKHR handle
flags: - Flags denote intended location - system or video.

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

将CUDA作为消费者连接到由stream指定的EGLStreamKHR，并使用cudaEglResourceLocationFlags定义的指定flags。

该标志指定消费者希望从系统内存还是视频内存访问帧。默认为cudaEglResourceLocationVidmem。

另请参阅：

cudaEGLStreamConsumerDisconnect, cudaEGLStreamConsumerAcquireFrame, cudaEGLStreamConsumerReleaseFrame, cuEGLStreamConsumerConnectWithFlags

__host__ cudaError_t cudaEGLStreamConsumerDisconnect ( cudaEglStreamConnection* conn )

断开CUDA作为EGLStream消费者的连接。

参数

conn: - Conection to disconnect.

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

断开CUDA作为EGLStreamKHR消费者的连接。

另请参阅：

cudaEGLStreamConsumerConnect, cudaEGLStreamConsumerAcquireFrame, cudaEGLStreamConsumerReleaseFrame, cuEGLStreamConsumerDisconnect

__host__ cudaError_t cudaEGLStreamConsumerReleaseFrame ( cudaEglStreamConnection* conn, cudaGraphicsResource_t pCudaResource, cudaStream_t* pStream )

释放从EGLStream获取的最后一帧。

参数

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.

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

将pCudaResource指定的已获取图像帧释放回EGLStreamKHR。

另请参阅：

cudaEGLStreamConsumerConnect, cudaEGLStreamConsumerDisconnect, cudaEGLStreamConsumerAcquireFrame, cuEGLStreamConsumerReleaseFrame

__host__ cudaError_t cudaEGLStreamProducerConnect ( cudaEglStreamConnection* conn, EGLStreamKHR eglStream, EGLint width, EGLint height )

将CUDA连接到EGLStream作为生产者。

参数

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

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

将CUDA作为生产者连接到由stream指定的EGLStreamKHR。

EGLStreamKHR是一种EGL对象，用于将一系列图像帧从一个API传输到另一个API。

另请参阅：

cudaEGLStreamProducerDisconnect, cudaEGLStreamProducerPresentFrame, cudaEGLStreamProducerReturnFrame, cuEGLStreamProducerConnect

__host__ cudaError_t cudaEGLStreamProducerDisconnect ( cudaEglStreamConnection* conn )

断开CUDA作为EGLStream生产者的连接。

参数

conn: - Conection to disconnect.

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

断开CUDA作为EGLStreamKHR生产者的连接。

另请参阅：

cudaEGLStreamProducerConnect, cudaEGLStreamProducerPresentFrame, cudaEGLStreamProducerReturnFrame, cuEGLStreamProducerDisconnect

__host__ cudaError_t cudaEGLStreamProducerPresentFrame ( cudaEglStreamConnection* conn, cudaEglFrame eglframe, cudaStream_t* pStream )

将CUDA eglFrame作为生产者呈现给EGLStream。

参数

conn: - Connection on which to present the CUDA array
eglframe: - CUDA Eglstream Proucer Frame handle to be sent to the consumer over EglStream.
pStream: - CUDA stream on which to present the frame.

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

cudaEglFrame的定义如下：

‎ typedef struct cudaEglFrame_st {
           union {
               cudaArray_t            pArray[CUDA_EGL_MAX_PLANES];
               struct cudaPitchedPtr  pPitch[CUDA_EGL_MAX_PLANES];
           } frame;
           cudaEglPlaneDesc planeDesc[CUDA_EGL_MAX_PLANES];
           unsigned int planeCount;
           cudaEglFrameType frameType;
           cudaEglColorFormat eglColorFormat;
       } cudaEglFrame;

对于类型为cudaEglFrameTypePitch的cudaEglFrame，应用程序可以呈现内存分配的子区域。在这种情况下，cudaPitchedPtr::ptr将指定分配中子区域的起始地址，而cudaEglPlaneDesc将指定子区域的维度。

另请参阅：

cudaEGLStreamProducerConnect, cudaEGLStreamProducerDisconnect, cudaEGLStreamProducerReturnFrame, cuEGLStreamProducerPresentFrame

__host__ cudaError_t cudaEGLStreamProducerReturnFrame ( cudaEglStreamConnection* conn, cudaEglFrame* eglframe, cudaStream_t* pStream )

将CUDA eglFrame返回到消费者最后释放的EGLStream。

参数

conn: - Connection on which to present the CUDA array
eglframe: - CUDA Eglstream Proucer Frame handle returned from the consumer over EglStream.
pStream: - CUDA stream on which to return the frame.

cudaSuccess, cudaErrorLaunchTimeout, cudaErrorInvalidValue, cudaErrorUnknown

描述

如果消费者未将帧返回给EGL流，此API可能会返回cudaErrorLaunchTimeout。如果返回超时，应用程序可以重试。

另请参阅：

cudaEGLStreamProducerConnect, cudaEGLStreamProducerDisconnect, cudaEGLStreamProducerPresentFrame, cuEGLStreamProducerReturnFrame

__host__ cudaError_t cudaEventCreateFromEGLSync ( cudaEvent_t* phEvent, EGLSyncKHR eglSync, unsigned int flags )

从EGLSync对象创建事件。

参数

phEvent: - Returns newly created event
eglSync: - Opaque handle to EGLSync object
flags: - Event creation flags

cudaSuccess, cudaErrorInitializationError, cudaErrorInvalidValue, cudaErrorLaunchFailure, cudaErrorMemoryAllocation

描述

从EGLSyncKHR eglSync创建一个事件*phEvent，并通过flags指定标志。有效标志包括：

cudaEventDefault: 默认事件创建标志。
cudaEventBlockingSync: 指定创建的事件应使用阻塞同步方式。使用cudaEventSynchronize()等待以此标志创建的事件的CPU线程将被阻塞，直到该事件实际完成。

cudaEventRecord 和 TimingData 不支持从 EGLSync 创建的事件。

EGLSyncKHR 是一个指向 EGL 同步对象的不透明句柄。typedef void* EGLSyncKHR

另请参阅：

cudaEventQuery, cudaEventSynchronize, cudaEventDestroy

__host__ cudaError_t cudaGraphicsEGLRegisterImage ( cudaGraphicsResource** pCudaResource, EGLImageKHR image, unsigned int flags )

注册一个EGL图像。

参数

pCudaResource: - Pointer to the returned object handle
image: - An EGLImageKHR image which can be used to create target resource.
flags: - Map flags

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorInvalidValue, cudaErrorUnknown

描述

将image指定的EGLImageKHR注册为可供CUDA访问。注册对象的句柄将作为pCudaResource返回。对于已注册的资源，不需要额外的映射/取消映射操作，可以直接在pCudaResource上调用cudaGraphicsResourceGetMappedEglFrame。

应用程序将负责同步对共享对象的访问。应用程序必须确保在将控制权交给CUDA之前，所有访问这些对象的待处理操作都已完成。这可以通过在所有GL上下文上发出并等待glFinish命令来实现（对于OpenGL以及其他API类似）。应用程序还需确保在执行其他API中访问相同内存对象的后续命令之前，已完成的任何对已注册CUDA资源的待处理操作。这可以通过调用cuCtxSynchronize或cuEventSynchronize（推荐）来实现。

表面的预期用途通过flags指定，如下所示：

cudaGraphicsRegisterFlagsNone: 指定该资源的使用方式无任何提示。因此默认假设该资源将被CUDA进行读写操作。此为默认值。
cudaGraphicsRegisterFlagsReadOnly: 指定CUDA不会写入此资源。
cudaGraphicsRegisterFlagsWriteDiscard: 指定CUDA不会读取该资源，而是会覆盖资源的全部内容，因此资源中原先存储的所有数据都不会被保留。

EGLImageKHR是一个可用于创建EGLImage目标资源的对象。它被定义为void指针类型。typedef void* EGLImageKHR

另请参阅：

cudaGraphicsUnregisterResource, cudaGraphicsResourceGetMappedEglFrame, cuGraphicsEGLRegisterImage

__host__ cudaError_t cudaGraphicsResourceGetMappedEglFrame ( cudaEglFrame* eglFrame, cudaGraphicsResource_t resource, unsigned int index, unsigned int mipLevel )

获取一个eglFrame，用于访问已注册的EGL图形资源。

参数

eglFrame: - Returned eglFrame.
resource: - Registered resource to access.
index: - Index for cubemap surfaces.
mipLevel: - Mipmap level for the subresource to access.

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

在*eglFrame中返回一个eglFrame指针，通过该指针可以访问已注册的图形资源resource。此API仅适用于EGL图形资源。

cudaEglFrame的定义如下

‎ typedef struct cudaEglFrame_st {
           union {
               cudaArray_t             pArray[CUDA_EGL_MAX_PLANES];
               struct cudaPitchedPtr   pPitch[CUDA_EGL_MAX_PLANES];
           } frame;
           cudaEglPlaneDesc planeDesc[CUDA_EGL_MAX_PLANES];
           unsigned int planeCount;
           cudaEglFrameType frameType;
           cudaEglColorFormat eglColorFormat;
       } cudaEglFrame;

Note:

请注意，对于多平面*eglFrame，应用程序只需考虑第一个平面的间距（无符号整型cudaEglPlaneDesc::pitch）。

另请参阅：

cudaGraphicsSubResourceGetMappedArray, cudaGraphicsResourceGetMappedPointer, cuGraphicsResourceGetMappedEglFrame