Difference between revisions of "Array Texture"

From OpenGL.org
Jump to: navigation, search
(No longer a stub.)
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
'''Array Textures''' are textures that are a sequence of 1D or 2D textures of the same size. Array textures are similar to [[3D Textures]] in that they have an effective "depth" component. However, filtering never takes place between the separate textures in the array.
+
{{ infobox feature
 +
| core = 3.0
 +
| ext_extension = {{extref|texture_array|EXT}}
 +
}}
  
Array texture are not usable from the fixed function pipeline. To use them, you have to use an assembly or GLSL shader. Therefore it is invalid to call:
+
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.
  
glEnable(GL_TEXTURE_2D_ARRAY);
+
Array texture are not usable from the fixed function pipeline; you must use a [[Shader]] to access them.
  
or
+
== Terminology ==
  
glDisable(GL_TEXTURE_2D_ARRAY);
+
Each mipmap level of an array texture is a series of images. Each image within a mipmap is called a "layer".
  
and will result in the OpenGL error flag being set to GL_INVALID_ENUM.
+
== Creation and Management ==
  
To bind and initialize a texture object as an array texture in a typical case, you should write:
+
1D array textures are created by binding a newly-created texture object to {{enum|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 "{{param|height}}" parameter sets the number of layers in the array texture.
<pre>
+
  
GLuint texture = 0;
+
Every row of pixel data in the "2D" array of pixels is considered a separate 1D layer.
  
//Set this to the preferred texture width.
+
2D array textures are created similarly; bind a newly-created texture object to {{enum|GL_TEXTURE_2D_ARRAY}}, then use the "3D" image functions to allocate storage. The {{param|depth}} parameter sets the number of layers in the array.
  
GLuint width = 2;
+
Each 2D row/column sequence of pixel data in the "3D" array of pixels is considered a separate 2D layer.
  
//Set this to the preferred texture height.
+
Here is a source-code example:
  
 +
<source lang="c">
 +
GLuint texture = 0;
 +
 +
GLuint width = 2;
 
GLuint height = 2;
 
GLuint height = 2;
 +
GLuint levelCount= 2;
  
//Set this to the preferred texture slice count.
+
//Read you texels here. In the current example, we have 2*2*2 = 8 texels, with each texel being 4 GLubytes.
 
+
GLubyte texels[32] =  
GLuint sliceCount = 2;
+
{
 
+
    //Texels for first image.
//Read you texels here. In the current example, we have 2*2*2*4=32 texels.
+
    0,   0,   0,   255,
 
+
    255, 0,   0,   255,
GLfloat texels[32] =  
+
    0,   255, 0,   255,
 
+
    0,   0,   255, 255,
<nowiki>{</nowiki>
+
    //Texels for second image.
 
+
    255, 255, 255, 255,
<nowiki>    //Texels for first image. </nowiki>
+
    255, 255,   0, 255,
 
+
    0,   255, 255, 255,
<nowiki>    0.0,0.0,0.0,1.0,</nowiki>
+
    255, 0,   255, 255,
 
+
};
<nowiki>    1.0,0.0,0.0,1.0,</nowiki>
+
 
+
<nowiki>    0.0,1.0,0.0,1.0,</nowiki>
+
 
+
<nowiki>    0.0,0.0,1.0,1.0,</nowiki>
+
 
+
<nowiki>    //Texels for second image.</nowiki>
+
 
+
<nowiki>    1.0,1.0,1.0,1.0,</nowiki>
+
 
+
<nowiki>    1.0,1.0,0.0,1.0,</nowiki>
+
 
+
<nowiki>    0.0,1.0,1.0,1.0,</nowiki>
+
 
+
<nowiki>    1.0,0.0,1.0,1.0</nowiki>
+
 
+
<nowiki>};</nowiki>
+
  
 
glGenTextures(1,&texture);
 
glGenTextures(1,&texture);
 
 
glBindTexture(GL_TEXTURE_2D_ARRAY,texture);
 
glBindTexture(GL_TEXTURE_2D_ARRAY,texture);
 
+
glTexParameteri(GL_TEXTURE_2D_ARRAY,GL_TEXTURE_MIN_FILTER,GL_LINEAR); //Always set reasonable texture parameters
glTexParameteri(GL_TEXTURE_2D_ARRAY,GL_TEXTURE_MIN_FILTER,GL_LINEAR);
+
 
+
 
glTexParameteri(GL_TEXTURE_2D_ARRAY,GL_TEXTURE_MAG_FILTER,GL_LINEAR);
 
glTexParameteri(GL_TEXTURE_2D_ARRAY,GL_TEXTURE_MAG_FILTER,GL_LINEAR);
 
 
glTexParameteri(GL_TEXTURE_2D_ARRAY,GL_TEXTURE_WRAP_S,GL_CLAMP_TO_EDGE);
 
glTexParameteri(GL_TEXTURE_2D_ARRAY,GL_TEXTURE_WRAP_S,GL_CLAMP_TO_EDGE);
 
 
glTexParameteri(GL_TEXTURE_2D_ARRAY,GL_TEXTURE_WRAP_T,GL_CLAMP_TO_EDGE);
 
glTexParameteri(GL_TEXTURE_2D_ARRAY,GL_TEXTURE_WRAP_T,GL_CLAMP_TO_EDGE);
 +
glTexImage3D(GL_TEXTURE_2D_ARRAY, 0, GL_RGBA8, width, height, levelCount, 0, GL_RGBA, GL_UNSIGNED_BYTE, texels);
 +
</source>
 +
 +
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:
  
glTexImage3D(GL_TEXTURE_2D_ARRAY,0,GL_RBGA,width,height,sliceCount,0,GL_RGBA,GL_FLOAT,texels);
+
<source lang="cpp">
 +
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, ...);
 +
</source>
  
</pre>
+
== Access in shaders ==
 +
{{main|GLSL Sampler}}
  
To declare a GLSL sampler for texture arrays:
+
Texture arrays have separate sampler types: {{code|sampler1DArray}} and {{code|sampler2DArray}}. When accessing them within a shader, you use one extra texture coordinate. So {{code|sampler1DArray}} would use a 2D texture coordinate, while {{code|sampler2DArray}} would use a 3D texture coordinate.
  
<pre>
+
The last coordinate is the layer number to access. For floating-point texture coordinates (when not using texture functions like [[GLSL_Sampler#Direct_texel_fetches|{{code|texelFetch}}]]), the floating-point layer is used to compute the integer layer index by the following function:
uniform sampler2DArray textureName;
+
</pre>
+
  
to read from the sampler, write:
+
actual_layer = max(0, min({{param|d}} - 1, floor({{param|layer}} + 0.5)) )
  
<pre>
+
Here, {{param|d}} is the number of layers in the texture, and {{param|layer}} is the floating-point layer from the texture coordinate.
vec4 color = texture2DArray(textureName,texCoord.xyz);
+
</pre>
+
  
where texCoord.xy contains s,t for the 2D image texture coordinates and texCoord.z contains the array index of the texture. s and t are in the range of [0..1] (floating point), array index is in the range of [0..number of texture array slices-1] (floating point rounded to nearest integer).
+
== Cubemap arrays ==
 +
{{main|Cubemap_Texture#Cubemap_array_textures}}
  
{{stub}}
+
Cubemap textures can come in arrays, if OpenGL 4.0 or {{extref|texture_cube_map_array}} is defined.
  
 
[[Category:Textures]]
 
[[Category:Textures]]

Revision as of 14:53, 10 September 2012

Array Texture
Core in version 4.5
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.

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

Terminology

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:

GLuint texture = 0;
 
GLuint width = 2;
GLuint height = 2;
GLuint levelCount= 2;
 
//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,
};
 
glGenTextures(1,&texture);
glBindTexture(GL_TEXTURE_2D_ARRAY,texture);
glTexParameteri(GL_TEXTURE_2D_ARRAY,GL_TEXTURE_MIN_FILTER,GL_LINEAR); //Always set reasonable texture parameters
glTexParameteri(GL_TEXTURE_2D_ARRAY,GL_TEXTURE_MAG_FILTER,GL_LINEAR);
glTexParameteri(GL_TEXTURE_2D_ARRAY,GL_TEXTURE_WRAP_S,GL_CLAMP_TO_EDGE);
glTexParameteri(GL_TEXTURE_2D_ARRAY,GL_TEXTURE_WRAP_T,GL_CLAMP_TO_EDGE);
glTexImage3D(GL_TEXTURE_2D_ARRAY, 0, GL_RGBA8, width, height, levelCount, 0, GL_RGBA, GL_UNSIGNED_BYTE, texels);

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

Cubemap arrays

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