skia / external / github.com / KhronosGroup / OpenGL-Registry / 4a8ee5dd31809d8f1318933804b6842c37a3b644 / . / extensions / EXT / EXT_texture3D.txt

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 |