glTexImage3D(3gl)

1GLTEXIMAGE3D(3G)                                              GLTEXIMAGE3D(3G)
2
3
4

NAME

6       glTexImage3D - specify a three-dimensional texture image
7
8

C SPECIFICATION

10       void glTexImage3D( GLenum target,
11                          GLint level,
12                          GLint internalFormat,
13                          GLsizei width,
14                          GLsizei height,
15                          GLsizei depth,
16                          GLint border,
17                          GLenum format,
18                          GLenum type,
19                          const GLvoid *pixels )
20
21

PARAMETERS

23       target          Specifies the target texture.  Must be GL_TEXTURE_3D or
24                       GL_PROXY_TEXTURE_3D.
25
26       level           Specifies the level-of-detail number.  Level 0  is  the
27                       base  image level.  Level n is the nth mipmap reduction
28                       image.
29
30       internalFormat  Specifies the number of color components  in  the  tex‐
31                       ture.   Must  be 1, 2, 3, or 4, or one of the following
32                       symbolic  constants:  GL_ALPHA,  GL_ALPHA4,  GL_ALPHA8,
33                       GL_ALPHA12,  GL_ALPHA16,  GL_LUMINANCE,  GL_LUMINANCE4,
34                       GL_LUMINANCE8,     GL_LUMINANCE12,      GL_LUMINANCE16,
35                       GL_LUMINANCE_ALPHA,               GL_LUMINANCE4_ALPHA4,
36                       GL_LUMINANCE6_ALPHA2,             GL_LUMINANCE8_ALPHA8,
37                       GL_LUMINANCE12_ALPHA4,          GL_LUMINANCE12_ALPHA12,
38                       GL_LUMINANCE16_ALPHA16,  GL_INTENSITY,   GL_INTENSITY4,
39                       GL_INTENSITY8,      GL_INTENSITY12,     GL_INTENSITY16,
40                       GL_R3_G3_B2,   GL_RGB,   GL_RGB4,   GL_RGB5,   GL_RGB8,
41                       GL_RGB10,   GL_RGB12,   GL_RGB16,   GL_RGBA,  GL_RGBA2,
42                       GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, GL_RGBA12,
43                       or GL_RGBA16.
44
45       width           Specifies  the  width  of  the  texture image.  Must be
46                       2n+2(border) for some integer  n.  All  implementations
47                       support  texture  images  that  are  at least 64 texels
48                       wide.
49
50       height          Specifies the height of the  texture  image.   Must  be
51                       2m+2(border)  for  some  integer m. All implementations
52                       support texture images that  are  at  least  64  texels
53                       high.
54
55       depth           Specifies  the  depth  of  the  texture image.  Must be
56                       2k+2(border) for some integer  k.  All  implementations
57                       support  texture  images  that  are  at least 64 texels
58                       deep.
59
60       border          Specifies the width of the border.  Must be either 0 or
61                       1.
62
63       format          Specifies  the   of the pixel data.  The following sym‐
64                       bolic  values  are  accepted:  GL_COLOR_INDEX,  GL_RED,
65                       GL_GREEN,  GL_BLUE,  GL_ALPHA, GL_RGB, GL_BGR, GL_RGBA,
66                       GL_BGRA, GL_LUMINANCE, and GL_LUMINANCE_ALPHA.
67
68       type            Specifies the data type of the pixel data.  The follow‐
69                       ing  symbolic  values  are  accepted: GL_UNSIGNED_BYTE,
70                       GL_BYTE,   GL_BITMAP,   GL_UNSIGNED_SHORT,    GL_SHORT,
71                       GL_UNSIGNED_INT,            GL_INT,            GL_FLOAT
72                       GL_UNSIGNED_BYTE_3_3_2,     GL_UNSIGNED_BYTE_2_3_3_REV,
73                       GL_UNSIGNED_SHORT_5_6_5,   GL_UNSIGNED_SHORT_5_6_5_REV,
74                       GL_UNSIGNED_SHORT_4_4_4_4,
75                       GL_UNSIGNED_SHORT_4_4_4_4_REV,
76                       GL_UNSIGNED_SHORT_5_5_5_1,
77                       GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8,
78                       GL_UNSIGNED_INT_8_8_8_8_REV,
79                       GL_UNSIGNED_INT_10_10_10_2,                         and
80                       GL_UNSIGNED_INT_2_10_10_10_REV.
81
82       pixels          Specifies a pointer to the image data in memory.
83

