Array Texture

From OpenGL Wiki
Revision as of 09:34, 18 April 2014 by Jiawen (talk | contribs) (Clarified how texture arrays are accessed in GLSL.)
Jump to navigation Jump to search
Array Texture
Core in version 4.6
Core since version 3.0
EXT extension EXT_texture_array

An Array Texture is a Texture where each mipmap contains a series of 1D or 2D images of the same size. Array textures are structurally similar to 3D Textures in that they have an effective "depth" component. However, filtering never takes place between the separate textures in the array, and lower mipmaps still have the same number of array layers.

Pre OpenGL 3.0, the high cost of texture switches resulted in a widespread preference for texture atlases, which result in less switching, and thus less overhead. 3.0 capable hardware attempts to overcome this by providing fast hardware texture switching capabilities in the form of array textures; but be aware that if you are limited by the number of hardware texture units, you may still be better off using atlases (perhaps even in conjunction with array textures).

Array texture are not usable from the fixed function pipeline; you must use a Shader to access them.


Each mipmap level of an array texture is a series of images. Each image within a mipmap is called a "layer".

Creation and Management

1D array textures are created by binding a newly-created texture object to GL_TEXTURE_1D_ARRAY, then creating storage for one or more mipmaps of the texture. This is done by using the "2D" image functions; the "height​" parameter sets the number of layers in the array texture.

Every row of pixel data in the "2D" array of pixels is considered a separate 1D layer.

2D array textures are created similarly; bind a newly-created texture object to GL_TEXTURE_2D_ARRAY, then use the "3D" image functions to allocate storage. The depth​ parameter sets the number of layers in the array.

Each 2D row/column sequence of pixel data in the "3D" array of pixels is considered a separate 2D layer.

Here is a source-code example:

This example code shows how to create a 2D array texture.

GLuint texture = 0;

GLsizei width = 2;
GLsizei height = 2;
GLsizei layerCount = 2;
GLsizei mipLevelCount = 1;

// Read you texels here. In the current example, we have 2*2*2 = 8 texels, with each texel being 4 GLubytes.
GLubyte texels[32] = 
     // Texels for first image.
     0,   0,   0,   255,
     255, 0,   0,   255,
     0,   255, 0,   255,
     0,   0,   255, 255,
     // Texels for second image.
     255, 255, 255, 255,
     255, 255,   0, 255,
     0,   255, 255, 255,
     255, 0,   255, 255,

// Allocate the storage.
glTexStorage3D(GL_TEXTURE_2D_ARRAY, mipLevelCount, GL_RGBA8, width, height, layerCount);
// Upload pixel data.
// The first 0 refers to the mipmap level (level 0, since there's only 1)
// The following 2 zeroes refers to the x and y offsets in case you only want to specify a subrectangle.
// The final 0 refers to the layer index offset (we start from index 0 and have 2 levels).
// Altogether you can specify a 3D box subset of the overall texture, but only one mip level at a time.
glTexSubImage3D(GL_TEXTURE_2D_ARRAY, 0, 0, 0, 0, width, height, layerCount, GL_RGBA, GL_UNSIGNED_BYTE, texels);

// Always set reasonable texture parameters

Note that, unlike for 3D Textures, each mipmap uses the same number of layers. So if you're allocating 3 mipmaps of a 2D array texture, it would look like this:

glBindTexture(GL_TEXTURE_2D_ARRAY, tex);
glTexImage3D(GL_TEXTURE_2D_ARRAY, 0, format, width, height, num_layers, ...);
glTexImage3D(GL_TEXTURE_2D_ARRAY, 1, format, width/2, height/2, num_layers, ...);
glTexImage3D(GL_TEXTURE_2D_ARRAY, 2, format, width/4, height/4, num_layers, ...);

Access in shaders

Texture arrays have separate sampler types: sampler1DArray and sampler2DArray. When accessing them within a shader, you use one extra texture coordinate. So sampler1DArray would use a 2D texture coordinate, while sampler2DArray would use a 3D texture coordinate.

The last coordinate is the layer number to access. For floating-point texture coordinates (when not using texture functions like texelFetch), the floating-point layer is rounded then clamped to compute the integer layer index by the following function:

actual_layer = max(0, min(d​ - 1, floor(layer​ + 0.5)) )

Here, d​ is the number of layers in the texture, and layer​ is the floating-point layer from the texture coordinate. For example, to sample at s = 0.4, t = 0.6, for layer 2, use vec3(0.4, 0.6, 2).

Cubemap arrays

Cubemap textures can come in arrays, if OpenGL 4.0 or ARB_texture_cube_map_array is defined.