upstream-man-pages/man4/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> or <constant>GL_TEXTURE_2D_ARRAY</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             or two-dimensional array 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>glReadPixels</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             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> modes affect texture images.
 180         </para>
 181     </refsect1>
 182     <refsect1 id="errors"><title>Errors</title>
 183         <para>
 184             <constant>GL_INVALID_ENUM</constant> is generated if /<parameter>target</parameter> is not <constant>GL_TEXTURE_3D</constant>.
 185         </para>
 186         <para>
 187             <constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not
 188             been defined by a previous <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry> operation.
 189         </para>
 190         <para>
 191             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
 192         </para>
 193         <para>
 194             <constant>GL_INVALID_VALUE</constant> may be generated if
 195             <inlineequation><mml:math>
 196                 <!-- eqn: level  >  log sub 2(max): -->
 197                 <mml:mrow>
 198                     <mml:mi mathvariant="italic">level</mml:mi>
 199                     <mml:mo>&gt;</mml:mo>
 200                     <mml:mrow>
 201                         <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 202                         <mml:mn>2</mml:mn>
 203                         </mml:msub>
 204                         <mml:mo>&af;</mml:mo>
 205                         <mml:mfenced open="(" close=")">
 206                             <mml:mi mathvariant="italic">max</mml:mi>
 207                         </mml:mfenced>
 208                     </mml:mrow>
 209                 </mml:mrow>
 210             </mml:math></inlineequation>,
 211             where
 212             <inlineequation><mml:math><mml:mi mathvariant="italic">max</mml:mi></mml:math></inlineequation>
 213             is the returned value of <constant>GL_MAX_3D_TEXTURE_SIZE</constant> if <parameter>target</parameter>
 214             is <constant>GL_TEXTURE_3D</constant> or the returned value of <constant>GL_MAX_ARRAY_TEXTURE_LAYERS</constant>
 215             if <parameter>target</parameter> is <constant>GL_TEXTURE_2D_ARRAY</constant>.
 216         </para>
 217         <para>
 218             <constant>GL_INVALID_VALUE</constant> is generated if
 219             <inlineequation><mml:math>
 220                 <!-- eqn: xoffset  <  -b: -->
 221                 <mml:mrow>
 222                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 223                     <mml:mo>&lt;</mml:mo>
 224                     <mml:mrow>
 225                         <mml:mo>-</mml:mo>
 226                         <mml:mi mathvariant="italic">b</mml:mi>
 227                     </mml:mrow>
 228                 </mml:mrow>
 229             </mml:math></inlineequation>,
 230             <inlineequation><mml:math>
 231                 <!-- eqn: (xoffset  +  width)  >  (w  - b): -->
 232                 <mml:mrow>
 233                     <mml:mfenced open="(" close=")">
 234                         <mml:mrow>
 235                             <mml:mi mathvariant="italic">xoffset</mml:mi>
 236                             <mml:mo>+</mml:mo>
 237                             <mml:mi mathvariant="italic">width</mml:mi>
 238                         </mml:mrow>
 239                     </mml:mfenced>
 240                     <mml:mo>&gt;</mml:mo>
 241                     <mml:mfenced open="(" close=")">
 242                         <mml:mrow>
 243                             <mml:mi mathvariant="italic">w</mml:mi>
 244                             <mml:mo>-</mml:mo>
 245                             <mml:mi mathvariant="italic">b</mml:mi>
 246                         </mml:mrow>
 247                     </mml:mfenced>
 248                 </mml:mrow>
 249             </mml:math></inlineequation>,
 250             <inlineequation><mml:math>
 251                 <!-- eqn: yoffset  <   -b: -->
 252                 <mml:mrow>
 253                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 254                     <mml:mo>&lt;</mml:mo>
 255                     <mml:mrow>
 256                         <mml:mo>-</mml:mo>
 257                         <mml:mi mathvariant="italic">b</mml:mi>
 258                     </mml:mrow>
 259                 </mml:mrow>
 260             </mml:math></inlineequation>,
 261             <inlineequation><mml:math>
 262                 <!-- eqn: (yoffset  +  height)  >  (h  - b): -->
 263                 <mml:mrow>
 264                     <mml:mfenced open="(" close=")">
 265                         <mml:mrow>
 266                             <mml:mi mathvariant="italic">yoffset</mml:mi>
 267                             <mml:mo>+</mml:mo>
 268                             <mml:mi mathvariant="italic">height</mml:mi>
 269                         </mml:mrow>
 270                     </mml:mfenced>
 271                     <mml:mo>&gt;</mml:mo>
 272                     <mml:mfenced open="(" close=")">
 273                         <mml:mrow>
 274                             <mml:mi mathvariant="italic">h</mml:mi>
 275                             <mml:mo>-</mml:mo>
 276                             <mml:mi mathvariant="italic">b</mml:mi>
 277                         </mml:mrow>
 278                     </mml:mfenced>
 279                 </mml:mrow>
 280             </mml:math></inlineequation>,
 281             <inlineequation><mml:math>
 282                 <!-- eqn: zoffset  <   -b: -->
 283                 <mml:mrow>
 284                     <mml:mi mathvariant="italic">zoffset</mml:mi>
 285                     <mml:mo>&lt;</mml:mo>
 286                     <mml:mrow>
 287                         <mml:mo>-</mml:mo>
 288                         <mml:mi mathvariant="italic">b</mml:mi>
 289                     </mml:mrow>
 290                 </mml:mrow>
 291             </mml:math></inlineequation>,
 292             or
 293             <inlineequation><mml:math>
 294                 <!-- eqn: (zoffset  +  1)  >  (d  - b): -->
 295                 <mml:mrow>
 296                      <mml:mfenced open="(" close=")">
 297                         <mml:mrow>
 298                             <mml:mi mathvariant="italic">zoffset</mml:mi>
 299                             <mml:mo>+</mml:mo>
 300                             <mml:mn>1</mml:mn>
 301                         </mml:mrow>
 302                     </mml:mfenced>
 303                     <mml:mo>&gt;</mml:mo>
 304                     <mml:mfenced open="(" close=")">
 305                         <mml:mrow>
 306                             <mml:mi mathvariant="italic">d</mml:mi>
 307                             <mml:mo>-</mml:mo>
 308                             <mml:mi mathvariant="italic">b</mml:mi>
 309                         </mml:mrow>
 310                     </mml:mfenced>
 311                 </mml:mrow>
 312             </mml:math></inlineequation>,
 313             where
 314             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 315             is the <constant>GL_TEXTURE_WIDTH</constant>,
 316             <inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
 317             is the <constant>GL_TEXTURE_HEIGHT</constant>,
 318             <inlineequation><mml:math><mml:mi mathvariant="italic">d</mml:mi></mml:math></inlineequation>
 319             is the <constant>GL_TEXTURE_DEPTH</constant>,
 320             and
 321             <inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
 322             is the <constant>GL_TEXTURE_BORDER</constant>
 323             of the texture image being modified.
 324             Note that
 325             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>,
 326             <inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>,
 327             and
 328             <inlineequation><mml:math><mml:mi mathvariant="italic">d</mml:mi></mml:math></inlineequation>
 329             include twice the border width.
 330         </para>
 331     </refsect1>
 332     <refsect1 id="associatedgets"><title>Associated Gets</title>
 333         <para>
 334             <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
 335         </para>
 336     </refsect1>
 337     <refsect1 id="seealso"><title>See Also</title>
 338         <para>
 339             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 340             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 341             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 342             <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
 343             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 344             <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
 345             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 346             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 347             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 348             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
 349             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 350             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 351             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
 352         </para>
 353     </refsect1>
 354     <refsect1 id="Copyright"><title>Copyright</title>
 355         <para>
 356             Copyright <trademark class="copyright"></trademark> 1991-2006
 357             Silicon Graphics, Inc. This document is licensed under the SGI
 358             Free Software B License. For details, see
 359             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 360         </para>
 361     </refsect1>
 362 </refentry>