[clinton/guile-figl.git] / upstream-doc / man3 / glCopyTexSubImage1D.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="glCopyTexSubImage1D">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glCopyTexSubImage1D</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glCopyTexSubImage1D</refname>
        <refpurpose>copy a one-dimensional texture subimage</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glCopyTexSubImage1D</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLint <parameter>level</parameter></paramdef>
                <paramdef>GLint <parameter>xoffset</parameter></paramdef>
                <paramdef>GLint <parameter>x</parameter></paramdef>
                <paramdef>GLint <parameter>y</parameter></paramdef>
                <paramdef>GLsizei <parameter>width</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 the texel offset within the texture array.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>x</parameter></term>
            <term><parameter>y</parameter></term>
            <listitem>
                <para>
                    Specify the window coordinates of the left corner
                    of the row of pixels to be copied.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>width</parameter></term>
            <listitem>
                <para>
                    Specifies the width of the texture subimage.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glCopyTexSubImage1D</function> replaces a portion of a one-dimensional
            texture image with pixels from the current <constant>GL_READ_BUFFER</constant> (rather
            than from main memory, as is the case for <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>).
        </para>
        <para>
            The screen-aligned pixel row with left corner at (<parameter>x</parameter>, <parameter>y</parameter>), and with
            length <parameter>width</parameter> replaces the portion of the
            texture array with x indices <parameter>xoffset</parameter> through 
            <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. The destination in the texture array may not
            include any texels outside the texture array as it was
            originally specified.
        </para>
        <para>
            The pixels in the row are processed exactly as if
            <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry> had been called, but the process stops just before
            final conversion.
            At this point, all pixel component values are clamped to the range 
            <inlineequation><mml:math>
                <!-- eqn: [0,1]: -->
                <mml:mfenced open="[" close="]">
                    <mml:mn>0</mml:mn>
                    <mml:mn>1</mml:mn>
                </mml:mfenced>
            </mml:math></inlineequation>
            and then converted to the texture's internal format for storage in the texel
            array.
        </para>
        <para>
            It is not an error to specify a subtexture with zero width, but
            such a specification has no effect.
            If any of the pixels within the specified row of the current
            <constant>GL_READ_BUFFER</constant> are outside the read window associated with the current
            rendering context, then the values obtained for those pixels are undefined.
        </para>
        <para>
            No change is made to the <emphasis>internalformat</emphasis> or <emphasis>width</emphasis> parameters of the specified texture
            array or to texel values outside the specified subregion.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            The <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> mode affects texture images.
        </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_1D</constant>.
        </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> or <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry> operation.
        </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 
            <inlineequation><mml:math>
                <!-- eqn: level  >  log sub 2(max): -->
                <mml:mrow>
                    <mml:mi mathvariant="italic">level</mml:mi>
                    <mml:mo>&gt;</mml:mo>
                    <mml:mrow>
                        <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
                        <mml:mn>2</mml:mn>
                        </mml:msub>
                        <mml:mo>&af;</mml:mo>
                        <mml:mfenced open="(" close=")">
                            <mml:mi mathvariant="italic">max</mml:mi>
                        </mml:mfenced>
                    </mml:mrow>
                </mml:mrow>
            </mml:math></inlineequation>,
            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:mn>0</mml:mn>
                </mml:mrow>
            </mml:math></inlineequation>,
            or
            <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:mi mathvariant="italic">w</mml:mi>
                </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>
            of the texture image being modified.
        </para>
    </refsect1>
    <refsect1 id="associatedgets"><title>Associated Gets</title>
        <para>
            <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexSubImage1D</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="glCopyTexSubImage1D">
	5	<refmeta>
	6	<refmetainfo>
	7	<copyright>
	8	<year>1991-2006</year>
	9	<holder>Silicon Graphics, Inc.</holder>
	10	</copyright>
	11	</refmetainfo>
	12	<refentrytitle>glCopyTexSubImage1D</refentrytitle>
	13	<manvolnum>3G</manvolnum>
	14	</refmeta>
	15	<refnamediv>
	16	<refname>glCopyTexSubImage1D</refname>
	17	<refpurpose>copy a one-dimensional texture subimage</refpurpose>
	18	</refnamediv>
	19	<refsynopsisdiv><title>C Specification</title>
	20	<funcsynopsis>
	21	<funcprototype>
	22	<funcdef>void <function>glCopyTexSubImage1D</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>x</parameter></paramdef>
	27	<paramdef>GLint <parameter>y</parameter></paramdef>
	28	<paramdef>GLsizei <parameter>width</parameter></paramdef>
	29	</funcprototype>
	30	</funcsynopsis>
	31	</refsynopsisdiv>
	32	<!-- eqn: ignoring delim $$ -->
	33	<para>
	34	</para>
	35	<refsect1 id="parameters"><title>Parameters</title>
	36	<variablelist>
	37	<varlistentry>
	38	<term><parameter>target</parameter></term>
	39	<listitem>
	40	<para>
	41	Specifies the target texture.
	42	Must be <constant>GL_TEXTURE_1D</constant>.
	43	</para>
	44	</listitem>
	45	</varlistentry>
	46	<varlistentry>
	47	<term><parameter>level</parameter></term>
	48	<listitem>
	49	<para>
	50	Specifies the level-of-detail number.
	51	Level 0 is the base image level.
	52	Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
	53	</para>
	54	</listitem>
	55	</varlistentry>
	56	<varlistentry>
	57	<term><parameter>xoffset</parameter></term>
	58	<listitem>
	59	<para>
	60	Specifies the texel offset within the texture array.
	61	</para>
	62	</listitem>
	63	</varlistentry>
	64	<varlistentry>
