Class ARBBindlessTexture
- java.lang.Object
-
- org.lwjgl.opengl.ARBBindlessTexture
-
public class ARBBindlessTexture extends java.lang.Object
Native bindings to the ARB_bindless_texture extension.This extension allows OpenGL applications to access texture objects in shaders without first binding each texture to one of a limited number of texture image units. Using this extension, an application can query a 64-bit unsigned integer texture handle for each texture that it wants to access and then use that handle directly in GLSL or assembly-based shaders. The ability to access textures without having to bind and/or re-bind them is similar to the capability provided by the NV_shader_buffer_load extension that allows shaders to access buffer objects without binding them. In both cases, these extensions significantly reduce the amount of API and internal GL driver overhead needed to manage resource bindings.
This extension also provides similar capability for the image load, store, and atomic functionality provided by OpenGL 4.2 and the
ARB_shader_image_load_store
and EXT_shader_image_load_store extensions, where a texture can be accessed without first binding it to an image unit. An image handle can be extracted from a texture object using an API with a set of parameters similar to those for BindImageTextureEXT.This extension adds no new data types to GLSL. Instead, it uses existing sampler and image data types and allows them to be populated with texture and image handles. This extension does permit sampler and image data types to be used in more contexts than in unextended GLSL 4.00. In particular, sampler and image types may be used as shader inputs/outputs, temporary variables, and uniform block members, and may be assigned to by shader code. Constructors are provided to convert unsigned integer values to and from sampler and image data types. Additionally, new APIs are provided to load values for sampler and image uniforms with 64-bit handle inputs. The use of existing integer-based Uniform* APIs is still permitted, in which case the integer specified will identify a texture image or image unit. For samplers and images with values specified as texture image or image units, the GL implemenation will translate the unit number to an internal handle as required.
To access texture or image resources using handles, the handles must first be made resident. Accessing a texture or image by handle without first making it resident can result in undefined results, including program termination. Since the amount of texture memory required by an application may exceed the amount of memory available to the system, this extension provides API calls allowing applications to manage overall texture memory consumption by making a texture resident and non-resident as required.
Requires
OpenGL 4.0
.
-
-
Field Summary
Fields Modifier and Type Field and Description static int
GL_UNSIGNED_INT64_ARB
Accepted by thetype
parameter of VertexAttribLPointer.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method and Description static long
glGetImageHandleARB(int texture, int level, boolean layered, int layer, int format)
Creates and returns an image handle for levellevel
of the texture namedtexture
.static long
glGetTextureHandleARB(int texture)
Creates a texture handle using the current state of the texture namedtexture
, including any embedded sampler state.static long
glGetTextureSamplerHandleARB(int texture, int sampler)
Creates a texture handle using the current non-sampler state from the texture namedtexture
and the sampler state from the sampler objectsampler
.static long
glGetVertexAttribLui64ARB(int index, int pname)
Returns the 64-bit unsigned integer handle value of a generic vertex attribute parameter.static void
glGetVertexAttribLui64vARB(int index, int pname, long[] params)
Array version of:GetVertexAttribLui64vARB
static void
glGetVertexAttribLui64vARB(int index, int pname, java.nio.LongBuffer params)
Returns the 64-bit unsigned integer handle value of a generic vertex attribute parameter.static boolean
glIsImageHandleResidentARB(long handle)
ReturnsTRUE
if the specified image handle is resident in the current context.static boolean
glIsTextureHandleResidentARB(long handle)
ReturnsTRUE
if the specified texture handle is resident in the current context.static void
glMakeImageHandleNonResidentARB(long handle)
Makes an image handle inaccessible to shaders.static void
glMakeImageHandleResidentARB(long handle, int access)
Makes an image handle resident, so that it is accessible to shaders for image loads, stores, and atomic operations.static void
glMakeTextureHandleNonResidentARB(long handle)
Makes a texture handle inaccessible to shaders.static void
glMakeTextureHandleResidentARB(long handle)
Make a texture handle resident, so that it is accessible to shaders for texture mapping operations.static void
glProgramUniformHandleui64ARB(int program, int location, long value)
DSA version ofUniformHandleui64ARB
.static void
glProgramUniformHandleui64vARB(int program, int location, long[] values)
Array version of:ProgramUniformHandleui64vARB
static void
glProgramUniformHandleui64vARB(int program, int location, java.nio.LongBuffer values)
DSA version ofUniformHandleui64vARB
.static void
glUniformHandleui64ARB(int location, long value)
Loads a 64-bit unsigned integer handle into a uniform location corresponding to sampler or image variable types.static void
glUniformHandleui64vARB(int location, long[] values)
Array version of:UniformHandleui64vARB
static void
glUniformHandleui64vARB(int location, java.nio.LongBuffer values)
Loadscount
64-bit unsigned integer handles into a uniform location corresponding to sampler or image variable types.static void
glVertexAttribL1ui64ARB(int index, long x)
Specifies the 64-bit unsigned integer handle value of a generic vertex attribute.static void
glVertexAttribL1ui64vARB(int index, long[] v)
Array version of:VertexAttribL1ui64vARB
static void
glVertexAttribL1ui64vARB(int index, java.nio.LongBuffer v)
Pointer version ofVertexAttribL1ui64ARB
.
-
-
-
Field Detail
-
GL_UNSIGNED_INT64_ARB
public static final int GL_UNSIGNED_INT64_ARB
Accepted by thetype
parameter of VertexAttribLPointer.- See Also:
- Constant Field Values
-
-
Method Detail
-
glGetTextureHandleARB
public static long glGetTextureHandleARB(int texture)
Creates a texture handle using the current state of the texture namedtexture
, including any embedded sampler state. SeeGetTextureSamplerHandleARB
for details.- Parameters:
texture
- the texture object
-
glGetTextureSamplerHandleARB
public static long glGetTextureSamplerHandleARB(int texture, int sampler)
Creates a texture handle using the current non-sampler state from the texture namedtexture
and the sampler state from the sampler objectsampler
. In both cases, a 64-bit unsigned integer handle is returned. The errorINVALID_VALUE
is generated iftexture
is zero or is not the name of an existing texture object or ifsampler
is zero or is not the name of an existing sampler object. The errorINVALID_OPERATION
is generated if the texture objecttexture
is not complete. If an error occurs, a handle of zero is returned.The error
INVALID_OPERATION
is generated if the border color (taken from the embedded sampler for GetTextureHandleARB or from thesampler
for GetTextureSamplerHandleARB) is not one of the following allowed values. If the texture's base internal format is signed or unsigned integer, allowed values are (0,0,0,0), (0,0,0,1), (1,1,1,0), and (1,1,1,1). If the base internal format is not integer, allowed values are (0.0,0.0,0.0,0.0), (0.0,0.0,0.0,1.0), (1.0,1.0,1.0,0.0), and (1.0,1.0,1.0,1.0).The handle for each texture or texture/sampler pair is unique; the same handle will be returned if GetTextureHandleARB is called multiple times for the same texture or if GetTextureSamplerHandleARB is called multiple times for the same texture/sampler pair.
When a texture object is referenced by one or more texture handles, the texture parameters of the object may not be changed, and the size and format of the images in the texture object may not be re-specified. The error
INVALID_OPERATION
is generated if the functions TexImage*, CopyTexImage*, CompressedTexImage*, TexBuffer*, or TexParameter* are called to modify a texture object referenced by one or more texture handles. The contents of the images in a texture object may still be updated via commands such as TexSubImage*, CopyTexSubImage*, and CompressedTexSubImage*, and by rendering to a framebuffer object, even if the texture object is referenced by one or more texture handles.The error
INVALID_OPERATION
is generated byBufferData
if it is called to modify a buffer object bound to a buffer texture while that texture object is referenced by one or more texture handles. The contents of the buffer object may still be updated via buffer update commands such asBufferSubData
and MapBuffer*, or via the texture update commands, even if the buffer is bound to a texture while that buffer texture object is referenced by one or more texture handles.When a sampler object is referenced by one or more texture handles, the sampler parameters of the object may not be changed. The error
INVALID_OPERATION
is generated when calling SamplerParameter* functions to modify a sampler object referenced by one or more texture handles.- Parameters:
texture
- the texture objectsampler
- the sampler object
-
glMakeTextureHandleResidentARB
public static void glMakeTextureHandleResidentARB(long handle)
Make a texture handle resident, so that it is accessible to shaders for texture mapping operations.While the texture handle is resident, it may be used in texture mapping operations. If a shader attempts to perform a texture mapping operation using a handle that is not resident, the results of that operation are undefined and may lead to application termination. When a texture handle is resident, the texture it references is also considered resident for the purposes of the
AreTexturesResident
command. The errorINVALID_OPERATION
is generated ifhandle
is not a valid texture handle, or ifhandle
is already resident in the current GL context.- Parameters:
handle
- the texture handle
-
glMakeTextureHandleNonResidentARB
public static void glMakeTextureHandleNonResidentARB(long handle)
Makes a texture handle inaccessible to shaders.The error
INVALID_OPERATION
is generated ifhandle
is not a valid texture handle, or ifhandle
is not resident in the current GL context.- Parameters:
handle
- the texture handle
-
glGetImageHandleARB
public static long glGetImageHandleARB(int texture, int level, boolean layered, int layer, int format)
Creates and returns an image handle for levellevel
of the texture namedtexture
. Iflayered
isTRUE
, a handle is created for the entire texture level. Iflayered
isFALSE
, a handle is created for only the layerlayer
of the texture level.format
specifies a format used to interpret the texels of the image when used for image loads, stores, and atomics, and has the same meaning as theformat
parameter of BindImageTextureEXT(). A 64-bit unsigned integer handle is returned if the command succeeds; otherwise, zero is returned.The error
INVALID_VALUE
is generated by GetImageHandleARB if:texture
is zero or not the name of an existing texture object;- the image for the texture level
level
doesn't exist (i.e., has a size of zero intexture
); or layered
is FALSE andlayer
is greater than or equal to the number of layers in the image at levellevel
.
The error
INVALID_OPERATION
is generated by GetImageHandleARB if:- the texture object
texture
is not complete (section 3.9.14); layered
is TRUE and the texture is not a three-dimensional, one-dimensional array, two dimensional array, cube map, or cube map array texture.
When a texture object is referenced by one or more image handles, the texture parameters of the object may not be changed, and the size and format of the images in the texture object may not be re-specified. The error
INVALID_OPERATION
is generated when calling TexImage*, CopyTexImage*, CompressedTexImage*, TexBuffer*, or TexParameter* functions while a texture object is referenced by one or more image handles. The contents of the images in a texture object may still be updated via commands such as TexSubImage*, CopyTexSubImage*, and CompressedTexSubImage*, and by rendering to a framebuffer object, even if the texture object is referenced by one or more image handles.The error
INVALID_OPERATION
is generated byBufferData
if it is called to modify a buffer object bound to a buffer texture while that texture object is referenced by one or more image handles. The contents of the buffer object may still be updated via buffer update commands such asBufferSubData
and MapBuffer*, or via the texture update commands, even if the buffer is bound to a texture while that buffer texture object is referenced by one or more image handles.The handle returned for each combination of
texture
,level
,layered
,layer
, andformat
is unique; the same handle will be returned if GetImageHandleARB is called multiple times with the same parameters.- Parameters:
texture
- the texture objectlevel
- the texture levellayered
- the layered flaglayer
- the texture layerformat
- the texture format
-
glMakeImageHandleResidentARB
public static void glMakeImageHandleResidentARB(long handle, int access)
Makes an image handle resident, so that it is accessible to shaders for image loads, stores, and atomic operations.access
specifies whether the texture bound to the image handle will be treated asREAD_ONLY
,WRITE_ONLY
, orREAD_WRITE
. If a shader reads from an image handle made resident asWRITE_ONLY
, or writes to an image handle made resident asREAD_ONLY
, the results of that shader operation are undefined and may lead to application termination. The errorINVALID_OPERATION
is generated ifhandle
is not a valid image handle, or ifhandle
is already resident in the current GL context.While the image handle is resident, it may be used in image load, store, and atomic operations. If a shader attempts to perform an image operation using a handle that is not resident, the results of that operation are undefined and may lead to application termination. When an image handle is resident, the texture it references is not necessarily considered resident for the purposes of the
AreTexturesResident
command.- Parameters:
handle
- the image handleaccess
- the access type. One of:READ_ONLY
WRITE_ONLY
READ_WRITE
-
glMakeImageHandleNonResidentARB
public static void glMakeImageHandleNonResidentARB(long handle)
Makes an image handle inaccessible to shaders.- Parameters:
handle
- the image handle
-
glUniformHandleui64ARB
public static void glUniformHandleui64ARB(int location, long value)
Loads a 64-bit unsigned integer handle into a uniform location corresponding to sampler or image variable types.- Parameters:
location
- the uniform locationvalue
- the handle value
-
glUniformHandleui64vARB
public static void glUniformHandleui64vARB(int location, java.nio.LongBuffer values)
Loadscount
64-bit unsigned integer handles into a uniform location corresponding to sampler or image variable types.- Parameters:
location
- the uniform locationvalues
- a buffer from which to load the handles
-
glProgramUniformHandleui64ARB
public static void glProgramUniformHandleui64ARB(int program, int location, long value)
DSA version ofUniformHandleui64ARB
.- Parameters:
program
- the program objectlocation
- the uniform locationvalue
- the handle value
-
glProgramUniformHandleui64vARB
public static void glProgramUniformHandleui64vARB(int program, int location, java.nio.LongBuffer values)
DSA version ofUniformHandleui64vARB
.- Parameters:
program
- the program objectlocation
- the uniform locationvalues
- a buffer from which to load the handles
-
glIsTextureHandleResidentARB
public static boolean glIsTextureHandleResidentARB(long handle)
ReturnsTRUE
if the specified texture handle is resident in the current context.- Parameters:
handle
- the texture handle
-
glIsImageHandleResidentARB
public static boolean glIsImageHandleResidentARB(long handle)
ReturnsTRUE
if the specified image handle is resident in the current context.- Parameters:
handle
- the image handle
-
glVertexAttribL1ui64ARB
public static void glVertexAttribL1ui64ARB(int index, long x)
Specifies the 64-bit unsigned integer handle value of a generic vertex attribute.- Parameters:
index
- the index of the generic vertex attribute to be modifiedx
- the handle value
-
glVertexAttribL1ui64vARB
public static void glVertexAttribL1ui64vARB(int index, java.nio.LongBuffer v)
Pointer version ofVertexAttribL1ui64ARB
.- Parameters:
index
- the index of the generic vertex attribute to be modifiedv
- the vertex attribute buffer
-
glGetVertexAttribLui64vARB
public static void glGetVertexAttribLui64vARB(int index, int pname, java.nio.LongBuffer params)
Returns the 64-bit unsigned integer handle value of a generic vertex attribute parameter.- Parameters:
index
- the generic vertex attribute indexpname
- the parameter to queryparams
- a buffer in which to place the returned data
-
glGetVertexAttribLui64ARB
public static long glGetVertexAttribLui64ARB(int index, int pname)
Returns the 64-bit unsigned integer handle value of a generic vertex attribute parameter.- Parameters:
index
- the generic vertex attribute indexpname
- the parameter to query
-
glUniformHandleui64vARB
public static void glUniformHandleui64vARB(int location, long[] values)
Array version of:UniformHandleui64vARB
-
glProgramUniformHandleui64vARB
public static void glProgramUniformHandleui64vARB(int program, int location, long[] values)
Array version of:ProgramUniformHandleui64vARB
-
glVertexAttribL1ui64vARB
public static void glVertexAttribL1ui64vARB(int index, long[] v)
Array version of:VertexAttribL1ui64vARB
-
glGetVertexAttribLui64vARB
public static void glGetVertexAttribLui64vARB(int index, int pname, long[] params)
Array version of:GetVertexAttribLui64vARB
-
-