OpenCL™规范 5.3.14. 从OpenGL纹理和渲染缓冲区创建OpenCL图像对象

最新推荐文章于 2024-06-24 19:12:42 发布

꧁白杨树下꧂

最新推荐文章于 2024-06-24 19:12:42 发布

阅读量71

点赞数

分类专栏： openCL 文章标签： opencl

原文链接：https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#_creating_opencl_image_objects_from_opengl_textures_and_renderbuffers

版权

openCL 专栏收录该内容

148 篇文章 12 订阅

订阅专栏

5.3.14. Creating OpenCL Image Objects From OpenGL Textures and Renderbuffers

5.3.14. 从OpenGL纹理和渲染缓冲区创建OpenCL图像对象

To create an OpenCL image object from an OpenGL texture object, call the function

要从OpenGL纹理对象创建OpenCL图像对象，请调用函数

// Provided by cl_khr_gl_sharing
cl_mem clCreateFromGLTexture(
    cl_context context,
    cl_mem_flags flags,
    cl_GLenum target,
    cl_GLint miplevel,
    cl_GLuint texture,
    cl_int* errcode_ret);

clCreateFromGLTexture is provided by the cl_khr_gl_sharing extension.

clCreateFromGLTexture由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标志。
texture_target must be one of GL_TEXTURE_1D, GL_TEXTURE_1D_ARRAY, GL_TEXTURE_BUFFER, GL_TEXTURE_2D, GL_TEXTURE_2D_ARRAY, GL_TEXTURE_3D, GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z, GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Z. GL_TEXTURE_RECTANGLE or the equivalent GL_TEXTURE_RECTANGLE_ARB may be specified if an OpenGL implementation supporting rectangular textures is supported. GL_TEXTURE_2D_MULTISAMPLE and GL_TEXTURE_2D_MULTISAMPLE_ARRAY may be specified if an OpenGL implementation supporting multi-sample two-dimensional textures is supported, and the cl_khr_gl_msaa_sharing extension is supported. Refer to the Restrictions on Multi-Sample Images section for more information on multi-sample images. texture_target is used only to define the image type of texture. No reference to a bound OpenGL texture object is made or implied by this parameter.
texture_target必须是GL_TEXTURE_1D, GL_TEXTURE_1D_ARRAY, GL_TEXTURE_BUFFER, GL_TEXTURE_2D, GL_TEXTURE_2D_ARRAY, GL_TEXTURE_3D, GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z, GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Z. GL_TEXTURE_RECTANGLE 。如果支持支持矩形纹理的OpenGL实现，则可以指定等效的GL_TEXTURE_RECTANGLE_ARB。如果支持支持多样本二维纹理的OpenGL实现，并且支持cl_khr_gl_msaa_sharing扩展，则可以指定GL_TEXTURE_2D_MULTISAMPLE和GL_TEXTURE_2D_MULTISAMPLE_ARRAY。有关多样本图像的更多信息，请参阅“多样本图像限制”部分。texture_target仅用于定义texture的图像类型。此参数不会引用或暗示绑定的OpenGL纹理对象。
miplevel is the mipmap level to be used. If texture_target is GL_TEXTURE_BUFFER, miplevel must be 0. Note: Implementations may return CL_INVALID_OPERATION for miplevel values > 0.
mipvevel是要使用的mipmap级别。如果texture_target为GL_TEXTURE_BUFFER，则mipvlevel必须为0。注意：对于mipvevel值>0，实现可能返回CL_INVALID_OPERATION。
texture is the name of an OpenGL 1D, 2D, 3D, 1D array, 2D array, cubemap, rectangle or buffer texture object. The texture object must be a complete texture as per OpenGL rules on texture completeness. The texture format and dimensions defined by OpenGL for the specified miplevel of the texture will be used to create the OpenCL image memory object. Only OpenGL texture objects with an internal format that maps to an appropriate Image Channel Order and Image Channel Data Type may be used to create the OpenCL image memory object.
纹理是OpenGL 1D、2D、3D、1D阵列、2D阵列、立方体映射、矩形或缓冲区纹理对象的名称。根据OpenGL关于纹理完整性的规则，纹理对象必须是完整的纹理。OpenGL为指定的纹理mipvevel定义的纹理格式和尺寸将用于创建OpenCL图像内存对象。只有具有映射到适当图像通道顺序和图像通道数据类型的内部格式的OpenGL纹理对象才能用于创建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，则不会返回任何错误代码。

clCreateFromGLTexture may create any of the following:

clCreateFromGLTexture可以创建以下任意一个：

