[clinton/guile-figl.git] / upstream-doc / man2 / glTexSubImage1D.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="glTexSubImage1D">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glTexSubImage1D</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glTexSubImage1D</refname>
        <refpurpose>specify a one-dimensional texture subimage</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glTexSubImage1D</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLint <parameter>level</parameter></paramdef>
                <paramdef>GLint <parameter>xoffset</parameter></paramdef>
                <paramdef>GLsizei <parameter>width</parameter></paramdef>
                <paramdef>GLenum <parameter>format</parameter></paramdef>
                <paramdef>GLenum <parameter>type</parameter></paramdef>
                <paramdef>const GLvoid * <parameter>data</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <!-- eqn: ignoring delim $$ -->
    <para>
    </para>
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>target</parameter></term>
            <listitem>
                <para>
                    Specifies the target texture.
                    Must be <constant>GL_TEXTURE_1D</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>level</parameter></term>
            <listitem>
                <para>
                    Specifies the level-of-detail number.
                    Level 0 is the base image level.
                    Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>xoffset</parameter></term>
            <listitem>
                <para>
                    Specifies a texel offset in the x direction within the texture array.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>width</parameter></term>
            <listitem>
                <para>
                    Specifies the width of the texture subimage.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>format</parameter></term>
            <listitem>
                <para>
                    Specifies the format of the pixel data.
                    The following symbolic values are accepted:
                    <constant>GL_COLOR_INDEX</constant>,
                    <constant>GL_RED</constant>,
                    <constant>GL_GREEN</constant>,
                    <constant>GL_BLUE</constant>,
                    <constant>GL_ALPHA</constant>,
                    <constant>GL_RGB</constant>,
                    <constant>GL_BGR</constant>,
                    <constant>GL_RGBA</constant>,
                    <constant>GL_BGRA</constant>,
                    <constant>GL_LUMINANCE</constant>, and
                    <constant>GL_LUMINANCE_ALPHA</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>type</parameter></term>
            <listitem>
                <para>
                    Specifies the data type of the pixel data.
                    The following symbolic values are accepted:
                    <constant>GL_UNSIGNED_BYTE</constant>,
                    <constant>GL_BYTE</constant>,
                    <constant>GL_BITMAP</constant>,
                    <constant>GL_UNSIGNED_SHORT</constant>,
                    <constant>GL_SHORT</constant>,
                    <constant>GL_UNSIGNED_INT</constant>,
                    <constant>GL_INT</constant>,
                    <constant>GL_FLOAT</constant>,
                    <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
                    <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
                    <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
                    <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
                    <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
                    <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
                    <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
                    <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
                    <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
                    <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
                    <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
                    <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>data</parameter></term>
            <listitem>
                <para>
                    Specifies a pointer to the image data in memory.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            Texturing maps a portion of a specified texture image
            onto each graphical primitive for which texturing is enabled.
            To enable or disable one-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
            and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_1D</constant>.
        </para>
        <para>
            <function>glTexSubImage1D</function> redefines a contiguous subregion of an existing one-dimensional
            texture image.
            The texels referenced by <parameter>data</parameter> replace the portion of the
            existing texture array with x indices <parameter>xoffset</parameter> and
            <inlineequation><mml:math>
                <!-- eqn: xoffset + width - 1:-->
                <mml:mrow>
                    <mml:mi mathvariant="italic">xoffset</mml:mi>
                    <mml:mo>+</mml:mo>
                    <mml:mi mathvariant="italic">width</mml:mi>
                    <mml:mo>-</mml:mo>
                    <mml:mn>1</mml:mn>
                </mml:mrow>
            </mml:math></inlineequation>,
            inclusive.
            This region may not include any texels outside the range of the
            texture array as it was originally specified.
            It is not an error to specify a subtexture with width of 0, but
            such a specification has no effect.
        </para>
        <para>
            If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target 
            (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
            specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            <function>glTexSubImage1D</function> is available only if the GL version is 1.1 or greater.
        </para>
        <para>
            Texturing has no effect in color index mode.
        </para>
        <para>
            <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry> modes affect texture images
            in exactly the way they affect <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>.
        </para>
        <para>
            Formats <constant>GL_BGR</constant>, and <constant>GL_BGRA</constant> and types
            <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
            <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
            <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
            <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
            <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
            <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
            <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
            <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
            <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
            <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
            <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
            <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant> are available only if the GL version
            is 1.2 or greater.
        </para>
        <para>
            For OpenGL versions 1.3 and greater, or when the <code>ARB_multitexture</code> extension is supported, <function>glTexSubImage1D</function>
            specifies a one-dimensional subtexture for the current texture unit,
            specified with <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>.
        </para>
        <para>
            When the <code>ARB_imaging</code> extension is supported, the RGBA components
            specified in <parameter>data</parameter> may be processed by the imaging pipeline.  See
            <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> for specific details.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the
            allowable values.
        </para>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not an accepted
            format constant.
        </para>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not a type constant.
        </para>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is <constant>GL_BITMAP</constant> and
            <parameter>format</parameter> is not <constant>GL_COLOR_INDEX</constant>.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater
            than 
            <inlineequation><mml:math>
                <!-- eqn: log sub 2:-->
                <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
                <mml:mn>2</mml:mn>
                </mml:msub>
            </mml:math></inlineequation>
            <emphasis>max</emphasis>,
            where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if 
            <inlineequation><mml:math>
                <!-- eqn: xoffset  <   -b:-->
                <mml:mrow>
                    <mml:mi mathvariant="italic">xoffset</mml:mi>
                    <mml:mo>&lt;</mml:mo>
                    <mml:mrow>
                        <mml:mo>-</mml:mo>
                        <mml:mi mathvariant="italic">b</mml:mi>
                    </mml:mrow>
                </mml:mrow>
            </mml:math></inlineequation>,
            or if 
            <inlineequation><mml:math>
                <!-- eqn: (xoffset + width)  >  (w  -  b):-->
                <mml:mrow>
                    <mml:mfenced open="(" close=")">
                        <mml:mrow>
                            <mml:mi mathvariant="italic">xoffset</mml:mi>
                            <mml:mo>+</mml:mo>
                            <mml:mi mathvariant="italic">width</mml:mi>
                        </mml:mrow>
                    </mml:mfenced>
                    <mml:mo>&gt;</mml:mo>
                    <mml:mfenced open="(" close=")">
                        <mml:mrow>
                            <mml:mi mathvariant="italic">w</mml:mi>
                            <mml:mo>-</mml:mo>
                            <mml:mi mathvariant="italic">b</mml:mi>
                        </mml:mrow>
                    </mml:mfenced>
                </mml:mrow>
            </mml:math></inlineequation>,
            where 
            <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
            is the <constant>GL_TEXTURE_WIDTH</constant>, and 
            <inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
            is
            the width of the <constant>GL_TEXTURE_BORDER</constant>
            of the texture image being modified.
            Note that 
            <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
            includes twice the border width.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than 0.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not
            been defined by a previous <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> operation.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
            <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
            <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
            <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
            <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
            and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
            <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
            <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
            <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
            <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
            <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
            <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
            <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
            <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
            and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
            <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
            <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer 
            object such that the memory reads required would exceed the data store size.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
            <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible 
            into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <function>glTexSubImage1D</function> is executed
            between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
            execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
        </para>
    </refsect1>
    <refsect1 id="associatedgets"><title>Associated Gets</title>
        <para>
            <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
        </para>
        <para>
            <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_1D</constant>
        </para>
        <para>
            <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 1991-2006
            Silicon Graphics, Inc. This document is licensed under the SGI
            Free Software B License. For details, see
            <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</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="glTexSubImage1D">
	5	<refmeta>
	6	<refmetainfo>
	7	<copyright>
	8	<year>1991-2006</year>
	9	<holder>Silicon Graphics, Inc.</holder>
	10	</copyright>
	11	</refmetainfo>
	12	<refentrytitle>glTexSubImage1D</refentrytitle>
	13	<manvolnum>3G</manvolnum>
	14	</refmeta>
	15	<refnamediv>
	16	<refname>glTexSubImage1D</refname>
	17	<refpurpose>specify a one-dimensional texture subimage</refpurpose>
	18	</refnamediv>
	19	<refsynopsisdiv><title>C Specification</title>
	20	<funcsynopsis>
	21	<funcprototype>
	22	<funcdef>void <function>glTexSubImage1D</function></funcdef>
	23	<paramdef>GLenum <parameter>target</parameter></paramdef>
	24	<paramdef>GLint <parameter>level</parameter></paramdef>
	25	<paramdef>GLint <parameter>xoffset</parameter></paramdef>
	26	<paramdef>GLsizei <parameter>width</parameter></paramdef>
	27	<paramdef>GLenum <parameter>format</parameter></paramdef>
	28	<paramdef>GLenum <parameter>type</parameter></paramdef>
	29	<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
	30	</funcprototype>
	31	</funcsynopsis>
	32	</refsynopsisdiv>
	33	<!-- eqn: ignoring delim $$ -->
	34	<para>
	35	</para>
	36	<refsect1 id="parameters"><title>Parameters</title>
	37	<variablelist>
	38	<varlistentry>
	39	<term><parameter>target</parameter></term>
	40	<listitem>
	41	<para>
	42	Specifies the target texture.
	43	Must be <constant>GL_TEXTURE_1D</constant>.
	44	</para>
	45	</listitem>
	46	</varlistentry>
	47	<varlistentry>
	48	<term><parameter>level</parameter></term>
	49	<listitem>
	50	<para>
	51	Specifies the level-of-detail number.
	52	Level 0 is the base image level.
	53	Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
	54	</para>
	55	</listitem>
	56	</varlistentry>
	57	<varlistentry>
	58	<term><parameter>xoffset</parameter></term>
	59	<listitem>
	60	<para>
	61	Specifies a texel offset in the x direction within the texture array.
	62	</para>
	63	</listitem>
	64	</varlistentry>
65	<varlistentry>
66	<term><parameter>width</parameter></term>
67	<listitem>
68	<para>
69	Specifies the width of the texture subimage.
70	</para>
71	</listitem>
72	</varlistentry>
73	<varlistentry>
74	<term><parameter>format</parameter></term>
75	<listitem>
76	<para>
77	Specifies the format of the pixel data.
78	The following symbolic values are accepted:
79	<constant>GL_COLOR_INDEX</constant>,
80	<constant>GL_RED</constant>,
81	<constant>GL_GREEN</constant>,
82	<constant>GL_BLUE</constant>,
83	<constant>GL_ALPHA</constant>,
84	<constant>GL_RGB</constant>,
85	<constant>GL_BGR</constant>,
86	<constant>GL_RGBA</constant>,
87	<constant>GL_BGRA</constant>,
88	<constant>GL_LUMINANCE</constant>, and
89	<constant>GL_LUMINANCE_ALPHA</constant>.
90	</para>
91	</listitem>
92	</varlistentry>
93	<varlistentry>
94	<term><parameter>type</parameter></term>
95	<listitem>
96	<para>
97	Specifies the data type of the pixel data.
98	The following symbolic values are accepted:
99	<constant>GL_UNSIGNED_BYTE</constant>,
100	<constant>GL_BYTE</constant>,
101	<constant>GL_BITMAP</constant>,
102	<constant>GL_UNSIGNED_SHORT</constant>,
103	<constant>GL_SHORT</constant>,
104	<constant>GL_UNSIGNED_INT</constant>,
105	<constant>GL_INT</constant>,
106	<constant>GL_FLOAT</constant>,
107	<constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
108	<constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
109	<constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
110	<constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
111	<constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
112	<constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
113	<constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
114	<constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
115	<constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
116	<constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
117	<constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
118	<constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>.
119	</para>
120	</listitem>
121	</varlistentry>
122	<varlistentry>
123	<term><parameter>data</parameter></term>
124	<listitem>
125	<para>
126	Specifies a pointer to the image data in memory.
127	</para>
128	</listitem>
129	</varlistentry>
130	</variablelist>
131	</refsect1>
132	<refsect1 id="description"><title>Description</title>
133	<para>
134	Texturing maps a portion of a specified texture image
135	onto each graphical primitive for which texturing is enabled.
136	To enable or disable one-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
137	and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_1D</constant>.
138	</para>
139	<para>
140	<function>glTexSubImage1D</function> redefines a contiguous subregion of an existing one-dimensional
141	texture image.
142	The texels referenced by <parameter>data</parameter> replace the portion of the
143	existing texture array with x indices <parameter>xoffset</parameter> and
144	<inlineequation><mml:math>
145	<!-- eqn: xoffset + width - 1:-->
146	<mml:mrow>
147	<mml:mi mathvariant="italic">xoffset</mml:mi>
148	<mml:mo>+</mml:mo>
149	<mml:mi mathvariant="italic">width</mml:mi>
150	<mml:mo>-</mml:mo>
151	<mml:mn>1</mml:mn>
152	</mml:mrow>
153	</mml:math></inlineequation>,
154	inclusive.
155	This region may not include any texels outside the range of the
156	texture array as it was originally specified.
157	It is not an error to specify a subtexture with width of 0, but
158	such a specification has no effect.
159	</para>
160	<para>
161	If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
162	(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
163	specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
164	</para>
165	</refsect1>
166	<refsect1 id="notes"><title>Notes</title>
167	<para>
168	<function>glTexSubImage1D</function> is available only if the GL version is 1.1 or greater.
169	</para>
170	<para>
171	Texturing has no effect in color index mode.
172	</para>
173	<para>
174	<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry> modes affect texture images
175	in exactly the way they affect <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>.
176	</para>
177	<para>
178	Formats <constant>GL_BGR</constant>, and <constant>GL_BGRA</constant> and types
179	<constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
180	<constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
181	<constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
182	<constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
183	<constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
184	<constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
185	<constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
186	<constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
187	<constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
188	<constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
189	<constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
190	<constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant> are available only if the GL version
191	is 1.2 or greater.
192	</para>
193	<para>
194	For OpenGL versions 1.3 and greater, or when the <code>ARB_multitexture</code> extension is supported, <function>glTexSubImage1D</function>
195	specifies a one-dimensional subtexture for the current texture unit,
196	specified with <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>.
197	</para>
198	<para>
199	When the <code>ARB_imaging</code> extension is supported, the RGBA components
200	specified in <parameter>data</parameter> may be processed by the imaging pipeline. See
201	<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> for specific details.
202	</para>
203	</refsect1>
204	<refsect1 id="errors"><title>Errors</title>
205	<para>
206	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the
207	allowable values.
208	</para>
209	<para>
210	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not an accepted
211	format constant.
212	</para>
213	<para>
214	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not a type constant.
215	</para>
216	<para>
217	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is <constant>GL_BITMAP</constant> and
218	<parameter>format</parameter> is not <constant>GL_COLOR_INDEX</constant>.
219	</para>
220	<para>
221	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
222	</para>
223	<para>
224	<constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater
225	than
226	<inlineequation><mml:math>
227	<!-- eqn: log sub 2:-->
228	<mml:msub><mml:mi mathvariant="italic">log</mml:mi>
229	<mml:mn>2</mml:mn>
230	</mml:msub>
231	</mml:math></inlineequation>
232	<emphasis>max</emphasis>,
233	where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
234	</para>
235	<para>
236	<constant>GL_INVALID_VALUE</constant> is generated if
237	<inlineequation><mml:math>
238	<!-- eqn: xoffset < -b:-->
239	<mml:mrow>
240	<mml:mi mathvariant="italic">xoffset</mml:mi>
241	<mml:mo><</mml:mo>
242	<mml:mrow>
243	<mml:mo>-</mml:mo>
244	<mml:mi mathvariant="italic">b</mml:mi>
245	</mml:mrow>
246	</mml:mrow>
247	</mml:math></inlineequation>,
248	or if
249	<inlineequation><mml:math>
250	<!-- eqn: (xoffset + width) > (w - b):-->
251	<mml:mrow>
252	<mml:mfenced open="(" close=")">
253	<mml:mrow>
254	<mml:mi mathvariant="italic">xoffset</mml:mi>
255	<mml:mo>+</mml:mo>
256	<mml:mi mathvariant="italic">width</mml:mi>
257	</mml:mrow>
258	</mml:mfenced>
259	<mml:mo>></mml:mo>
260	<mml:mfenced open="(" close=")">
261	<mml:mrow>
262	<mml:mi mathvariant="italic">w</mml:mi>
263	<mml:mo>-</mml:mo>
264	<mml:mi mathvariant="italic">b</mml:mi>
265	</mml:mrow>
266	</mml:mfenced>
267	</mml:mrow>
268	</mml:math></inlineequation>,
269	where
270	<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
271	is the <constant>GL_TEXTURE_WIDTH</constant>, and
272	<inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
273	is
274	the width of the <constant>GL_TEXTURE_BORDER</constant>
275	of the texture image being modified.
276	Note that
277	<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
278	includes twice the border width.
279	</para>
280	<para>
281	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than 0.
282	</para>
283	<para>
284	<constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not
285	been defined by a previous <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> operation.
286	</para>
287	<para>
288	<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
289	<constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
290	<constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
291	<constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
292	<constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
293	and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
294	</para>
295	<para>
296	<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
297	<constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
298	<constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
299	<constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
300	<constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
301	<constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
302	<constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
303	<constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
304	<constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
305	and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
306	</para>
307	<para>
308	<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
309	<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
310	</para>
311	<para>
312	<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
313	<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
314	object such that the memory reads required would exceed the data store size.
315	</para>
316	<para>
317	<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
318	<constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
319	into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
320	</para>
321	<para>
322	<constant>GL_INVALID_OPERATION</constant> is generated if <function>glTexSubImage1D</function> is executed
323	between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
324	execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
325	</para>
326	</refsect1>
327	<refsect1 id="associatedgets"><title>Associated Gets</title>
328	<para>
329	<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
330	</para>
331	<para>
332	<citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_1D</constant>
333	</para>
334	<para>
335	<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
336	</para>
337	</refsect1>
338	<refsect1 id="seealso"><title>See Also</title>
339	<para>
340	<citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
341	<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
342	<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
343	<citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
344	<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
345	<citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
346	<citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
347	<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
348	<citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
349	<citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
350	<citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
351	<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
352	<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
353	<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
354	<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
355	<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
356	<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
357	</para>
358	</refsect1>
359	<refsect1 id="Copyright"><title>Copyright</title>
360	<para>
361	Copyright <trademark class="copyright"></trademark> 1991-2006
362	Silicon Graphics, Inc. This document is licensed under the SGI
363	Free Software B License. For details, see
364	<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
365	</para>
366	</refsect1>
367	</refentry>