# GVR Beta APIs

# GVR Beta APIs

These are Beta APIs that are likely to change between releases.

## Summary

This file contains Daydream Beta APIs. Beta APIs are not subject to the usual deprecation process. Beta APIs are expected to change and may be removed entirely in a future version without warning. Beta APIs might also use functionality that is not available to all users or on all devices.

| ### Enumerations ||
|---|---|
| `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga2569b0020ba7b3aaa04c3083ec0a10ee{ https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gga2569b0020ba7b3aaa04c3083ec0a10eea428402bd0913b687273df6cd97bc9a92 = 0, https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gga2569b0020ba7b3aaa04c3083ec0a10eea2af5f96c508eceea2b2ac09387490a21 = 1, https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gga2569b0020ba7b3aaa04c3083ec0a10eea5772e7a7915ba7b457f226deee6f4a89 = 2 }` | enumConfiguration for a specific controller. |
| `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga6c7e53106b1ccd9f427d447e44a40835{ https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gga6c7e53106b1ccd9f427d447e44a40835ae2ddd5a563d2626d545164f5765f172d = (1U << 0), https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gga6c7e53106b1ccd9f427d447e44a40835ab299f51fce9d1782a644c945dec16a9d = (1U << 1), https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gga6c7e53106b1ccd9f427d447e44a40835a96e158488f1448482b89656049b9ea64 = (1U << 2), https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gga6c7e53106b1ccd9f427d447e44a40835a9955ad60c359960103bf081d6ee76b62 = (1U << 3) }` | enumTracking state for experimental 6DoF controllers. |
| `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga25d1ed59fa8607347aadf31314c24178{ https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gga25d1ed59fa8607347aadf31314c24178a59c55ed950b910b00fdcaeb357dac248 = 0, https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gga25d1ed59fa8607347aadf31314c24178a6904c1625ff896ffa032e5f4cd0b6a08 = 1, https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gga25d1ed59fa8607347aadf31314c24178a3479b9b3b5eadee857c4e002fc7faa06 = 2 }` | enumThe different supported appearances that determine how camera see-through frames will be drawn. |
| `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga418e768dffcbf0d5a9b180b534f9e851{ https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gga418e768dffcbf0d5a9b180b534f9e851ac4d244437afbb3a25d68bdd508f1d9e8 = 0, https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gga418e768dffcbf0d5a9b180b534f9e851a9a190be0dd76dc5d69be6c959203e396 = 1 }` | enumThe different scene types that an app can have. |

| ### Typedefs ||
|---|---|
| `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga7f5033e9e06cd01dd914bb88d9324d34` | typedef `struct gvr_beta_see_through_config_` Configuration settings for see-through. |

| ### Functions ||
|---|---|
| `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gaac84e3b782f925eaa6b9c39f15b7dc1a(const https://developers.google.com/vr/reference/android-ndk/group/controller#group___controller_1gae7d7740693479bd8b5e9841b6df8d665 *controller_context, const gvr_controller_state *state)` | `int32_t` Returns the configuration of the given controller. |
| `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga1d0f72891247045c7e8e6374cd5dc1fe(const gvr_controller_state *state)` | `int32_t` Returns the tracking status of the controller. |
| `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga1c22130f09553bc701e3a171a8aa1146(https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *gvr)` | `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga7f5033e9e06cd01dd914bb88d9324d34 *` Creates a [gvr_beta_see_through_config](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga7f5033e9e06cd01dd914bb88d9324d34) instance. |
| `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gaf2982f58ecb8b4365985b6baf348a1fe(https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga7f5033e9e06cd01dd914bb88d9324d34 **config)` | `void` Destroys a [gvr_beta_see_through_config](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga7f5033e9e06cd01dd914bb88d9324d34) instance created by [gvr_beta_see_through_config_create()](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga1c22130f09553bc701e3a171a8aa1146). |
| `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga7f4f7e0f2c3bd7cdb99450b63bbc5af4(https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga7f5033e9e06cd01dd914bb88d9324d34 *config, int32_t camera_mode)` | `void` Sets the camera mode for the given see-through config which determines the see-through's appearance. |
| `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga4c07c1442abdd3441c51056169bdc1dc(https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga7f5033e9e06cd01dd914bb88d9324d34 *config, int32_t scene_type)` | `void` Sets the scene type on the given see-through config. |
| `https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gae09f837120bddcbfbf3164b4ae621e4b(https://developers.google.com/vr/reference/android-ndk/group/types#group__types_1ga23df772969ac0cc13f77fffdec5c18ea *context, const https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga7f5033e9e06cd01dd914bb88d9324d34 *config)` | `void` The main function for enabling/disabling and configuring see-through. |

