OpenCL™规范 5.18. 查询支持与OpenGL共享的设备

翻译于 2025-01-15 10:00:19 发布 · 113 阅读

CC 4.0 BY-SA版权

原文链接：https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#querying-devices-that-support-sharing-with-opengl

文章标签：

#opencl

openCL 专栏收录该内容

198 篇文章

订阅专栏

5.18. 查询支持与OpenGL共享的设备

OpenCL device(s) corresponding to an OpenGL context may be queried. Such a device may not always exist (for example, if an OpenGL context is specified on a GPU not supporting OpenCL command-queues, but which does support shared OpenCL/OpenGL memory objects), and if it does exist, may change over time. When such a device does exist, acquiring and releasing shared OpenCL/OpenGL memory objects may be faster on a command-queue corresponding to this device than on command-queues corresponding to other devices available to an OpenCL context.

可以查询与OpenGL上下文对应的OpenCL设备。这样的设备可能并不总是存在（例如，如果在不支持OpenCL命令队列但支持共享OpenCL/OpenGL内存对象的GPU上指定了OpenGL上下文），如果确实存在，可能会随着时间的推移而变化。当这样的设备确实存在时，在与该设备对应的命令队列上获取和释放共享的OpenCL/OpenGL内存对象可能比在与OpenCL上下文可用的其他设备对应的指令队列上更快。

To query the OpenCL device corresponding to an OpenGL context, call the function

要查询与OpenGL上下文对应的OpenCL设备，请调用以下函数

// Provided by cl_khr_gl_sharing
cl_int clGetGLContextInfoKHR(
    const cl_context_properties* properties,
    cl_gl_context_info param_name,
    size_t param_value_size,
    void* param_value,
    size_t* param_value_size_ret);

properties points to an property list whose format and valid contents are identical to the properties argument of clCreateContext. properties must identify a single valid GL context or GL share group object.
properties指向一个属性列表，其格式和有效内容与clCreateContext的properties参数相同。properties必须标识单个有效的GL上下文或GL共享组对象。
param_name is a constant that specifies the device types to query, and must be one of the values shown in the Supported Device Types table below.
param_name是一个常数，指定要查询的设备类型，并且必须是下面“支持的设备类型”表中显示的值之一。
param_value is a pointer to memory where the result of the query is returned, as described in the Supported Device Types table. If param_value is NULL, it is ignored.
param_value是一个指向返回查询结果的内存的指针，如“支持的设备类型”表所述。如果param_value为NULL，则忽略它。
param_value_size specifies the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of the return type specified in the Supported Device Types table. If param_value is NULL, it is ignored.
param_value_size指定param_value指向的内存大小（以字节为单位）。此大小必须大于或等于“支持的设备类型”表中指定的返回类型的大小。如果param_value为NULL，则忽略它。
param_value_size_ret returns the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored.
param_value_size_ret返回param_value查询的数据的实际大小（以字节为单位）。如果param_value_size_ret为NULL，则忽略它。

Table 62. Supported Device Types for clGetGLContextInfoKHR

表62 clGetGLContextInfoKHR支持的设备类型
param_name 参数名称	Return Type 返回类型	Information returned in param_value param_value中返回的信息
CL_CURRENT_DEVICE_FOR_GL_CONTEXT_KHR provided by the `cl_khr_gl_sharing` extension.	`cl_device_id`	Return the OpenCL device currently associated with the specified OpenGL context. 返回当前与指定OpenGL上下文关联的OpenCL设备。
CL_DEVICES_FOR_GL_CONTEXT_KHR provided by the `cl_khr_gl_sharing` extension.	`cl_device_id`[]	Return all OpenCL devices which may be associated with the specified OpenGL context. 返回可能与指定OpenGL上下文关联的所有OpenCL设备。

clGetGLContextInfoKHR returns CL_SUCCESS if the function is executed successfully. If no device(s) exist corresponding to param_name, the call will not fail, but the value of param_value_size_ret will be zero. Otherwise, it returns one of the following errors:

如果函数执行成功，clGetGLContextInfoKHR将返回CL_SUCCESS。如果不存在与param_name对应的设备，则调用不会失败，但param_value_size_ret的值将为零。否则，它将返回以下错误之一：

CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR if a context was specified for an OpenGL or OpenGL ES implementation using the EGL, GLX, or WGL binding APIs, as described for clCreateContext; and any of the following conditions hold:

CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR，如果使用EGL、GLX或WGL绑定API为OpenGL或OpenGL ES实现指定了上下文，如clCreateContext所述；并且满足以下任何条件：
- The specified display and context properties do not identify a valid OpenGL or OpenGL ES context.
- 指定的显示和上下文属性无法标识有效的OpenGL或OpenGL ES上下文。
- The specified context does not support buffer and renderbuffer objects.
- 指定的上下文不支持缓冲区和渲染缓冲区对象。
- The specified context is not compatible with the OpenCL context being created (for example, it exists in a physically distinct address space, such as another hardware device; or it does not support sharing data with OpenCL due to implementation restrictions).
- 指定的上下文与正在创建的OpenCL上下文不兼容（例如，它存在于物理上不同的地址空间中，如另一个硬件设备；或者由于实现限制，它不支持与OpenCL共享数据）。
CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR if a share group was specified for a CGL-based OpenGL implementation by setting the property CL_CGL_SHAREGROUP_KHR, and the specified share group does not identify a valid CGL share group object.
如果通过设置属性CL_CGL_SHAREGROUP_KHR为基于CGL的OpenGL实现指定了共享组，并且指定的共享组没有标识有效的CGL共享组对象，则返回CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR。
CL_INVALID_OPERATION if a context was specified as described above and any of the following conditions hold:

CL_INVALID_OPERATION，如果如上所述指定了上下文，并且满足以下任何条件：
- A context or share group object was specified for one of CGL, EGL, GLX, or WGL and the OpenGL implementation does not support that window-system binding API.
- 为CGL、EGL、GLX或WGL之一指定了上下文或共享组对象，并且OpenGL实现不支持该窗口系统绑定API。
- More than one of the properties CL_CGL_SHAREGROUP_KHR, CL_EGL_DISPLAY_KHR, CL_GLX_DISPLAY_KHR, and CL_WGL_HDC_KHR is set to a non-default value.
- 属性CL_CGL_SHAREGROUP_KHR、CL_EGL_DISPLAY_KHR、CL_GLX_DISPLAY_KHR和CL_WGL_HDC_KHR中的多个设置为非默认值。
- Both of the properties CL_CGL_SHAREGROUP_KHR and CL_GL_CONTEXT_KHR are set to non-default values.
- 属性CL_CGL_SHAREGROUP_KHR和CL_GL_CONTEXT_KHR都设置为非默认值。
CL_INVALID_VALUE if a property name specified in properties is invalid.
如果properties中指定的属性名无效，则返回CL_INVALID_VALUE。
CL_INVALID_VALUE if param_name is not one of the supported values, or if the size in bytes specified by param_value_size is less than size of the return type specified in the Supported Device Types table and param_value is not NULL.
如果param_name不是支持的值之一，或者param_value_size 指定的字节大小小于“支持的设备类型”表中指定的返回类型的大小，并且param_value 不为NULL，则返回CL_INVALID_VALUE。
CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device
CL_OUT_OF_RESOURCES（如果无法在设备上分配OpenCL实现所需的资源）
CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
CL_OUT_OF_HOST_MEMORY，如果无法在主机上分配OpenCL实现所需的资源。