an OpenCL 2D image object from an OpenGL 2D texture object or a single face of an OpenGL cubemap texture object,
来自OpenGL 2D纹理对象的OpenCL 2D图像对象或OpenGL立方体映射纹理对象的单个面，
an OpenCL 2D image array object from an OpenGL 2D texture array object,
来自OpenGL 2D纹理阵列对象的OpenCL 2D图像阵列对象，
an OpenCL 2D multi-sample image object from an OpenGL 2D multi-sample texture.
来自OpenGL 2D多样本纹理的OpenCL 2D多样本图像对象。
an OpenCL 2D multi-sample array image object from an OpenGL 2D multi-sample texture.
来自OpenGL 2D多样本纹理的OpenCL 2D多样本阵列图像对象。
an OpenCL 1D image object from an OpenGL 1D texture object,
来自OpenGL 1D纹理对象的OpenCL 1D图像对象，
an OpenCL 1D image buffer object from an OpenGL texture buffer object,
来自OpenGL纹理缓冲对象的OpenCL 1D图像缓冲对象，
an OpenCL 1D image array object from an OpenGL 1D texture array object,
来自OpenGL 1D纹理阵列对象的OpenCL 1D图像阵列对象，
an OpenCL 3D image object from an OpenGL 3D texture object.
来自OpenGL 3D纹理对象的OpenCL 3D图像对象。

If both the cl_khr_mipmap_image and cl_khr_gl_sharing extensions are supported by the OpenCL device, clCreateFromGLTexture may also be used to create a mipmapped OpenCL image from a mipmapped OpenGL texture by specify a negative value for miplevel. In this case, then an OpenCL mipmapped image object is created from a mipmapped OpenGL texture object, instead of an OpenCL image object for a specific miplevel of the OpenGL texture.

如果cl_khr_mipmap_image和cl_kher_gl_sharing扩展都受OpenCL设备支持，则clCreateFromGLTexture也可以用于通过为miplievel指定负值来从mipmapped OpenGL纹理创建mipmappet OpenCL图像。在这种情况下，将从mipmapped OpenGL纹理对象创建OpenCL mipmappet图像对象，而不是针对OpenGL纹理的特定miploevel创建OpenCL图像对象。

For a detailed description of how the level of detail is computed, please refer to the “Scale Factor and Level-of-Detail” section of the OpenGL 4.6 Specification.

有关如何计算细节级别的详细说明，请参阅OpenGL 4.6规范的“比例因子和细节级别”部分。

If the state of an OpenGL texture object is modified through the OpenGL API (e.g. glTexImage2D, glTexImage3D or the values of the texture parameters GL_TEXTURE_BASE_LEVEL or GL_TEXTURE_MAX_LEVEL are modified) while there exists a corresponding OpenCL image object, subsequent use of the OpenCL image object will result in undefined behavior.

如果在存在对应的OpenCL图像对象时通过OpenGL API修改OpenGL纹理对象的状态（例如修改glTexImage2D、glTexImage3D或纹理参数GL_TEXTURE_BASE_LEVEL或GL_TEXTURE_MAX_LEVEL的值），则随后使用OpenCL图像对象将导致未定义的行为。

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

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

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

clCreateFromGLTexture 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:

clCreateFromGLTexture返回有效的非零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 or if value specified in texture_target is not one of the values specified in the description of texture_target.
CL_INVALID_VALUE，如果flags中指定的值无效，或者texture_target中指定的数值不是texture_target描述中指定的其中一个数值。
CL_INVALID_MIP_LEVEL if miplevel is less than the value of levelbase (for OpenGL implementations) or zero (for OpenGL ES implementations); or greater than the value of q (for both OpenGL and OpenGL ES). levelbase and q are defined for the texture in section 3.8.10 (Texture Completeness) of the OpenGL 2.1 Specification and section 3.7.10 of the OpenGL ES 2.0 Specification.
CL_INVALID_MIP_LEVEL，如果mipvlevel小于levelbase的值（对于OpenGL实现）或零（对于OpenGL ES实现）；或者大于q的值（对于OpenGL和OpenGL ES两者）。在OpenGL 2.1规范的第3.8.10节（纹理完整性）和OpenGL ES 2.0规范的第3.7.10节中为纹理定义了levelbase和q。
CL_INVALID_MIP_LEVEL if miplevel is greather than zero and the OpenGL implementation does not support creating from non-zero mipmap levels.
CL_INVALID_MIP_LEVEL如果mipmap级别大于零并且OpenGL实现不支持从非零mipmap级创建。
CL_INVALID_GL_OBJECT if texture is not an OpenGL texture object whose type matches texture_target, if the specified miplevel of texture is not defined, or if the width or height of the specified miplevel is zero or if the OpenGL texture object is incomplete.
CL_INVALID_GL_OBJECT如果纹理不是类型与texture_target匹配的OpenGL纹理对象，如果未定义指定的纹理mipvlevel，或者如果指定的mipvlevel的宽度或高度为零，或者OpenGL纹理对象不完整。
CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if the internal format of texture is not listed in the OpenGL Internal Formats and Corresponding OpenCL Internal Formats table.
CL_INVALID_IMAGE_FORMAT_DESCRIPTOR（如果OpenGL内部格式和相应的OpenCL内部格式表中未列出纹理的内部格式）。
CL_INVALID_OPERATION if texture is an OpenGL texture object created with a border width value greater than zero.
CL_INVALID_OPERATION如果texture是用大于零的边界宽度值创建的OpenGL纹理对象。
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实现所需的资源失败。