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

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

*Last Modified Date*::
    2023-12-04
*IP Status*::
    No known IP claims.
*Contributors*::
    Cass Everitt, Oculus +
    Johannes van Waveren, Oculus +
    Martin Renschler, Qualcomm +
    Krzysztof Kosiński, Google +
    Xiang Wei, Meta



*Overview*

For XR to be comfortable, it is important for applications to deliver frames
quickly and consistently.
In order to make sure the important application threads get their full share
of time, these threads must be identified to the system, which will adjust
their scheduling priority accordingly.

*New Object Types*

*New Flag Types*

*New Enum Constants*

elink:XrResult enumeration is extended with:

* ename:XR_ERROR_ANDROID_THREAD_SETTINGS_ID_INVALID_KHR
* ename:XR_ERROR_ANDROID_THREAD_SETTINGS_FAILURE_KHR

*New Enums*
[open,refpage='XrAndroidThreadTypeKHR',desc='Enum describing Android thread types',type='enums']
--
The possible thread types are specified by the elink:XrAndroidThreadTypeKHR
enumeration:

include::{generated}/api/enums/XrAndroidThreadTypeKHR.adoc[]

.Enumerants
****
* ename:XR_ANDROID_THREAD_TYPE_APPLICATION_MAIN_KHR +
  hints the XR runtime that the thread is doing time critical CPU tasks
* ename:XR_ANDROID_THREAD_TYPE_APPLICATION_WORKER_KHR +
  hints the XR runtime that the thread is doing background CPU tasks
* ename:XR_ANDROID_THREAD_TYPE_RENDERER_MAIN_KHR +
  hints the XR runtime that the thread is doing time critical graphics
  device tasks
* ename:XR_ANDROID_THREAD_TYPE_RENDERER_WORKER_KHR +
  hints the XR runtime that the thread is doing background graphics device
  tasks
****
--

*New Structures*

*New Functions*
[open,refpage='xrSetAndroidApplicationThreadKHR',desc='declare threads to be of a certain priority type',type='protos',xrefs='']
--
To declare a thread to be of a certain elink:XrAndroidThreadTypeKHR type
call:

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

.Parameter Descriptions
****
* pname:session is a valid slink:XrSession handle.
* pname:threadType is a classification of the declared thread allowing the
  XR runtime to apply the relevant priority and attributes.
  If such settings fail, the runtime must: return
  ename:XR_ERROR_ANDROID_THREAD_SETTINGS_FAILURE_KHR.
* pname:threadId is the kernel thread ID of the declared thread, as returned
  by `gettid()` or `android.os.process.myTid()`.
  If the thread ID is invalid, the runtime must: return
  ename:XR_ERROR_ANDROID_THREAD_SETTINGS_ID_INVALID_KHR.
****

flink:xrSetAndroidApplicationThreadKHR allows to declare an XR-critical
thread and to classify it.

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

*Version History*

* Revision 1, 2017-01-17 (Johannes van Waveren)
** Initial draft.
* Revision 2, 2017-10-31 (Armelle Laine)
** Move the performance settings to EXT extension.
* Revision 3, 2018-12-20 (Paul Pedriana)
** Revised the error code naming to use KHR and renamed
   xrSetApplicationThreadKHR -> flink:xrSetAndroidApplicationThreadKHR.
* Revision 4, 2019-01-24 (Martin Renschler)
** Added enum specification, reformatting
* Revision 5, 2019-07-17 (Krzysztof Kosiński)
** Clarify the type of thread identifier used by the extension.
* Revision 6, 2023-12-04 (Xiang Wei)
** Revise/fix the hints of enum specification
