xref: /third_party/openGLES/extensions/ARB/GLX_ARB_create_context.txt

Name

    ARB_create_context
    ARB_create_context_profile

Name Strings

    GLX_ARB_create_context
    GLX_ARB_create_context_profile

Contact

    Jon Leech (jon 'at' alumni.caltech.edu)

Notice

    Copyright (c) 2009-2013 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 Working Group. 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

IP Status

    No known IP claims.

Status

    Complete. Approved by the ARB on July 28, 2009.
    Approved by the Khronos Board of Promoters on August 28, 2009.
    Version 8 update approved by the ARB on September 24, 2009.

Version

    Version 10, 2012/03/28

Number

    ARB Extension #56 (GLX_ARB_create_context)
    ARB Extension #75 (GLX_ARB_create_context_profile)

Dependencies

    GLX 1.4 is required.

    Some of the capabilities of these extensions are only available with
    contexts supporting OpenGL 3.0 or later.

    The presence of an OpenGL 3.2 or later implementation determines
    whether or not GLX_ARB_create_context_profile is required.

Overview

    With the advent of new versions of OpenGL which deprecate features
    and/or break backward compatibility with older versions, there is a
    need and desire to indicate at context creation which interface will
    be used. These extensions add a new context creation routine with
    attributes specifying the GL version and context properties
    requested for the context, and additionally add an attribute
    specifying the GL profile requested for a context of OpenGL 3.2 or
    later. It also allows making an OpenGL 3.0 or later context current
    without providing a default framebuffer.

New Procedures and Functions

    GLXContext glXCreateContextAttribsARB(
                    Display *dpy, GLXFBConfig config,
                    GLXContext share_context, Bool direct,
                    const int *attrib_list);

New Tokens

    Accepted as an attribute name in <*attrib_list>:

        GLX_CONTEXT_MAJOR_VERSION_ARB           0x2091
        GLX_CONTEXT_MINOR_VERSION_ARB           0x2092
        GLX_CONTEXT_FLAGS_ARB                   0x2094
        GLX_CONTEXT_PROFILE_MASK_ARB            0x9126

    Accepted as bits in the attribute value for GLX_CONTEXT_FLAGS_ARB in
    <*attrib_list>:

        GLX_CONTEXT_DEBUG_BIT_ARB               0x0001
        GLX_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB  0x0002

    Accepted as bits in the attribute value for
    GLX_CONTEXT_PROFILE_MASK_ARB in <*attrib_list>:

        GLX_CONTEXT_CORE_PROFILE_BIT_ARB        0x00000001
        GLX_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB 0x00000002

Additions to the OpenGL / WGL Specifications

    None. This specification is written for GLX.

