GLAPI/glTexStorage3D

glTexStorage3D

Core in version		4.6
Core since version		4.2
Core ARB extension	ARB_texture_storage

glTexStorage3D: simultaneously specify storage for all levels of a three-dimensional, two-dimensional array or cube-map array texture

Function Definition

 void glTexStorage3D(GLenum target​, GLsizei levels​, GLenum internalformat​, GLsizei width​, GLsizei height​, GLsizei depth​);

target

Specify the target of the operation. target​ must be one of GL_TEXTURE_3D, GL_PROXY_TEXTURE_3D, GL_TEXTURE_2D_ARRAY, GL_PROXY_TEXTURE_2D_ARRAY, GL_TEXTURE_CUBE_MAP_ARRAY, or GL_PROXY_TEXTURE_CUBE_ARRAY.

levels

Specify the number of texture levels.

internalformat

Specifies the sized internal format to be used to store texture image data.

width

Specifies the width of the texture, in texels.

height

Specifies the height of the texture, in texels.

depth

Specifies the depth of the texture, in texels.

Description

glTexStorage3D specifies the storage requirements for all levels of a three-dimensional, two-dimensional array or cube-map array texture simultaneously. Once a texture is specified with this command, the format and dimensions of all levels become immutable unless it is a proxy texture. The contents of the image may still be modified, however, its storage requirements may not change. Such a texture is referred to as an immutable-format texture.

The behavior of glTexStorage3D depends on the target​ parameter. When target​ is GL_TEXTURE_3D, or GL_PROXY_TEXTURE_3D, calling glTexStorage3D is equivalent, assuming no errors are generated, to executing the following pseudo-code:

for (i = 0; i < levels; i++)
{
    glTexImage3D(target, i, internalformat, width, height, depth, 0, format, type, NULL);
    width = max(1, (width / 2));
    height = max(1, (height / 2));
    depth = max(1, (depth / 2));
}

When target​ is GL_TEXTURE_2D_ARRAY, GL_PROXY_TEXTURE_2D_ARRAY, GL_TEXTURE_CUBE_MAP_ARRAY, or GL_PROXY_TEXTURE_CUBE_MAP_ARRAY, glTexStorage3D is equivalent to:

for (i = 0; i < levels; i++)
{
    glTexImage3D(target, i, internalformat, width, height, depth, 0, format, type, NULL);
    width = max(1, (width / 2));
    height = max(1, (height / 2));
}

Since no texture data is actually provided, the values used in the pseudo-code for format​ and type​ are irrelevant and may be considered to be any values that are legal for the chosen internalformat​ enumerant. internalformat​ must be one of the internal formats given in the tables below.

Upon success, the value of GL_TEXTURE_IMMUTABLE_FORMAT becomes GL_TRUE. The value of GL_TEXTURE_IMMUTABLE_FORMAT may be discovered by calling glGetTexParameter with pname set to GL_TEXTURE_IMMUTABLE_FORMAT. No further changes to the dimensions or format of the texture object may be made. Using any command that might alter the dimensions or format of the texture object (such as glTexImage3D or another call to glTexStorage3D) will result in the generation of a GL_INVALID_OPERATION error, even if it would not, in fact, alter the dimensions or format of the object.

Sized Internal Formats

		Component Bitdepth
Sized Internal Format	Base Internal Format	Red	Green	Blue	Alpha	Shared
GL_R8	GL_RED	8
GL_R8_SNORM	GL_RED	s8
GL_R16	GL_RED	16
GL_R16_SNORM	GL_RED	s16
GL_RG8	GL_RG	8	8
GL_RG8_SNORM	GL_RG	s8	s8
GL_RG16	GL_RG	16	16
GL_RG16_SNORM	GL_RG	s16	s16
GL_R3_G3_B2	GL_RGB	3	3	2
GL_RGB4	GL_RGB	4	4	4
GL_RGB5	GL_RGB	5	5	5
GL_RGB8	GL_RGB	8	8	8
GL_RGB8_SNORM	GL_RGB	s8	s8	s8
GL_RGB10	GL_RGB	10	10	10
GL_RGB12	GL_RGB	12	12	12
GL_RGB16_SNORM	GL_RGB	16	16	16
GL_RGBA2	GL_RGB	2	2	2	2
GL_RGBA4	GL_RGB	4	4	4	4
GL_RGB5_A1	GL_RGBA	5	5	5	1
GL_RGBA8	GL_RGBA	8	8	8	8
GL_RGBA8_SNORM	GL_RGBA	s8	s8	s8	s8
GL_RGB10_A2	GL_RGBA	10	10	10	2
GL_RGB10_A2UI	GL_RGBA	ui10	ui10	ui10	ui2
GL_RGBA12	GL_RGBA	12	12	12	12
GL_RGBA16	GL_RGBA	16	16	16	16
GL_SRGB8	GL_RGB	8	8	8
GL_SRGB8_ALPHA8	GL_RGBA	8	8	8	8
GL_R16F	GL_RED	f16
GL_RG16F	GL_RG	f16	f16
GL_RGB16F	GL_RGB	f16	f16	f16
GL_RGBA16F	GL_RGBA	f16	f16	f16	f16
GL_R32F	GL_RED	f32
GL_RG32F	GL_RG	f32	f32
GL_RGB32F	GL_RGB	f32	f32	f32
GL_RGBA32F	GL_RGBA	f32	f32	f32	f32
GL_R11F_G11F_B10F	GL_RGB	f11	f11	f10
GL_RGB9_E5	GL_RGB	9	9	9		5
GL_R8I	GL_RED	i8
GL_R8UI	GL_RED	ui8
GL_R16I	GL_RED	i16
GL_R16UI	GL_RED	ui16
GL_R32I	GL_RED	i32
GL_R32UI	GL_RED	ui32
GL_RG8I	GL_RG	i8	i8
GL_RG8UI	GL_RG	ui8	ui8
GL_RG16I	GL_RG	i16	i16
GL_RG16UI	GL_RG	ui16	ui16
GL_RG32I	GL_RG	i32	i32
GL_RG32UI	GL_RG	ui32	ui32
GL_RGB8I	GL_RGB	i8	i8	i8
GL_RGB8UI	GL_RGB	ui8	ui8	ui8
GL_RGB16I	GL_RGB	i16	i16	i16
GL_RGB16UI	GL_RGB	ui16	ui16	ui16
GL_RGB32I	GL_RGB	i32	i32	i32
GL_RGB32UI	GL_RGB	ui32	ui32	ui32
GL_RGBA8I	GL_RGBA	i8	i8	i8	i8
GL_RGBA8UI	GL_RGBA	ui8	ui8	ui8	ui8
GL_RGBA16I	GL_RGBA	i16	i16	i16	i16
GL_RGBA16UI	GL_RGBA	ui16	ui16	ui16	ui16
GL_RGBA32I	GL_RGBA	i32	i32	i32	i32
GL_RGBA32UI	GL_RGBA	ui32	ui32	ui32	ui32

