Top Description Fields Constructors Methods
org.lwjgl.opengl

public Class KHRRobustness

extends Object
Class Inheritance
Imports
java.nio.*, org.lwjgl.system.*

Native bindings to the KHR_robustness extension.

Several recent trends in how OpenGL ES integrates into modern computer systems have created new requirements for robustness and security for GL rendering contexts.

Additionally GPU architectures now support hardware fault detection; for example, video memory supporting ECC (error correcting codes) and error detection. GL contexts should be capable of recovering from hardware faults such as uncorrectable memory errors. Along with recovery from such hardware faults, the recovery mechanism can also allow recovery from video memory access exceptions and system software failures. System software failures can be due to device changes or driver failures.

GL queries that return (write) some number of bytes to a buffer indicated by a pointer parameter introduce risk of buffer overflows that might be exploitable by malware. To address this, queries with return value sizes that are not expressed directly by the parameters to the query itself are given additional API functions with an additional parameter that specifies the number of bytes in the buffer and never writing bytes beyond that limit. This is particularly useful for multi-threaded usage of GL contexts in a "share group" where one context can change objects in ways that can cause buffer overflows for another context's GL queries.

The original ARB_vertex_buffer_object extension includes an issue that explicitly states program termination is allowed when out-of-bounds vertex buffer object fetches occur. Modern graphics hardware is capable of well-defined behavior in the case of out-of- bounds vertex buffer object fetches. Older hardware may require extra checks to enforce well-defined (and termination free) behavior, but this expense is warranted when processing potentially untrusted content.

The intent of this extension is to address some specific robustness goals:

Requires OpenGL 3.2.

Field Summary

Modifier and TypeField and Description
public static final int
public static final int
GL_CONTEXT_ROBUST_ACCESS

Accepted by the value parameter of GetBooleanv, GetIntegerv, and GetFloatv.

public static final int
public static final int
public static final int
GL_LOSE_CONTEXT_ON_RESET

Returned by GetIntegerv and related simple queries when value is RESET_NOTIFICATION_STRATEGY.

public static final int
public static final int
GL_NO_RESET_NOTIFICATION

Returned by GetIntegerv and related simple queries when value is RESET_NOTIFICATION_STRATEGY.

public static final int
GL_RESET_NOTIFICATION_STRATEGY

Accepted by the value parameter of GetBooleanv, GetIntegerv, and GetFloatv.

public static final int

Constructor Summary

AccessConstructor and Description
protected

Method Summary

Modifier and TypeMethod and Description
public static int
glGetGraphicsResetStatus()

Indicates if the GL context has been in a reset state at any point since the last call to GetGraphicsResetStatus:

  • NO_ERROR indicates that the GL context has not been in a reset state since the last call.
  • GUILTY_CONTEXT_RESET indicates that a reset has been detected that is attributable to the current GL context.
  • INNOCENT_CONTEXT_RESET indicates a reset has been detected that is not attributable to the current GL context.
  • UNKNOWN_CONTEXT_RESET indicates a detected graphics reset whose cause is unknown.
public static float
glGetnUniformf(int
the program object
program
,
int
the uniform location
location
)

Returns the value or values of a uniform of the default uniform block.

public static void
glGetnUniformfv(int
the program object
program
,
int
the uniform location
location
,
FloatBuffer
the buffer in which to place the returned data
params
)

Returns the value or values of a uniform of the default uniform block.

public static void
glGetnUniformfv(int program, int location, float[] params)

Array version of: GetnUniformfv

public static int
glGetnUniformi(int
the program object
program
,
int
the uniform location
location
)

Integer version of GetnUniformfv.

public static void
glGetnUniformiv(int
the program object
program
,
int
the uniform location
location
,
IntBuffer
the buffer in which to place the returned data
params
)

Integer version of GetnUniformfv.

public static void
glGetnUniformiv(int program, int location, int[] params)

Array version of: GetnUniformiv

public static int
glGetnUniformui(int
the program object
program
,
int
the uniform location
location
)

Unsigned version of GetnUniformiv.

public static void
glGetnUniformuiv(int
the program object
program
,
int
the uniform location
location
,
IntBuffer
the buffer in which to place the returned data
params
)

Unsigned version of GetnUniformiv.

public static void
glGetnUniformuiv(int program, int location, int[] params)

Array version of: GetnUniformuiv

public static void
glReadnPixels(int
the left pixel coordinate
x
,
int
the lower pixel coordinate
y
,
int
the number of pixels to read in the x-dimension
width
,
int
the number of pixels to read in the y-dimension
height
,
int format, int type, int
the maximum number of bytes to write into data
bufSize
,
long
a buffer in which to place the returned pixel data
pixels
)

