Top Description Fields Constructors Methods
org.lwjgl.opengl

public Class ARBBindlessTexture

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

Modifier and TypeField and Description
public static final int
GL_UNSIGNED_INT64_ARB

Accepted by the type parameter of VertexAttribLPointer.

Constructor Summary

AccessConstructor and Description
protected
ARBBindlessTexture()

Method Summary

Modifier and TypeMethod and Description
public static native long
glGetImageHandleARB(int
the texture object
texture, int
the texture level
level, boolean
the layered flag
layered, int
the texture layer
layer, int
the texture format
format)

Creates and returns an image handle for level level of the texture named texture.

public static native long
glGetTextureHandleARB(int
the texture object
texture)

Creates a texture handle using the current state of the texture named texture, including any embedded sampler state.

public static native long
glGetTextureSamplerHandleARB(int
the texture object
texture, int
the sampler object
sampler)

Creates a texture handle using the current non-sampler state from the texture named texture and the sampler state from the sampler object sampler.

public static long
glGetVertexAttribLui64ARB(int
the generic vertex attribute index
index, int
the parameter to query
pname)

Returns the 64-bit unsigned integer handle value of a generic vertex attribute parameter.

public static void
glGetVertexAttribLui64vARB(int
the generic vertex attribute index
index, int
the parameter to query
pname, LongBuffer
a buffer in which to place the returned data
params)

Returns the 64-bit unsigned integer handle value of a generic vertex attribute parameter.

public static void
glGetVertexAttribLui64vARB(int index, int pname, long[] params)

Array version of: GetVertexAttribLui64vARB

public static native boolean
glIsImageHandleResidentARB(long
the image handle
handle)

Returns TRUE if the specified image handle is resident in the current context.

public static native boolean
glIsTextureHandleResidentARB(long
the texture handle
handle)

Returns TRUE if the specified texture handle is resident in the current context.

public static native void
glMakeImageHandleNonResidentARB(long
the image handle
handle)

Makes an image handle inaccessible to shaders.

public static native void
glMakeImageHandleResidentARB(long
the image handle
handle, int
the access type. One of:
READ_ONLYWRITE_ONLYREAD_WRITE
access)

Makes an image handle resident, so that it is accessible to shaders for image loads, stores, and atomic operations.

public static native void
glMakeTextureHandleNonResidentARB(long
the texture handle
handle)

Makes a texture handle inaccessible to shaders.

public static native void
glMakeTextureHandleResidentARB(long
the texture handle
handle)

Make a texture handle resident, so that it is accessible to shaders for texture mapping operations.

public static native void
glProgramUniformHandleui64ARB(int
the program object
program, int
the uniform location
location, long
the handle value
value)

DSA version of UniformHandleui64ARB.

public static void
glProgramUniformHandleui64vARB(int
the program object
program, int
the uniform location
location, LongBuffer
a buffer from which to load the handles
values)

DSA version of UniformHandleui64vARB.

public static void
glProgramUniformHandleui64vARB(int program, int location, long[] values)

Array version of: ProgramUniformHandleui64vARB

public static native void
glUniformHandleui64ARB(int
the uniform location
location, long
the handle value
value)

Loads a 64-bit unsigned integer handle into a uniform location corresponding to sampler or image variable types.

public static void
glUniformHandleui64vARB(int
the uniform location
location, LongBuffer
a buffer from which to load the handles
values)

Loads count 64-bit unsigned integer handles into a uniform location corresponding to sampler or image variable types.

public static void
glUniformHandleui64vARB(int location, long[] values)

Array version of: UniformHandleui64vARB

public static native void
glVertexAttribL1ui64ARB(int
the index of the generic vertex attribute to be modified
index, long
the handle value
x)

Specifies the 64-bit unsigned integer handle value of a generic vertex attribute.

public static void
glVertexAttribL1ui64vARB(int
the index of the generic vertex attribute to be modified
index, LongBuffer
the vertex attribute buffer
v)

Pointer version of VertexAttribL1ui64ARB.

