Texture

OpenGL Objects

OpenGL Object

---

• Buffer Objects
  • Vertex Buffer Objects
  • Uniform Buffer Objects
  • Shader Storage Buffer Objects
  • Pixel Buffer Objects
  • Atomic Counters
  • Buffer Object Streaming
• Vertex Array Objects
• Textures
  • Texture Storage
  • Image formats
  • Sampler Objects
  • Cubemap Textures
  • Array Textures
  • Multisample Textures
  • Rectangle Textures
  • 3D Textures
  • Buffer Textures
  • Texture Views
• Asynchronous query objects
• Framebuffer Objects
  • Default Framebuffer
  • Renderbuffer Objects
• Unconventional objects:
  • Sync Objects
  • Shader and program objects

A texture is an OpenGL Object that contains one or more images that all have the same image format. A texture can be used in two ways: it can be the source of a texture access from a Shader, or it can be used as a render target.

Theory

For the purpose of this discussion, an image is defined as a single array of pixels of a certain dimensionality (1D, 2D, or 3D), with a particular size, and a specific format.

A texture is a container of one or more images. But textures do not store arbitrary images; a texture has specific constraints on the images it can contain. There are three defining characteristics of a texture, each of them defining part of those constraints: the texture type, texture size, and the image format used for images in the texture. The texture type defines the arrangement of images within the texture. The size defines the size of the images in the texture. And the image format defines the format that all of these images share.

There are a number of different types of textures. These are:

• GL_TEXTURE_1D: Images in this texture all are 1-dimensional. They have width, but no height or depth.
• GL_TEXTURE_2D: Images in this texture all are 2-dimensional. They have width and height, but no depth.
• GL_TEXTURE_3D: Images in this texture all are 3-dimensional. They have width, height, and depth.
• GL_TEXTURE_RECTANGLE: The image in this texture (only one image. No mipmapping) is 2-dimensional. Texture coordinates used for these textures are not normalized.
• GL_TEXTURE_BUFFER: The image in this texture (only one image. No mipmapping) is 1-dimensional. The storage for this data comes from a Buffer Object.
• GL_TEXTURE_CUBE_MAP: There are exactly 6 distinct sets of 2D images, each image being of the same size and must be of a square size. These images act as 6 faces of a cube.
• GL_TEXTURE_1D_ARRAY: Images in this texture all are 1-dimensional. However, it contains multiple sets of 1-dimensional images, all within one texture. The array length is part of the texture's size.
• GL_TEXTURE_2D_ARRAY: Images in this texture all are 2-dimensional. However, it contains multiple sets of 2-dimensional images, all within one texture. The array length is part of the texture's size.
• GL_TEXTURE_CUBE_MAP_ARRAY: Images in this texture are all cube maps. It contains multiple sets of cube maps, all within one texture. The array length * 6 (number of cube faces) is part of the texture size.
• GL_TEXTURE_2D_MULTISAMPLE: The image in this texture (only one image. No mipmapping) is 2-dimensional. Each pixel in these images contains multiple samples instead of just one value.
• GL_TEXTURE_2D_MULTISAMPLE_ARRAY: Combines 2D array and 2D multisample types. No mipmapping.

Texture sizes have a limit based on the GL implementation. For 1D and 2D textures (and any texture types that use similar dimensionality, like cubemaps) the max size of either dimension is GL_MAX_TEXTURE_SIZE. For array textures, the maximum array length is GL_MAX_ARRAY_TEXTURE_LAYERS. For 3D textures, no dimension can be greater than GL_MAX_3D_TEXTURE_SIZE in size.

Within these limits, the size of a texture can be any value. It is advised however, that you stick to powers-of-two for texture sizes, unless you have a significant need to use arbitrary sizes.

Mip maps

When a texture is directly applied to a surface, how many pixels of that texture (commonly called "texels") are used depends on the angle at which that surface is rendered. A texture mapped to a plane that is almost edge-on with the camera will only use a fraction of the pixels of the texture. Similarly, looking directly down on the texture from far away will show fewer texels than an up-close version.

The problem is with animation. When you slowly zoom out on a texture, you start to see aliasing artifacts appear. These are caused by sampling fewer than all of the texels; the choice of which texels are sampled changes between different frames of the animation. Even with linear filtering (see below), artifacts will appear as the camera zooms out.

To solve this problem, we employ mip maps. These are pre-shrunk versions of the full-sized image. Each mipmap is half the size (rounded down) of the previous one in the chain, continuing until all dimensions are 1. So a 64x16 2D texture can have 6 mip-maps: 32x8, 16x4, 8x2, 4x1, 2x1, and 1x1. OpenGL does not require that the entire mipmap chain is complete; you can specify what range of mipmaps in a texture are available.