Behaves identically to ReadPixels except that it does not write more than bufSize bytes into data

public static void
public static void
public static void
public static void
public static void
glReadnPixels(int x, int y, int width, int height, int format, int type, short[] pixels)

Array version of: ReadnPixels

public static void
glReadnPixels(int x, int y, int width, int height, int format, int type, int[] pixels)

Array version of: ReadnPixels

public static void
glReadnPixels(int x, int y, int width, int height, int format, int type, float[] pixels)

Array version of: ReadnPixels

public static void
nglGetnUniformfv(int program, int location, int
the maximum number of bytes to write to params
bufSize
,
long params)

Unsafe version of: GetnUniformfv

public static void
nglGetnUniformiv(int program, int location, int
the maximum number of bytes to write to params
bufSize
,
long params)

Unsafe version of: GetnUniformiv

public static void
nglGetnUniformuiv(int program, int location, int
the maximum number of bytes to write to params
bufSize
,
long params)

Unsafe version of: GetnUniformuiv

public static void
nglReadnPixels(int x, int y, int width, int height, int format, int type, int
the maximum number of bytes to write into data
bufSize
,
long pixels)

Unsafe version of: ReadnPixels

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

GL_CONTEXT_LOSTback to summary
public static final int GL_CONTEXT_LOST

Returned by GetError.

GL_CONTEXT_ROBUST_ACCESSback to summary
public static final int GL_CONTEXT_ROBUST_ACCESS

Accepted by the value parameter of GetBooleanv, GetIntegerv, and GetFloatv.

GL_GUILTY_CONTEXT_RESETback to summary
public static final int GL_GUILTY_CONTEXT_RESET

Returned by GetGraphicsResetStatus.

GL_INNOCENT_CONTEXT_RESETback to summary
public static final int GL_INNOCENT_CONTEXT_RESET

Returned by GetGraphicsResetStatus.

GL_LOSE_CONTEXT_ON_RESETback to summary
public static final int GL_LOSE_CONTEXT_ON_RESET

Returned by GetIntegerv and related simple queries when value is RESET_NOTIFICATION_STRATEGY.

GL_NO_ERRORback to summary
public static final int GL_NO_ERROR

Returned by GetGraphicsResetStatus.

GL_NO_RESET_NOTIFICATIONback to summary
public static final int GL_NO_RESET_NOTIFICATION

Returned by GetIntegerv and related simple queries when value is RESET_NOTIFICATION_STRATEGY.

GL_RESET_NOTIFICATION_STRATEGYback to summary
public static final int GL_RESET_NOTIFICATION_STRATEGY

Accepted by the value parameter of GetBooleanv, GetIntegerv, and GetFloatv.

GL_UNKNOWN_CONTEXT_RESETback to summary
public static final int GL_UNKNOWN_CONTEXT_RESET

Returned by GetGraphicsResetStatus.

Constructor Detail

KHRRobustnessback to summary
protected KHRRobustness()

Method Detail

glGetGraphicsResetStatusback to summary
public static int glGetGraphicsResetStatus()

Indicates if the GL context has been in a reset state at any point since the last call to GetGraphicsResetStatus:

  • NO_ERROR indicates that the GL context has not been in a reset state since the last call.
  • GUILTY_CONTEXT_RESET indicates that a reset has been detected that is attributable to the current GL context.
  • INNOCENT_CONTEXT_RESET indicates a reset has been detected that is not attributable to the current GL context.
  • UNKNOWN_CONTEXT_RESET indicates a detected graphics reset whose cause is unknown.

If a reset status other than NO_ERROR is returned and subsequent calls return NO_ERROR, the context reset was encountered and completed. If a reset status is repeatedly returned, the context may be in the process of resetting.

Reset notification behavior is determined at context creation time, and may be queried by calling GetIntegerv with the symbolic constant RESET_NOTIFICATION_STRATEGY.

If the reset notification behavior is NO_RESET_NOTIFICATION, then the implementation will never deliver notification of reset events, and GetGraphicsResetStatus will always return NO_ERROR.

If the behavior is LOSE_CONTEXT_ON_RESET, a graphics reset will result in a lost context and require creating a new context as described above. In this case GetGraphicsResetStatus will return an appropriate value from those described above.

If a graphics reset notification occurs in a context, a notification must also occur in all other contexts which share objects with that context.

