Package org.lwjgl.opengl

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	Description
static int	GL_MAX_SPARSE_3D_TEXTURE_SIZE_ARB GL_MAX_SPARSE_ARRAY_TEXTURE_LAYERS_ARB GL_MAX_SPARSE_TEXTURE_SIZE_ARB	Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.
static int	GL_NUM_SPARSE_LEVELS_ARB	Accepted by the pname parameter of GetTexParameter{if}v and GetTexParameterIi{u}v.
static int	GL_NUM_VIRTUAL_PAGE_SIZES_ARB	Accepted by the pname parameter to GetInternalformativ.
static int	GL_SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB	Accepted by the pname parameter to GetIntegerv, GetFloatv, GetDoublev, GetInteger64v, and GetBooleanv.
static int	GL_TEXTURE_SPARSE_ARB 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.
static int	GL_VIRTUAL_PAGE_SIZE_X_ARB GL_VIRTUAL_PAGE_SIZE_Y_ARB GL_VIRTUAL_PAGE_SIZE_Z_ARB	Accepted by the pname parameter to GetInternalformativ.

Method Summary

Modifier and Type	Method	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 of TexPageCommitmentARB.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GL_TEXTURE_SPARSE_ARB, 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_NUM_SPARSE_LEVELS_ARB

Accepted by the pname 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 the pname 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 the pname 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 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_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-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