Additions to the GLX 1.4 Specification

    Replace the initial six paragraphs of section 3.3.7 "Rendering
    Contexts", describing glXCreateNewContext, with:

   "To create an OpenGL rendering context, call

        GLXContext glXCreateContextAttribsARB(
                        Display *dpy,
                        GLXFBConfig config,
                        GLXContext share_context,
                        Bool direct,
                        const int *attrib_list);

    If glXCreateContextAttribsARB succeeds, it initializes the context
    to the initial state defined by the OpenGL specification, and
    returns a handle to it. This handle can be used to render to any GLX
    surface (window, pixmap, or pbuffer) compatible with <config>,
    subject to constraints imposed by the OpenGL API version of the
    context.

    If <share_context> is not NULL, then all shareable data (excluding
    OpenGL texture objects named 0) will be shared by <share_context>,
    all other contexts <share_context> already shares with, and the
    newly created context. An arbitrary number of GLXContexts can share
    data in this fashion. The server context state for all sharing
    contexts must exist in a single address space.

    Direct rendering is requested if <direct> is True, and indirect
    rendering if <direct> is False. If <direct> is True, the
    implementation may nonetheless create an indirect rendering context
    if any of the following conditions hold:

      * The implementation does not support direct rendering.
      * <display> is not a local X server.
      * Implementation-dependent limits on the number of direct
        rendering contexts that can be supported simultaneously are
        exceeded.

    Use glXIsDirect (see below) to determine whether or not a request
    for a direct rendering context succeeded.

    <attrib_list> specifies a list of attributes for the context. The
    list consists of a sequence of <name,value> pairs terminated by the
    value None (0). If an attribute is not specified in <attrib_list>,
    then the default value specified below is used instead.

    <attrib_list> may be NULL or empty (first attribute is None), in
    which case all attributes assume their default values as described
    below.

    The attribute names GLX_CONTEXT_MAJOR_VERSION_ARB and
    GLX_CONTEXT_MINOR_VERSION_ARB request an OpenGL context supporting
    the specified version of the API. If successful, the context
    returned must be backwards compatible with the context requested.
    Backwards compatibility is determined as follows:

    If a version less than or equal to 3.0 is requested, the context
    returned may implement any of the following versions:

      * Any version no less than that requested and no greater than 3.0.
      * Version 3.1, if the GL_ARB_compatibility extension is also
        implemented.
      * The compatibility profile of version 3.2 or greater.

    If version 3.1 is requested, the context returned may implement
    any of the following versions:

      * Version 3.1. The GL_ARB_compatibility extension may or may not
        be implemented, as determined by the implementation.
      * The core profile of version 3.2 or greater.

    If version 3.2 or greater is requested, the context returned may
    implement any of the following versions:

      * The requested profile of the requested version.
      * The requested profile of any later version, so long as no
        features have been removed from that later version and profile.

    Querying the GL_VERSION string with glGetString (or the
    GL_MAJOR_VERSION and GL_MINOR_VERSION values with glGetIntegerv, in
    a 3.0 or later context) will return the actual version supported by
    a context.

    The default values for GLX_CONTEXT_MAJOR_VERSION_ARB and
    GLX_CONTEXT_MINOR_VERSION_ARB are 1 and 0 respectively. In this
    case, implementations will typically return the most recent version
    of OpenGL they support which is backwards compatible with OpenGL 1.0
    (e.g. 3.0, 3.1 + GL_ARB_compatibility, or 3.2 compatibility profile)

    The attribute name GLX_CONTEXT_PROFILE_MASK_ARB requests an OpenGL
    context supporting a specific <profile> of the API. If the
    GLX_CONTEXT_CORE_PROFILE_BIT_ARB bit is set in the attribute value,
    then a context implementing the <core> profile of OpenGL is
    returned. If the GLX_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB bit is
    set, then a context implementing the <compatibility> profile is
    returned. If the requested OpenGL version is less than 3.2,
    GLX_CONTEXT_PROFILE_MASK_ARB is ignored and the functionality of the
    context is determined solely by the requested version.

    Querying the value of GL_CONTEXT_PROFILE_MASK with glGetIntegerv
    will return the profile mask used to create the context. This query
    is only supported in an OpenGL 3.2 or later context.

    The default value for GLX_CONTEXT_PROFILE_MASK_ARB is
    GLX_CONTEXT_CORE_PROFILE_BIT_ARB. All OpenGL 3.2 implementations are
    required to implement the core profile, but implementation of the
    compatibility profile is optional.

    If the core profile is requested, then the context returned cannot
    implement functionality defined only by the compatibility profile.

    The attribute name GLX_CONTEXT_FLAGS_ARB specifies a set of flag
    bits affecting the rendering context.

    If the GLX_CONTEXT_DEBUG_BIT_ARB flag bit is set in
    GLX_CONTEXT_FLAGS_ARB, then a <debug context> will be created. Debug
    contexts are intended for use during application development, and
    provide additional runtime checking, validation, and logging
    functionality while possibly incurring performance penalties. The
    additional functionality provided by debug contexts may vary
    according to the implementation(fn). In some cases a debug context
    may be identical to a non-debug context.
        [fn: The ARB Ecosystem TSG is still defining the expected and
        required features of debug contexts.]

    If the GLX_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB is set in
    GLX_CONTEXT_FLAGS_ARB, then a <forward-compatible> context will be
    created. Forward-compatible contexts are defined only for OpenGL
    versions 3.0 and later. They must not support functionality marked
    as <deprecated> by that version of the API, while a
    non-forward-compatible context must support all functionality in
    that version, deprecated or not.

    The default value of GLX_CONTEXT_FLAGS_ARB is 0.

    The attribute name GLX_RENDER_TYPE specifies the type of rendering
    to be supported by the context. RGBA rendering is supported if the
    attribute value is GLX_RGBA_TYPE, and color index rendering is
    supported if the attribute value is GLX_COLOR_INDEX_TYPE. The
    default value of GLX_RENDER_TYPE is GLX_RGBA_TYPE. OpenGL contexts
    supporting version 3.0 or later of the API do not support color
    index rendering, even if a color index <config> is available.

    On failure glXCreateContextAttribsARB returns NULL and generates an
    X error with extended error information. Conditions that cause
    failure include:

      * If the server context state for <share_context> exists in an
        address space that cannot be shared with the newly created
        context, if <share_context> was created on a different screen
        than the one referenced by <config>, or if the contexts are
        otherwise incompatible (for example, one context being
        associated with a hardware device driver and the other with a
        software renderer), BadMatch is generated.

      * If the server does not have enough resources to allocate the new
        context, BadAlloc is generated.

      * If <share_context> is neither zero nor a valid GLX rendering
        context, GLXBadContext is generated.

      * If <config> is not a valid GLXFBConfig, GLXBadFBConfig is
        generated.

      * If attribute GLX_RENDER_TYPE does not describe a valid rendering
        type, BadValue is generated.

      * If attributes GLX_CONTEXT_MAJOR_VERSION_ARB and
        GLX_CONTEXT_MINOR_VERSION_ARB, when considered together with
        attributes GLX_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB and
        GLX_RENDER_TYPE, specify an OpenGL version and feature set that
        are not defined, BadMatch is generated.

        The defined versions of OpenGL at the time of writing are OpenGL
        1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 2.0, 2.1, 3.0, 3.1, and 3.2.
        Feature deprecation was introduced with OpenGL 3.0, so
        forward-compatible contexts may only be requested for OpenGL 3.0
        and above. Thus, examples of invalid combinations of attributes
        include:

          - Major version < 1 or > 3
          - Major version == 1 and minor version < 0 or > 5
          - Major version == 2 and minor version < 0 or > 1
          - Major version == 3 and minor version > 2
          - Forward-compatible flag set and major version < 3
          - Color index rendering and major version >= 3

        Because the purpose of forward-compatible contexts is to allow
        application development on a specific OpenGL version with the
        knowledge that the app will run on a future version, context
        creation will fail if GLX_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB is
        set and the context version returned cannot implement exactly
        the requested version.

      * If attribute GLX_CONTEXT_PROFILE_MASK_ARB has no bits set; has
        any bits set other than GLX_CONTEXT_CORE_PROFILE_BIT_ARB and
        GLX_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB; has more than one of
        these bits set; or if the implementation does not support the
        requested profile, then GLXBadProfileARB is generated.

      * If <config> does not support compatible OpenGL contexts
        providing the requested API major and minor version,
        forward-compatible flag, and debug context flag, GLXBadFBConfig
        is generated.

      * If an attribute or attribute value in <attrib_list>
        is not recognized (including unrecognized bits in bitmask
        attributes), BadValue is generated.

    3.3.7.1 Legacy Context Creation
    -------------------------------

    To create an OpenGL rendering context of version 2.1 or below, call

        GLXContext glXCreateNewContext(
                        Display *dpy,
                        GLXFBConfig config,
                        int render_type,
                        GLXContext share_list,
                        Bool direct);

    Calling glXCreateNewContext is equivalent to the command sequence

        int attrib_list[] = {
            GLX_RENDER_TYPE, render_type,
            None
        };

        glXCreateContextAttribs(dpy, config, share_list, direct, attrib_list);

    The legacy context creation routines can only return OpenGL 3.1
    contexts if the GL_ARB_compatibility extension is supported, and can
    only return OpenGL 3.2 or greater contexts implementing the
    compatibility profile. This ensures compatibility for existing
    applications. However, 3.0-aware applications are encouraged to use
    wglCreateContextAttribsARB instead of the legacy routines.

    To determine if an OpenGL rendering context is direct, call..."


    In the description of glXMakeContextCurrent, replace the text

   "If either <draw> or <read> are not a valid GLX drawable, a
    GLXBadDrawable error is generated."

    with

   "If either <draw> or <read> are not a valid GLX drawable, a
    GLXBadDrawable error is generated, unless <draw> and <read> are both
    None and the OpenGL version supported by <ctx> is 3.0 or greater. In
    this case the context is made current without a default framebuffer,
    as defined in chapter 4 of the OpenGL 3.0 Specification."

    Replace the text

   "To release the current context without assigning a new one, set
    <ctx> to NULL and set <draw> and <read> to None. If <ctx> is NULL
    and <draw> and <read> are not None, or if <draw> or <read> are set
    to None and <ctx> is not NULL, then a BadMatch error will be
    generated."

    with

   "To release the current context without assigning a new one, set
    <ctx> to NULL and set <draw> and <read> to None. A BadMatch
    error will be generated under any of the following conditions:

      * <ctx> is NULL, and either or both of <draw> and <read> are not
        None.
      * <ctx> is not NULL, and exactly one of <draw> or <read> is None.
      * <ctx> is not NULL, both <draw> or <read> are None, and the
        OpenGL version supported by <ctx> is less than 3.0."

    After the sentence

   "The first time <ctx> is made current, the viewport and scissor
    dimensions are set to the size of the draw drawable (as though
    glViewport(0,0,w,h) and glScissor(0,0,w,h) were called, where <w>
    and <h> are the width and height of the drawable, respectively)."

    insert

   "If the first time <ctx> is made current, it is without a default
    framebuffer (e.g. both <draw> and <read> are None), then the
    viewport and scissor regions are set as though glViewport(0,0,0,0)
    and glScissor(0,0,0,0) were called."