DESCRIPTION

85       Texturing maps a portion of a specified texture image onto each graphi‐
86       cal  primitive  for  which texturing is enabled.  To enable and disable
87       three-dimensional texturing, call glEnable and glDisable with  argument
88       GL_TEXTURE_3D.
89
90       To  define  texture  images, call glTexImage3D.  The arguments describe
91       the parameters of the texture image,  such  as  height,  width,  depth,
92       width  of  the border, level-of-detail number (see glTexParameter), and
93       number of color components provided.  The last three arguments describe
94       how the image is represented in memory; they are identical to the pixel
95       formats used for glDrawPixels.
96
97       If target is GL_PROXY_TEXTURE_3D, no data is read from pixels, but  all
98       of  the  texture  image state is recalculated, checked for consistency,
99       and checked against the implementation's capabilities. If the implemen‐
100       tation  cannot  handle a texture of the requested texture size, it sets
101       all of the image state to 0,  but  does  not  generate  an  error  (see
102       glGetError).  To  query  for an entire mipmap array, use an image array
103       level greater than or equal to 1.
104
105       If target is GL_TEXTURE_3D, data is read from pixels as a  sequence  of
106       signed  or unsigned bytes, shorts, or longs, or single-precision float‐
107       ing-point values, depending on type.  These  values  are  grouped  into
108       sets  of  one, two, three, or four values, depending on format, to form
109       elements.  If type is GL_BITMAP, the data is considered as a string  of
110       unsigned  bytes (and format must be GL_COLOR_INDEX).  Each data byte is
111       treated as eight  1-bit  elements,  with  bit  ordering  determined  by
112       GL_UNPACK_LSB_FIRST (see glPixelStore).
113
114       The  first  element corresponds to the lower left corner of the texture
115       image.  Subsequent elements progress left-to-right through the  remain‐
116       ing  texels in the lowest row of the texture image, and then in succes‐
117       sively higher rows of the texture image.  The final element corresponds
118       to the upper right corner of the texture image.
119
120       format  determines  the  composition of each element in pixels.  It can
121       assume one of eleven symbolic values:
122
123       GL_COLOR_INDEX
124                 Each element is a single value, a color index.  The  GL  con‐
125                 verts  it  to fixed point (with an unspecified number of zero
126                 bits to the right of the binary point), shifted left or right
127                 depending  on the value and sign of GL_INDEX_SHIFT, and added
128                 to GL_INDEX_OFFSET (see
129                 glPixelTransfer).  The resulting index is converted to a  set
130                 of    color   components   using   the   GL_PIXEL_MAP_I_TO_R,
131                 GL_PIXEL_MAP_I_TO_G,         GL_PIXEL_MAP_I_TO_B,         and
132                 GL_PIXEL_MAP_I_TO_A tables, and clamped to the range [0,1].
133
134       GL_RED    Each  element  is a single red component.  The GL converts it
135                 to floating point and assembles it into an  RGBA  element  by
136                 attaching 0 for green and blue, and 1 for alpha.  Each compo‐
137                 nent  is  then  multiplied  by  the   signed   scale   factor
138                 GL_c_SCALE,  added  to the signed bias GL_c_BIAS, and clamped
139                 to the range [0,1] (see glPixelTransfer).
140
141       GL_GREEN  Each element is a single green component.  The GL converts it
142                 to  floating  point  and assembles it into an RGBA element by
143                 attaching 0 for red and blue, and 1 for alpha.   Each  compo‐
144                 nent   is   then   multiplied  by  the  signed  scale  factor
145                 GL_c_SCALE, added to the signed bias GL_c_BIAS,  and  clamped
146                 to the range [0,1] (see glPixelTransfer).
147
148       GL_BLUE   Each  element is a single blue component.  The GL converts it
149                 to floating point and assembles it into an  RGBA  element  by
150                 attaching  0 for red and green, and 1 for alpha.  Each compo‐
151                 nent  is  then  multiplied  by  the   signed   scale   factor
152                 GL_c_SCALE,  added  to the signed bias GL_c_BIAS, and clamped
153                 to the range [0,1] (see glPixelTransfer).
154
155       GL_ALPHA  Each element is a single alpha component.  The GL converts it
156                 to  floating  point  and assembles it into an RGBA element by
157                 attaching 0 for red, green, and blue.  Each component is then
158                 multiplied  by  the  signed scale factor GL_c_SCALE, added to
159                 the signed bias GL_c_BIAS, and clamped  to  the  range  [0,1]
160                 (see glPixelTransfer).
161
162       GL_RGB
163
164       GL_BGR    Each  element is an RGB triple.  The GL converts it to float‐
165                 ing point and assembles it into an RGBA element by  attaching
166                 1 for alpha.  Each component is then multiplied by the signed
167                 scale factor GL_c_SCALE, added to the signed bias  GL_c_BIAS,
168                 and clamped to the range [0,1] (see
169                 glPixelTransfer).
170
171       GL_RGBA
172
173       GL_BGRA   Each element contains all four components.  Each component is
174                 multiplied by the signed scale factor  GL_c_SCALE,  added  to
175                 the  signed  bias  GL_c_BIAS,  and clamped to the range [0,1]
176                 (see glPixelTransfer).
177
178       GL_LUMINANCE
179                 Each element is a single luminance value.  The GL converts it
180                 to  floating point, then assembles it into an RGBA element by
181                 replicating the luminance value three times for  red,  green,
182                 and  blue  and attaching 1 for alpha.  Each component is then
183                 multiplied by the signed scale factor  GL_c_SCALE,  added  to
184                 the  signed  bias  GL_c_BIAS,  and clamped to the range [0,1]
185                 (see glPixelTransfer).
186
187       GL_LUMINANCE_ALPHA
188                 Each element is a luminance/alpha pair.  The GL  converts  it
189                 to  floating point, then assembles it into an RGBA element by
190                 replicating the luminance value three times for  red,  green,
191                 and  blue.   Each  component is then multiplied by the signed
192                 scale factor GL_c_SCALE, added to the signed bias  GL_c_BIAS,
193                 and clamped to the range [0,1] (see
194                 glPixelTransfer).
195
196       Refer  to  the  glDrawPixels  reference  page  for a description of the
197       acceptable values for the type parameter.
198
199       If an application wants to store the texture at a certain resolution or
200       in  a certain , it can request the resolution and  with internalFormat.
201       The GL will choose an internal representation that closely approximates
202       that  requested  by internalFormat, but it may not match exactly.  (The
203       representations specified by GL_LUMINANCE, GL_LUMINANCE_ALPHA,  GL_RGB,
204       and  GL_RGBA  must match exactly. The numeric values 1, 2, 3, and 4 may
205       also be used to specify the above representations.)
206
207       Use the GL_PROXY_TEXTURE_3D target to try out a resolution  and  update
208       and recompute its best match for the requested storage resolution and .
209       To then query this state, call glGetTexLevelParameter.  If the  texture
210       cannot be accommodated, texture state is set to 0.
211
212       A  one-component  texture image uses only the red component of the RGBA
213       color extracted from pixels.  A two-component image uses the  R  and  A
214       values.   A three-component image uses the R, G, and B values.  A four-
215       component image uses all of the RGBA components.
216

