'\" t
.\"     Title: glTexStorage3D
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 05/30/2012
.\"    Manual: [FIXME: manual]
.\"    Source: [FIXME: source]
.\"  Language: English
.\"
.TH "GLTEXSTORAGE3D" "3G" "05/30/2012" "[FIXME: source]" "[FIXME: manual]"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
glTexStorage3D \- simultaneously specify storage for all levels of a three\-dimensional, two\-dimensional array or cube\-map array texture
.SH "C SPECIFICATION"
.HP \w'void\ glTexStorage3D('u
.BI "void glTexStorage3D(GLenum\ " "target" ", GLsizei\ " "levels" ", GLenum\ " "internalformat" ", GLsizei\ " "width" ", GLsizei\ " "height" ", GLsizei\ " "depth" ");"
.SH "PARAMETERS"
.PP
\fItarget\fR
.RS 4
Specify the target of the operation\&.
\fItarget\fR
must be one of
\fBGL_TEXTURE_3D\fR,
\fBGL_PROXY_TEXTURE_3D\fR,
\fBGL_TEXTURE_2D_ARRAY\fR,
\fBGL_PROXY_TEXTURE_2D_ARRAY\fR,
\fBGL_TEXTURE_CUBE_ARRAY\fR, or
\fBGL_PROXY_TEXTURE_CUBE_ARRAY\fR\&.
.RE
.PP
\fIlevels\fR
.RS 4
Specify the number of texture levels\&.
.RE
.PP
\fIinternalformat\fR
.RS 4
Specifies the sized internal format to be used to store texture image data\&.
.RE
.PP
\fIwidth\fR
.RS 4
Specifies the width of the texture, in texels\&.
.RE
.PP
\fIheight\fR
.RS 4
Specifies the height of the texture, in texels\&.
.RE
.PP
\fIdepth\fR
.RS 4
Specifies the depth of the texture, in texels\&.
.RE
.SH "DESCRIPTION"
.PP

\fBglTexStorage3D\fR
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
\fIimmutable\-format\fR
texture\&.
.PP
The behavior of
\fBglTexStorage3D\fR
depends on the
\fItarget\fR
parameter\&. When
\fItarget\fR
is
\fBGL_TEXTURE_3D\fR, or
\fBGL_PROXY_TEXTURE_3D\fR, calling
\fBglTexStorage3D\fR
is equivalent, assuming no errors are generated, to executing the following pseudo\-code:
.sp
.if n \{\
.RS 4
.\}
.nf
    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));
    }
.fi
.if n \{\
.RE
.\}
.PP
When
\fItarget\fR
is
\fBGL_TEXTURE_2D_ARRAY\fR,
\fBGL_PROXY_TEXTURE_2D_ARRAY\fR,
\fBGL_TEXTURE_CUBE_MAP_ARRAY\fR, or
\fBGL_PROXY_TEXTURE_CUBE_MAP_ARRAY\fR,
\fBglTexStorage3D\fR
is equivalent to:
.sp
.if n \{\
.RS 4
.\}
.nf
    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));
    }
