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