After a graphics reset has occurred on a context, subsequent GL commands on that context (or any context which shares with that context) will generate a CONTEXT_LOST error. Such commands will not have side effects (in particular, they will not modify memory passed by pointer for query results, and may not block indefinitely or cause termination of the application. Exceptions to this behavior include:

  • GetError and GetGraphicsResetStatus behave normally following a graphics reset, so that the application can determine a reset has occurred, and when it is safe to destroy and recreate the context.
  • Any commands which might cause a polling application to block indefinitely will generate a CONTEXT_LOST error, but will also return a value indicating completion to the application.
Annotations
@NativeType:GLenum
glGetnUniformfback to summary
public static float glGetnUniformf(int program, int location)

Returns the value or values of a uniform of the default uniform block.

Parameters
program:int

the program object

location:int

the uniform location

Annotations
@NativeType:void
glGetnUniformfvback to summary
public static void glGetnUniformfv(int program, int location, FloatBuffer params)

Returns the value or values of a uniform of the default uniform block.

Parameters
program:int

the program object

location:int

the uniform location

params:FloatBuffer

the buffer in which to place the returned data

glGetnUniformfvback to summary
public static void glGetnUniformfv(int program, int location, float[] params)

Array version of: GetnUniformfv

glGetnUniformiback to summary
public static int glGetnUniformi(int program, int location)

Integer version of GetnUniformfv.

Parameters
program:int

the program object

location:int

the uniform location

Annotations
@NativeType:void
glGetnUniformivback to summary
public static void glGetnUniformiv(int program, int location, IntBuffer params)

Integer version of GetnUniformfv.

Parameters
program:int

the program object

location:int

the uniform location

params:IntBuffer

the buffer in which to place the returned data

glGetnUniformivback to summary
public static void glGetnUniformiv(int program, int location, int[] params)

Array version of: GetnUniformiv

glGetnUniformuiback to summary
public static int glGetnUniformui(int program, int location)

Unsigned version of GetnUniformiv.

Parameters
program:int

the program object

location:int

the uniform location

Annotations
@NativeType:void
glGetnUniformuivback to summary
public static void glGetnUniformuiv(int program, int location, IntBuffer params)

Unsigned version of GetnUniformiv.

Parameters
program:int

the program object

location:int

the uniform location

params:IntBuffer

the buffer in which to place the returned data

glGetnUniformuivback to summary
public static void glGetnUniformuiv(int program, int location, int[] params)

Array version of: GetnUniformuiv

glReadnPixelsback to summary
public static void glReadnPixels(int x, int y, int width, int height, int format, int type, int bufSize, long pixels)

Behaves identically to ReadPixels except that it does not write more than bufSize bytes into data

Parameters
x:int

the left pixel coordinate

y:int

the lower pixel coordinate

width:int

the number of pixels to read in the x-dimension

height:int

the number of pixels to read in the y-dimension

format:int

the pixel format. One of:

REDGREENBLUEALPHARGRGBRGBABGR
BGRARED_INTEGERGREEN_INTEGERBLUE_INTEGERALPHA_INTEGERRG_INTEGERRGB_INTEGERRGBA_INTEGER
BGR_INTEGERBGRA_INTEGERSTENCIL_INDEXDEPTH_COMPONENTDEPTH_STENCILLUMINANCELUMINANCE_ALPHA
type:int

the pixel type. One of:

UNSIGNED_BYTEBYTEUNSIGNED_SHORTSHORT
UNSIGNED_INTINTHALF_FLOATFLOAT
UNSIGNED_BYTE_3_3_2UNSIGNED_BYTE_2_3_3_REVUNSIGNED_SHORT_5_6_5UNSIGNED_SHORT_5_6_5_REV
UNSIGNED_SHORT_4_4_4_4UNSIGNED_SHORT_4_4_4_4_REVUNSIGNED_SHORT_5_5_5_1UNSIGNED_SHORT_1_5_5_5_REV
UNSIGNED_INT_8_8_8_8UNSIGNED_INT_8_8_8_8_REVUNSIGNED_INT_10_10_10_2UNSIGNED_INT_2_10_10_10_REV
UNSIGNED_INT_24_8UNSIGNED_INT_10F_11F_11F_REVUNSIGNED_INT_5_9_9_9_REVFLOAT_32_UNSIGNED_INT_24_8_REV
BITMAP
bufSize:int

the maximum number of bytes to write into data

pixels:long

a buffer in which to place the returned pixel data

glReadnPixelsback to summary
public static void glReadnPixels(int x, int y, int width, int height, int format, int type, ByteBuffer pixels)

Behaves identically to ReadPixels except that it does not write more than bufSize bytes into data

Parameters
x:int

the left pixel coordinate

y:int

the lower pixel coordinate

width:int

the number of pixels to read in the x-dimension

height:int

the number of pixels to read in the y-dimension

format:int

the pixel format. One of:

REDGREENBLUEALPHARGRGBRGBABGR
BGRARED_INTEGERGREEN_INTEGERBLUE_INTEGERALPHA_INTEGERRG_INTEGERRGB_INTEGERRGBA_INTEGER
BGR_INTEGERBGRA_INTEGERSTENCIL_INDEXDEPTH_COMPONENTDEPTH_STENCILLUMINANCELUMINANCE_ALPHA
type:int

the pixel type. One of:

UNSIGNED_BYTEBYTEUNSIGNED_SHORTSHORT
UNSIGNED_INTINTHALF_FLOATFLOAT
UNSIGNED_BYTE_3_3_2UNSIGNED_BYTE_2_3_3_REVUNSIGNED_SHORT_5_6_5UNSIGNED_SHORT_5_6_5_REV
UNSIGNED_SHORT_4_4_4_4UNSIGNED_SHORT_4_4_4_4_REVUNSIGNED_SHORT_5_5_5_1UNSIGNED_SHORT_1_5_5_5_REV
UNSIGNED_INT_8_8_8_8UNSIGNED_INT_8_8_8_8_REVUNSIGNED_INT_10_10_10_2UNSIGNED_INT_2_10_10_10_REV
UNSIGNED_INT_24_8UNSIGNED_INT_10F_11F_11F_REVUNSIGNED_INT_5_9_9_9_REVFLOAT_32_UNSIGNED_INT_24_8_REV
BITMAP
pixels:ByteBuffer

a buffer in which to place the returned pixel data

glReadnPixelsback to summary
public static void glReadnPixels(int x, int y, int width, int height, int format, int type, ShortBuffer pixels)

Behaves identically to ReadPixels except that it does not write more than bufSize bytes into data

Parameters
x:int

the left pixel coordinate

y:int

the lower pixel coordinate

width:int

the number of pixels to read in the x-dimension

height:int

the number of pixels to read in the y-dimension

format:int

the pixel format. One of:

REDGREENBLUEALPHARGRGBRGBABGR
BGRARED_INTEGERGREEN_INTEGERBLUE_INTEGERALPHA_INTEGERRG_INTEGERRGB_INTEGERRGBA_INTEGER
BGR_INTEGERBGRA_INTEGERSTENCIL_INDEXDEPTH_COMPONENTDEPTH_STENCILLUMINANCELUMINANCE_ALPHA
type:int

the pixel type. One of:

UNSIGNED_BYTEBYTEUNSIGNED_SHORTSHORT
UNSIGNED_INTINTHALF_FLOATFLOAT
UNSIGNED_BYTE_3_3_2UNSIGNED_BYTE_2_3_3_REVUNSIGNED_SHORT_5_6_5UNSIGNED_SHORT_5_6_5_REV
UNSIGNED_SHORT_4_4_4_4UNSIGNED_SHORT_4_4_4_4_REVUNSIGNED_SHORT_5_5_5_1UNSIGNED_SHORT_1_5_5_5_REV
UNSIGNED_INT_8_8_8_8UNSIGNED_INT_8_8_8_8_REVUNSIGNED_INT_10_10_10_2UNSIGNED_INT_2_10_10_10_REV
UNSIGNED_INT_24_8UNSIGNED_INT_10F_11F_11F_REVUNSIGNED_INT_5_9_9_9_REVFLOAT_32_UNSIGNED_INT_24_8_REV
BITMAP
pixels:ShortBuffer

a buffer in which to place the returned pixel data

glReadnPixelsback to summary
public static void glReadnPixels(int x, int y, int width, int height, int format, int type, IntBuffer pixels)

Behaves identically to ReadPixels except that it does not write more than bufSize bytes into data

Parameters
x:int

the left pixel coordinate

y:int

the lower pixel coordinate

width:int

the number of pixels to read in the x-dimension

height:int

the number of pixels to read in the y-dimension

format:int

the pixel format. One of:

REDGREENBLUEALPHARGRGBRGBABGR
BGRARED_INTEGERGREEN_INTEGERBLUE_INTEGERALPHA_INTEGERRG_INTEGERRGB_INTEGERRGBA_INTEGER
BGR_INTEGERBGRA_INTEGERSTENCIL_INDEXDEPTH_COMPONENTDEPTH_STENCILLUMINANCELUMINANCE_ALPHA
type:int

the pixel type. One of:

UNSIGNED_BYTEBYTEUNSIGNED_SHORTSHORT
UNSIGNED_INTINTHALF_FLOATFLOAT
UNSIGNED_BYTE_3_3_2UNSIGNED_BYTE_2_3_3_REVUNSIGNED_SHORT_5_6_5UNSIGNED_SHORT_5_6_5_REV
UNSIGNED_SHORT_4_4_4_4UNSIGNED_SHORT_4_4_4_4_REVUNSIGNED_SHORT_5_5_5_1UNSIGNED_SHORT_1_5_5_5_REV
UNSIGNED_INT_8_8_8_8UNSIGNED_INT_8_8_8_8_REVUNSIGNED_INT_10_10_10_2UNSIGNED_INT_2_10_10_10_REV
UNSIGNED_INT_24_8UNSIGNED_INT_10F_11F_11F_REVUNSIGNED_INT_5_9_9_9_REVFLOAT_32_UNSIGNED_INT_24_8_REV
BITMAP
pixels:IntBuffer

a buffer in which to place the returned pixel data

glReadnPixelsback to summary
public static void glReadnPixels(int x, int y, int width, int height, int format, int type, FloatBuffer pixels)

Behaves identically to ReadPixels except that it does not write more than bufSize bytes into data

Parameters
x:int

the left pixel coordinate

y:int

the lower pixel coordinate

width:int

the number of pixels to read in the x-dimension

height:int

the number of pixels to read in the y-dimension

format:int

the pixel format. One of:

REDGREENBLUEALPHARGRGBRGBABGR
BGRARED_INTEGERGREEN_INTEGERBLUE_INTEGERALPHA_INTEGERRG_INTEGERRGB_INTEGERRGBA_INTEGER
BGR_INTEGERBGRA_INTEGERSTENCIL_INDEXDEPTH_COMPONENTDEPTH_STENCILLUMINANCELUMINANCE_ALPHA
type:int

the pixel type. One of:

UNSIGNED_BYTEBYTEUNSIGNED_SHORTSHORT
UNSIGNED_INTINTHALF_FLOATFLOAT
UNSIGNED_BYTE_3_3_2UNSIGNED_BYTE_2_3_3_REVUNSIGNED_SHORT_5_6_5UNSIGNED_SHORT_5_6_5_REV
UNSIGNED_SHORT_4_4_4_4UNSIGNED_SHORT_4_4_4_4_REVUNSIGNED_SHORT_5_5_5_1UNSIGNED_SHORT_1_5_5_5_REV
UNSIGNED_INT_8_8_8_8UNSIGNED_INT_8_8_8_8_REVUNSIGNED_INT_10_10_10_2UNSIGNED_INT_2_10_10_10_REV
UNSIGNED_INT_24_8UNSIGNED_INT_10F_11F_11F_REVUNSIGNED_INT_5_9_9_9_REVFLOAT_32_UNSIGNED_INT_24_8_REV
BITMAP
pixels:FloatBuffer

a buffer in which to place the returned pixel data

glReadnPixelsback to summary
public static void glReadnPixels(int x, int y, int width, int height, int format, int type, short[] pixels)

Array version of: ReadnPixels

glReadnPixelsback to summary
public static void glReadnPixels(int x, int y, int width, int height, int format, int type, int[] pixels)

Array version of: ReadnPixels

glReadnPixelsback to summary
public static void glReadnPixels(int x, int y, int width, int height, int format, int type, float[] pixels)

Array version of: ReadnPixels

nglGetnUniformfvback to summary
public static void nglGetnUniformfv(int program, int location, int bufSize, long params)

Unsafe version of: GetnUniformfv

Parameters
bufSize:int

the maximum number of bytes to write to params

nglGetnUniformivback to summary
public static void nglGetnUniformiv(int program, int location, int bufSize, long params)

Unsafe version of: GetnUniformiv

Parameters
bufSize:int

the maximum number of bytes to write to params

nglGetnUniformuivback to summary
public static void nglGetnUniformuiv(int program, int location, int bufSize, long params)

Unsafe version of: GetnUniformuiv

Parameters
bufSize:int

the maximum number of bytes to write to params

nglReadnPixelsback to summary
public static void nglReadnPixels(int x, int y, int width, int height, int format, int type, int bufSize, long pixels)

Unsafe version of: ReadnPixels

Parameters
bufSize:int

the maximum number of bytes to write into data