+++ /dev/null
-<?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="glCopyTexSubImage3D">
- <refmeta>
- <refmetainfo>
- <copyright>
- <year>1991-2006</year>
- <holder>Silicon Graphics, Inc.</holder>
- </copyright>
- </refmetainfo>
- <refentrytitle>glCopyTexSubImage3D</refentrytitle>
- <manvolnum>3G</manvolnum>
- </refmeta>
- <refnamediv>
- <refname>glCopyTexSubImage3D</refname>
- <refpurpose>copy a three-dimensional texture subimage</refpurpose>
- </refnamediv>
- <refsynopsisdiv><title>C Specification</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>void <function>glCopyTexSubImage3D</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>GLint <parameter>x</parameter></paramdef>
- <paramdef>GLint <parameter>y</parameter></paramdef>
- <paramdef>GLsizei <parameter>width</parameter></paramdef>
- <paramdef>GLsizei <parameter>height</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>x</parameter></term>
- <term><parameter>y</parameter></term>
- <listitem>
- <para>
- Specify the window coordinates of the lower left corner
- of the rectangular region 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>
- <varlistentry>
- <term><parameter>height</parameter></term>
- <listitem>
- <para>
- Specifies the height of the texture subimage.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1 id="description"><title>Description</title>
- <para>
- <function>glCopyTexSubImage3D</function> replaces a rectangular portion of a three-dimensional
- or two-dimensional array texture image with pixels from the current <constant>GL_READ_BUFFER</constant> (rather
- than from main memory, as is the case for <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>).
- </para>
- <para>
- The screen-aligned pixel rectangle with lower left corner at
- (<parameter>x</parameter>, <parameter>y</parameter>) and with
- width <parameter>width</parameter> and height <parameter>height</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, and y indices <parameter>yoffset</parameter> through
- <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, at z index <parameter>zoffset</parameter> and at the mipmap level specified by <parameter>level</parameter>.
- </para>
- <para>
- The pixels in the rectangle 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>
- The destination rectangle in the texture array may not include any texels
- outside the texture array as it was originally specified.
- It is not an error to specify a subtexture with zero width or height, but
- such a specification has no effect.
- </para>
- <para>
- If any of the pixels within the specified rectangle 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>,
- <emphasis>height</emphasis>, <emphasis>depth</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>
- <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> modes affect 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_3D</constant>.
- </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> 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>></mml:mo>
- <mml:mrow>
- <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
- <mml:mn>2</mml:mn>
- </mml:msub>
- <mml:mo>⁡</mml:mo>
- <mml:mfenced open="(" close=")">
- <mml:mi mathvariant="italic">max</mml:mi>
- </mml:mfenced>
- </mml:mrow>
- </mml:mrow>
- </mml:math></inlineequation>,
- where
- <inlineequation><mml:math><mml:mi mathvariant="italic">max</mml:mi></mml:math></inlineequation>
- is the returned value of <constant>GL_MAX_3D_TEXTURE_SIZE</constant> if <parameter>target</parameter>
- is <constant>GL_TEXTURE_3D</constant> or the returned value of <constant>GL_MAX_ARRAY_TEXTURE_LAYERS</constant>
- if <parameter>target</parameter> is <constant>GL_TEXTURE_2D_ARRAY</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><</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>></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><</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: (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>></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>,
- <inlineequation><mml:math>
- <!-- eqn: zoffset < -b: -->
- <mml:mrow>
- <mml:mi mathvariant="italic">zoffset</mml:mi>
- <mml:mo><</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 + 1) > (d - b): -->
- <mml:mrow>
- <mml:mfenced open="(" close=")">
- <mml:mrow>
- <mml:mi mathvariant="italic">zoffset</mml:mi>
- <mml:mo>+</mml:mo>
- <mml:mn>1</mml:mn>
- </mml:mrow>
- </mml:mfenced>
- <mml:mo>></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 <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>,
- <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>
- </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>glCopyTexSubImage1D</refentrytitle></citerefentry>,
- <citerefentry><refentrytitle>glCopyTexSubImage2D</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>
HCoop / clinton / guile-figl.git / blobdiff