blob: 3f8762356680284e84749cd3f9c963a14344d066 [file] [log] [blame]
Name
WGL_ARB_create_context
WGL_ARB_create_context_profile
Name Strings
WGL_ARB_create_context
WGL_ARB_create_context_profile
Contact
Jon Leech (jon 'at' alumni.caltech.edu)
Michael Gold, NVIDIA (gold 'at' nvidia.com)
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
July 28, 2009 (version 20)
Number
ARB Extension #55 (WGL_ARB_create_context)
ARB Extension #74 (WGL_ARB_create_context_profile)
Dependencies
WGL_ARB_extensions_string is required.
The presence of an OpenGL 3.2 or later implementation determines
whether or not WGL_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.
New Procedures and Functions
HGLRC wglCreateContextAttribsARB(HDC hDC, HGLRC hShareContext,
const int *attribList)
New Tokens
Accepted as an attribute name in <*attribList>:
WGL_CONTEXT_MAJOR_VERSION_ARB 0x2091
WGL_CONTEXT_MINOR_VERSION_ARB 0x2092
WGL_CONTEXT_LAYER_PLANE_ARB 0x2093
WGL_CONTEXT_FLAGS_ARB 0x2094
WGL_CONTEXT_PROFILE_MASK_ARB 0x9126
Accepted as bits in the attribute value for WGL_CONTEXT_FLAGS in
<*attribList>:
WGL_CONTEXT_DEBUG_BIT_ARB 0x0001
WGL_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB 0x0002
Accepted as bits in the attribute value for
WGL_CONTEXT_PROFILE_MASK_ARB in <*attribList>:
WGL_CONTEXT_CORE_PROFILE_BIT_ARB 0x00000001
WGL_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB 0x00000002
New errors returned by GetLastError:
ERROR_INVALID_VERSION_ARB 0x2095
ERROR_INVALID_PROFILE_ARB 0x2096
Additions to the OpenGL / GLX / GLX Protocol Specificaitons
None. This specification is written for WGL.
Additions to the WGL specification
Context Creation
----------------
To create an OpenGL rendering context, call
HGLRC wglCreateContextAttribsARB(HDC hDC, HGLRC hshareContext,
const int *attribList);
If wglCreateContextAttribsARB succeeds, it initializes the context
to the initial state defined by the OpenGL specification, and
returns a handle to it. The handle can be used (via wglMakeCurrent
or wglMakeContextCurrentARB) with any HDC sharing the same pixel
format as <hDC>, and created on the same device, subject to
constraints imposed by the API version.
If <hshareContext> is not 0, then all shareable data (excluding
OpenGL texture objects named 0) will be shared by <hshareContext>,
all other contexts <hshareContext> already shares with, and the
newly created context. An arbitrary number of contexts can share
data in this fashion.
<attribList> specifies a list of attributes for the context. The
list consists of a sequence of <name,value> pairs terminated by the
value 0. If an attribute is not specified in <attribList>, then the
default value specified below is used instead. If an attribute is
specified more than once, then the last value specified is used.
<attribList> may be NULL or empty (first attribute is 0), in which
case all attributes assume their default values as described below.
The attribute names WGL_CONTEXT_MAJOR_VERSION_ARB and
WGL_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 WGL_CONTEXT_MAJOR_VERSION_ARB and
WGL_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 WGL_CONTEXT_PROFILE_MASK_ARB requests an OpenGL
context supporting a specific <profile> of the API. If the
WGL_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 WGL_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,
WGL_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 WGL_CONTEXT_PROFILE_MASK_ARB is
WGL_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 WGL_CONTEXT_LAYER_PLANE specifies the layer plane
that the rendering context is bound to. The attribute value has the
same meaning and allowed values as the <iLayerPlane> parameter of
wglCreateLayerContext. The default value for WGL_CONTEXT_LAYER_PLANE
is 0 (the main plane).
The attribute name WGL_CONTEXT_FLAGS_ARB specifies a set of flag
bits affecting the rendering context.
If the WGL_CONTEXT_DEBUG_BIT_ARB flag bit is set in
WGL_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 WGL_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB is set in
WGL_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 WGL_CONTEXT_FLAGS_ARB is 0.
On failure wglCreateContextAttribsARB returns NULL. Extended error
information can be obtained with GetLastError. Conditions that cause
failure include:
* If attributes WGL_CONTEXT_MAJOR_VERSION_ARB and
WGL_CONTEXT_MINOR_VERSION_ARB, when considered together with
WGL_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB, specify an OpenGL version
and feature set that are not defined, then ERROR_INVALID_VERSION_ARB
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
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 WGL_CONTEXT_FORWARD_COMPATIBLE_BIT_ARB is set
and the context version returned cannot implement exactly the
requested version.
* If attribute WGL_CONTEXT_PROFILE_MASK_ARB has no bits set; has any
bits set other than WGL_CONTEXT_CORE_PROFILE_BIT_ARB and
WGL_CONTEXT_COMPATIBILITY_PROFILE_BIT_ARB; has more than one of
these bits set; or if the implementation does not supported the
requested profile, then ERROR_INVALID_PROFILE_ARB is generated.
* If <hShareContext> is neither zero nor a valid context handle, then
ERROR_INVALID_OPERATION is generated.
* If <hDC> is not a valid device context handle, then
ERROR_DC_NOT_FOUND is generated.
* If the pixel format associated with <hDC> does not support OpenGL
contexts providing the requested API major and minor version,
forward-compatible flag, and/or debug context flag, then
ERROR_INVALID_PIXEL_FORMAT is generated.
* If the OpenGL server context state for <hShareContext> exists in an
address space that cannot be shared with the newly created context,
if <shareContext> was created on a different device context than the
one referenced by <hDC>, 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), then
ERROR_INVALID_OPERATION is generated.
* If the server does not have enough resources to allocate the new
context, then ERROR_NO_SYSTEM_RESOURCES is generated.
* If an unrecognized attribute is present in <attribList>,
then ERROR_INVALID_PARAMETER is generated.
Legacy Context Creation
-----------------------
When this extension is supported, calling
wglCreateContext(hdc)
is equivalent to calling
wglCreateContextAttribs(hdc,0,NULL).
Calling
wglCreateLayerContext(hdc,layer)
is equivalent to calling
wglCreateContextAttribs(hdc, 0,
{ WGL_CONTEXT_LAYER_PLANE, layer, 0 }) .
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.
Binding a Context to a Surface
------------------------------
(add to the description of wglMakeCurrent and
wglMakeContextCurrentARB)
"If the OpenGL context version of <hglrc> is 3.0 or above, and if
either the <hdc> parameter of wglMakeCurrent is NULL, or both of the
<hDrawDC> and <hReadDC> parameters of wglMakeContextCurrentARB are
NULL, then the context is made current, but with no default
framebuffer defined. The effects of having no default framebuffer on
the GL are defined in Chapter 4 of the OpenGL 3.0 Specification.
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). If
the first time <ctx> is made current, it is without a default
framebuffer, then the viewport and scissor regions are set as though
glViewport(0,0,0,0) and glScissor(0,0,0,0) were called."
However, the viewport and scissor dimensions are not modified when
<ctx> is subsequently made current; it is the client's
responsibility to reset the viewport and scissor in this case."
Sharing Objects Between Contexts
--------------------------------
(add to the description of wglShareLists)
Future versions of OpenGL may only support being added to a share
group at context creation time. Specifying such a version of a
context as either the <hglrc1> or <hglrc2> arguments to
wglShareLists will fail. wglShareLists will return FALSE, and
GetLastError will return ERROR_INCOMPATIBLE_DEVICE_CONTEXTS_ARB.
Dependencies on WGL_ARB_extensions_string
Because there is no way to extend wgl, these calls are defined in
the ICD and can be called by obtaining the address with
wglGetProcAddress. Because this extension is a WGL extension, it is
not included in the GL_EXTENSIONS string. Its existence can be
determined with the WGL_ARB_extensions_string extension.
Dependencies on WGL_ARB_create_context
If WGL_ARB_create_context_profile is supported, then
WGL_ARB_create_context must also be supported.
Dependencies on OpenGL 3.2 and later OpenGL versions
If WGL_ARB_create_context is supported, and if the OpenGL
implementation supports OpenGL 3.2 or later, then
WGL_ARB_create_context_profile must also be supported. If the OpenGL
implementation does not support OpenGL 3.2 or later, then
WGL_ARB_create_context_profile may or may not be supported.
If WGL_ARB_create_context_profile is not supported, then the
WGL_CONTEXT_PROFILE_MASK_ARB attribute, the
WGL_CONTEXT_CORE_PROFILE_BIT_ARB and
WGL_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 an
error.
New State
None
New Implementation Dependent State
None
Conformance Tests
TBD
Sample Code
TBD
Issues
1) Can different GL context versions share data?
PROPOSED: Yes, with restrictions as defined by the supported feature
sets. For example, program and shader objects cannot be shared with
OpenGL 1.x contexts, which do not support them.
NOTE: When the new object model is introduced, sharing must be
established at creation time, since the object handle namespace is
also shared. wglShareLists would therefore fail if either context
parameter to it were to be a context supporting the new object
model.
2) Should we introduce a token WGL_NONE to terminate attribute lists,
instead of using the value 0, by analogy to GLX and EGL?
RESOLVED: No.
3) Should all GL context versions be able to bind to all the same pixel
formats?
RESOLVED: unlike EGL, we don't expose the version restriction in the
pixel format. Instead, wglMakeCurrent may fail when binding contexts
to surfaces if the surface type is unrecognized by that context
version. No specific examples exist at present, but in a
hypothetical future version of the API supporting only the new
object model, such an API probably could not bind to pbuffer
surfaces.
4) Should there be a way to make a context current without binding
it to a window system drawable at the same time?
RESOLVED: Yes, but only in OpenGL 3.0 and later. This results in a
context with an invalid default framebuffer, the meaning of which is
defined in the OpenGL 3.0 specification.
NOTE: Apparently on Windows, opengl32.dll makes use of the drawable
argument to identify the namespace of the driver, so we may not be
able to work around it.
5) Should we add a token to the attrib list for pixel format selection
to indicate the GL context version, instead of introducing a new
entry point for context creation?
RESOLVED: No. We want pixel formats to be portable between
feature-incompatible context versions, so that drawables and GL
objects that make sense to share, may be shared between such
contexts. This is important for code migration and backward
compatibility.
6) Do we need a "can be shared" parameter at context creation time?
RESOLVED: No. All contexts have potential to share objects (whether
they actually can share depends on context version and feature sets,
and the address space they're created in). Savings from saying a
context cannot share objects are unclear but probably minimal. Such
a parameter would default to TRUE if it existed.
7) How are "debug contexts" created?
RESOLVED: by specifying the WGL_CONTEXT_DEBUG_BIT_ARB flag in the
WGL_CONTEXT_FLAGS_ARB attribute value.
DISCUSSION: For the most part, the behavior of debug contexts is
being determined by the ARB Ecosystem TSG. However, whatever their
behavior, it's clear that "debug contexts" may differ at a basic
level from regular contexts. Debug contexts might even go down a
completely separate driver path. So it's essential to know at
context creation time if a debug context is required.
8) Is wglCreateContextVersion a good name?
Ian Romanick suggests wglCreateContextAttribs instead. Changed in
version 12.
9) Should the context version be named with separate major and minor
number attributes, or as a single (major*100 + minor*10) number as
in GLSL (e.g. version == 220 <-> major = 2, minor = 2)?
John Kessenich argues for consistency with the existing GLSL naming
scheme.
10) How are profiles specified? Why is the profile attribute a bitmask
rather than an enum?
RESOLVED: Profiles are specified as individual bits passed in a
bitmask attribute. This attribute is ignored unless the OpenGL
version requested defines profiles (OpenGL 3.2 and later). While
only a single profile can be specified today, it is not unlikely
that eventually there will be profiles defined than can be
implemented in the same context. In that case we will need to be
able to specify multiple profiles at context creation and in the GL
context profile query, for which a bitmask is appropriate.
11) Why is the value of WGL_CONTEXT_PROFILE_MASK_ARB in the GL
core enumerant range?
RESOLVED: The token value for the context profile mask and for the
context profile bits should be shared by GL, GLX, and WGL to ease
implementation and reduce programming errors. These values are drawn
from the GL token ranges.
12) What errors can result from requesting a profile?
RESOLVED: Only a single profile can currently be requested.
Requesting no profile, more than one profile, or an unrecognized
profile are all errors.
13) How does the profile request interact with older GL versions?
RESOLVED: It does not. The profile mask is ignored unless the
requested GL version is >= 3.2.
DISCUSSION: Bruce had proposed using the profile mask to control
whether or not GL_ARB_compatibility was provided in earlier GL
versions, but general feeling was that apps had already had to sort
this out, and it's difficult to see how to define a default value
that can always be implemented (core profile) without changing the
existing behavior of wglCreateContextAttribsARB on implementations
which implement GL_ARB_compatibility by default when an OpenGL 3.1
context is requested.
14) How does the profile request interact with the forward compatibility
bit?
RESOLVED: Nothing special need be done here. If the forward
compatibility bit is set, the returned context must not implement
deprecated functionality in that profile (nothing is deprecated
from the OpenGL 3.2 compatibility profile, so a forward-compatible
compatibility profile has exactly the same functionality as
a non-forward-compatible compatibility profile, while a
forward-compatible core profile would leave out only the handful
of features - wide lines and two queries - deprecated from core
OpenGL 3.2).
15) How is context sharing between contexts of different versions
handled?
RESOLVED: It's up to the implementation whether or not to allow
this, and to define behavior when shared objects include state or
behaviors not described by one of the contexts sharing them (for
example, textures with nonzero width borders shared by 3.2 core and
compatibility profile contexts).
16) Is the GL_ARB_compatibility extension equivalent to the
compatibility profile?
RESOLVED: No. The extension refers specifically to functionality
removed from OpenGL 3.1 and restored by this extension. The
compatibility profile also restores this functionality, but may
define additional interactions between new features in version 3.N
and the functionality removed in OpenGL 3.1.
In other words, the extension is a subset of the compatibility
profile. A context implementing the compatibility profile for OpenGL
3.2 or greater may (and probably will) choose to export
GL_ARB_compatibility, but this is not required.
17) If the core profile is requested, what additional functionality
can be provided?
RESOLVED: Functionality defined only by the compatibility profile
cannot be implemented by a context supporting the core profile. For
example, if a 3.2 core profile is requested, that context cannot
implement the GL_ARB_compatibility extension. However, any desired
new functionality may be exposed via vendor or ARB extensions in the
normal fashion.
Revision History
Version 20, 2009/07/28 - Correct issue 14 to note that the 3.2
compatibility profile does not deprecated anything.
Version 19, 2009/07/27 - Add profiled context creation functionality
(WGL_CONTEXT_PROFILE_MASK_ARB and the associated bit tokens, error
code, and issues 10-16). Clarify that if the core profile is
requested, the returned context cannot restore functionality from
the compatibility profile (issue 17 and corresponding spec
language). Add ERROR_INVALID_PARAMETER error if an unrecognized
attribute is specified. Specify the interdependencies between the
two WGL extensions defined here and OpenGL 3.2, including the
requirement that WGL_ARB_create_context_profile be supported if an
OpenGL 3.2 or later implementation is supported.
Version 18, 2009/07/24 - Specify that repeated attribute values
always result in the last specified value being used.
Version 17, 2009/07/23 - Update the extension to clarify
interactions with OpenGL 3.1 and greater, allow returning 3.0 and
greater contexts from the legacy context creation routines so long
as they're backwards compatible, and mandate that requesting a
forward-compatible context always return exactly the requested
version (bugs 5112, 5349).
Version 16, 2008/08/21 - Add initial viewport/scissor setting
behavior (cloned from GLX, including the case when no default
framebuffer is made current.
Version 15, 2008/08/10 - Assign enumerant values and extension
number.
Version 14, 2008/07/10 - Add trailing zero to array attributes in
wglCreateLayerContext example (Pat Brown).
Version 13, 2008/07/03 - Update versioning behavior so asking for <=
2.1 will return <= 2.1, asking for 3.0 will return 3.0, and noting
that we must update interactions with GL once 3.1 is defined.
Mandated behavior of legacy context creation APIs when this
extension is supported (bug 3595).
Version 12, 2008/07/02 - Rename WGL_PREVIEW_BIT to
WGL_CONTEXT_FORWARD_COMPATIBLE_BIT and other replace "preview
context" with "forward-compatible context". Rename
wglCreateContextVersion to wglCreateContextAttribs.
Version 11, 2008/06/12 - Use ARB suffix. Raise ERROR_INVALID_VERSION
instead of ERROR_INVALID_DATA on a bad version/preview combination.
Version 10, 2008/04/08 - Changed "lite" to "preview" (still open for
discussion however), and changed version "2.2" to "3.0" following
the marketing TSG recommendation. Changed definition of preview
contexts so that deprecated functionality *must not* be supported.
Added issue 10 about how to handle profiles.
Version 9, 2008/02/07 - Added version naming issue 9.
Version 8, 2008/02/07 - Added naming issue 8. Removed reference to
GL version 3 in "Sharing Objects Between Contexts".
Version 7, 2008/02/01 - Rewrote issues list in light of new API
direction, and reopened some issues. Added separate major and minor
version attributes and "lite" API flag.
Version 6, 2007/05/22 - Resolve issue 4, although the exact
mechanism is still unknown.
Version 5, 2007/04/09 - Added WGL_CONTEXT_FLAGS attribute and
WGL_CONTEXT_DEBUG_BIT flag, and a high-level description of the
concept of "debug contexts".
Version 4, 2007/02/06 - Removed CreateContextVersion error when GL2
and Longs Peak contexts are placed in the same share group, and
referred to the GL_EXT_bind_image extension in issue 1. Added issues
6 ("can be shared" attribute) and 7 (creation of debug contexts) per
discussion at the Atlanta F2F ARB meeting. Added error condition for
wglShareLists if passed a Longs Peak context handle.
Version 3, 2007/01/22 - added issue 5.
Version 2, 2007/01/17 - change to the same style as
eglCreateContext, using an attribute list. Add wglMakeCurrent
language disallowing current 3.x contexts bound to pbuffers, and
allowing current 3.x context without a window-system provided
framebuffer.
Version 1, 2007/1/17 - First draft