[clinton/guile-figl.git] / upstream-doc / man4 / glTexStorage1D.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="glTexStorage1D">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>2011</year>
                <holder>Khronos Group</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glTexStorage1D</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glTexStorage1D</refname>
        <refpurpose>simultaneously specify storage for all levels of a one-dimensional texture</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glTexStorage1D</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>
            </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
                    either <constant>GL_TEXTURE_1D</constant> or <constant>GL_PROXY_TEXTURE_1D</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>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glTexStorage1D</function> 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 <emphasis>immutable-format</emphasis>
            texture.
        </para>
        <para>
            Calling <function>glTexStorage1D</function> is equivalent, assuming no errors are generated,
            to executing the following pseudo-code:
        </para>
<programlisting><![CDATA[    for (i = 0; i < levels; i++)
    {
        glTexImage1D(target, i, internalformat, width, 0, format, type, NULL);
        width = max(1, (width / 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>glTexImage1D</refentrytitle></citerefentry> or
            another call to <function>glTexStorage1D</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
            <constant>GL_TEXTURE_1D</constant> or <constant>GL_TEXTURE_2D</constant>.
        </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>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:mi>width</mml:mi>
        </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>glTexImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexStorage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexStorage3D</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="glTexStorage1D">
	5	<refmeta>
	6	<refmetainfo>
	7	<copyright>
	8	<year>2011</year>
	9	<holder>Khronos Group</holder>
	10	</copyright>
	11	</refmetainfo>
	12	<refentrytitle>glTexStorage1D</refentrytitle>
	13	<manvolnum>3G</manvolnum>
	14	</refmeta>
	15	<refnamediv>
	16	<refname>glTexStorage1D</refname>
	17	<refpurpose>simultaneously specify storage for all levels of a one-dimensional texture</refpurpose>
	18	</refnamediv>
	19	<refsynopsisdiv><title>C Specification</title>
	20	<funcsynopsis>
	21	<funcprototype>
	22	<funcdef>void <function>glTexStorage1D</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	</funcprototype>
	28	</funcsynopsis>
	29	</refsynopsisdiv>
	30	<refsect1 id="parameters"><title>Parameters</title>
	31	<variablelist>
	32	<varlistentry>
	33	<term><parameter>target</parameter></term>
	34	<listitem>
	35	<para>
	36	Specify the target of the operation. <parameter>target</parameter> must be
	37	either <constant>GL_TEXTURE_1D</constant> or <constant>GL_PROXY_TEXTURE_1D</constant>.
	38	</para>
	39	</listitem>
	40	</varlistentry>
	41	<varlistentry>
	42	<term><parameter>levels</parameter></term>
	43	<listitem>
	44	<para>
	45	Specify the number of texture levels.
	46	</para>
	47	</listitem>
	48	</varlistentry>
	49	<varlistentry>
	50	<term><parameter>internalformat</parameter></term>
	51	<listitem>
	52	<para>
	53	Specifies the sized internal format to be used to store texture image data.
	54	</para>
	55	</listitem>
	56	</varlistentry>
	57	<varlistentry>
	58	<term><parameter>width</parameter></term>
	59	<listitem>
	60	<para>
	61	Specifies the width of the texture, in texels.
	62	</para>
	63	</listitem>
	64	</varlistentry>
65	</variablelist>
66	</refsect1>
67	<refsect1 id="description"><title>Description</title>
68	<para>
69	<function>glTexStorage1D</function> specifies the storage requirements for all levels
70	of a one-dimensional texture simultaneously. Once a texture is specified with this
71	command, the format and dimensions of all levels become immutable unless it is a proxy
72	texture. The contents of the image may still be modified, however, its storage requirements
73	may not change. Such a texture is referred to as an <emphasis>immutable-format</emphasis>
74	texture.
75	</para>
76	<para>
77	Calling <function>glTexStorage1D</function> is equivalent, assuming no errors are generated,
78	to executing the following pseudo-code:
79	</para>
80	<programlisting><![CDATA[ for (i = 0; i < levels; i++)
81	{
82	glTexImage1D(target, i, internalformat, width, 0, format, type, NULL);
83	width = max(1, (width / 2));
84	}]]></programlisting>
85	<para>
86	Since no texture data is actually provided, the values used in the pseudo-code
87	for <parameter>format</parameter> and <parameter>type</parameter> are
88	irrelevant and may be considered to be any values that are legal for the
89	chosen <parameter>internalformat</parameter> enumerant. <parameter>internalformat</parameter>
90	must be one of the sized internal formats given in Table 1 below, one of the sized depth-component
91	formats <constant>GL_DEPTH_COMPONENT32F</constant>, <constant>GL_DEPTH_COMPONENT24</constant>, or
92	<constant>GL_DEPTH_COMPONENT16</constant>, or one of the combined depth-stencil formats,
93	<constant>GL_DEPTH32F_STENCIL8</constant>, or <constant>GL_DEPTH24_STENCIL8</constant>. Upon success,
94	the value of <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant> becomes
95	<constant>GL_TRUE</constant>. The value of <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant>
96	may be discovered by calling <citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry>
97	with <parameter>pname</parameter> set to <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant>.
98	No further changes to the dimensions or format of the texture object may be
99	made. Using any command that might alter the dimensions or format of the
100	texture object (such as <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> or
101	another call to <function>glTexStorage1D</function>) will result in the
102	generation of a <constant>GL_INVALID_OPERATION</constant> error, even if it
103	would not, in fact, alter the dimensions or format of the object.
104	</para>
105	<para>
106	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="internalformattable.xml" />
107	</para>
108	</refsect1>
109	<refsect1 id="errors"><title>Errors</title>
110	<para>
111	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is not a
112	valid sized internal format.
113	</para>
114	<para>
115	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
116	<constant>GL_TEXTURE_1D</constant> or <constant>GL_TEXTURE_2D</constant>.
117	</para>
118	<para>
119	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> or <parameter>levels</parameter>
120	are less than 1.
121	</para>
122	<para>
123	<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>levels</parameter> is greater than <mml:math>
124	<mml:mrow>
125	<mml:mfenced open = '&lfloor;' close = '&rfloor;'>
126	<mml:mrow>
127	<mml:msub>
128	<mml:mi>log</mml:mi>
129	<mml:mn>2</mml:mn>
130	</mml:msub>
131	<mml:mfenced open = '(' close = ')'>
132	<mml:mi>width</mml:mi>
133	</mml:mfenced>
134	</mml:mrow>
135	</mml:mfenced>
136	<mml:mo>+</mml:mo>
137	<mml:mn>1</mml:mn>
138	</mml:mrow>
139	</mml:math>.
140	</para>
141	</refsect1>
142	<refsect1 id="seealso"><title>See Also</title>
143	<para>
144	<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
145	<citerefentry><refentrytitle>glTexStorage2D</refentrytitle></citerefentry>,
146	<citerefentry><refentrytitle>glTexStorage3D</refentrytitle></citerefentry>.
147	</para>
148	</refsect1>
149	<refsect1 id="Copyright"><title>Copyright</title>
150	<para>
151	Copyright <trademark class="copyright"></trademark> 2011 Khronos Group.
152	This material may be distributed subject to the terms and conditions set forth in
153	the Open Publication License, v 1.0, 8 June 1999.
154	<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
155	</para>
156	</refsect1>
157	</refentry>