## Enumerations

### gvr_beta_controller_configuration_type

```
 gvr_beta_controller_configuration_type
```
Configuration for a specific controller.

| Properties ||
|---|---|
| `GVR_BETA_CONTROLLER_CONFIGURATION_3DOF` | Daydream (3DoF) controller. This controller might have simulated position data. |
| `GVR_BETA_CONTROLLER_CONFIGURATION_6DOF` | Experiemntal 6DoF controller. |
| `GVR_BETA_CONTROLLER_CONFIGURATION_UNKNOWN` | Used when controller configuration is unknown. |

### gvr_beta_controller_tracking_status_flags

```
 gvr_beta_controller_tracking_status_flags
```
Tracking state for experimental 6DoF controllers.

| Properties ||
|---|---|
| `GVR_BETA_CONTROLLER_TRACKING_STATUS_FLAG_OCCLUDED` | Indicates whether the controller is occluded. For optically tracked controllers, occlusion happens for a brief time as the user blocks the tracking system with their hand or the other controller. The position of the controller will be clamped to the last known value. |
| `GVR_BETA_CONTROLLER_TRACKING_STATUS_FLAG_OUT_OF_FOV` | Indicates whether the controller is out of field of view of the tracking system. The position of the controller is no longer accurate and should be ignored. |
| `GVR_BETA_CONTROLLER_TRACKING_STATUS_FLAG_TRACKING_NOMINAL` | Indicates whether the controller is tracking in full 6DoF mode. |
| `GVR_BETA_CONTROLLER_TRACKING_STATUS_FLAG_TRACKING_UNKNOWN` | Indicates whether the controller's tracking status is unknown. |

### gvr_beta_see_through_camera_mode

```
 gvr_beta_see_through_camera_mode
```
The different supported appearances that determine how camera see-through frames will be drawn.

| Properties ||
|---|---|
| `GVR_BETA_SEE_THROUGH_CAMERA_MODE_DISABLED` | The default behavior where no camera frames will be drawn. |
| `GVR_BETA_SEE_THROUGH_CAMERA_MODE_RAW_IMAGE` | The camera's image will be shown unaltered. For the devices with a grayscale camera this will be a grayscale image. |
| `GVR_BETA_SEE_THROUGH_CAMERA_MODE_TONEMAPPED` | The monochrome image will be artifically colored with darker areas given a blue tint, middle areas given an orange tint, and bright areas becoming pure white. |

### gvr_beta_see_through_scene_type

```
 gvr_beta_see_through_scene_type
```
The different scene types that an app can have.

These control where the scene is rendered from. Generally a virtual scene the scene should be rendered from the users' eyes while an augmented scene should be rendered from the camera's position to match the see-through images. More details should be found at the eye offset doc.

| Properties ||
|---|---|
| `GVR_BETA_SEE_THROUGH_SCENE_TYPE_AUGMENTED_SCENE` | Augmented scene type. This represents a scene that is primarily see-through with sparse virtual objects placed on or inside the real environment. This is ignored if the corresponding camera mode is disabled. |
| `GVR_BETA_SEE_THROUGH_SCENE_TYPE_VIRTUAL_SCENE` | Virtual scene type. This represents a scene either composed entirely of virtual objects with no see-through or a scene that is primarily virtual with windows to see the background see-through. |

## Typedefs

### gvr_beta_see_through_config

```
struct gvr_beta_see_through_config_ gvr_beta_see_through_config
```
Configuration settings for see-through.

## Functions

### gvr_beta_controller_get_configuration_type

