.. _6 OpenXR Controller Support:

6 OpenXR Controller Support
===============================

The controller part mainly contains event and extension.


6.1	Event of Controller
---------------------------------

The event is defined as follows:

.. code-block:: c++

 enum xrt_device_eventtype
 {
     XRT_DEVICE_CONNECTCHANGED = 0,
     XRT_DEVICE_MAIN_CHANGED = 1,
     XRT_DEVICE_VERSION = 2,
     XRT_DEVICE_SN = 3,
     XRT_DEVICE_BIND_STATUS = 4,
     XRT_STATION_STATUS = 5,
     XRT_DEVICE_IOBUSY = 6,
     XRT_DEVICE_OTASTAUS = 7,
     XRT_DEVICE_ID = 8,
     XRT_DEVICE_HANDNESS_CHANGED = 15,
     XRT_DEVICE_CHANNEL = 16,
     XRT_DEVICE_LOSSRATE = 17,
     XRT_DEVICE_THREAD_STARTED = 18
 };
 typedef struct XrControllerEventChanged {
      XrStructureType              type;
      const void* XR_MAY_ALIAS     next;
      enum xrt_device_eventtype    eventtype;
      uint8_t                      controller;
      uint8_t                      status;
      uint8_t                      varying[400];
      uint16_t                     length;
 } XrControllerEventChanged;

The bottom layer notifies the top layer via xrPollevent when the controller state changes, and the corresponding type is ``XR_TYPE_EVENT_CONTROLLER_STATE_CHANGED``.

The ``xrt_device_eventtype`` is commented as follows:

.. code-block:: java

 XRT_DEVICE_CONNECTCHANGED  //the connection of controller has changed
 XRT_DEVICE_MAIN_CHANGED   //the main controller has changed
 XRT_DEVICE_VERSION   //return controller version
 XRT_DEVICE_SN  //return controller SN
 XRT_DEVICE_BIND_STATUS //the binding status of controller has changed
 XRT_STATION_STATUS  //the station status of controller has changed
 XRT_DEVICE_IOBUSY   //the serial port is busy
 XRT_DEVICE_OTASTAUS  //the OTA status of controller has changed
 XRT_DEVICE_ID //return controller ID
 XRT_DEVICE_HANDNESS_CHANGED  //the handness has changed
 XRT_DEVICE_CHANNEL //the electronic channel has changed
 XRT_DEVICE_LOSSRATE  //packet loss rate of controller
 XRT_DEVICE_THREAD_STARTED //the controller binding thread has started



6.2	Extension of Controller
---------------------------------

To use the feature of controller, you need to enable the extension ``XR_PICO_android_controller_function_ext_enable`` at ``xrCreateInstance``, and then use  ``xrGetInstanceProcAddress`` to get the function pointer to the extension function after successful creation of ``xrInstance`` . 

It is as follows:

.. code-block:: java

 PFN_xrGetControllerConnectionStatePico pfnXrGetControllerConnectionStatePico;
 xrGetInstanceProcAddr(up.mInstance,"xrGetControllerConnectionStatePico",reinterpret_cast<PFN_xrVoidFunction*>(&pfnXrGetControllerConnectionStatePico));

For the extended use of controller, you can refer to the HelloXR Sample, which shows the use of controller vibration extension ( ``xrVibrateControllerPico`` ). In this Sample, the vibration of controller is realized by long pressing the Trigger button.

The extension function definition is detailed as follows:

xrGetControllerConnectionStatePico
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Function name: XrResult XRAPI_CALL xrGetControllerConnectionStatePico(XrInstance instance,uint8_t controllerhandle,uint8_t* status)

Function: getting the connection status of controller

Parameters: controllerhandle  0 - left controller; 1 - right controller

            status - connection status  0 - disconnected; 1 - connected

Returned value: 0 - Call succeeds; other values - Call fails

xrSetMainControllerHandlePico
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Function name: XrResult XRAPI_CALL xrSetMainControllerHandlePico(XrInstance instance,int controllerHandle)

Function: setting the main controller

Parameters: controllerHandle   0 - left controller; 1 - right controller

Returned value: 0 - Call succeeds; other values - Call fails


xrGetMainControllerHandlePico（NEW）
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Function name: XrResult XRAPI_CALL xrGetMainControllerHandlePico(XrInstance instance,int* controllerHandle)

Function: getting the main controller

Parameters: controllerHandle   0 - left controller; 1 - right controller

Returned value: 0 - Call succeeds; other values - Call fails

xrSetPhyControllerEnableKeyPico（NEW）
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Function name: XrResult XRAPI_CALL xrSetPhyControllerEnableKeyPico(XrInstance instance,bool isEnable, XrControllerKeyMap Key);

Function: whether the application blocks the specified key 

Parameters: isEnable   true - key enable, false - key block

	Key - corresponding key

Returned value: 0 - Call succeeds; other values - Call fails

xrGetPhyControllerInfoPico（NEW）
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Function name: XrResult XRAPI_CALL xrGetPhyControllerInfoPico(XrInstance instance,int device, XrControllerInfo* controllerinfo)

Function: getting controller information data

Parameters: device   0 - left controller; 1 - right controller

	controllerinfo - controller information data, bluetooth address, controller type version number, etc.

Returned value: 0 - Call succeeds; other values - Call fails

xrVibrateControllerPico
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Function name: XrResult XRAPI_CALL xrVibrateControllerPico(XrInstance instance, float strength,int time,int controllerHandle)

Function: setting controller vibration

Parameters: strength - strength of vibration, range: 0 to 1

	        time - time of vibration, range: 0 to 65535, unit: ms 

	        controllerHandle   0 - left controller; 1 - right controller

Returned value: 0 - Call succeeds; other values - Call fails