Sized Depth and Stencil Internal Formats

		Component Bitdepth
Sized Internal Format	Base Internal Format	Depth	Stencil
GL_DEPTH_COMPONENT16	GL_DEPTH_COMPONENT	16
GL_DEPTH_COMPONENT24	GL_DEPTH_COMPONENT	24
GL_DEPTH_COMPONENT32	GL_DEPTH_COMPONENT	32
GL_DEPTH_COMPONENT32F	GL_DEPTH_COMPONENT	f32
GL_DEPTH24_STENCIL8	GL_DEPTH_STENCIL	24	8
GL_DEPTH32F_STENCIL8	GL_DEPTH_STENCIL	f32	8
GL_STENCIL_INDEX8	GL_STENCIL_INDEX		8

Compressed Internal Formats

Compressed Internal Format	Base Internal Format	Type
GL_COMPRESSED_RED	GL_RED	Generic
GL_COMPRESSED_RG	GL_RG	Generic
GL_COMPRESSED_RGB	GL_RGB	Generic
GL_COMPRESSED_RGBA	GL_RGBA	Generic
GL_COMPRESSED_SRGB	GL_RGB	Generic
GL_COMPRESSED_SRGB_ALPHA	GL_RGBA	Generic
GL_COMPRESSED_RED_RGTC1	GL_RED	Specific
GL_COMPRESSED_SIGNED_RED_RGTC1	GL_RED	Specific
GL_COMPRESSED_RG_RGTC2	GL_RG	Specific
GL_COMPRESSED_SIGNED_RG_RGTC2	GL_RG	Specific
GL_COMPRESSED_RGBA_BPTC_UNORM	GL_RGBA	Specific
GL_COMPRESSED_SRGB_ALPHA_BPTC_UNORM	GL_RGBA	Specific
GL_COMPRESSED_RGB_BPTC_SIGNED_FLOAT	GL_RGB	Specific
GL_COMPRESSED_RGB_BPTC_UNSIGNED_FLOAT	GL_RGB	Specific
S3TC formats
GL_COMPRESSED_RGB_S3TC_DXT1_EXT	GL_RGB	Specific
GL_COMPRESSED_SRGB_S3TC_DXT1_EXT	GL_RGB	Specific
GL_COMPRESSED_RGBA_S3TC_DXT1_EXT	GL_RGBA	Specific
GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT1_EXT	GL_RGBA	Specific
GL_COMPRESSED_RGBA_S3TC_DXT3_EXT	GL_RGBA	Specific
GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT3_EXT	GL_RGBA	Specific
GL_COMPRESSED_RGBA_S3TC_DXT5_EXT	GL_RGBA	Specific
GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT	GL_RGBA	Specific

Errors

GL_INVALID_ENUM is generated if internalformat​ is not a valid sized internal format.

GL_INVALID_ENUM is generated if target​ is not one of the accepted target enumerants.

GL_INVALID_VALUE is generated if width​ or levels​ are less than 1.

GL_INVALID_OPERATION is generated if target​ is GL_TEXTURE_3D or GL_PROXY_TEXTURE_3D and levels​ is greater than $\left\lfloor \log _{2}(max(width,height,depth))\right\rfloor +1$.

GL_INVALID_OPERATION is generated if target​ is GL_TEXTURE_2D_ARRAY, GL_PROXY_TEXTURE_2D_ARRAY, GL_TEXURE_CUBE_MAP_ARRAY, or GL_PROXY_TEXTURE_CUBE_MAP_ARRAY and levels​ is greater than $\left\lfloor \log _{2}(max(width,height))\right\rfloor +1$.

See Also

glActiveTexture, glBindTexture, glTexStorage1D, glTexStorage2D, glTexStorage2DMultisample, glTexStorage3DMultisample, glTextureView, glTexSubImage3D

View textures and S3TC compressed formats

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