docs/MESA_texture_array.spec

   1 Name
   2
   3     MESA_texture_array
   4
   5 Name Strings
   6
   7     GL_MESA_texture_array
   8
   9 Contact
  10
  11     Ian Romanick, IBM (idr 'at' us.ibm.com)
  12
  13 IP Status
  14
  15     No known IP issues.
  16
  17 Status
  18
  19     Shipping in Mesa 7.1
  20
  21 Version
  22
  23     $Date: 2007/05/16$ $Revision: 0.4$
  24
  25 Number
  26
  27     TBD
  28
  29 Dependencies
  30
  31     OpenGL 1.2 or GL_EXT_texture3D is required.
  32
  33     Support for ARB_fragment_program is assumed, but not required.
  34
  35     Support for ARB_fragment_program_shadow is assumed, but not required.
  36
  37     Support for EXT_framebuffer_object is assumed, but not required.
  38
  39     Written based on the wording of the OpenGL 2.0 specification and
  40     ARB_fragment_program_shadow but not dependent on them.
  41
  42 Overview
  43
  44     There are a number of circumstances where an application may wish to
  45     blend two textures out of a larger set of textures.  Moreover, in some
  46     cases the selected textures may vary on a per-fragment basis within
  47     a polygon.  Several examples include:
  48
  49        1. High dynamic range textures.  The application stores several
  50        different "exposures" of an image as different textures.  On a
  51        per-fragment basis, the application selects which exposures are
  52        used.
  53
  54        2. A terrain engine where the altitude of a point determines the
  55        texture applied to it.  If the transition is from beach sand to
  56        grass to rocks to snow, the application will store each texture
  57        in a different texture map, and dynamically select which two
  58        textures to blend at run-time.
  59
  60        3. Storing short video clips in textures.  Each depth slice is a
  61        single frame of video.
  62
  63     Several solutions to this problem have been proposed, but they either
  64     involve using a separate texture unit for each texture map or using 3D
  65     textures without mipmaps.  Both of these options have major drawbacks.
  66
  67     This extension provides a third alternative that eliminates the major
  68     drawbacks of both previous methods.  A new texture target,
  69     TEXTURE_2D_ARRAY, is added that functions identically to TEXTURE_3D in
  70     all aspects except the sizes of the non-base level images.  In
  71     traditional 3D texturing, the size of the N+1 LOD is half the size
  72     of the N LOD in all three dimensions.  For the TEXTURE_2D_ARRAY target,
  73     the height and width of the N+1 LOD is halved, but the depth is the
  74     same for all levels of detail. The texture then becomes an array of
  75     2D textures.  The per-fragment texel is selected by the R texture
  76     coordinate.
  77
  78     References:
  79
  80         http://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=011557
  81         http://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=000516
  82         http://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=011903
  83         http://www.delphi3d.net/articles/viewarticle.php?article=terraintex.htm
  84
  85 New Procedures and Functions
  86
  87     All functions come directly from EXT_texture_array.
  88
  89     void FramebufferTextureLayerEXT(enum target, enum attachment,
  90                                     uint texture, int level, int layer);
  91
  92 New Tokens
  93
  94     All token names and values come directly from EXT_texture_array.
  95
  96     Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, by
  97     the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and
  98     GetDoublev, and by the <target> parameter of TexImage3D, GetTexImage,
  99     GetTexLevelParameteriv, GetTexLevelParameterfv, GetTexParameteriv, and
 100     GetTexParameterfv:
 101
 102         TEXTURE_1D_ARRAY_EXT                            0x8C18
 103         TEXTURE_2D_ARRAY_EXT                            0x8C1A
 104
 105     Accepted by the <target> parameter of TexImage2D, TexSubImage2D,
 106     CopyTexImage2D, CopyTexSubImage2D, CompressedTexImage2D,
 107     CompressedTexSubImage2D, GetTexLevelParameteriv, and
 108     GetTexLevelParameterfv:
 109
 110         TEXTURE_1D_ARRAY_EXT
 111         PROXY_TEXTURE_1D_ARRAY_EXT                      0x8C19
 112
 113     Accepted by the <target> parameter of TexImage3D, TexSubImage3D,
 114     CopyTexSubImage3D, CompressedTexImage3D, CompressedTexSubImage3D,
 115     GetTexLevelParameteriv, and GetTexLevelParameterfv:
 116
 117         TEXTURE_2D_ARRAY_EXT
 118         PROXY_TEXTURE_2D_ARRAY_EXT                      0x8C1B
 119
 120     Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
 121     GetFloatv, and GetDoublev
 122
 123         TEXTURE_BINDING_1D_ARRAY_EXT                    0x8C1C
 124         TEXTURE_BINDING_2D_ARRAY_EXT                    0x8C1D
 125         MAX_ARRAY_TEXTURE_LAYERS_EXT                    0x88FF
 126
 127     Accepted by the <param> parameter of TexParameterf, TexParameteri,
 128     TexParameterfv, and TexParameteriv when the <pname> parameter is
 129     TEXTURE_COMPARE_MODE_ARB:
 130
 131         COMPARE_REF_DEPTH_TO_TEXTURE_EXT                0x884E
 132
 133     (Note:  COMPARE_REF_DEPTH_TO_TEXTURE_EXT is simply an alias for the
 134     existing COMPARE_R_TO_TEXTURE token in OpenGL 2.0; the alternate name
 135     reflects the fact that the R coordinate is not always used.)
 136
 137     Accepted by the <internalformat> parameter of TexImage3D and
 138     CompressedTexImage3D, and by the <format> parameter of
 139     CompressedTexSubImage3D:
 140
 141         COMPRESSED_RGB_S3TC_DXT1_EXT
 142         COMPRESSED_RGBA_S3TC_DXT1_EXT
 143         COMPRESSED_RGBA_S3TC_DXT3_EXT
 144         COMPRESSED_RGBA_S3TC_DXT5_EXT
 145
 146     Accepted by the <pname> parameter of
 147     GetFramebufferAttachmentParameterivEXT:
 148
 149         FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT          0x8CD4
 150
 151     (Note:  FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER is simply an alias for the
 152     FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_EXT token provided in
 153     EXT_framebuffer_object.  This extension generalizes the notion of
 154     "<zoffset>" to include layers of an array texture.)
 155
 156 Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation)
 157
 158     None
 159
 160 Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization)
 161
 162     -- Section 3.8.1 "Texture Image Specification"
 163
 164        Change the first paragraph (page 150) to say (spec changes identical to
 165        EXT_texture_array):
 166
 167        "The command
 168
 169          void TexImage3D(enum target, int level, int internalformat,
 170                          sizei width, sizei height, sizei depth, int border,
 171                          enum format, enum type, void *data);
 172
 173        is used to specify a three-dimensional texture image. target must be one
 174        one of TEXTURE_3D for a three-dimensional texture or
 175        TEXTURE_2D_ARRAY_EXT for an two-dimensional array texture.
 176        Additionally, target may be either PROXY_TEXTURE_3D for a
 177        three-dimensional proxy texture, or PROXY_TEXTURE_2D_ARRAY_EXT for a
 178        two-dimensional proxy array texture."
 179
 180        Change the fourth paragraph on page 151 to say (spec changes identical
 181        to EXT_texture_array):
 182
 183        "Textures with a base internal format of DEPTH_COMPONENT are supported
 184        by texture image specification commands only if target is TEXTURE_1D,
 185        TEXTURE_2D, TEXTURE_1D_ARRAY_EXT, TEXTURE_2D_ARRAY_EXT,
 186        PROXY_TEXTURE_1D, PROXY_TEXTURE_2D, PROXY_TEXTURE_1D_ARRAY_EXT, or
 187        PROXY_TEXTURE_2D_ARRAY_EXT. Using this format in conjunction with any
 188        other target will result in an INVALID_OPERATION error."
 189
 190
 191        Change the fourth paragraph on page 156 to say (spec changes identical
 192        to EXT_texture_array):
 193
 194        "The command
 195
 196          void TexImage2D(enum target, int level,
 197                          int internalformat, sizei width, sizei height,
 198                          int border, enum format, enum type, void *data);
 199
 200        is used to specify a two-dimensional texture image. target must be one
 201        of TEXTURE_2D for a two-dimensional texture, TEXTURE_1D_ARRAY_EXT for a
 202        one-dimensional array texture, or one of TEXTURE_CUBE_MAP_POSITIVE_X,
 203        TEXTURE_CUBE_MAP_NEGATIVE_X, TEXTURE_CUBE_MAP_POSITIVE_Y,
 204        TEXTURE_CUBE_MAP_NEGATIVE_Y, TEXTURE_CUBE_MAP_POSITIVE_Z, or
 205        TEXTURE_CUBE_MAP_NEGATIVE_Z for a cube map texture. Additionally,
 206        target may be either PROXY_TEXTURE_2D for a two-dimensional proxy
 207        texture, PROXY_TEXTURE_1D_ARRAY_EXT for a one-dimensional proxy array
 208        texture, or PROXY TEXTURE_CUBE_MAP for a cube map proxy texture in the
 209        special case discussed in section 3.8.11.  The other parameters match
 210        the corresponding parameters of TexImage3D.
 211
 212        For the purposes of decoding the texture image, TexImage2D is
 213        equivalent to calling TexImage3D with corresponding arguments and depth
 214        of 1, except that
 215
 216          * The border depth, d_b, is zero, and the depth of the image is
 217            always 1 regardless of the value of border.
 218
 219          * The border height, h_b, is zero if <target> is
 220            TEXTURE_1D_ARRAY_EXT, and <border> otherwise.
 221
 222          * Convolution will be performed on the image (possibly changing its
 223            width and height) if SEPARABLE 2D or CONVOLUTION 2D is enabled.
 224
 225          * UNPACK SKIP IMAGES is ignored."
 226
 227     -- Section 3.8.2 "Alternate Texture Image Specification Commands"
 228
 229        Change the second paragraph (page 159) (spec changes identical
 230        to EXT_texture_array):
 231
 232        "The command
 233
 234          void CopyTexImage2D(enum target, int level,
 235                              enum internalformat, int x, int y, sizei width,
 236                              sizei height, int border);
 237
 238        defines a two-dimensional texture image in exactly the manner of
 239        TexImage2D, except that the image data are taken from the framebuffer
 240        rather than from client memory. Currently, target must be one of
 241        TEXTURE_2D, TEXTURE_1D_ARRAY_EXT, TEXTURE_CUBE_MAP_POSITIVE_X,
 242        TEXTURE_CUBE_MAP_NEGATIVE_X, TEXTURE_CUBE MAP_POSITIVE_Y,
 243        TEXTURE_CUBE_MAP_NEGATIVE_Y, TEXTURE_CUBE_MAP_POSITIVE_Z, or
 244        TEXTURE_CUBE_MAP_NEGATIVE_Z.
 245
 246
 247        Change the last paragraph on page 160 to say (spec changes identical
 248        to EXT_texture_array):
 249
 250        "Currently the target arguments of TexSubImage1D and CopyTexSubImage1D
 251        must be TEXTURE_1D, the target arguments of TexSubImage2D and
 252        CopyTexSubImage2D must be one of TEXTURE_2D, TEXTURE_1D_ARRAY_EXT,
 253        TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_NEGATIVE_X,
 254        TEXTURE_CUBE_MAP_POSITIVE_Y, TEXTURE_CUBE_MAP_NEGATIVE_Y,
 255        TEXTURE_CUBE_MAP_POSITIVE_Z, or TEXTURE_CUBE_MAP_NEGATIVE_Z, and the
 256        target arguments of TexSubImage3D and CopyTexSubImage3D must be
 257        TEXTURE_3D or TEXTURE_2D_ARRAY_EXT. ..."
 258
 259
 260     -- Section 3.8.4 "Texture Parameters"
 261
 262        Change the first paragraph (page 166) to say:
 263
 264        "Various parameters control how the texel array is treated when
 265        specified or changed, and when applied to a fragment. Each parameter is
 266        set by calling
 267
 268          void TexParameter{if}(enum target, enum pname, T param);
 269          void TexParameter{if}v(enum target, enum pname, T params);
 270
 271        target is the target, either TEXTURE_1D, TEXTURE_2D, TEXTURE_3D,
 272        TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or TEXTURE_2D_ARRAY_EXT."
 273
 274
 275     -- Section 3.8.8 "Texture Minification" in the section "Scale Factor and Level of Detail"
 276
 277        Change the first paragraph (page 172) to say:
 278
 279        "Let s(x,y) be the function that associates an s texture coordinate
 280        with each set of window coordinates (x,y) that lie within a primitive;
 281        define t(x,y) and r(x,y) analogously.  Let u(x,y) = w_t * s(x,y),
 282        v(x,y) = h_t * t(x,y), and w(x,y) = d_t * r(x,y), where w_t, h_t,
 283        and d_t are as defined by equations 3.15, 3.16, and 3.17 with
 284        w_s, h_s, and d_s equal to the width, height, and depth of the
 285        image array whose level is level_base.  For a one-dimensional
 286        texture or a one-dimensional array texture, define v(x,y) = 0 and
 287        w(x,y) = 0; for a two-dimensional texture or a two-dimensional array
 288        texture, define w(x,y) = 0..."
 289
 290     -- Section 3.8.8 "Texture Minification" in the section "Mipmapping"
 291
 292        Change the third paragraph (page 174) to say:
 293
 294        "For a two-dimensional texture, two-dimensional array texture, or
 295        cube map texture,"
 296
 297        Change the fourth paragraph (page 174) to say:
 298
 299        "And for a one-dimensional texture or a one-dimensional array texture,"
 300
 301        After the first paragraph (page 175) add:
 302
 303        "For one-dimensional array textures, h_b and d_b are treated as 1,
 304        regardless of the actual values, when performing mipmap calculations.
 305        For two-dimensional array textures, d_b is always treated as one,
 306        regardless of the actual value, when performing mipmap calculations."
 307
 308     -- Section 3.8.8 "Automatic Mipmap Generation" in the section "Mipmapping"
 309
 310        Change the third paragraph (page 176) to say (spec changes identical
 311        to EXT_texture_array):
 312
 313        "The contents of the derived arrays are computed by repeated, filtered
 314        reduction of the level_base array.  For one- and two-dimensional array
 315        textures, each layer is filtered independently.  ..."
 316
 317     -- Section 3.8.8 "Manual Mipmap Generation" in the section "Mipmapping"
 318
 319        Change first paragraph to say (spec changes identical to
 320        EXT_texture_array):
 321
 322        "Mipmaps can be generated manually with the command
 323
 324          void GenerateMipmapEXT(enum target);
 325
 326        where <target> is one of TEXTURE_1D, TEXTURE_2D, TEXTURE_CUBE_MAP,
 327        TEXTURE_3D, TEXTURE_1D_ARRAY, or TEXTURE_2D_ARRAY.  Mipmap generation
 328        affects the texture image attached to <target>.  ..."
 329
 330     -- Section 3.8.10 "Texture Completeness"
 331
 332        Change the second paragaph (page 177) to say (spec changes identical
 333        to EXT_texture_array):
 334
 335        "For one-, two-, or three-dimensional textures and one- or
 336        two-dimensional array textures, a texture is complete if the following
 337        conditions all hold true:"
 338
 339     -- Section 3.8.11 "Texture State and Proxy State"
 340
 341        Change the second and third paragraphs (page 179) to say (spec changes
 342        identical to EXT_texture_array):
 343
 344        "In addition to image arrays for one-, two-, and three-dimensional
 345        textures, one- and two-dimensional array textures, and the six image
 346        arrays for the cube map texture, partially instantiated image arrays
 347        are maintained for one-, two-, and three-dimensional textures and one-
 348        and two-dimensional array textures.  Additionally, a single proxy image
 349        array is maintained for the cube map texture.  Each proxy image array
 350        includes width, height, depth, border width, and internal format state
 351        values, as well as state for the red, green, blue, alpha, luminance,
 352        and intensity component resolutions. Proxy image arrays do not include
 353        image data, nor do they include texture properties. When TexImage3D is
 354        executed with target specified as PROXY_TEXTURE_3D, the
 355        three-dimensional proxy state values of the specified level-of-detail
 356        are recomputed and updated. If the image array would not be supported
 357        by TexImage3D called with target set to TEXTURE 3D, no error is
 358        generated, but the proxy width, height, depth, border width, and
 359        component resolutions are set to zero. If the image array would be
 360        supported by such a call to TexImage3D, the proxy state values are set
 361        exactly as though the actual image array were being specified. No pixel
 362        data are transferred or processed in either case.
 363
 364        Proxy arrays for one- and two-dimensional textures and one- and
 365        two-dimensional array textures are operated on in the same way when
 366        TexImage1D is executed with target specified as PROXY_TEXTURE_1D,
 367        TexImage2D is executed with target specified as PROXY_TEXTURE_2D or
 368        PROXY_TEXTURE_1D_ARRAY_EXT, or TexImage3D is executed with target
 369        specified as PROXY_TETXURE_2D_ARRAY_EXT."
 370
 371     -- Section 3.8.12 "Texture Objects"
 372
 373        Change section (page 180) to say (spec changes identical to
 374        EXT_texture_array):
 375
 376        "In addition to the default textures TEXTURE_1D, TEXTURE_2D,
 377        TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, and TEXTURE_2D_EXT,
 378        named one-, two-, and three-dimensional, cube map, and one- and
 379        two-dimensional array texture objects can be created and operated upon.
 380        The name space for texture objects is the unsigned integers, with zero
 381        reserved by the GL.
 382
 383        A texture object is created by binding an unused name to TEXTURE_1D,
 384        TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or
 385        TEXTURE_2D_ARRAY_EXT. The binding is effected by calling
 386
 387          void BindTexture(enum target, uint texture);
 388
 389        with <target> set to the desired texture target and <texture> set to
 390        the unused name.  The resulting texture object is a new state vector,
 391        comprising all the state values listed in section 3.8.11, set to the
 392        same initial values. If the new texture object is bound to TEXTURE_1D,
 393        TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or
 394        TEXTURE_2D_ARRAY_EXT, it is and remains a one-, two-,
 395        three-dimensional, cube map, one- or two-dimensional array texture
 396        respectively until it is deleted.
 397
 398        BindTexture may also be used to bind an existing texture object to
 399        either TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP,
 400        TEXTURE_1D_ARRAY_EXT, or TEXTURE_2D_ARRAY_EXT. The error
 401        INVALID_OPERATION is generated if an attempt is made to bind a texture
 402        object of different dimensionality than the specified target. If the
 403        bind is successful no change is made to the state of the bound texture
 404        object, and any previous binding to target is broken.
 405
 406        While a texture object is bound, GL operations on the target to which
 407        it is bound affect the bound object, and queries of the target to which
 408        it is bound return state from the bound object. If texture mapping of
 409        the dimensionality of the target to which a texture object is bound is
 410        enabled, the state of the bound texture object directs the texturing
 411        operation.
 412
 413        In the initial state, TEXTURE_1D, TEXTURE_2D, TEXTURE_3D,
 414        TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, and TEXTURE_2D_ARRAY_EXT have
 415        one-, two-, three-dimensional, cube map, and one- and two-dimensional
 416        array texture state vectors respectively associated with them. In order
 417        that access to these initial textures not be lost, they are treated as
 418        texture objects all of whose names are 0. The initial one-, two-,
 419        three-dimensional, cube map, one- and two-dimensional array textures
 420        are therefore operated upon, queried, and applied as TEXTURE_1D,
 421        TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, and
 422        TEXTURE_2D_ARRAY_EXT respectively while 0 is bound to the corresponding
 423        targets.
 424
 425        Change second paragraph on page 181 to say (spec changes identical to
 426        EXT_texture_array):
 427
 428        "...  If a texture that is currently bound to one of the targets
 429        TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP,
 430        TEXTURE_1D_ARRAY_EXT, or TEXTURE_2D_ARRAY_EXT is deleted, it is as
 431        though BindTexture had been executed with the same target and texture
 432        zero. ..."
 433
 434        Change second paragraph on page 182 to say (spec changes identical to
 435        EXT_texture_array):
 436
 437        "The texture object name space, including the initial one-, two-, and
 438        three dimensional, cube map, and one- and two-dimensional array texture
 439        objects, is shared among all texture units. ..."
 440
 441
 442     -- Section 3.8.14 "Depth Texture Comparison Modes" in "Texture Comparison Modes"
 443
 444        Change second through fourth paragraphs (page 188) to say:
 445
 446        "Let D_t be the depth texture value, in the range [0, 1].  For
 447        texture lookups from one- and two-dimesional, rectangle, and
 448        one-dimensional array targets, let R be the interpolated <r>
 449        texture coordinate, clamped to the range [0, 1].  For texture lookups
 450        from two-dimesional array texture targets, let R be the interpolated
 451        <q> texture coordinate, clamped to the range [0, 1].  Then the
 452        effective texture value L_t, I_t, or A_t is computed as follows:
 453
 454        If the value of TEXTURE_COMPARE_MODE is NONE, then
 455
 456           r = Dt
 457
 458        If the value of TEXTURE_COMPARE_MODE is
 459        COMPARE_REF_DEPTH_TO_TEXTURE_EXT), then r depends on the texture
 460        comparison function as shown in table 3.27."
 461
 462     -- Section 3.8.15 "Texture Application"
 463
 464        Change the first paragraph (page 189) to say:
 465
 466        "Texturing is enabled or disabled using the generic Enable and Disable
 467        commands, respectively, with the symbolic constants TEXTURE_1D,
 468        TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or
 469        TEXTURE_2D_ARRAY_EXT to enable one-, two-, three-dimensional, cube
 470        map, one-dimensional array, or two-dimensional array texture,
 471        respectively.  If both two- and one-dimensional textures are enabled,
 472        the two-dimensional texture is used.  If the three-dimensional and
 473        either of the two- or one-dimensional textures is enabled, the
 474        three-dimensional texture is used.  If the cube map texture and any of
 475        the three-, two-, or one-dimensional textures is enabled, then cube map
 476        texturing is used.  If one-dimensional array texture is enabled and any
 477        of cube map, three-, two-, or one-dimensional textures is enabled,
 478        one-dimensional array texturing is used.  If two-dimensional array
 479        texture is enabled and any of cube map, three-, two-, one-dimensional
 480        textures or one-dimensional array texture is enabled, two-dimensional
 481        array texturing is used..."
 482
 483     -- Section 3.11.2 of ARB_fragment_program (Fragment Program Grammar and Restrictions):
 484
 485        (mostly add to existing grammar rules)
 486
 487        <optionName>           ::= "MESA_texture_array"
 488
 489        <texTarget>            ::= "1D"
 490                                | "2D"
 491                                | "3D"
 492                                | "CUBE"
 493                                | "RECT"
 494                                | <arrayTarget> (if program option is present)
 495                                | <shadowTarget> (if program option is present)
 496
 497        <arrayTarget>          ::= "ARRAY1D"
 498                                | "ARRAY2D"
 499
 500        <shadowTarget>         ::= "SHADOW1D"
 501                                | "SHADOW2D"
 502                                | "SHADOWRECT"
 503                                | <shadowArrayTarget> (if program option is present)
 504
 505        <shadowArrayTarget>    ::= "SHADOWARRAY1D"
 506                                | "SHADOWARRAY2D"
 507
 508
 509     -- Add Section 3.11.4.5.4 "Texture Stack Option"
 510
 511        "If a fragment program specifies the "MESA_texture_array" program
 512        option, the <texTarget> rule is modified to add the texture targets
 513        ARRAY1D and ARRAY2D (See Section 3.11.2)."
 514
 515     -- Section 3.11.6 "Fragment Program Texture Instruction Set"
 516
 517        (replace 1st and 2nd paragraphs with the following paragraphs)
 518
 519        "The first three texture instructions described below specify the
 520        mapping of 4-tuple input vectors to 4-tuple output vectors.
 521        The sampling of the texture works as described in section 3.8,
 522        except that texture environments and texture functions are not
 523        applicable, and the texture enables hierarchy is replaced by explicit
 524        references to the desired texture target (i.e., 1D, 2D, 3D, cube map,
 525        rectangle, ARRAY1D, ARRAY2D).  These texture instructions specify
 526        how the 4-tuple is mapped into the coordinates used for sampling.  The
 527        following function is used to describe the texture sampling in the
 528        descriptions below:
 529
 530          vec4 TextureSample(vec4 coord, float lodBias, int texImageUnit,
 531                             enum texTarget);
 532
 533        Note that not all four components of the texture coordinates <coord>
 534        are used by all texture targets.  Component usage for each <texTarget>
 535        is defined in table X.
 536
 537                                                         coordinates used
 538          texTarget          Texture Type               s t r  layer  shadow
 539          ----------------   ---------------------      -----  -----  ------
 540          1D                 TEXTURE_1D                 x - -    -      -
 541          2D                 TEXTURE_2D                 x y -    -      -
 542          3D                 TEXTURE_3D                 x y z    -      -
 543          CUBE               TEXTURE_CUBE_MAP           x y z    -      -
 544          RECT               TEXTURE_RECTANGLE_ARB      x y -    -      -
 545          ARRAY1D            TEXTURE_1D_ARRAY_EXT       x - -    y      -
 546          ARRAY2D            TEXTURE_2D_ARRAY_EXT       x y -    z      -
 547          SHADOW1D           TEXTURE_1D                 x - -    -      z
 548          SHADOW2D           TEXTURE_2D                 x y -    -      z
 549          SHADOWRECT         TEXTURE_RECTANGLE_ARB      x y -    -      z
 550          SHADOWARRAY1D      TEXTURE_1D_ARRAY_EXT       x - -    y      z
 551          SHADOWARRAY2D      TEXTURE_2D_ARRAY_EXT       x y -    z      w
 552
 553          Table X:  Texture types accessed for each of the <texTarget>, and
 554          coordinate mappings.  The "coordinates used" column indicate the
 555          input values used for each coordinate of the texture lookup, the
 556          layer selector for array textures, and the reference value for
 557          texture comparisons."
 558
 559     -- Section 3.11.6.2 "TXP: Project coordinate and map to color"
 560
 561        Add to the end of the section:
 562
 563        "A program will fail to load if the TXP instruction is used in
 564        conjunction with the SHADOWARRAY2D target."
 565
 566 Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment Operations)
 567
 568     -- Section 4.4.2.3 "Attaching Texture Images to a Framebuffer"
 569
 570        Add to the end of the section (spec changes identical to
 571        EXT_texture_array):
 572
 573        "The command
 574
 575          void FramebufferTextureLayerEXT(enum target, enum attachment,
 576                                          uint texture, int level, int layer);
 577
 578        operates identically to FramebufferTexture3DEXT, except that it
 579        attaches a single layer of a three-dimensional texture or a one- or
 580        two-dimensional array texture.  <layer> is an integer indicating the
 581        layer number, and is treated identically to the <zoffset> parameter in
 582        FramebufferTexture3DEXT.  The error INVALID_VALUE is generated if
 583        <layer> is negative.  The error INVALID_OPERATION is generated if
 584        <texture> is non-zero and is not the name of a three dimensional
 585        texture or one- or two-dimensional array texture.  Unlike
 586        FramebufferTexture3D, no <textarget> parameter is accepted.
 587
 588        If <texture> is non-zero and the command does not result in an error,
 589        the framebuffer attachment state corresponding to <attachment> is
 590        updated as in the other FramebufferTexture commands, except that
 591        FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT is set to <layer>."
 592
 593     -- Section 4.4.4.1 "Framebuffer Attachment Completeness"
 594
 595       Add to the end of the list of completeness rules (spec changes
 596       identical to EXT_texture_array):
 597
 598         "* If FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is TEXTURE and
 599            FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT names a one- or
 600            two-dimensional array texture, then
 601            FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT must be smaller than the
 602            number of layers in the texture."
 603
 604 Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions)
 605
 606     -- Section 5.4 "Display Lists"
 607
 608        Change the first paragraphi on page 242 to say (spec changes
 609        identical to EXT_texture_array):
 610
 611        "TexImage3D, TexImage2D, TexImage1D, Histogram, and ColorTable are
 612        executed immediately when called with the corresponding proxy arguments
 613        PROXY_TEXTURE_3D or PROXY_TEXTURE_2D_ARRAY_EXT; PROXY_TEXTURE_2D,
 614        PROXY_TEXTURE_CUBE_MAP, or PROXY_TEXTURE_1D_ARRAY_EXT;
 615        PROXY_TEXTURE_1D; PROXY_HISTOGRAM; and PROXY_COLOR_TABLE,
 616        PROXY_POST_CONVOLUTION_COLOR_TABLE, or
 617        PROXY_POST_COLOR_MATRIX_COLOR_TABLE."
 618
 619 Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State Requests)
 620
 621     -- Section 6.1.3 "Enumerated Queries"
 622
 623        Add after the line beginning "If the value of
 624        FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is TEXTURE" (spec changes
 625        identical to EXT_texture_array):
 626
 627        "If <pname> is FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT and the
 628        texture object named FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT is a
 629        three-dimensional texture or a one- or two-dimensional array texture,
 630        then <params> will contain the number of texture layer attached to the
 631        attachment point.  Otherwise, <params> will contain the value zero."
 632
 633     -- Section 6.1.4 "Texture Queries"
 634
 635        Change the first three paragraphs (page 248) to say (spec changes
 636        identical to EXT_texture_array):
 637
 638        "The command
 639
 640          void GetTexImage(enum tex, int lod, enum format,
 641                           enum type, void *img);
 642
 643        is used to obtain texture images. It is somewhat different from the
 644        other get commands; tex is a symbolic value indicating which texture
 645        (or texture face in the case of a cube map texture target name) is to
 646        be obtained.  TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_1D_ARRAY_EXT,
 647        and TEXTURE_2D_ARRAY_EXT indicate a one-, two-, or three-dimensional
 648        texture, or one- or two-dimensional array texture, respectively.
 649        TEXTURE_CUBE_MAP_POSITIVE_X, ...
 650
 651        GetTexImage obtains... from the first image to the last for
 652        three-dimensional textures.  One- and two-dimensional array textures
 653        are treated as two- and three-dimensional images, respectively, where
 654        the layers are treated as rows or images.  These groups are then...
 655
 656        For three-dimensional and two-dimensional array textures, pixel storage
 657        operations are applied as if the image were two-dimensional, except
 658        that the additional pixel storage state values PACK_IMAGE_HEIGHT and
 659        PACK_SKIP_IMAGES are applied. ..."
 660
 661 Additions to Appendix A of the OpenGL 2.0 Specification (Invariance)
 662
 663     None
 664
 665 Additions to the AGL/GLX/WGL Specifications
 666
 667     None
 668
 669 GLX Protocol
 670
 671     None
 672
 673 Dependencies on ARB_fragment_program
 674
 675     If ARB_fragment_program is not supported, the changes to section 3.11
 676     should be ignored.
 677
 678 Dependencies on EXT_framebuffer_object
 679
 680     If EXT_framebuffer_object is not supported, the changes to section
 681     3.8.8 ("Manual Mipmap Generation"), 4.4.2.3, and 6.1.3 should be ignored.
 682
 683 Dependencies on EXT_texture_compression_s3tc and NV_texture_compression_vtc
 684
 685     (Identical dependency as EXT_texture_array.)
 686
 687     S3TC texture compression is supported for two-dimensional array textures.
 688     When <target> is TEXTURE_2D_ARRAY_EXT, each layer is stored independently
 689     as a compressed two-dimensional textures.  When specifying or querying
 690     compressed images using one of the S3TC formats, the images are provided
 691     and/or returned as a series of two-dimensional textures stored
 692     consecutively in memory, with the layer closest to zero specified first.
 693     For array textures, images are not arranged in 4x4x4 or 4x4x2 blocks as in
 694     the three-dimensional compression format provided in the
 695     EXT_texture_compression_vtc extension.  Pixel store parameters, including
 696     those specific to three-dimensional images, are ignored when compressed
 697     image data are provided or returned, as in the
 698     EXT_texture_compression_s3tc extension.
 699
 700     S3TC compression is not supported for one-dimensional texture targets in
 701     EXT_texture_compression_s3tc, and is not supported for one-dimensional
 702     array textures in this extension.  If compressed one-dimensional arrays
 703     are needed, use a two-dimensional texture with a height of one.
 704
 705     This extension allows the use of the four S3TC internal format types in
 706     TexImage3D, CompressedTexImage3D, and CompressedTexSubImage3D calls.
 707
 708 Errors
 709
 710     None
 711
 712 New State
 713
 714     (add to table 6.15, p. 276)
 715
 716                                                      Initial
 717     Get Value                     Type   Get Command  Value Description           Sec.    Attribute
 718     ----------------------------  -----  -----------  ----- --------------------  ------  ---------
 719     TEXTURE_BINDING_1D_ARRAY_EXT  2*xZ+  GetIntegerv    0   texture object bound  3.8.12  texture
 720                                                             to TEXTURE_1D_ARRAY
 721     TEXTURE_BINDING_2D_ARRAY_EXT  2*xZ+  GetIntegerv    0   texture object bound  3.8.12  texture
 722                                                             to TEXTURE_2D_ARRAY
 723
 724
 725 New Implementation Dependent State
 726
 727     (add to Table 6.32, p. 293)
 728
 729                                                     Minimum
 730     Get Value                     Type  Get Command  Value  Description         Sec.  Attribute
 731     ----------------------------  ----  ----------- ------- ------------------  ----- ---------
 732     MAX_TEXTURE_ARRAY_LAYERS_EXT   Z+   GetIntegerv   64    maximum number of   3.8.1     -
 733                                                             layers for texture
 734                                                             arrays
 735
 736 Issues
 737
 738     (1) Is "texture stack" a good name for this functionality?
 739
 740         NO.  The name is changed to "array texture" to match the
 741         nomenclature used by GL_EXT_texture_array.
 742
 743     (2) Should the R texture coordinate be treated as normalized or
 744     un-normalized?  If it were un-normalized, floor(R) could be thought
 745     of as a direct index into the array texture.  This may be more
 746     convenient for applications.
 747
 748         RESOLVED.  All texture coordinates are normalized.  The issue of
 749         un-normalized texture coordinates has been discussed in the ARB
 750         before and should be left for a layered extension.
 751
 752         RE-RESOLVED.  The R coordinate is un-normalized.  Accessing an array
 753         using [0, layers-1] coordinates is much more natural.
 754
 755     (3) How does LOD selection work for stacked textures?
 756
 757         RESOLVED.  For 2D array textures the R coordinate is ignored, and
 758         the LOD selection equations for 2D textures are used.  For 1D
 759         array textures the T coordinate is ignored, and the LOD selection
 760         equations for 1D textures are used.  The expected usage is in a
 761         fragment program with an explicit LOD selection.
 762
 763     (4) What is the maximum size of a 2D array texture?  Is it the same
 764     as for a 3D texture, or should a new query be added?  How about for 1D
 765     array textures?
 766
 767         RESOLVED.  A new query is added.
 768
 769     (5) How are array textures exposed in GLSL?
 770
 771         RESOLVED.  Use GL_EXT_texture_array.
 772
 773     (6) Should a 1D array texture also be exposed?
 774
 775         RESOLVED.  For orthogonality, yes.
 776
 777     (7) How are stacked textures attached to framebuffer objects?
 778
 779         RESOLVED.  Layers of both one- and two-dimensional array textures
 780         are attached using FreambufferTextureLayerEXT.  Once attached, the
 781         array texture layer behaves exactly as either a one- or
 782         two-dimensional texture.
 783
 784     (8) How is this extension related to GL_EXT_texture_array?
 785
 786         This extension adapats GL_MESAX_texture_stack to the notation,
 787         indexing, and FBO access of GL_EXT_texture_array.  This extension
 788         replaces the GLSL support of GL_EXT_texture_array with
 789         GL_ARB_fragment_program support.
 790
 791         Assembly program support is also provided by GL_NV_gpu_program4.
 792         GL_NV_gpu_program4 also adds support for other features that are
 793         specific to Nvidia hardware, while this extension adds only support
 794         for array textures.
 795
 796         Much of text of this extension that has changed since
 797         GL_MESAX_texture_stack comes directly from either
 798         GL_EXT_texture_array or GL_NV_gpu_program4.
 799
 800 Revision History
 801
 802     ||2005/11/15||0.1||idr||Initial draft MESAX version.||
 803     ||2005/12/07||0.2||idr||Added framebuffer object interactions.||
 804     ||2005/12/12||0.3||idr||Updated fragment program interactions.||
 805     ||2007/05/16||0.4||idr||Converted to MESA_texture_array.  Brought in line with EXT_texture_array and NV_gpu_program4.||