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 , subject to constraints imposed by the OpenGL API version of the context. If is not NULL, then all shareable data (excluding OpenGL texture objects named 0) will be shared by , all other contexts 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 is True, and indirect rendering if is False. If 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. * 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. specifies a list of attributes for the context. The list consists of a sequence of pairs terminated by the value None (0). If an attribute is not specified in , then the default value specified below is used instead. 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 of the API. If the GLX_CONTEXT_CORE_PROFILE_BIT_ARB bit is set in the attribute value, then a context implementing the profile of OpenGL is returned. If the GLX_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB bit is set, then a context implementing the 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 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 context will be created. Forward-compatible contexts are defined only for OpenGL versions 3.0 and later. They must not support functionality marked as 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 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 exists in an address space that cannot be shared with the newly created context, if was created on a different screen than the one referenced by , 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 is neither zero nor a valid GLX rendering context, GLXBadContext is generated. * If 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 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 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 or are not a valid GLX drawable, a GLXBadDrawable error is generated." with "If either or are not a valid GLX drawable, a GLXBadDrawable error is generated, unless and are both None and the OpenGL version supported by 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 to NULL and set and to None. If is NULL and and are not None, or if or are set to None and is not NULL, then a BadMatch error will be generated." with "To release the current context without assigning a new one, set to NULL and set and to None. A BadMatch error will be generated under any of the following conditions: * is NULL, and either or both of and are not None. * is not NULL, and exactly one of or is None. * is not NULL, both or are None, and the OpenGL version supported by is less than 3.0." After the sentence "The first time 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 and are the width and height of the drawable, respectively)." insert "If the first time is made current, it is without a default framebuffer (e.g. both and 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 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 folded into the attribute list, while the parameters and remains explicit? For , 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 , 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 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.