CUDA Driver API :: CUDA Toolkit Documentation

6.44. EGL互操作性

本节介绍低级CUDA驱动程序应用程序编程接口的EGL互操作性函数。

Functions

CUresult cuEGLStreamConsumerAcquireFrame ( CUeglStreamConnection* conn, CUgraphicsResource* pCudaResource, CUstream* pStream, unsigned int timeout ): Acquire an image frame from the EGLStream with CUDA as a consumer.
CUresult cuEGLStreamConsumerConnect ( CUeglStreamConnection* conn, EGLStreamKHR stream ): Connect CUDA to EGLStream as a consumer.
CUresult cuEGLStreamConsumerConnectWithFlags ( CUeglStreamConnection* conn, EGLStreamKHR stream, unsigned int flags ): Connect CUDA to EGLStream as a consumer with given flags.
CUresult cuEGLStreamConsumerDisconnect ( CUeglStreamConnection* conn ): Disconnect CUDA as a consumer to EGLStream .
CUresult cuEGLStreamConsumerReleaseFrame ( CUeglStreamConnection* conn, CUgraphicsResource pCudaResource, CUstream* pStream ): Releases the last frame acquired from the EGLStream.
CUresult cuEGLStreamProducerConnect ( CUeglStreamConnection* conn, EGLStreamKHR stream, EGLint width, EGLint height ): Connect CUDA to EGLStream as a producer.
CUresult cuEGLStreamProducerDisconnect ( CUeglStreamConnection* conn ): Disconnect CUDA as a producer to EGLStream .
CUresult cuEGLStreamProducerPresentFrame ( CUeglStreamConnection* conn, CUeglFrame eglframe, CUstream* pStream ): Present a CUDA eglFrame to the EGLStream with CUDA as a producer.
CUresult cuEGLStreamProducerReturnFrame ( CUeglStreamConnection* conn, CUeglFrame* eglframe, CUstream* pStream ): Return the CUDA eglFrame to the EGLStream released by the consumer.
CUresult cuEventCreateFromEGLSync ( CUevent* phEvent, EGLSyncKHR eglSync, unsigned int flags ): Creates an event from EGLSync object.
CUresult cuGraphicsEGLRegisterImage ( CUgraphicsResource* pCudaResource, EGLImageKHR image, unsigned int flags ): Registers an EGL image.
CUresult cuGraphicsResourceGetMappedEglFrame ( CUeglFrame* eglFrame, CUgraphicsResource resource, unsigned int index, unsigned int mipLevel ): Get an eglFrame through which to access a registered EGL graphics resource.

Functions

CUresult cuEGLStreamConsumerAcquireFrame ( CUeglStreamConnection* conn, CUgraphicsResource* pCudaResource, CUstream* pStream, unsigned int timeout )

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

参数

conn: - Connection on which to acquire
pCudaResource: - CUDA resource on which the stream frame will be mapped for use.
pStream: - CUDA stream for synchronization and any data migrations implied by CUeglResourceLocationFlags.
timeout: - Desired timeout in usec for a new frame to be acquired. If set as CUDA_EGL_INFINITE_TIMEOUT, acquire waits infinitely. After timeout occurs CUDA consumer tries to acquire an old frame if available and EGL_SUPPORT_REUSE_NV flag is set.

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_LAUNCH_TIMEOUT,

描述

从EGLStreamKHR获取图像帧。此API还可以获取生产者呈现的旧帧，除非在流初始化期间通过将EGL_SUPPORT_REUSE_NV标志设置为EGL_FALSE明确禁用。默认情况下，EGLStream创建时此标志设置为EGL_TRUE。cuGraphicsResourceGetMappedEglFrame可以在pCudaResource上调用以获取CUeglFrame。

另请参阅：

cuEGLStreamConsumerConnect, cuEGLStreamConsumerDisconnect, cuEGLStreamConsumerAcquireFrame, cuEGLStreamConsumerReleaseFrame, cudaEGLStreamConsumerAcquireFrame