NOTES

218       Texturing has no effect in color index mode.
219
220       The texture image can be represented by the same data  formats  as  the
221       pixels  in  a  glDrawPixels  command,  except that GL_STENCIL_INDEX and
222       GL_DEPTH_COMPONENT cannot be used.   glPixelStore  and  glPixelTransfer
223       modes   affect   texture   images   in  exactly  the  way  they  affect
224       glDrawPixels.
225
226       glTexImage3D is available only if the GL version is 1.2 or greater.
227
228       Internal formats other than 1, 2, 3, or 4 may be used only  if  the  GL
229       version is 1.1 or greater.
230
231       pixels may be a null pointer.  In this case texture memory is allocated
232       to accommodate a texture of  width  width,  height  height,  and  depth
233       depth.   You  can  then download subtextures to initialize this texture
234       memory.  The image is undefined if the user tries to  apply  an  unini‐
235       tialized portion of the texture image to a primitive.
236
237       Formats   GL_BGR,   and   GL_BGRA   and  types  GL_UNSIGNED_BYTE_3_3_2,
238       GL_UNSIGNED_BYTE_2_3_3_REV,                    GL_UNSIGNED_SHORT_5_6_5,
239       GL_UNSIGNED_SHORT_5_6_5_REV,                 GL_UNSIGNED_SHORT_4_4_4_4,
240       GL_UNSIGNED_SHORT_4_4_4_4_REV,               GL_UNSIGNED_SHORT_5_5_5_1,
241       GL_UNSIGNED_SHORT_1_5_5_5_REV,                 GL_UNSIGNED_INT_8_8_8_8,
242       GL_UNSIGNED_INT_8_8_8_8_REV,      GL_UNSIGNED_INT_10_10_10_2,       and
243       GL_UNSIGNED_INT_2_10_10_10_REV  are available only if the GL version is
244       1.2 or greater.
245
246       When the GL_ARB_multitexture extension is supported, glTexImage3D spec‐
247       ifies the three-dimensional texture for the current texture unit, spec‐
248       ified with glActiveTextureARB.
249
250       If the GL_ARB_imaging extension is supported, RGBA elements may also be
251       processed by the imaging pipeline.  The following stages may be applied
252       to an RGBA color before color component clamping to the range [0, 1]:
253
254       1. Color component replacement by the color table specified for
255          GL_COLOR_TABLE, if enabled. See glColorTable.
256
257       2. Color component replacement by the color table specified for
258          GL_POST_CONVOLUTION_COLOR_TABLE, if enabled.  See glColorTable.
259
260       3. Transformation by the color matrix.  See glMatrixMode.
261
262       4. RGBA components may be multiplied by GL_POST_COLOR_MATRIX_c_SCALE,
263          and  added  to   GL_POST_COLOR_MATRIX_c_BIAS,   if   enabled.    See
264          glPixelTransfer.
265
266       5. Color component replacement by the color table specified for
267          GL_POST_COLOR_MATRIX_COLOR_TABLE, if enabled.  See glColorTable.
268

