CUDA 运行时 API :: CUDA 工具包文档

6.25. EGL 互操作性

本节介绍 CUDA 运行时应用程序编程接口的 EGL 互操作性函数。

函数

__host__ cudaError_t cudaEGLStreamConsumerAcquireFrame ( cudaEglStreamConnection* conn, cudaGraphicsResource_t* pCudaResource, cudaStream_t* pStream, unsigned int timeout ): 从 EGLStream 获取图像帧，CUDA 作为消费者。
__host__ cudaError_t cudaEGLStreamConsumerConnect ( cudaEglStreamConnection* conn, EGLStreamKHR eglStream ): 将 CUDA 连接到 EGLStream 作为消费者。
__host__ cudaError_t cudaEGLStreamConsumerConnectWithFlags ( cudaEglStreamConnection* conn, EGLStreamKHR eglStream, unsigned int flags ): 使用给定标志将 CUDA 连接到 EGLStream 作为消费者。
__host__ cudaError_t cudaEGLStreamConsumerDisconnect ( cudaEglStreamConnection* conn ): 断开 CUDA 作为消费者与 EGLStream 的连接。
__host__ cudaError_t cudaEGLStreamConsumerReleaseFrame ( cudaEglStreamConnection* conn, cudaGraphicsResource_t pCudaResource, cudaStream_t* pStream ): 释放从 EGLStream 获取的最后一个帧。
__host__ cudaError_t cudaEGLStreamProducerConnect ( cudaEglStreamConnection* conn, EGLStreamKHR eglStream, EGLint width, EGLint height ): 将 CUDA 连接到 EGLStream 作为生产者。
__host__ cudaError_t cudaEGLStreamProducerDisconnect ( cudaEglStreamConnection* conn ): 断开 CUDA 作为生产者与 EGLStream 的连接。
__host__ cudaError_t cudaEGLStreamProducerPresentFrame ( cudaEglStreamConnection* conn, cudaEglFrame eglframe, cudaStream_t* pStream ): 将 CUDA eglFrame 呈现给 EGLStream，CUDA 作为生产者。
__host__ cudaError_t cudaEGLStreamProducerReturnFrame ( cudaEglStreamConnection* conn, cudaEglFrame* eglframe, cudaStream_t* pStream ): 将 CUDA eglFrame 返回给消费者最后释放的 EGLStream。
__host__ cudaError_t cudaEventCreateFromEGLSync ( cudaEvent_t* phEvent, EGLSyncKHR eglSync, unsigned int flags ): 从 EGLSync 对象创建事件。
__host__ cudaError_t cudaGraphicsEGLRegisterImage ( cudaGraphicsResource** pCudaResource, EGLImageKHR image, unsigned int flags ): 注册 EGL 图像。
__host__ cudaError_t cudaGraphicsResourceGetMappedEglFrame ( cudaEglFrame* eglFrame, cudaGraphicsResource_t resource, unsigned int index, unsigned int mipLevel ): 获取一个 eglFrame，通过它来访问已注册的 EGL 图形资源。

函数

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

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

参数

conn: - 要获取的连接
pCudaResource: - 将在其上映射 EGLStream 帧以供使用的 CUDA 资源。
pStream: - CUDA 流，用于同步以及 cudaEglResourceLocationFlags 暗示的任何数据迁移。
timeout: - 期望的超时时间，单位为微秒 (usec)。

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown, cudaErrorLaunchTimeout

描述

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

另请参阅

cudaEGLStreamConsumerConnect, cudaEGLStreamConsumerDisconnect, cudaEGLStreamConsumerReleaseFrame, cuEGLStreamConsumerAcquireFrame

__host__ cudaError_t cudaEGLStreamConsumerConnect ( cudaEglStreamConnection* conn, EGLStreamKHR eglStream )

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

参数

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

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

将 CUDA 作为消费者连接到由 ... 指定的 EGLStreamKHReglStream.

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

另请参阅

cudaEGLStreamConsumerDisconnect, cudaEGLStreamConsumerAcquireFrame, cudaEGLStreamConsumerReleaseFrame, cuEGLStreamConsumerConnect

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

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

参数

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

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

将 CUDA 作为消费者连接到由 ... 指定的 EGLStreamKHRstream使用指定的flags由 cudaEglResourceLocationFlags 定义。

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

另请参阅

cudaEGLStreamConsumerDisconnect, cudaEGLStreamConsumerAcquireFrame, cudaEGLStreamConsumerReleaseFrame, cuEGLStreamConsumerConnectWithFlags

__host__ cudaError_t cudaEGLStreamConsumerDisconnect ( cudaEglStreamConnection* conn )

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

参数

conn: - 要断开的连接。

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

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

另请参阅

cudaEGLStreamConsumerConnect, cudaEGLStreamConsumerAcquireFrame, cudaEGLStreamConsumerReleaseFrame, cuEGLStreamConsumerDisconnect

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

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

参数

conn: - 要释放的连接
pCudaResource: - 要释放其对应帧的 CUDA 资源
pStream: - 将在其上执行释放的 CUDA 流。

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

将由 ... 指定的已获取图像帧释放到 EGLStreamKHR。pCudaResource到 EGLStreamKHR。

另请参阅

cudaEGLStreamConsumerConnect, cudaEGLStreamConsumerDisconnect, cudaEGLStreamConsumerAcquireFrame, cuEGLStreamConsumerReleaseFrame

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

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

参数

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

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

将 CUDA 作为生产者连接到由 ... 指定的 EGLStreamKHRstream.

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

另请参阅

cudaEGLStreamProducerDisconnect, cudaEGLStreamProducerPresentFrame, cudaEGLStreamProducerReturnFrame, cuEGLStreamProducerConnect

__host__ cudaError_t cudaEGLStreamProducerDisconnect ( cudaEglStreamConnection* conn )

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

参数

conn: - 要断开的连接。

返回值

cudaSuccess, cudaErrorInvalidValue, cudaErrorUnknown

描述

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

另请参阅

cudaEGLStreamProducerConnect, cudaEGLStreamProducerPresentFrame, cudaEGLStreamProducerReturnFrame, cuEGLStreamProducerDisconnect

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

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

参数

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

返回值

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: - 要在其上呈现 CUDA 数组的连接
eglframe: - 通过 EglStream 从消费者返回的 CUDA Eglstream 生产者帧句柄。
pStream: - 要在其上返回帧的 CUDA 流。

返回值

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: - 返回新创建的事件
eglSync: - EGLSync 对象的不透明句柄
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: - 指向返回的对象句柄的指针
image: - 可用于创建目标资源的 EGLImageKHR 图像。
flags: - 映射标志

返回值

cudaSuccess, cudaErrorInvalidResourceHandle, cudaErrorInvalidValue, cudaErrorUnknown

描述

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

应用程序将负责同步对共享对象的访问。应用程序必须确保在将控制权传递给 CUDA 之前，任何访问这些对象的待处理操作都已完成。这可以通过在所有 GL 上下文（对于 OpenGL 以及其他 API）上发出并等待 glFinish 命令来完成。应用程序还将负责确保在执行其他 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 )

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

参数

eglFrame: - 返回的 eglFrame。
resource: - 要访问的已注册资源。
index: - 立方体贴图表面的索引。
mipLevel: - 要访问的子资源的 Mipmap 级别。

返回值

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;

注意

请注意，在多平面情况下*eglFrame，应用程序应仅考虑第一个平面的步幅（unsigned int cudaEglPlaneDesc::pitch）。

另请参阅

cudaGraphicsSubResourceGetMappedArray, cudaGraphicsResourceGetMappedPointer, cuGraphicsResourceGetMappedEglFrame