xref: /third_party/openGLES/extensions/KHR/KHR_context_flush_control.txt

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 <pname> parameter of GetIntegerv, GetFloatv, GetBooleanv
    GetDoublev and GetInteger64v:

        GL_CONTEXT_RELEASE_BEHAVIOR                         0x82FB

    Returned in <data> by GetIntegerv, GetFloatv, GetBooleanv
    GetDoublev and GetInteger64v when <pname> 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
    <value> 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 <ctx>, 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 <release behavior> (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. <ctx> 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 <release behavior> (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 <ctx> 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 <release behavior> (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 <ctx> 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.