Class ARBSparseTexture
- java.lang.Object
-
- org.lwjgl.opengl.ARBSparseTexture
-
public class ARBSparseTexture extends java.lang.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 Summary
Fields Modifier and Type Field and Description static int
GL_MAX_SPARSE_3D_TEXTURE_SIZE_ARB
GL_MAX_SPARSE_ARRAY_TEXTURE_LAYERS_ARB
GL_MAX_SPARSE_TEXTURE_SIZE_ARBAccepted by thepname
parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.static int
GL_NUM_SPARSE_LEVELS_ARB
Accepted by thepname
parameter of GetTexParameter{if}v and GetTexParameterIi{u}v.static int
GL_NUM_VIRTUAL_PAGE_SIZES_ARB
Accepted by thepname
parameter to GetInternalformativ.static int
GL_SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB
Accepted by thepname
parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.static int
GL_TEXTURE_SPARSE_ARB
GL_VIRTUAL_PAGE_SIZE_INDEX_ARBAccepted by thepname
parameter to TexParameter{i f}{v}, TexParameterI{u}v, GetTexParameter{if}v and GetTexParameterIi{u}v.static int
GL_VIRTUAL_PAGE_SIZE_X_ARB
GL_VIRTUAL_PAGE_SIZE_Y_ARB
GL_VIRTUAL_PAGE_SIZE_Z_ARBAccepted by thepname
parameter to GetInternalformativ.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method and Description 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.static void
glTexturePageCommitmentEXT(int texture, int level, int xoffset, int yoffset, int zoffset, int width, int height, int depth, boolean commit)
DSA version ofTexPageCommitmentARB
.
-
-
-
Field Detail
-
GL_TEXTURE_SPARSE_ARB, GL_VIRTUAL_PAGE_SIZE_INDEX_ARB
Accepted by thepname
parameter to TexParameter{i f}{v}, TexParameterI{u}v, GetTexParameter{if}v and GetTexParameterIi{u}v.
-
GL_NUM_SPARSE_LEVELS_ARB
Accepted by thepname
parameter of GetTexParameter{if}v and GetTexParameterIi{u}v.
-
GL_NUM_VIRTUAL_PAGE_SIZES_ARB, GL_VIRTUAL_PAGE_SIZE_X_ARB, GL_VIRTUAL_PAGE_SIZE_Y_ARB, GL_VIRTUAL_PAGE_SIZE_Z_ARB
Accepted by thepname
parameter to GetInternalformativ.
-
GL_MAX_SPARSE_TEXTURE_SIZE_ARB, GL_MAX_SPARSE_3D_TEXTURE_SIZE_ARB, GL_MAX_SPARSE_ARRAY_TEXTURE_LAYERS_ARB, GL_SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB
Accepted by thepname
parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.
-
-
Method Detail
-
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
isTRUE
, then the texture pages contained in the region defined by the values ofxoffset
,yoffset
,zoffset
,width
,height
anddepth
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 ofcommitted
isFALSE
, 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 thepname
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 withlevel
greater than or equal toNUM_SPARSE_LEVELS_ARB
and the value ofcommit
wasTRUE
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 ifxoffset
+width
oryoffset
+height
is greater than the width or height, respectively, of levellevel
of the texture bound totarget
.An
INVALID_OPERATION
error is generated ifzoffset
+depth
is greater than- the depth of level
level
of the texture bound totarget
, iftarget
isTEXTURE_3D
; - the number of layers of level
level
of the texture bound totarget
, iftarget
isTEXTURE_2D_ARRAY
; - six times the number of layers of level
level
of the texture bound totarget
, iftarget
isTEXTURE_CUBE_MAP_ARRAY
; or - one, for all other targets.
An
INVALID_VALUE
error is generated ifxoffset
,yoffset
, orzoffset
is not a multiple ofVIRTUAL_PAGE_SIZE_X_ARB
,VIRTUAL_PAGE_SIZE_Y_ARB
, orVIRTUAL_PAGE_SIZE_Z_ARB
, respectively, of the texture bound totarget
.An
INVALID_OPERATION
error is generated ifwidth
is not an integer multiple ofVIRTUAL_PAGE_SIZE_X_ARB
andwidth
plusxoffset
is not equal to the width of levellevel
of the texture bound totarget
.An
INVALID_OPERATION
error is generated ifheight
is not an integer multiple ofVIRTUAL_PAGE_SIZE_Y_ARB
andheight
plusyoffset
is not equal to the height of levellevel
of the texture bound totarget
.An
INVALID_OPERATION
error is generated ifdepth
is not an integer multiple ofVIRTUAL_PAGE_SIZE_Z_ARB
anddepth
pluszoffset
is not equal to- the depth of level
level
of the texture bound totarget
, iftarget
is TEXTURE_3D; - the number of layers of level
level
of the texture bound totarget
, iftarget
is TEXTURE_2D_ARRAY; - six times the number of layers of level
level
of the texture bound totarget
, iftarget
is TEXTURE_CUBE_MAP_ARRAY; or - one, for all other targets.
An
INVALID_OPERATION
error is generated if the value ofTEXTURE_IMMUTABLE_FORMAT
orTEXTURE_SPARSE_ARB
for the texture bound totarget
isFALSE
.- Parameters:
target
- the texture target. One of:TEXTURE_1D
TEXTURE_2D
TEXTURE_1D_ARRAY
TEXTURE_RECTANGLE
TEXTURE_CUBE_MAP
TEXTURE_3D
TEXTURE_2D_ARRAY
TEXTURE_CUBE_MAP_ARRAY
level
- the level-of-detail-numberxoffset
- the x coordinate of the texel subregionyoffset
- the y coordinate of the texel subregionzoffset
- the z coordinate of the texel subregionwidth
- the subregion widthheight
- the subregion heightdepth
- the subregion depthcommit
- the commit flag
- the depth of level
-
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 ofTexPageCommitmentARB
.- Parameters:
texture
- the texture objectlevel
- the level-of-detail-numberxoffset
- the x coordinate of the texel subregionyoffset
- the y coordinate of the texel subregionzoffset
- the z coordinate of the texel subregionwidth
- the subregion widthheight
- the subregion heightdepth
- the subregion depthcommit
- the commit flag
-
-