# gvr::ControllerApi

`#include <gvr_controller.h>`

This is a convenience C++ wrapper for the Controller C API.

## Summary

This wrapper strategy prevents ABI compatibility issues between compilers by ensuring that the interface between client code and the implementation code in libgvr.so is a pure C interface. The translation from C++ calls to C calls provided by this wrapper runs entirely in the client's binary and is compiled by the client's compiler.

Methods in this class are only documented insofar as the C++ wrapping logic is concerned; for information about the method itself, please refer to the corresponding function in the C API.

Typical C++ initialization example:

```
std::unique_ptr controller_api(new ControllerApi);

// Your GVR context pointer (which can be obtained from GvrLayout)
gvr_context* context = .....;  // (get it from GvrLayout)

// Set up the options:
int32_t options = ControllerApi::DefaultOptions();

// Enable non-default options, if you need them:
options |= GVR_CONTROLLER_ENABLE_GYRO;

// Init the ControllerApi object:
bool success = controller_api->Init(options, context);
if (!success) {
  // Handle failure.
  // Do NOT call other methods (like Resume, etc) if init failed.
  return;
}

// Resume the ControllerApi (if your app is on the foreground).
controller_api->Resume();

ControllerState state;
```

<br />

Usage example:

```
void DrawFrame() {
  state.Update(*controller_api);
  // ... process controller state ...
}

// When your application gets paused:
void OnPause() {
  controller_api->Pause();
}

// When your application gets resumed:
void OnResume() {
  controller_api->Resume();
}
```

<br />

To conserve battery, be sure to call [Pause()](https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a8265c1a53847ee5253df4635a46ccf23) and [Resume()](https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a19b369fc23e5d24331ecd90e17ee211f) when your app gets paused and resumed, respectively. This will allow the underlying logic to unbind from the VR service and let the controller sleep when no apps are using it.

THREADING: this class is thread-safe and reentrant after initialized with [Init()](https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a3415cdecf69b63666acae3afd9fe77b6).

### Inheritance

