glTexSubImage3D(3gl)

1GLTEXSUBIMAGE3D(3G)                                        GLTEXSUBIMAGE3D(3G)
2
3
4

NAME

6       glTexSubImage3D - specify a three-dimensional texture subimage
7
8

C SPECIFICATION

10       void glTexSubImage3D( GLenum target,
11                             GLint level,
12                             GLint xoffset,
13                             GLint yoffset,
14                             GLint zoffset,
15                             GLsizei width,
16                             GLsizei height,
17                             GLsizei depth,
18                             GLenum format,
19                             GLenum type,
20                             const GLvoid *pixels )
21
22

PARAMETERS

24       target   Specifies the target texture.  Must be GL_TEXTURE_3D.
25
26       level    Specifies  the  level-of-detail  number.   Level 0 is the base
27                image level.  Level n is the nth mipmap reduction image.
28
29       xoffset  Specifies a texel offset in the x direction within the texture
30                array.
31
32       yoffset  Specifies a texel offset in the y direction within the texture
33                array.
34
35       zoffset  Specifies a texel offset in the z direction within the texture
36                array.
37
38       width    Specifies the width of the texture subimage.
39
40       height   Specifies the height of the texture subimage.
41
42       depth    Specifies the depth of the texture subimage.
43
44       format   Specifies the  of the pixel data.  The following symbolic val‐
45                ues are accepted: GL_COLOR_INDEX, GL_RED,  GL_GREEN,  GL_BLUE,
46                GL_ALPHA,  GL_RGB, GL_BGR, GL_RGBA, GL_BGRA, GL_LUMINANCE, and
47                GL_LUMINANCE_ALPHA.
48
49       type     Specifies the data type of the pixel data.  The following sym‐
50                bolic   values   are   accepted:   GL_UNSIGNED_BYTE,  GL_BYTE,
51                GL_BITMAP,   GL_UNSIGNED_SHORT,   GL_SHORT,   GL_UNSIGNED_INT,
52                GL_INT,            GL_FLOAT,           GL_UNSIGNED_BYTE_3_3_2,
53                GL_UNSIGNED_BYTE_2_3_3_REV,           GL_UNSIGNED_SHORT_5_6_5,
54                GL_UNSIGNED_SHORT_5_6_5_REV,        GL_UNSIGNED_SHORT_4_4_4_4,
55                GL_UNSIGNED_SHORT_4_4_4_4_REV,      GL_UNSIGNED_SHORT_5_5_5_1,
56                GL_UNSIGNED_SHORT_1_5_5_5_REV,        GL_UNSIGNED_INT_8_8_8_8,
57                GL_UNSIGNED_INT_8_8_8_8_REV,  GL_UNSIGNED_INT_10_10_10_2,  and
58                GL_UNSIGNED_INT_2_10_10_10_REV.
59
60       pixels   Specifies a pointer to the image data in memory.
61

DESCRIPTION

63       Texturing maps a portion of a specified texture image onto each graphi‐
64       cal primitive for which texturing is enabled.  To  enable  and  disable
65       three-dimensional  texturing, call glEnable and glDisable with argument
66       GL_TEXTURE_3D.
67
68       glTexSubImage3D redefines a contiguous subregion of an existing  three-
69       dimensional texture image.  The texels referenced by pixels replace the
70       portion of the existing texture array with x indices xoffset and  xoff‐
71       set+width−1,  inclusive, y indices yoffset and yoffset+height−1, inclu‐
72       sive, and z  indices  zoffset  and  zoffset+depth−1,  inclusive.   This
73       region  may  not  include  any  texels outside the range of the texture
74       array as it was originally specified.  It is not an error to specify  a
75       subtexture  with  zero width, height, or depth but such a specification
76       has no effect.
77

NOTES

