1Name 2 3 KHR_context_flush_control 4 5Name Strings 6 7 GL_KHR_context_flush_control 8 EGL_KHR_context_flush_control 9 GLX_ARB_context_flush_control 10 WGL_ARB_context_flush_control 11 12Contact 13 14 Graham Sellers (graham.sellers 'at' amd.com) 15 16Contributors 17 18 Graham Sellers, AMD 19 Jon Leech 20 21Notice 22 23 Copyright (c) 2014 The Khronos Group Inc. Copyright terms at 24 http://www.khronos.org/registry/speccopyright.html 25 26Specification Update Policy 27 28 Khronos-approved extension specifications are updated in response to 29 issues and bugs prioritized by the Khronos OpenGL and OpenGL ES Working Groups. For 30 extensions which have been promoted to a core Specification, fixes will 31 first appear in the latest version of that core Specification, and will 32 eventually be backported to the extension document. This policy is 33 described in more detail at 34 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 35 36Status 37 38 Complete. 39 Approved by the ARB on June 26, 2014. 40 Approved by the OpenGL ES Working Group on August 6, 2014. 41 Ratified by the Khronos Board of Promoters on August 7, 2014 (non-EGL 42 extensions, and on September 26, 2014 (EGL extension). 43 44Version 45 46 Last Modified Date: 9/28/2016 47 Author Revision: 8 48 49Number 50 51 ARB Extension #168 52 OpenGL ES Extension #191 (for GL_KHR_context_flush_control only) 53 EGL Extension #102 (for EGL_KHR_context_flush_control only) 54 55Dependencies 56 57 GL_KHR_context_flush_control is written against the OpenGL 4.4 (Core 58 Profile) specification, but can be implemented against any version of 59 OpenGL or OpenGL ES. 60 61 EGL_KHR_context_flush_control is written against the EGL 1.5 62 Specification, but can be implemented against any version of EGL. 63 64 GLX_ARB_context_flush_control is written against the GLX 1.4 and 65 GLX_ARB_create_context specifications. Both are required. 66 67 WGL_ARB_context_flush_control is written against the 68 WGL_ARB_create_context specification, which is required. 69 70Overview 71 72 OpenGL and OpenGL ES have long supported multiple contexts. The 73 semantics of switching contexts is generally left to window system 74 binding APIs such as WGL, GLX and EGL. Most of these APIs (if not all) 75 specify that when the current context for a thread is changed, the 76 outgoing context performs an implicit flush of any commands that have 77 been issued to that point. OpenGL and OpenGL ES define a flush as 78 sending any pending commands for execution and that this action will 79 result in their completion in finite time. 80 81 This behavior has subtle consequences. For example, if an application is 82 rendering to the front buffer and switches contexts, it may assume that 83 any rendering performed thus far will eventually be visible to the user. 84 With recent introduction of shared memory buffers, there become inumerable 85 ways in which applications may observe side effects of an implicit flush 86 (or lack thereof). 87 88 In general, a full flush is not the desired behavior of the application. 89 Nonetheless, applications that switch contexts frequently suffer the 90 performance consequences of this unless implementations make special 91 considerations for them, which is generally untenable. 92 93 The EGL, GLX, and WGL extensions add new context creation parameters 94 that allow an application to specify the behavior that is desired when a 95 context is made non-current, and specifically to opt out of the implicit 96 flush behavior. The GL extension allows querying the context flush 97 behavior. 98 99New Procedures and Functions 100 101 None. 102 103New Tokens (GL) 104 105 NOTE: when implemented in an OpenGL ES context, all tokens defined by 106 this extension must have a "_KHR" suffix. When implemented in an OpenGL 107 context, all tokens must have NO suffix, as described below. 108 109 Accepted by the <pname> parameter of GetIntegerv, GetFloatv, GetBooleanv 110 GetDoublev and GetInteger64v: 111 112 GL_CONTEXT_RELEASE_BEHAVIOR 0x82FB 113 114 Returned in <data> by GetIntegerv, GetFloatv, GetBooleanv 115 GetDoublev and GetInteger64v when <pname> is 116 GL_CONTEXT_RELEASE_BEHAVIOR: 117 118 GL_NONE 0x0000 119 GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH 0x82FC 120 121New Tokens (EGL) 122 123 Accepted as an attribute name in the <*attrib_list> argument to 124 eglCreateContext: 125 126 EGL_CONTEXT_RELEASE_BEHAVIOR_KHR 0x2097 127 128 Accepted as an attribute value for EGL_CONTEXT_RELEASE_BEHAVIOR_KHR in 129 the <*attrib_list> argument to eglCreateContext: 130 131 EGL_CONTEXT_RELEASE_BEHAVIOR_NONE_KHR 0x0000 132 EGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_KHR 0x2098 133 134New Tokens (GLX) 135 136 Accepted as an attribute name in the <*attrib_list> argument to 137 glXCreateContextAttribsARB: 138 139 GLX_CONTEXT_RELEASE_BEHAVIOR_ARB 0x2097 140 141 Accepted as an attribute value for GLX_CONTEXT_RELEASE_BEHAVIOR_ARB in 142 the <*attrib_list> argument to glXCreateContextAttribsARB: 143 144 GLX_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB 0x0000 145 GLX_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB 0x2098 146 147New Tokens (WGL) 148 149 Accepted as an attribute name in the <*attrib_list> argument to 150 wglCreateContextAttribsARB: 151 152 WGL_CONTEXT_RELEASE_BEHAVIOR_ARB 0x2097 153 154 Accepted as an attribute value for WGL_CONTEXT_RELEASE_BEHAVIOR_ARB in 155 the <*attrib_list> argument to wglCreateContextAttribsARB: 156 157 WGL_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB 0x0000 158 WGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB 0x2098 159 160Additions to Chapter 22 of the OpenGL 4.4 Core Pofile Specification (Context 161State Queries) 162 163 In Subsection 22.2, "String Queries", after the description of 164 CONTEXT_FLAGS, insert the following: 165 166 The behavior of the context when it is made no longer current (released) 167 by the platform binding may be queried by calling GetIntegerv with 168 <value> CONTEXT_RELEASE_BEHAVIOR. If the behavior is 169 CONTEXT_RELEASE_BEHAVIOR_FLUSH, any pending commands on the context will 170 be flushed. If the behavior is NONE, pending commands are not flushed. 171 172 The default value is CONTEXT_RELEASE_BEHAVIOR_FLUSH, and may in some 173 cases be changed using platform-specific context creation extensions. 174 175 176Additions to the EGL 1.5 Specification 177 178 Add a new subsection to the description of eglCreateContext, 179 following section 3.7.1.6 "OpenGL and OpenGL ES Reset Notification 180 Strategy": 181 182 "3.7.1.7 OpenGL and OpenGL ES Context Flush Behavior 183 184 The attribute name EGL_CONTEXT_RELEASE_BEHAVIOR_KHR specifies the 185 behavior of the rendering context when it is made non-current, as 186 described in section 3.7.3. The attribute value may be one of 187 EGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_KHR or 188 EGL_CONTEXT_RELEASE_BEHAVIOR_NONE_KHR. The default value is 189 EGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_KHR." 190 191 192 Modify section 3.7.3 "Binding Contexts and Drawables", on p. 58: 193 194 Replace the fourth paragraph in the description of eglMakeCurrent, 195 starting "If the calling thread already has a current context...": 196 197 "If the calling thread already has a current context of the same 198 client API type as <ctx>, behavior is determined as follows: 199 200 The current context is flushed if any of the following conditions 201 are true: 202 203 - The client API type of the current context is not OpenGL or OpenGL 204 ES; 205 - The client API type of the current context is OpenGL or OpenGL ES, 206 and the context does not support the GL_KHR_context_flush_control 207 extension 208 - The client API type of the current context is OpenGL or OpenGL ES, 209 the context supports the GL_KHR_context_flush_control extension, 210 and the <release behavior> (the value of the 211 EGL_CONTEXT_RELEASE_BEHAVIOR_KHR parameter) of the current context 212 is EGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_KHR. 213 214 The only remaining case is treated differently. In this case, the client 215 API type of the current context must be OpenGL or OpenGL ES; the context 216 must support the GL_KHR_context_flush_control extension; and the release 217 behavior must be EGL_CONTEXT_RELEASE_BEHAVIOR_NONE_KHR. In this case no 218 action is taken, and it is as if the application simply stops making GL 219 commands on the current context. 220 221 After flushing (if appropriate) is performed, the current context is 222 marked as no longer current. <ctx> is then made the current context 223 for the calling thread. For purposes of ..." 224 225 226Additions to WGL_ARB_create_context and wglMakeCurrent 227 228 Add a new paragraph to the description of wglCreateContextAttribsARB, as 229 defined by WGL_ARB_create_context: 230 231 "The attribute name WGL_MAKE_NON_CONTEXT_BEHAVIOR_ARB specifies the 232 behavior of the rendering context when it is made non-current. The 233 attribute value may be one of WGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB or 234 WGL_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB. The default value of 235 WGL_MAKE_NON_CONTEXT_BEHAVIOR_ARB is 236 WGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB." 237 238 Define flushing behavior for wglMakeCurrent (there is no WGL 239 specification; this language replaces the sentence "Before switching to 240 the new rendering context, OpenGL flushes any previous rendering context 241 that was current to the calling thread." in the Microsoft wglMakeCurrent 242 reference page): 243 244 "If the calling thread already has a current rendering context, behavior 245 is determined by the <release behavior> (the value of the 246 WGL_CONTEXT_RELEASE_BEHAVIOR_ARB parameter) of the current context. If 247 the release behavior is WGL_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB, pending 248 commands to the previous context are flushed; if the release behavior is 249 WGL_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB, then no action is taken, and it 250 is as if the application simply stops making GL commands on that 251 context. That context is marked as no longer current, and <ctx> is made 252 the current context for the calling thread." 253 254Additions to the GLX 1.4 Specification and GLX_ARB_create_context 255 256 Add a new paragraph to the description of glXCreateContextAttribsARB, 257 as defined by GLX_ARB_create_context: 258 259 "The attribute name GLX_CONTEXT_RELEASE_BEHAVIOR_ARB specifies the 260 behavior of the rendering context when it is made non-current. The 261 attribute value may be one of GLX_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB or 262 GLX_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB. The default value of 263 GLX_CONTEXT_RELEASE_BEHAVIOR_ARB is GLX_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB." 264 265 Modify section 3.3.7 "Rendering Contexts" on p. 27: 266 267 Replace the third paragraph in the description of glXMakeContextCurrent, 268 starting "If the calling thread already has a current rendering 269 context...": 270 271 "If the calling thread already has a current rendering context, behavior 272 is determined by the <release behavior> (the value of the 273 GLX_CONTEXT_RELEASE_BEHAVIOR_ARB parameter) of the current context. If 274 the release behavior is GLX_CONTEXT_RELEASE_BEHAVIOR_FLUSH_ARB, pending 275 commands to the previous context are flushed; if the release behavior is 276 GLX_CONTEXT_RELEASE_BEHAVIOR_NONE_ARB, then no action is taken, and it 277 is as if the application simply stops making GL commands on that 278 context. That context is marked as no longer current, and <ctx> is made 279 the current context for the calling thread." 280 281 282GLX Protocol 283 284 TBD. 285 286Errors 287 288 The errors defined for eglCreateContext, glXCreateContextAttribsARB, and 289 wglCreateContextAttribsARB already describe the situations where invalid 290 attribute values for the context release behavior are specified, and 291 where no context can be created satisfying the specified behavior, so no 292 new errors are added. 293 294New State 295 296 None. 297 298New Implementation Dependent State 299 300 Append to Table 23.54, "Implementation Dependent State" of the OpenGL 4.4 Specification: 301 302 +-------------------------------+-------+--------------------+------------------------------------------+------------------------------------+---------+ 303 | Get Value | Type | Get Command | Initial Value | Description | Sec. | 304 +-------------------------------+-------+--------------------+------------------------------------------+------------------------------------+---------+ 305 | CONTEXT_RELEASE_BEHAVIOR | E | GetIntegerv | See sec. 2.22 | Specifies flush behavior when | 22.2 | 306 | | | | | the context is released. | | 307 +-------------------------------+-------+--------------------+------------------------------------------+------------------------------------+---------+ 308 309Usage Examples 310 311 TBD 312 313Issues 314 315 1) What happens when you switch between contexts that have the new 316 CONTEXT_RELEASE_BEHAVIOR_NONE behavior? 317 318 Nothing. It is as if the thread simply stopped calling functions on 319 one context and started calling functions on another. If, for 320 example, an application is rendering to multiple windows or multiple 321 framebuffer objects, it may not care what order commands are executed 322 across the contexts. This extension allows the application to rapidly 323 switch between contexts that may or may not share objects without any 324 implied flushes. 325 326 2) Does this extension affect or change sharing semantics? 327 328 RESOLVED: No. There is no intention to do so. From the client's 329 perspective, at least, changes made to objects on one context should 330 be visible to other contexts whenever they would have before. 331 However, there may be some subtle interaction here that we haven't 332 thought of yet. 333 334 3) Do we need to be able to query the context behavior? 335 336 RESOLVED. Yes. Added a state query for GL_CONTEXT_RELEASE_BEHAVIOR. 337 338 4) Should EGL/GLX/WGL/GL enum values for similar tokens be shared? 339 340 RESOLVED: the developing tradition is for window system binding enums 341 for context creation to share the same values, but GL to have its own 342 values lying in the traditional GL enum ranges. 343 344 5) Should there be a GL extension string corresponding to 345 the window system binding extension strings? 346 347 RESOLVED: Yes. This is how we've always done it. Added 348 GL_KHR_context_flush_control to Name Strings in revision 3. 349 350 6) Should there be an EGL equivalent of this functionality? Should the 351 GL extension be KHR or ARB? 352 353 RESOLVED: Yes, there should be an EGL extension, but it will be 354 approved on a different schedule by EGL and GL WGs. The GL extension 355 should be KHR, since ES is also interested in this functionality. 356 357 7) When the release behavior of an OpenGL compatibility profile context 358 or an OpenGL ES 1.x context is to not flush, should it be possible to 359 make a context non-current within a glBegin/glEnd pair? 360 361 RESOLVED: No. Only GLX (not EGL or WGL) specifies this constraint, 362 and hypothetical immediate-mode paths would have difficulty 363 supporting MakeCurrent between Begin and End whether or not a flush 364 is done. 365 366 367Revision History 368 369 Rev. Date Author Changes 370 ---- --------- -------- --------------------------------------------- 371 8 9/28/2016 Jon Leech Merge EGL_KHR_context_flush_control language, 372 which was ratified more than two years ago but 373 which we forgot to post until now. 374 7 8/11/2014 Jon Leech Add issue 7, minor wording tweaks to include 375 GL and ES as peer APIs. 376 6 8/06/2014 Jon Leech Change GL extension to KHR instead of ARB. 377 5 6/26/2014 Jon Leech Remove ARB suffixes from GL tokens (only, Bug 378 12299) and clarify the initial value of the 379 GL flush behavior query. 380 4 6/25/2014 Jon Leech Rewrite spec changes to be against the actual 381 GLX/WGL API and extension specification 382 documents, where possible. 383 3 6/24/2014 Jon Leech Assign enum values, add issues 4/5. 384 2 6/05/2014 gsellers Add state query for retrieving context behavior. 385 Rename "lose-context" to "context release". This 386 is the terminology in the existing GLX spec. The 387 WGL spec doesn't appear to use a concrete term. 388 Update state table. 389 Renumbered issues to be contiguous. 390 1 4/17/2014 gsellers Initial revision based on earlier extension. 391