ERRORS

270       GL_INVALID_ENUM   is  generated  if  target  is  not  GL_TEXTURE_3D  or
271       GL_PROXY_TEXTURE_3D.
272
273       GL_INVALID_ENUM is generated if format is not an accepted
274        constant.   Format   constants   other   than   GL_STENCIL_INDEX   and
275       GL_DEPTH_COMPONENT are accepted.
276
277       GL_INVALID_ENUM is generated if type is not a type constant.
278
279       GL_INVALID_ENUM  is  generated  if  type is GL_BITMAP and format is not
280       GL_COLOR_INDEX.
281
282       GL_INVALID_VALUE is generated if level is less than 0.
283
284       GL_INVALID_VALUE may be generated if level  is  greater  than  log2max,
285       where max is the returned value of GL_MAX_TEXTURE_SIZE.
286
287       GL_INVALID_VALUE  is  generated if internalFormat is not 1, 2, 3, 4, or
288       one of the accepted resolution and  symbolic constants.
289
290       GL_INVALID_VALUE is generated if width, height, or depth is less than 0
291       or  greater than 2 + GL_MAX_TEXTURE_SIZE, or if either cannot be repre‐
292       sented as 2k+2(border) for some integer value of k.
293
294       GL_INVALID_VALUE is generated if border is not 0 or 1.
295
296       GL_INVALID_OPERATION is generated if glTexImage3D is  executed  between
297       the execution of glBegin and the corresponding execution of glEnd.
298
299       GL_INVALID_OPERATION    is    generated    if    type    is    one   of
300       GL_UNSIGNED_BYTE_3_3_2,                     GL_UNSIGNED_BYTE_2_3_3_REV,
301       GL_UNSIGNED_SHORT_5_6_5,  or  GL_UNSIGNED_SHORT_5_6_5_REV and format is
302       not GL_RGB.
303
304       GL_INVALID_OPERATION   is    generated    if    type    is    one    of
305       GL_UNSIGNED_SHORT_4_4_4_4,               GL_UNSIGNED_SHORT_4_4_4_4_REV,
306       GL_UNSIGNED_SHORT_5_5_5_1,               GL_UNSIGNED_SHORT_1_5_5_5_REV,
307       GL_UNSIGNED_INT_8_8_8_8,                   GL_UNSIGNED_INT_8_8_8_8_REV,
308       GL_UNSIGNED_INT_10_10_10_2, or GL_UNSIGNED_INT_2_10_10_10_REV and  for‐
309       mat is neither GL_RGBA nor GL_BGRA.
310

ASSOCIATED GETS

312       glGetTexImage
313       glIsEnabled with argument GL_TEXTURE_3D
314