[clinton/guile-figl.git] / upstream-doc / man4 / glTexStorage3D.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
              "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glTexStorage3D">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>2011</year>
                <holder>Khronos Group</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glTexStorage3D</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glTexStorage3D</refname>
        <refpurpose>simultaneously specify storage for all levels of a three-dimensional, two-dimensional array or cube-map array texture</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glTexStorage3D</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLsizei <parameter>levels</parameter></paramdef>
                <paramdef>GLenum <parameter>internalformat</parameter></paramdef>
                <paramdef>GLsizei <parameter>width</parameter></paramdef>
                <paramdef>GLsizei <parameter>height</parameter></paramdef>
                <paramdef>GLsizei <parameter>depth</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>target</parameter></term>
            <listitem>
                <para>
                    Specify the target of the operation. <parameter>target</parameter> must be
                    one of <constant>GL_TEXTURE_3D</constant>, <constant>GL_PROXY_TEXTURE_3D</constant>,
                    <constant>GL_TEXTURE_2D_ARRAY</constant>, <constant>GL_PROXY_TEXTURE_2D_ARRAY</constant>,
                    <constant>GL_TEXTURE_CUBE_ARRAY</constant>, or <constant>GL_PROXY_TEXTURE_CUBE_ARRAY</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>levels</parameter></term>
            <listitem>
                <para>
                    Specify the number of texture levels.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>internalformat</parameter></term>
            <listitem>
                <para>
                    Specifies the sized internal format to be used to store texture image data.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>width</parameter></term>
            <listitem>
                <para>
                    Specifies the width of the texture, in texels.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>height</parameter></term>
            <listitem>
                <para>
                    Specifies the height of the texture, in texels.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>depth</parameter></term>
            <listitem>
                <para>
                    Specifies the depth of the texture, in texels.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glTexStorage3D</function> 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 <emphasis>immutable-format</emphasis>
            texture.
        </para>
        <para>
            The behavior of <function>glTexStorage3D</function> depends on the <parameter>target</parameter> parameter.
            When <parameter>target</parameter> is <constant>GL_TEXTURE_3D</constant>, or <constant>GL_PROXY_TEXTURE_3D</constant>,
            calling <function>glTexStorage3D</function> is equivalent, assuming no errors are generated,
            to executing the following pseudo-code:
        </para>
<programlisting><![CDATA[    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));
    }]]></programlisting>
        <para>
            When <parameter>target</parameter> is <constant>GL_TEXTURE_2D_ARRAY</constant>, <constant>GL_PROXY_TEXTURE_2D_ARRAY</constant>,
            <constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant>, or <constant>GL_PROXY_TEXTURE_CUBE_MAP_ARRAY</constant>, <function>glTexStorage3D</function>
            is equivalent to:
        </para>
<programlisting><![CDATA[    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));
    }]]></programlisting>
        <para>
            Since no texture data is actually provided, the values used in the pseudo-code
            for <parameter>format</parameter> and <parameter>type</parameter> are
            irrelevant and may be considered to be any values that are legal for the
            chosen <parameter>internalformat</parameter> enumerant. <parameter>internalformat</parameter>
            must be one of the sized internal formats given in Table 1 below, one of the sized depth-component
            formats <constant>GL_DEPTH_COMPONENT32F</constant>, <constant>GL_DEPTH_COMPONENT24</constant>, or
            <constant>GL_DEPTH_COMPONENT16</constant>, or one of the combined depth-stencil formats,
            <constant>GL_DEPTH32F_STENCIL8</constant>, or <constant>GL_DEPTH24_STENCIL8</constant>. Upon success,
            the value of <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant> becomes
            <constant>GL_TRUE</constant>. The value of <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant>
            may be discovered by calling <citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry>
            with <parameter>pname</parameter> set to <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant>.
            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 <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry> or
            another call to <function>glTexStorage3D</function>) will result in the
            generation of a <constant>GL_INVALID_OPERATION</constant> error, even if it
            would not, in fact, alter the dimensions or format of the object.
        </para>
        <para>
            <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="internalformattable.xml" />
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is not a
            valid sized internal format.
        </para>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
            one of the accepted target enumerants.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> or <parameter>levels</parameter>
            are less than 1.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>target</parameter> is <constant>GL_TEXTURE_3D</constant>
            or <constant>GL_PROXY_TEXTURE_3D</constant> and <parameter>levels</parameter> is greater than <mml:math>
  <mml:mrow>
    <mml:mfenced open = '&lfloor;' close = '&rfloor;'>
      <mml:mrow>
        <mml:msub>
          <mml:mi>log</mml:mi>
          <mml:mn>2</mml:mn>
        </mml:msub>
        <mml:mfenced open = '(' close = ')'>
          <mml:mrow>
            <mml:mi>max</mml:mi>
            <mml:mfenced open = '(' close = ')'>
              <mml:mrow>
                <mml:mi>width</mml:mi>
                <mml:mo>,</mml:mo>
                <mml:mtext fontfamily='Times New Roman'>&nbsp;</mml:mtext>
                <mml:mi>height</mml:mi>
                <mml:mo>,</mml:mo>
                <mml:mtext fontfamily='Times New Roman'>&nbsp;</mml:mtext>
                <mml:mi>depth</mml:mi>
              </mml:mrow>
            </mml:mfenced>
          </mml:mrow>
        </mml:mfenced>
      </mml:mrow>
    </mml:mfenced>
    <mml:mo>+</mml:mo>
    <mml:mn>1</mml:mn>
  </mml:mrow>
