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