upstream-doc/man3/xhtml/glTexSubImage3D.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   3 <!-- saved from url=(0013)about:internet -->
   4 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><link rel="stylesheet" type="text/css" href="opengl-man.css" /><title>glTexSubImage3D - OpenGL 3.3 Reference Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glTexSubImage3D"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glTexSubImage3D — specify a three-dimensional texture subimage</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glTexSubImage3D</b>(</code></td><td>GLenum  </td><td><var class="pdparam">target</var>, </td></tr><tr><td> </td><td>GLint  </td><td><var class="pdparam">level</var>, </td></tr><tr><td> </td><td>GLint  </td><td><var class="pdparam">xoffset</var>, </td></tr><tr><td> </td><td>GLint  </td><td><var class="pdparam">yoffset</var>, </td></tr><tr><td> </td><td>GLint  </td><td><var class="pdparam">zoffset</var>, </td></tr><tr><td> </td><td>GLsizei  </td><td><var class="pdparam">width</var>, </td></tr><tr><td> </td><td>GLsizei  </td><td><var class="pdparam">height</var>, </td></tr><tr><td> </td><td>GLsizei  </td><td><var class="pdparam">depth</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">format</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">type</var>, </td></tr><tr><td> </td><td>const GLvoid *  </td><td><var class="pdparam">data</var><code>)</code>;</td></tr></table></div></div><p>
   5     </p><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
   6                     Specifies the target texture.
   7                     Must be <code class="constant">GL_TEXTURE_3D</code> or <code class="constant">GL_TEXTURE_2D_ARRAY</code>.
   8                 </p></dd><dt><span class="term"><em class="parameter"><code>level</code></em></span></dt><dd><p>
   9                     Specifies the level-of-detail number.
  10                     Level 0 is the base image level.
  11                     Level <span class="emphasis"><em>n</em></span> is the <span class="emphasis"><em>n</em></span>th mipmap reduction image.
  12                 </p></dd><dt><span class="term"><em class="parameter"><code>xoffset</code></em></span></dt><dd><p>
  13                     Specifies a texel offset in the x direction within the texture array.
  14                 </p></dd><dt><span class="term"><em class="parameter"><code>yoffset</code></em></span></dt><dd><p>
  15                     Specifies a texel offset in the y direction within the texture array.
  16                 </p></dd><dt><span class="term"><em class="parameter"><code>zoffset</code></em></span></dt><dd><p>
  17                     Specifies a texel offset in the z direction within the texture array.
  18                 </p></dd><dt><span class="term"><em class="parameter"><code>width</code></em></span></dt><dd><p>
  19                     Specifies the width of the texture subimage.
  20                 </p></dd><dt><span class="term"><em class="parameter"><code>height</code></em></span></dt><dd><p>
  21                     Specifies the height of the texture subimage.
  22                 </p></dd><dt><span class="term"><em class="parameter"><code>depth</code></em></span></dt><dd><p>
  23                     Specifies the depth of the texture subimage.
  24                 </p></dd><dt><span class="term"><em class="parameter"><code>format</code></em></span></dt><dd><p>
  25                     Specifies the format of the pixel data.
  26                     The following symbolic values are accepted:
  27                     <code class="constant">GL_RED</code>,
  28                     <code class="constant">GL_RG</code>,
  29                     <code class="constant">GL_RGB</code>,
  30                     <code class="constant">GL_BGR</code>,
  31                     <code class="constant">GL_RGBA</code>, and
  32                     <code class="constant">GL_BGRA</code>.
  33                 </p></dd><dt><span class="term"><em class="parameter"><code>type</code></em></span></dt><dd><p>
  34                     Specifies the data type of the pixel data.
  35                     The following symbolic values are accepted:
  36                     <code class="constant">GL_UNSIGNED_BYTE</code>,
  37                     <code class="constant">GL_BYTE</code>,
  38                     <code class="constant">GL_UNSIGNED_SHORT</code>,
  39                     <code class="constant">GL_SHORT</code>,
  40                     <code class="constant">GL_UNSIGNED_INT</code>,
  41                     <code class="constant">GL_INT</code>,
  42                     <code class="constant">GL_FLOAT</code>,
  43                     <code class="constant">GL_UNSIGNED_BYTE_3_3_2</code>,
  44                     <code class="constant">GL_UNSIGNED_BYTE_2_3_3_REV</code>,
  45                     <code class="constant">GL_UNSIGNED_SHORT_5_6_5</code>,
  46                     <code class="constant">GL_UNSIGNED_SHORT_5_6_5_REV</code>,
  47                     <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4</code>,
  48                     <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4_REV</code>,
  49                     <code class="constant">GL_UNSIGNED_SHORT_5_5_5_1</code>,
  50                     <code class="constant">GL_UNSIGNED_SHORT_1_5_5_5_REV</code>,
  51                     <code class="constant">GL_UNSIGNED_INT_8_8_8_8</code>,
  52                     <code class="constant">GL_UNSIGNED_INT_8_8_8_8_REV</code>,
  53                     <code class="constant">GL_UNSIGNED_INT_10_10_10_2</code>, and
  54                     <code class="constant">GL_UNSIGNED_INT_2_10_10_10_REV</code>.
  55                 </p></dd><dt><span class="term"><em class="parameter"><code>data</code></em></span></dt><dd><p>
  56                     Specifies a pointer to the image data in memory.
  57                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  58             Texturing maps a portion of a specified texture image
  59             onto each graphical primitive for which texturing is enabled.
  60         </p><p>
  61             <code class="function">glTexSubImage3D</code> redefines a contiguous subregion of an existing three-dimensional
  62             or two-dimensioanl array texture image.
  63             The texels referenced by <em class="parameter"><code>data</code></em> replace the portion of the
  64             existing texture array with x indices <em class="parameter"><code>xoffset</code></em> and
  65             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  66
  67                 <mml:mrow>
  68                     <mml:mi mathvariant="italic">xoffset</mml:mi>
  69                     <mml:mo>+</mml:mo>
  70                     <mml:mi mathvariant="italic">width</mml:mi>
  71                     <mml:mo>-</mml:mo>
  72                     <mml:mn>1</mml:mn>
  73                 </mml:mrow>
  74             </mml:math>,
  75             inclusive,
  76             y indices <em class="parameter"><code>yoffset</code></em> and
  77             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  78
  79                 <mml:mrow>
  80                     <mml:mi mathvariant="italic">yoffset</mml:mi>
  81                     <mml:mo>+</mml:mo>
  82                     <mml:mi mathvariant="italic">height</mml:mi>
  83                     <mml:mo>-</mml:mo>
  84                     <mml:mn>1</mml:mn>
  85                 </mml:mrow>
  86             </mml:math>,
  87             inclusive,
  88             and z indices <em class="parameter"><code>zoffset</code></em> and
  89             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  90
  91                 <mml:mrow>
  92                     <mml:mi mathvariant="italic">zoffset</mml:mi>
  93                     <mml:mo>+</mml:mo>
  94                     <mml:mi mathvariant="italic">depth</mml:mi>
  95                     <mml:mo>-</mml:mo>
  96                     <mml:mn>1</mml:mn>
  97                 </mml:mrow>
  98             </mml:math>,
  99             inclusive.
 100             For three-dimensional textures, the z index refers to the third
 101             dimension. For two-dimensional array textures, the z index refers to
 102             the slice index.
 103             This region may not include any texels outside the range of the
 104             texture array as it was originally specified.
 105             It is not an error to specify a subtexture with zero width, height, or
 106             depth but such a specification has no effect.
 107         </p><p>
 108             If a non-zero named buffer object is bound to the <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target
 109             (see <a href="glBindBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glBindBuffer</span></span></a>) while a texture image is
 110             specified, <em class="parameter"><code>data</code></em> is treated as a byte offset into the buffer object's data store.
 111         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
 112             The <a href="glPixelStore.xml"><span class="citerefentry"><span class="refentrytitle">glPixelStore</span></span></a> modes affect texture images.
 113         </p><p>
 114             <code class="function">glTexSubImage3D</code> specifies a three-dimensional or two-dimenaional array subtexture for the current texture unit,
 115             specified with <a href="glActiveTexture.xml"><span class="citerefentry"><span class="refentrytitle">glActiveTexture</span></span></a>.
 116         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
 117             <code class="constant">GL_INVALID_ENUM</code> is generated if /<em class="parameter"><code>target</code></em> is not <code class="constant">GL_TEXTURE_3D</code> or <code class="constant">GL_TEXTURE_2D_ARRAY</code>.
 118         </p><p>
 119             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>format</code></em> is not an accepted
 120             format constant.
 121         </p><p>
 122             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>type</code></em> is not a type constant.
 123         </p><p>
 124             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>level</code></em> is less than 0.
 125         </p><p>
 126             <code class="constant">GL_INVALID_VALUE</code> may be generated if <em class="parameter"><code>level</code></em> is greater
 127             than
 128             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 129
 130                 <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 131                 <mml:mn>2</mml:mn>
 132                 </mml:msub>
 133             </mml:math>
 134             <span class="emphasis"><em>max</em></span>,
 135             where <span class="emphasis"><em>max</em></span> is the returned value of <code class="constant">GL_MAX_TEXTURE_SIZE</code>.
 136         </p><p>
 137             <code class="constant">GL_INVALID_VALUE</code> is generated if
 138             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 139
 140                 <mml:mrow>
 141                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 142                     <mml:mo>&lt;</mml:mo>
 143                     <mml:mrow>
 144                         <mml:mo>-</mml:mo>
 145                         <mml:mi mathvariant="italic">b</mml:mi>
 146                     </mml:mrow>
 147                 </mml:mrow>
 148             </mml:math>,
 149             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 150
 151                 <mml:mrow>
 152                     <mml:mfenced open="(" close=")">
 153                         <mml:mrow>
 154                             <mml:mi mathvariant="italic">xoffset</mml:mi>
 155                             <mml:mo>+</mml:mo>
 156                             <mml:mi mathvariant="italic">width</mml:mi>
 157                         </mml:mrow>
 158                     </mml:mfenced>
 159                     <mml:mo>&gt;</mml:mo>
 160                     <mml:mfenced open="(" close=")">
 161                         <mml:mrow>
 162                             <mml:mi mathvariant="italic">w</mml:mi>
 163                             <mml:mo>-</mml:mo>
 164                             <mml:mi mathvariant="italic">b</mml:mi>
 165                         </mml:mrow>
 166                     </mml:mfenced>
 167                 </mml:mrow>
 168             </mml:math>,
 169             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 170
 171                 <mml:mrow>
 172                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 173                     <mml:mo>&lt;</mml:mo>
 174                     <mml:mrow>
 175                         <mml:mo>-</mml:mo>
 176                         <mml:mi mathvariant="italic">b</mml:mi>
 177                     </mml:mrow>
 178                 </mml:mrow>
 179             </mml:math>,
 180             or
 181             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 182
 183                 <mml:mrow>
 184                     <mml:mfenced open="(" close=")">
 185                         <mml:mrow>
 186                             <mml:mi mathvariant="italic">yoffset</mml:mi>
 187                             <mml:mo>+</mml:mo>
 188                             <mml:mi mathvariant="italic">height</mml:mi>
 189                         </mml:mrow>
 190                     </mml:mfenced>
 191                     <mml:mo>&gt;</mml:mo>
 192                     <mml:mfenced open="(" close=")">
 193                         <mml:mrow>
 194                             <mml:mi mathvariant="italic">h</mml:mi>
 195                             <mml:mo>-</mml:mo>
 196                             <mml:mi mathvariant="italic">b</mml:mi>
 197                         </mml:mrow>
 198                     </mml:mfenced>
 199                 </mml:mrow>
 200             </mml:math>,
 201             or
 202             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 203
 204                 <mml:mrow>
 205                     <mml:mi mathvariant="italic">zoffset</mml:mi>
 206                     <mml:mo>&lt;</mml:mo>
 207                     <mml:mrow>
 208                         <mml:mo>-</mml:mo>
 209                         <mml:mi mathvariant="italic">b</mml:mi>
 210                     </mml:mrow>
 211                 </mml:mrow>
 212             </mml:math>,
 213             or
 214             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 215
 216                 <mml:mrow>
 217                     <mml:mfenced open="(" close=")">
 218                         <mml:mrow>
 219                             <mml:mi mathvariant="italic">zoffset</mml:mi>
 220                             <mml:mo>+</mml:mo>
 221                             <mml:mi mathvariant="italic">depth</mml:mi>
 222                         </mml:mrow>
 223                     </mml:mfenced>
 224                     <mml:mo>&gt;</mml:mo>
 225                     <mml:mfenced open="(" close=")">
 226                         <mml:mrow>
 227                             <mml:mi mathvariant="italic">d</mml:mi>
 228                             <mml:mo>-</mml:mo>
 229                             <mml:mi mathvariant="italic">b</mml:mi>
 230                         </mml:mrow>
 231                     </mml:mfenced>
 232                 </mml:mrow>
 233             </mml:math>,
 234             where
 235             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">w</mml:mi></mml:math>
 236             is the <code class="constant">GL_TEXTURE_WIDTH</code>,
 237             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">h</mml:mi></mml:math>
 238             is the <code class="constant">GL_TEXTURE_HEIGHT</code>,
 239             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">d</mml:mi></mml:math>
 240             is the <code class="constant">GL_TEXTURE_DEPTH</code>
 241             and
 242             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">b</mml:mi></mml:math>
 243             is the border width of the texture image being modified.
 244             Note that
 245             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">w</mml:mi></mml:math>,
 246             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">h</mml:mi></mml:math>,
 247             and
 248             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">d</mml:mi></mml:math>
 249             include twice the border width.
 250         </p><p>
 251             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>width</code></em>, <em class="parameter"><code>height</code></em>, or <em class="parameter"><code>depth</code></em>
 252             is less than 0.
 253         </p><p>
 254             <code class="constant">GL_INVALID_OPERATION</code> is generated if the texture array has not
 255             been defined by a previous <a href="glTexImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage3D</span></span></a> operation.
 256         </p><p>
 257             <code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>type</code></em> is one of
 258             <code class="constant">GL_UNSIGNED_BYTE_3_3_2</code>,
 259             <code class="constant">GL_UNSIGNED_BYTE_2_3_3_REV</code>,
 260             <code class="constant">GL_UNSIGNED_SHORT_5_6_5</code>, or
 261             <code class="constant">GL_UNSIGNED_SHORT_5_6_5_REV</code>
 262             and <em class="parameter"><code>format</code></em> is not <code class="constant">GL_RGB</code>.
 263         </p><p>
 264             <code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>type</code></em> is one of
 265             <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4</code>,
 266             <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4_REV</code>,
 267             <code class="constant">GL_UNSIGNED_SHORT_5_5_5_1</code>,
 268             <code class="constant">GL_UNSIGNED_SHORT_1_5_5_5_REV</code>,
 269             <code class="constant">GL_UNSIGNED_INT_8_8_8_8</code>,
 270             <code class="constant">GL_UNSIGNED_INT_8_8_8_8_REV</code>,
 271             <code class="constant">GL_UNSIGNED_INT_10_10_10_2</code>, or
 272             <code class="constant">GL_UNSIGNED_INT_2_10_10_10_REV</code>
 273             and <em class="parameter"><code>format</code></em> is neither <code class="constant">GL_RGBA</code> nor <code class="constant">GL_BGRA</code>.
 274         </p><p>
 275             <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
 276             <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and the buffer object's data store is currently mapped.
 277         </p><p>
 278             <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
 279             <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and the data would be unpacked from the buffer
 280             object such that the memory reads required would exceed the data store size.
 281         </p><p>
 282             <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
 283             <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and <em class="parameter"><code>data</code></em> is not evenly divisible
 284             into the number of bytes needed to store in memory a datum indicated by <em class="parameter"><code>type</code></em>.
 285         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
 286             <a href="glGetTexImage.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexImage</span></span></a>
 287         </p><p>
 288             <a href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_PIXEL_UNPACK_BUFFER_BINDING</code>
 289         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 290             <a href="glActiveTexture.xml"><span class="citerefentry"><span class="refentrytitle">glActiveTexture</span></span></a>,
 291             <a href="glCopyTexImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glCopyTexImage1D</span></span></a>,
 292             <a href="glCopyTexImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glCopyTexImage2D</span></span></a>,
 293             <a href="glCopyTexSubImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glCopyTexSubImage1D</span></span></a>,
 294             <a href="glCopyTexSubImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glCopyTexSubImage2D</span></span></a>,
 295             <a href="glCopyTexSubImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glCopyTexSubImage3D</span></span></a>,
 296             <a href="glPixelStore.xml"><span class="citerefentry"><span class="refentrytitle">glPixelStore</span></span></a>,
 297             <a href="glTexImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage1D</span></span></a>,
 298             <a href="glTexImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage2D</span></span></a>,
 299             <a href="glTexImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage3D</span></span></a>,
 300             <a href="glTexSubImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexSubImage1D</span></span></a>,
 301             <a href="glTexSubImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glTexSubImage2D</span></span></a>,
 302             <a href="glTexParameter.xml"><span class="citerefentry"><span class="refentrytitle">glTexParameter</span></span></a>
 303         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 304             Copyright <span class="trademark"></span>© 1991-2006
 305             Silicon Graphics, Inc. This document is licensed under the SGI
 306             Free Software B License. For details, see
 307             <a href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
 308         </p></div></div></body></html>