CUDA 驱动程序 API :: CUDA 工具包文档

6.44. EGL 互操作性

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

函数

CUresult cuEGLStreamConsumerAcquireFrame ( CUeglStreamConnection* conn, CUgraphicsResource* pCudaResource, CUstream* pStream, unsigned int timeout ): 从以 CUDA 作为消费者的 EGLStream 获取图像帧。
CUresult cuEGLStreamConsumerConnect ( CUeglStreamConnection* conn, EGLStreamKHR stream ): 将 CUDA 连接到 EGLStream 作为消费者。
CUresult cuEGLStreamConsumerConnectWithFlags ( CUeglStreamConnection* conn, EGLStreamKHR stream, unsigned int flags ): 使用给定标志将 CUDA 连接到 EGLStream 作为消费者。
CUresult cuEGLStreamConsumerDisconnect ( CUeglStreamConnection* conn ): 断开 CUDA 作为 EGLStream 的消费者连接。
CUresult cuEGLStreamConsumerReleaseFrame ( CUeglStreamConnection* conn, CUgraphicsResource pCudaResource, CUstream* pStream ): 释放从 EGLStream 获取的最后一个帧。
CUresult cuEGLStreamProducerConnect ( CUeglStreamConnection* conn, EGLStreamKHR stream, EGLint width, EGLint height ): 将 CUDA 连接到 EGLStream 作为生产者。
CUresult cuEGLStreamProducerDisconnect ( CUeglStreamConnection* conn ): 断开 CUDA 作为 EGLStream 的生产者连接。
CUresult cuEGLStreamProducerPresentFrame ( CUeglStreamConnection* conn, CUeglFrame eglframe, CUstream* pStream ): 将 CUDA eglFrame 呈现给以 CUDA 作为生产者的 EGLStream。
CUresult cuEGLStreamProducerReturnFrame ( CUeglStreamConnection* conn, CUeglFrame* eglframe, CUstream* pStream ): 将消费者释放的 CUDA eglFrame 返回给 EGLStream。
CUresult cuEventCreateFromEGLSync ( CUevent* phEvent, EGLSyncKHR eglSync, unsigned int flags ): 从 EGLSync 对象创建事件。
CUresult cuGraphicsEGLRegisterImage ( CUgraphicsResource* pCudaResource, EGLImageKHR image, unsigned int flags ): 注册 EGL 图像。
CUresult cuGraphicsResourceGetMappedEglFrame ( CUeglFrame* eglFrame, CUgraphicsResource resource, unsigned int index, unsigned int mipLevel ): 获取 eglFrame，通过该帧访问已注册的 EGL 图形资源。

函数

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

从以 CUDA 作为消费者的 EGLStream 获取图像帧。

参数

conn: - 要在其上获取的连接
pCudaResource: - 流帧将被映射以供使用的 CUDA 资源。
pStream: - CUDA 流，用于同步以及 CUeglResourceLocationFlags 暗示的任何数据迁移。
timeout: - 获取新帧所需的超时时间（微秒）。如果设置为 CUDA_EGL_INFINITE_TIMEOUT，则获取操作将无限期等待。超时后，如果设置了 EGL_SUPPORT_REUSE_NV 标志，CUDA 消费者会尝试获取旧帧（如果可用）。

返回值

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_LAUNCH_TIMEOUT,

描述

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

另请参阅

cuEGLStreamConsumerConnect, cuEGLStreamConsumerDisconnect, cuEGLStreamConsumerAcquireFrame, cuEGLStreamConsumerReleaseFrame, cudaEGLStreamConsumerAcquireFrame

CUresult cuEGLStreamConsumerConnect ( CUeglStreamConnection* conn, EGLStreamKHR stream )

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

参数

conn: - 指向返回的连接句柄的指针
stream: - EGLStreamKHR 句柄

返回值

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_CONTEXT,

描述

将 CUDA 作为消费者连接到 EGLStreamKHR，由stream.

EGLStreamKHR 是一个 EGL 对象，它将图像帧序列从一个 API 传输到另一个 API。

另请参阅

cuEGLStreamConsumerConnect, cuEGLStreamConsumerDisconnect, cuEGLStreamConsumerAcquireFrame, cuEGLStreamConsumerReleaseFrame, cudaEGLStreamConsumerConnect

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

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

参数