GLX Errors

    GLXBadProfileARB

    The requested context profile is invalid or not supported.

    BEC is the base error code for the extension, as returned by
    XQueryExtension.

    Encoding:

        1      0                      Error
        1      BEC + 13               Error code (GLXBadProfileARB)
        2      CARD16                 sequence number
        4      CARD32                 bad profile bitmask
        2      CARD16                 minor opcode
        1      CARD8                  major opcode
        21                            unused

GLX Protocol

    Three new GLX protocol commands are added.

    Send Extended Client Information To The Server (glXSetClientInfoARB
    and glXSetClientInfo2ARB)
    ----------------------------------------------

    This request is sent to the server during initialization, describing
    the GLX version, GLX extensions, GL version(s), and GL extensions
    supported by the client. The client needs to send only names of GL
    extensions that require server support, but must send all GLX
    extension names.

    When the server receives a GetString request, it uses this
    information to compute the version and extensions that can be
    supported on the connection. The GLX client library should append
    any client-side only extensions to the extension string returned by
    the GetString request. When the server receives a
    glXCreateContextAttribsARB request, it uses this information to
    determine whether the requested context version, attributes, and
    flags can be supported on the connection.

    glXSetClientInfo2ARB supersedes glXSetClientInfoARB, which in turn
    supersedes the glXClientInfo request.  The client should only send
    glXSetClientInfo2ARB if both GLX_ARB_create_context and
    GLX_ARB_create_context_profile are present in the server's extension
    string.  If only GLX_ARB_create_context is present, the client
    should send glXSetClientInfoARB, and if neither are present
    glXClientInfo should be sent. If none of these requests are ever
    sent to the server, the server assumes the client supports OpenGL
    major version 1 and minor version 0, GLX major version 1, and minor
    version 0, and doesn't support any OpenGL or GLX extensions.

    glXSetClientInfo2ARB Encoding:

        1      CARD8                 opcode (X assigned)
        1      35                    GLX opcode (glXSetClientInfoARB)
        2      6+(n0*3)+((n1+p1)/4)+((n2+p2)/4)    request length
        4      CARD32                client GLX major version
        4      CARD32                client GLX minor version
        4      n0                    number of context versions
        4      n1                    number of bytes in extension_string
        4      n2                    number of bytes in glx_extension_string
        n0*3*4 LISTofCARD32          context versions
        n1     STRING8               client GL extension string
        p1                           unused, p1 = pad(n1)
        n2     STRING8               client GLX extension string
        p2                           unused, p2 = pad(n2)

    glXSetClientInfoARB Encoding:

        1      CARD8                 opcode (X assigned)
        1      33                    GLX opcode (glXSetClientInfoARB)
        2      6+(n0*2)+((n1+p1)/4)+((n2+p2)/4)    request length
        4      CARD32                client GLX major version
        4      CARD32                client GLX minor version
        4      n0                    number of context versions
        4      n1                    number of bytes in extension_string
        4      n2                    number of bytes in glx_extension_string
        n0*2*4 LISTofCARD32          context versions
        n1     STRING8               client GL extension string
        p1                           unused, p1 = pad(n1)
        n2     STRING8               client GLX extension string
        p2                           unused, p2 = pad(n2)

    "Context versions" is a list of (major version, minor version,
    [profile mask]) tuple; each tuple describes a GL version supported
    by the client.  The profile mask member is only sent when using
    glXSetClientInfo2ARB and is ignored for versions less than 3.2.
    Only the highest supported version below 3.0 should be sent, since
    OpenGL 2.1 is backwards compatible with all earlier versions.  For
    example, a context versions array containing

        { 2, 1, 0x0, 3, 0, 0x0, 3, 1, 0x0, 3, 2, 0x3 }

    Means that the client supports all GL versions between 1.0 and 2.1,
    as well as versions 3.0, 3.1, and 3.2.  Version 3.2 core and
    compatibility profiles are supported.  A BadValue error will be
    generated if the client sends a 3.2 or greater version tuple with a
    profile mask of 0, or with a profile mask that does not include the
    core profile.

    If glXSetClientInfo2ARB or glXSetClientInfoARB are not sent by the
    client prior to context creation the server will behave as if no
    contexts above version 2.1 are supported, and assume the client
    supports all GLX extensions.  If the client sends
    glXSetClientInfoARB and the server supports
    GLX_ARB_create_context_profile, the server will behave as if no
    contexts above version 3.1 are supported.


    Context Creation with Attributes (glXCreateContextAttribsARB)
    --------------------------------

    This request is sent to create a context with specified attributes

        1     CARD8                  opcode (X assigned)
        1     34                     GLX opcode (glXCreateContextAttribsARB)
        2     7+n                    request length
        4     GLX_CONTEXT            context
        4     FBCONFIGID             fbconfig
        4     CARD32                 screen
        4     GLX_CONTEXT            share_context
        1     BOOL                   isdirect
        1     CARD8                  reserved1
        2     CARD16                 reserved2
        4     CARD32                 num_attribs
        4*n   LISTofATTRIBUTE_PAIR   attribute, value pairs

