upstream-doc/man2/glCopyTexSubImage3D.xml

   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="glCopyTexSubImage3D">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glCopyTexSubImage3D</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glCopyTexSubImage3D</refname>
  17         <refpurpose>copy a three-dimensional texture subimage</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glCopyTexSubImage3D</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>GLint <parameter>x</parameter></paramdef>
  29                 <paramdef>GLint <parameter>y</parameter></paramdef>
  30                 <paramdef>GLsizei <parameter>width</parameter></paramdef>
  31                 <paramdef>GLsizei <parameter>height</parameter></paramdef>
  32             </funcprototype>
  33         </funcsynopsis>
  34     </refsynopsisdiv>
  35     <!-- eqn: ignoring delim $$ -->
  36     <para>
  37     </para>
  38     <refsect1 id="parameters"><title>Parameters</title>
  39         <variablelist>
  40         <varlistentry>
  41             <term><parameter>target</parameter></term>
  42             <listitem>
  43                 <para>
  44                     Specifies the target texture.
  45                     Must be <constant>GL_TEXTURE_3D</constant>
  46                 </para>
  47             </listitem>
  48         </varlistentry>
  49         <varlistentry>
  50             <term><parameter>level</parameter></term>
  51             <listitem>
  52                 <para>
  53                     Specifies the level-of-detail number.
  54                     Level 0 is the base image level.
  55                     Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
  56                 </para>
  57             </listitem>
  58         </varlistentry>
  59         <varlistentry>
  60             <term><parameter>xoffset</parameter></term>
  61             <listitem>
  62                 <para>
  63                     Specifies a texel offset in the x direction within the texture array.
  64                 </para>
  65             </listitem>
  66         </varlistentry>
  67         <varlistentry>
  68             <term><parameter>yoffset</parameter></term>
  69             <listitem>
  70                 <para>
  71                     Specifies a texel offset in the y direction within the texture array.
  72                 </para>
  73             </listitem>
  74         </varlistentry>
  75         <varlistentry>
  76             <term><parameter>zoffset</parameter></term>
  77             <listitem>
  78                 <para>
  79                     Specifies a texel offset in the z direction within the texture array.
  80                 </para>
  81             </listitem>
  82         </varlistentry>
  83         <varlistentry>
  84             <term><parameter>x</parameter></term>
  85             <term><parameter>y</parameter></term>
  86             <listitem>
  87                 <para>
  88                     Specify the window coordinates of the lower left corner
  89                     of the rectangular region of pixels to be copied.
  90                 </para>
  91             </listitem>
  92         </varlistentry>
  93         <varlistentry>
  94             <term><parameter>width</parameter></term>
  95             <listitem>
  96                 <para>
  97                     Specifies the width of the texture subimage.
  98                 </para>
  99             </listitem>
 100         </varlistentry>
 101         <varlistentry>
 102             <term><parameter>height</parameter></term>
 103             <listitem>
 104                 <para>
 105                     Specifies the height of the texture subimage.
 106                 </para>
 107             </listitem>
 108         </varlistentry>
 109         </variablelist>
 110     </refsect1>
 111     <refsect1 id="description"><title>Description</title>
 112         <para>
 113             <function>glCopyTexSubImage3D</function> replaces a rectangular portion of a three-dimensional
 114             texture image with pixels from the current <constant>GL_READ_BUFFER</constant> (rather
 115             than from main memory, as is the case for <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>).
 116         </para>
 117         <para>
 118             The screen-aligned pixel rectangle with lower left corner at
 119             (<parameter>x</parameter>,\ <parameter>y</parameter>) and with
 120             width <parameter>width</parameter> and height <parameter>height</parameter> replaces the portion of the
 121             texture array with x indices <parameter>xoffset</parameter> through
 122             <inlineequation><mml:math>
 123                 <!-- eqn: xoffset  +  width  -  1:-->
 124                 <mml:mrow>
 125                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 126                     <mml:mo>+</mml:mo>
 127                     <mml:mi mathvariant="italic">width</mml:mi>
 128                     <mml:mo>-</mml:mo>
 129                     <mml:mn>1</mml:mn>
 130                 </mml:mrow>
 131             </mml:math></inlineequation>,
 132             inclusive, and y indices <parameter>yoffset</parameter> through
 133             <inlineequation><mml:math>
 134                 <!-- eqn: yoffset  +  height  -  1:-->
 135                 <mml:mrow>
 136                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 137                     <mml:mo>+</mml:mo>
 138                     <mml:mi mathvariant="italic">height</mml:mi>
 139                     <mml:mo>-</mml:mo>
 140                     <mml:mn>1</mml:mn>
 141                 </mml:mrow>
 142             </mml:math></inlineequation>,
 143             inclusive, at z index <parameter>zoffset</parameter> and at the mipmap level specified by <parameter>level</parameter>.
 144         </para>
 145         <para>
 146             The pixels in the rectangle are processed exactly as if
 147             <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry> had been called, but the process stops just before
 148             final conversion.
 149             At this point, all pixel component values are clamped to the range
 150             <inlineequation><mml:math>
 151                 <!-- eqn: [0,1]:-->
 152                 <mml:mfenced open="[" close="]">
 153                     <mml:mn>0</mml:mn>
 154                     <mml:mn>1</mml:mn>
 155                 </mml:mfenced>
 156             </mml:math></inlineequation>
 157             and then converted to the texture's internal format for storage in the texel
 158             array.
 159         </para>
 160         <para>
 161             The destination rectangle in the texture array may not include any texels
 162             outside the texture array as it was originally specified.
 163             It is not an error to specify a subtexture with zero width or height, but
 164             such a specification has no effect.
 165         </para>
 166         <para>
 167             If any of the pixels within the specified rectangle of the current
 168             <constant>GL_READ_BUFFER</constant> are outside the read window associated with the current
 169             rendering context, then the values obtained for those pixels are undefined.
 170         </para>
 171         <para>
 172             No change is made to the <emphasis>internalformat</emphasis>, <emphasis>width</emphasis>,
 173             <emphasis>height</emphasis>, <emphasis>depth</emphasis>, or <emphasis>border</emphasis> parameters of the specified texture
 174             array or to texel values outside the specified subregion.
 175         </para>
 176     </refsect1>
 177     <refsect1 id="notes"><title>Notes</title>
 178         <para>
 179             <function>glCopyTexSubImage3D</function> is available only if the GL version is 1.2 or greater.
 180         </para>
 181         <para>
 182             Texturing has no effect in color index mode.
 183         </para>
 184         <para>
 185             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry> modes affect texture images
 186             in exactly the way they affect <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>.
 187         </para>
 188         <para>
 189             When the <code>ARB_imaging</code> extension is supported, the RGBA components
 190             copied from the framebuffer may be processed by the imaging pipeline, as
 191             if they were a two-dimensional texture.  See <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> for
 192             specific details.
 193         </para>
 194     </refsect1>
 195     <refsect1 id="errors"><title>Errors</title>
 196         <para>
 197             <constant>GL_INVALID_ENUM</constant> is generated if /<parameter>target</parameter> is not <constant>GL_TEXTURE_3D</constant>.
 198         </para>
 199         <para>
 200             <constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not
 201             been defined by a previous <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry> operation.
 202         </para>
 203         <para>
 204             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
 205         </para>
 206         <para>
 207             <constant>GL_INVALID_VALUE</constant> may be generated if
 208             <inlineequation><mml:math>
 209                 <!-- eqn: level  >  log sub 2(max):-->
 210                 <mml:mrow>
 211                     <mml:mi mathvariant="italic">level</mml:mi>
 212                     <mml:mo>&gt;</mml:mo>
 213                     <mml:mrow>
 214                         <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 215                         <mml:mn>2</mml:mn>
 216                         </mml:msub>
 217                         <mml:mo>&af;</mml:mo>
 218                         <mml:mfenced open="(" close=")">
 219                             <mml:mi mathvariant="italic">max</mml:mi>
 220                         </mml:mfenced>
 221                     </mml:mrow>
 222                 </mml:mrow>
 223             </mml:math></inlineequation>,
 224             where
 225             <inlineequation><mml:math><mml:mi mathvariant="italic">max</mml:mi></mml:math></inlineequation>
 226             is the returned value of <constant>GL_MAX_3D_TEXTURE_SIZE</constant>.
 227         </para>
 228         <para>
 229             <constant>GL_INVALID_VALUE</constant> is generated if
 230             <inlineequation><mml:math>
 231                 <!-- eqn: xoffset  <  -b:-->
 232                 <mml:mrow>
 233                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 234                     <mml:mo>&lt;</mml:mo>
 235                     <mml:mrow>
 236                         <mml:mo>-</mml:mo>
 237                         <mml:mi mathvariant="italic">b</mml:mi>
 238                     </mml:mrow>
 239                 </mml:mrow>
 240             </mml:math></inlineequation>,
 241             <inlineequation><mml:math>
 242                 <!-- eqn: (xoffset  +  width)  >  (w  - b):-->
 243                 <mml:mrow>
 244                     <mml:mfenced open="(" close=")">
 245                         <mml:mrow>
 246                             <mml:mi mathvariant="italic">xoffset</mml:mi>
 247                             <mml:mo>+</mml:mo>
 248                             <mml:mi mathvariant="italic">width</mml:mi>
 249                         </mml:mrow>
 250                     </mml:mfenced>
 251                     <mml:mo>&gt;</mml:mo>
 252                     <mml:mfenced open="(" close=")">
 253                         <mml:mrow>
 254                             <mml:mi mathvariant="italic">w</mml:mi>
 255                             <mml:mo>-</mml:mo>
 256                             <mml:mi mathvariant="italic">b</mml:mi>
 257                         </mml:mrow>
 258                     </mml:mfenced>
 259                 </mml:mrow>
 260             </mml:math></inlineequation>,
 261             <inlineequation><mml:math>
 262                 <!-- eqn: yoffset  <   -b:-->
 263                 <mml:mrow>
 264                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 265                     <mml:mo>&lt;</mml:mo>
 266                     <mml:mrow>
 267                         <mml:mo>-</mml:mo>
 268                         <mml:mi mathvariant="italic">b</mml:mi>
 269                     </mml:mrow>
 270                 </mml:mrow>
 271             </mml:math></inlineequation>,
 272             <inlineequation><mml:math>
 273                 <!-- eqn: (yoffset  +  height)  >  (h  - b):-->
 274                 <mml:mrow>
 275                     <mml:mfenced open="(" close=")">
 276                         <mml:mrow>
 277                             <mml:mi mathvariant="italic">yoffset</mml:mi>
 278                             <mml:mo>+</mml:mo>
 279                             <mml:mi mathvariant="italic">height</mml:mi>
 280                         </mml:mrow>
 281                     </mml:mfenced>
 282                     <mml:mo>&gt;</mml:mo>
 283                     <mml:mfenced open="(" close=")">
 284                         <mml:mrow>
 285                             <mml:mi mathvariant="italic">h</mml:mi>
 286                             <mml:mo>-</mml:mo>
 287                             <mml:mi mathvariant="italic">b</mml:mi>
 288                         </mml:mrow>
 289                     </mml:mfenced>
 290                 </mml:mrow>
 291             </mml:math></inlineequation>,
 292             <inlineequation><mml:math>
 293                 <!-- eqn: zoffset  <   -b:-->
 294                 <mml:mrow>
 295                     <mml:mi mathvariant="italic">zoffset</mml:mi>
 296                     <mml:mo>&lt;</mml:mo>
 297                     <mml:mrow>
 298                         <mml:mo>-</mml:mo>
 299                         <mml:mi mathvariant="italic">b</mml:mi>
 300                     </mml:mrow>
 301                 </mml:mrow>
 302             </mml:math></inlineequation>,
 303             or
 304             <inlineequation><mml:math>
 305                 <!-- eqn: (zoffset  +  1)  >  (d  - b):-->
 306                 <mml:mrow>
 307                      <mml:mfenced open="(" close=")">
 308                         <mml:mrow>
 309                             <mml:mi mathvariant="italic">zoffset</mml:mi>
 310                             <mml:mo>+</mml:mo>
 311                             <mml:mn>1</mml:mn>
 312                         </mml:mrow>
 313                     </mml:mfenced>
 314                     <mml:mo>&gt;</mml:mo>
 315                     <mml:mfenced open="(" close=")">
 316                         <mml:mrow>
 317                             <mml:mi mathvariant="italic">d</mml:mi>
 318                             <mml:mo>-</mml:mo>
 319                             <mml:mi mathvariant="italic">b</mml:mi>
 320                         </mml:mrow>
 321                     </mml:mfenced>
 322                 </mml:mrow>
 323             </mml:math></inlineequation>,
 324             where
 325             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 326             is the <constant>GL_TEXTURE_WIDTH</constant>,
 327             <inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
 328             is the <constant>GL_TEXTURE_HEIGHT</constant>,
 329             <inlineequation><mml:math><mml:mi mathvariant="italic">d</mml:mi></mml:math></inlineequation>
 330             is the <constant>GL_TEXTURE_DEPTH</constant>,
 331             and
 332             <inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
 333             is the <constant>GL_TEXTURE_BORDER</constant>
 334             of the texture image being modified.
 335             Note that
 336             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>,
 337             <inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>,
 338             and
 339             <inlineequation><mml:math><mml:mi mathvariant="italic">d</mml:mi></mml:math></inlineequation>
 340             include twice the border width.
 341         </para>
 342         <para>
 343             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyTexSubImage3D</function> is executed
 344             between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
 345             execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 346         </para>
 347     </refsect1>
 348     <refsect1 id="associatedgets"><title>Associated Gets</title>
 349         <para>
 350             <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
 351         </para>
 352         <para>
 353             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_3D</constant>
 354         </para>
 355     </refsect1>
 356     <refsect1 id="seealso"><title>See Also</title>
 357         <para>
 358             <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
 359             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 360             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 361             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 362             <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
 363             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 364             <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
 365             <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
 366             <citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
 367             <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
 368             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 369             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 370             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 371             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
 372             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 373             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 374             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
 375         </para>
 376     </refsect1>
 377     <refsect1 id="Copyright"><title>Copyright</title>
 378         <para>
 379             Copyright <trademark class="copyright"></trademark> 1991-2006
 380             Silicon Graphics, Inc. This document is licensed under the SGI
 381             Free Software B License. For details, see
 382             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 383         </para>
 384     </refsect1>
 385 </refentry>