</mml:math>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>target</parameter> is <constant>GL_TEXTURE_2D_ARRAY</constant>,
            <constant>GL_PROXY_TEXTURE_2D_ARRAY</constant>, <constant>GL_TEXURE_CUBE_ARRAY</constant>, or <constant>GL_PROXY_TEXTURE_CUBE_MAP_ARRAY</constant>
            and <parameter>levels</parameter> is greater than <mml:math>
  <mml:mrow>
    <mml:mfenced open = '&lfloor;' close = '&rfloor;'>
      <mml:mrow>
        <mml:msub>
          <mml:mi>log</mml:mi>
          <mml:mn>2</mml:mn>
        </mml:msub>
        <mml:mfenced open = '(' close = ')'>
          <mml:mrow>
            <mml:mi>max</mml:mi>
            <mml:mfenced open = '(' close = ')'>
              <mml:mrow>
                <mml:mi>width</mml:mi>
                <mml:mo>,</mml:mo>
                <mml:mtext fontfamily='Times New Roman'>&nbsp;</mml:mtext>
                <mml:mi>height</mml:mi>
              </mml:mrow>
            </mml:mfenced>
          </mml:mrow>
        </mml:mfenced>
      </mml:mrow>
    </mml:mfenced>
    <mml:mo>+</mml:mo>
    <mml:mn>1</mml:mn>
  </mml:mrow>
</mml:math>.
    </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexStorage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexStorage2D</refentrytitle></citerefentry>.
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 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.
            <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
        </para>
    </refsect1>
</refentry>
Commit	Line	Data
7faf1d71 AW	1	<?xml version="1.0" encoding="UTF-8"?>
	2	<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
	3	"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
	4	<refentry id="glTexStorage3D">
	5	<refmeta>
	6	<refmetainfo>
	7	<copyright>
	8	<year>2011</year>
	9	<holder>Khronos Group</holder>
	10	</copyright>
	11	</refmetainfo>
	12	<refentrytitle>glTexStorage3D</refentrytitle>
	13	<manvolnum>3G</manvolnum>
	14	</refmeta>
	15	<refnamediv>
	16	<refname>glTexStorage3D</refname>
	17	<refpurpose>simultaneously specify storage for all levels of a three-dimensional, two-dimensional array or cube-map array texture</refpurpose>
	18	</refnamediv>
	19	<refsynopsisdiv><title>C Specification</title>
	20	<funcsynopsis>
	21	<funcprototype>
	22	<funcdef>void <function>glTexStorage3D</function></funcdef>
	23	<paramdef>GLenum <parameter>target</parameter></paramdef>
	24	<paramdef>GLsizei <parameter>levels</parameter></paramdef>
	25	<paramdef>GLenum <parameter>internalformat</parameter></paramdef>
	26	<paramdef>GLsizei <parameter>width</parameter></paramdef>
	27	<paramdef>GLsizei <parameter>height</parameter></paramdef>
	28	<paramdef>GLsizei <parameter>depth</parameter></paramdef>
	29	</funcprototype>
	30	</funcsynopsis>
	31	</refsynopsisdiv>
	32	<refsect1 id="parameters"><title>Parameters</title>
	33	<variablelist>
	34	<varlistentry>
	35	<term><parameter>target</parameter></term>
	36	<listitem>
	37	<para>
	38	Specify the target of the operation. <parameter>target</parameter> must be
	39	one of <constant>GL_TEXTURE_3D</constant>, <constant>GL_PROXY_TEXTURE_3D</constant>,
	40	<constant>GL_TEXTURE_2D_ARRAY</constant>, <constant>GL_PROXY_TEXTURE_2D_ARRAY</constant>,
	41	<constant>GL_TEXTURE_CUBE_ARRAY</constant>, or <constant>GL_PROXY_TEXTURE_CUBE_ARRAY</constant>.
	42	</para>
	43	</listitem>
	44	</varlistentry>
	45	<varlistentry>
	46	<term><parameter>levels</parameter></term>
	47	<listitem>
	48	<para>
	49	Specify the number of texture levels.
	50	</para>
	51	</listitem>
	52	</varlistentry>
	53	<varlistentry>
	54	<term><parameter>internalformat</parameter></term>
	55	<listitem>
	56	<para>
	57	Specifies the sized internal format to be used to store texture image data.
	58	</para>
	59	</listitem>
	60	</varlistentry>
	61	<varlistentry>
	62	<term><parameter>width</parameter></term>
	63	<listitem>
	64	<para>