Errors

    GLX errors for glXCreateContextAttribsARB and glXSetClientInfo2ARB
    as described in the body of the specification.

    glXMakeContextCurrent error behavior is relaxed to allow making an
    OpenGL 3.0 or later context current without a default read or draw
    framebuffer.

Dependencies on GLX_ARB_create_context

    If GLX_ARB_create_context_profile is supported, then
    GLX_ARB_create_context must also be supported.

Dependencies on OpenGL 3.2 and later OpenGL versions

    If GLX_ARB_create_context is supported, and if the OpenGL
    implementation supports OpenGL 3.2 or later, then
    GLX_ARB_create_context_profile must also be supported. If the OpenGL
    implementation does not support OpenGL 3.2 or later, then
    GLX_ARB_create_context_profile may or may not be supported.

    If GLX_ARB_create_context_profile is not supported, then the
    GLX_CONTEXT_PROFILE_MASK_ARB attribute, the
    GLX_CONTEXT_CORE_PROFILE_BIT_ARB and
    GLX_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB bits in that attribute,
    and the ERROR_INVALID_PROFILE_ARB error are not defined, and
    specifying the attribute in <attribList> attribute will generate
    BadValue.

New State

    None

New Implementation Dependent State

    None

Conformance Tests

    TBD

Sample Code

    TBD