conn: - 指向返回的连接句柄的指针
stream: - EGLStreamKHR 句柄
flags: - 标志表示预期位置 - 系统内存或显存。

返回值

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_CONTEXT,

描述

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

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

另请参阅

cuEGLStreamConsumerConnect, cuEGLStreamConsumerDisconnect, cuEGLStreamConsumerAcquireFrame, cuEGLStreamConsumerReleaseFrame, cudaEGLStreamConsumerConnectWithFlags

CUresult cuEGLStreamConsumerDisconnect ( CUeglStreamConnection* conn )

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

参数

conn: - 要断开连接的连接。

返回值

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: - 要在其上释放的连接
pCudaResource: - 要释放的对应帧的 CUDA 资源
pStream: - 将在其上完成释放的 CUDA 流。

返回值

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE,

描述

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

另请参阅

cuEGLStreamConsumerConnect, cuEGLStreamConsumerDisconnect, cuEGLStreamConsumerAcquireFrame, cuEGLStreamConsumerReleaseFrame, cudaEGLStreamConsumerReleaseFrame

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

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

参数

conn: - 指向返回的连接句柄的指针
stream: - EGLStreamKHR 句柄
width: - 要提交到流的图像宽度
height: - 要提交到流的图像高度

返回值

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_INVALID_CONTEXT,

描述

将 CUDA 作为生产者连接到 EGLStreamKHR，由stream.

EGLStreamKHR 是一个 EGL 对象，它将图像帧序列从一个 API 传输到另一个 API。

另请参阅

cuEGLStreamProducerConnect, cuEGLStreamProducerDisconnect, cuEGLStreamProducerPresentFrame, cudaEGLStreamProducerConnect

CUresult cuEGLStreamProducerDisconnect ( CUeglStreamConnection* conn )

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

参数

conn: - 要断开连接的连接。

返回值

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 呈现给以 CUDA 作为生产者的 EGLStream。

参数

conn: - 要在其上呈现 CUDA 数组的连接
eglframe: - 要通过 EglStream 发送到消费者的 CUDA Eglstream 生产者帧句柄。
pStream: - 要在其上呈现帧的 CUDA 流。

返回值

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，应用程序可以呈现内存分配的子区域。在这种情况下，pitched 指针将指定分配中子区域的起始地址，相应的 CUeglFrame 字段将指定子区域的尺寸。

另请参阅

cuEGLStreamProducerConnect, cuEGLStreamProducerDisconnect, cuEGLStreamProducerReturnFrame, cudaEGLStreamProducerPresentFrame

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

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

参数

conn: - 要在其上返回的连接
eglframe: - 从消费者通过 EglStream 返回的 CUDA Eglstream 生产者帧句柄。
pStream: - 要在其上返回帧的 CUDA 流。

返回值

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: - 返回新创建的事件
eglSync: - EGLSync 对象的不透明句柄
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。

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

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

另请参阅

cuEventQuery, cuEventSynchronize, cuEventDestroy

CUresult cuGraphicsEGLRegisterImage ( CUgraphicsResource* pCudaResource, EGLImageKHR image, unsigned int flags )

参数

pCudaResource: - 指向返回的对象句柄的指针
image: - 可用于创建目标资源的 EGLImageKHR 图像。
flags: - 映射标志

返回值

CUDA_SUCCESS, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_ALREADY_MAPPED, CUDA_ERROR_INVALID_CONTEXT,

描述

注册由以下项指定的 EGLImageKHRimage，以便 CUDA 访问。注册对象的句柄作为pCudaResource返回。注册资源不需要额外的映射/取消映射，可以直接对

调用 cuGraphicsResourceGetMappedEglFrame。pCudaResource.

应用程序将负责同步对共享对象的访问。应用程序必须确保在将控制权传递给 CUDA 之前，任何访问对象的挂起操作都已完成。这可以通过在所有 GLcontext 上发出并等待 glFinish 命令（对于 OpenGL 以及其他 API 类似）来完成。应用程序还将负责确保在执行访问相同内存对象的其他 API 中的后续命令之前，已完成对已注册 CUDA 资源的任何挂起操作。这可以通过调用 cuCtxSynchronize 或 cuEventSynchronize（最好是 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: - 返回的 eglFrame。
resource: - 要访问的已注册资源。
index: - 立方体贴图表面的索引。
mipLevel: - 要访问的子资源的 Mipmap 级别。

返回值

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