1Name 2 3 EXT_texture3D 4 5Name Strings 6 7 GL_EXT_texture3D 8 9Version 10 11 $Date: 1996/04/05 19:17:05 $ $Revision: 1.22 $ 12 13Number 14 15 6 16 17Dependencies 18 19 EXT_abgr affects the definition of this extension 20 EXT_texture is required 21 22Overview 23 24 This extension defines 3-dimensional texture mapping. In order to 25 define a 3D texture image conveniently, this extension also defines the 26 in-memory formats for 3D images, and adds pixel storage modes to support 27 them. 28 29 One important application of 3D textures is rendering volumes of image 30 data. 31 32New Procedures and Functions 33 34 void TexImage3DEXT(enum target, 35 int level, 36 enum internalformat, 37 sizei width, 38 sizei height, 39 sizei depth, 40 int border, 41 enum format, 42 enum type, 43 const void* pixels); 44 45New Tokens 46 47 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 48 GetFloatv, and GetDoublev, and by the <pname> parameter of PixelStore: 49 50 PACK_SKIP_IMAGES_EXT 0x806B 51 PACK_IMAGE_HEIGHT_EXT 0x806C 52 UNPACK_SKIP_IMAGES_EXT 0x806D 53 UNPACK_IMAGE_HEIGHT_EXT 0x806E 54 55 Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, by 56 the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and 57 GetDoublev, and by the <target> parameter of TexImage3DEXT, GetTexImage, 58 GetTexLevelParameteriv, GetTexLevelParameterfv, GetTexParameteriv, and 59 GetTexParameterfv: 60 61 TEXTURE_3D_EXT 0x806F 62 63 Accepted by the <target> parameter of TexImage3DEXT, 64 GetTexLevelParameteriv, and GetTexLevelParameterfv: 65 66 PROXY_TEXTURE_3D_EXT 0x8070 67 68 Accepted by the <pname> parameter of GetTexLevelParameteriv and 69 GetTexLevelParameterfv: 70 71 TEXTURE_DEPTH_EXT 0x8071 72 73 Accepted by the <pname> parameter of TexParameteriv, TexParameterfv, 74 GetTexParameteriv, and GetTexParameterfv: 75 76 TEXTURE_WRAP_R_EXT 0x8072 77 78 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 79 GetFloatv, and GetDoublev: 80 81 MAX_3D_TEXTURE_SIZE_EXT 0x8073 82 83Additions to Chapter 2 of the GL Specification (OpenGL Operation) 84 85 None 86 87Additions to Chapter 3 of the GL Specification (Rasterization) 88 89 The pixel storage modes are augmented to support 3D image formats in 90 memory. Table 3.1 is replaced with the table below: 91 92 Parameter Name Type Initial Value Valid Range 93 -------------- ---- ------------- ----------- 94 UNPACK_SWAP_BYTES boolean FALSE TRUE/FALSE 95 UNPACK_LSB_FIRST boolean FALSE TRUE/FALSE 96 UNPACK_ROW_LENGTH integer 0 [0, infinity] 97 UNPACK_SKIP_ROWS integer 0 [0, infinity] 98 UNPACK_SKIP_PIXELS integer 0 [0, infinity] 99 UNPACK_ALIGNMENT integer 4 1, 2, 4, 8 100 UNPACK_IMAGE_HEIGHT_EXT integer 0 [0, infinity] 101 UNPACK_SKIP_IMAGES_EXT integer 0 [0, infinity] 102 103 Table 3.1: PixelStore parameters pertaining to one or more of 104 DrawPixels, TexImage1D, TexImage2D, and TexImage3DEXT. 105 106 When TexImage3DEXT is called, the groups in memory are treated as being 107 arranged in a sequence of adjacent rectangles. Each rectangle is a 108 2-dimensional image, whose size and organization are specified by the 109 <width> and <height> parameters to TexImage3DEXT. The values of 110 UNPACK_ROW_LENGTH and UNPACK_ALIGNMENT control the row-to-row spacing in 111 these images in exactly the manner described in the GL Specification for 112 2-dimensional images. If the value of UNPACK_IMAGE_HEIGHT_EXT is not 113 positive, then the number of rows in each 2-dimensional image is 114 <height>; otherwise the number of rows is UNPACK_IMAGE_HEIGHT_EXT. Each 115 2-dimensional image comprises an integral number of rows, and is exactly 116 adjacent to its neighbor images. 117 118 The mechanism for selecting a sub-volume of a 3-dimensional image builds 119 on the mechanism for selecting a sub-rectangle of groups from a larger 120 containing rectangle. If UNPACK_SKIP_IMAGES_EXT is positive, the 121 pointer is advanced by UNPACK_SKIP_IMAGES_EXT times the number of 122 elements in one 2-dimensional image. Then <depth> 2-dimensional images 123 are processed, each having a subimage extracted in the manner described 124 in the GL Specification for 2-dimensional images. 125 126 The selected groups are processed as though they were part of a 127 2-dimensional image. When the final R, G, B, and A components have been 128 computed for a group, they are assigned to components of a texel as 129 described by Table 3.6 in the EXT_texture extension. Counting from 130 zero, each resulting Nth texel is assigned internal integer coordinates 131 [i,j,k], where 132 133 i = (N mod width) - border 134 135 j = ((N div width) mod height) - border 136 137 k = ((N div (width * height)) mod depth) - border 138 139 and the div operator performs integer division with truncation. Thus 140 the last 2-dimensional image of the 3-dimensional image is indexed with 141 the highest value of k. The dimensions of the 3-dimensional texture 142 image are <width> x <height> x <depth>. Integer values that will 143 represent the base-2 logarithm of these dimensions are n, m, and l, 144 defined such that 145 146 width = 2**n + (2 * border) 147 148 height = 2**m + (2 * border) 149 150 depth = 2**l + (2 * border) 151 152 It is acceptable for an implementation to vary its allocation of 153 internal component resolution based any TexImage3DEXT parameter, but the 154 allocation must not be a function of any other factor, and cannot be 155 changed once it is established. In particular, allocations must be 156 invariant -- the same allocation must be made each time a texture image 157 is specified with the same parameter values. Provision is made for an 158 application to determine what component resolutions are available 159 without having to fully specify the texture (see below). 160 161 Texture Wrap Modes 162 ------------------ 163 164 The additional token value TEXTURE_WRAP_R_EXT is accepted by 165 TexParameteri, TexParameterv, TexParameteriv, and TexParameterfv, 166 causing table 3.7 to be replaced with the table below: 167 168 Name Type Legal Values 169 ---- ---- ------------ 170 TEXTURE_WRAP_S integer CLAMP, REPEAT 171 TEXTURE_WRAP_T integer CLAMP, REPEAT 172 TEXTURE_WRAP_R_EXT integer CLAMP, REPEAT 173 TEXTURE_MIN_FILTER integer NEAREST, LINEAR, 174 NEAREST_MIPMAP_NEAREST, 175 NEAREST_MIPMAP_LINEAR, 176 LINEAR_MIPMAP_NEAREST, 177 LINEAR_MIPMAP_LINEAR 178 TEXTURE_MAG_FILTER integer NEAREST, LINEAR 179 TEXTURE_BORDER_COLOR 4 floats any 4 values in [0,1] 180 181 Table 3.7: Texture parameters and their values. 182 183 If TEXTURE_WRAP_R_EXT is set to REPEAT, then the GL ignores the integer 184 part of R coordinates, using only the fractional part. CLAMP causes R 185 to be clamped to the range [0, 1]. The initial state is for 186 TEXTURE_WRAP_R_EXT to be REPEAT. 187 188 Texture Minification 189 -------------------- 190 191 Continuous coordinates s, t, u, and v are defined in figure 3.10 of the 192 GL Specification. To discuss 3-dimensional texture mapping, coordinates 193 r and w are defined similarly. Coordinate w is equal to -border at the 194 "far" edge of the 3D image, understanding the image to be right-handed, 195 with k values increasing toward the viewer. It has value depth+border 196 at the near edge of this volume. Coordinate r has the same direction, 197 but is normalized so that it is 0.0 and 1.0 at the "far" and "near" 198 edges of a borderless volume. If the volume has a border, the 0.0 and 199 1.0 mappings of r continue to bound the core image. 200 201 The formulas for p, used to determine the level of detail, are modified 202 by including dw/dx and dw/dy terms in the obvious ways. Equation 3.7 203 sums (dw/dx)**2 into the left term, and (dw/dy)**2 into the right term. 204 Equation 3.8 has ((dw/dx * Dx + dw/dy * Dy)**2 added to the two terms 205 under the square root. The requirements for the function f(x,y) become 206 207 1. f(x, y) is continuous and monotonically increasing in each of 208 |du/dx|, |du/dy|, |dv/dx|, |dv/dy|, |dw/dx|, and |dw/dy|. 209 210 2. Let 211 212 m_u = max(|du/dx|, |du/dy|) 213 m_v = max(|dv/dx|, |dv/dy|) 214 m_w = max(|dw/dx|, |dw/dy|) 215 216 Then 217 218 max(m_u, m_v, m_w) <= f(x, y) <= m_u + m_v + m_w 219 220 The i and j coordinates of the texel selected for NEAREST filtering are 221 as defined in equations 3.9 and 3.10 of the GL Specification. 222 Coordinate k is computed as 223 224 / floor(w), r < 1 225 k = ( 226 \ 2**l - 1, r = 1 227 228 A 2x2x2 cube of texels is selected for LINEAR filtering. The i and j 229 coordinates of these texels are computed as defined in the GL 230 Specification for 2-dimensional images. The k coordinates are 231 computed as 232 233 / floor(w - 1/2) mod 2**l, TEXTURE_WRAP_R_EXT is REPEAT 234 k0 = ( 235 \ floor(w - 1/2), TEXTURE_WRAP_R_EXT is CLAMP 236 237 238 / (k0 + 1) mod 2**l, TEXTURE_WRAP_R_EXT is REPEAT 239 k1 = ( 240 \ k0 + 1, TEXTURE_WRAP_R_EXT is CLAMP 241 242 Let 243 244 A = frac(u - 1/2) 245 B = frac(v - 1/2) 246 C = frac(w - 1/2) 247 248 where frac(x) denotes the fractional part of x. Let T[i,j,k] be the 249 texel at location [i,j,k] in the texture image. Then the texture value, 250 T, is found as 251 252 T = (1-A) * (1-B) * (1-C) * T[i0,j0,k0] + 253 A * (1-B) * (1-C) * T[i1,j0,k0] + 254 (1-A) * B * (1-C) * T[i0,j1,k0] + 255 A * B * (1-C) * T[i1,j1,k0] + 256 (1-A) * (1-B) * C * T[i0,j0,k1] + 257 A * (1-B) * C * T[i1,j0,k1] + 258 (1-A) * B * C * T[i0,j1,k1] + 259 A * B * C * T[i1,j1,k1] 260 261 for a 3-dimensional texture. If any of the selected T[i,j,k] in the 262 above equation refer to a border texel with unspecified value, then the 263 border color given by the current setting of TEXTURE_BORDER_COLOR is 264 used instead of the unspecified value or values. 265 266 Mipmapping 267 ---------- 268 269 TEXTURE_MIN_FILTER values NEAREST_MIPMAP_NEAREST, NEAREST_MIPMAP_LINEAR, 270 LINEAR_MIPMAP_NEAREST, and LINEAR_MIPMAP_LINEAR each require the use of 271 a mipmap. A 3-dimensional mipmap is an ordered set of arrays 272 representing the same image; each array has a resolution lower than the 273 previous one. If the texture, excluding is border, has dimensions 274 2**n x 2**m x 2**l, then there are exactly max(n, m, l) + 1 mipmap 275 arrays. Each subsequent array has dimensions 276 277 size(i-1) x size(j-1) x size(k-1) 278 279 where the dimensions of the previous array are 280 281 size(i) x size(j) x size(k) 282 283 and 284 285 / 2**x + 2*border, x > 0 286 size(x) = ( 287 \ 1 + 2*border, x <= 0 288 289 Each array in a 3-dimensional mipmap is transmitted to the GL using 290 TexImage3DEXT; the array being set is indicated with the <level> 291 parameter. The rules for completeness of the set of arrays are as 292 described in the GL Specification, augmented in EXT_texture. The rules 293 for mipmap array selection, and for filtering of the two selected 294 arrays, are also as described in the GL Specification. Finally, the 295 rules for texture magnification are also exactly as described in the 296 GL Specification. 297 298 Texture Application 299 ------------------- 300 301 3-dimensional texture mapping is enabled and disabled using the generic 302 Enable and Disable commands, with <cap> specified as TEXTURE_3D_EXT. If 303 either or both TEXTURE_1D or TEXTURE_2D are enabled at the same time as 304 TEXTURE_3D_EXT, the 3-dimensional texture is used. 305 306 Query support 307 ------------- 308 309 The proxy texture PROXY_TEXTURE_3D_EXT can be used by applications to 310 query an implementations maximum configurations just as it can be for 311 1-dimensional and 2-dimensional textures. 312 313 Alternate sets of partial per-level texture state are defined for 314 the proxy texture PROXY_TEXTURE_3D_EXT. Specifically, 315 TEXTURE_WIDTH, TEXTURE_HEIGHT, TEXTURE_DEPTH_EXT, TEXTURE_BORDER, 316 TEXTURE_COMPONENTS, TEXTURE_RED_SIZE_EXT, TEXTURE_GREEN_SIZE_EXT, 317 TEXTURE_BLUE_SIZE_EXT, TEXTURE_ALPHA_SIZE_EXT, 318 TEXTURE_LUMINANCE_SIZE_EXT, and TEXTURE_INTENSITY_SIZE_EXT are 319 maintained the the proxy texture. When TexImage3DEXT is called 320 with <target> set to PROXY_TEXTURE_3D_EXT, these proxy state 321 values are always respecified, even if the texture is too large to 322 actually be used. If the texture is too large, all of these state 323 variables are set to zero. If the texture could be accommodated 324 by TexImage3DEXT called with <target> TEXTURE_3D_EXT, these values 325 are set as though TEXTURE_3D_EXT were being defined. All of these 326 state value can be queried with GetTexLevelParameteriv with 327 <target> set to PROXY_TEXTURE_3D_EXT. Calling TexImage3DEXT with 328 <target> PROXY_TEXTURE_3D_EXT has no effect on the actual 329 3-dimensional texture or its state. 330 331 There is no image associated with PROXY_TEXTURE_3D_EXT. Therefore 332 PROXY_TEXTURE_3D_EXT cannot be used as a texture, and its image must 333 never be queried using GetTexImage. (The error INVALID_ENUM results if 334 this is attempted.) Likewise, there is no nonlevel-related state 335 associated with a proxy texture, so calling GetTexParameteriv or 336 GetTexParameterfv with <target> PROXY_TEXTURE_3D_EXT results in the 337 error INVALID_ENUM. 338 339Additions to Chapter 4 of the GL Specification (Per-Fragment Operations 340and the Framebuffer) 341 342 None 343 344Additions to Chapter 5 of the GL Specification (Special Functions) 345 346 TexImage3DEXT with a proxy target is not included in display 347 lists, but is instead executed immediately. 348 349Additions to Chapter 6 of the GL Specification (State and State Requests) 350 351 3-dimensional texture images are queried using GetTexImage with its 352 <target> parameter set to TEXTURE_3D_EXT. The assignment of texel 353 component values to the initial R, G, B, and A components of a pixel 354 group is described in EXT_texture. Pixel transfer and pixel storage 355 operations are applied as if the image were 2-dimensional, except that 356 the additional pixel storage state values PACK_IMAGE_HEIGHT_EXT and 357 PACK_SKIP_IMAGES_EXT affect the storage of the image into memory. The 358 correspondence of texels to memory locations is as defined for 359 TexImage3DEXT above, substituting PACK* state for UNPACK* state in all 360 occurrences. 361 362Additions to the GLX Specification 363 364 None 365 366GLX Protocol 367 368 A new GL rendering command is added. This command contains pixel data; 369 thus it is sent to the server either as part of a glXRender request 370 or as part of a glXRenderLarge request: 371 372 TexImage3DEXT 373 2 84+n+p rendering command length 374 2 4114 rendering command opcode 375 1 BOOL swap_bytes 376 1 BOOL lsb_first 377 2 unused 378 4 CARD32 row_length 379 4 CARD32 image_height 380 4 CARD32 image_depth 381 4 CARD32 skip_rows 382 4 CARD32 skip_images 383 4 CARD32 skip_volumes 384 4 CARD32 skip_pixels 385 4 CARD32 alignment 386 4 ENUM target 387 4 INT32 level 388 4 ENUM internalformat 389 4 INT32 width 390 4 INT32 height 391 4 INT32 depth 392 4 INT32 size4d 393 4 INT32 border 394 4 ENUM format 395 4 ENUM type 396 4 CARD32 null_image 397 n LISTofBYTE pixels 398 p unused, p=pad(n) 399 400 If the command is encoded in a glXRenderLarge request, the command 401 opcode and command length fields above are expanded to 4 bytes each: 402 403 4 88+n+p rendering command length 404 4 4114 rendering command opcode 405 406 If <width> < 0, <height> < 0, <depth> < 0, <format> is invalid or <type> is 407 invalid, then the command is erroneous and n=0. 408 409 <pixels> is arranged as a sequence of adjacent rectangles. Each rectangle is a 410 2-dimensional image, whose structure is determined by the image height and the 411 parameters <swap_bytes>, <lsb_first>, <row_length>, <skip_rows>, <skip_pixels>, 412 <alignment>, <width>, <format>, and <type> given in the request. If <image_height> 413 is not positive then the number of rows (i.e., the image height) is <height>; 414 otherwise the number of rows is <image_height>. 415 416 <skip_images> allows a sub-volume of the 3-dimensional image to be selected. 417 If <skip_images> is positive, then the pointer is advanced by <skip_images> 418 times the number of elements in one 2-dimensional image. Then <depth> 419 2-dimensional images are read, each having a subimage extracted in the 420 manner described in Appendix A of the GLX Protocol Specification. 421 422 423Dependencies on EXT_abgr 424 425 If EXT_abgr is supported, the <format> parameter of TexImage3DEXT 426 accepts ABGR_EXT. Otherwise it does not. 427 428Dependencies on EXT_texture 429 430 EXT_texture is required. All of the <components> tokens defined by 431 EXT_texture are accepted by the <internalformat> parameter of 432 TexImage3DEXT, with the same semantics that are defined by EXT_texture. 433 434 The query and error extensions defined by EXT_texture are extended in 435 this document. 436 437Errors 438 439 INVALID_ENUM is generated if <target> is not TEXTURE_3D_EXT or 440 PROXY_TEXTURE_3D_EXT. 441 442 INVALID_ENUM is generated if the <target> parameter to 443 GetTexParameteriv, GetTexParameterfv or GetTexImage is 444 PROXY_TEXTURE_3D_EXT. 445 446 INVALID_VALUE is generated if <level> is less than zero 447 448 INVALID_ENUM is generated if <internalformat> is not ALPHA, RGB, RGBA, 449 LUMINANCE, LUMINANCE_ALPHA, or one of the tokens defined by the 450 EXT_texture extension. (Values 1, 2, 3, and 4 are not accepted as 451 internal formats by TexImage3DEXT). 452 453 INVALID_VALUE is generated if <width>, <height>, or <depth> is less than 454 zero, or cannot be represented as 2**k + 2*border for some integer k. 455 456 INVALID_VALUE is generated if <border> is not 0 or 1. 457 458 INVALID_ENUM is generated if <format> is not COLOR_INDEX, RED, GREEN, 459 BLUE, ALPHA, RGB, RGBA, LUMINANCE, or LUMINANCE_ALPHA (or ABGR_EXT if 460 EXT_abgr is supported). 461 462 INVALID_ENUM is generated if <type> is not UNSIGNED_BYTE, BYTE, 463 UNSIGNED_SHORT, SHORT, UNSIGNED_INT, INT, or FLOAT. 464 465 INVALID_OPERATION is generated if TexImage3DEXT is called between 466 execution of Begin and the corresponding execution of End. 467 468 TEXTURE_TOO_LARGE_EXT is generated if the texture as specified cannot be 469 accommodated by the implementation. This error will not occur if none 470 of <width>, <height>, or <depth> is greater than MAX_3D_TEXTURE_SIZE_EXT. 471 472New State 473 474 Get Value Get Command Type Initial Value Attribute 475 --------- ----------- ---- ------------- --------- 476 UNPACK_SKIP_IMAGES_EXT GetIntegerv Z+ 0 - 477 UNPACK_IMAGE_HEIGHT_EXT GetIntegerv Z+ 0 - 478 PACK_SKIP_IMAGES_EXT GetIntegerv Z+ 0 - 479 PACK_IMAGE_HEIGHT_EXT GetIntegerv Z+ 0 - 480 TEXTURE_3D_EXT IsEnabled B FALSE texture/enable 481 TEXTURE_WRAP_R_EXT GetTexParameteriv 1 x Z2 REPEAT texture 482 TEXTURE_DEPTH_EXT GetTexLevelParameteriv 1 x 2 x levels x Z+ 0 - 483 484 (old state with new type information) 485 486 TEXTURE GetTexImage 3 x 1 x levels x I null - 487 TEXTURE_RED_SIZE_EXT GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - 488 TEXTURE_GREEN_SIZE_EXT GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - 489 TEXTURE_BLUE_SIZE_EXT GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - 490 TEXTURE_ALPHA_SIZE_EXT GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - 491 TEXTURE_LUMINANCE_SIZE_EXT GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - 492 TEXTURE_INTENSITY_SIZE_EXT GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - 493 TEXTURE_WIDTH GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - 494 TEXTURE_HEIGHT GetTexLevelParameteriv 2 x 2 x levels x Z+ 0 - 495 TEXTURE_BORDER GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - 496 TEXTURE_COMPONENTS (1D and 2D) GetTexLevelParameteriv 2 x 2 x levels x Z42 1 - 497 TEXTURE_COMPONENTS (3D) GetTexLevelParameteriv 1 x 2 x levels x Z38 LUMINANCE - 498 TEXTURE_BORDER_COLOR GetTexParameteriv 3 x C 0, 0, 0, 0 texture 499 TEXTURE_MIN_FILTER GetTexParameteriv 3 x Z6 NEAREST_MIPMAP_LINEAR texture 500 TEXTURE_MAG_FILTER GetTexParameteriv 3 x Z2 LINEAR texture 501 TEXTURE_WRAP_S GetTexParameteriv 3 x Z2 REPEAT texture 502 TEXTURE_WRAP_T GetTexParameteriv 2 x Z2 REPEAT texture 503 504New Implementation Dependent State 505 506 Get Value Get Command Type Minimum Value 507 --------- ----------- ---- ------------- 508 MAX_3D_TEXTURE_SIZE_EXT GetIntegerv Z+ 16 509