Issues

    All non-window-system dependent issues described in the
    WGL_ARB_create_context extension specification apply equally to
    GLX_ARB_create_context.

 1) Why was the context creation parameter <render_type> folded into the
    attribute list, while the parameters <direct> and <share_context>
    remains explicit?

    For <direct>, because different paths to the server may be taken for
    creating direct contexts, and parsing the attribute list in the
    client should not be required. For <share_context>, because putting
    a GLXContext, which is implemented as a struct pointer, into a list
    of 'int's does not work on LP64 architectures.

 2) What is the behavior when creating an indirect rendering context
    with attributes, flags, or a GLXFBConfig that require extensions not
    supported by the client GLX implementation?

    Context creation will succeed, but using such features may be
    impossible, since there may be no entry points defined in the client
    library to control them.

 3) Does client support for profiles need to be sent to the server
    along with client support for versions?

    Yes.  glXSetClientInfo2ARB extends glXSetClientInfoARB to support
    sending supported profile masks for each supported version.

Revision History

    Version 1, 2008/08/20 - Fork from WGL_ARB_create_context

    Version 2, 2008/08/21 - Add viewport/scissor setting behavior when
    no default framebuffer is made current.

    Version 3, 2008/10/08 - Restore <direct> as an explicit parameter
    instead of an attribute. Allow creating indirect contexts requiring
    extensions not supported by the client. Add GLX protocol. Use
    existing GLX_RENDER_TYPE token. Rename some parameters following
    existing conventions. Update Errors section.

    Version 4, 2008/10/13 - Move "undefined behavior when successfully
    creating a context requiring extensions not supported by the client"
    language from the spec into the issues list. Remove unused
    GLX_DIRECT_RENDERER_ARB token. Expand description of
    glXSetClientInfoARB protocol negotiation.

    Version 5, 2008/10/22 - Mark as complete and assign extension number
    for the registry.

    Version 6, 2008/10/24 - Renumber to ARB extension #55 - misplaced
    into vendor extension numbering scheme at first.

    Version 7, 2009/07/27 - Add profiled context creation functionality
    (GLX_CONTEXT_PROFILE_MASK_ARB and the associated bit tokens).
    Clarify that if the core profile is requested, the returned context
    cannot restore functionality from the compatibility profile (issue
    17 in WGL_ARB_create_context). Specify the interdependencies between
    the two GLX extensions defined here and OpenGL 3.2, including the
    requirement that GLX_ARB_create_context_profile be supported if an
    OpenGL 3.2 or later implementation is supported. Add issue 3 on
    sending profile support to the server.

    Version 8, 2009/08/30 - Add glXSetClientInfo2ARB to support sending
    profile masks with the versions as well.  Specify which error is
    generated in the case profile tokens are used with a server that
    doesn't support them.  Replace ERROR_INVALID_PROFILE_ARB with
    GLXBadProfileARB and define its encoding.

    Version 9, 2009/11/19 - Clarify that BEC in the BadProfile protocol
    represents the base error code for the GLX extension.

    Version 10, 2012/03/28 - Clarify error conditions when
    glXMakeContextCurrent is called with a valid context and exactly one
    None drawable.