Note that the division by 2 rounds down. So a 63x63 texture has as its next lowest mipmap level 31x31. And so on.

The base level of a mipmap chain is the largest one in size. It is also the one that defines the full size of the texture. OpenGL numbers this mipmap level as 0; the next largest mipmap level is 1, and so on.

Some texture types have multiple conceptually independent sets of mipmaps. Each face of a cubemap has its own set of mipmaps, as does each entry in an array texture. However, while the chains are conceptually independent, there is only one mipmap setting per-texture. So all of the mipmap chains in a texture must have the same number of mipmaps.

When sampling a texture (see below), the implementation will automatically select which mipmap to use based on the viewing angle, size of texture, and various other factors.

The base level of a texture does not have to be loaded. The valid range of mipmaps must be contiguous, but the range need not start at 0.

Texture Objects

Diagram of the contents of a texture object

Textures in OpenGL are OpenGL Objects, and they follow the standard conventions of such. So they have the standard glGenTextures, glBindTexture, as you would expect.

The target parameter of glBindTexture corresponds to the texture's type. So when you use a freshly generated texture name, the first bind helps define the type of the texture. It is not legal to bind an object to a different target than the one it was previously bound with. So if you generate a texture and bind it as GL_TEXTURE_1D, then you must continue to bind it as such.

As with any other kind of OpenGL object, it is legal to bind multiple objects to different targets. So you can have a GL_TEXTURE_1D bound while a GL_TEXTURE_2D_ARRAY is bound.

Texture completeness

A texture object has the concept of "completeness". A complete texture object is one which is in a logical state to be used for many operations. Until a texture is complete, it *cannot* be used in shader sampling or Image Load Store operations. And attaching an image from a texture to a Framebuffer Object requires certain forms of completeness.

A texture object is complete if it fulfills the following 3 kinds of completeness requirements.

Mipmap completeness

Mipmap completeness essentially requires that there is consistency between the image formats of the allocated mipmap levels, the texture parameters, and the texture's sampling parameters.

Textures that use storage allocated with immutable storage functions (and Buffer Textures) will always be mipmap complete. For other textures, the following rules apply.

If the texture's sampling parameter GL_TEXTURE_MIN_FILTER specifies that it uses mipmaps, then the following must all be true:

• Each mipmap level must use the exact same internal format.
• Each allocated mipmap level must have a consistent size, relative to the one before it. The width/height/depth of a mipmap level is the width/height/depth of the base level / 2^k, where k is the mipmap level (remember: 0 is the base level). Remember to round down, and that the minimum size is 1.
  • 1D Array Textures have a width​ and height​. But the height​ specifies the number of array layers in the array of 1D textures. Therefore, the height​ does not change with mipmap levels. Each mipmap level uses the same height​. The same goes for 2D Array textures and Cubemap Array textures with the depth​ parameter.
• The mipmap range texture parameters are given values where GL_TEXTURE_BASE_LEVEL <= GL_TEXTURE_MAX_LEVEL.
• The base and max levels must only specify mipmap levels that have been allocated, in accord with the above.

Mipmap completion only applies if the minification filtering parameters use mipmaps. If it does not, then the texture is always mipmap complete.

Cubemap completeness

Cubemap Textures have additional requirements, due to how they are allocated (with mutable storage functions). Textures that use storage allocated with immutable storage functions will always be cubemap complete. For other textures, the following rules apply:

• For each mipmap level, each face of a cubemap must have the same size. And that size must be square.
• For each mipmap level, each face of a cubemap must have the same internal format.

Image format completeness

The internal format a texture uses can also affect its completeness, depending on its sampling parameters.

Integer color formats and stencil index formats (whether GL_STENCIL_INDEX directly or via Stencil Texturing) do not support linear filtering. As such, the GL_TEXTURE_MAG_FILTER sampling parameter must be GL_NEAREST, and GL_TEXTURE_MIN_FILTER must be either GL_NEAREST or GL_NEAREST_MIPMAP_NEAREST.

Sampler objects and completeness

When using a texture with a Sampler Object, the completeness of that texture will be based on the sampler object's sampling parameters, rather than the internal sampling parameters of the texture.

For example, if a texture object only has the base mipmap, and the mipmap range parameters permit accessing beyond the base level, that texture object will be incomplete if the GL_TEXTURE_MIN_FILTER parameters require access to mipmaps other than the base level. However, if you pair this object with a sampler who's min filter is GL_LINEAR or GL_NEAREST, then that texture image unit will be mipmap complete.

Similarly, if a texture uses an integer Image Format, and the paired sampler only uses nearest filtering, the texture will be image format complete.

So a texture may be considered complete or not, based on where it is used.

