// Copyright (c) 2017-2024, The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/XR_KHR_opengl_enable.adoc[]

*Last Modified Date*::
    2019-07-02
*IP Status*::
    No known IP claims.
*Contributors*::
    Mark Young, LunarG +
    Bryce Hutchings, Microsoft +
    Paul Pedriana, Oculus +
    Minmin Gong, Microsoft +
    Robert Menzel, NVIDIA +
    Jakob Bornecrantz, Collabora +
    Paulo Gomes, Samsung Electronics

*Overview*

This extension enables the use of the OpenGL graphics API in an OpenXR
runtime.
Without this extension, the OpenXR runtime may: not be able to provide any
OpenGL swapchain images.

This extension provides the mechanisms necessary for an application to
generate a valid stext:XrGraphicsBindingOpenGL*KHR structure in order to
create an OpenGL-based slink:XrSession.
Note that during this process the application is responsible for creating an
OpenGL context to be used for rendering.
The runtime however will provide the OpenGL textures to render into in the
form of a swapchain.

This extension provides mechanisms for the application to interact with
images acquired by calling flink:xrEnumerateSwapchainImages.

In order to expose the structures, types, and functions of this extension,
the application must: define dlink:XR_USE_GRAPHICS_API_OPENGL, as well as an
appropriate <<appendix-window-system-header-control,window system define>>
supported by this extension, before including the OpenXR platform header
`openxr_platform.h`, in all portions of the library or application that
include it.
The window system defines currently supported by this extension are:

* dlink:XR_USE_PLATFORM_WIN32
* dlink:XR_USE_PLATFORM_XLIB
* dlink:XR_USE_PLATFORM_XCB
* dlink:XR_USE_PLATFORM_WAYLAND

Note that a runtime implementation of this extension is only required to
support the structs introduced by this extension which belong to the
platform it is running on.

Note that the OpenGL context given to the call flink:xrCreateSession must:
not be bound in another thread when calling the functions:
flink:xrCreateSession, flink:xrDestroySession, flink:xrBeginFrame,
flink:xrEndFrame, flink:xrCreateSwapchain, flink:xrDestroySwapchain,
flink:xrEnumerateSwapchainImages, flink:xrAcquireSwapchainImage,
flink:xrWaitSwapchainImage and flink:xrReleaseSwapchainImage.
It may: be bound in the thread calling those functions.
The runtime must: not access the context from any other function.
In particular the application must be able to call flink:xrWaitFrame from a
different thread than the rendering thread.

*Swapchain Flag Bits*

All elink:XrSwapchainUsageFlags valid values passed in a session created
using slink:XrGraphicsBindingOpenGLWin32KHR,
slink:XrGraphicsBindingOpenGLXlibKHR, slink:XrGraphicsBindingOpenGLXcbKHR or
slink:XrGraphicsBindingOpenGLWaylandKHR should: be ignored as there is no
mapping to OpenGL texture settings.

[NOTE]
.Note
====

In such a session, a runtime may: use a supporting graphics API, such as
Vulkan, to allocate images that are intended to alias with OpenGL textures,
and be part of an slink:XrSwapchain.
A runtime which allocates the texture with a different graphics API may:
need to enable several usage flags on the underlying native texture resource
to ensure compatibility with OpenGL.

====

*New Object Types*

*New Flag Types*

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_GRAPHICS_REQUIREMENTS_OPENGL_KHR
* ename:XR_TYPE_GRAPHICS_BINDING_OPENGL_WIN32_KHR
* ename:XR_TYPE_GRAPHICS_BINDING_OPENGL_XLIB_KHR
* ename:XR_TYPE_GRAPHICS_BINDING_OPENGL_XCB_KHR
* ename:XR_TYPE_GRAPHICS_BINDING_OPENGL_WAYLAND_KHR
* ename:XR_TYPE_SWAPCHAIN_IMAGE_OPENGL_KHR

*New Enums*

*New Structures*

The following structures are provided to supply supporting runtimes the
necessary information required to work with the OpenGL API executing on
certain operating systems.

These structures are only available when the corresponding
`XR_USE_PLATFORM_` macro is defined before including `openxr_platform.h`.

[open,refpage='XrGraphicsBindingOpenGLWin32KHR',type='structs',desc='The graphics binding structure to be passed at session creation to use OpenGL on Windows',xrefs='xrCreateSession']
--
The slink:XrGraphicsBindingOpenGLWin32KHR structure is defined as:

include::{generated}/api/structs/XrGraphicsBindingOpenGLWin32KHR.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:hDC is a valid Windows HW device context handle.
* pname:hGLRC is a valid Windows OpenGL rendering context handle.
****

