Name
ARB_robustness
Name Strings
GL_ARB_robustness
Contributors
Acorn Pooley, NVIDIA
Anton Staaf, Google
Barthold Lichtenbelt, NVIDIA
Bruce Merry, ARM
Chris Marrin, Apple
Greg Roth, NVIDIA
Jeff Bolz, NVIDIA
Jon Leech
Kenneth Russell, Google
Kent Miller, Apple
Piers Daniell, NVIDIA
Vladimir Vukicevic, Mozilla
Contact
Mark Kilgard, NVIDIA (mjk 'at' nvidia.com)
Notice
Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete. Approved by the ARB on June 9, 2010.
Approved by the Khronos Board of Promoters on July 23, 2010.
Version
Last Modified Date: June 25, 2014
Version: 18
Number
ARB Extension #105
Dependencies
This extension is written against the OpenGL 3.2 Compatibility
Profile Specification but can apply to OpenGL 1.1 and up.
This specification interacts with the ARB_imaging subset of the OpenGL
3.2 Compatibility Profile.
This specification interacts with the OpenGL 3.2 Core Profile.
This specification interacts with EXT_direct_state_access.
GLX_ARB_create_context_robustness and
WGL_ARB_create_context_robustness are used to determine if a context
implementing this extension supports robust buffer access, and if it
supports reset notification. Equivalent platform-dependent
mechanisms in other window-system integration layers such as EGL and
AGL may exist for those platforms.
Overview
Several recent trends in how OpenGL integrates into modern computer
systems have created new requirements for robustness and security
for OpenGL rendering contexts.
Additionally GPU architectures now support hardware fault detection;
for example, video memory supporting ECC (error correcting codes)
and error detection. OpenGL 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.
Demands for increased software robustness and concerns about malware
exploiting buffer overflows have lead API designers to provide
additional "safe" APIs that bound the amount of data returned by
an API query. For example, the safer "snprintf" or "_snprintf"
routines are prefered over "sprintf".
The OpenGL API has many such robustness perils. OpenGL queries
return (write) some number of bytes to a buffer indicated by a
pointer parameter. The exact number of bytes written by existing
OpenGL queries is not expressed directly by any specific parameter;
instead the number of bytes returned is a complex function of one
or more query arguments, sometimes context state such as pixel
store modes or the active texture selector, and the current state
of an object (such as a texture level's number of total texels).
By the standards of modern API design, such queries are not "safe".
Making these queries safer involves introducing a new query API with
an additional parameter that specifies the number of bytes in the
buffer and never writing bytes beyond that limit.
Multi-threaded use of OpenGL contexts in a "share group" allow
sharing of objects such as textures and programs. Such sharing in
conjunction with concurrent OpenGL commands stream execution by two
or more contexts introduces hazards whereby one context can change
objects in ways that can cause buffer overflows for another context's
OpenGL 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 GPUs
capable of DirectX 10 enforce the well-defined behavior of always
returning zero values for indices or non-fixed components in this
case. Older GPUs 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:
* For all existing OpenGL queries, provide additional "safe" APIs
that limit data written to user pointers to a buffer size in
bytes that is an explicit additional parameter of the query.
* Provide a mechanism for an OpenGL application to learn about
graphics resets that affect the context. When a graphics reset
occurs, the OpenGL context becomes unusable and the application
must create a new context to continue operation. Detecting a
graphics reset happens through an inexpensive query.
* Provide an enable to guarantee that out-of-bounds buffer object
accesses by the GPU will have deterministic behavior and preclude
application instability or termination due to an incorrect buffer
access. Such accesses include vertex buffer fetches of
attributes and indices, and indexed reads of uniforms or
parameters from buffers.
In one anticipated usage model, WebGL contexts may make use of these
robust features to grant greater stability when using untrusted code.
WebGL contexts cannot call OpenGL commands directly but rather must
route all OpenGL API calls through the web browser. It is then the
web browser that configures the context, using the commands in this
extension, to enforce safe behavior. In this scenario, the WebGL
content cannot specify or change the use of this extension's features
itself; the web browser enforces this policy.
There are other well-known robustness issues with the OpenGL API
which this extension does not address. For example, selector-based
OpenGL commands are a well-known source of programming errors.
Code to manipulate texture state may assume the active texture
selector is set appropriately when an intervening function call
obscures a change to the active texture state resulting in
incorrectly updated or queried state. The EXT_direct_state_access
extension introduces selector-free OpenGL commands and queries to
address that particular issue so this extension does not.
The intent of this extension is NOT to deprecate any existing API
and thereby introduce compatibility issues and coding burdens on
existing code, but rather to provide new APIs to ensure a level of
robustness commensurate with the expectations of modern applications
of OpenGL.
IP Status
No known IP claims.
New Procedures and Functions
GRAPHICS RESET DETECTION AND RECOVERY
enum GetGraphicsResetStatusARB();
SIZED BUFFER QUERIES
OpenGL 1.0 sized buffer queries
void GetnMapdvARB(enum target, enum query, sizei bufSize, double *v);
void GetnMapfvARB(enum target, enum query, sizei bufSize, float *v);
void GetnMapivARB(enum target, enum query, sizei bufSize, int *v);
void GetnPixelMapfvARB(enum map, sizei bufSize, float *values);
void GetnPixelMapuivARB(enum map, sizei bufSize, uint *values);
void GetnPixelMapusvARB(enum map, sizei bufSize, ushort *values);
void GetnPolygonStippleARB(sizei bufSize, ubyte *pattern);
void GetnTexImageARB(enum target, int level, enum format,
enum type, sizei bufSize, void *img);
void ReadnPixelsARB(int x, int y, sizei width, sizei height,
enum format, enum type, sizei bufSize,
void *data);
ARB_imaging sized buffer queries
void GetnColorTableARB(enum target, enum format, enum type,
sizei bufSize, void *table);
void GetnConvolutionFilterARB(enum target, enum format,
enum type, sizei bufSize, void *image);
void GetnSeparableFilterARB(enum target, enum format, enum type,
sizei rowBufSize, void *row,
sizei columnBufSize, void *column,
void *span);
void GetnHistogramARB(enum target, boolean reset, enum format,
enum type, sizei bufSize, void *values);
void GetnMinmaxARB(enum target, boolean reset, enum format,
enum type, sizei bufSize, void *values);
OpenGL 1.3 sized buffer queries
void GetnCompressedTexImageARB(enum target, int lod,
sizei bufSize, void *img);
OpenGL 2.0 sized buffer queries
void GetnUniformfvARB(uint program, int location, sizei bufSize,
float *params);
void GetnUniformivARB(uint program, int location, sizei bufSize,
int *params);
void GetnUniformuivARB(uint program, int location, sizei bufSize,
uint *params);
void GetnUniformdvARB(uint program, int location, sizei bufSize,
double *params);
New Tokens
Returned by GetGraphicsResetStatusARB:
NO_ERROR 0x0000
GUILTY_CONTEXT_RESET_ARB 0x8253
INNOCENT_CONTEXT_RESET_ARB 0x8254
UNKNOWN_CONTEXT_RESET_ARB 0x8255
Accepted by the <value> parameter of GetBooleanv, GetIntegerv,
GetInteger64v, GetFloatv, and GetDoublev:
RESET_NOTIFICATION_STRATEGY_ARB 0x8256
Returned by GetIntegerv and related simple queries when
<value> is RESET_NOTIFICATION_STRATEGY_ARB:
LOSE_CONTEXT_ON_RESET_ARB 0x8252
NO_RESET_NOTIFICATION_ARB 0x8261
Returned by GetIntegerv when <pname> is CONTEXT_FLAGS:
CONTEXT_FLAG_ROBUST_ACCESS_BIT_ARB 0x00000004
Additions to Chapter 2 of the OpenGL 3.2 (Compatibility Profile)
Specification (OpenGL Operation)
Add a new subsection after 2.5 "GL Errors" and renumber subsequent
sections accordingly
2.6 "Graphics Reset Recovery"
Certain events can result in a reset of the GL context. Such a reset
causes all context state to be lost. Recovery from such events
requires recreation of all objects in the affected context. The
current status of the graphics reset state is returned by
enum GetGraphicsResetStatusARB();
The symbolic constant returned indicates if the GL context has been
in a reset state at any point since the last call to
GetGraphicsResetStatusARB. NO_ERROR indicates that the GL context
has not been in a reset state since the last call.
GUILTY_CONTEXT_RESET_ARB indicates that a reset has been detected
that is attributable to the current GL context.
INNOCENT_CONTEXT_RESET_ARB indicates a reset has been detected that
is not attributable to the current GL context.
UNKNOWN_CONTEXT_RESET_ARB 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_ARB.
If the reset notification behavior is NO_RESET_NOTIFICATION_ARB,
then the implementation will never deliver notification of reset
events, and GetGraphicsResetStatusARB will always return
NO_ERROR[fn1].
[fn1: In this case it is recommended that implementations should
not allow loss of context state no matter what events occur.
However, this is only a recommendation, and cannot be relied
upon by applications.]
If the behavior is LOSE_CONTEXT_ON_RESET_ARB, a graphics reset will
result in the loss of all context state, requiring the recreation of
all associated objects. In this case GetGraphicsResetStatusARB. may
return any of the values 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[fn2].
[fn2: The values returned by GetGraphicsResetStatusARB in the
different contexts may differ.]
Add to Section 2.8 "Vertex Arrays" before 2.8.1 "Drawing Commands"
Robust buffer access is enabled by creating a context with robust
access enabled through the window system binding APIs. When enabled,
indices within the vertex array that lie outside the arrays defined
for enabled attributes result in undefined values for the
corresponding attributes, but cannot result in application failure.
Additions to Chapter 3 of the OpenGL 3.2 (Compatibility Profile)
Specification (Rasterization)
None
Additions to Chapter 4 of the OpenGL 3.2 (Compatibility Profile)
Specification (Per-Fragment Operations and the Frame Buffer)
Modify section 4.3.2 "Reading Pixels"
Pixels are read using
void ReadPixels(int x, int y, sizei width, sizei height,
enum format, enum type, void *data);
void ReadnPixelsARB(int x, int y, sizei width, sizei height,
enum format, enum type, sizei bufSize,
void *data);
The arguments after <x> and <y> to ReadPixels are described in
section 3.7.4. The pixel storage modes that apply to ReadPixels and
other commands that query images (see section 6.1) are summarized in
table 4.7. ReadnPixelsARB behaves identically to ReadPixels except
that it does not write more than <bufSize> bytes into <data>.
Additions to Chapter 5 of the OpenGL 3.2 (Compatibility Profile)
Specification (Special Functions)
None
Additions to Chapter 6 of the OpenGL 3.2 (Compatibility Profile)
Specification (State and State Requests)
Modify Section 6.1.3 "Enumerated Queries"
void GetPixelMap{ui us f}v(enum map, T data);
void GetnPixelMap{ui us f}vARB(enum map, sizei bufSize, T data);
return all values in the pixel map <map> in <data>. <map> must be
a map name from table 3.3. GetPixelMapuiv, GetnPixelMapuivARB,
GetPixelMapusv, and GetnPixelMapusvARB convert floating point pixel
map values to integers according to the UNSIGNED_INT and
UNSIGNED_SHORT entries, respectively, of table 4.9.
GetnPixelMap{ui us f}vARB does not write more than <bufSize>
bytes into <data>.
If a pixel pack buffer ...
... an INVALID_OPERATIONS_ERROR results. When calling
GetnPixelMap{ui us f}vARB, if a pixel pack buffer object is bound
and <n> is greater than <bufSize>, but <data>+<n> does not exceed
the size of the buffer, no error results.
...
void GetMap{ifd}v(enum map, enum value, T data);
void GetnMap{ifd}vARB(enum map, enum value, sizei bufSize, T data);
places information about <value> for <map> in <data>. <map> must
be one of the map types described in section 5.1, and <value> must
be one of ORDER, COEFF, or DOMAIN. GetnMap{ifd}vARB does not write
more than <bufSize> bytes into <data>.
Section 6.1.4 "Texture Queries"
Modify the description of GetTexImage:
"The commands
void GetTexImage(enum tex, int lod, enum format, enum type,
void *img );
void GetnTexImageARB(enum tex, int lod, enum format, enum type,
sizei bufSize, void *img );
are used to obtain texture images. ...
... <type> is a pixel type from table 3.5. GetnTexImageARB does
not write more than <bufSize> bytes into <img>."
Add to the end of the sixth paragraph:
"When calling GetnTextureImageARB, if a pixel pack buffer object
is bound and packing a texture image into buffer memory would
exceed <bufSize> but not the size of the buffer, no error results."
Modify the description of GetCompressedTexImage:
"The commands
void GetCompressedTexImage(enum target, int lod, void *img);
void GetnCompressedTexImageARB(enum target, int lod, sizei bufSize,
void *img );
are used to obtain texture images stored in compressed form. The
parameters <target>, <lod>, and <img> are interpreted in the same
manner as in GetTexImage and GetnTexImageARB respectively. When
called, GetCompressedTexImage and GetnCompressedTexImageARB write
MIN(n,bufSize) ubytes of compressed image data ...
... If a pixel pack buffer object is bound and img + n is greater
than the size of the buffer, an INVALID_OPERATION error results.
When calling GetnCompressedTextureImageARB, if a pixel pack buffer
object is bound and <n> is greater than <bufSize> but <img>+<n>
does not exceed the size of the buffer, no error results."
Modify Section 6.1.5 "Stipple Query"
The commands
void GetPolygonStipple(void *pattern);
void GetnPolygonStippleARB(sizei bufSize, void *pattern);
obtain the polygon stipple. The pattern is packed into pixel pack
buffer or client memory according to the procedure given in section
4.3.2 for ReadPixels; it is as if the <height> and <width> passed
to that command were both equal to 32, the type were BITMAP, and
the format were COLOR_INDEX. GetnPolygonStippleARB does not write
more than <bufSize> bytes into <pattern>.
Modify Section 6.1.7 "Color Table Query"
The current contents of a color table are queried using
void GetColorTable(enum target, enum format, enum type,
void *table );
void GetnColorTableARB(enum target, enum format, enum type,
sizei bufSize, void *table);
<target> must be one of the regular color table names listed in
table 3.4. ...
... to the components requested by format are described in table
6.1. GetnColorTableARB does not write more than <bufSize> bytes
into <table>.
Modify Section 6.1.8 "Convolution Query"
The current contents of a convolution filter image are queried
with the command
void GetConvolutionFilter(enum target, enum format, enum type,
void *image );
void GetnConvolutionFilterARB(enum target, enum format,
enum type, sizei bufSize, void *image);
<target> must be CONVOLUTION_1D or CONVOLUTION_2D. ...
... Pixel processing and component mapping are identical to those
of GetTexImage. GetnConvolutionFilterARB does not write more than
<bufSize> bytes into <image>.
...
The current contents of a separable filter image are queried using
void GetSeparableFilter(enum target, enum format, enum type,
void *row, void *column, void *span );
void GetnSeparableFilterARB(enum target, enum format, enum type,
sizei rowBufSize, void *row,
sizei columnBufSize, void *column,
void *span);
... The row and column images are returned to pixel pack buffer or
client memory starting at row and column respectively.
GetnSeparableFilterARB does not write more than <rowBufSize> bytes
into <row> and no more than <columnBufSize> bytes into <column>.
<span> is currently unused. ...
Modify Section 6.1.9 "Histogram Query"
The current contents of the histogram table are queried using
void GetHistogram(enum target, boolean reset, enum format,
enum type, void* values );
void GetnHistogramARB(enum target, boolean reset, enum format,
enum type, sizei bufSize, void* values);
... component values are simply clamped to the range of the target
data type. GetnHistogramARB does not write more than <bufSize>
bytes into <values>.
Modify Section 6.1.10 "Minmax Query"
The current contents of the minmax table are queried using
void GetMinmax(enum target, boolean reset, enum format,
enum type, void* values );
void GetnMinmaxARB(enum target, boolean reset, enum format,
enum type, sizei bufSize, void* values);
... A one-dimensional image of width 2 is returned to pixel pack
buffer or client memory starting at <values>. GetnMinmaxARB does
not write more than <bufSize> bytes into <values>.
Modify Section 6.1.11 "Pointer and String Queries"
Add to the paragraph describing the context profile mask and flags
(preceding the description of GetStringi) on page 379:
"If CONTEXT_FLAG_ROBUST_ACCESS_BIT_ARB is set in CONTEXT_FLAGS,
then robust buffer access will be enabled for drawing commands
using vertex arrays, as described in section 2.8."
Modify Section 6.1.16 "Shader and Program Queries"
The commands
void GetUniformfv(uint program, int location, float *params);
void GetnUniformfvARB(uint program, int location, sizei bufSize,
float *params);
void GetUniformiv(uint program, int location, int *params);
void GetnUniformivARB(uint program, int location, sizei bufSize,
int *params);
void GetUniformuiv(uint program, int location, uint *params);
void GetnUniformuivARB(uint program, int location, sizei bufSize,
uint *params);
void GetUniformdv(uint program, int location, double *params);
void GetnUniformdvARB(uint program, int location, sizei bufSize,
double *params);
return the value or values of the uniform at location location of
the default uniform block for program object program in the array
params. GetnUniformfvARB, GetnUniformivARB, GetnUniformuivARB and
GetnUniformdvARB do not write any data to <params> if <bufSize> is
less than the size of the requested data.
...
Additions to the AGL/GLX/WGL Specifications
None
Additions to The OpenGL Shading Language Specification, Version 1.50.11
Change the first paragraph of section 4.1.9 "Arrays"
... Undefined behavior results from indexing an array with a
non-constant expression that's greater than or equal to the array's
size or less than 0. If robust buffer access is enabled via the
OpenGL API, such indexing must not result in abnormal program
termination. The results are still undefined, but implementations
are encouraged to produce zero values for such accesses. Only
one-dimensional arrays may be declared. ...
GLX Protocol
XXX
Interactions with GLX_ARB_create_context_robustness
If the GLX window-system binding API is used to create a context,
the GLX_ARB_create_context_robustness extension is supported, and
the bit GLX_CONTEXT_ROBUST_ACCESS_BIT_ARB is set in
GLX_CONTEXT_FLAGS when glXCreateContextAttribsARB is called, the
resulting context will perform robust buffer access as described
above in section 2.8, and the CONTEXT_FLAG_ROBUST_ACCESS_BIT_ARB bit
will be set in CONTEXT_FLAGS as described above in section 6.1.11.
If the GLX window-system binding API is used to create a context and
the GLX_ARB_create_context_robustness extension is supported, then
the value of attribute GLX_CONTEXT_RESET_NOTIFICATION_STRATEGY_ARB
determines the reset notification behavior and the value of
RESET_NOTIFICATION_STRATEGY_ARB, as described in section 2.6.
Interactions with WGL_ARB_create_context_robustness
If the WGL window-system binding API is used to create a context,
the WGL_ARB_create_context_robustness extension is supported, and
the bit WGL_CONTEXT_ROBUST_ACCESS_BIT_ARB is set in
WGL_CONTEXT_FLAGS when wglCreateContextAttribsARB is called, the
resulting context will perform robust buffer access as described
above in section 2.8, and the CONTEXT_FLAG_ROBUST_ACCESS_BIT_ARB bit
will be set in CONTEXT_FLAGS as described above in section 6.1.11.
If the WGL window-system binding API is used to create a context and
the WGL_ARB_create_context_robustness extension is supported, then
the value of attribute WGL_CONTEXT_RESET_NOTIFICATION_STRATEGY_ARB
determines the reset notification behavior and the value of
RESET_NOTIFICATION_STRATEGY_ARB, as described in section 2.6.
Errors
GetnMapdvARB, GetnMapfvARB, GetnMapivARB, GetnPixelMapfvARB,
GetnPixelMapuivARB, GetnPixelMapusvARB, GetnPolygonStippleARB,
GetnTexImageARB, ReadnPixelsARB, GetnColorTableARB,
GetnConvolutionFilterARB, GetnSeparableFilterARB, GetnHistogramARB,
GetnMinmaxARB, GetnCompressedTexImageARB, GetnUniformfvARB,
GetnUniformivARB, GetnUniformuivARB and GetnUniformdvARB share all the
errors of their unsized buffer query counterparts with the addition
that INVALID_OPERATION is generated if the buffer size required to
fill all the requested data is greater than <bufSize>.
New State
Get Value Type Get Command Value Description Sec Attribute
-------------------------- ---- ----------- ------------ --------------------------- ------ ---------
RESET_NOTIFICATION_STRATEGY_ARB Z_2 GetIntegerv See sec. 2.6 Reset notification behavior 2.6 -
New Implementation Dependent State
None
Dependencies on the ARB_imaging subset
If the ARB_imaging subset of the OpenGL 3.2 Compatibility Profile is not
supported, the commands GetnColorTableARB, GetnConvolutionFilterARB,
GetnHistogramARB, GetnMap*ARB, GetnMinmaxARB, GetnPixelMap*ARB, and
GetnSeparableFilterARB defined by this extension are not supported, and
all references to them should be ignored.
Dependencies on OpenGL 3.2 (Core Profile)
If only the core profile of OpenGL 3.2 is supported, the commands
GetnColorTableARB, GetnConvolutionFilterARB, GetnHistogramARB,
GetnMap*ARB, GetnMinmaxARB, GetnPixelMap*ARB, GetnPolygonStippleARB, and
GetnSeparableFilterARB defined by this extension are not supported, and
all references to them should be ignored.
Issues
1. Does robust buffer access affect vertex pulling from vertex
buffer objects, client vertex arrays, or both?
RESOLVED: Only vertex buffer objects.
DirectX 10-era GPUs are guaranteed to provide guarantees
consistent with those required by robust buffer access.
Client memory vertex arrays should not be expected to be used
directly in situations requiring robust operation.
Historically the original EXT_vertex_array extension provided a
"GLsizei count" parameter to indicate how long vertex arrays
should be. This proved to be unworkable in practice because
applications typically found it too difficult to properly compute
the count; instead a very large integer was passed, obviating any
practical use for the parameter. When vertex arrays were added
to core OpenGL in version 1.1, the "GLsizei count" parameter
was eliminated for this reason.
There are other problems too. Clever applications using client
memory vertex arrays can specify the base pointer to be NULL
(address 0) and then use indices that essentially correspond
to pointers divided by the stride. There's also no guarantee a
pointer itself has a contiguous range of memory allocate within
a given range.
Moreover client memory vertex arrays are no longer a performance
path so they simply are not particularly interesting to address.
The result is there's really no practical way to bound client
vertex array access in a way that's likely to be practically
useful.
Vertex buffer objects do not have this same problem because
buffer objects have a bounded index-able range.
Robust applications should simply use vertex buffer objects for
robust vertex pulling (ignoring client memory vertex arrays for
an rendering that must be done robustly).
2. If robust buffer access is supported and a vertex index is large
enough to fetch beyond the size of an enabled vertex buffer
object, what happens?
RESOLVED: Undefined values are read for the varying (non-fixed)
components.
A fixed-component would be a component such as the W component
when only a 2- or 3-component position is fetched. In this case,
the W component is fixed as 1.0 and that will be the case still
if the index would have resulted in an out-of-bounds fetch.
Undefined results are required for implementations that can't
guarantee any particular value. It make testing this behavior
difficult, but it's required for certain implementations.
3. If robust buffer access is supported and an element array buffer
is accessed beyond the size of the element array buffer so
there's not a valide index, what happens?
RESOLVED: The value of the index is undefined.
Undefined results are required for implementations that can't
guarantee any particular value. It make testing this behavior
difficult, but it's required for certain implementations.
4. What query commands actually need a new "GLsizei bufSize"
parameter?
RESOLVED: If the number of bytes returned by the query is not
*completely* determined by the parameters to the function (in
the absence of errors) and not already bounded by an existing
GLsizei buffer size parameter, a new query is needed.
This means commands such as glGetClipPlane, glGetIntegerv,
etc. do NOT need new versions.
This means queries that depend on pixel store pack state need
new queries. Examples: glReadPixels, glGetPolygonStipple,
glGetTexImage, glGetConvolutionFilter, etc.
This means queries that query an object's state which can
vary in size need new queries. Examples: glGetTexImage,
glGetCompressedTexImage, glGetUniformfv, glGetUniformuiv, etc.
This means queries that query context state which can vary
depending on other context state variables need new queries.
Examples: glGetHistogram, glGetPixelMapfv, glGetColorTable, etc.
If the command already has a parameter that limits the amount
of data returned through a pointer, no new command is needed.
Examples: glGetActiveAttrib, glGetActiveUniform, glGetInfoLog,
glGetAttachedShaders, glGetAttachedObjects, glGetShaderSource,
glGetActiveAttrib, glGetBufferSubData, glGen*, etc.
5. If a new query with an explicit buffer size is called and the buffer
size is not sufficient to return the data, what happens?
RESOLVED: Return an INVALID_OPERATION error and ignore the query.
Some consideration was given to clearing the entire buffer range.
This might arguably avoid applications subsequently reading from
uninitialized buffers.
This was rejected for several reasons:
1) Doing something when there's an error is inconsistent with
the rest of OpenGL's operation.
2) If the buffer is left untouched, the application can initialize
the buffer to some bogus value (NaN or an invalid negative
value) and notice that the buffer was left unmodified after
the query without the expense of checking for OpenGL errors.
3) Many commands return information through packing pixels based
on the pixel store state. The pixel store state allows skipping
over some data (GL_SKIP_PIXELS, GL_SKIP_ROWS, etc.) so zero'ing
memory for the entire buffer isn't a good idea.
6. Can you explain why various glGet queries do NOT have new
"sized" versions?
RESOLVED:
Queries always returning a constant number of bytes:
OpenGL 1.0
glGetClipPlane
- always 4*sizeof(GLdouble)
OpenGL 2.0
glGetVertexAttribdv
- always 4*sizeof(GLdouble)
glGetVertexAttribfv
- always 4*sizeof(GLfloat)
glGetVertexAttribiv
- always 4*sizeof(GLint)
Queries with an effective buffer size parameter already:
OpenGL 1.5
glGetBufferSubData
- returns size (parameter) bytes
Queries with an effective buffer bound (no more bytes than)
parameter already:
OpenGL 2.0
glGetAttachedShaders
- returns no more than sizeof(GLuint)*maxCount
to count and no more than sizeof(GLuint)*maxCount
to shaders
glGetShaderInfoLog
glGetProgramInfoLog
glGetShaderSource
glGetActiveAttrib
glGetActiveUniform
- returns no more than bufSize bytes
OpenGL 3.0
glGetTransformFeedbackVarying
- returns no more than bufSize bytes
OpenGL 3.2
glGetUniformIndices
- returns sizeof(GLuint)*uniformCount bytes
glGetActiveUniformName
glGetActiveUniformBlockName
- returns no more than bufSize bytes
Query's some function of enumeration parameters fully determine
the number bytes returned:
OpenGL 1.0
glGetIntegerv
glGetFloatv
glGetDoublev
glGetBooleanv
glGetLightiv
glGetLightfv
glGetMaterialfv
glGetMaterialiv
glGetTexEnvfv
glGetTexEnviv
glGetTexGendv
glGetTexGenfv
glGetTexGeniv
glGetTexParameterfv
glGetTexParameteriv
glGetTexLevelParameterfv
glGetTexLevelParameteriv
- fully determined by pname parameter
OpenGL 1.1
glGetPointerv
- fully determined by pname parameter
glGenTextures
- sizeof(GLuint)*n
ARB_imaging
glGetColorTableParameterfv
glGetColorTableParameteriv
glGetConvolutionParameterfv
glGetConvolutionParameteriv
glGetHistogramParameterfv
glGetHistogramParameteriv
glGetMinmaxParameterfv
glGetMinmaxParameteriv
- fully determined by pname parameter
OpenGL 1.5
glGenBuffers
glGenQueries
- sizeof(GLuint)*n
glGetBufferParameteriv
glGetQueryObjectiv
glGetQueryObjectfv
glGetQueryiv
- fully determined by pname parameter
OpenGL 2.0
glGetVertexAttribPointerv
glGetShaderiv
glGetProgramiv
- fully determined by pname parameter
OpenGL 3.0
glGenRenderbuffers
glGenFramebuffers
glGenVertexArrays
- sizeof(GLuint)*n
OpenGL 3.2
glGetActiveUniformBlockiv
- function of pname and uniformCount
glGetActiveUniformsiv
- function of pname
NV_vertex_program
glGenProgramsNV
- sizeof(GLuint)*n
ARB_vertex_program
glGenProgramsARB
- sizeof(GLuint)*n
7. What can cause a graphics reset?
Either user or implementor errors may result in a graphics reset.
If the application attempts to perform a rendering that takes too long
whether due to an infinite loop in a shader or even just a rendering
operation that takes too long on the given hardware. Implementation
errors may produce badly formed hardware commands. Memory access errors
may result from user or implementor mistakes. Any of these events may
result in a graphics reset event that will be detectable by the mechanism
described in this extension.
8. How should the application react to a reset context event?
RESOLVED: For this extension, the application is expected to query
the reset status until NO_ERROR is returned. If a reset is encountered,
at least one *RESET* status will be returned. Once NO_ERROR is
encountered, the application can safely destroy the old context and
create a new one.
After a reset event, apps should not use a context for any purpose
other than determining its reset status, and then destroying it. If a
context receives a reset event, all other contexts in its share group
will also receive reset events, and should be destroyed and
recreated.
Apps should be cautious in interpreting the GUILTY and INNOCENT reset
statuses. These are guidelines to the immediate cause of a reset, but
not guarantees of the ultimate cause.
9. If a graphics reset occurs in a shared context, what happens in
shared contexts?
RESOLVED: A reset in one context will result in a reset in all other
contexts in its share group. This is mandated, not recommended
behavior as of revision 14.
10. How can an application query for robust buffer access support,
since this is now determined at context creation time?
RESOLVED. The application can query the CONTEXT_FLAGS bitfield
using GetIntegerv and check for the presence of CONTEXT_FLAG_-
ROBUST_ACCESS_BIT_ARB.
11. How is the reset notification behavior controlled?
RESOLVED: Reset notification behavior is determined at context
creation time using GLX/WGL/etc. mechanisms. In order that shared
objects be handled predictably, a context cannot share with
another context unless both have the same reset notification
behavior.
Revision History
Rev. Date Author Changes
---- ------------ --------- --------------------------------------------
18 25 Jun 2014 Jon Leech Fix type of <params> in Get*Uniformdv.
17 17 Sep 2012 Jon Leech Clarify that GetnUniform* does not write
any data if bufSize is less than required
(Bug 8739).
16 25 Jun 2012 Jon Leech Add interactions with ARB_imaging and
core profile.
15 10 Apr 2012 Jon Leech Fix description of INVALID_OPERATION
error to be when required data size is
*greater* than bufSize, not *less*.
14 22 Jul 2010 Jon Leech Require resets to be delivered to all
contexts which share objects. Expand on
recommended recovery behavior in Issues 8
and 9. Assign enum for new token.
13 21 Jul 2010 Jon Leech Remove RequestGraphicsResetNotificationARB
and determine graphics reset notification
behavior at context creation time in
separate GLX/WGL extensions.
12 19 Jul 2010 pdaniell Added missing GetnUniformdARB. Add additional
language to the "Graphics Reset Recovery"
section to clarify objects of shared contexts.
Revert revision #7 changes to restore the
old "bufSize" behavior and remove the new
"length" parameter, both of which proved
problematic with implementation. Truncating
the output buffer data written to "bufSize"
length is hard to implement efficiently in
software and impossible with some hardware
paths. Also the additional "length" parameter
caused PBO based async calls to become sync,
which is undesirable.
11 07 Jun 2010 groth Clarify PBO errors/sized queries interaction
Make consistent the app response to a reset
Resolve issue 10 per revision 10 changes.
10 07 Jun 2010 Jon Leech Add a bit to the context flags query
indicating whether or not robust buffer
access was enabled at context creation.
9 06 Jun 2010 Jon Leech Note interactions with context creation
extensions enabling robust buffer
access, and add issue 10 regarding
queries for robust buffer access.
Remove dangling references to old
ROBUST_BUFFER_ACCESS token.
8 21 May 2010 groth bmerry comment response
Restore ARB suffixes in light of rejection from core
7 20 May 2010 groth Allow bounds checking using context creation flag
Fix issues.
Revise bounded queries to take and return lengths.
Add query for current reset strategy.
72 column resizing.
6 06 May 2010 groth ARBify, catch a few sized gets that hadn't
been named correctly.
5 05 May 2010 groth Add clarification regarding recovered reset
detection.
4 02 May 2010 groth Remove references to deleted functionality.
Add issue addressing differences with
3 15 Apr 2010 groth Describe GLSL array behavior when using
robust arrays.
Add issue explaining graphics reset causes.
2 22 Mar 2010 groth Flesh out missing secions. Remove vestiges of
specified limits API. Rename sized queries.
Various grammar corrections and clarifications.
1 19 Jan 2010 mjk Initial version