Top Description Fields Constructors Methods
org.lwjgl.opengl

public Class ARBSparseTexture

extends Object
Class Inheritance
Imports
org.lwjgl.system.*
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 Summary

Modifier and TypeField and Description
public static final int
GL_MAX_SPARSE_3D_TEXTURE_SIZE_ARB

Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.

public static final int
GL_MAX_SPARSE_ARRAY_TEXTURE_LAYERS_ARB

Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.

public static final int
GL_MAX_SPARSE_TEXTURE_SIZE_ARB

Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.

public static final int
GL_NUM_SPARSE_LEVELS_ARB

Accepted by the pname parameter of GetTexParameter{if}v and GetTexParameterIi{u}v.

public static final int
GL_NUM_VIRTUAL_PAGE_SIZES_ARB

Accepted by the pname parameter to GetInternalformativ.

public static final int
GL_SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB

Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.

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.

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.

public static final int
GL_VIRTUAL_PAGE_SIZE_X_ARB

Accepted by the pname parameter to GetInternalformativ.

public static final int
GL_VIRTUAL_PAGE_SIZE_Y_ARB

Accepted by the pname parameter to GetInternalformativ.

public static final int
GL_VIRTUAL_PAGE_SIZE_Z_ARB

Accepted by the pname parameter to GetInternalformativ.

Constructor Summary

AccessConstructor and Description
protected
ARBSparseTexture()

Method Summary

Modifier and TypeMethod and Description
public static native void
glTexPageCommitmentARB(int
the texture target. One of:
TEXTURE_1DTEXTURE_2DTEXTURE_1D_ARRAYTEXTURE_RECTANGLETEXTURE_CUBE_MAP
TEXTURE_3DTEXTURE_2D_ARRAYTEXTURE_CUBE_MAP_ARRAY
target, int
the level-of-detail-number
level, int
the x coordinate of the texel subregion
xoffset, int
the y coordinate of the texel subregion
yoffset, int
the z coordinate of the texel subregion
zoffset, int
the subregion width
width, int
the subregion height
height, int
the subregion depth
depth, boolean
the commit flag
commit)

Makes individual pages of a sparse texture resident or non resident.

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

DSA version of TexPageCommitmentARB.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

GL_MAX_SPARSE_3D_TEXTURE_SIZE_ARBback to summary
public static final int GL_MAX_SPARSE_3D_TEXTURE_SIZE_ARB

Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.

GL_MAX_SPARSE_ARRAY_TEXTURE_LAYERS_ARBback to summary
public static final int GL_MAX_SPARSE_ARRAY_TEXTURE_LAYERS_ARB

Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.

GL_MAX_SPARSE_TEXTURE_SIZE_ARBback to summary
public static final int GL_MAX_SPARSE_TEXTURE_SIZE_ARB

Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.

GL_NUM_SPARSE_LEVELS_ARBback to summary
public static final int GL_NUM_SPARSE_LEVELS_ARB

Accepted by the pname parameter of GetTexParameter{if}v and GetTexParameterIi{u}v.

GL_NUM_VIRTUAL_PAGE_SIZES_ARBback to summary
public static final int GL_NUM_VIRTUAL_PAGE_SIZES_ARB

Accepted by the pname parameter to GetInternalformativ.

GL_SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARBback to summary
public static final int GL_SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB

Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.

GL_TEXTURE_SPARSE_ARBback to summary
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.

GL_VIRTUAL_PAGE_SIZE_INDEX_ARBback to summary
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.

GL_VIRTUAL_PAGE_SIZE_X_ARBback to summary
public static final int GL_VIRTUAL_PAGE_SIZE_X_ARB

Accepted by the pname parameter to GetInternalformativ.

GL_VIRTUAL_PAGE_SIZE_Y_ARBback to summary
public static final int GL_VIRTUAL_PAGE_SIZE_Y_ARB

Accepted by the pname parameter to GetInternalformativ.

GL_VIRTUAL_PAGE_SIZE_Z_ARBback to summary
public static final int GL_VIRTUAL_PAGE_SIZE_Z_ARB

Accepted by the pname parameter to GetInternalformativ.

Constructor Detail

ARBSparseTextureback to summary
protected ARBSparseTexture()

Method Detail

glTexPageCommitmentARBback to summary
public static native 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:int

the texture target. One of:

TEXTURE_1DTEXTURE_2DTEXTURE_1D_ARRAYTEXTURE_RECTANGLETEXTURE_CUBE_MAP
TEXTURE_3DTEXTURE_2D_ARRAYTEXTURE_CUBE_MAP_ARRAY
level:int

the level-of-detail-number

xoffset:int

the x coordinate of the texel subregion

yoffset:int

the y coordinate of the texel subregion

zoffset:int

the z coordinate of the texel subregion

width:int

the subregion width

height:int

the subregion height

depth:int

the subregion depth

commit:boolean

the commit flag

glTexturePageCommitmentEXTback to summary
public static native 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:int

the texture object

level:int

the level-of-detail-number

xoffset:int

the x coordinate of the texel subregion

yoffset:int

the y coordinate of the texel subregion

zoffset:int

the z coordinate of the texel subregion

width:int

the subregion width

height:int

the subregion height

depth:int

the subregion depth

commit:boolean

the commit flag