5.18. Querying Devices That Support Sharing With OpenGL

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，则忽略它。

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实现所需的资源。