| Name | |
| EXT_texture3D | |
| Name Strings | |
| GL_EXT_texture3D | |
| Version | |
| $Date: 1996/04/05 19:17:05 $ $Revision: 1.22 $ | |
| Number | |
| 6 | |
| Dependencies | |
| EXT_abgr affects the definition of this extension | |
| EXT_texture is required | |
| Overview | |
| This extension defines 3-dimensional texture mapping. In order to | |
| define a 3D texture image conveniently, this extension also defines the | |
| in-memory formats for 3D images, and adds pixel storage modes to support | |
| them. | |
| One important application of 3D textures is rendering volumes of image | |
| data. | |
| New Procedures and Functions | |
| void TexImage3DEXT(enum target, | |
| int level, | |
| enum internalformat, | |
| sizei width, | |
| sizei height, | |
| sizei depth, | |
| int border, | |
| enum format, | |
| enum type, | |
| const void* pixels); | |
| New Tokens | |
| Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, | |
| GetFloatv, and GetDoublev, and by the <pname> parameter of PixelStore: | |
| PACK_SKIP_IMAGES_EXT 0x806B | |
| PACK_IMAGE_HEIGHT_EXT 0x806C | |
| UNPACK_SKIP_IMAGES_EXT 0x806D | |
| UNPACK_IMAGE_HEIGHT_EXT 0x806E | |
| Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, by | |
| the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and | |
| GetDoublev, and by the <target> parameter of TexImage3DEXT, GetTexImage, | |
| GetTexLevelParameteriv, GetTexLevelParameterfv, GetTexParameteriv, and | |
| GetTexParameterfv: | |
| TEXTURE_3D_EXT 0x806F | |
| Accepted by the <target> parameter of TexImage3DEXT, | |
| GetTexLevelParameteriv, and GetTexLevelParameterfv: | |
| PROXY_TEXTURE_3D_EXT 0x8070 | |
| Accepted by the <pname> parameter of GetTexLevelParameteriv and | |
| GetTexLevelParameterfv: | |
| TEXTURE_DEPTH_EXT 0x8071 | |
| Accepted by the <pname> parameter of TexParameteriv, TexParameterfv, | |
| GetTexParameteriv, and GetTexParameterfv: | |
| TEXTURE_WRAP_R_EXT 0x8072 | |
| Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, | |
| GetFloatv, and GetDoublev: | |
| MAX_3D_TEXTURE_SIZE_EXT 0x8073 | |
| Additions to Chapter 2 of the GL Specification (OpenGL Operation) | |
| None | |
| Additions to Chapter 3 of the GL Specification (Rasterization) | |
| The pixel storage modes are augmented to support 3D image formats in | |
| memory. Table 3.1 is replaced with the table below: | |
| Parameter Name Type Initial Value Valid Range | |
| -------------- ---- ------------- ----------- | |
| UNPACK_SWAP_BYTES boolean FALSE TRUE/FALSE | |
| UNPACK_LSB_FIRST boolean FALSE TRUE/FALSE | |
| UNPACK_ROW_LENGTH integer 0 [0, infinity] | |
| UNPACK_SKIP_ROWS integer 0 [0, infinity] | |
| UNPACK_SKIP_PIXELS integer 0 [0, infinity] | |
| UNPACK_ALIGNMENT integer 4 1, 2, 4, 8 | |
| UNPACK_IMAGE_HEIGHT_EXT integer 0 [0, infinity] | |
| UNPACK_SKIP_IMAGES_EXT integer 0 [0, infinity] | |
| Table 3.1: PixelStore parameters pertaining to one or more of | |
| DrawPixels, TexImage1D, TexImage2D, and TexImage3DEXT. | |
| When TexImage3DEXT is called, the groups in memory are treated as being | |
| arranged in a sequence of adjacent rectangles. Each rectangle is a | |
| 2-dimensional image, whose size and organization are specified by the | |
| <width> and <height> parameters to TexImage3DEXT. The values of | |
| UNPACK_ROW_LENGTH and UNPACK_ALIGNMENT control the row-to-row spacing in | |
| these images in exactly the manner described in the GL Specification for | |
| 2-dimensional images. If the value of UNPACK_IMAGE_HEIGHT_EXT is not | |
| positive, then the number of rows in each 2-dimensional image is | |
| <height>; otherwise the number of rows is UNPACK_IMAGE_HEIGHT_EXT. Each | |
| 2-dimensional image comprises an integral number of rows, and is exactly | |
| adjacent to its neighbor images. | |
| The mechanism for selecting a sub-volume of a 3-dimensional image builds | |
| on the mechanism for selecting a sub-rectangle of groups from a larger | |
| containing rectangle. If UNPACK_SKIP_IMAGES_EXT is positive, the | |
| pointer is advanced by UNPACK_SKIP_IMAGES_EXT times the number of | |
| elements in one 2-dimensional image. Then <depth> 2-dimensional images | |
| are processed, each having a subimage extracted in the manner described | |
| in the GL Specification for 2-dimensional images. | |
| The selected groups are processed as though they were part of a | |
| 2-dimensional image. When the final R, G, B, and A components have been | |
| computed for a group, they are assigned to components of a texel as | |
| described by Table 3.6 in the EXT_texture extension. Counting from | |
| zero, each resulting Nth texel is assigned internal integer coordinates | |
| [i,j,k], where | |
| i = (N mod width) - border | |
| j = ((N div width) mod height) - border | |
| k = ((N div (width * height)) mod depth) - border | |
| and the div operator performs integer division with truncation. Thus | |
| the last 2-dimensional image of the 3-dimensional image is indexed with | |
| the highest value of k. The dimensions of the 3-dimensional texture | |
| image are <width> x <height> x <depth>. Integer values that will | |
| represent the base-2 logarithm of these dimensions are n, m, and l, | |
| defined such that | |
| width = 2**n + (2 * border) | |
| height = 2**m + (2 * border) | |
| depth = 2**l + (2 * border) | |
| It is acceptable for an implementation to vary its allocation of | |
| internal component resolution based any TexImage3DEXT parameter, but the | |
| allocation must not be a function of any other factor, and cannot be | |
| changed once it is established. In particular, allocations must be | |
| invariant -- the same allocation must be made each time a texture image | |
| is specified with the same parameter values. Provision is made for an | |
| application to determine what component resolutions are available | |
| without having to fully specify the texture (see below). | |
| Texture Wrap Modes | |
| ------------------ | |
| The additional token value TEXTURE_WRAP_R_EXT is accepted by | |
| TexParameteri, TexParameterv, TexParameteriv, and TexParameterfv, | |
| causing table 3.7 to be replaced with the table below: | |
| Name Type Legal Values | |
| ---- ---- ------------ | |
| TEXTURE_WRAP_S integer CLAMP, REPEAT | |
| TEXTURE_WRAP_T integer CLAMP, REPEAT | |
| TEXTURE_WRAP_R_EXT integer CLAMP, REPEAT | |
| TEXTURE_MIN_FILTER integer NEAREST, LINEAR, | |
| NEAREST_MIPMAP_NEAREST, | |
| NEAREST_MIPMAP_LINEAR, | |
| LINEAR_MIPMAP_NEAREST, | |
| LINEAR_MIPMAP_LINEAR | |
| TEXTURE_MAG_FILTER integer NEAREST, LINEAR | |
| TEXTURE_BORDER_COLOR 4 floats any 4 values in [0,1] | |
| Table 3.7: Texture parameters and their values. | |
| If TEXTURE_WRAP_R_EXT is set to REPEAT, then the GL ignores the integer | |
| part of R coordinates, using only the fractional part. CLAMP causes R | |
| to be clamped to the range [0, 1]. The initial state is for | |
| TEXTURE_WRAP_R_EXT to be REPEAT. | |
| Texture Minification | |
| -------------------- | |
| Continuous coordinates s, t, u, and v are defined in figure 3.10 of the | |
| GL Specification. To discuss 3-dimensional texture mapping, coordinates | |
| r and w are defined similarly. Coordinate w is equal to -border at the | |
| "far" edge of the 3D image, understanding the image to be right-handed, | |
| with k values increasing toward the viewer. It has value depth+border | |
| at the near edge of this volume. Coordinate r has the same direction, | |
| but is normalized so that it is 0.0 and 1.0 at the "far" and "near" | |
| edges of a borderless volume. If the volume has a border, the 0.0 and | |
| 1.0 mappings of r continue to bound the core image. | |
| The formulas for p, used to determine the level of detail, are modified | |
| by including dw/dx and dw/dy terms in the obvious ways. Equation 3.7 | |
| sums (dw/dx)**2 into the left term, and (dw/dy)**2 into the right term. | |
| Equation 3.8 has ((dw/dx * Dx + dw/dy * Dy)**2 added to the two terms | |
| under the square root. The requirements for the function f(x,y) become | |
| 1. f(x, y) is continuous and monotonically increasing in each of | |
| |du/dx|, |du/dy|, |dv/dx|, |dv/dy|, |dw/dx|, and |dw/dy|. | |
| 2. Let | |
| m_u = max(|du/dx|, |du/dy|) | |
| m_v = max(|dv/dx|, |dv/dy|) | |
| m_w = max(|dw/dx|, |dw/dy|) | |
| Then | |
| max(m_u, m_v, m_w) <= f(x, y) <= m_u + m_v + m_w | |
| The i and j coordinates of the texel selected for NEAREST filtering are | |
| as defined in equations 3.9 and 3.10 of the GL Specification. | |
| Coordinate k is computed as | |
| / floor(w), r < 1 | |
| k = ( | |
| \ 2**l - 1, r = 1 | |
| A 2x2x2 cube of texels is selected for LINEAR filtering. The i and j | |
| coordinates of these texels are computed as defined in the GL | |
| Specification for 2-dimensional images. The k coordinates are | |
| computed as | |
| / floor(w - 1/2) mod 2**l, TEXTURE_WRAP_R_EXT is REPEAT | |
| k0 = ( | |
| \ floor(w - 1/2), TEXTURE_WRAP_R_EXT is CLAMP | |
| / (k0 + 1) mod 2**l, TEXTURE_WRAP_R_EXT is REPEAT | |
| k1 = ( | |
| \ k0 + 1, TEXTURE_WRAP_R_EXT is CLAMP | |
| Let | |
| A = frac(u - 1/2) | |
| B = frac(v - 1/2) | |
| C = frac(w - 1/2) | |
| where frac(x) denotes the fractional part of x. Let T[i,j,k] be the | |
| texel at location [i,j,k] in the texture image. Then the texture value, | |
| T, is found as | |
| T = (1-A) * (1-B) * (1-C) * T[i0,j0,k0] + | |
| A * (1-B) * (1-C) * T[i1,j0,k0] + | |
| (1-A) * B * (1-C) * T[i0,j1,k0] + | |
| A * B * (1-C) * T[i1,j1,k0] + | |
| (1-A) * (1-B) * C * T[i0,j0,k1] + | |
| A * (1-B) * C * T[i1,j0,k1] + | |
| (1-A) * B * C * T[i0,j1,k1] + | |
| A * B * C * T[i1,j1,k1] | |
| for a 3-dimensional texture. If any of the selected T[i,j,k] in the | |
| above equation refer to a border texel with unspecified value, then the | |
| border color given by the current setting of TEXTURE_BORDER_COLOR is | |
| used instead of the unspecified value or values. | |
| Mipmapping | |
| ---------- | |
| TEXTURE_MIN_FILTER values NEAREST_MIPMAP_NEAREST, NEAREST_MIPMAP_LINEAR, | |
| LINEAR_MIPMAP_NEAREST, and LINEAR_MIPMAP_LINEAR each require the use of | |
| a mipmap. A 3-dimensional mipmap is an ordered set of arrays | |
| representing the same image; each array has a resolution lower than the | |
| previous one. If the texture, excluding is border, has dimensions | |
| 2**n x 2**m x 2**l, then there are exactly max(n, m, l) + 1 mipmap | |
| arrays. Each subsequent array has dimensions | |
| size(i-1) x size(j-1) x size(k-1) | |
| where the dimensions of the previous array are | |
| size(i) x size(j) x size(k) | |
| and | |
| / 2**x + 2*border, x > 0 | |
| size(x) = ( | |
| \ 1 + 2*border, x <= 0 | |
| Each array in a 3-dimensional mipmap is transmitted to the GL using | |
| TexImage3DEXT; the array being set is indicated with the <level> | |
| parameter. The rules for completeness of the set of arrays are as | |
| described in the GL Specification, augmented in EXT_texture. The rules | |
| for mipmap array selection, and for filtering of the two selected | |
| arrays, are also as described in the GL Specification. Finally, the | |
| rules for texture magnification are also exactly as described in the | |
| GL Specification. | |
| Texture Application | |
| ------------------- | |
| 3-dimensional texture mapping is enabled and disabled using the generic | |
| Enable and Disable commands, with <cap> specified as TEXTURE_3D_EXT. If | |
| either or both TEXTURE_1D or TEXTURE_2D are enabled at the same time as | |
| TEXTURE_3D_EXT, the 3-dimensional texture is used. | |
| Query support | |
| ------------- | |
| The proxy texture PROXY_TEXTURE_3D_EXT can be used by applications to | |
| query an implementations maximum configurations just as it can be for | |
| 1-dimensional and 2-dimensional textures. | |
| Alternate sets of partial per-level texture state are defined for | |
| the proxy texture PROXY_TEXTURE_3D_EXT. Specifically, | |
| TEXTURE_WIDTH, TEXTURE_HEIGHT, TEXTURE_DEPTH_EXT, TEXTURE_BORDER, | |
| TEXTURE_COMPONENTS, TEXTURE_RED_SIZE_EXT, TEXTURE_GREEN_SIZE_EXT, | |
| TEXTURE_BLUE_SIZE_EXT, TEXTURE_ALPHA_SIZE_EXT, | |
| TEXTURE_LUMINANCE_SIZE_EXT, and TEXTURE_INTENSITY_SIZE_EXT are | |
| maintained the the proxy texture. When TexImage3DEXT is called | |
| with <target> set to PROXY_TEXTURE_3D_EXT, these proxy state | |
| values are always respecified, even if the texture is too large to | |
| actually be used. If the texture is too large, all of these state | |
| variables are set to zero. If the texture could be accommodated | |
| by TexImage3DEXT called with <target> TEXTURE_3D_EXT, these values | |
| are set as though TEXTURE_3D_EXT were being defined. All of these | |
| state value can be queried with GetTexLevelParameteriv with | |
| <target> set to PROXY_TEXTURE_3D_EXT. Calling TexImage3DEXT with | |
| <target> PROXY_TEXTURE_3D_EXT has no effect on the actual | |
| 3-dimensional texture or its state. | |
| There is no image associated with PROXY_TEXTURE_3D_EXT. Therefore | |
| PROXY_TEXTURE_3D_EXT cannot be used as a texture, and its image must | |
| never be queried using GetTexImage. (The error INVALID_ENUM results if | |
| this is attempted.) Likewise, there is no nonlevel-related state | |
| associated with a proxy texture, so calling GetTexParameteriv or | |
| GetTexParameterfv with <target> PROXY_TEXTURE_3D_EXT results in the | |
| error INVALID_ENUM. | |
| Additions to Chapter 4 of the GL Specification (Per-Fragment Operations | |
| and the Framebuffer) | |
| None | |
| Additions to Chapter 5 of the GL Specification (Special Functions) | |
| TexImage3DEXT with a proxy target is not included in display | |
| lists, but is instead executed immediately. | |
| Additions to Chapter 6 of the GL Specification (State and State Requests) | |
| 3-dimensional texture images are queried using GetTexImage with its | |
| <target> parameter set to TEXTURE_3D_EXT. The assignment of texel | |
| component values to the initial R, G, B, and A components of a pixel | |
| group is described in EXT_texture. Pixel transfer and pixel storage | |
| operations are applied as if the image were 2-dimensional, except that | |
| the additional pixel storage state values PACK_IMAGE_HEIGHT_EXT and | |
| PACK_SKIP_IMAGES_EXT affect the storage of the image into memory. The | |
| correspondence of texels to memory locations is as defined for | |
| TexImage3DEXT above, substituting PACK* state for UNPACK* state in all | |
| occurrences. | |
| Additions to the GLX Specification | |
| None | |
| GLX Protocol | |
| A new GL rendering command is added. This command contains pixel data; | |
| thus it is sent to the server either as part of a glXRender request | |
| or as part of a glXRenderLarge request: | |
| TexImage3DEXT | |
| 2 84+n+p rendering command length | |
| 2 4114 rendering command opcode | |
| 1 BOOL swap_bytes | |
| 1 BOOL lsb_first | |
| 2 unused | |
| 4 CARD32 row_length | |
| 4 CARD32 image_height | |
| 4 CARD32 image_depth | |
| 4 CARD32 skip_rows | |
| 4 CARD32 skip_images | |
| 4 CARD32 skip_volumes | |
| 4 CARD32 skip_pixels | |
| 4 CARD32 alignment | |
| 4 ENUM target | |
| 4 INT32 level | |
| 4 ENUM internalformat | |
| 4 INT32 width | |
| 4 INT32 height | |
| 4 INT32 depth | |
| 4 INT32 size4d | |
| 4 INT32 border | |
| 4 ENUM format | |
| 4 ENUM type | |
| 4 CARD32 null_image | |
| n LISTofBYTE pixels | |
| p unused, p=pad(n) | |
| If the command is encoded in a glXRenderLarge request, the command | |
| opcode and command length fields above are expanded to 4 bytes each: | |
| 4 88+n+p rendering command length | |
| 4 4114 rendering command opcode | |
| If <width> < 0, <height> < 0, <depth> < 0, <format> is invalid or <type> is | |
| invalid, then the command is erroneous and n=0. | |
| <pixels> is arranged as a sequence of adjacent rectangles. Each rectangle is a | |
| 2-dimensional image, whose structure is determined by the image height and the | |
| parameters <swap_bytes>, <lsb_first>, <row_length>, <skip_rows>, <skip_pixels>, | |
| <alignment>, <width>, <format>, and <type> given in the request. If <image_height> | |
| is not positive then the number of rows (i.e., the image height) is <height>; | |
| otherwise the number of rows is <image_height>. | |
| <skip_images> allows a sub-volume of the 3-dimensional image to be selected. | |
| If <skip_images> is positive, then the pointer is advanced by <skip_images> | |
| times the number of elements in one 2-dimensional image. Then <depth> | |
| 2-dimensional images are read, each having a subimage extracted in the | |
| manner described in Appendix A of the GLX Protocol Specification. | |
| Dependencies on EXT_abgr | |
| If EXT_abgr is supported, the <format> parameter of TexImage3DEXT | |
| accepts ABGR_EXT. Otherwise it does not. | |
| Dependencies on EXT_texture | |
| EXT_texture is required. All of the <components> tokens defined by | |
| EXT_texture are accepted by the <internalformat> parameter of | |
| TexImage3DEXT, with the same semantics that are defined by EXT_texture. | |
| The query and error extensions defined by EXT_texture are extended in | |
| this document. | |
| Errors | |
| INVALID_ENUM is generated if <target> is not TEXTURE_3D_EXT or | |
| PROXY_TEXTURE_3D_EXT. | |
| INVALID_ENUM is generated if the <target> parameter to | |
| GetTexParameteriv, GetTexParameterfv or GetTexImage is | |
| PROXY_TEXTURE_3D_EXT. | |
| INVALID_VALUE is generated if <level> is less than zero | |
| INVALID_ENUM is generated if <internalformat> is not ALPHA, RGB, RGBA, | |
| LUMINANCE, LUMINANCE_ALPHA, or one of the tokens defined by the | |
| EXT_texture extension. (Values 1, 2, 3, and 4 are not accepted as | |
| internal formats by TexImage3DEXT). | |
| INVALID_VALUE is generated if <width>, <height>, or <depth> is less than | |
| zero, or cannot be represented as 2**k + 2*border for some integer k. | |
| INVALID_VALUE is generated if <border> is not 0 or 1. | |
| INVALID_ENUM is generated if <format> is not COLOR_INDEX, RED, GREEN, | |
| BLUE, ALPHA, RGB, RGBA, LUMINANCE, or LUMINANCE_ALPHA (or ABGR_EXT if | |
| EXT_abgr is supported). | |
| INVALID_ENUM is generated if <type> is not UNSIGNED_BYTE, BYTE, | |
| UNSIGNED_SHORT, SHORT, UNSIGNED_INT, INT, or FLOAT. | |
| INVALID_OPERATION is generated if TexImage3DEXT is called between | |
| execution of Begin and the corresponding execution of End. | |
| TEXTURE_TOO_LARGE_EXT is generated if the texture as specified cannot be | |
| accommodated by the implementation. This error will not occur if none | |
| of <width>, <height>, or <depth> is greater than MAX_3D_TEXTURE_SIZE_EXT. | |
| New State | |
| Get Value Get Command Type Initial Value Attribute | |
| --------- ----------- ---- ------------- --------- | |
| UNPACK_SKIP_IMAGES_EXT GetIntegerv Z+ 0 - | |
| UNPACK_IMAGE_HEIGHT_EXT GetIntegerv Z+ 0 - | |
| PACK_SKIP_IMAGES_EXT GetIntegerv Z+ 0 - | |
| PACK_IMAGE_HEIGHT_EXT GetIntegerv Z+ 0 - | |
| TEXTURE_3D_EXT IsEnabled B FALSE texture/enable | |
| TEXTURE_WRAP_R_EXT GetTexParameteriv 1 x Z2 REPEAT texture | |
| TEXTURE_DEPTH_EXT GetTexLevelParameteriv 1 x 2 x levels x Z+ 0 - | |
| (old state with new type information) | |
| TEXTURE GetTexImage 3 x 1 x levels x I null - | |
| TEXTURE_RED_SIZE_EXT GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - | |
| TEXTURE_GREEN_SIZE_EXT GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - | |
| TEXTURE_BLUE_SIZE_EXT GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - | |
| TEXTURE_ALPHA_SIZE_EXT GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - | |
| TEXTURE_LUMINANCE_SIZE_EXT GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - | |
| TEXTURE_INTENSITY_SIZE_EXT GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - | |
| TEXTURE_WIDTH GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - | |
| TEXTURE_HEIGHT GetTexLevelParameteriv 2 x 2 x levels x Z+ 0 - | |
| TEXTURE_BORDER GetTexLevelParameteriv 3 x 2 x levels x Z+ 0 - | |
| TEXTURE_COMPONENTS (1D and 2D) GetTexLevelParameteriv 2 x 2 x levels x Z42 1 - | |
| TEXTURE_COMPONENTS (3D) GetTexLevelParameteriv 1 x 2 x levels x Z38 LUMINANCE - | |
| TEXTURE_BORDER_COLOR GetTexParameteriv 3 x C 0, 0, 0, 0 texture | |
| TEXTURE_MIN_FILTER GetTexParameteriv 3 x Z6 NEAREST_MIPMAP_LINEAR texture | |
| TEXTURE_MAG_FILTER GetTexParameteriv 3 x Z2 LINEAR texture | |
| TEXTURE_WRAP_S GetTexParameteriv 3 x Z2 REPEAT texture | |
| TEXTURE_WRAP_T GetTexParameteriv 2 x Z2 REPEAT texture | |
| New Implementation Dependent State | |
| Get Value Get Command Type Minimum Value | |
| --------- ----------- ---- ------------- | |
| MAX_3D_TEXTURE_SIZE_EXT GetIntegerv Z+ 16 |