C Specification

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

// 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.

Parameters

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

  • 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.

  • 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.

  • 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.

  • 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.

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

Description

clCreateFromGLTexture may create any of the following:

  • an OpenCL 2D image object from an OpenGL 2D texture object or a single face of an OpenGL cubemap texture object,

  • an OpenCL 2D image array object from an OpenGL 2D texture array object,

  • an OpenCL 2D multi-sample image object from an OpenGL 2D multi-sample texture.

  • an OpenCL 2D multi-sample array image object from an OpenGL 2D multi-sample texture.

  • an OpenCL 1D image object from an OpenGL 1D texture object,

  • an OpenCL 1D image buffer object from an OpenGL texture buffer object,

  • an OpenCL 1D image array object from an OpenGL 1D texture array object,

  • an OpenCL 3D image object from an OpenGL 3D texture object.

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.

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.

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.

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

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.

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:

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

  • 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_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 if miplevel is greather than zero and the OpenGL implementation does not support creating from non-zero mipmap levels.

  • 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_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_OPERATION if texture is an OpenGL texture object created with a border width value greater than zero.

  • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

  • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

See Also

cl_GLenum, cl_GLint, cl_GLuint, cl_context, cl_int, cl_khr_gl_sharing, cl_mem_flags

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0