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

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

*Last Modified Date*::
    2019-07-17
*IP Status*::
    No known IP claims.
*Contributors*::
    Robert Menzel, NVIDIA +
    Martin Renschler, Qualcomm +
    Krzysztof Kosiński, Google

*Overview*

When the application creates an slink:XrInstance object on Android systems,
additional information from the application has to be provided to the XR
runtime.

The Android XR runtime must: return error ename:XR_ERROR_VALIDATION_FAILURE
if the additional information is not provided by the application or if the
additional parameters are invalid.

*New Object Types*

*New Flag Types*

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_INSTANCE_CREATE_INFO_ANDROID_KHR

*New Enums*

*New Structures*
[open,refpage='XrInstanceCreateInfoAndroidKHR',desc='Creates an OpenXR Instance',type='structs',xrefs='xrCreateInstance xrDestroyInstance']
--
The slink:XrInstanceCreateInfoAndroidKHR structure is defined as:

include::{generated}/api/structs/XrInstanceCreateInfoAndroidKHR.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:applicationVM is a pointer to the JNI's opaque `JavaVM` structure,
  cast to a void pointer.
* pname:applicationActivity is a JNI reference to an `android.app.Activity`
  that will drive the session lifecycle of this instance, cast to a void
  pointer.
****

slink:XrInstanceCreateInfoAndroidKHR contains additional Android specific
information needed when calling flink:xrCreateInstance.
The pname:applicationVM field should be populated with the `JavaVM`
structure received by the `JNI_OnLoad` function, while the
pname:applicationActivity field will typically contain a reference to a Java
activity object received through an application-specific native method.
The slink:XrInstanceCreateInfoAndroidKHR structure must: be provided in the
pname:next chain of the slink:XrInstanceCreateInfo structure when calling
flink:xrCreateInstance.


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

*New Functions*

*Issues*

*Version History*

* Revision 1, 2017-05-26 (Robert Menzel)
** Initial draft
* Revision 2, 2019-01-24 (Martin Renschler)
** Added error code, reformatted
* Revision 3, 2019-07-17 (Krzysztof Kosiński)
** Non-substantive clarifications.
