| Name | |
| EXT_robustness | |
| Name Strings | |
| GL_EXT_robustness | |
| Contributors | |
| Daniel Koch, TransGaming | |
| Nicolas Capens, TransGaming | |
| Contributors to ARB_robustness | |
| Contact | |
| Greg Roth, NVIDIA (groth 'at' nvidia.com) | |
| Status | |
| Complete. | |
| Version | |
| Version 3, 2011/10/31 | |
| Number | |
| OpenGL ES Extension #107 | |
| Dependencies | |
| This extension is written against the OpenGL ES 2.0 Specification | |
| but can apply to OpenGL ES 1.1 and up. | |
| EGL_EXT_create_context_robustness is used to determine if a context | |
| implementing this extension supports robust buffer access, and if it | |
| supports reset notification. | |
| 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. | |
| OpenGL queries that 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 OpenGL contexts | |
| in a "share group" where 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 graphics | |
| hardware is capable 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: | |
| * 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. | |
| New Procedures and Functions | |
| enum GetGraphicsResetStatusEXT(); | |
| void ReadnPixelsEXT(int x, int y, sizei width, sizei height, | |
| enum format, enum type, sizei bufSize, | |
| void *data); | |
| void GetnUniformfvEXT(uint program, int location, sizei bufSize, | |
| float *params); | |
| void GetnUniformivEXT(uint program, int location, sizei bufSize, | |
| int *params); | |
| New Tokens | |
| Returned by GetGraphicsResetStatusEXT: | |
| NO_ERROR 0x0000 | |
| GUILTY_CONTEXT_RESET_EXT 0x8253 | |
| INNOCENT_CONTEXT_RESET_EXT 0x8254 | |
| UNKNOWN_CONTEXT_RESET_EXT 0x8255 | |
| Accepted by the <value> parameter of GetBooleanv, GetIntegerv, | |
| and GetFloatv: | |
| CONTEXT_ROBUST_ACCESS_EXT 0x90F3 | |
| RESET_NOTIFICATION_STRATEGY_EXT 0x8256 | |
| Returned by GetIntegerv and related simple queries when <value> is | |
| RESET_NOTIFICATION_STRATEGY_EXT : | |
| LOSE_CONTEXT_ON_RESET_EXT 0x8252 | |
| NO_RESET_NOTIFICATION_EXT 0x8261 | |
| Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES 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 GetGraphicsResetStatusEXT(); | |
| The symbolic constant returned indicates if the GL context has been | |
| in a reset state at any point since the last call to | |
| GetGraphicsResetStatusEXT. NO_ERROR indicates that the GL context | |
| has not been in a reset state since the last call. | |
| GUILTY_CONTEXT_RESET_EXT indicates that a reset has been detected | |
| that is attributable to the current GL context. | |
| INNOCENT_CONTEXT_RESET_EXT indicates a reset has been detected that | |
| is not attributable to the current GL context. | |
| UNKNOWN_CONTEXT_RESET_EXT 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_EXT. | |
| If the reset notification behavior is NO_RESET_NOTIFICATION_EXT, | |
| then the implementation will never deliver notification of reset | |
| events, and GetGraphicsResetStatusEXT 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_EXT, a graphics reset will | |
| result in the loss of all context state, requiring the recreation of | |
| all associated objects. In this case GetGraphicsResetStatusEXT 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 GetGraphicsResetStatusEXT in the | |
| different contexts may differ.] | |
| Add to Section 2.8 "Vertex Arrays" before subsection "Transferring | |
| Array Elements" | |
| 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. | |
| Robust buffer access behavior may be queried by calling GetIntegerv | |
| with the symbolic constant CONTEXT_ROBUST_ACCESS_EXT. | |
| Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment | |
| Operations and the Frame Buffer) | |
| Modify section 4.3.1 "Reading Pixels" | |
| Pixels are read using | |
| void ReadPixels(int x, int y, sizei width, sizei height, | |
| enum format, enum type, void *data); | |
| void ReadnPixelsEXT(int x, int y, sizei width, sizei height, | |
| enum format, enum type, sizei bufSize, | |
| void *data); | |
| Add to the description of ReadPixels: | |
| ReadnPixelsEXT behaves identically to ReadPixels except that it does | |
| not write more than <bufSize> bytes into <data>. If the buffer size | |
| required to fill all the requested data is greater than <bufSize> an | |
| INVALID_OPERATION error is generated and <data> is not altered. | |
| Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special | |
| Functions): | |
| None | |
| Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and | |
| State Requests) | |
| Modify Section 6.1.8 "Shader and Program Queries" | |
| The commands | |
| void GetUniformfv(uint program, int location, float *params); | |
| void GetnUniformfvEXT(uint program, int location, sizei bufSize, | |
| float *params); | |
| void GetUniformiv(uint program, int location, int *params); | |
| void GetnUniformivEXT(uint program, int location, sizei bufSize, | |
| int *params); | |
| return the value or values of the uniform at location <location> | |
| for program object <program> in the array <params>. Calling | |
| GetnUniformfvEXT or GetnUniformivEXT ensures that no more than | |
| <bufSize> bytes are written into <params>. If the buffer size | |
| required to fill all the requested data is greater than <bufSize> an | |
| INVALID_OPERATION error is generated and <params> is not altered. | |
| ... | |
| Additions to The OpenGL ES Shading Language Specification, Version 1. | |
| Append to the third paragraph of section 4.1.9 "Arrays" | |
| If robust buffer access is enabled via the OpenGL ES 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. | |
| Interactions with EGL_EXT_create_context_robustness | |
| If the EGL window-system binding API is used to create a context, | |
| the EGL_EXT_create_context_robustness extension is supported, and | |
| the attribute EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT is set to | |
| EGL_TRUE when eglCreateContext is called, the resulting context will | |
| perform robust buffer access as described above in section 2.8, and | |
| the CONTEXT_ROBUST_ACCESS_EXT query will return GL_TRUE as described | |
| above in section 6.1.5. | |
| If the EGL window-system binding API is used to create a context and | |
| the EGL_EXT_create_context_robustness extension is supported, then | |
| the value of attribute EGL_CONTEXT_RESET_NOTIFICATION_STRATEGY_EXT | |
| determines the reset notification behavior and the value of | |
| RESET_NOTIFICATION_STRATEGY_EXT, as described in section 2.6. | |
| Errors | |
| ReadnPixelsEXT, GetnUniformfvEXT, and GetnUniformivEXT 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 Implementation Dependent State | |
| Get Value Type Get Command Minimum Value Description Sec. Attribute | |
| --------- ---- ----------- ------------- --------------------------- ----- --------- | |
| CONTEXT_ROBUST_ACCESS_EXT B GetIntegerv - Robust access enabled 6.1.5 - | |
| RESET_NOTIFICATION_STRATEGY_EXT Z_2 GetIntegerv See sec. 2.6 Reset notification behavior 2.6 - | |
| Issues | |
| 1. What should this extension be called? | |
| RESOLVED: EXT_robustness | |
| Since this is intended to be a version of ARB_robustness for | |
| OpenGL ES, it should be named accordingly. | |
| 2. How does this extension differ from Desktop GL's ARB_robustness? | |
| RESOLVED: Because EGL_EXT_create_context_robustness uses a | |
| separate attribute to enable robust buffer access, a | |
| corresponding query is added here. | |
| 3. Should we provide a context creation mechanism to enable this extension? | |
| RESOLVED. Yes. | |
| Currently, EGL_EXT_create_context_robustness provides this | |
| mechanism via two unique attributes. These attributes differ | |
| from those specified by KHR_create_context to allow for | |
| differences in what functionality those attributes define. | |
| 4. 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. On some systems, power | |
| management events such as system sleep, screen saver activation, or | |
| pre-emption may also context resets to occur. Any of these events may | |
| result in a graphics reset event that will be detectable by the | |
| mechanism described in this extension. | |
| 5. 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 again | |
| 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. | |
| 6. 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. | |
| 7. 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 value of ROBUST_ACCESS_EXT | |
| using GetIntegerv. If true, this functionality is enabled. | |
| 8. How is the reset notification behavior controlled? | |
| RESOLVED: Reset notification behavior is determined at context | |
| creation time using EGL/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 | |
| ---- ------------ --------- ---------------------------------------- | |
| 3 31 Oct 2011 groth Reverted to attribute for robust access. Now it's a | |
| companion to rather than subset of KHR_create_context | |
| 2 11 Oct 2011 groth Merged ANGLE and NV extensions. | |
| Convert to using flag to indicate robust access. | |
| 1 15 July 2011 groth Initial version |