• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    ARB_sparse_texture
4
5Name Strings
6
7    GL_ARB_sparse_texture
8
9Contributors
10
11    Graham Sellers, AMD
12    Pierre Boudier, AMD
13    Juraj Obert, AMD
14    Jeff Bolz, NVIDIA
15    Pat Brown, NVIDIA
16    ... +others TBD
17
18Contact
19
20    Graham Sellers, AMD (graham.sellers 'at' amd.com)
21
22Notice
23
24    Copyright (c) 2013 The Khronos Group Inc. Copyright terms at
25        http://www.khronos.org/registry/speccopyright.html
26
27Specification Update Policy
28
29    Khronos-approved extension specifications are updated in response to
30    issues and bugs prioritized by the Khronos OpenGL Working Group. For
31    extensions which have been promoted to a core Specification, fixes will
32    first appear in the latest version of that core Specification, and will
33    eventually be backported to the extension document. This policy is
34    described in more detail at
35        https://www.khronos.org/registry/OpenGL/docs/update_policy.php
36
37Status
38
39    Complete. Approved by the ARB on June 3, 2013.
40    Ratified by the Khronos Board of Promoters on July 19, 2013.
41
42Version
43
44    Last Modified Date:         05/11/2017
45    Revision:                   12
46
47Number
48
49    ARB Extension #158
50
51Dependencies
52
53    OpenGL 1.1 is required.
54
55    This extension is written against the OpenGL 4.3 (Core) Specification,
56    February 14, 2013.
57
58    The definition of this extension depends on GL_EXT_direct_state_access
59    and GL_ARB_direct_state_access.
60
61Overview
62
63    Recent advances in application complexity and a desire for higher
64    resolutions have pushed texture sizes up considerably. Often, the amount
65    of physical memory available to a graphics processor is a limiting factor
66    in the performance of texture-heavy applications. Once the available
67    physical memory is exhausted, paging may occur bringing performance down
68    considerably - or worse, the application may fail. Nevertheless, the amount
69    of address space available to the graphics processor has increased to the
70    point where many gigabytes - or even terabytes of address space may be
71    usable even though that amount of physical memory is not present.
72
73    This extension allows the separation of the graphics processor's address
74    space (reservation) from the requirement that all textures must be
75    physically backed (commitment). This exposes a limited form of
76    virtualization for textures. Use cases include sparse (or partially
77    resident) textures, texture paging, on-demand and delayed loading of
78    texture assets and application controlled level of detail.
79
80New Procedures and Functions
81
82        void TexPageCommitmentARB(enum target,
83                                  int level,
84                                  int xoffset,
85                                  int yoffset,
86                                  int zoffset,
87                                  sizei width,
88                                  sizei height,
89                                  sizei depth,
90                                  boolean commit);
91
92        void TexturePageCommitmentEXT(uint texture,
93                                      int level,
94                                      int xoffset,
95                                      int yoffset,
96                                      int zoffset,
97                                      sizei width,
98                                      sizei height,
99                                      sizei depth,
100                                      boolean commit);
101
102        [[ Note: TexturePageCommitmentEXT is supported if and only if
103           the EXT_direct_state_access or the ARB_direct_state_access extension
104           is supported. ]]
105
106New Tokens
107
108    Accepted by the <pname> parameter to TexParameter{i f}{v},
109    TexParameterI{u}v, GetTexParameter{if}v and GetTexParameterIi{u}v:
110
111        TEXTURE_SPARSE_ARB                          0x91A6
112        VIRTUAL_PAGE_SIZE_INDEX_ARB                 0x91A7
113
114    Accepted by the <pname> parameter of GetTexParameter{if}v and
115    GetTexParameterIi{u}v:
116
117        NUM_SPARSE_LEVELS_ARB                       0x91AA
118
119    Accepted by the <pname> parameter to GetInternalformativ:
120
121        NUM_VIRTUAL_PAGE_SIZES_ARB                  0x91A8
122
123        VIRTUAL_PAGE_SIZE_X_ARB                     0x9195
124        VIRTUAL_PAGE_SIZE_Y_ARB                     0x9196
125        VIRTUAL_PAGE_SIZE_Z_ARB                     0x9197
126
127    Accepted by the <pname> parameter to GetIntegerv, GetFloatv, GetDoublev,
128    GetInteger64v, and GetBooleanv:
129
130        MAX_SPARSE_TEXTURE_SIZE_ARB                 0x9198
131        MAX_SPARSE_3D_TEXTURE_SIZE_ARB              0x9199
132        MAX_SPARSE_ARRAY_TEXTURE_LAYERS_ARB         0x919A
133        SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB  0x91A9
134
135Additions to Chapter 8 of the OpenGL 4.3 (Core) Specification (Textures and
136Samplers)
137
138    Add the "Supports Sparse Allocation" column to Table 8.12, "Sized internal
139    color formats"
140
141        +-------------------------------+-------------------------------+
142        | Sized Internal Format         | Supports Sparse Allocation    |
143        +-------------------------------+-------------------------------+
144        | R8                            | Y                             |
145        | R8_SNORM                      | Y                             |
146        | R16                           | Y                             |
147        | R16_SNORM                     | Y                             |
148        | RG8                           | Y                             |
149        | RG8_SNORM                     | Y                             |
150        | RG16                          | Y                             |
151        | RG16_SNORM                    | Y                             |
152        | R3_G3_B2                      |                               |
153        | RGB4                          |                               |
154        | RGB8                          |                               |
155        | RGB565                        | Y                             |
156        | RGB8                          |                               |
157        | RGB8_SNORM                    |                               |
158        | RGB10                         |                               |
159        | RGB12                         |                               |
160        | RGB16                         |                               |
161        | RGB16_SNORM                   |                               |
162        | RGBA2                         |                               |
163        | RGBA4                         |                               |
164        | RGB5_A1                       |                               |
165        | RGBA8                         | Y                             |
166        | RGBA8_SNORM                   | Y                             |
167        | RGB10_A2                      | Y                             |
168        | RGB10_A2UI                    | Y                             |
169        | RGBA12                        |                               |
170        | RGBA16                        | Y                             |
171        | RGBA16_SNORM                  | Y                             |
172        | SRGB8                         |                               |
173        | SRGB8_ALPHA8                  |                               |
174        | R16F                          | Y                             |
175        | RG16F                         | Y                             |
176        | RGB16F                        |                               |
177        | RGBA16F                       | Y                             |
178        | R32F                          | Y                             |
179        | RG32F                         | Y                             |
180        | RGB32F                        |                               |
181        | RGBA32F                       | Y                             |
182        | R11F_G11F_B10F                | Y                             |
183        | RGB9_E5                       | Y                             |
184        | R8I                           | Y                             |
185        | R8UI                          | Y                             |
186        | R16I                          | Y                             |
187        | R16UI                         | Y                             |
188        | R32I                          | Y                             |
189        | R32UI                         | Y                             |
190        | RG8I                          | Y                             |
191        | RG8UI                         | Y                             |
192        | RG16I                         | Y                             |
193        | RG16UI                        | Y                             |
194        | RG32I                         | Y                             |
195        | RG32UI                        | Y                             |
196        | RGB8I                         |                               |
197        | RGB8UI                        |                               |
198        | RGB16I                        |                               |
199        | RGB16UI                       |                               |
200        | RGB32I                        |                               |
201        | RGB32UI                       |                               |
202        | RGBA8I                        | Y                             |
203        | RGBA8UI                       | Y                             |
204        | RGBA16I                       | Y                             |
205        | RGBA16UI                      | Y                             |
206        | RGBA32I                       | Y                             |
207        | RGBA32UI                      | Y                             |
208        +-------------------------------+-------------------------------+
209
210    Insert the following paragraph before Table 8.16:
211
212        If <pname> is TEXTURE_SPARSE_ARB or VIRTUAL_PAGE_SIZE_INDEX_ARB, then
213    the state is stored in the texture, but only takes effect the next time
214    storage is allocated for a texture using TexStorage*. If the value of
215    TEXTURE_IMMUTABLE_FORMAT is TRUE, then TEXTURE_SPARSE_ARB and
216    VIRTUAL_PAGE_SIZE_INDEX_ARB cannot be changed and an error is generated.
217
218    Append to Table 8.16: "Texture parameters and their values."
219
220      +------------------------------+---------+---------------------------+
221      | Name                         | Type    | Legal values              |
222      +------------------------------+---------+---------------------------+
223      | TEXTURE_SPARSE_ARB           | boolean | TRUE, FALSE               |
224      | VIRTUAL_PAGE_SIZE_INDEX_ARB  | int     | any non-negative integer  |
225      +------------------------------+---------+---------------------------+
226
227    Add to the Errors table for TexParameter*
228
229        INVALID_OPERATION is generated if <pname> is TEXTURE_SPARSE_ARB or
230    VIRTUAL_PAGE_SIZE_INDEX_ARB and the value of TEXTURE_IMMUTABLE_FORMAT for
231    the texture identified by <target> is TRUE.
232
233        INVALID_VALUE is generated if <pname> is TEXTURE_SPARSE_ARB, <pname>
234    is TRUE and <target> is not one of TEXTURE_2D, TEXTURE_2D_ARRAY,
235    TEXTURE_CUBE_MAP, TEXTURE_CUBE_MAP_ARRAY, TEXTURE_3D, or
236    TEXTURE_RECTANGLE.
237
238    Additions to Section 8.18 of the OpenGL Specification, "Texture Views"
239
240        Texture views may be created that reference sparse textures (see
241    Section 8.20.1), and in such cases, the view is considered to be sparse.
242    Should a texture view reference part or all of the tail of a sparse
243    texture, then modifications to the commitment of that tail via the view
244    affect the tail of the parent texture and all other views that reference
245    the tail, even for portions of the tail outside the controling view.
246
247    Additions to Section 8.19 of the OpenGL Specification, "Immutable-Format
248    Texture Images"
249
250    Add the following bullet point to the list of psuedo-operations performed
251    by all variants of TexStorage* (p.233):
252
253        * If TEXTURE_SPARSE_ARB is TRUE, only virtual address space is
254          allocated for the texture but physical backing store is not.
255          Physical store for pages of a virtual texture may be committed and
256          decommitted by calling TexPageCommitmentARB. The page size chosen
257          for the texture is taken from the texture's value of
258          VIRTUAL_PAGE_SIZE_INDEX_ARB. In this case, <width>, <height> and
259          <depth> must either be integer multiples of the selected virtual
260          page size in the X, Y and Z dimensions, respectively, or be less
261          than those dimensions. Additionally, the dimensions of sparse
262          textures must be compatible with the chosen value of
263          <internalFormat> as described in Section 8.20.1.
264
265    Add to the errors that may be generated by TexStorage*:
266
267        An INVALID_OPERATION error is generated if the texture's
268        TEXTURE_SPARSE_ARB parameter is TRUE and the value of its
269        VIRTUAL_PAGE_SIZE_INDEX_ARB parameter is greater than or equal to
270        NUM_VIRTUAL_PAGE_SIZES_ARB for the specified target and internal
271        format.
272
273        An INVALID_VALUE error is generated if the texture's TEXTURE_SPARSE_ARB
274        parameter is TRUE and any of the following are true:
275
276          * <target> is TEXTURE_3D, and <width>, <height>, or <depth>
277            is greater than MAX_SPARSE_3D_TEXTURE_SIZE_ARB;
278
279          * <target> is not TEXTURE_3D, and <width> or <height> is greater
280            than MAX_SPARSE_TEXTURE_SIZE_ARB; or
281
282          * <target> is TEXTURE_2D_ARRAY or TEXTURE_CUBE_MAP_ARRAY and
283            <depth> is greater than MAX_SPARSE_TEXTURE_ARRAY_LAYERS_ARB.
284
285        An INVALID_VALUE error is generated if the texture's
286        TEXTURE_SPARSE_ARB parameter is TRUE and <width> or <height> is greater
287        than the value of MAX_SPARSE_3D_TEXTURE_SIZE_ARB when <target> is
288        TEXTURE_3D, or if <height> or <depth> is greater than the value of
289        MAX_SPARSE_ARRAY_TEXTURE_LAYERS_ARB if <target> is a 1D or 2D array
290        texture target, respectively.
291
292        An INVALID_VALUE error is generated if TEXTURE_SPARSE_ARB is TRUE and
293        <width>, <height> or <depth> is is not an integer multiple of the
294        page size in the corresponding dimension.
295
296        If the value of SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB is FALSE,
297        then TexStorage* will generate an INVALID_OPERATION error if
298
299          * the texture's TEXTURE_SPARSE_ARB parameter is TRUE,
300
301          * <target> is one of TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY,
302            TEXTURE_CUBE_MAP, or TEXTURE_CUBE_MAP_ARRAY, and
303
304          * for the virtual page size corresponding to the
305            VIRTUAL_PAGE_SIZE_INDEX_ARB parameter, either of the following is
306            true:
307
308              - <width> is not a multiple of VIRTUAL_PAGE_SIZE_X_ARB *
309                 2^(<levels>-1), or
310
311              - <height> is not a multiple of VIRTUAL_PAGE_SIZE_Y_ARB *
312                 2^(<levels>-1).
313
314    Insert Section 8.20, "Sparse Textures and Commitment" (p.238), renumber
315    subsequent sections.
316
317        Textures may be allocated such that their images' physical backing
318    store is only partially allocated. Only immutable format textures may
319    be sparsely allocated. To allocate a sparse texture, set a texture's
320    TEXTURE_SPARSE_ARB parameter to TRUE before allocating storage for it
321    with TexStorage*.
322
323    Insert Subsection 8.20.1, "Allocation of and Access to Sparse Textures"
324
325        Sparse textures are allocated setting a texture's TEXTURE_SPARSE_ARB
326    parameter to TRUE and then issuing one of the TexStorage* commands.
327    The dimensions of a sparse texture must be compatible with the internal
328    format chosen for the texture. Each internal format has zero or more
329    sparse page sizes that may be selected. The number of available page sizes
330    for an internal format and the dimensions of the pages may be determined
331    by calling GetInternalFormat* with the <pname> NUM_VIRTUAL_PAGE_SIZES_ARB
332    (for the number of available page sizes), VIRTUAL_PAGE_SIZE_X_ARB,
333    VIRTUAL_PAGE_SIZE_Y_ARB or VIRTUAL_PAGE_SIZE_Z_ARB (for the virtual
334    page widths, heights and depths, respectively). Not all internal formats
335    support sparse allocation. For those formats, the value of
336    NUM_VIRTUAL_PAGE_SIZES_ARB will be zero. The internal formats which are
337    guaranteed to support sparse allocation is listed in Table 8.12. Formats
338    not listed as supported in Table 8.12 may still be supported by some
339    implementations.
340
341        The VIRTUAL_PAGE_SIZE_INDEX_ARB may be used to select the page layout for
342    a sparse texture. The value of the texture's VIRTUAL_PAGE_SIZE_INDEX_ARB
343    parameter is treated as an index into the array of possible page sizes
344    for the type and requested internal format of the texture, and matches
345    index of the array of values returned for the VIRTUAL_PAGE_SIZE_{XYZ}_ARB
346    internal format query.
347
348        When a sparsely committed texture is accessed by the GL, accesses that
349    require only samples contained in committed regions complete as normal.
350    For operations that access samples from uncommitted regions produce
351    the following behavior:
352
353        * Reads from such regions produce undefined data, but otherwise have
354          no adverse effect. This includes samples required for the
355          implementation of texture filtering, mipmap generation and so on.
356
357        * Writes to such regions are ignored. The GL may attempt to write to
358          uncommitted regions but the effect of doing so will be benign.
359
360        * Atomic operations with return values on uncommitted regions will
361          complete normally, but the returned value will be undefined and the
362          result of the atomic operation will be discarded.
363
364        * Reads and writes through framebuffers shall have no adverse effect,
365          but fragment shaders corresponding to uncommitted regions of the
366          framebuffer still execute to completion. Visible side effects
367          of these shaders such as operations on atomic counters, storage
368          blocks or committed regions of images are still seen, as are
369          the results of operations such as occlusion queries.
370
371        * Access to uncommitted regions by the client (for example through
372          ReadPixels or GetTexImage) shall have similar effect as through any
373          other part of the GL --- reads return undefined data and writes are
374          discarded, with no other ill effect.
375
376    Insert Subsection 8.20.2. "Controlling Sparse Texture Commitment"
377
378        If a texture is allocated using sparse storage (that is, its
379    TEXTURE_SPARSE_ARB parameter is TRUE) at the time that its storage is
380    allocated, it is initially created with only a virtual data store, and no
381    physical data store. Individual pages of a sparse texture may be made
382    resident or non resident by calling
383
384        void TexPageCommitmentARB(enum target,
385                                  int level,
386                                  int xoffset,
387                                  int yoffset,
388                                  int zoffset,
389                                  sizei width,
390                                  sizei height,
391                                  sizei depth,
392                                  boolean commit);
393
394    with <target> and <level> indicating the level of the texture object whose
395    residency is to be modified. <xoffset>, <yoffset>, <zoffset>, <width>,
396    <height> and <depth> are interpreted as they are in TexSubImage3D.  An
397    error will be generated unless <xoffset>, <yoffset> <zoffset>, <width>,
398    <height> and <depth> specify a region of the texture level that is aligned
399    to multiples of the page size or to the edges of the texture.
400
401    If the value of <commit> is TRUE, then the texture pages contained in
402    the region defined by the values of <xoffset>, <yoffset>, <zoffset>,
403    <width>, <height> and <depth> are committed. If they were not committed
404    before the call, then new physical backing store is allocated and associated
405    with the sparse pages and their initial content is undefined. If the pages
406    were already committed, then they remain committed, no error is generated,
407    and the content of those pages remains unmodified. If the value of
408    <committed> is FALSE, then the texture pages contained in the region are
409    made de-committed. Their physical store is de-allocated, and their contents
410    again become undefined.
411
412    For the purposes of commitment, a cube map texture is treated as a 2D
413    array texture with a depth of six and cube map array textures are treated
414    as 2D array textures with a depth equal to six times the number of layers
415    in the cube map array.
416
417    For levels of a sparse texture where each dimension is a multiple of the
418    virtual page size, the residency of individual page-size regions is
419    controlled by TexPageCommitmentARB and such levels may be partially
420    populated.  When the mipmap chain reaches a level that is not an integer
421    multiple of the virtual page size in any dimension, padding and memory
422    layout considerations may make it impossible to treat that level and
423    subsequent smaller ones as partially populated.  The set of levels that
424    can be partially populated is implementation-dependent.  The total number
425    of levels that may be partially populated may be queried by calling
426    GetTexParameteriv with the <pname> NUM_SPARSE_LEVELS_ARB.
427
428    The collection of texture levels that may not be partially populated, if
429    any, consists of levels NUM_SPARSE_LEVELS_ARB and higher, and is referred
430    to as the mipmap 'tail'.  The levels comprising the tail are made resident
431    or non-resident as a unit.  The tail is resident if and only if
432    TexPageCommitmentARB has been called successfully with <level> greater
433    than or equal to NUM_SPARSE_LEVELS_ARB and the value of <commit> was TRUE
434    for the last such call.
435
436    Views of sparse textures are also considered sparse. Modifications to
437    commitment of a texture via a view of it affect the parent texture and
438    any other views containing the modified pages. If a view of a sparse
439    texture references its tail (or is entirely contained within it),
440    modifications to commitment of the tail via the view will affect the entire
441    tail of the parent, even for parts of the tail that are not referenced
442    by the view. Furthermore, modifications to tail commitment may affect
443    views referencing other parts of the tail.
444
445    Errors
446
447      An INVALID_OPERATION error is generated if <xoffset> + <width> or
448      <yoffset> + <height> is greater than the width or height, respectively,
449      of level <level> of the texture bound to <target>.
450
451      An INVALID_OPERATION error is generated if <zoffset> + <depth> is
452      greater than
453
454        * the depth of level <level> of the texture bound to <target>, if
455          <target> is TEXTURE_3D;
456
457        * the number of layers of level <level> of the texture bound to
458          <target>, if <target> is TEXTURE_2D_ARRAY;
459
460        * six times the number of layers of level <level> of the texture bound
461          to <target>, if <target> is TEXTURE_CUBE_MAP_ARRAY; or
462
463        * one, for all other targets.
464
465      An INVALID_VALUE error is generated if <xoffset>, <yoffset>, or
466      <zoffset> is not a multiple of VIRTUAL_PAGE_SIZE_X_ARB,
467      VIRTUAL_PAGE_SIZE_Y_ARB, or VIRTUAL_PAGE_SIZE_Z_ARB, respectively, of
468      the texture bound to <target>.
469
470      An INVALID_OPERATION error is generated if <width> is not an integer
471      multiple of VIRTUAL_PAGE_SIZE_X_ARB and <width> plus <xoffset> is not
472      equal to the width of level <level> of the texture bound to <target>.
473
474      An INVALID_OPERATION error is generated if <height> is not an integer
475      multiple of VIRTUAL_PAGE_SIZE_Y_ARB and <height> plus <yoffset> is not
476      equal to the height of level <level> of the texture bound to <target>.
477
478      An INVALID_OPERATION error is generated if <depth> is not an integer
479      multiple of VIRTUAL_PAGE_SIZE_Z_ARB and <depth> plus <zoffset> is not
480      equal to
481
482        * the depth of level <level> of the texture bound to <target>, if
483          <target> is TEXTURE_3D;
484
485        * the number of layers of level <level> of the texture bound to
486          <target>, if <target> is TEXTURE_2D_ARRAY;
487
488        * six times the number of layers of level <level> of the texture bound
489          to <target>, if <target> is TEXTURE_CUBE_MAP_ARRAY; or
490
491        * one, for all other targets.
492
493      An INVALID_OPERATION error is generated if the value of
494      TEXTURE_IMMUTABLE_FORMAT or TEXTURE_SPARSE_ARB for the texture bound to
495      <target> is FALSE.
496
497    [[ The following is only added if EXT_direct_state_access or
498       ARB_direct_state_access is supported. ]]
499
500    The command
501
502        void TexturePageCommitmentEXT(uint texture,
503                                      int level,
504                                      int xoffset,
505                                      int yoffset,
506                                      int zoffset,
507                                      sizei width,
508                                      sizei height,
509                                      sizei depth,
510                                      boolean commit);
511
512    may also be used to control the residency of sparse textures.  This
513    command behaves identically to TexPageCommitmentARB, except that the
514    texture is identified by the name <texture> instead of via <target>.
515
516    Errors
517
518      An INVALID_OPERATION error is generated if <texture> is not the name of
519      an existing texture.
520
521      All other errors listed for TexPageCommitmentARB also apply to
522      TexturePageCommitmentEXT, except that references to "the texture bound
523      to <target>" should be replaced with "the texture <texture>", and all
524      other references to "<target>" should be replaced with "the target of
525      texture <texture>".
526
527
528Additions to the AGL/GLX/WGL Specifications
529
530    None.
531
532GLX Protocol
533
534    None.
535
536New State
537
538    Append to Table 23.15, "Textures (state per texture object) (cont.)"
539
540    +-----------------------------------+-------+---------------------+-----------------+---------------------------------------+-------+
541    | Get Value                         | Type  | Get Command         | Initial Value   | Description                           | Sec.  |
542    +-----------------------------------+-------+---------------------+-----------------+---------------------------------------+-------+
543    | VIRTUAL_PAGE_SIZE_INDEX_ARB       | Z+    | GetTexParameteriv   | 0               | Virtual page size index               | 8.19  |
544    | TEXTURE_SPARSE_ARB                | B     | GetTexParameteriv   | FALSE           | Texture sparseness                    | 8.19  |
545    | NUM_SPARSE_LEVELS_ARB             | Z+    | GetTexParameteriv   | 0               | Number of potentially sparse levels   | 8.19  |
546    +-----------------------------------+-------+---------------------+-----------------+---------------------------------------+-------+
547
548New Implementation Dependent State
549
550    Append to Table 6.42, "Implementation Dependent Values"
551
552    +--------------------------------------------+-------+-------------+-----------------+---------------------------------------+-------+
553    | Get Value                                  | Type  | Get Command | Minimum Value   | Description                           | Sec.  |
554    +--------------------------------------------+-------+-------------+-----------------+---------------------------------------+-------+
555    | MAX_SPARSE_TEXTURE_SIZE_ARB                | Z+    | GetIntegerv | 16384           | Maximum 1D/2D/rectangle texture image | 8.19  |
556    |                                            |       |             |                 | dimension for a sparse texture.       |       |
557    | MAX_SPARSE_3D_TEXTURE_SIZE_ARB             | Z+    | GetIntegerv | 2048            | Maximum 3D texture image dimension    | 8.19  |
558    |                                            |       |             |                 | for a sparse texture.                 |       |
559    | MAX_SPARSE_ARRAY_TEXTURE_LAYERS_ARB        | Z+    | GetIntegerv | 2048            | Maximum number of layers in a sparse  | 8.19  |
560    |                                            |       |             |                 | array texture.                        |       |
561    | SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB | B     | GetBooleanv | -               | TRUE if there are no restrictions on  | 8.19  |
562    |                                            |       |             |                 | the allocation of mipmaps in sparse   |       |
563    |                                            |       |             |                 | textures and FALSE otherwise.         |       |
564    +--------------------------------------------+-------+-------------+-----------------+---------------------------------------+-------+
565
566Dependencies on OpenGL 4.3 and ARB_texture_view
567
568    If the GL version is less than 4.3 or if ARB_texture_view is not supported,
569    then remove all references to texture views.
570
571Dependencies on GL_EXT_direct_state_access and GL_ARB_direct_state_access
572
573    If neither the GL_EXT_direct_state_access nor the
574    GL_ARB_direct_state_access extensions is supported, remove all references
575    to TexturePageCommitmentEXT.
576
577Issues
578
579    1) Do we want to mandate specific page sizes for specific formats?
580
581       RESOLVED. No.
582
583    2) What happened to MIN_SPARSE_LEVEL_AMD from the AMD spec? Do we need it
584       here?
585
586       RESOLVED. We changed it to NUM_SPARSE_LEVELS_ARB. MIN_SPARSE_LEVEL_AMD
587       could not acceptably describe the case where a texture is technically
588       sparse, but no level of the texture may be sparsely populated. The
589       AMD specification disallowed creation of such a texture. However, this
590       extension does allow creation of a texture that is either wholly
591       resident or non-resident. Furthermore, if a view of a sparse texture
592       is created starting somewhere in the tail, then that whole view
593       is essentially sparse.
594
595    3) Should it be mandatory to support sparse allocation for compressed
596       textures?
597
598       RESOLVED: No, but in all likelihood, implementations will support some
599       or all compressed texture formats.
600
601    4) Are multisample textures supported? What about depth and stencil
602       format textures?
603
604       RESOLVED: No. Depth and stencil format textures are optional to support.
605       Providing support would be a case of reporting non-zero for
606       NUM_VIRTUAL_PAGE_SIZES_ARB for those formats. Multi-sample textures
607       are explicitly not supported by this extension as their targets are
608       excluded from TexStorage* support. Allowing support for these would
609       require a new extension, if only to remove the error generated
610       if one of the multi-sample targets is used with TexStorage* when
611       the sparse flag is set.
612
613    5) Do we need language clarifying completeness and the effects of
614       residency on completeness?
615
616       RESOLVED: Currently, there is no language. Textures allocated by
617       TexStorage* (which include all sparse textures) are always complete.
618       Residency doesn't effect that and sampling from them is well defined
619       (or explicitly undefined).
620
621    6) Can commitment fail? What happens if it does?
622
623       RESOLVED: An OUT_OF_MEMORY error is generated if physical backing cannot
624       be allocated for the previously allocated virtual space. No language
625       is added here as it is implicit that any command can generate
626       OUT_OF_MEMORY at any time for any reason... which includes new commands
627       introduced here.
628
629    7) Please explain, in plain English, what the rules are governing the size
630       of a texture's base level, mipmap levels, and the 'tail'.
631
632       The base level of the texture must be an integer multiple of the page
633       size in each dimension. This need not be a power of two or square or
634       anything of that nature. As we proceed along the mipmap chain, the
635       current level will become smaller and smaller, at each step halving in
636       size. At some point, the level dimensions will no longer be an integer
637       multiple of the page size, where the memory corresponding to that level
638       and smaller sized levels may not be evenly divided into pages.  The
639       memory allocated to such levels may not be naturally aligned on memory
640       page boundaries or may be too small to bother with partial residency.
641       Implementations are permitted to treat such a level and all subsequent
642       levels as either fully resident or fully non-resident.  We refer to
643       this set of levels as the mipmap "tail".  The set of levels belonging
644       to the tail is implementation-dependent.  Some implementations may
645       start the tail at the first level where any dimension is not the
646       multiple of a page size; others might pad out such allocations to page
647       boundaries and start the tail at a much smaller mipmap level.  The tail
648       is made resident or non-resident as a unit; the tail is resident if and
649       only if <resident> was TRUE for the last call to TexPageCommitmentARB
650       when <level> was any value in the tail.
651
652       Clearly, making the base level a square power of two multiple of the
653       page size will mean that the greatest part of the texture can be sparse
654       and will minimize the size of the tail. However, it's perfectly legal,
655       with a hypothetical 256 x 256 texel page size to create a texture with
656       a base level of 4096 x 256. Such a texture can be sparse in the base
657       level, but level 1 would be 2048 x 128, which is no longer a multiple
658       of the page size, and therefore might be considered as the start of the
659       tail.
660
661    8) What's SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB for?
662
663       Some implementations may store the mipmap chain for array textures
664       and cubemaps such that the presence and size of mipmaps affects the
665       alignment of the start of each layer, even in the base level. Consider
666       an implementation that stores all layers of of level 0, then all of
667       level 1, then all of level 2 and so on. The presence of a mipmap chain
668       (or lack thereof) would have no effect on the alignment of layers 1
669       through N of the array (or cubemap faces). Now, consider an
670       implementation that stores all of the levels for layer 0, then all
671       levels of layer 1 and so on. The number and size of the levels of the
672       texture _would_ have an effect on the alignment of layers 1 through N
673       of the texture. If the size of the mipmap chain for a single layer
674       causes the next layer to become misaligned to the page size in linear
675       address space, then the texture cannot be sparsely populated. This flag
676       indicates whether the implementation has any restrictions on the size
677       of the mipmap chain. In particular, these restrictions ensure that,
678       while the texture may have mipmaps, the total size of the mipmap chain
679       for each level still satisfies the alignment restrictions required by
680       that implementation's virtual memory subsystem.
681
682    9) What happens when you create a view of a sparse texture?
683
684       RESOLVED: That view is sparse, as are views of that view and so on.
685       Also, if the view hits the tail, then modifications of tail residency
686       via the view affect the whole tail of the parent texture.
687
688    10) Why is there no TexturePageCommitmentARB?
689
690       There was originally no documented interaction between this extension
691       and ARB_direct_state_access. Since implementations that support both
692       extensions were shipped without TexturePageCommitmentARB, it is not
693       feasible to add this entry point after the fact. On the other hand,
694       implementations that support both extensions but *not*
695       EXT_direct_state_access should also be able to provide a DSA entry
696       point. Since every known implementation that supports this extension and
697       ARB_direct_state_access does have the TexturePageCommitmentEXT entry
698       point, making this fact retroactively part of the spec is an unusual
699       but pragmatic resolution.
700
701Revision History
702
703    Rev.    Date      Author    Changes
704    ----  --------    --------  -----------------------------------------
705    12    05/11/2017  nhaehnle  Add interaction with ARB_direct_state_access
706                                (bug 13684)
707    11    08/16/2013  pbrown    Remove the <target> parameter from the DSA
708                                function TexturePageCommitmentEXT() and also
709                                add more explicit error language.  The
710                                parameter removal was agreed to before the
711                                spec was published but didn't get added to the
712                                shipping spec (bug 10445).  Add missing
713                                RG8_SNORM and RG16 entries to the formats
714                                table and list them as supporting sparse
715                                textures (bug 10709).
716    10    08/06/2013  pbrown    Add spec langauge for the VIRTUAL_PAGE_SIZE_
717                                INDEX_ARB texture parameter.  Remove the
718                                TexStorage error for a negative virtual page
719                                size index, since that can be checked by
720                                TexParameter.  Fix the errors section for the
721                                offset and sizes in TexPageCommitmentARB (bug
722                                10387) and remove duplicate introductory
723                                language describing alignment requirements.
724                                Clarify spec language and issue (7) describing
725                                the implementation-dependent sparse mipmap
726                                "tail" (bug 10353) and guarantee that any
727                                level that is a multiple of the page size is
728                                not in the tail.  Add spec language describing
729                                TexturePageCommitmentEXT.  Add a few missing
730                                "_ARB" suffixes.  Remove the "minimum maximum"
731                                for SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB.
732     9    07/08/2013  gsellers  Fix token value clash for
733                                NUM_SPARSE_LEVELS_ARB.
734     8    07/03/2013  gsellers  Change MIN_SPARSE_LEVEL_ARB to
735                                NUM_SPARSE_LEVELS_ARB (new token value).
736                                Add language to describe views of sparse
737                                textures, including tail residency issues.
738                                Add issue 9.
739     7    06/13/2013  gsellers  Assign enums. Add MIN_SPARSE_LEVEL_ARB to
740                                state table.
741     6    06/07/2013  gsellers  Bring back MIN_SPARSE_LEVEL_ARB.
742     5    06/06/2013  gsellers  Multiple updates from bugs 10186, 10329,
743                                10131, and 10353.
744     4    05/31/2013  gsellers  Resolve several issues from bug 10186.
745     3    04/22/2013  gsellers  Add column to tables to indicate which formats
746                                support sparse allocation.
747                                Add requirement that the base level of a sparse
748                                texture must be an integer multiple of the
749                                selected virtual page size.
750                                Document that the tail of a mip-chain becomes
751                                completely resident at the same time.
752     2    03/07/2013  gsellers  Major overhaul from AMD version. Deleted
753                                most things. Added:
754                                 * NUM_VIRTUAL_PAGE_SIZES_ARB
755                                 * Set texture immutable state before calling
756                                   TexStorage.
757     1    01/21/2013  gsellers  Initial Revision based on AMD_sparse_texture
758