79       glTexSubImage3D is available only if the GL version is 1.2 or greater.
80
81       Texturing has no effect in color index mode.
82
83       glPixelStore and glPixelTransfer modes affect texture images in exactly
84       the way they affect glDrawPixels.
85
86       Formats   GL_BGR,   and   GL_BGRA   and  types  GL_UNSIGNED_BYTE_3_3_2,
87       GL_UNSIGNED_BYTE_2_3_3_REV,                    GL_UNSIGNED_SHORT_5_6_5,
88       GL_UNSIGNED_SHORT_5_6_5_REV,                 GL_UNSIGNED_SHORT_4_4_4_4,
89       GL_UNSIGNED_SHORT_4_4_4_4_REV,               GL_UNSIGNED_SHORT_5_5_5_1,
90       GL_UNSIGNED_SHORT_1_5_5_5_REV,                 GL_UNSIGNED_INT_8_8_8_8,
91       GL_UNSIGNED_INT_8_8_8_8_REV,      GL_UNSIGNED_INT_10_10_10_2,       and
92       GL_UNSIGNED_INT_2_10_10_10_REV  are available only if the GL version is
93       1.2 or greater.
94
95       When the GL_ARB_multitexture extension  is  supported,  glTexSubImage3D
96       specifies a three-dimensional sub texture for the current texture unit,
97       specified with glActiveTextureARB.
98
99       When the GL_ARB_imaging extension is  supported,  the  RGBA  components
100       specified  in  pixels  may  be  processed by the imaging pipeline.  See
101       glTexImage3D for specific details.
102

ERRORS

104       GL_INVALID_ENUM is generated if target is not GL_TEXTURE_3D.
105
106       GL_INVALID_OPERATION is generated if the texture  array  has  not  been
107       defined by a previous glTexImage3D operation.
108
109       GL_INVALID_VALUE is generated if level is less than 0.
110
111       GL_INVALID_VALUE  may  be  generated  if level is greater than log2max,
112       where max is the returned value of GL_MAX_TEXTURE_SIZE.
113
114       GL_INVALID_VALUE is  generated  if  xoffset<−b,  (xoffset+width)>(w−b),
115       yoffset<−b,   or   (yoffset+height)>(h−b),  or  zoffset<−b,  or  (zoff‐
116       set+depth)>(d−b),  where  w  is  the   GL_TEXTURE_WIDTH,   h   is   the
117       GL_TEXTURE_HEIGHT,  d is the GL_TEXTURE_DEPTH and b is the border width
118       of the texture image being modified.  Note that w,  h,  and  d  include
119       twice the border width.
120
121       GL_INVALID_VALUE  is  generated if width, height, or depth is less than
122       0.
123
124       GL_INVALID_ENUM is generated if format is not an accepted
125        constant.
126
127       GL_INVALID_ENUM is generated if type is not a type constant.
128
129       GL_INVALID_ENUM is generated if type is GL_BITMAP  and  format  is  not
130       GL_COLOR_INDEX.
131
132       GL_INVALID_OPERATION   is  generated  if  glTexSubImage3D  is  executed
133       between the execution of glBegin and  the  corresponding  execution  of
134       glEnd.
135
136       GL_INVALID_OPERATION    is    generated    if    type    is    one   of
137       GL_UNSIGNED_BYTE_3_3_2,                     GL_UNSIGNED_BYTE_2_3_3_REV,
138       GL_UNSIGNED_SHORT_5_6_5,  or  GL_UNSIGNED_SHORT_5_6_5_REV and format is
139       not GL_RGB.
140
141       GL_INVALID_OPERATION   is    generated    if    type    is    one    of
142       GL_UNSIGNED_SHORT_4_4_4_4,               GL_UNSIGNED_SHORT_4_4_4_4_REV,
143       GL_UNSIGNED_SHORT_5_5_5_1,               GL_UNSIGNED_SHORT_1_5_5_5_REV,
144       GL_UNSIGNED_INT_8_8_8_8,                   GL_UNSIGNED_INT_8_8_8_8_REV,
145       GL_UNSIGNED_INT_10_10_10_2, or GL_UNSIGNED_INT_2_10_10_10_REV and  for‐
146       mat is neither GL_RGBA nor GL_BGRA.
147

ASSOCIATED GETS

149       glGetTexImage
150       glIsEnabled with argument GL_TEXTURE_3D
151