1Name
2
3    MESA_texture_array
4
5Name Strings
6
7    GL_MESA_texture_array
8
9Contact
10
11    Ian Romanick, IBM (idr 'at' us.ibm.com)
12
13IP Status
14
15    No known IP issues.
16
17Status
18
19    DEPRECATED - Support removed in Mesa 10.1.
20
21Version
22
23
24Number
25
26    TBD
27
28Dependencies
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
41Overview
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
84New 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
91New 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
155Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation)
156
157    None
158
159Additions 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 paragraph (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-dimensional, 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-dimensional 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
565Additions 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
603Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions)
604
605    -- Section 5.4 "Display Lists"
606
607       Change the first paragraph 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
618Additions 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
660Additions to Appendix A of the OpenGL 2.0 Specification (Invariance)
661
662    None
663
664Additions to the AGL/GLX/WGL Specifications
665
666    None
667
668GLX Protocol
669
670    None
671
672Dependencies on ARB_fragment_program
673
674    If ARB_fragment_program is not supported, the changes to section 3.11
675    should be ignored.
676
677Dependencies 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
682Dependencies 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
707Errors
708
709    None
710
711New 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
724New 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
735Issues
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
799Revision 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.||
805