Name KHR_context_flush_control Name Strings GL_KHR_context_flush_control EGL_KHR_context_flush_control GLX_ARB_context_flush_control WGL_ARB_context_flush_control Contact Graham Sellers (graham.sellers 'at' amd.com) Contributors Graham Sellers, AMD Jon Leech Notice Copyright (c) 2014 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Specification Update Policy Khronos-approved extension specifications are updated in response to issues and bugs prioritized by the Khronos OpenGL and OpenGL ES Working Groups. For extensions which have been promoted to a core Specification, fixes will first appear in the latest version of that core Specification, and will eventually be backported to the extension document. This policy is described in more detail at https://www.khronos.org/registry/OpenGL/docs/update_policy.php Status Complete. Approved by the ARB on June 26, 2014. Approved by the OpenGL ES Working Group on August 6, 2014. Ratified by the Khronos Board of Promoters on August 7, 2014 (non-EGL extensions, and on September 26, 2014 (EGL extension). Version Last Modified Date: 9/28/2016 Author Revision: 8 Number ARB Extension #168 OpenGL ES Extension #191 (for GL_KHR_context_flush_control only) EGL Extension #102 (for EGL_KHR_context_flush_control only) Dependencies GL_KHR_context_flush_control is written against the OpenGL 4.4 (Core Profile) specification, but can be implemented against any version of OpenGL or OpenGL ES. EGL_KHR_context_flush_control is written against the EGL 1.5 Specification, but can be implemented against any version of EGL. GLX_ARB_context_flush_control is written against the GLX 1.4 and GLX_ARB_create_context specifications. Both are required. WGL_ARB_context_flush_control is written against the WGL_ARB_create_context specification, which is required. Overview OpenGL and OpenGL ES have long supported multiple contexts. The semantics of switching contexts is generally left to window system binding APIs such as WGL, GLX and EGL. Most of these APIs (if not all) specify that when the current context for a thread is changed, the outgoing context performs an implicit flush of any commands that have been issued to that point. OpenGL and OpenGL ES define a flush as sending any pending commands for execution and that this action will result in their completion in finite time. This behavior has subtle consequences. For example, if an application is rendering to the front buffer and switches contexts, it may assume that any rendering performed thus far will eventually be visible to the user. With recent introduction of shared memory buffers, there become inumerable ways in which applications may observe side effects of an implicit flush (or lack thereof). In general, a full flush is not the desired behavior of the application. Nonetheless, applications that switch contexts frequently suffer the performance consequences of this unless implementations make special considerations for them, which is generally untenable. The EGL, GLX, and WGL extensions add new context creation parameters that allow an application to specify the behavior that is desired when a context is made non-current, and specifically to opt out of the implicit flush behavior. The GL extension allows querying the context flush behavior. New Procedures and Functions None. New Tokens (GL) NOTE: when implemented in an OpenGL ES context, all tokens defined by this extension must have a "_KHR" suffix. When implemented in an OpenGL context, all tokens must have NO suffix, as described below. Accepted by the parameter of GetIntegerv, GetFloatv, GetBooleanv GetDoublev and GetInteger64v: GL_CONTEXT_RELEASE_BEHAVIOR 0x82FB Returned in by GetIntegerv, GetFloatv, GetBooleanv GetDoublev and GetInteger64v when is GL_CONTEXT_RELEASE_BEHAVIOR: GL_NONE 0x0000 GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH 0x82FC New Tokens (EGL) Accepted as an attribute name in the <*attrib_list> argument to eglCreateContext: EGL_CONTEXT_RELEASE_BEHAVIOR_KHR 0x2097 Accepted as an attribute value for EGL_CONTEXT_RELEASE_BEHAVIOR_KHR in the <*attrib_list> argument to eglCreateContext: EGL_CONTEXT_RELEASE_BEHAVIOR_NONE_KHR 0x0000 EGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_KHR 0x2098 New Tokens (GLX) Accepted as an attribute name in the <*attrib_list> argument to glXCreateContextAttribsARB: GLX_CONTEXT_RELEASE_BEHAVIOR_ARB 0x2097 Accepted as an attribute value for GLX_CONTEXT_RELEASE_BEHAVIOR_ARB in the <*attrib_list> argument to glXCreateContextAttribsARB: GLX_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB 0x0000 GLX_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB 0x2098 New Tokens (WGL) Accepted as an attribute name in the <*attrib_list> argument to wglCreateContextAttribsARB: WGL_CONTEXT_RELEASE_BEHAVIOR_ARB 0x2097 Accepted as an attribute value for WGL_CONTEXT_RELEASE_BEHAVIOR_ARB in the <*attrib_list> argument to wglCreateContextAttribsARB: WGL_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB 0x0000 WGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB 0x2098 Additions to Chapter 22 of the OpenGL 4.4 Core Pofile Specification (Context State Queries) In Subsection 22.2, "String Queries", after the description of CONTEXT_FLAGS, insert the following: The behavior of the context when it is made no longer current (released) by the platform binding may be queried by calling GetIntegerv with CONTEXT_RELEASE_BEHAVIOR. If the behavior is CONTEXT_RELEASE_BEHAVIOR_FLUSH, any pending commands on the context will be flushed. If the behavior is NONE, pending commands are not flushed. The default value is CONTEXT_RELEASE_BEHAVIOR_FLUSH, and may in some cases be changed using platform-specific context creation extensions. Additions to the EGL 1.5 Specification Add a new subsection to the description of eglCreateContext, following section 3.7.1.6 "OpenGL and OpenGL ES Reset Notification Strategy": "3.7.1.7 OpenGL and OpenGL ES Context Flush Behavior The attribute name EGL_CONTEXT_RELEASE_BEHAVIOR_KHR specifies the behavior of the rendering context when it is made non-current, as described in section 3.7.3. The attribute value may be one of EGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_KHR or EGL_CONTEXT_RELEASE_BEHAVIOR_NONE_KHR. The default value is EGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_KHR." Modify section 3.7.3 "Binding Contexts and Drawables", on p. 58: Replace the fourth paragraph in the description of eglMakeCurrent, starting "If the calling thread already has a current context...": "If the calling thread already has a current context of the same client API type as , behavior is determined as follows: The current context is flushed if any of the following conditions are true: - The client API type of the current context is not OpenGL or OpenGL ES; - The client API type of the current context is OpenGL or OpenGL ES, and the context does not support the GL_KHR_context_flush_control extension - The client API type of the current context is OpenGL or OpenGL ES, the context supports the GL_KHR_context_flush_control extension, and the (the value of the EGL_CONTEXT_RELEASE_BEHAVIOR_KHR parameter) of the current context is EGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_KHR. The only remaining case is treated differently. In this case, the client API type of the current context must be OpenGL or OpenGL ES; the context must support the GL_KHR_context_flush_control extension; and the release behavior must be EGL_CONTEXT_RELEASE_BEHAVIOR_NONE_KHR. In this case no action is taken, and it is as if the application simply stops making GL commands on the current context. After flushing (if appropriate) is performed, the current context is marked as no longer current. is then made the current context for the calling thread. For purposes of ..." Additions to WGL_ARB_create_context and wglMakeCurrent Add a new paragraph to the description of wglCreateContextAttribsARB, as defined by WGL_ARB_create_context: "The attribute name WGL_MAKE_NON_CONTEXT_BEHAVIOR_ARB specifies the behavior of the rendering context when it is made non-current. The attribute value may be one of WGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB or WGL_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB. The default value of WGL_MAKE_NON_CONTEXT_BEHAVIOR_ARB is WGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB." Define flushing behavior for wglMakeCurrent (there is no WGL specification; this language replaces the sentence "Before switching to the new rendering context, OpenGL flushes any previous rendering context that was current to the calling thread." in the Microsoft wglMakeCurrent reference page): "If the calling thread already has a current rendering context, behavior is determined by the (the value of the WGL_CONTEXT_RELEASE_BEHAVIOR_ARB parameter) of the current context. If the release behavior is WGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB, pending commands to the previous context are flushed; if the release behavior is WGL_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB, then no action is taken, and it is as if the application simply stops making GL commands on that context. That context is marked as no longer current, and is made the current context for the calling thread." Additions to the GLX 1.4 Specification and GLX_ARB_create_context Add a new paragraph to the description of glXCreateContextAttribsARB, as defined by GLX_ARB_create_context: "The attribute name GLX_CONTEXT_RELEASE_BEHAVIOR_ARB specifies the behavior of the rendering context when it is made non-current. The attribute value may be one of GLX_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB or GLX_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB. The default value of GLX_CONTEXT_RELEASE_BEHAVIOR_ARB is GLX_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB." Modify section 3.3.7 "Rendering Contexts" on p. 27: Replace the third paragraph in the description of glXMakeContextCurrent, starting "If the calling thread already has a current rendering context...": "If the calling thread already has a current rendering context, behavior is determined by the (the value of the GLX_CONTEXT_RELEASE_BEHAVIOR_ARB parameter) of the current context. If the release behavior is GLX_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB, pending commands to the previous context are flushed; if the release behavior is GLX_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB, then no action is taken, and it is as if the application simply stops making GL commands on that context. That context is marked as no longer current, and is made the current context for the calling thread." GLX Protocol TBD. Errors The errors defined for eglCreateContext, glXCreateContextAttribsARB, and wglCreateContextAttribsARB already describe the situations where invalid attribute values for the context release behavior are specified, and where no context can be created satisfying the specified behavior, so no new errors are added. New State None. New Implementation Dependent State Append to Table 23.54, "Implementation Dependent State" of the OpenGL 4.4 Specification: +-------------------------------+-------+--------------------+------------------------------------------+------------------------------------+---------+ | Get Value | Type | Get Command | Initial Value | Description | Sec. | +-------------------------------+-------+--------------------+------------------------------------------+------------------------------------+---------+ | CONTEXT_RELEASE_BEHAVIOR | E | GetIntegerv | See sec. 2.22 | Specifies flush behavior when | 22.2 | | | | | | the context is released. | | +-------------------------------+-------+--------------------+------------------------------------------+------------------------------------+---------+ Usage Examples TBD Issues 1) What happens when you switch between contexts that have the new CONTEXT_RELEASE_BEHAVIOR_NONE behavior? Nothing. It is as if the thread simply stopped calling functions on one context and started calling functions on another. If, for example, an application is rendering to multiple windows or multiple framebuffer objects, it may not care what order commands are executed across the contexts. This extension allows the application to rapidly switch between contexts that may or may not share objects without any implied flushes. 2) Does this extension affect or change sharing semantics? RESOLVED: No. There is no intention to do so. From the client's perspective, at least, changes made to objects on one context should be visible to other contexts whenever they would have before. However, there may be some subtle interaction here that we haven't thought of yet. 3) Do we need to be able to query the context behavior? RESOLVED. Yes. Added a state query for GL_CONTEXT_RELEASE_BEHAVIOR. 4) Should EGL/GLX/WGL/GL enum values for similar tokens be shared? RESOLVED: the developing tradition is for window system binding enums for context creation to share the same values, but GL to have its own values lying in the traditional GL enum ranges. 5) Should there be a GL extension string corresponding to the window system binding extension strings? RESOLVED: Yes. This is how we've always done it. Added GL_KHR_context_flush_control to Name Strings in revision 3. 6) Should there be an EGL equivalent of this functionality? Should the GL extension be KHR or ARB? RESOLVED: Yes, there should be an EGL extension, but it will be approved on a different schedule by EGL and GL WGs. The GL extension should be KHR, since ES is also interested in this functionality. 7) When the release behavior of an OpenGL compatibility profile context or an OpenGL ES 1.x context is to not flush, should it be possible to make a context non-current within a glBegin/glEnd pair? RESOLVED: No. Only GLX (not EGL or WGL) specifies this constraint, and hypothetical immediate-mode paths would have difficulty supporting MakeCurrent between Begin and End whether or not a flush is done. Revision History Rev. Date Author Changes ---- --------- -------- --------------------------------------------- 8 9/28/2016 Jon Leech Merge EGL_KHR_context_flush_control language, which was ratified more than two years ago but which we forgot to post until now. 7 8/11/2014 Jon Leech Add issue 7, minor wording tweaks to include GL and ES as peer APIs. 6 8/06/2014 Jon Leech Change GL extension to KHR instead of ARB. 5 6/26/2014 Jon Leech Remove ARB suffixes from GL tokens (only, Bug 12299) and clarify the initial value of the GL flush behavior query. 4 6/25/2014 Jon Leech Rewrite spec changes to be against the actual GLX/WGL API and extension specification documents, where possible. 3 6/24/2014 Jon Leech Assign enum values, add issues 4/5. 2 6/05/2014 gsellers Add state query for retrieving context behavior. Rename "lose-context" to "context release". This is the terminology in the existing GLX spec. The WGL spec doesn't appear to use a concrete term. Update state table. Renumbered issues to be contiguous. 1 4/17/2014 gsellers Initial revision based on earlier extension.