65	Specifies the width of the texture, in texels.
66	</para>
67	</listitem>
68	</varlistentry>
69	<varlistentry>
70	<term><parameter>height</parameter></term>
71	<listitem>
72	<para>
73	Specifies the height of the texture, in texels.
74	</para>
75	</listitem>
76	</varlistentry>
77	<varlistentry>
78	<term><parameter>depth</parameter></term>
79	<listitem>
80	<para>
81	Specifies the depth of the texture, in texels.
82	</para>
83	</listitem>
84	</varlistentry>
85	</variablelist>
86	</refsect1>
87	<refsect1 id="description"><title>Description</title>
88	<para>
89	<function>glTexStorage3D</function> specifies the storage requirements for all levels
90	of a three-dimensional, two-dimensional array or cube-map array texture simultaneously. Once a texture is specified with this
91	command, the format and dimensions of all levels become immutable unless it is a proxy
92	texture. The contents of the image may still be modified, however, its storage requirements
93	may not change. Such a texture is referred to as an <emphasis>immutable-format</emphasis>
94	texture.
95	</para>
96	<para>
97	The behavior of <function>glTexStorage3D</function> depends on the <parameter>target</parameter> parameter.
98	When <parameter>target</parameter> is <constant>GL_TEXTURE_3D</constant>, or <constant>GL_PROXY_TEXTURE_3D</constant>,
99	calling <function>glTexStorage3D</function> is equivalent, assuming no errors are generated,
100	to executing the following pseudo-code:
101	</para>
102	<programlisting><![CDATA[ for (i = 0; i < levels; i++)
103	{
104	glTexImage3D(target, i, internalformat, width, height, depth, 0, format, type, NULL);
105	width = max(1, (width / 2));
106	height = max(1, (height / 2));
107	depth = max(1, (depth / 2));
108	}]]></programlisting>
109	<para>
110	When <parameter>target</parameter> is <constant>GL_TEXTURE_2D_ARRAY</constant>, <constant>GL_PROXY_TEXTURE_2D_ARRAY</constant>,
111	<constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant>, or <constant>GL_PROXY_TEXTURE_CUBE_MAP_ARRAY</constant>, <function>glTexStorage3D</function>
112	is equivalent to:
113	</para>
114	<programlisting><![CDATA[ for (i = 0; i < levels; i++)
115	{
116	glTexImage3D(target, i, internalformat, width, height, depth, 0, format, type, NULL);
117	width = max(1, (width / 2));
118	height = max(1, (height / 2));
119	}]]></programlisting>
120	<para>
121	Since no texture data is actually provided, the values used in the pseudo-code
122	for <parameter>format</parameter> and <parameter>type</parameter> are
123	irrelevant and may be considered to be any values that are legal for the
124	chosen <parameter>internalformat</parameter> enumerant. <parameter>internalformat</parameter>
125	must be one of the sized internal formats given in Table 1 below, one of the sized depth-component
126	formats <constant>GL_DEPTH_COMPONENT32F</constant>, <constant>GL_DEPTH_COMPONENT24</constant>, or
127	<constant>GL_DEPTH_COMPONENT16</constant>, or one of the combined depth-stencil formats,
128	<constant>GL_DEPTH32F_STENCIL8</constant>, or <constant>GL_DEPTH24_STENCIL8</constant>. Upon success,
129	the value of <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant> becomes
130	<constant>GL_TRUE</constant>. The value of <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant>
131	may be discovered by calling <citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry>
132	with <parameter>pname</parameter> set to <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant>.
133	No further changes to the dimensions or format of the texture object may be
134	made. Using any command that might alter the dimensions or format of the
135	texture object (such as <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry> or
136	another call to <function>glTexStorage3D</function>) will result in the
137	generation of a <constant>GL_INVALID_OPERATION</constant> error, even if it
138	would not, in fact, alter the dimensions or format of the object.
139	</para>
140	<para>
141	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="internalformattable.xml" />
142	</para>
143	</refsect1>
144	<refsect1 id="errors"><title>Errors</title>
145	<para>
146	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is not a
147	valid sized internal format.
148	</para>
149	<para>
150	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
151	one of the accepted target enumerants.
152	</para>
153	<para>
154	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> or <parameter>levels</parameter>
155	are less than 1.
156	</para>
157	<para>
158	<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>target</parameter> is <constant>GL_TEXTURE_3D</constant>
159	or <constant>GL_PROXY_TEXTURE_3D</constant> and <parameter>levels</parameter> is greater than <mml:math>
160	<mml:mrow>
161	<mml:mfenced open = '&lfloor;' close = '&rfloor;'>
162	<mml:mrow>
163	<mml:msub>
164	<mml:mi>log</mml:mi>
165	<mml:mn>2</mml:mn>
166	</mml:msub>
167	<mml:mfenced open = '(' close = ')'>
168	<mml:mrow>
169	<mml:mi>max</mml:mi>
170	<mml:mfenced open = '(' close = ')'>
171	<mml:mrow>
172	<mml:mi>width</mml:mi>
173	<mml:mo>,</mml:mo>
174	<mml:mtext fontfamily='Times New Roman'> </mml:mtext>
175	<mml:mi>height</mml:mi>
176	<mml:mo>,</mml:mo>
177	<mml:mtext fontfamily='Times New Roman'> </mml:mtext>
178	<mml:mi>depth</mml:mi>
179	</mml:mrow>
180	</mml:mfenced>
181	</mml:mrow>
182	</mml:mfenced>
183	</mml:mrow>
184	</mml:mfenced>
185	<mml:mo>+</mml:mo>
186	<mml:mn>1</mml:mn>
187	</mml:mrow>
188	</mml:math>.
189	</para>
190	<para>
191	<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>target</parameter> is <constant>GL_TEXTURE_2D_ARRAY</constant>,
192	<constant>GL_PROXY_TEXTURE_2D_ARRAY</constant>, <constant>GL_TEXURE_CUBE_ARRAY</constant>, or <constant>GL_PROXY_TEXTURE_CUBE_MAP_ARRAY</constant>
193	and <parameter>levels</parameter> is greater than <mml:math>
194	<mml:mrow>
195	<mml:mfenced open = '&lfloor;' close = '&rfloor;'>
196	<mml:mrow>
197	<mml:msub>
198	<mml:mi>log</mml:mi>
199	<mml:mn>2</mml:mn>
200	</mml:msub>
201	<mml:mfenced open = '(' close = ')'>
202	<mml:mrow>
203	<mml:mi>max</mml:mi>
204	<mml:mfenced open = '(' close = ')'>
205	<mml:mrow>
206	<mml:mi>width</mml:mi>
207	<mml:mo>,</mml:mo>
208	<mml:mtext fontfamily='Times New Roman'> </mml:mtext>
209	<mml:mi>height</mml:mi>
210	</mml:mrow>
211	</mml:mfenced>
212	</mml:mrow>
213	</mml:mfenced>
214	</mml:mrow>
215	</mml:mfenced>
216	<mml:mo>+</mml:mo>
217	<mml:mn>1</mml:mn>
218	</mml:mrow>
219	</mml:math>.
220	</para>
221	</refsect1>
222	<refsect1 id="seealso"><title>See Also</title>
223	<para>
224	<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
225	<citerefentry><refentrytitle>glTexStorage1D</refentrytitle></citerefentry>,
226	<citerefentry><refentrytitle>glTexStorage2D</refentrytitle></citerefentry>.
227	</para>
228	</refsect1>
229	<refsect1 id="Copyright"><title>Copyright</title>
230	<para>
231	Copyright <trademark class="copyright"></trademark> 2011 Khronos Group.
232	This material may be distributed subject to the terms and conditions set forth in
233	the Open Publication License, v 1.0, 8 June 1999.
234	<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
235	</para>
236	</refsect1>
237	</refentry>