[clinton/guile-figl.git] / upstream-doc / man4 / 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>, <emphasis>width</emphasis>,
            or <emphasis>border</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:mrow>
                        <mml:mo>-</mml:mo>
                        <mml:mi mathvariant="italic">b</mml:mi>
                    </mml:mrow>
                </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: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 <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>
        </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>
91	The screen-aligned pixel row with left corner at (<parameter>x</parameter>,\ <parameter>y</parameter>), and with
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>
131	No change is made to the <emphasis>internalformat</emphasis>, <emphasis>width</emphasis>,
132	or <emphasis>border</emphasis> parameters of the specified texture
133	array or to texel values outside the specified subregion.
134	</para>
135	</refsect1>
136	<refsect1 id="notes"><title>Notes</title>
137	<para>
138	The <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> mode affects texture images.
139	</para>
140	</refsect1>
141	<refsect1 id="errors"><title>Errors</title>
142	<para>
143	<constant>GL_INVALID_ENUM</constant> is generated if /<parameter>target</parameter> is not <constant>GL_TEXTURE_1D</constant>.
144	</para>
145	<para>
146	<constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not
147	been defined by a previous <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry> operation.
148	</para>
149	<para>
150	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
151	</para>
152	<para>
153	<constant>GL_INVALID_VALUE</constant> may be generated if
154	<inlineequation><mml:math>
155	<!-- eqn: level > log sub 2(max): -->
156	<mml:mrow>
157	<mml:mi mathvariant="italic">level</mml:mi>
158	<mml:mo>></mml:mo>
159	<mml:mrow>
160	<mml:msub><mml:mi mathvariant="italic">log</mml:mi>
161	<mml:mn>2</mml:mn>
162	</mml:msub>
163	<mml:mo>⁡</mml:mo>
164	<mml:mfenced open="(" close=")">
165	<mml:mi mathvariant="italic">max</mml:mi>
166	</mml:mfenced>
167	</mml:mrow>
168	</mml:mrow>
169	</mml:math></inlineequation>,
170	where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
171	</para>
172	<para>
173	<constant>GL_INVALID_VALUE</constant> is generated if
174	<inlineequation><mml:math>
175	<!-- eqn: xoffset < -b: -->
176	<mml:mrow>
177	<mml:mi mathvariant="italic">xoffset</mml:mi>
178	<mml:mo><</mml:mo>
179	<mml:mrow>
180	<mml:mo>-</mml:mo>
181	<mml:mi mathvariant="italic">b</mml:mi>
182	</mml:mrow>
183	</mml:mrow>
184	</mml:math></inlineequation>,
185	or
186	<inlineequation><mml:math>
187	<!-- eqn: (xoffset + width) > (w-b): -->
188	<mml:mrow>
189	<mml:mfenced open="(" close=")">
190	<mml:mrow>
191	<mml:mi mathvariant="italic">xoffset</mml:mi>
192	<mml:mo>+</mml:mo>
193	<mml:mi mathvariant="italic">width</mml:mi>
194	</mml:mrow>
195	</mml:mfenced>
196	<mml:mo>></mml:mo>
197	<mml:mfenced open="(" close=")">
198	<mml:mrow>
199	<mml:mi mathvariant="italic">w</mml:mi>
200	<mml:mo>-</mml:mo>
201	<mml:mi mathvariant="italic">b</mml:mi>
202	</mml:mrow>
203	</mml:mfenced>
204	</mml:mrow>
205	</mml:math></inlineequation>,
206	where
207	<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
208	is the <constant>GL_TEXTURE_WIDTH</constant> and
209	<inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
210	is the <constant>GL_TEXTURE_BORDER</constant>
211	of the texture image being modified.
212	Note that
213	<inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
214	includes twice the border width.
215	</para>
216	<para>
217	</para>
218	</refsect1>
219	<refsect1 id="associatedgets"><title>Associated Gets</title>
220	<para>
221	<citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
222	</para>
223	</refsect1>
224	<refsect1 id="seealso"><title>See Also</title>
225	<para>
226	<citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
227	<citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
228	<citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
229	<citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
230	<citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
231	<citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
232	<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
233	<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
234	<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
235	<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
236	<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
237	<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
238	<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
239	</para>
240	</refsect1>
241	<refsect1 id="Copyright"><title>Copyright</title>
242	<para>
243	Copyright <trademark class="copyright"></trademark> 1991-2006
244	Silicon Graphics, Inc. This document is licensed under the SGI
245	Free Software B License. For details, see
246	<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
247	</para>
248	</refsect1>
249	</refentry>