public static void
glVertexAttribL1ui64vARB(int index, long[] v)

Array version of: VertexAttribL1ui64vARB

public static native void
nglGetVertexAttribLui64vARB(int index, int pname, long params)

Unsafe version of: GetVertexAttribLui64vARB

public static native void
nglProgramUniformHandleui64vARB(int program, int location, int
the number of handles to load
count, long values)

Unsafe version of: ProgramUniformHandleui64vARB

public static native void
nglUniformHandleui64vARB(int location, int
the number of handles to load
count, long values)

Unsafe version of: UniformHandleui64vARB

public static native void
nglVertexAttribL1ui64vARB(int index, long v)

Unsafe version of: VertexAttribL1ui64vARB

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

GL_UNSIGNED_INT64_ARBback to summary
public static final int GL_UNSIGNED_INT64_ARB

Accepted by the type parameter of VertexAttribLPointer.

Constructor Detail

ARBBindlessTextureback to summary
protected ARBBindlessTexture()

Method Detail

glGetImageHandleARBback to summary
public static native long glGetImageHandleARB(int texture, int level, boolean layered, int layer, int format)

Creates and returns an image handle for level level of the texture named texture. If layered is TRUE, a handle is created for the entire texture level. If layered is FALSE, a handle is created for only the layer layer 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 the format 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 in texture); or
  • layered is FALSE and layer is greater than or equal to the number of layers in the image at level level.

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 by BufferData 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 as BufferSubData 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, and format is unique; the same handle will be returned if GetImageHandleARB is called multiple times with the same parameters.

Parameters
texture:int

the texture object

level:int

the texture level

layered:boolean

the layered flag

layer:int

the texture layer

format:int

the texture format

Annotations
@NativeType:GLuint64
glGetTextureHandleARBback to summary
public static native long glGetTextureHandleARB(int texture)

Creates a texture handle using the current state of the texture named texture, including any embedded sampler state. See GetTextureSamplerHandleARB for details.

Parameters
texture:int

the texture object

Annotations
@NativeType:GLuint64
glGetTextureSamplerHandleARBback to summary
public static native long glGetTextureSamplerHandleARB(int texture, int sampler)

Creates a texture handle using the current non-sampler state from the texture named texture and the sampler state from the sampler object sampler. In both cases, a 64-bit unsigned integer handle is returned. The error INVALID_VALUE is generated if texture is zero or is not the name of an existing texture object or if sampler is zero or is not the name of an existing sampler object. The error INVALID_OPERATION is generated if the texture object texture 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 the sampler 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 by BufferData 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 as BufferSubData 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:int

the texture object

sampler:int

the sampler object

Annotations
@NativeType:GLuint64
glGetVertexAttribLui64ARBback to summary
public static long glGetVertexAttribLui64ARB(int index, int pname)

Returns the 64-bit unsigned integer handle value of a generic vertex attribute parameter.

Parameters
index:int

the generic vertex attribute index

pname:int

the parameter to query

Annotations
@NativeType:void
glGetVertexAttribLui64vARBback to summary
public static void glGetVertexAttribLui64vARB(int index, int pname, LongBuffer params)

Returns the 64-bit unsigned integer handle value of a generic vertex attribute parameter.

Parameters
index:int

the generic vertex attribute index

pname:int

the parameter to query

params:LongBuffer

a buffer in which to place the returned data

glGetVertexAttribLui64vARBback to summary
public static void glGetVertexAttribLui64vARB(int index, int pname, long[] params)

Array version of: GetVertexAttribLui64vARB

glIsImageHandleResidentARBback to summary
public static native boolean glIsImageHandleResidentARB(long handle)

Returns TRUE if the specified image handle is resident in the current context.

Parameters
handle:long

the image handle

Annotations
@NativeType:GLboolean
glIsTextureHandleResidentARBback to summary
public static native boolean glIsTextureHandleResidentARB(long handle)

Returns TRUE if the specified texture handle is resident in the current context.

Parameters
handle:long

the texture handle

