Name

glTexStorage1D — simultaneously specify storage for all levels of a one-dimensional texture

C Specification

void glTexStorage1D(GLenum  target,
 GLsizei  levels,
 GLenum  internalformat,
 GLsizei  width);

Parameters

target

Specify the target of the operation. target must be either GL_TEXTURE_1D or GL_PROXY_TEXTURE_1D.

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.

Description

glTexStorage1D specifies the storage requirements for all levels of a one-dimensional 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.

Calling glTexStorage1D is equivalent, assuming no errors are generated, to executing the following pseudo-code: 

    for (i = 0; i < levels; i++)
    {
        glTexImage1D(target, i, internalformat, width, 0, format, type, NULL);
        width = max(1, (width / 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 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, or one of the combined depth-stencil formats, GL_DEPTH32F_STENCIL8, or GL_DEPTH24_STENCIL8. 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 glTexImage1D or another call to glTexStorage1D) 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 Format Base Internal Format Red Bits Green Bits Blue Bits Alpha Bits Shared 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 

Errors

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

GL_INVALID_ENUM is generated if target is not GL_TEXTURE_1D or GL_TEXTURE_2D.

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

GL_INVALID_OPERATION is generated if levels is greater than log 2 width + 1 .

See Also

glTexImage1D, glTexStorage2D, glTexStorage3D.

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