When creating an OpenGL-backed slink:XrSession on Microsoft Windows, the
application will provide a pointer to an
slink:XrGraphicsBindingOpenGLWin32KHR in the `next` chain of the
slink:XrSessionCreateInfo.
As no standardized way exists for OpenGL to create the graphics context on a
specific GPU, the runtime must: assume that the application uses the
operating systems default GPU.
If the GPU used by the runtime does not match the GPU on which the OpenGL
context of the application got created, flink:xrCreateSession must: return
ename:XR_ERROR_GRAPHICS_DEVICE_INVALID.

The required window system configuration define to expose this structure
type is dlink:XR_USE_PLATFORM_WIN32.

include::{generated}/validity/structs/XrGraphicsBindingOpenGLWin32KHR.adoc[]
--

[open,refpage='XrGraphicsBindingOpenGLXlibKHR',type='structs',desc='The graphics binding structure to be passed at session creation to use OpenGL on X11 via Xlib',xrefs='xrCreateSession']
--
The slink:XrGraphicsBindingOpenGLXlibKHR structure is defined as:

include::{generated}/api/structs/XrGraphicsBindingOpenGLXlibKHR.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:xDisplay is a valid X11 sname:Display.
* pname:visualid is a valid X11 visual identifier.
* pname:glxFBConfig is a valid X11 OpenGL GLX sname:GLXFBConfig.
* pname:glxDrawable is a valid X11 OpenGL GLX sname:GLXDrawable.
* pname:glxContext is a valid X11 OpenGL GLX sname:GLXContext.
****

When creating an OpenGL-backed slink:XrSession on any Linux/Unix platform
that utilizes X11 and GLX, via the Xlib library, the application will
provide a pointer to an slink:XrGraphicsBindingOpenGLXlibKHR in the `next`
chain of the slink:XrSessionCreateInfo.

The required window system configuration define to expose this structure
type is dlink:XR_USE_PLATFORM_XLIB.

include::{generated}/validity/structs/XrGraphicsBindingOpenGLXlibKHR.adoc[]
--


[open,refpage='XrGraphicsBindingOpenGLXcbKHR',type='structs',desc='The graphics binding structure to be passed at session creation to use OpenGL on X11 via XCB',xrefs='xrCreateSession']
--
The slink:XrGraphicsBindingOpenGLXcbKHR structure is defined as:

include::{generated}/api/structs/XrGraphicsBindingOpenGLXcbKHR.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:connection is a valid sname:xcb_connection_t.
* pname:screenNumber is an index indicating which screen should be used for
  rendering.
* pname:fbconfigid is a valid XCB OpenGL GLX sname:xcb_glx_fbconfig_t.
* pname:visualid is a valid XCB OpenGL GLX sname:xcb_visualid_t.
* pname:glxDrawable is a valid XCB OpenGL GLX sname:xcb_glx_drawable_t.
* pname:glxContext is a valid XCB OpenGL GLX sname:xcb_glx_context_t.
****

When creating an OpenGL-backed slink:XrSession on any Linux/Unix platform
that utilizes X11 and GLX, via the Xlib library, the application will
provide a pointer to an slink:XrGraphicsBindingOpenGLXcbKHR in the `next`
chain of the slink:XrSessionCreateInfo.

The required window system configuration define to expose this structure
type is dlink:XR_USE_PLATFORM_XCB.

include::{generated}/validity/structs/XrGraphicsBindingOpenGLXcbKHR.adoc[]
--

[open,refpage='XrGraphicsBindingOpenGLWaylandKHR',type='structs',desc='The graphics binding structure to be passed at session creation to use OpenGL on Wayland',xrefs='xrCreateSession']
--
The slink:XrGraphicsBindingOpenGLWaylandKHR structure is defined as:

include::{generated}/api/structs/XrGraphicsBindingOpenGLWaylandKHR.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:display is a valid Wayland sname:wl_display.
****

When creating an OpenGL-backed slink:XrSession on any Linux/Unix platform
that utilizes the Wayland protocol with its compositor, the application will
provide a pointer to an slink:XrGraphicsBindingOpenGLWaylandKHR in the
`next` chain of the slink:XrSessionCreateInfo.

The required window system configuration define to expose this structure
type is dlink:XR_USE_PLATFORM_WAYLAND.

include::{generated}/validity/structs/XrGraphicsBindingOpenGLWaylandKHR.adoc[]
--

[open,refpage='XrSwapchainImageOpenGLKHR',type='structs',desc='OpenGL-specific swapchain image structure',xrefs='XrSwapchainImageBaseHeader']
--
The slink:XrSwapchainImageOpenGLKHR structure is defined as:

include::{generated}/api/structs/XrSwapchainImageOpenGLKHR.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:image is the OpenGL texture handle associated with this swapchain
  image.
****

If a given session was created with a stext:XrGraphicsBindingOpenGL*KHR, the
following conditions must: apply.

* Calls to flink:xrEnumerateSwapchainImages on an slink:XrSwapchain in that
  session must: return an array of slink:XrSwapchainImageOpenGLKHR
  structures.
* Whenever an OpenXR function accepts an slink:XrSwapchainImageBaseHeader
  pointer as a parameter in that session, the runtime must: also accept a
  pointer to an slink:XrSwapchainImageOpenGLKHR.

The OpenXR runtime must: interpret the bottom-left corner of the swapchain
image as the coordinate origin unless specified otherwise by extension
functionality.

The OpenXR runtime must: interpret the swapchain images in a clip space of
positive Y pointing up, near Z plane at -1, and far Z plane at 1.

include::{generated}/validity/structs/XrSwapchainImageOpenGLKHR.adoc[]
--

[open,refpage='XrGraphicsRequirementsOpenGLKHR',type='structs',desc='OpenGL API version requirements',xrefs='xrGetOpenGLGraphicsRequirementsKHR']
--
The slink:XrGraphicsRequirementsOpenGLKHR structure is defined as:

include::{generated}/api/structs/XrGraphicsRequirementsOpenGLKHR.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:minApiVersionSupported is the minimum version of OpenGL that the
  runtime supports.
  Uses dlink:XR_MAKE_VERSION on major and minor API version, ignoring any
  patch version component.
* pname:maxApiVersionSupported is the maximum version of OpenGL that the
  runtime has been tested on and is known to support.
  Newer OpenGL versions might work if they are compatible.
  Uses dlink:XR_MAKE_VERSION on major and minor API version, ignoring any
  patch version component.
****

slink:XrGraphicsRequirementsOpenGLKHR is populated by
flink:xrGetOpenGLGraphicsRequirementsKHR with the runtime's OpenGL API
version requirements.

include::{generated}/validity/structs/XrGraphicsRequirementsOpenGLKHR.adoc[]
--

*New Functions*

[open,refpage='xrGetOpenGLGraphicsRequirementsKHR',type='protos',desc='Retrieve the OpenGL version requirements for an instance and system',xrefs='XrGraphicsRequirementsOpenGLKHR']
--
To query OpenGL API version requirements for an instance and system, call:

include::{generated}/api/protos/xrGetOpenGLGraphicsRequirementsKHR.adoc[]

.Parameter Descriptions
****
* pname:instance is an slink:XrInstance handle previously created with
  flink:xrCreateInstance.
* pname:systemId is an basetype:XrSystemId handle for the system which will
  be used to create a session.
* pname:graphicsRequirements is the slink:XrGraphicsRequirementsOpenGLKHR
  output structure.
****

The flink:xrGetOpenGLGraphicsRequirementsKHR function identifies to the
application the minimum OpenGL version requirement and the highest known
tested OpenGL version.
The runtime must: return ename:XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING
(ename:XR_ERROR_VALIDATION_FAILURE may: be returned due to legacy behavior)
on calls to flink:xrCreateSession if
flink:xrGetOpenGLGraphicsRequirementsKHR has not been called for the same
pname:instance and pname:systemId.

include::{generated}/validity/protos/xrGetOpenGLGraphicsRequirementsKHR.adoc[]
--

*Issues*

*Version History*

* Revision 1, 2018-05-07 (Mark Young)
** Initial draft
* Revision 2, 2018-06-21 (Bryce Hutchings)
** Add new `xrGetOpenGLGraphicsRequirementsKHR`
* Revision 3, 2018-11-15 (Paul Pedriana)
** Specified the swapchain texture coordinate origin.
* Revision 4, 2018-11-16 (Minmin Gong)
** Specified Y direction and Z range in clip space
* Revision 5, 2019-01-25 (Robert Menzel)
** Description updated
* Revision 6, 2019-07-02 (Robert Menzel)
** Minor fixes
* Revision 7, 2019-07-08 (Rylie Pavlik)
** Adjusted member name in XCB struct
* Revision 8, 2019-11-28 (Jakob Bornecrantz)
** Added note about context not allowed to be current in a different thread.
* Revision 9, 2020-08-06 (Bryce Hutchings)
** Added new `XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING` error code
* Revision 10, 2021-08-31 (Paulo F. Gomes)
** Document handling of `XrSwapchainUsageFlags`
