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

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

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

*Overview*

This extension must be provided by runtimes supporting applications using
OpenGL ES APIs for rendering.
OpenGL ES applications need this extension to obtain compatible swapchain
images which the runtime is required to supply.
The runtime needs the following OpenGL ES objects from the application in
order to interact properly with the OpenGL ES driver: EGLDisplay, EGLConfig
and EGLContext.

These are passed from the application to the runtime in a
slink:XrGraphicsBindingOpenGLESAndroidKHR structure when creating the
slink:XrSession.
Although not restricted to Android, the OpenGL ES extension is currently
tailored for Android.

Note that the application is responsible for creating the required OpenGL ES
objects, including an OpenGL ES context to be used for rendering.

This extension also 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 source code must: define
dlink:XR_USE_GRAPHICS_API_OPENGL_ES, as well as an appropriate
<<appendix-window-system-header-control,window system define>>, before
including the OpenXR platform header `openxr_platform.h`, in all portions of
your library or application that include it.
The only window system define currently supported by this extension is:

* dlink:XR_USE_PLATFORM_ANDROID

*Swapchain Flag Bits*

All elink:XrSwapchainUsageFlags valid values passed in a session created
using slink:XrGraphicsBindingOpenGLESAndroidKHR should: be ignored as there
is no mapping to OpenGL ES 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 OpenGLES
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 ES.

====


*New Object Types*

*New Flag Types*

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_GRAPHICS_REQUIREMENTS_OPENGL_ES_KHR
* ename:XR_TYPE_GRAPHICS_BINDING_OPENGL_ES_ANDROID_KHR
* ename:XR_TYPE_SWAPCHAIN_IMAGE_OPENGL_ES_KHR

*New Enums*

*New Structures*

The following structures are provided to supply supporting runtimes the
necessary information required to work with the OpenGL ES 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='XrGraphicsBindingOpenGLESAndroidKHR',type='structs',desc='The graphics binding structure to be passed at session creation to use OpenGL ES on Android',xrefs='xrCreateSession']
--
The slink:XrGraphicsBindingOpenGLESAndroidKHR structure is defined as:

include::{generated}/api/structs/XrGraphicsBindingOpenGLESAndroidKHR.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 Android OpenGL ES sname:EGLDisplay.
* pname:config is a valid Android OpenGL ES sname:EGLConfig.
* pname:context is a valid Android OpenGL ES sname:EGLContext.
****

When creating an OpenGL ES-backed slink:XrSession on Android, the
application will provide a pointer to an
slink:XrGraphicsBindingOpenGLESAndroidKHR structure in the pname:next chain
of the slink:XrSessionCreateInfo.

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

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

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

include::{generated}/api/structs/XrSwapchainImageOpenGLESKHR.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 an index indicating the current OpenGL ES swapchain image
  to use.
****

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

* Calls to flink:xrEnumerateSwapchainImages on an slink:XrSwapchain in that
  session must: return an array of slink:XrSwapchainImageOpenGLESKHR
  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:XrSwapchainImageOpenGLESKHR structure.

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/XrSwapchainImageOpenGLESKHR.adoc[]
--

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

include::{generated}/api/structs/XrGraphicsRequirementsOpenGLESKHR.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 ES 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 ES that the
  runtime has been tested on and is known to support.
  Newer OpenGL ES versions might work if they are compatible.
  Uses dlink:XR_MAKE_VERSION on major and minor API version, ignoring any
  patch version component.
****

slink:XrGraphicsRequirementsOpenGLESKHR is populated by
flink:xrGetOpenGLESGraphicsRequirementsKHR with the runtime's OpenGL ES API
version requirements.

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

*New Functions*

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

include::{generated}/api/protos/xrGetOpenGLESGraphicsRequirementsKHR.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:XrGraphicsRequirementsOpenGLESKHR
  output structure.
****

The flink:xrGetOpenGLESGraphicsRequirementsKHR function identifies to the
application the minimum OpenGL ES version requirement and the highest known
tested OpenGL ES 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:xrGetOpenGLESGraphicsRequirementsKHR has not been called for the same
pname:instance and pname:systemId.

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

*Issues*

*Version History*

* Revision 1, 2018-05-07 (Mark Young)
** Initial draft
* Revision 2, 2018-06-21 (Bryce Hutchings)
** Add new `xrGetOpenGLESGraphicsRequirementsKHR`
* 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-12 (Martin Renschler)
** Description updated
* Revision 7, 2020-08-06 (Bryce Hutchings)
** Added new `XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING` error code
* Revision 8, 2021-08-27 (Paulo F. Gomes)
** Document handling of `XrSwapchainUsageFlags`
