HCoop / clinton / guile-figl.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
rename upstream-man-pages to upstream-doc
[clinton/guile-figl.git] / upstream-doc / man2 / glTexImage3D.xml
CommitLineData
7faf1d71
AW		 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="glTexImage3D">
5 <refmeta>
6 <refmetainfo>
7 <copyright>
8 <year>1991-2006</year>
9 <holder>Silicon Graphics, Inc.</holder>
10 </copyright>
11 </refmetainfo>
12 <refentrytitle>glTexImage3D</refentrytitle>
13 <manvolnum>3G</manvolnum>
14 </refmeta>
15 <refnamediv>
16 <refname>glTexImage3D</refname>
17 <refpurpose>specify a three-dimensional texture image</refpurpose>
18 </refnamediv>
19 <refsynopsisdiv><title>C Specification</title>
20 <funcsynopsis>
21 <funcprototype>
22 <funcdef>void <function>glTexImage3D</function></funcdef>
23 <paramdef>GLenum <parameter>target</parameter></paramdef>
24 <paramdef>GLint <parameter>level</parameter></paramdef>
25 <paramdef>GLint <parameter>internalFormat</parameter></paramdef>
26 <paramdef>GLsizei <parameter>width</parameter></paramdef>
27 <paramdef>GLsizei <parameter>height</parameter></paramdef>
28 <paramdef>GLsizei <parameter>depth</parameter></paramdef>
29 <paramdef>GLint <parameter>border</parameter></paramdef>
30 <paramdef>GLenum <parameter>format</parameter></paramdef>
31 <paramdef>GLenum <parameter>type</parameter></paramdef>
32 <paramdef>const GLvoid * <parameter>data</parameter></paramdef>
33 </funcprototype>
34 </funcsynopsis>
35 </refsynopsisdiv>
36 <!-- eqn: ignoring delim $$ -->
37 <para>
38 </para>
39 <refsect1 id="parameters"><title>Parameters</title>
40 <variablelist>
41 <varlistentry>
42 <term><parameter>target</parameter></term>
43 <listitem>
44 <para>
45 Specifies the target texture.
46 Must be <constant>GL_TEXTURE_3D</constant> or <constant>GL_PROXY_TEXTURE_3D</constant>.
47 </para>
48 </listitem>
49 </varlistentry>
50 <varlistentry>
51 <term><parameter>level</parameter></term>
52 <listitem>
53 <para>
54 Specifies the level-of-detail number.
55 Level 0 is the base image level.
56 Level
57 <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
58 is the
59 <inlineequation><mml:math>
60 <!-- eqn: n sup th:-->
61 <mml:msup><mml:mi mathvariant="italic">n</mml:mi>
62 <mml:mi mathvariant="italic">th</mml:mi>
63 </mml:msup>
64 </mml:math></inlineequation>
65 mipmap reduction image.
66 </para>
67 </listitem>
68 </varlistentry>
69 <varlistentry>
70 <term><parameter>internalFormat</parameter></term>
71 <listitem>
72 <para>
73 Specifies the number of color components in the texture.
74 Must be 1, 2, 3, or 4, or one of the following symbolic constants:
75 <constant>GL_ALPHA</constant>,
76 <constant>GL_ALPHA4</constant>,
77 <constant>GL_ALPHA8</constant>,
78 <constant>GL_ALPHA12</constant>,
79 <constant>GL_ALPHA16</constant>,
80 <constant>GL_COMPRESSED_ALPHA</constant>,
81 <constant>GL_COMPRESSED_LUMINANCE</constant>,
82 <constant>GL_COMPRESSED_LUMINANCE_ALPHA</constant>,
83 <constant>GL_COMPRESSED_INTENSITY</constant>,
84 <constant>GL_COMPRESSED_RGB</constant>,
85 <constant>GL_COMPRESSED_RGBA</constant>,
86 <constant>GL_LUMINANCE</constant>,
87 <constant>GL_LUMINANCE4</constant>,
88 <constant>GL_LUMINANCE8</constant>,
89 <constant>GL_LUMINANCE12</constant>,
90 <constant>GL_LUMINANCE16</constant>,
91 <constant>GL_LUMINANCE_ALPHA</constant>,
92 <constant>GL_LUMINANCE4_ALPHA4</constant>,
93 <constant>GL_LUMINANCE6_ALPHA2</constant>,
94 <constant>GL_LUMINANCE8_ALPHA8</constant>,
95 <constant>GL_LUMINANCE12_ALPHA4</constant>,
96 <constant>GL_LUMINANCE12_ALPHA12</constant>,
97 <constant>GL_LUMINANCE16_ALPHA16</constant>,
98 <constant>GL_INTENSITY</constant>,
99 <constant>GL_INTENSITY4</constant>,
100 <constant>GL_INTENSITY8</constant>,
101 <constant>GL_INTENSITY12</constant>,
102 <constant>GL_INTENSITY16</constant>,
103 <constant>GL_R3_G3_B2</constant>,
104 <constant>GL_RGB</constant>,
105 <constant>GL_RGB4</constant>,
106 <constant>GL_RGB5</constant>,
107 <constant>GL_RGB8</constant>,
108 <constant>GL_RGB10</constant>,
109 <constant>GL_RGB12</constant>,
110 <constant>GL_RGB16</constant>,
111 <constant>GL_RGBA</constant>,
112 <constant>GL_RGBA2</constant>,
113 <constant>GL_RGBA4</constant>,
114 <constant>GL_RGB5_A1</constant>,
115 <constant>GL_RGBA8</constant>,
116 <constant>GL_RGB10_A2</constant>,
117 <constant>GL_RGBA12</constant>,
118 <constant>GL_RGBA16</constant>,
119 <constant>GL_SLUMINANCE</constant>,
120 <constant>GL_SLUMINANCE8</constant>,
121 <constant>GL_SLUMINANCE_ALPHA</constant>,
122 <constant>GL_SLUMINANCE8_ALPHA8</constant>,
123 <constant>GL_SRGB</constant>,
124 <constant>GL_SRGB8</constant>,
125 <constant>GL_SRGB_ALPHA</constant>, or
126 <constant>GL_SRGB8_ALPHA8</constant>.
127 </para>
128 </listitem>
129 </varlistentry>
130 <varlistentry>
131 <term><parameter>width</parameter></term>
132 <listitem>
133 <para>
134 Specifies the width of the texture image including the border if any. If the GL version does not support non-power-of-two sizes, this value must be
135 <inlineequation><mml:math>
136 <!-- eqn: 2 sup n + 2 ( border ):-->
137 <mml:mrow>
138 <mml:msup><mml:mn>2</mml:mn>
139 <mml:mi mathvariant="italic">n</mml:mi>
140 </mml:msup>
141 <mml:mo>+</mml:mo>
142 <mml:mrow>
143 <mml:mn>2</mml:mn>
144 <mml:mo>&af;</mml:mo>
145 <mml:mfenced open="(" close=")">
146 <mml:mi mathvariant="italic">border</mml:mi>
147 </mml:mfenced>
148 </mml:mrow>
149 </mml:mrow>
150 </mml:math></inlineequation>
151 for some integer
152 <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>.
153 All
154 implementations support 3D texture images that are at least 16 texels
155 wide.
156 </para>
157 </listitem>
158 </varlistentry>
159 <varlistentry>
160 <term><parameter>height</parameter></term>
161 <listitem>
162 <para>
163 Specifies the height of the texture image including the border if any. If the GL version does not support non-power-of-two sizes, this value must be
164 <inlineequation><mml:math>
165 <!-- eqn: 2 sup m + 2 ( border ):-->
166 <mml:mrow>
167 <mml:msup><mml:mn>2</mml:mn>
168 <mml:mi mathvariant="italic">m</mml:mi>
169 </mml:msup>
170 <mml:mo>+</mml:mo>
171 <mml:mrow>
172 <mml:mn>2</mml:mn>
173 <mml:mo>&af;</mml:mo>
174 <mml:mfenced open="(" close=")">
175 <mml:mi mathvariant="italic">border</mml:mi>
176 </mml:mfenced>
177 </mml:mrow>
178 </mml:mrow>
179 </mml:math></inlineequation>
180 for some integer
181 <inlineequation><mml:math><mml:mi mathvariant="italic">m</mml:mi></mml:math></inlineequation>.
182 All
183 implementations support 3D texture images that are at least 16 texels
184 high.
185 </para>
186 </listitem>
187 </varlistentry>
188 <varlistentry>
189 <term><parameter>depth</parameter></term>
190 <listitem>
191 <para>
192 Specifies the depth of the texture image including the border if any. If the GL version does not support non-power-of-two sizes, this value must be
193 <inlineequation><mml:math>
194 <!-- eqn: 2 sup k + 2 ( border ):-->
195 <mml:mrow>
196 <mml:msup><mml:mn>2</mml:mn>
197 <mml:mi mathvariant="italic">k</mml:mi>
198 </mml:msup>
199 <mml:mo>+</mml:mo>
200 <mml:mrow>
201 <mml:mn>2</mml:mn>
202 <mml:mo>&af;</mml:mo>
203 <mml:mfenced open="(" close=")">
204 <mml:mi mathvariant="italic">border</mml:mi>
205 </mml:mfenced>
206 </mml:mrow>
207 </mml:mrow>
208 </mml:math></inlineequation>
209 for some integer
210 <inlineequation><mml:math><mml:mi mathvariant="italic">k</mml:mi></mml:math></inlineequation>.
211 All
212 implementations support 3D texture images that are at least 16 texels
213 deep.
214 </para>
215 </listitem>
216 </varlistentry>
217 <varlistentry>
218 <term><parameter>border</parameter></term>
219 <listitem>
220 <para>
221 Specifies the width of the border.
222 Must be either 0 or 1.
223 </para>
224 </listitem>
225 </varlistentry>
226 <varlistentry>
227 <term><parameter>format</parameter></term>
228 <listitem>
229 <para>
230 Specifies the format of the pixel data.
231 The following symbolic values are accepted:
232 <constant>GL_COLOR_INDEX</constant>,
233 <constant>GL_RED</constant>,
234 <constant>GL_GREEN</constant>,
235 <constant>GL_BLUE</constant>,
236 <constant>GL_ALPHA</constant>,
237 <constant>GL_RGB</constant>,
238 <constant>GL_BGR</constant>,
239 <constant>GL_RGBA</constant>,
240 <constant>GL_BGRA</constant>,
241 <constant>GL_LUMINANCE</constant>, and
242 <constant>GL_LUMINANCE_ALPHA</constant>.
243 </para>
244 </listitem>
245 </varlistentry>
246 <varlistentry>
247 <term><parameter>type</parameter></term>
248 <listitem>
249 <para>
250 Specifies the data type of the pixel data.
251 The following symbolic values are accepted:
252 <constant>GL_UNSIGNED_BYTE</constant>,
253 <constant>GL_BYTE</constant>,
254 <constant>GL_BITMAP</constant>,
255 <constant>GL_UNSIGNED_SHORT</constant>,
256 <constant>GL_SHORT</constant>,
257 <constant>GL_UNSIGNED_INT</constant>,
258 <constant>GL_INT</constant>,
259 <constant>GL_FLOAT</constant>,
260 <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
261 <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
262 <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
263 <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
264 <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
265 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
266 <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
267 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
268 <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
269 <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
270 <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
271 <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>.
272 </para>
273 </listitem>
274 </varlistentry>
275 <varlistentry>
276 <term><parameter>data</parameter></term>
277 <listitem>
278 <para>
279 Specifies a pointer to the image data in memory.
280 </para>
281 </listitem>
282 </varlistentry>
283 </variablelist>
284 </refsect1>
285 <refsect1 id="description"><title>Description</title>
286 <para>
287 Texturing maps a portion of a specified texture image
288 onto each graphical primitive for which texturing is enabled.
289 To enable and disable three-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
290 and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_3D</constant>.
291 </para>
292 <para>
293 To define texture images, call <function>glTexImage3D</function>.
294 The arguments describe the parameters of the texture image,
295 such as height,
296 width, depth,
297 width of the border,
298 level-of-detail number
299 (see <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>),
300 and number of color components provided.
301 The last three arguments describe how the image is represented in memory;
302 they are identical to the pixel formats used for <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>.
303 </para>
304 <para>
305 If <parameter>target</parameter> is <constant>GL_PROXY_TEXTURE_3D</constant>, no data is read from <parameter>data</parameter>, but
306 all of the texture image state is recalculated, checked for
307 consistency, and checked
308 against the implementation's capabilities. If the implementation cannot
309 handle a texture of the requested texture size, it sets
310 all of the image state to 0,
311 but does not generate an error (see <citerefentry><refentrytitle>glGetError</refentrytitle></citerefentry>). To query for an
312 entire mipmap array, use an image array level greater than or equal to
313 1.
314 </para>
315 <para>
316 If <parameter>target</parameter> is <constant>GL_TEXTURE_3D</constant>,
317 data is read from <parameter>data</parameter> as a sequence of signed or unsigned bytes,
318 shorts,
319 or longs,
320 or single-precision floating-point values,
321 depending on <parameter>type</parameter>.
322 These values are grouped into sets of one,
323 two,
324 three,
325 or four values,
326 depending on <parameter>format</parameter>,
327 to form elements.
328 If <parameter>type</parameter> is <constant>GL_BITMAP</constant>,
329 the data is considered as a string of unsigned bytes (and
330 <parameter>format</parameter> must be <constant>GL_COLOR_INDEX</constant>).
331 Each data byte is treated as eight 1-bit elements,
332 with bit ordering determined by <constant>GL_UNPACK_LSB_FIRST</constant>
333 (see <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>).
334 </para>
335 <para>
336 If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
337 (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
338 specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
339 </para>
340 <para>
341 The first element corresponds to the lower left corner of the texture
342 image.
343 Subsequent elements progress left-to-right through the remaining texels
344 in the lowest row of the texture image, and then in successively higher
345 rows of the texture image.
346 The final element corresponds to the upper right corner of the texture
347 image.
348 </para>
349 <para>
350 <parameter>format</parameter> determines the composition of each element in <parameter>data</parameter>.
351 It can assume one of these symbolic values:
352 </para>
353 <variablelist>
354 <varlistentry>
355 <term><constant>GL_COLOR_INDEX</constant></term>
356 <listitem>
357 <para>
358 Each element is a single value,
359 a color index.
360 The GL converts it to fixed point
361 (with an unspecified number of zero bits to the right of the binary point),
362 shifted left or right depending on the value and sign of <constant>GL_INDEX_SHIFT</constant>,
363 and added to <constant>GL_INDEX_OFFSET</constant>
364 (see <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>).
365 The resulting index is converted to a set of color components
366 using the
367 <constant>GL_PIXEL_MAP_I_TO_R</constant>,
368 <constant>GL_PIXEL_MAP_I_TO_G</constant>,
369 <constant>GL_PIXEL_MAP_I_TO_B</constant>, and
370 <constant>GL_PIXEL_MAP_I_TO_A</constant> tables,
371 and clamped to the range [0,1].
372 </para>
373 </listitem>
374 </varlistentry>
375 <varlistentry>
376 <term><constant>GL_RED</constant></term>
377 <listitem>
378 <para>
379 Each element is a single red component.
380 The GL converts it to floating point and assembles it into an RGBA element
381 by attaching 0 for green and blue, and 1 for alpha.
382 Each component is then multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
383 added to the signed bias <constant>GL_c_BIAS</constant>,
384 and clamped to the range [0,1]
385 (see <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>).
386 </para>
387 </listitem>
388 </varlistentry>
389 <varlistentry>
390 <term><constant>GL_GREEN</constant></term>
391 <listitem>
392 <para>
393 Each element is a single green component.
394 The GL converts it to floating point and assembles it into an RGBA element
395 by attaching 0 for red and blue, and 1 for alpha.
396 Each component is then multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
397 added to the signed bias <constant>GL_c_BIAS</constant>,
398 and clamped to the range [0,1]
399 (see <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>).
400 </para>
401 </listitem>
402 </varlistentry>
403 <varlistentry>
404 <term><constant>GL_BLUE</constant></term>
405 <listitem>
406 <para>
407 Each element is a single blue component.
408 The GL converts it to floating point and assembles it into an RGBA element
409 by attaching 0 for red and green, and 1 for alpha.
410 Each component is then multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
411 added to the signed bias <constant>GL_c_BIAS</constant>,
412 and clamped to the range [0,1]
413 (see <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>).
414 </para>
415 </listitem>
416 </varlistentry>
417 <varlistentry>
418 <term><constant>GL_ALPHA</constant></term>
419 <listitem>
420 <para>
421 Each element is a single alpha component.
422 The GL converts it to floating point and assembles it into an RGBA element
423 by attaching 0 for red, green, and blue.
424 Each component is then multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
425 added to the signed bias <constant>GL_c_BIAS</constant>,
426 and clamped to the range [0,1]
427 (see <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>).
428 </para>
429 </listitem>
430 </varlistentry>
431 <varlistentry>
432 <term><constant>GL_INTENSITY</constant></term>
433 <listitem>
434 <para>
435 Each element is a single intensity value.
436 The GL converts it to floating point,
437 then assembles it into an RGBA element by replicating the intensity value
438 three times for red, green, blue, and alpha.
439 Each component is then multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
440 added to the signed bias <constant>GL_c_BIAS</constant>,
441 and clamped to the range [0,1]
442 (see <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>).
443 </para>
444 </listitem>
445 </varlistentry>
446 <varlistentry>
447 <term><constant>GL_RGB</constant></term>
448 <listitem>
449 </listitem>
450 </varlistentry>
451 <varlistentry>
452 <term><constant>GL_BGR</constant></term>
453 <listitem>
454 <para>
455 Each element is an RGB triple.
456 The GL converts it to floating point and assembles it into an RGBA element
457 by attaching 1 for alpha.
458 Each component is then multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
459 added to the signed bias <constant>GL_c_BIAS</constant>,
460 and clamped to the range [0,1]
461 (see <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>).
462 </para>
463 </listitem>
464 </varlistentry>
465 <varlistentry>
466 <term><constant>GL_RGBA</constant></term>
467 <listitem>
468 </listitem>
469 </varlistentry>
470 <varlistentry>
471 <term><constant>GL_BGRA</constant></term>
472 <listitem>
473 <para>
474 Each element contains all four components.
475 Each component is multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
476 added to the signed bias <constant>GL_c_BIAS</constant>,
477 and clamped to the range [0,1]
478 (see <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>).
479 </para>
480 </listitem>
481 </varlistentry>
482 <varlistentry>
483 <term><constant>GL_LUMINANCE</constant></term>
484 <listitem>
485 <para>
486 Each element is a single luminance value.
487 The GL converts it to floating point,
488 then assembles it into an RGBA element by replicating the luminance value
489 three times for red, green, and blue and attaching 1 for alpha.
490 Each component is then multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
491 added to the signed bias <constant>GL_c_BIAS</constant>,
492 and clamped to the range [0,1]
493 (see <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>).
494 </para>
495 </listitem>
496 </varlistentry>
497 <varlistentry>
498 <term><constant>GL_LUMINANCE_ALPHA</constant></term>
499 <listitem>
500 <para>
501 Each element is a luminance/alpha pair.
502 The GL converts it to floating point,
503 then assembles it into an RGBA element by replicating the luminance value
504 three times for red, green, and blue.
505 Each component is then multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
506 added to the signed bias <constant>GL_c_BIAS</constant>,
507 and clamped to the range [0,1] (see <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>).
508 </para>
509 </listitem>
510 </varlistentry>
511 </variablelist>
512 <para>
513 Refer to the <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry> reference page for a description of
514 the acceptable values for the <parameter>type</parameter> parameter.
515 </para>
516 <para>
517 If an application wants to store the texture at a certain
518 resolution or in a certain format, it can request the resolution
519 and format with <parameter>internalFormat</parameter>. The GL will choose an internal
520 representation that closely approximates that requested by <parameter>internalFormat</parameter>, but
521 it may not match exactly.
522 (The representations specified by <constant>GL_LUMINANCE</constant>,
523 <constant>GL_LUMINANCE_ALPHA</constant>, <constant>GL_RGB</constant>,
524 and <constant>GL_RGBA</constant> must match exactly. The numeric values 1, 2, 3, and 4
525 may also be used to specify the above representations.)
526 </para>
527 <para>
528 If the <parameter>internalFormat</parameter> parameter is one of the generic compressed formats,
529 <constant>GL_COMPRESSED_ALPHA</constant>,
530 <constant>GL_COMPRESSED_INTENSITY</constant>,
531 <constant>GL_COMPRESSED_LUMINANCE</constant>,
532 <constant>GL_COMPRESSED_LUMINANCE_ALPHA</constant>,
533 <constant>GL_COMPRESSED_RGB</constant>, or
534 <constant>GL_COMPRESSED_RGBA</constant>, the GL will replace the internal format with the symbolic constant for a specific internal format and compress the texture before storage. If no corresponding internal format is available, or the GL can not compress that image for any reason, the internal format is instead replaced with a corresponding base internal format.
535 </para>
536 <para>
537 If the <parameter>internalFormat</parameter> parameter is
538 <constant>GL_SRGB</constant>,
539 <constant>GL_SRGB8</constant>,
540 <constant>GL_SRGB_ALPHA</constant>,
541 <constant>GL_SRGB8_ALPHA8</constant>,
542 <constant>GL_SLUMINANCE</constant>,
543 <constant>GL_SLUMINANCE8</constant>,
544 <constant>GL_SLUMINANCE_ALPHA</constant>, or
545 <constant>GL_SLUMINANCE8_ALPHA8</constant>, the texture is treated as if the red, green, blue, or luminance components are encoded in the sRGB color space. Any alpha component is left unchanged. The conversion from the sRGB encoded component
546 <inlineequation><mml:math>
547 <mml:msub><mml:mi mathvariant="italic">c</mml:mi>
548 <mml:mi mathvariant="italic">s</mml:mi>
549 </mml:msub>
550 </mml:math></inlineequation>
551 to a linear component
552 <inlineequation><mml:math>
553 <mml:msub><mml:mi mathvariant="italic">c</mml:mi>
554 <mml:mi mathvariant="italic">l</mml:mi>
555 </mml:msub>
556 </mml:math></inlineequation>
557 is:
558 </para>
559 <para>
560 <inlineequation><mml:math>
561 <mml:mrow>
562 <mml:msub>
563 <mml:mi mathvariant="italic">c</mml:mi>
564 <mml:mi mathvariant="italic">l</mml:mi>
565 </mml:msub>
566 <mml:mo>=</mml:mo>
567 <mml:mrow>
568 <mml:mo>{</mml:mo>
569
570 <mml:mtable columnalign="left">
571 <mml:mtr>
572 <mml:mtd columnalign="left">
573 <mml:mfrac>
574 <mml:msub>
575 <mml:mi mathvariant="italic">c</mml:mi>
576 <mml:mi mathvariant="italic">s</mml:mi>
577 </mml:msub>
578 <mml:mn>12.92</mml:mn>
579 </mml:mfrac>
580 </mml:mtd>
581 <mml:mtd columnalign="left">
582 <mml:mrow>
583 <mml:mspace width="1ex"/>
584 <mml:mo>if</mml:mo>
585 <mml:mspace width="1ex"/>
586 </mml:mrow>
587 <mml:msub>
588 <mml:mi mathvariant="italic">c</mml:mi>
589 <mml:mi mathvariant="italic">s</mml:mi>
590 </mml:msub>
591 <mml:mo>&le;</mml:mo>
592 <mml:mn>0.04045</mml:mn>
593 </mml:mtd>
594 </mml:mtr>
595 <mml:mtr>
596 <mml:mtd columnalign="left">
597 <mml:msup>
598 <mml:mrow>
599 <mml:mo>(</mml:mo>
600 <mml:mfrac>
601 <mml:mrow>
602 <mml:msub>
603 <mml:mi>c</mml:mi>
604 <mml:mi>s</mml:mi>
605 </mml:msub>
606 <mml:mo>+</mml:mo>
607 <mml:mn>0.055</mml:mn>
608 </mml:mrow>
609 <mml:mn>1.055</mml:mn>
610 </mml:mfrac>
611 <mml:mo>)</mml:mo>
612 </mml:mrow>
613 <mml:mn>2.4</mml:mn>
614 </mml:msup>
615 </mml:mtd>
616 <mml:mtd columnalign="left">
617 <mml:mrow>
618 <mml:mspace width="1ex"/>
619 <mml:mo>if</mml:mo>
620 <mml:mspace width="1ex"/>
621 </mml:mrow>
622 <mml:msub>
623 <mml:mi mathvariant="italic">c</mml:mi>
624 <mml:mi mathvariant="italic">s</mml:mi>
625 </mml:msub>
626 <mml:mo>&gt;</mml:mo>
627 <mml:mn>0.04045</mml:mn>
628 </mml:mtd>
629 </mml:mtr>
630 </mml:mtable>
631 </mml:mrow>
632 </mml:mrow>
633 </mml:math>
634 </inlineequation>
635 </para>
636 <para>
637 Assume
638 <inlineequation><mml:math>
639 <mml:msub><mml:mi mathvariant="italic">c</mml:mi>
640 <mml:mi mathvariant="italic">s</mml:mi>
641 </mml:msub>
642 </mml:math></inlineequation>
643 is the sRGB component in the range [0,1].
644 </para>
645 <para>
646 Use the <constant>GL_PROXY_TEXTURE_3D</constant> target to try out a resolution and
647 format. The implementation will
648 update and recompute its best match for the requested storage resolution
649 and format. To then query this state, call <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>.
650 If the texture cannot be accommodated, texture state is set to 0.
651 </para>
652 <para>
653 A one-component texture image uses only the red component of the RGBA
654 color extracted from <parameter>data</parameter>.
655 A two-component image uses the R and A values.
656 A three-component image uses the R, G, and B values.
657 A four-component image uses all of the RGBA components.
658 </para>
659 </refsect1>
660 <refsect1 id="notes"><title>Notes</title>
661 <para>
662 Texturing has no effect in color index mode.
663 </para>
664 <para>
665 The texture image can be represented by the same data formats
666 as the pixels in a <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry> command,
667 except that <constant>GL_STENCIL_INDEX</constant> and <constant>GL_DEPTH_COMPONENT</constant>
668 cannot be used.
669 <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry> modes affect texture images
670 in exactly the way they affect <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>.
671 </para>
672 <para>
673 <function>glTexImage3D</function> is available only if the GL version is 1.2 or greater.
674 </para>
675 <para>
676 Internal formats other than 1, 2, 3, or 4 may be used only if the GL
677 version is 1.1 or greater.
678 </para>
679 <para>
680 <parameter>data</parameter> may be a null pointer.
681 In this case texture memory is
682 allocated to accommodate a texture of width <parameter>width</parameter>, height <parameter>height</parameter>,
683 and depth <parameter>depth</parameter>.
684 You can then download subtextures to initialize this
685 texture memory.
686 The image is undefined if the user tries to apply
687 an uninitialized portion of the texture image to a primitive.
688 </para>
689 <para>
690 Formats <constant>GL_BGR</constant>, and <constant>GL_BGRA</constant> and types
691 <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
692 <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
693 <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
694 <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
695 <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
696 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
697 <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
698 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
699 <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
700 <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
701 <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
702 <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant> are available only if the GL version
703 is 1.2 or greater.
704 </para>
705 <para>
706 For OpenGL versions 1.3 and greater, or when the <code>ARB_multitexture</code> extension is supported, <function>glTexImage3D</function>
707 specifies the three-dimensional texture for the current texture unit,
708 specified with <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>.
709 </para>
710 <para>
711 If the <code>ARB_imaging</code> extension is supported, RGBA elements may
712 also be processed by the imaging pipeline. The following stages may be
713 applied to an RGBA color before color component clamping to the range
714 <inlineequation><mml:math>
715 <!-- eqn: [0,1]:-->
716 <mml:mfenced open="[" close="]">
717 <mml:mn>0</mml:mn>
718 <mml:mn>1</mml:mn>
719 </mml:mfenced>
720 </mml:math></inlineequation>:
721 </para>
722 <variablelist>
723 <varlistentry>
724 <term>1. Color component replacement by the color table specified for</term>
725 <listitem>
726 <para>
727 <constant>GL_COLOR_TABLE</constant>, if enabled. See <citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>.
728 </para>
729 </listitem>
730 </varlistentry>
731 <varlistentry>
732 <term>2. Color component replacement by the color table specified for</term>
733 <listitem>
734 <para>
735 <constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>, if enabled. See <citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>.
736 </para>
737 </listitem>
738 </varlistentry>
739 <varlistentry>
740 <term>3. Transformation by the color matrix. See <citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>.</term>
741 <listitem>
742 </listitem>
743 </varlistentry>
744 <varlistentry>
745 <term>4. RGBA components may be multiplied by <constant>GL_POST_COLOR_MATRIX_c_SCALE</constant>,</term>
746 <listitem>
747 <para>
748 and added to <constant>GL_POST_COLOR_MATRIX_c_BIAS</constant>, if enabled. See
749 <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>.
750 </para>
751 </listitem>
752 </varlistentry>
753 <varlistentry>
754 <term>5. Color component replacement by the color table specified for</term>
755 <listitem>
756 <para>
757 <constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>, if enabled. See
758 <citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>.
759 </para>
760 </listitem>
761 </varlistentry>
762 </variablelist>
763 <para>
764 Non-power-of-two textures are supported if the GL version is 2.0 or greater, or if the implementation exports the <constant>GL_ARB_texture_non_power_of_two</constant> extension.
765 </para>
766 <para>
767 The
768 <constant>GL_SRGB</constant>,
769 <constant>GL_SRGB8</constant>,
770 <constant>GL_SRGB_ALPHA</constant>,
771 <constant>GL_SRGB8_ALPHA8</constant>,
772 <constant>GL_SLUMINANCE</constant>,
773 <constant>GL_SLUMINANCE8</constant>,
774 <constant>GL_SLUMINANCE_ALPHA</constant>, and
775 <constant>GL_SLUMINANCE8_ALPHA8</constant>
776 internal formats are only available if the GL version is 2.1 or greater.
777 </para>
778 </refsect1>
779 <refsect1 id="errors"><title>Errors</title>
780 <para>
781 <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_TEXTURE_3D</constant>
782 or <constant>GL_PROXY_TEXTURE_3D</constant>.
783 </para>
784 <para>
785 <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not an accepted
786 format constant. Format constants other than <constant>GL_STENCIL_INDEX</constant> and <constant>GL_DEPTH_COMPONENT</constant>
787 are accepted.
788 </para>
789 <para>
790 <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not a type constant.
791 </para>
792 <para>
793 <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is <constant>GL_BITMAP</constant> and
794 <parameter>format</parameter> is not <constant>GL_COLOR_INDEX</constant>.
795 </para>
796 <para>
797 <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
798 </para>
799 <para>
800 <constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater than
801 <inlineequation><mml:math>
802 <!-- eqn: log sub 2 (max):-->
803 <mml:mrow>
804 <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
805 <mml:mn>2</mml:mn>
806 </mml:msub>
807 <mml:mo>&af;</mml:mo>
808 <mml:mfenced open="(" close=")">
809 <mml:mi mathvariant="italic">max</mml:mi>
810 </mml:mfenced>
811 </mml:mrow>
812 </mml:math></inlineequation>,
813 where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
814 </para>
815 <para>
816 <constant>GL_INVALID_VALUE</constant> is generated if <parameter>internalFormat</parameter> is not 1, 2, 3, 4, or one of the
817 accepted resolution and format symbolic constants.
818 </para>
819 <para>
820 <constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter>, <parameter>height</parameter>, or <parameter>depth</parameter> is less than 0 or greater than 2 + <constant>GL_MAX_TEXTURE_SIZE</constant>.
821 </para>
822 <para>
823 <constant>GL_INVALID_VALUE</constant> is generated if non-power-of-two textures are not supported and the <parameter>width</parameter>, <parameter>height</parameter>, or <parameter>depth</parameter> cannot be represented as
824 <inlineequation><mml:math>
825 <!-- eqn: 2 sup k + 2( border ):-->
826 <mml:mrow>
827 <mml:msup><mml:mn>2</mml:mn>
828 <mml:mi mathvariant="italic">k</mml:mi>
829 </mml:msup>
830 <mml:mo>+</mml:mo>
831 <mml:mrow>
832 <mml:mn>2</mml:mn>
833 <mml:mo>&af;</mml:mo>
834 <mml:mfenced open="(" close=")">
835 <mml:mi mathvariant="italic">border</mml:mi>
836 </mml:mfenced>
837 </mml:mrow>
838 </mml:mrow>
839 </mml:math></inlineequation>
840 for some
841 integer value of <emphasis>k</emphasis>.
842 </para>
843 <para>
844 <constant>GL_INVALID_VALUE</constant> is generated if <parameter>border</parameter> is not 0 or 1.
845 </para>
846 <para>
847 <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
848 <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
849 <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
850 <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
851 <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
852 and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
853 </para>
854 <para>
855 <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
856 <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
857 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
858 <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
859 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
860 <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
861 <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
862 <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
863 <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
864 and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
865 </para>
866 <para>
867 <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> or <parameter>internalFormat</parameter> is
868 <constant>GL_DEPTH_COMPONENT</constant>, <constant>GL_DEPTH_COMPONENT16</constant>,
869 <constant>GL_DEPTH_COMPONENT24</constant>, or <constant>GL_DEPTH_COMPONENT32</constant>.
870 </para>
871 <para>
872 <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
873 <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
874 </para>
875 <para>
876 <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
877 <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
878 object such that the memory reads required would exceed the data store size.
879 </para>
880 <para>
881 <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
882 <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
883 into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
884 </para>
885 <para>
886 <constant>GL_INVALID_OPERATION</constant> is generated if <function>glTexImage3D</function>
887 is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
888 and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
889 </para>
890 </refsect1>
891 <refsect1 id="associatedgets"><title>Associated Gets</title>
892 <para>
893 <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
894 </para>
895 <para>
896 <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_3D</constant>
897 </para>
898 <para>
899 <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
900 </para>
901 </refsect1>
902 <refsect1 id="seealso"><title>See Also</title>
903 <para>
904 <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
905 <citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
906 <citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
907 <citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
908 <citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
909 <citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
910 <citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
911 <citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
912 <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
913 <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
914 <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
915 <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
916 <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
917 <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
918 <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
919 <citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>,
920 <citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
921 <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
922 <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
923 <citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
924 <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
925 <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
926 <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
927 <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
928 <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
929 <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
930 <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
931 </para>
932 </refsect1>
933 <refsect1 id="Copyright"><title>Copyright</title>
934 <para>
935 Copyright <trademark class="copyright"></trademark> 1991-2006
936 Silicon Graphics, Inc. This document is licensed under the SGI
937 Free Software B License. For details, see
938 <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
939 </para>
940 </refsect1>
941</refentry>
Unnamed repository; edit this file 'description' to name the repository.