NAME¶
glBindImageTexture - bind a level of a texture to an image unit
C SPECIFICATION¶
void
glBindImageTexture(GLuint unit,
GLuint texture, GLint level,
GLboolean layered, GLint layer,
GLenum access, GLenum format);
PARAMETERS¶
unit
Specifies the index of the image unit to which
to bind the texture
texture
Specifies the name of the texture to bind to
the image unit.
level
Specifies the level of the texture that is to
be bound.
layered
Specifies whether a layered texture binding is
to be established.
layer
If layered is GL_FALSE,
specifies the layer of texture to be bound to the image unit. Ignored
otherwise.
access
Specifies a token indicating the type of
access that will be performed on the image.
format
Specifies the format that the elements of the
image will be treated as for the purposes of formatted stores.
DESCRIPTION¶
glBindImageTexture binds a single level of a texture to an image unit for
the purpose of reading and writing it from shaders.
unit specifies the
zero-based index of the image unit to which to bind the texture level.
texture specifies the name of an existing texture object to bind to the
image unit. If
texture is zero, then any existing binding to the image
unit is broken.
level specifies the level of the texture to bind to the
image unit.
If
texture is the name of a one-, two-, or three-dimensional array
texture, a cube map or cube map array texture, or a two-dimensional
multisample array texture, then it is possible to bind either the entire
array, or only a single layer of the array to the image unit. In such cases,
if
layered is
GL_TRUE, the entire array is attached to the image
unit and
layer is ignored. However, if
layered is
GL_FALSE then
layer specifies the layer of the array to attach
to the image unit.
access specifies the access types to be performed by shaders and may be
set to
GL_READ_ONLY,
GL_WRITE_ONLY, or
GL_READ_WRITE to
indicate read-only, write-only or read-write access, respectively. Violation
of the access type specified in
access (for example, if a shader writes
to an image bound with
access set to
GL_READ_ONLY) will lead to
undefined results, possibly including program termination.
format specifies the format that is to be used when performing formatted
stores into the image from shaders.
format must be compatible with the
texture's internal format and must be one of the formats listed in the
following table.
Table 1. Internal Image Formats
Image Unit Format |
Format Qualifier |
GL_RGBA32F |
rgba32f |
GL_RGBA16F |
rgba16f |
GL_RG32F |
rg32f |
GL_RG16F |
rg16f |
GL_R11F_G11F_B10F |
r11f_g11f_b10f |
GL_R32F |
r32f |
GL_R16F |
r16f |
GL_RGBA32UI |
rgba32ui |
GL_RGBA16UI |
rgba16ui |
GL_RGB10_A2UI |
rgb10_a2ui |
GL_RGBA8UI |
rgba8ui |
GL_RG32UI |
rg32ui |
GL_RG16UI |
rg16ui |
GL_RG8UI |
rg8ui |
GL_R32UI |
r32ui |
GL_R16UI |
r16ui |
GL_R8UI |
r8ui |
GL_RGBA32I |
rgba32i |
GL_RGBA16I |
rgba16i |
GL_RGBA8I |
rgba8i |
GL_RG32I |
rg32i |
GL_RG16I |
rg16i |
GL_RG8I |
rg8i |
GL_R32I |
r32i |
GL_R16I |
r16i |
GL_R8I |
r8i |
GL_RGBA16 |
rgba16 |
GL_RGB10_A2 |
rgb10_a2 |
GL_RGBA8 |
rgba8 |
GL_RG16 |
rg16 |
GL_RG8 |
rg8 |
GL_R16 |
r16 |
GL_R8 |
r8 |
GL_RGBA16_SNORM |
rgba16_snorm |
GL_RGBA8_SNORM |
rgba8_snorm |
GL_RG16_SNORM |
rg16_snorm |
GL_RG8_SNORM |
rg8_snorm |
GL_R16_SNORM |
r16_snorm |
GL_R8_SNORM |
r8_snorm |
When a texture is bound to an image unit, the
format parameter for the image unit need not exactly match the texture
internal format as long as the formats are considered compatible as defined in
the OpenGL Specification. The matching criterion used for a given texture may
be determined by calling
glGetTexParameter() with
value set to
GL_IMAGE_FORMAT_COMPATIBILITY_TYPE, with return values of
GL_IMAGE_FORMAT_COMPATIBILITY_BY_SIZE and
GL_IMAGE_FORMAT_COMPATIBILITY_BY_CLASS, specifying matches by size and
class, respectively.
NOTES¶
The
glBindImageTexture is available only if the GL version is 4.2 or
greater.
ERRORS¶
GL_INVALID_VALUE is generated if
unit greater than or equal to the
value of
GL_MAX_IMAGE_UNITS.
GL_INVALID_VALUE is generated if
texture is not the name of an
existing texture object.
GL_INVALID_VALUE is generated if
level or
layer is less
than zero.
GL_INVALID_ENUM is generated if
access or
format is not one
of the supported tokens.
ASSOCIATED GETS¶
glGet() with argument
GL_IMAGE_BINDING_NAME.
glGet() with argument
GL_IMAGE_BINDING_LEVEL.
glGet() with argument
GL_IMAGE_BINDING_LAYERED.
glGet() with argument
GL_IMAGE_BINDING_LAYER.
glGet() with argument
GL_IMAGE_BINDING_ACCESS.
glGet() with argument
GL_IMAGE_BINDING_FORMAT.
SEE ALSO¶
glGenTextures(),
glTexImage1D(),
glTexImage2D(),
glTexImage3D(),
glTexStorage1D(),
glTexStorage2D(),
glTexStorage3D(),
glBindTexture()
COPYRIGHT¶
Copyright © 2011 Khronos Group. This material may be distributed subject to
the terms and conditions set forth in the Open Publication License, v 1.0, 8
June 1999.
http://opencontent.org/openpub/.