Annotations
@NativeType:GLboolean
glMakeImageHandleNonResidentARBback to summary
public static native void glMakeImageHandleNonResidentARB(long handle)

Makes an image handle inaccessible to shaders.

Parameters
handle:long

the image handle

glMakeImageHandleResidentARBback to summary
public static native 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 as READ_ONLY, WRITE_ONLY, or READ_WRITE. If a shader reads from an image handle made resident as WRITE_ONLY, or writes to an image handle made resident as READ_ONLY, the results of that shader operation are undefined and may lead to application termination. The error INVALID_OPERATION is generated if handle is not a valid image handle, or if handle 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:long

the image handle

access:int

the access type. One of:

READ_ONLYWRITE_ONLYREAD_WRITE
glMakeTextureHandleNonResidentARBback to summary
public static native void glMakeTextureHandleNonResidentARB(long handle)

Makes a texture handle inaccessible to shaders.

The error INVALID_OPERATION is generated if handle is not a valid texture handle, or if handle is not resident in the current GL context.

Parameters
handle:long

the texture handle

glMakeTextureHandleResidentARBback to summary
public static native 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 error INVALID_OPERATION is generated if handle is not a valid texture handle, or if handle is already resident in the current GL context.

Parameters
handle:long

the texture handle

glProgramUniformHandleui64ARBback to summary
public static native void glProgramUniformHandleui64ARB(int program, int location, long value)

DSA version of UniformHandleui64ARB.

Parameters
program:int

the program object

location:int

the uniform location

value:long

the handle value

glProgramUniformHandleui64vARBback to summary
public static void glProgramUniformHandleui64vARB(int program, int location, LongBuffer values)

DSA version of UniformHandleui64vARB.

Parameters
program:int

the program object

location:int

the uniform location

values:LongBuffer

a buffer from which to load the handles

glProgramUniformHandleui64vARBback to summary
public static void glProgramUniformHandleui64vARB(int program, int location, long[] values)

Array version of: ProgramUniformHandleui64vARB

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

the uniform location

value:long

the handle value

glUniformHandleui64vARBback to summary
public static void glUniformHandleui64vARB(int location, LongBuffer values)

Loads count 64-bit unsigned integer handles into a uniform location corresponding to sampler or image variable types.

Parameters
location:int

the uniform location

values:LongBuffer

a buffer from which to load the handles

glUniformHandleui64vARBback to summary
public static void glUniformHandleui64vARB(int location, long[] values)

Array version of: UniformHandleui64vARB

glVertexAttribL1ui64ARBback to summary
public static native void glVertexAttribL1ui64ARB(int index, long x)

Specifies the 64-bit unsigned integer handle value of a generic vertex attribute.

Parameters
index:int

the index of the generic vertex attribute to be modified

x:long

the handle value

glVertexAttribL1ui64vARBback to summary
public static void glVertexAttribL1ui64vARB(int index, LongBuffer v)

Pointer version of VertexAttribL1ui64ARB.

Parameters
index:int

the index of the generic vertex attribute to be modified

v:LongBuffer

the vertex attribute buffer

glVertexAttribL1ui64vARBback to summary
public static void glVertexAttribL1ui64vARB(int index, long[] v)

Array version of: VertexAttribL1ui64vARB

nglGetVertexAttribLui64vARBback to summary
public static native void nglGetVertexAttribLui64vARB(int index, int pname, long params)

Unsafe version of: GetVertexAttribLui64vARB

nglProgramUniformHandleui64vARBback to summary
public static native void nglProgramUniformHandleui64vARB(int program, int location, int count, long values)

Unsafe version of: ProgramUniformHandleui64vARB

Parameters
count:int

the number of handles to load

nglUniformHandleui64vARBback to summary
public static native void nglUniformHandleui64vARB(int location, int count, long values)

Unsafe version of: UniformHandleui64vARB

Parameters
count:int

the number of handles to load

nglVertexAttribL1ui64vARBback to summary
public static native void nglVertexAttribL1ui64vARB(int index, long v)

Unsafe version of: VertexAttribL1ui64vARB