TexturesGL 1.2

glTexImage3D

Allocates (and optionally fills) a texture with depth: a 3D volume or an array of 2D layers.

Signature

void glTexImage3D(GLenum target, GLint level, GLint internalformat,
                  GLsizei width, GLsizei height, GLsizei depth, GLint border,
                  GLenum format, GLenum type, const void *data);

How it works

glTexImage2D with one more dimension. What depth means depends on the target:

GL_TEXTURE_3D: a true volume, filtered in all three directions. Used for colour-grading lookup tables, fog and cloud densities. GL_TEXTURE_2D_ARRAY: depth separate 2D layers of the same size, never blended into each other. The shader picks one with the third coordinate. Cascaded shadow maps keep every cascade in one, and a terrain can keep all its materials in one.

Parameters

targetGLenum

GL_TEXTURE_3D or GL_TEXTURE_2D_ARRAY (also GL_TEXTURE_CUBE_MAP_ARRAY).

levelGLint

Mip level, 0 for the base.

internalformatGLint

Sized GPU format: GL_RGBA8, GL_DEPTH_COMPONENT32F…

width, heightGLsizei

Size of each slice or layer.

depthGLsizei

Number of slices (3D) or layers (array).

borderGLint

Must be 0.

format, typeGLenum

Layout and type of your data, as in glTexImage2D.

dataconst void *

All slices one after another, or nullptr to only allocate.

Tips & pitfalls

Fill single layers later with glTexSubImage3D, or render into them with glFramebufferTextureLayer.
glTexStorage3D allocates immutable storage with all mip levels, like glTexStorage2D does for 2D.

Errors

When the call is invalid it does nothing and sets an error, which glGetError returns:

GL_INVALID_VALUE: A size is negative or larger than GL_MAX_3D_TEXTURE_SIZE / GL_MAX_ARRAY_TEXTURE_LAYERS, or border is not 0.

Example

example.cpp

1// one depth layer per shadow cascade
2glBindTexture(GL_TEXTURE_2D_ARRAY, shadowArray);
3glTexImage3D(GL_TEXTURE_2D_ARRAY, 0, GL_DEPTH_COMPONENT32F, size, size, cascades, 0,
4             GL_DEPTH_COMPONENT, GL_FLOAT, nullptr);

Official Khronos documentation