Inherits from: [gvr::WrapperBase\< gvr_controller_context, gvr_controller_destroy \>](https://developers.google.com/vr/reference/android-ndk/class/gvr/wrapper-base)

| ### Public static functions ||
|---|---|
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a9c2d51518648a1c1b70f9a9869ad2167()` | `std::unique_ptr< https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api >` |
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a521fa440573ac64e34d922914c0dfb1f()` | `int32_t` Returns the default controller options. |
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a4c0506b1fd6fe078392bb766b23944e2(https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1gaae9868cb18a642676cc9ca2364adee8d status)` | `const char *` Convenience functions to convert enums to strings. |
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a7d42d4ece044daef7ef37194e6df4ce7(https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1gaedb36d874b0add14801d22bdf2b64e9f state)` | `const char *` |
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1af2a6ccc4988fc2f67010a2caa389388e(https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga25a81f172e4de5c794b8f3ddb6194f41 button)` | `const char *` |
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1abcc9a9940a317508bc9f31e6a8c17d33(https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga5fa47795f01fd630034592fe562669ce level)` | `const char *` |

| ### Public functions ||
|---|---|
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a7bfc57b848d5f9f79af5c384f0b4809b(const ControllerHandedness handedness, const https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga97eb4ac3be58678a987c1ba9a5c52802 behavior, const https://developers.google.com/vr/reference/android-ndk/struct/gvr-mat4f#structgvr__mat4f & head_space_from_start_space_rotation)` | `void` For more information, see [gvr_controller_apply_arm_model()](https://developers.google.com/vr/reference/android-ndk/group/controller#group___controller_1ga74887cb6cf3b6cd5c8ecca6055964a9d). |
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a7be22e53801b0dd0dbda6c69c133da2d(int32_t controller_index, const ControllerHandedness handedness, const https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga97eb4ac3be58678a987c1ba9a5c52802 behavior, const https://developers.google.com/vr/reference/android-ndk/struct/gvr-mat4f#structgvr__mat4f & head_space_from_start_space_rotation)` | `void` For more information, see [gvr_controller_apply_arm_model()](https://developers.google.com/vr/reference/android-ndk/group/controller#group___controller_1ga74887cb6cf3b6cd5c8ecca6055964a9d). |
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1aff034e73e52288139f7f22b29173876f()` | `int32_t` Returns the number (N) of controllers currently available. |
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a3415cdecf69b63666acae3afd9fe77b6(int32_t options, https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *context)` | `bool` Initializes the controller API. |
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1ab45df245ebe694e8d7cba54e9e7d9cfa(JNIEnv *env, jobject android_context, jobject class_loader, int32_t options, https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *context)` | `bool` Overload of [Init()](https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a3415cdecf69b63666acae3afd9fe77b6) with explicit Android context and class loader (for Android only). |
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a0d7373c27247a56b7caf6964f956eb3d(int32_t options)` | `bool` Convenience overload that calls Init without a gvr_context. |
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a8265c1a53847ee5253df4635a46ccf23()` | `void` Pauses the controller. |
| `https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a19b369fc23e5d24331ecd90e17ee211f()` | `void` Resumes the controller. |

## Public static functions

### Create

```
std::unique_ptr< ControllerApi > Create()
```

### DefaultOptions

```
int32_t DefaultOptions()
```
Returns the default controller options.

### ToString

```
const char * ToString(
  ControllerApiStatus status
)
```
Convenience functions to convert enums to strings.

For more information, see the corresponding functions in the C API.

### ToString

```
const char * ToString(
  ControllerConnectionState state
)
```

### ToString

```
const char * ToString(
  ControllerButton button
)
```

### ToString

```
const char * ToString(
  ControllerBatteryLevel level
)
```

## Public functions

### ApplyArmModel

```
void ApplyArmModel(
  const ControllerHandedness handedness,
  const ArmModelBehavior behavior,
  const Mat4f & head_space_from_start_space_rotation
)
```
For more information, see [gvr_controller_apply_arm_model()](https://developers.google.com/vr/reference/android-ndk/group/controller#group___controller_1ga74887cb6cf3b6cd5c8ecca6055964a9d).

### ApplyArmModel

```
void ApplyArmModel(
  int32_t controller_index,
  const ControllerHandedness handedness,
  const ArmModelBehavior behavior,
  const Mat4f & head_space_from_start_space_rotation
)
```
For more information, see [gvr_controller_apply_arm_model()](https://developers.google.com/vr/reference/android-ndk/group/controller#group___controller_1ga74887cb6cf3b6cd5c8ecca6055964a9d).

### GetControllerCount

```
int32_t GetControllerCount()
```
Returns the number (N) of controllers currently available.

Each controller can be identified by an index in the range \[0, N), which can be passed to the [ControllerState](https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-state#classgvr_1_1_controller_state) constructor to get the state instance corresponding to the controller at that index.

### Init

```
bool Init(
  int32_t options,
  gvr_context *context
)
```
Initializes the controller API.

This method must be called exactly once in the lifetime of this object. Other methods in this class may only be called after [Init()](https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a3415cdecf69b63666acae3afd9fe77b6) returns true. Note: this does not cause the [ControllerApi](https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api) to be resumed. You must call [Resume()](https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a19b369fc23e5d24331ecd90e17ee211f) explicitly in order to start using the controller.

For more information see [gvr_controller_create_and_init()](https://developers.google.com/vr/reference/android-ndk/group/controller#group___controller_1gabcb9b2f3a1e2d065bf309232cd1ffc1c).

<br />

| Details ||
|---|---|
| **Returns** | True if initialization was successful, false if it failed. Initialization may fail, for example, because invalid options were supplied. |

### Init

```
bool Init(
  JNIEnv *env,
  jobject android_context,
  jobject class_loader,
  int32_t options,
  gvr_context *context
)
```
Overload of [Init()](https://developers.google.com/vr/reference/android-ndk/class/gvr/controller-api#classgvr_1_1_controller_api_1a3415cdecf69b63666acae3afd9fe77b6) with explicit Android context and class loader (for Android only).

For more information, see: [gvr_controller_create_and_init_android()](https://developers.google.com/vr/reference/android-ndk/group/controller#group___controller_1ga6ebaaa5df7f63fa53da9726e352d4b12).

### Init

```
bool Init(
  int32_t options
)
```
Convenience overload that calls Init without a gvr_context.

### Pause

```
void Pause()
```
Pauses the controller.

For more information, see [gvr_controller_pause()](https://developers.google.com/vr/reference/android-ndk/group/controller#group___controller_1gafa841b25accbb66d48dc90824221f1bf).

### Resume

```
void Resume()
```
Resumes the controller.

For more information, see [gvr_controller_resume()](https://developers.google.com/vr/reference/android-ndk/group/controller#group___controller_1ga0d625da4677d9b521319eeb50183974a).