65	<term><parameter>x</parameter></term>
66	<term><parameter>y</parameter></term>
67	<listitem>
68	<para>
69	Specify the window coordinates of the left corner
70	of the row of pixels to be copied.
71	</para>
72	</listitem>
73	</varlistentry>
74	<varlistentry>
75	<term><parameter>width</parameter></term>
76	<listitem>
77	<para>
78	Specifies the width of the texture subimage.
79	</para>
80	</listitem>
81	</varlistentry>
82	</variablelist>
83	</refsect1>
84	<refsect1 id="description"><title>Description</title>
85	<para>
86	<function>glCopyTexSubImage1D</function> replaces a portion of a one-dimensional
87	texture image with pixels from the current <constant>GL_READ_BUFFER</constant> (rather
88	than from main memory, as is the case for <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>).
89	</para>
90	<para>
c7b31271	91	The screen-aligned pixel row with left corner at (<parameter>x</parameter>, <parameter>y</parameter>), and with
7faf1d71 AW	92	length <parameter>width</parameter> replaces the portion of the
	93	texture array with x indices <parameter>xoffset</parameter> through
	94	<inlineequation><mml:math>
	95	<!-- eqn: xoffset + width - 1: -->
	96	<mml:mrow>
	97	<mml:mi mathvariant="italic">xoffset</mml:mi>
	98	<mml:mo>+</mml:mo>
	99	<mml:mi mathvariant="italic">width</mml:mi>
	100	<mml:mo>-</mml:mo>
	101	<mml:mn>1</mml:mn>
	102	</mml:mrow>
	103	</mml:math></inlineequation>,
	104	inclusive. The destination in the texture array may not
	105	include any texels outside the texture array as it was
	106	originally specified.
	107	</para>
	108	<para>
	109	The pixels in the row are processed exactly as if
	110	<citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry> had been called, but the process stops just before
	111	final conversion.
	112	At this point, all pixel component values are clamped to the range
	113	<inlineequation><mml:math>
	114	<!-- eqn: [0,1]: -->
	115	<mml:mfenced open="[" close="]">
	116	<mml:mn>0</mml:mn>
	117	<mml:mn>1</mml:mn>
	118	</mml:mfenced>
	119	</mml:math></inlineequation>
	120	and then converted to the texture's internal format for storage in the texel
	121	array.
	122	</para>
	123	<para>
	124	It is not an error to specify a subtexture with zero width, but
	125	such a specification has no effect.
	126	If any of the pixels within the specified row of the current
	127	<constant>GL_READ_BUFFER</constant> are outside the read window associated with the current
	128	rendering context, then the values obtained for those pixels are undefined.
	129	</para>
	130	<para>
