OpenCL™规范 5.3.14.2. 对多样本图像的限制

5.3.14.2. Restrictions on Multi-Sample Images

5.3.14.2. 对多样本图像的限制

The formats described in the Image Channel Order Values and Image Channel Data Types tables of the OpenCL 3.0 specification, specification and the additional formats described in the Minimum list of supported image formats for reading or writing table also support OpenCL images created from a OpenGL multi-sampled color or depth texture.

​OpenCL 3.0规范的“图像通道顺序值”和“图像通道数据类型”表中描述的格式，以及“用于读取或写入的支持图像格式的最小列表”表中所描述的附加格式也支持从OpenGL多采样颜色或深度纹理创建的OpenCL图像。

Multi-sample OpenCL image objects can only be read from a kernel. Multi-sample OpenCL image objects cannot be used as arguments to clEnqueueReadImage, clEnqueueWriteImage, clEnqueueCopyImage, clEnqueueCopyImageToBuffer, clEnqueueCopyBufferToImage, clEnqueueMapImage, and clEnqueueFillImage. Such use will return a CL_INVALID_OPERATION error.

​多样本OpenCL图像对象只能从内核中读取。多示例OpenCL映像对象不能用作clEnqueueReadImage、clEnqueueWriteImage、clEnqueueCopyImage、clEnqueueCopyImageToBuffer、clEnQueueCopyBufferToImage、clEqueueMapImage和clEnqueueFillImage的参数。这样的使用将返回CL_INVALID_OPERATION错误。

To create an OpenCL 2D image object from an OpenGL renderbuffer object, call the function

要从OpenGL renderbuffer对象创建OpenCL 2D图像对象，请调用函数

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

clCreateFromGLRenderbuffer is provided by the cl_khr_gl_sharing extension. clCreateFromGLRenderbuffer由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标志。

• renderbuffer is the name of an OpenGL renderbuffer object. The renderbuffer storage must be specified before the image object can be created. The renderbuffer format and dimensions defined by OpenGL will be used to create the 2D image object. Only OpenGL renderbuffers with an internal format that maps to an appropriate Image Channel Order and Image Channel Data Type may be used to create the 2D image object.

• ​renderbuffer是OpenGL渲染缓冲区对象的名称。必须先指定渲染缓冲区存储，然后才能创建图像对象。OpenGL定义的renderbuffer格式和尺寸将用于创建2D图像对象。只有具有映射到适当的“图像通道顺序”和“图像通道数据类型”的内部格式的OpenGL渲染缓冲区才能用于创建2D图像对象。

• 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，则不会返回任何错误代码。

If the state of an OpenGL renderbuffer object is modified through the OpenGL API (i.e. changes to the dimensions or format used to represent pixels of the OpenGL renderbuffer using appropriate OpenGL API calls such as glRenderbufferStorage) while there exists a corresponding OpenCL image object, subsequent use of the OpenCL image object will result in undefined behavior.

如果在存在相应的OpenCL图像对象时，通过OpenGL API修改OpenGL渲染缓冲区对象的状态（即，使用适当的OpenGL API调用（如glRenderbufferStorage）更改用于表示OpenGL渲染缓冲区时像素的尺寸或格式），则随后使用OpenCL图像将导致未定义的行为。

The clRetainMemObject and clReleaseMemObject functions can be used to retain and release the image objects.

​clRetainMemObject和clReleaseMemObject函数可用于保留和释放图像对象。

The OpenGL Internal Formats and Corresponding OpenCL Internal Formats table describes the list of OpenGL renderbuffer internal formats and the Corresponding OpenCL Image Formats. If an OpenGL renderbuffer object with an internal format from the table is successfully created by OpenGL, then there is guaranteed to be a mapping to one of the corresponding OpenCL image format(s) in that table. Renderbuffer objects created with other OpenGL internal formats may (but are not guaranteed to) have a mapping to an OpenCL image format; if such mappings exist, they are guaranteed to preserve all color components, data types, and at least the number of bits/component actually allocated by OpenGL for that format.

​OpenGL内部格式和相应的OpenCL内部格式表描述了OpenGL renderbuffer内部格式和对应的OpenCL图像格式的列表。如果OpenGL成功创建了表中具有内部格式的OpenGL renderbuffer对象，则可以保证映射到该表中相应的OpenCL图像格式之一。使用其他OpenGL内部格式创建的渲染缓冲区对象可能（但不能保证）具有到OpenCL图像格式的映射；如果存在这样的映射，则保证它们保留所有颜色分量、数据类型，以及至少OpenGL为该格式实际分配的位数/分量。

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内存目标的访问部分。

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

​clCreateFromGLRenderbuffer返回有效的非零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（如果context不是有效上下文或不是从OpenGL上下文创建的）。

• CL_INVALID_VALUE if values specified in flags are not valid.

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

• CL_INVALID_GL_OBJECT if renderbuffer is not an OpenGL renderbuffer object, or if the width or height of renderbuffer is zero.

• CL_INVALID_GL_OBJECT（如果renderbuffer不是OpenGL渲染缓冲区对象，或者renderbuffer的宽度或高度为零）。

• CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if the internal format of renderbuffer is not listed in the OpenGL Internal Formats and Corresponding OpenCL Internal Formats table.

• CL_INVALID_IMAGE_FORMAT_DESCRIPTOR（如果renderbuffer的内部格式未在OpenGL内部格式和相应的OpenCL内部格式表中列出）。

• CL_INVALID_OPERATION if renderbuffer is a multi-sample OpenGL renderbuffer object.

• CL_INVALID_OPERATION如果renderbuffer是一个多样本OpenGL renderbufferobject。

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