```
int32_t gvr_beta_controller_get_configuration_type(
  const gvr_controller_context *controller_context,
  const gvr_controller_state *state
)
```
Returns the configuration of the given controller.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `controller_context` | Controller API context. | | `state` | The controller to query. | |
| **Returns** | the current controller configuration of type [gvr_beta_controller_configuration_type](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga2569b0020ba7b3aaa04c3083ec0a10ee). |

### gvr_beta_controller_state_get_tracking_status

```
int32_t gvr_beta_controller_state_get_tracking_status(
  const gvr_controller_state *state
)
```
Returns the tracking status of the controller.

The status is an OR'd combination of GVR_BETA_CONTROLLER_TRACKING_STATUS_FLAG_\* flags.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `state` | The controller state to get the tracking status from. | |
| **Returns** | The set of flags representing the current the tracking status. |

### gvr_beta_see_through_config_create

```
gvr_beta_see_through_config * gvr_beta_see_through_config_create(
  gvr_context *gvr
)
```
Creates a [gvr_beta_see_through_config](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga7f5033e9e06cd01dd914bb88d9324d34) instance.

It can then be set as the active config through [gvr_beta_set_see_through_config()](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1gae09f837120bddcbfbf3164b4ae621e4b).

### gvr_beta_see_through_config_destroy

```
void gvr_beta_see_through_config_destroy(
  gvr_beta_see_through_config **config
)
```
Destroys a [gvr_beta_see_through_config](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga7f5033e9e06cd01dd914bb88d9324d34) instance created by [gvr_beta_see_through_config_create()](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga1c22130f09553bc701e3a171a8aa1146).

### gvr_beta_see_through_config_set_camera_mode

```
void gvr_beta_see_through_config_set_camera_mode(
  gvr_beta_see_through_config *config,
  int32_t camera_mode
)
```
Sets the camera mode for the given see-through config which determines the see-through's appearance.

camera_mode should be a [gvr_beta_see_through_camera_mode](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga25d1ed59fa8607347aadf31314c24178). This will control whether see-through is shown on screen and how it will be colored.

### gvr_beta_see_through_config_set_scene_type

```
void gvr_beta_see_through_config_set_scene_type(
  gvr_beta_see_through_config *config,
  int32_t scene_type
)
```
Sets the scene type on the given see-through config.

scene_type should be a [gvr_beta_see_through_scene_type](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga418e768dffcbf0d5a9b180b534f9e851). This changes the behavior of [gvr_get_eye_from_head_matrix()](https://developers.google.com/vr/reference/android-ndk/group/h-m-d#group___h_m_d_1gaddf0ec0d10c90427b87257d0f1344348) and [gvr_get_head_space_from_start_space_transform()](https://developers.google.com/vr/reference/android-ndk/group/headtracking#group___headtracking_1ga012a104b2dd330ce4722fd9b023516cc) based on the scene type.

### gvr_beta_set_see_through_config

```
void gvr_beta_set_see_through_config(
  gvr_context *context,
  const gvr_beta_see_through_config *config
)
```
The main function for enabling/disabling and configuring see-through.

This function should only be called from the same thread as gvr_frame_submit.

This will both:

1. Set the camera see-through appearance. If this appearance is anything other than GVR_BETA_SEE_THROUGH_CAMERA_MODE_DISABLED then a buffer viewport will be added for each eye whenever a frame is submitted. This will cause the camera frames to be drawn as a background layer, with the rendering style determined by the camera mode. Alpha blending will work as normal, so if the app's bottom layer has alpha 1 then the camera frame will be occluded but if the alpha is 0 the camera frame will show through.
2. If the scene type is GVR_BETA_SEE_THROUGH_SCENE_TYPE_AUGMENTED_SCENE, it will change the behavior of gvr_get_head_space_from_start_space_transform to offset the input timestamp and gvr_get_eye_from_head_matrix to include the camera offset.

<br />

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `config` | The [gvr_beta_see_through_config](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga7f5033e9e06cd01dd914bb88d9324d34) struct contains the [gvr_beta_see_through_camera_mode](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga25d1ed59fa8607347aadf31314c24178) enum value and the [gvr_beta_see_through_scene_type](https://developers.google.com/vr/reference/android-ndk/group/beta#group___beta_1ga418e768dffcbf0d5a9b180b534f9e851) enum value. | |