glTexStorage2D.3G man page

glTexStorage2D, glTextureStorage2D — simultaneously specify storage for all levels of a two-dimensional or one-dimensional array texture

C Specification

void glTexStorage2D(GLenum target, GLsizei levels, GLenum internalformat, GLsizei width, GLsizei height);

void glTextureStorage2D(GLuint texture, GLsizei levels, GLenum internalformat, GLsizei width, GLsizei height);

Parameters

target

Specifies the target to which the texture object is bound for glTexStorage2D. Must be one of GL_TEXTURE_2D, GL_TEXTURE_1D_ARRAY, GL_TEXTURE_RECTANGLE, GL_PROXY_TEXTURE_2D, GL_PROXY_TEXTURE_1D_ARRAY, GL_PROXY_TEXTURE_RECTANGLE, or GL_PROXY_TEXTURE_CUBE_MAP.

texture

Specifies the texture object name for glTextureStorage2D. The effective target of texture must be one of the valid non-proxy target values above.

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.

Description

glTexStorage2D and glTextureStorage2D specify the storage requirements for all levels of a two-dimensional texture or one-dimensional texture array 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 glTexStorage2D depends on the target parameter. When target is GL_TEXTURE_2D, GL_PROXY_TEXTURE_2D, GL_TEXTURE_RECTANGLE, GL_PROXY_TEXTURE_RECTANGLE or GL_PROXY_TEXTURE_CUBE_MAP, calling glTexStorage2D is equivalent, assuming no errors are generated, to executing the following pseudo-code:

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

When target is GL_TEXTURE_CUBE_MAP, glTexStorage2D is equivalent to:

for (i = 0; i < levels; i++) {
    for (face in (+X, -X, +Y, -Y, +Z, -Z)) {
        glTexImage2D(face, i, internalformat, width, height, 0, format, type, NULL);
    }
    width = max(1, (width / 2));
    height = max(1, (height / 2));
}

When target is GL_TEXTURE_1D or GL_TEXTURE_1D_ARRAY, glTexStorage2D is equivalent to:

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

Calling glTextureStorage2D is equivalent to the above pseudo-code, where target is the effective target of texture and it is as if texture were bound to target for the purposes of glTexImage2D.

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 sized internal formats given in Table 1 below, one of the sized depth-component formats GL_DEPTH_COMPONENT32F, GL_DEPTH_COMPONENT24, or GL_DEPTH_COMPONENT16, one of the combined depth-stencil formats, GL_DEPTH32F_STENCIL8, or GL_DEPTH24_STENCIL8, or the stencil-only format, GL_STENCIL_INDEX8. 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 glTexImage2D() or another call to glTexStorage2D) 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.

Table 1. Sized Internal Formats

Sized Internal FormatBase Internal FormatRed BitsGreen BitsBlue BitsAlpha BitsShared Bits
GL_R8GL_RED8
GL_R8_SNORMGL_REDs8
GL_R16GL_RED16
GL_R16_SNORMGL_REDs16
GL_RG8GL_RG88
GL_RG8_SNORMGL_RGs8s8
GL_RG16GL_RG1616
GL_RG16_SNORMGL_RGs16s16
GL_R3_G3_B2GL_RGB332
GL_RGB4GL_RGB444
GL_RGB5GL_RGB555
GL_RGB8GL_RGB888
GL_RGB8_SNORMGL_RGBs8s8s8
GL_RGB10GL_RGB101010
GL_RGB12GL_RGB121212
GL_RGB16_SNORMGL_RGB161616
GL_RGBA2GL_RGB2222
GL_RGBA4GL_RGB4444
GL_RGB5_A1GL_RGBA5551
GL_RGBA8GL_RGBA8888
GL_RGBA8_SNORMGL_RGBAs8s8s8s8
GL_RGB10_A2GL_RGBA1010102
GL_RGB10_A2UIGL_RGBAui10ui10ui10ui2
GL_RGBA12GL_RGBA12121212
GL_RGBA16GL_RGBA16161616
GL_SRGB8GL_RGB888
GL_SRGB8_ALPHA8GL_RGBA8888
GL_R16FGL_REDf16
GL_RG16FGL_RGf16f16
GL_RGB16FGL_RGBf16f16f16
GL_RGBA16FGL_RGBAf16f16f16f16
GL_R32FGL_REDf32
GL_RG32FGL_RGf32f32
GL_RGB32FGL_RGBf32f32f32
GL_RGBA32FGL_RGBAf32f32f32f32
GL_R11F_G11F_B10FGL_RGBf11f11f10
GL_RGB9_E5GL_RGB999 5
GL_R8IGL_REDi8
GL_R8UIGL_REDui8
GL_R16IGL_REDi16
GL_R16UIGL_REDui16
GL_R32IGL_REDi32
GL_R32UIGL_REDui32
GL_RG8IGL_RGi8i8
GL_RG8UIGL_RGui8ui8
GL_RG16IGL_RGi16i16
GL_RG16UIGL_RGui16ui16
GL_RG32IGL_RGi32i32
GL_RG32UIGL_RGui32ui32
GL_RGB8IGL_RGBi8i8i8
GL_RGB8UIGL_RGBui8ui8ui8
GL_RGB16IGL_RGBi16i16i16
GL_RGB16UIGL_RGBui16ui16ui16
GL_RGB32IGL_RGBi32i32i32
GL_RGB32UIGL_RGBui32ui32ui32
GL_RGBA8IGL_RGBAi8i8i8i8
GL_RGBA8UIGL_RGBAui8ui8ui8ui8
GL_RGBA16IGL_RGBAi16i16i16i16
GL_RGBA16UIGL_RGBAui16ui16ui16ui16
GL_RGBA32IGL_RGBAi32i32i32i32
GL_RGBA32UIGL_RGBAui32ui32ui32ui32

Notes

GL_STENCIL_INDEX8 is accepted for internalformat only if the GL version is 4.4 or higher.

Errors

GL_INVALID_OPERATION is generated by glTexStorage2D if zero is bound to target.

GL_INVALID_OPERATION is generated by glTextureStorage2D if texture is not the name of an existing texture object.

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

GL_INVALID_ENUM is generated if target or the effective target of texture is not one of the accepted targets described above.

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

GL_INVALID_OPERATION is generated if target is GL_TEXTURE_1D_ARRAY or GL_PROXY_TEXTURE_1D_ARRAY and levels is greater than log 2 width + 1.

GL_INVALID_OPERATION is generated if target is not GL_TEXTURE_1D_ARRAY or GL_PROXY_TEXTURE_1D_ARRAY and levels is greater than log 2 max width ,   height + 1.

Version Support

OpenGL Version
Function / Feature Name2.02.13.03.13.23.34.04.14.24.34.44.5
glTexStorage2D--------
glTextureStorage2D-----------

See Also

glTexImage2D(), glTexStorage1D(), glTexStorage3D().

Referenced By

glTextureStorage2D.3G(3) is an alias of glTexStorage2D.3G(3).

12/28/2016 [FIXME: source] [FIXME: manual]