.fi
.if n \{\
.RE
.\}
.PP
Since no texture data is actually provided, the values used in the pseudo\-code for
\fIformat\fR
and
\fItype\fR
are irrelevant and may be considered to be any values that are legal for the chosen
\fIinternalformat\fR
enumerant\&.
\fIinternalformat\fR
must be one of the sized internal formats given in Table 1 below, one of the sized depth\-component formats
\fBGL_DEPTH_COMPONENT32F\fR,
\fBGL_DEPTH_COMPONENT24\fR, or
\fBGL_DEPTH_COMPONENT16\fR, or one of the combined depth\-stencil formats,
\fBGL_DEPTH32F_STENCIL8\fR, or
\fBGL_DEPTH24_STENCIL8\fR\&. Upon success, the value of
\fBGL_TEXTURE_IMMUTABLE_FORMAT\fR
becomes
\fBGL_TRUE\fR\&. The value of
\fBGL_TEXTURE_IMMUTABLE_FORMAT\fR
may be discovered by calling
\fBglGetTexParameter\fR()
with
\fIpname\fR
set to
\fBGL_TEXTURE_IMMUTABLE_FORMAT\fR\&. 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
\fBglTexImage3D\fR()
or another call to
\fBglTexStorage3D\fR) will result in the generation of a
\fBGL_INVALID_OPERATION\fR
error, even if it would not, in fact, alter the dimensions or format of the object\&.
.PP
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table\ \&1.\ \&Sized Internal Formats
.TS
allbox tab(:);
lB lB lB lB lB lB lB.
T{
\fB
            Sized Internal Format
            \fR
T}:T{
\fB
            Base Internal Format
            \fR
T}:T{
\fB
            Red Bits
            \fR
T}:T{
\fB
            Green Bits
            \fR
T}:T{
\fB
            Blue Bits
            \fR
T}:T{
\fB
            Alpha Bits
            \fR
T}:T{
\fB
            Shared Bits
            \fR
T}
.T&
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c
l l c c c c c.
T{
\fBGL_R8\fR
T}:T{
\fBGL_RED\fR
T}:T{
8
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_R8_SNORM\fR
T}:T{
\fBGL_RED\fR
T}:T{
s8
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_R16\fR
T}:T{
\fBGL_RED\fR
T}:T{
16
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_R16_SNORM\fR
T}:T{
\fBGL_RED\fR
T}:T{
s16
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RG8\fR
T}:T{
\fBGL_RG\fR
T}:T{
8
T}:T{
8
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RG8_SNORM\fR
T}:T{
\fBGL_RG\fR
T}:T{
s8
T}:T{
s8
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RG16\fR
T}:T{
\fBGL_RG\fR
T}:T{
16
T}:T{
16
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RG16_SNORM\fR
T}:T{
\fBGL_RG\fR
T}:T{
s16
T}:T{
s16
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_R3_G3_B2\fR
T}:T{
\fBGL_RGB\fR
T}:T{
3
T}:T{
3
T}:T{
2
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB4\fR
T}:T{
\fBGL_RGB\fR
T}:T{
4
T}:T{
4
T}:T{
4
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB5\fR
T}:T{
\fBGL_RGB\fR
T}:T{
5
T}:T{
5
T}:T{
5
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB8\fR
T}:T{
\fBGL_RGB\fR
T}:T{
8
T}:T{
8
T}:T{
8
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB8_SNORM\fR
T}:T{
\fBGL_RGB\fR
T}:T{
s8
T}:T{
s8
T}:T{
s8
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB10\fR
T}:T{
\fBGL_RGB\fR
T}:T{
10
T}:T{
10
T}:T{
10
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB12\fR
T}:T{
\fBGL_RGB\fR
T}:T{
12
T}:T{
12
T}:T{
12
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB16_SNORM\fR
T}:T{
\fBGL_RGB\fR
T}:T{
16
T}:T{
16
T}:T{
16
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGBA2\fR
T}:T{
\fBGL_RGB\fR
T}:T{
2
T}:T{
2
T}:T{
2
T}:T{
2
T}:T{
\ \&
T}
T{
\fBGL_RGBA4\fR
T}:T{
\fBGL_RGB\fR
T}:T{
4
T}:T{
4
T}:T{
4
T}:T{
4
T}:T{
\ \&
T}
T{
\fBGL_RGB5_A1\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
5
T}:T{
5
T}:T{
5
T}:T{
1
T}:T{
\ \&
T}
T{
\fBGL_RGBA8\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
8
T}:T{
8
T}:T{
8
T}:T{
8
T}:T{
\ \&
T}
T{
\fBGL_RGBA8_SNORM\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
s8
T}:T{
s8
T}:T{
s8
T}:T{
s8
T}:T{
\ \&
T}
T{
\fBGL_RGB10_A2\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
10
T}:T{
10
T}:T{
10
T}:T{
2
T}:T{
\ \&
T}
T{
\fBGL_RGB10_A2UI\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
ui10
T}:T{
ui10
T}:T{
ui10
T}:T{
ui2
T}:T{
\ \&
T}
T{
\fBGL_RGBA12\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
12
T}:T{
12
T}:T{
12
T}:T{
12
T}:T{
\ \&
T}
T{
\fBGL_RGBA16\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
16
T}:T{
16
T}:T{
16
T}:T{
16
T}:T{
\ \&
T}
T{
\fBGL_SRGB8\fR
T}:T{
\fBGL_RGB\fR
T}:T{
8
T}:T{
8
T}:T{
8
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_SRGB8_ALPHA8\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
8
T}:T{
8
T}:T{
8
T}:T{
8
T}:T{
\ \&
T}
T{
\fBGL_R16F\fR
T}:T{
\fBGL_RED\fR
T}:T{
f16
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RG16F\fR
T}:T{
\fBGL_RG\fR
T}:T{
f16
T}:T{
f16
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB16F\fR
T}:T{
\fBGL_RGB\fR
T}:T{
f16
T}:T{
f16
T}:T{
f16
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGBA16F\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
f16
T}:T{
f16
T}:T{
f16
T}:T{
f16
T}:T{
\ \&
T}
T{
\fBGL_R32F\fR
T}:T{
\fBGL_RED\fR
T}:T{
f32
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RG32F\fR
T}:T{
\fBGL_RG\fR
T}:T{
f32
T}:T{
f32
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB32F\fR
T}:T{
\fBGL_RGB\fR
T}:T{
f32
T}:T{
f32
T}:T{
f32
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGBA32F\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
f32
T}:T{
f32
T}:T{
f32
T}:T{
f32
T}:T{
\ \&
T}
T{
\fBGL_R11F_G11F_B10F\fR
T}:T{
\fBGL_RGB\fR
T}:T{
f11
T}:T{
f11
T}:T{
f10
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB9_E5\fR
T}:T{
\fBGL_RGB\fR
T}:T{
9
T}:T{
9
T}:T{
9
T}:T{
\ \&
T}:T{
5
T}
T{
\fBGL_R8I\fR
T}:T{
\fBGL_RED\fR
T}:T{
i8
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_R8UI\fR
T}:T{
\fBGL_RED\fR
T}:T{
ui8
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_R16I\fR
T}:T{
\fBGL_RED\fR
T}:T{
i16
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_R16UI\fR
T}:T{
\fBGL_RED\fR
T}:T{
ui16
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_R32I\fR
T}:T{
\fBGL_RED\fR
T}:T{
i32
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_R32UI\fR
T}:T{
\fBGL_RED\fR
T}:T{
ui32
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RG8I\fR
T}:T{
\fBGL_RG\fR
T}:T{
i8
T}:T{
i8
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RG8UI\fR
T}:T{
\fBGL_RG\fR
T}:T{
ui8
T}:T{
ui8
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RG16I\fR
T}:T{
\fBGL_RG\fR
T}:T{
i16
T}:T{
i16
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RG16UI\fR
T}:T{
\fBGL_RG\fR
T}:T{
ui16
T}:T{
ui16
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RG32I\fR
T}:T{
\fBGL_RG\fR
T}:T{
i32
T}:T{
i32
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RG32UI\fR
T}:T{
\fBGL_RG\fR
T}:T{
ui32
T}:T{
ui32
T}:T{
\ \&
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB8I\fR
T}:T{
\fBGL_RGB\fR
T}:T{
i8
T}:T{
i8
T}:T{
i8
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB8UI\fR
T}:T{
\fBGL_RGB\fR
T}:T{
ui8
T}:T{
ui8
T}:T{
ui8
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB16I\fR
T}:T{
\fBGL_RGB\fR
T}:T{
i16
T}:T{
i16
T}:T{
i16
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB16UI\fR
T}:T{
\fBGL_RGB\fR
T}:T{
ui16
T}:T{
ui16
T}:T{
ui16
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB32I\fR
T}:T{
\fBGL_RGB\fR
T}:T{
i32
T}:T{
i32
T}:T{
i32
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGB32UI\fR
T}:T{
\fBGL_RGB\fR
T}:T{
ui32
T}:T{
ui32
T}:T{
ui32
T}:T{
\ \&
T}:T{
\ \&
T}
T{
\fBGL_RGBA8I\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
i8
T}:T{
i8
T}:T{
i8
T}:T{
i8
T}:T{
\ \&
T}
T{
\fBGL_RGBA8UI\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
ui8
T}:T{
ui8
T}:T{
ui8
T}:T{
ui8
T}:T{
\ \&
T}
T{
\fBGL_RGBA16I\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
i16
T}:T{
i16
T}:T{
i16
T}:T{
i16
T}:T{
\ \&
T}
T{
\fBGL_RGBA16UI\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
ui16
T}:T{
ui16
T}:T{
ui16
T}:T{
ui16
T}:T{
\ \&
T}
T{
\fBGL_RGBA32I\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
i32
T}:T{
i32
T}:T{
i32
T}:T{
i32
T}:T{
\ \&
T}
T{
\fBGL_RGBA32UI\fR
T}:T{
\fBGL_RGBA\fR
T}:T{
ui32
T}:T{
ui32
T}:T{
ui32
T}:T{
ui32
T}:T{
\ \&
T}
.TE
.sp 1
.SH "ERRORS"
.PP

