OpenCL™规范 5.2.7. 从OpenGL缓冲区对象创建OpenCL缓冲区对象

5.2.7. Creating OpenCL Buffer Objects From OpenGL Buffer Objects

5.2.7. 从OpenGL缓冲区对象创建OpenCL缓冲区对象

To create an OpenCL buffer object from an OpenGL buffer object, call the function

要从OpenGL缓冲区对象创建OpenCL缓冲区对象，请调用函数

// Provided by cl_khr_gl_sharing
cl_mem clCreateFromGLBuffer(
    cl_context context,
    cl_mem_flags flags,
    cl_GLuint bufobj,
    cl_int* errcode_ret);

clCreateFromGLBuffer is provided by the cl_khr_gl_sharing extension. clCreateFromGLBuffer由cl_khr_gl_sharing扩展提供。

• context is a valid OpenCL context created from an OpenGL context.

• context是从OpenGL上下文创建的有效OpenCL上下文。

• flags is a bit-field that is used to specify usage information. Refer to the Memory Flags table for a description of flags. Only the CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE flags specified in that table can be used.

• ​flags是一个用于指定使用信息的位字段。有关标志的说明，请参阅内存标志表。只能使用该表中指定的CL_MEM_READ_ONLY、CL_MEM_WRITE_ONLY和CL_MEM_READ_WRITE标志。

• bufobj is the name of an OpenGL buffer object. The data store of the OpenGL buffer object must have have been previously created by calling glBufferData, although its contents need not be initialized. The size of the data store will be used to determine the size of the OpenCL buffer object.

• bufobj是OpenGL缓冲区对象的名称。OpenGL缓冲区对象的数据存储必须是以前通过调用glBufferData创建的，尽管其内容不需要初始化。数据存储的大小将用于确定OpenCL缓冲区对象的大小。

• errcode_ret will return an appropriate error code as described below. If errcode_ret is NULL, no error code is returned.

• errcode_ret将返回适当的错误代码，如下所述。如果errcode_ret为NULL，则不会返回任何错误代码。

The size of the OpenGL buffer object data store at the time clCreateFromGLBuffer is called will be used as the size of buffer object returned by clCreateFromGLBuffer. If the state of an OpenGL buffer object is modified through the OpenGL API (e.g. glBufferData) while there exists a corresponding OpenCL buffer object, subsequent use of the OpenCL buffer object will result in undefined behavior.

调用clCreateFromGLBuffer时OpenGL缓冲区对象数据存储的大小将用作clCreateFromGL缓冲区返回的缓冲区对象的大小。如果通过OpenGL API（例如glBufferData）修改OpenGL缓冲区对象的状态，同时存在相应的OpenCL缓冲区对象，则后续使用OpenCL缓冲区时将导致未定义的行为。

The clRetainMemObject and clReleaseMemObject functions can be used to retain and release the buffer object.

​clRetainMemObject和clReleaseMemObject函数可用于保留和释放缓冲区对象。

The OpenCL buffer object created using clCreateFromGLBuffer can also be used to create an OpenCL 1D image buffer object.

使用clCreateFromGLBuffer创建的OpenCL缓冲区对象也可以用于创建OpenCL 1D图像缓冲区对象。

Refer to the Lifetime of Shared OpenCL/OpenGL Memory Objects and Acquiring, Releasing, and Synchronizing Access to Shared OpenCL/OpenGL Memory Objects sections for more information. ​ 有关更多信息，请参阅共享OpenCL/OpenGL内存对象的寿命以及获取、释放和同步对共享OpenCL/OpenGL内存目标的访问部分。

clCreateFromGLBuffer returns a valid non-zero OpenCL buffer object and errcode_ret is set to CL_SUCCESS if the buffer object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

​clCreateFromGLBuffer返回一个有效的非零OpenCL缓冲区对象，如果缓冲区对象创建成功，则errcode_ret设置为CL_SUCCESS。否则，它将返回一个NULL值，并在errcode_ret中返回以下错误值之一：

• CL_INVALID_CONTEXT if context is not a valid context or was not created from an OpenGL context.

• CL_INVALID_CONTEXT（如果上下文不是有效上下文或不是从OpenGL上下文创建的）。

• CL_INVALID_VALUE if values specified in flags are not valid.

• CL_INVALID_VALUE（如果标志中指定的值无效）。

• CL_INVALID_GL_OBJECT if bufobj is not an OpenGL buffer object or is a OpenGL buffer object but does not have an existing data store or the size of the buffer is 0.

• CL_INVALID_GL_OBJECT如果bufobj不是OpenGL缓冲区对象，或者是OpenGL缓冲区，但没有现有的数据存储，或者缓冲区的大小为0。

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