c7b31271	131	No change is made to the <emphasis>internalformat</emphasis> or <emphasis>width</emphasis> parameters of the specified texture
7faf1d71 AW	132	array or to texel values outside the specified subregion.
	133	</para>
	134	</refsect1>
	135	<refsect1 id="notes"><title>Notes</title>
	136	<para>
	137	The <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> mode affects texture images.
	138	</para>
	139	</refsect1>
	140	<refsect1 id="errors"><title>Errors</title>
	141	<para>
c7b31271	142	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_TEXTURE_1D</constant>.
7faf1d71 AW	143	</para>
	144	<para>
	145	<constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not
	146	been defined by a previous <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry> operation.
	147	</para>
	148	<para>
	149	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
	150	</para>
	151	<para>
	152	<constant>GL_INVALID_VALUE</constant> may be generated if
	153	<inlineequation><mml:math>
	154	<!-- eqn: level > log sub 2(max): -->
	155	<mml:mrow>
	156	<mml:mi mathvariant="italic">level</mml:mi>
	157	<mml:mo>></mml:mo>
	158	<mml:mrow>
	159	<mml:msub><mml:mi mathvariant="italic">log</mml:mi>
	160	<mml:mn>2</mml:mn>
	161	</mml:msub>
	162	<mml:mo>⁡</mml:mo>
	163	<mml:mfenced open="(" close=")">
	164	<mml:mi mathvariant="italic">max</mml:mi>
	165	</mml:mfenced>
	166	</mml:mrow>
	167	</mml:mrow>
	168	</mml:math></inlineequation>,
	169	where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
	170	</para>
	171	<para>
	172	<constant>GL_INVALID_VALUE</constant> is generated if
	173	<inlineequation><mml:math>
	174	<!-- eqn: xoffset < -b: -->
	175	<mml:mrow>
	176	<mml:mi mathvariant="italic">xoffset</mml:mi>
	177	<mml:mo><</mml:mo>
c7b31271	178	<mml:mn>0</mml:mn>
7faf1d71 AW	179	</mml:mrow>
	180	</mml:math></inlineequation>,
	181	or
	182	<inlineequation><mml:math>
	183	<!-- eqn: (xoffset + width) > (w-b): -->
	184	<mml:mrow>
	185	<mml:mfenced open="(" close=")">
	186	<mml:mrow>
	187	<mml:mi mathvariant="italic">xoffset</mml:mi>
	188	<mml:mo>+</mml:mo>
	189	<mml:mi mathvariant="italic">width</mml:mi>
	190	</mml:mrow>
	191	</mml:mfenced>
	192	<mml:mo>></mml:mo>
c7b31271	193	<mml:mi mathvariant="italic">w</mml:mi>
7faf1d71 AW	194	</mml:mrow>
	195	</mml:math></inlineequation>,
	196	where
	197	<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
c7b31271	198	is the <constant>GL_TEXTURE_WIDTH</constant>
7faf1d71	199	of the texture image being modified.
7faf1d71 AW	200	</para>
	201	</refsect1>
	202	<refsect1 id="associatedgets"><title>Associated Gets</title>
	203	<para>
	204	<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
	205	</para>
	206	</refsect1>
	207	<refsect1 id="seealso"><title>See Also</title>
	208	<para>
	209	<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
	210	<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
	211	<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
	212	<citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
	213	<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
	214	<citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
	215	<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
	216	<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
	217	<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
	218	<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
	219	<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
	220	<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
	221	<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
	222	</para>
	223	</refsect1>
	224	<refsect1 id="Copyright"><title>Copyright</title>
	225	<para>
	226	Copyright <trademark class="copyright"></trademark> 1991-2006
	227	Silicon Graphics, Inc. This document is licensed under the SGI
	228	Free Software B License. For details, see
	229	<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
	230	</para>
	231	</refsect1>
	232	</refentry>