Class ARBSparseTexture

java.lang.Object
org.lwjgl.opengl.ARBSparseTexture

public class ARBSparseTexture extends Object
Native bindings to the ARB_sparse_texture extension.

Recent advances in application complexity and a desire for higher resolutions have pushed texture sizes up considerably. Often, the amount of physical memory available to a graphics processor is a limiting factor in the performance of texture-heavy applications. Once the available physical memory is exhausted, paging may occur bringing performance down considerably - or worse, the application may fail. Nevertheless, the amount of address space available to the graphics processor has increased to the point where many gigabytes - or even terabytes of address space may be usable even though that amount of physical memory is not present.

This extension allows the separation of the graphics processor's address space (reservation) from the requirement that all textures must be physically backed (commitment). This exposes a limited form of virtualization for textures. Use cases include sparse (or partially resident) textures, texture paging, on-demand and delayed loading of texture assets and application controlled level of detail.

  • Field Details

    • GL_TEXTURE_SPARSE_ARB

      public static final int GL_TEXTURE_SPARSE_ARB
      Accepted by the pname parameter to TexParameter{i f}{v}, TexParameterI{u}v, GetTexParameter{if}v and GetTexParameterIi{u}v.
      See Also:
    • GL_VIRTUAL_PAGE_SIZE_INDEX_ARB

      public static final int GL_VIRTUAL_PAGE_SIZE_INDEX_ARB
      Accepted by the pname parameter to TexParameter{i f}{v}, TexParameterI{u}v, GetTexParameter{if}v and GetTexParameterIi{u}v.
      See Also:
    • GL_NUM_SPARSE_LEVELS_ARB

      public static final int GL_NUM_SPARSE_LEVELS_ARB
      Accepted by the pname parameter of GetTexParameter{if}v and GetTexParameterIi{u}v.
      See Also:
    • GL_NUM_VIRTUAL_PAGE_SIZES_ARB

      public static final int GL_NUM_VIRTUAL_PAGE_SIZES_ARB
      Accepted by the pname parameter to GetInternalformativ.
      See Also:
    • GL_VIRTUAL_PAGE_SIZE_X_ARB

      public static final int GL_VIRTUAL_PAGE_SIZE_X_ARB
      Accepted by the pname parameter to GetInternalformativ.
      See Also:
    • GL_VIRTUAL_PAGE_SIZE_Y_ARB

      public static final int GL_VIRTUAL_PAGE_SIZE_Y_ARB
      Accepted by the pname parameter to GetInternalformativ.
      See Also:
    • GL_VIRTUAL_PAGE_SIZE_Z_ARB

      public static final int GL_VIRTUAL_PAGE_SIZE_Z_ARB
      Accepted by the pname parameter to GetInternalformativ.
      See Also:
    • GL_MAX_SPARSE_TEXTURE_SIZE_ARB

      public static final int GL_MAX_SPARSE_TEXTURE_SIZE_ARB
      Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.
      See Also:
    • GL_MAX_SPARSE_3D_TEXTURE_SIZE_ARB

      public static final int GL_MAX_SPARSE_3D_TEXTURE_SIZE_ARB
      Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.
      See Also:
    • GL_MAX_SPARSE_ARRAY_TEXTURE_LAYERS_ARB

      public static final int GL_MAX_SPARSE_ARRAY_TEXTURE_LAYERS_ARB
      Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.
      See Also:
    • GL_SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB

      public static final int GL_SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB
      Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.
      See Also:
  • Method Details

    • glTexPageCommitmentARB

      public static void glTexPageCommitmentARB(int target, int level, int xoffset, int yoffset, int zoffset, int width, int height, int depth, boolean commit)
      Makes individual pages of a sparse texture resident or non resident.

      If the value of commit is TRUE, then the texture pages contained in the region defined by the values of xoffset, yoffset, zoffset, width, height and depth are committed. If they were not committed before the call, then new physical backing store is allocated and associated with the sparse pages and their initial content is undefined. If the pages were already committed, then they remain committed, no error is generated, and the content of those pages remains unmodified. If the value of committed is FALSE, then the texture pages contained in the region are made de-committed. Their physical store is de-allocated, and their contents again become undefined.

      For the purposes of commitment, a cube map texture is treated as a 2D array texture with a depth of six and cube map array textures are treated as 2D array textures with a depth equal to six times the number of layers in the cube map array.

      For levels of a sparse texture where each dimension is a multiple of the virtual page size, the residency of individual page-size regions is controlled by TexPageCommitmentARB and such levels may be partially populated. When the mipmap chain reaches a level that is not an integer multiple of the virtual page size in any dimension, padding and memory layout considerations may make it impossible to treat that level and subsequent smaller ones as partially populated. The set of levels that can be partially populated is implementation-dependent. The total number of levels that may be partially populated may be queried by calling GetTexParameteriv with the pname NUM_SPARSE_LEVELS_ARB.

      The collection of texture levels that may not be partially populated, if any, consists of levels NUM_SPARSE_LEVELS_ARB and higher, and is referred to as the mipmap 'tail'. The levels comprising the tail are made resident or non-resident as a unit. The tail is resident if and only if TexPageCommitmentARB has been called successfully with level greater than or equal to NUM_SPARSE_LEVELS_ARB and the value of commit was TRUE for the last such call.

      Views of sparse textures are also considered sparse. Modifications to commitment of a texture via a view of it affect the parent texture and any other views containing the modified pages. If a view of a sparse texture references its tail (or is entirely contained within it), modifications to commitment of the tail via the view will affect the entire tail of the parent, even for parts of the tail that are not referenced by the view. Furthermore, modifications to tail commitment may affect views referencing other parts of the tail.

      Errors

      An INVALID_OPERATION error is generated if xoffset + width or yoffset + height is greater than the width or height, respectively, of level level of the texture bound to target.

      An INVALID_OPERATION error is generated if zoffset + depth is greater than

      • the depth of level level of the texture bound to target, if target is TEXTURE_3D;
      • the number of layers of level level of the texture bound to target, if target is TEXTURE_2D_ARRAY;
      • six times the number of layers of level level of the texture bound to target, if target is TEXTURE_CUBE_MAP_ARRAY; or
      • one, for all other targets.

      An INVALID_VALUE error is generated if xoffset, yoffset, or zoffset is not a multiple of VIRTUAL_PAGE_SIZE_X_ARB, VIRTUAL_PAGE_SIZE_Y_ARB, or VIRTUAL_PAGE_SIZE_Z_ARB, respectively, of the texture bound to target.

      An INVALID_OPERATION error is generated if width is not an integer multiple of VIRTUAL_PAGE_SIZE_X_ARB and width plus xoffset is not equal to the width of level level of the texture bound to target.

      An INVALID_OPERATION error is generated if height is not an integer multiple of VIRTUAL_PAGE_SIZE_Y_ARB and height plus yoffset is not equal to the height of level level of the texture bound to target.

      An INVALID_OPERATION error is generated if depth is not an integer multiple of VIRTUAL_PAGE_SIZE_Z_ARB and depth plus zoffset is not equal to

      • the depth of level level of the texture bound to target, if target is TEXTURE_3D;
      • the number of layers of level level of the texture bound to target, if target is TEXTURE_2D_ARRAY;
      • six times the number of layers of level level of the texture bound to target, if target is TEXTURE_CUBE_MAP_ARRAY; or
      • one, for all other targets.

      An INVALID_OPERATION error is generated if the value of TEXTURE_IMMUTABLE_FORMAT or TEXTURE_SPARSE_ARB for the texture bound to target is FALSE.

      Parameters:
      target - the texture target. One of:
      TEXTURE_1DTEXTURE_2DTEXTURE_1D_ARRAYTEXTURE_RECTANGLETEXTURE_CUBE_MAP
      TEXTURE_3DTEXTURE_2D_ARRAYTEXTURE_CUBE_MAP_ARRAY
      level - the level-of-detail-number
      xoffset - the x coordinate of the texel subregion
      yoffset - the y coordinate of the texel subregion
      zoffset - the z coordinate of the texel subregion
      width - the subregion width
      height - the subregion height
      depth - the subregion depth
      commit - the commit flag
    • glTexturePageCommitmentEXT

      public static void glTexturePageCommitmentEXT(int texture, int level, int xoffset, int yoffset, int zoffset, int width, int height, int depth, boolean commit)
      DSA version of TexPageCommitmentARB.
      Parameters:
      texture - the texture object
      level - the level-of-detail-number
      xoffset - the x coordinate of the texel subregion
      yoffset - the y coordinate of the texel subregion
      zoffset - the z coordinate of the texel subregion
      width - the subregion width
      height - the subregion height
      depth - the subregion depth
      commit - the commit flag