CUresult cuEGLStreamConsumerConnect ( CUeglStreamConnection* conn, EGLStreamKHR stream )

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

参数

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

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_CONTEXT,

描述

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

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

另请参阅：

cuEGLStreamConsumerConnect, cuEGLStreamConsumerDisconnect, cuEGLStreamConsumerAcquireFrame, cuEGLStreamConsumerReleaseFrame, cudaEGLStreamConsumerConnect

CUresult cuEGLStreamConsumerConnectWithFlags ( CUeglStreamConnection* conn, EGLStreamKHR stream, unsigned int flags )

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

参数

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

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_CONTEXT,

描述

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

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

另请参阅：

cuEGLStreamConsumerConnect, cuEGLStreamConsumerDisconnect, cuEGLStreamConsumerAcquireFrame, cuEGLStreamConsumerReleaseFrame, cudaEGLStreamConsumerConnectWithFlags

CUresult cuEGLStreamConsumerDisconnect ( CUeglStreamConnection* conn )

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

参数

conn: - Conection to disconnect.

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_CONTEXT,

描述

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

另请参阅：

cuEGLStreamConsumerConnect, cuEGLStreamConsumerDisconnect, cuEGLStreamConsumerAcquireFrame, cuEGLStreamConsumerReleaseFrame, cudaEGLStreamConsumerDisconnect

