HCoop / clinton / guile-figl.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
update upstream sources
[clinton/guile-figl.git] / upstream-doc / man3 / xhtml / glTexSubImage3D.xml
CommitLineData
7faf1d71
AW		 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>
c7b31271 143 <mml:mn>0</mml:mn>
7faf1d71
AW		 144 </mml:mrow>
145 </mml:math>,
146 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
147
148 <mml:mrow>
149 <mml:mfenced open="(" close=")">
150 <mml:mrow>
151 <mml:mi mathvariant="italic">xoffset</mml:mi>
152 <mml:mo>+</mml:mo>
153 <mml:mi mathvariant="italic">width</mml:mi>
154 </mml:mrow>
155 </mml:mfenced>
156 <mml:mo>&gt;</mml:mo>
c7b31271 157 <mml:mi mathvariant="italic">w</mml:mi>
7faf1d71
AW		 158 </mml:mrow>
159 </mml:math>,
160 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
161
162 <mml:mrow>
163 <mml:mi mathvariant="italic">yoffset</mml:mi>
164 <mml:mo>&lt;</mml:mo>
c7b31271 165 <mml:mn>0</mml:mn>
7faf1d71
AW		 166 </mml:mrow>
167 </mml:math>,
168 or
169 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
170
171 <mml:mrow>
172 <mml:mfenced open="(" close=")">
173 <mml:mrow>
174 <mml:mi mathvariant="italic">yoffset</mml:mi>
175 <mml:mo>+</mml:mo>
176 <mml:mi mathvariant="italic">height</mml:mi>
177 </mml:mrow>
178 </mml:mfenced>
179 <mml:mo>&gt;</mml:mo>
c7b31271 180 <mml:mi mathvariant="italic">h</mml:mi>
7faf1d71
AW		 181 </mml:mrow>
182 </mml:math>,
183 or
184 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
185
186 <mml:mrow>
187 <mml:mi mathvariant="italic">zoffset</mml:mi>
188 <mml:mo>&lt;</mml:mo>
c7b31271 189 <mml:mn>0</mml:mn>
7faf1d71
AW		 190 </mml:mrow>
191 </mml:math>,
192 or
193 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
194
195 <mml:mrow>
196 <mml:mfenced open="(" close=")">
197 <mml:mrow>
198 <mml:mi mathvariant="italic">zoffset</mml:mi>
199 <mml:mo>+</mml:mo>
200 <mml:mi mathvariant="italic">depth</mml:mi>
201 </mml:mrow>
202 </mml:mfenced>
203 <mml:mo>&gt;</mml:mo>
c7b31271 204 <mml:mi mathvariant="italic">d</mml:mi>
7faf1d71
AW		 205 </mml:mrow>
206 </mml:math>,
207 where
208 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">w</mml:mi></mml:math>
209 is the <code class="constant">GL_TEXTURE_WIDTH</code>,
210 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">h</mml:mi></mml:math>
c7b31271 211 is the <code class="constant">GL_TEXTURE_HEIGHT</code>, and
7faf1d71
AW		 212 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">d</mml:mi></mml:math>
213 is the <code class="constant">GL_TEXTURE_DEPTH</code>
c7b31271 214 of the texture image being modified.
7faf1d71
AW		 215 </p><p>
216 <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>
217 is less than 0.
218 </p><p>
219 <code class="constant">GL_INVALID_OPERATION</code> is generated if the texture array has not
220 been defined by a previous <a href="glTexImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage3D</span></span></a> operation.
221 </p><p>
222 <code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>type</code></em> is one of
223 <code class="constant">GL_UNSIGNED_BYTE_3_3_2</code>,
224 <code class="constant">GL_UNSIGNED_BYTE_2_3_3_REV</code>,
225 <code class="constant">GL_UNSIGNED_SHORT_5_6_5</code>, or
226 <code class="constant">GL_UNSIGNED_SHORT_5_6_5_REV</code>
227 and <em class="parameter"><code>format</code></em> is not <code class="constant">GL_RGB</code>.
228 </p><p>
229 <code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>type</code></em> is one of
230 <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4</code>,
231 <code class="constant">GL_UNSIGNED_SHORT_4_4_4_4_REV</code>,
232 <code class="constant">GL_UNSIGNED_SHORT_5_5_5_1</code>,
233 <code class="constant">GL_UNSIGNED_SHORT_1_5_5_5_REV</code>,
234 <code class="constant">GL_UNSIGNED_INT_8_8_8_8</code>,
235 <code class="constant">GL_UNSIGNED_INT_8_8_8_8_REV</code>,
236 <code class="constant">GL_UNSIGNED_INT_10_10_10_2</code>, or
237 <code class="constant">GL_UNSIGNED_INT_2_10_10_10_REV</code>
238 and <em class="parameter"><code>format</code></em> is neither <code class="constant">GL_RGBA</code> nor <code class="constant">GL_BGRA</code>.
239 </p><p>
240 <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
241 <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and the buffer object's data store is currently mapped.
242 </p><p>
243 <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
244 <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and the data would be unpacked from the buffer
245 object such that the memory reads required would exceed the data store size.
246 </p><p>
247 <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
248 <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and <em class="parameter"><code>data</code></em> is not evenly divisible
249 into the number of bytes needed to store in memory a datum indicated by <em class="parameter"><code>type</code></em>.
250 </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
251 <a href="glGetTexImage.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexImage</span></span></a>
252 </p><p>
253 <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>
254 </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
255 <a href="glActiveTexture.xml"><span class="citerefentry"><span class="refentrytitle">glActiveTexture</span></span></a>,
256 <a href="glCopyTexImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glCopyTexImage1D</span></span></a>,
257 <a href="glCopyTexImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glCopyTexImage2D</span></span></a>,
258 <a href="glCopyTexSubImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glCopyTexSubImage1D</span></span></a>,
259 <a href="glCopyTexSubImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glCopyTexSubImage2D</span></span></a>,
260 <a href="glCopyTexSubImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glCopyTexSubImage3D</span></span></a>,
261 <a href="glPixelStore.xml"><span class="citerefentry"><span class="refentrytitle">glPixelStore</span></span></a>,
262 <a href="glTexImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage1D</span></span></a>,
263 <a href="glTexImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage2D</span></span></a>,
264 <a href="glTexImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage3D</span></span></a>,
265 <a href="glTexSubImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexSubImage1D</span></span></a>,
266 <a href="glTexSubImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glTexSubImage2D</span></span></a>,
267 <a href="glTexParameter.xml"><span class="citerefentry"><span class="refentrytitle">glTexParameter</span></span></a>
268 </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
269 Copyright <span class="trademark"></span>© 1991-2006
270 Silicon Graphics, Inc. This document is licensed under the SGI
271 Free Software B License. For details, see
272 <a href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
273 </p></div></div></body></html>
Unnamed repository; edit this file 'description' to name the repository.