Image Load Store does not use sampler objects. But it still performs texture completeness checks. So it will apply the completeness rules based on the texture's internal sampling parameters, not those of a sampler object.

Storage

Main article: Texture Storage

Texture objects come in three parts: storage, sampling parameters, and texture parameters. There are numerous functions to create a texture's storage; so many that the article needs its own page to describe them all.

Parameters

Texture objects have parameters. These parameters control many aspects of how the texture functions.

Texture parameters are set with the following functions:

void glTexParameter[if]( GLenum target​, GLenum pname​, T param​);

void glTexParameter[if]v( GLenum target​, GLenum pname​, T *params​ );

void glTexParameterI[i ui]v( GLenum target​, GLenum pname​, T *params​ );

These function set the parameter values param​ or params​ for the particular parameter pname​ in the texture bound to target​.

In the anatomy of a texture object image above, it shows three pieces of data: Texture Storage, texture parameters, and sampling parameters. It's important to understand that both of the last two kinds of data are set by the same functions for textures. Certain parameters are about the texture itself, and some are about sampling from them.

This section will describe the texture parameters only.

Mipmap range

The parameters GL_TEXTURE_BASE_LEVEL and GL_TEXTURE_MAX_LEVEL (integer values) define the closed range of the mipmaps that are to be considered available with this texture. Nothing can cause the sampling of mipmaps smaller than GL_TEXTURE_BASE_LEVEL and nothing can cause the sampling of mipmaps greater than GL_TEXTURE_MAX_LEVEL. This even filters into GLSL; the texture size functions will retrieve the size of GL_TEXTURE_BASE_LEVEL, rather than the size of mipmap level 0.

Note that immutable storage textures will already have these values set to the mipmap range of the storage upon creation. You can set them to be some subrange of this, but it is an error to set the base or max level outside of the available mipmap range for the immutable storage.

Swizzle mask

Texture Swizzle

Core in version		4.6
Core since version		3.3
ARB extension	ARB_texture_swizzle
EXT extension	EXT_texture_swizzle

While GLSL shaders are perfectly capable of reordering the vec4 value returned by a texture function, it is often more convenient to control the ordering of the data fetched from a texture from code. This is done through swizzle parameters.

Texture objects can have swizzling parameters. This only works for textures with color image formats. Each of the four output components, RGBA, can be set to come from a particular color channel. The swizzle mask is respected by all shader read accesses, whether via texture samplers or Image Load Store.

Note: This feature only applies to reads from the shader. Writes via Image Load Store are not affected by the swizzle mask. Also, are reads or writes from other sources, such as Blending operations, do not respect the swizzle mask.

To set the output for a component, you would set the GL_TEXTURE_SWIZZLE_C texture parameter, where C is R, G, B, or A. These parameters can be set to the following values:

• GL_RED: The value for this component comes from the red channel of the image. All color formats have at least a red channel.
• GL_GREEN: The value for this component comes from the green channel of the image, or 0 if it has no green channel.
• GL_BLUE: The value for this component comes from the blue channel of the image, or 0 if it has no blue channel.
• GL_ALPHA: The value for this component comes from the alpha channel of the image, or 1 if it has no alpha channel.
• GL_ZERO: The value for this component is always 0.
• GL_ONE: The value for this component is always 1.

You can also use the GL_TEXTURE_SWIZZLE_RGBA parameter to set all four at once. This one takes an array of four values. For example:

// Bind the texture 2D.
GLint swizzleMask[] = {GL_ZERO, GL_ZERO, GL_ZERO, GL_RED};
glTexParameteriv(GL_TEXTURE_2D, GL_TEXTURE_SWIZZLE_RGBA, swizzleMask);

This will effectively map the red channel in the image to the alpha channel when the shader accesses it.

Stencil texturing

Stencil Texturing

Core in version		4.6
Core since version		4.3
Core ARB extension	ARB_stencil_texturing

A texture with a depth image format is normally considered a depth component texture. This means that non-depth comparison access will return a single floating-point value (as depth components are either normalized integers or floats). Depth textures in this way can be considered a special form of single-channel floating-point color textures.

However, if the texture uses a packed depth/stencil image format, it is possible to access the stencil component instead of the depth component. This is controlled by the parameter GL_DEPTH_STENCIL_TEXTURE_MODE.

When the parameter is set to GL_DEPTH_COMPONENT, then accessing it from the shader will access the depth component as a single float, as normal. But when the parameter is set to GL_STENCIL_INDEX, the shader can access the stencil component.

This parameter changes the very nature of the texture access. The stencil component is an unsigned integer value, so you must use an unsigned integer sampler when accessing it. So when accessing the stencil component of a 2D depth/stencil texture, you must use usampler2D.