CUresult cuEGLStreamConsumerReleaseFrame ( CUeglStreamConnection* conn, CUgraphicsResource pCudaResource, CUstream* 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.

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE,

描述

将pCudaResource指定的已获取图像帧释放回EGLStreamKHR。如果设置了EGL_SUPPORT_REUSE_NV标志为EGL_TRUE，在EGL创建时此API不会释放EGLStream上获取的最后一帧。默认情况下，EGLStream创建时该标志设置为EGL_TRUE。

另请参阅：

cuEGLStreamConsumerConnect, cuEGLStreamConsumerDisconnect, cuEGLStreamConsumerAcquireFrame, cuEGLStreamConsumerReleaseFrame, cudaEGLStreamConsumerReleaseFrame

CUresult cuEGLStreamProducerConnect ( CUeglStreamConnection* conn, EGLStreamKHR stream, EGLint width, EGLint height )

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

参数

conn: - Pointer to the returned connection handle
stream: - EGLStreamKHR handle
width: - width of the image to be submitted to the stream
height: - height of the image to be submitted to the stream

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_CONTEXT,

描述

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

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

另请参阅：

cuEGLStreamProducerConnect, cuEGLStreamProducerDisconnect, cuEGLStreamProducerPresentFrame, cudaEGLStreamProducerConnect

CUresult cuEGLStreamProducerDisconnect ( CUeglStreamConnection* conn )

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

参数

conn: - Conection to disconnect.

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_CONTEXT,

描述

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

另请参阅：

cuEGLStreamProducerConnect, cuEGLStreamProducerDisconnect, cuEGLStreamProducerPresentFrame, cudaEGLStreamProducerDisconnect

CUresult cuEGLStreamProducerPresentFrame ( CUeglStreamConnection* conn, CUeglFrame eglframe, CUstream* 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.

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE,

描述

当生产者呈现一个帧时，该帧会与EGLStream关联，因此在生产者断开连接之前释放该帧是非法的。如果释放并重用帧，可能会导致未定义的行为。

如果生产者和消费者位于不同的GPU（iGPU和dGPU）上，则不支持帧类型CU_EGL_FRAME_TYPE_ARRAY。对于此类跨设备应用，可以使用CU_EGL_FRAME_TYPE_PITCH。

CUeglFrame的定义如下：

‎ typedef struct CUeglFrame_st {
           union {
               CUarray pArray[MAX_PLANES];
               void*   pPitch[MAX_PLANES];
           } frame;
           unsigned int width;
           unsigned int height;
           unsigned int depth;
           unsigned int pitch;
           unsigned int planeCount;
           unsigned int numChannels;
           CUeglFrameType frameType;
           CUeglColorFormat eglColorFormat;
           CUarray_format cuFormat;
       } CUeglFrame;

对于类型为CU_EGL_FRAME_TYPE_PITCH的CUeglFrame，应用程序可以呈现内存分配的子区域。在这种情况下，倾斜指针将指定分配中子区域的起始地址，相应的CUeglFrame字段将指定子区域的维度。

另请参阅：

cuEGLStreamProducerConnect, cuEGLStreamProducerDisconnect, cuEGLStreamProducerReturnFrame, cudaEGLStreamProducerPresentFrame

CUresult cuEGLStreamProducerReturnFrame ( CUeglStreamConnection* conn, CUeglFrame* eglframe, CUstream* pStream )

将CUDA eglFrame返回给消费者释放的EGLStream。

参数

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

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_LAUNCH_TIMEOUT

描述

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

另请参阅：

cuEGLStreamProducerConnect, cuEGLStreamProducerDisconnect, cuEGLStreamProducerPresentFrame, cudaEGLStreamProducerReturnFrame

CUresult cuEventCreateFromEGLSync ( CUevent* phEvent, EGLSyncKHR eglSync, unsigned int flags )

从EGLSync对象创建事件。

参数

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

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_OUT_OF_MEMORY

描述

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

CU_EVENT_DEFAULT: 默认事件创建标志。
CU_EVENT_BLOCKING_SYNC: 指定创建的事件应使用阻塞同步。使用cuEventSynchronize()等待以此标志创建事件的CPU线程将会阻塞，直到事件实际完成。

一旦eglSync被销毁，cuEventDestroy是唯一可以对该事件调用的API。

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

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

另请参阅：

cuEventQuery, cuEventSynchronize, cuEventDestroy

CUresult cuGraphicsEGLRegisterImage ( CUgraphicsResource* 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

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_ALREADY_MAPPED, CUDA_ERROR_INVALID_CONTEXT,

描述

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

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

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

CU_GRAPHICS_MAP_RESOURCE_FLAGS_NONE: 指定不提供关于该资源使用方式的提示。因此默认假设该资源将被CUDA读取和写入。这是默认值。
CU_GRAPHICS_MAP_RESOURCE_FLAGS_READ_ONLY: 指定CUDA不会写入该资源。
CU_GRAPHICS_MAP_RESOURCE_FLAGS_WRITE_DISCARD: 指定CUDA不会读取该资源，而是会覆盖资源的全部内容，因此资源中原先存储的所有数据都不会被保留。

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

另请参阅：

cuGraphicsEGLRegisterImage, cuGraphicsUnregisterResource, cuGraphicsResourceSetMapFlags, cuGraphicsMapResources, cuGraphicsUnmapResources, cudaGraphicsEGLRegisterImage

CUresult cuGraphicsResourceGetMappedEglFrame ( CUeglFrame* eglFrame, CUgraphicsResource 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.

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_NOT_MAPPED

描述

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

CUeglFrame的定义如下：

‎ typedef struct CUeglFrame_st {
           union {
               CUarray pArray[MAX_PLANES];
               void*   pPitch[MAX_PLANES];
           } frame;
           unsigned int width;
           unsigned int height;
           unsigned int depth;
           unsigned int pitch;
           unsigned int planeCount;
           unsigned int numChannels;
           CUeglFrameType frameType;
           CUeglColorFormat eglColorFormat;
           CUarray_format cuFormat;
       } CUeglFrame;

如果resource未注册，则返回CUDA_ERROR_NOT_MAPPED。

另请参阅：

cuGraphicsMapResources, cuGraphicsSubResourceGetMappedArray, cuGraphicsResourceGetMappedPointer, cudaGraphicsResourceGetMappedEglFrame