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

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

*Last Modified Date*::
    2021-04-14
*IP Status*::
    No known IP claims.
*Contributors*::
    Lachlan Ford, Microsoft +
    Rylie Pavlik, Collabora +


*Overview*

The +XR_EXT_conformance_automation+ allows conformance test and runtime
developers to provide hints to the underlying runtime as to what input the
test is expecting.
This enables runtime authors to automate the testing of their runtime
conformance.
This is useful for achieving rapidly iterative runtime development whilst
maintaining conformance for runtime releases.

This extension provides the following capabilities:

* The ability to toggle the active state of an input device.
* The ability to set the state of an input device button or other input
  component.
* The ability to set the location of the input device.

Applications may: call these functions at any time.
The runtime must: do its best to honor the request of applications calling
these functions, however it does not guarantee that any state change will be
reflected immediately, at all, or with the exact value that was requested.
Applications are thus advised to wait for the state change to be observable
and to not assume that the value they requested will be the value observed.
If any of the functions of this extension are called, control over input
must: be removed from the physical hardware of the system.

// This should be kept in sync with conformance_automation_warning.adoc
// which has one additional sentence at the start.
.Warning
****
This extension is **not** intended for use by non-conformance-test
applications.
A runtime may: require a runtime-specified configuration such as a
"developer mode" to be enabled before reporting support for this extension
or providing a non-stub implementation of it.

**Do not** use this functionality in a non-conformance-test application!
****

*New Object Types*


*New Flag Types*


*New Enum Constants*


*New Enums*


*New Structures*


*New Functions*

[open,refpage='xrSetInputDeviceActiveEXT',type='protos',desc='Sets the active state of the input device']
--
include::{generated}/api/protos/xrSetInputDeviceActiveEXT.adoc[]

.Parameter Descriptions
****
* pname:session is the slink:XrSession to set the input device state in.
* pname:interactionProfile is the path representing the interaction profile
  of the input device (e.g.
  pathname:/interaction_profiles/khr/simple_controller).
* pname:topLevelPath is the path representing the input device (e.g.
  pathname:/user/hand/left).
* pname:isActive is the requested activation state of the input device.
****

// In ref pages, expands to a warning to not use this in normal apps.
include::{appendices}/conformance_automation_warning.adoc[]

.Valid Usage
****
* pname:session must: be a valid session handle.
* pname:topLevelPath must: be a valid top level path.
****

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

--

[open,refpage='xrSetInputDeviceStateBoolEXT',type='protos',desc='Sets the state of a boolean input source on the input device']
--
include::{generated}/api/protos/xrSetInputDeviceStateBoolEXT.adoc[]

.Parameter Descriptions
****
* pname:session is the slink:XrSession to set the input device state in.
* pname:topLevelPath is the path representing the input device (e.g.
  pathname:/user/hand/left).
* pname:inputSourcePath is the full path of the input component for which we
  wish to set the state for (e.g.
  pathname:/user/hand/left/input/select/click).
* pname:state is the requested boolean state of the input device.
****

// In ref pages, expands to a warning to not use this in normal apps.
include::{appendices}/conformance_automation_warning.adoc[]

.Valid Usage
****
* pname:session must: be a valid session handle.
* pname:topLevelPath must: be a valid top level path.
* pname:inputSourcePath must: be a valid input source path.
****

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

--

[open,refpage='xrSetInputDeviceStateFloatEXT',type='protos',desc='Sets the state of a float input source on the input device']
--
include::{generated}/api/protos/xrSetInputDeviceStateFloatEXT.adoc[]

.Parameter Descriptions
****
* pname:session is the slink:XrSession to set the input device state in.
* pname:topLevelPath is the path representing the input device (e.g.
  pathname:/user/hand/left).
* pname:inputSourcePath is the full path of the input component for which we
  wish to set the state for (e.g.
  pathname:/user/hand/left/input/trigger/value).
* pname:state is the requested float state of the input device.
****

// In ref pages, expands to a warning to not use this in normal apps.
include::{appendices}/conformance_automation_warning.adoc[]

.Valid Usage
****
* pname:session must: be a valid session handle.
* pname:topLevelPath must: be a valid top level path.
* pname:inputSourcePath must: be a valid input source path.
****

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

--

[open,refpage='xrSetInputDeviceStateVector2fEXT',type='protos',desc='Sets the state of a 2D vector input source on the input device']
--
include::{generated}/api/protos/xrSetInputDeviceStateVector2fEXT.adoc[]

.Parameter Descriptions
****
* pname:session is the slink:XrSession to set the input device state in.
* pname:topLevelPath is the path representing the input device (e.g.
  pathname:/user/hand/left).
* pname:inputSourcePath is the full path of the input component for which we
  wish to set the state for (e.g.
  pathname:/user/hand/left/input/thumbstick).
* pname:state is the requested two-dimensional state of the input device.
****

// In ref pages, expands to a warning to not use this in normal apps.
include::{appendices}/conformance_automation_warning.adoc[]

.Valid Usage
****
* pname:session must: be a valid session handle.
* pname:topLevelPath must: be a valid top level path.
* pname:inputSourcePath must: be a valid input source path.
****

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

--

[open,refpage='xrSetInputDeviceLocationEXT',type='protos',desc='Sets the effective location of a pose input source on the input device']
--
include::{generated}/api/protos/xrSetInputDeviceLocationEXT.adoc[]

.Parameter Descriptions
****
* pname:session is the slink:XrSession to set the input device state in.
* pname:topLevelPath is the path representing the input device (e.g.
  pathname:/user/hand/left).
* pname:inputSourcePath is the full path of the input component for which we
  wish to set the pose for (e.g. pathname:/user/hand/left/input/grip/pose).
* pname:pose is the requested pose state of the input device.
****

// In ref pages, expands to a warning to not use this in normal apps.
include::{appendices}/conformance_automation_warning.adoc[]

.Valid Usage
****
* pname:session must: be a valid session handle.
* pname:topLevelPath must: be a valid top level path.
* pname:inputSourcePath must: be a valid input source path.
* pname:space must: be a valid slink:XrSpace.
* pname:pose must: be a valid slink:XrPosef.
****

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

--

*New Function Pointers*

*Issues*

None

*Version History*

* Revision 1, 2019-10-01 (Lachlan Ford)
** Initial draft
* Revision 2, 2021-03-04 (Rylie Pavlik)
** Correct errors in function parameter documentation.
* Revision 3, 2021-04-14 (Rylie Pavlik)
** Fix missing error code