Note: Though this parameter affects sampling, it is not a sampling parameter. As such, you cannot bind the same texture object to two image units and use two different sampler objects to fetch the depth and stencil components. However, you can create a view of the texture (both view textures and stencil texturing are GL 4.3 features), and set different texture parameters into the different views. One view for the depth, one view for the stencil.

Sampling parameters

Main article: Sampler Object#Sampling parameters

Sampling is the process of fetching a value from a texture at a given position. GLSL controls much of the process of sampling, but there are many values associated with the texture object that can affect this as well.

These parameters are shared with Sampler Objects, in that both texture objects and sampler objects have them. If a texture is used with a sampler object, all of the parameters from the sampler object override those set by the texture object.

Texture image units

Much like with Buffer Objects and indexed targets, a texture can be bound to one or more locations for rendering. These locations are called texture image units. OpenGL contexts have a maximum number of texture image units, queryable from the constant GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS.

Textures can be bound to these textures units with this function:

void glBindTextureUnit(GLuint unit​, GLuint texture​);

Where unit​ is the 0-indexed texture unit you'd like to bind to, and texture​ is the texture object you'd like to bind there (or zero to unbind it).

glBindTextureUnit is a DSA function, so if you don't have access to this you can also use the older active texture unit API:

void glActiveTexture(GLenum texture​);

Which specifies which texture unit a glBindTexture call should bind the texture object to, and defines the active texture unit that any subsequent function that takes a texture target should use. texture​ isn't a simple index as in glBindTextureUnit, but one of a consecutive set of enums starting from GL_TEXTURE0 - commonly written as GL_TEXTURE0 + unit​.

Put simply, where with DSA you would write:

glBindTextureUnit(0, texture1);
glBindTextureUnit(1, texture2);
glBindTextureUnit(2, texture3);

You would instead previously have written:

glActiveTexture(GL_TEXTURE0 + 0);
glBindTexture(GL_TEXTURE_2D, texture1);

glActiveTexture(GL_TEXTURE0 + 1);
glBindTexture(GL_TEXTURE_3D, texture2);

glActiveTexture(GL_TEXTURE0 + 2);
glBindTexture(GL_TEXTURE_2D, texture3);

Noting that not only are there more calls and that there's some strangeness around GL_TEXTURE0s usage, but that you also must ensure to bind to the correct target​ as well. glBindTextureUnit not only combines these calls, but derives the correct targets from the texture objects you bind, avoiding potential errors.

Each texture image unit supports bindings to all targets. So a 2D texture and an array texture can be bound to the same image unit, or different 2D textures can be bound in two different image units without affecting each other. So which texture gets used when rendering? In GLSL, this depends on the type of sampler that uses this texture image unit.

Note: This sounds suspiciously like you can use the same texture image unit for different samplers, as long as they have different texture types. Do not do this. The spec explicitly disallows it; if two different GLSL samplers have different texture types, but are associated with the same texture image unit, then rendering will fail. Give each sampler a different texture image unit.

GLSL binding

Shader programs are one of two uses of textures. In order to use textures with a program, the program itself must use certain syntax to expose texture binding points.

Samplers

Main article: Sampler (GLSL)

A sampler in GLSL is a uniform variable that represents an accessible texture. It cannot be set from within a program; it can only be set by the user of the program. Sampler types correspond to OpenGL texture types.

Samplers are used with GLSL texture access functions.

The process of using textures with program samplers involves 2 halves. Texture objects are not directly associated with or attached to program objects. Instead, program samplers reference texture image unit indices. Whatever textures are bound to those image units at the time of rendering are used by the program.

So the first step is to set the uniform value for the program samplers. For each sampler uniform, set its uniform value to an integer on the range [0, GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS). When the time comes to use the program directly, simply use glActiveTexture and glBindTexture to bind the textures of interest to these image units.

The textures bound to the image unit set in the sampler uniforms must match the sampler's type. So a sampler1D will look to the GL_TEXTURE_1D binding in the image unit it is set in.

If a Sampler Object is bound to the same texture image unit as a texture, then the sampler object's parameters will replace the sampling parameters from that texture object.

Images

Main article: Image Load Store

Images within a texture can be used for arbitrary image load/store operations. This is done via image variables, which are declared as uniforms. Image uniforms are associated with an image unit (different from a texture image unit). The association works similarly as for sampler uniforms, only the number of image units per shader stage is different from the number of texture image units per shader stage.

Images are bound to image units with glBindImageTexture.

Render targets

Main article: Framebuffer Objects

Through the use of a framebuffer object, individual images within a texture can be the destination for rendering.

Reference

• Category:Core API Ref Texturing‎: Reference documentation for all functions related to textures and sampler objects.