\fBGL_INVALID_ENUM\fR
is generated if
\fIinternalformat\fR
is not a valid sized internal format\&.
.PP

\fBGL_INVALID_ENUM\fR
is generated if
\fItarget\fR
is not one of the accepted target enumerants\&.
.PP

\fBGL_INVALID_VALUE\fR
is generated if
\fIwidth\fR
or
\fIlevels\fR
are less than 1\&.
.PP

\fBGL_INVALID_OPERATION\fR
is generated if
\fItarget\fR
is
\fBGL_TEXTURE_3D\fR
or
\fBGL_PROXY_TEXTURE_3D\fR
and
\fIlevels\fR
is greater than
log 2 max width , \ \& height , \ \& depth + 1\&.
.PP

\fBGL_INVALID_OPERATION\fR
is generated if
\fItarget\fR
is
\fBGL_TEXTURE_2D_ARRAY\fR,
\fBGL_PROXY_TEXTURE_2D_ARRAY\fR,
\fBGL_TEXURE_CUBE_ARRAY\fR, or
\fBGL_PROXY_TEXTURE_CUBE_MAP_ARRAY\fR
and
\fIlevels\fR
is greater than
log 2 max width , \ \& height + 1\&.
.SH "SEE ALSO"
.PP

\fBglTexImage3D\fR(),
\fBglTexStorage1D\fR(),
\fBglTexStorage2D\fR()\&.
.SH "COPYRIGHT"
.PP
Copyright
\(co
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\&.
\m[blue]\fBhttp://opencontent\&.org/openpub/\fR\m[]\&.