Controller API

This is the Controller C API, which allows access to a VR controller.

Summary

If you are writing C++ code, you might prefer to use the C++ wrapper rather than implement this C API directly.

Typical initialization example:

// Get your gvr_context* pointer from GvrLayout:
gvr_context* gvr = ......;  // (get from GvrLayout in Java)

// Set up the API features:
int32_t options = gvr_controller_get_default_options();

// Enable non-default options, if needed:
options |= GVR_CONTROLLER_ENABLE_GYRO | GVR_CONTROLLER_ENABLE_ACCEL;

// Create and init:
gvr_controller_context* context =
    gvr_controller_create_and_init(options, gvr);

// Check if init was successful.
if (!context) {
  // Handle error.
  return;
}

gvr_controller_state* state = gvr_controller_state_create();

// Resume:
gvr_controller_resume(context);

Usage:

void DrawFrame() {
  gvr_controller_state_update(context, 0, state);
  // ... process controller state ...
}

// When your application gets paused:
void OnPause() {
  gvr_controller_pause(context);
}

// When your application gets resumed:
void OnResume() {
  gvr_controller_resume(context);
}

To conserve battery, be sure to call gvr_controller_pause and gvr_controller_resume when your app gets paused and resumed, respectively.

THREADING: unless otherwise noted, all functions are thread-safe, so you can operate on the same gvr_controller_context object from multiple threads.

Typedefs

gvr_controller_context typedef
struct gvr_controller_context_
Represents a Daydream Controller API object, used to invoke the Daydream Controller API.

Functions

gvr_controller_api_status_to_string(int32_t status)
const char *
Convenience to convert an API status code to string.
gvr_controller_apply_arm_model(gvr_controller_context *api, int32_t controller_index, int32_t handedness, int32_t behavior, gvr_mat4f head_space_from_start_space_rotation)
void
Sets up arm model with user's handedness, gaze behavior and head rotation.
gvr_controller_battery_level_to_string(int32_t level)
const char *
Convenience to convert a battery level to string.
gvr_controller_button_to_string(int32_t button)
const char *
Convenience to convert an connection state to string.
gvr_controller_connection_state_to_string(int32_t state)
const char *
Convenience to convert an connection state to string.
gvr_controller_create_and_init(int32_t options, gvr_context *context)
Creates and initializes a gvr_controller_context instance which can be used to invoke the Daydream Controller API functions.
gvr_controller_create_and_init_android(JNIEnv *env, jobject android_context, jobject class_loader, int32_t options, gvr_context *context)
Creates and initializes a gvr_controller_context instance with an explicit Android context and class loader.
gvr_controller_destroy(gvr_controller_context **api)
void
Destroys a gvr_controller_context that was previously created with gvr_controller_init.
gvr_controller_get_count(gvr_controller_context *api)
int32_t
Returns the number (N) of controllers currently available.
gvr_controller_get_default_options()
int32_t
Returns the default features for the controller API.
gvr_controller_pause(gvr_controller_context *api)
void
Pauses the controller, possibly releasing resources.
gvr_controller_resume(gvr_controller_context *api)
void
Resumes the controller.
gvr_controller_state_create()
gvr_controller_state *
Creates a gvr_controller_state.
gvr_controller_state_destroy(gvr_controller_state **state)
void
Destroys and sets to NULL a gvr_controller_state that was previously created with gvr_controller_state_create.
gvr_controller_state_get_accel(const gvr_controller_state *state)
Current (latest) controller accelerometer reading, in Start Space.
gvr_controller_state_get_api_status(const gvr_controller_state *state)
int32_t
Gets the API status of the controller state.
gvr_controller_state_get_battery_charging(const gvr_controller_state *state)
bool
Returns whether the controller battery is currently charging.
gvr_controller_state_get_battery_level(const gvr_controller_state *state)
int32_t
Returns the bucketed controller battery level at the last update.
gvr_controller_state_get_button_down(const gvr_controller_state *state, int32_t button)
bool
Returns whether the given button was just pressed (transient).
gvr_controller_state_get_button_state(const gvr_controller_state *state, int32_t button)
bool
Returns whether the given button is currently pressed.
gvr_controller_state_get_button_up(const gvr_controller_state *state, int32_t button)
bool
Returns whether the given button was just released (transient).
gvr_controller_state_get_connection_state(const gvr_controller_state *state)
int32_t
Gets the connection state of the controller.
gvr_controller_state_get_gyro(const gvr_controller_state *state)
Returns the current controller gyro reading, in Start Space.
gvr_controller_state_get_last_accel_timestamp(const gvr_controller_state *state)
int64_t
Returns the timestamp (nanos) when the last accelerometer event was received.
gvr_controller_state_get_last_battery_timestamp(const gvr_controller_state *state)
int64_t
Returns the timestamp (nanos) when the last battery event was received.
gvr_controller_state_get_last_button_timestamp(const gvr_controller_state *state)
int64_t
Returns the timestamp (nanos) when the last button event was received.
gvr_controller_state_get_last_gyro_timestamp(const gvr_controller_state *state)
int64_t
Returns the timestamp (nanos) when the last gyro event was received.
gvr_controller_state_get_last_orientation_timestamp(const gvr_controller_state *state)
int64_t
Returns the timestamp (nanos) when the last orientation event was received.
gvr_controller_state_get_last_position_timestamp(const gvr_controller_state *state)
int64_t
Returns the timestamp (nanos) when the last position event was received.
gvr_controller_state_get_last_touch_timestamp(const gvr_controller_state *state)
int64_t
Returns the timestamp (nanos) when the last touch event was received.
gvr_controller_state_get_orientation(const gvr_controller_state *state)
Returns the current controller orientation, in Start Space.
gvr_controller_state_get_position(const gvr_controller_state *state)
Current (latest) controller position.
gvr_controller_state_get_recentered(const gvr_controller_state *state)
bool
Returns true if a recenter operation just ended.
gvr_controller_state_get_recentering(const gvr_controller_state *state)
bool
Deprecated. Use gvr_controller_state_get_recentered instead.
gvr_controller_state_get_touch_down(const gvr_controller_state *state)
bool
Returns true iff user just started touching touchpad.
gvr_controller_state_get_touch_pos(const gvr_controller_state *state)
Returns the normalized coordinates on the touchpad.
gvr_controller_state_get_touch_up(const gvr_controller_state *state)
bool
Returns true if user just stopped touching touchpad.
gvr_controller_state_is_touching(const gvr_controller_state *state)
bool
Returns whether the user is touching the touchpad.
gvr_controller_state_update(gvr_controller_context *api, int32_t controller_index, gvr_controller_state *out_state)
void
Updates the controller state.

Typedefs

gvr_controller_context

struct gvr_controller_context_ gvr_controller_context

Represents a Daydream Controller API object, used to invoke the Daydream Controller API.

Functions

gvr_controller_api_status_to_string

const char * gvr_controller_api_status_to_string(
  int32_t status
)

Convenience to convert an API status code to string.

The returned pointer is static and valid throughout the lifetime of the application.

Details
Parameters
status
The gvr_controller_api_status to convert to string.
Returns
A pointer to a string that describes the value.

gvr_controller_apply_arm_model

void gvr_controller_apply_arm_model(
  gvr_controller_context *api,
  int32_t controller_index,
  int32_t handedness,
  int32_t behavior,
  gvr_mat4f head_space_from_start_space_rotation
)

Sets up arm model with user's handedness, gaze behavior and head rotation.

This setting needs to be applied for every frame. User preferences of handedness and gaze behavior can be changed as needed in a sequence of frames. This needs to be called before gvr_controller_state_update() to apply arm model. GVR_CONTROLLER_ENABLE_ARM_MODEL flag needs to be enabled to apply arm model. The controller position computed with arm model is relative to the head origin. If using the opt-in neck model, the effective eye position after using vr_apply_neck_model() is shifted forward from the head origin by the neck-to-eye distance (8cm) when the head is in neutral position, and a matching forward offset should be applied to the controller position to compensate.

Note that this method will not generate a simulated position if real position information is available. Clear the GVR_CONTROLLER_ENABLE_POSITION option to discard any real position data and force the arm model on systems with real position data.

When multiple controllers are configured, this arm model will be applied to the controller at the given controller_index, if one exists.

Details
Parameters
api
Pointer to a gvr_controller_context.
controller_index
Index of the controller to apply the arm model to.
handedness
User's preferred handedness (GVR_CONTROLLER_RIGHT_HANDED or GVR_CONTROLLER_LEFT_HANDED). Arm model will assume this is the hand that is holding the controller and position the arm accordingly.
behavior
User's preferred gaze behavior (SYNC_GAZE / FOLLOW_GAZE / IGNORE_GAZE). Arm model uses this to determine how the body rotates as gaze direction (i.e. head rotation) changes.
head_space_from_start_space_rotation
User's head rotation with respect to start space.

gvr_controller_battery_level_to_string

const char * gvr_controller_battery_level_to_string(
  int32_t level
)

Convenience to convert a battery level to string.

The returned pointer is static and valid throughout the lifetime of the application.

Details
Parameters
level
The gvr_controller_battery_level to convert to string.
Returns
A pointer to a string that describes the value.

gvr_controller_button_to_string

const char * gvr_controller_button_to_string(
  int32_t button
)

Convenience to convert an connection state to string.

The returned pointer is static and valid throughout the lifetime of the application.

Details
Parameters
button
The gvr_controller_button to convert to string.
Returns
A pointer to a string that describes the value.

gvr_controller_connection_state_to_string

const char * gvr_controller_connection_state_to_string(
  int32_t state
)

Convenience to convert an connection state to string.

The returned pointer is static and valid throughout the lifetime of the application.

Details
Parameters
state
The state to convert to string.
Returns
A pointer to a string that describes the value.

gvr_controller_create_and_init

gvr_controller_context * gvr_controller_create_and_init(
  int32_t options,
  gvr_context *context
)

Creates and initializes a gvr_controller_context instance which can be used to invoke the Daydream Controller API functions.

Important: after creation the API will be in the paused state (the controller will be inactive). You must call gvr_controller_resume() explicitly (typically, in your Android app's onResume() callback).

Details
Parameters
options
The API options. To get the defaults, use gvr_controller_get_default_options().
context
The GVR Context object to sync with (optional). This can be nullptr. If provided, the context's state will be synchronized with the controller's state where possible. For example, when the user recenters the controller, this will automatically recenter head tracking as well. WARNING: the caller is responsible for making sure the pointer remains valid for the lifetime of this object.
Returns
A pointer to the initialized API, or NULL if an error occurs.

gvr_controller_create_and_init_android

gvr_controller_context * gvr_controller_create_and_init_android(
  JNIEnv *env,
  jobject android_context,
  jobject class_loader,
  int32_t options,
  gvr_context *context
)

Creates and initializes a gvr_controller_context instance with an explicit Android context and class loader.

Details
Parameters
env
The JNI Env associated with the current thread.
android_context
The Android application context. This must be the application context, NOT an Activity context (Note: from any Android Activity in your app, you can call getApplicationContext() to retrieve the application context).
class_loader
The class loader to use when loading Java classes. This must be your app's main class loader (usually accessible through activity.getClassLoader() on any of your Activities).
options
The API options. To get the defaults, use gvr_controller_get_default_options().
context
The GVR Context object to sync with (optional). This can be nullptr. If provided, the context's state will be synchronized with the controller's state where possible. For example, when the user recenters the controller, this will automatically recenter head tracking as well. WARNING: the caller is responsible for making sure the pointer remains valid for the lifetime of this object.
Returns
A pointer to the initialized API, or NULL if an error occurs.

gvr_controller_destroy

void gvr_controller_destroy(
  gvr_controller_context **api
)

Destroys a gvr_controller_context that was previously created with gvr_controller_init.

Details
Parameters
api
Pointer to a pointer to a gvr_controller_context. The pointer will be set to NULL after destruction.

gvr_controller_get_count

int32_t gvr_controller_get_count(
  gvr_controller_context *api
)

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 gvr_controller_state_update to set a gvr_controller_state instance to the state of the controller for that index.

Details
Parameters
api
Pointer to a gvr_controller_context.
Returns
The number of controllers currently available.

gvr_controller_get_default_options

int32_t gvr_controller_get_default_options()

Returns the default features for the controller API.

Details
Returns
The set of default features, as bit flags (an OR'ed combination of the GVR_CONTROLLER_ENABLE_* feature flags).

gvr_controller_pause

void gvr_controller_pause(
  gvr_controller_context *api
)

Pauses the controller, possibly releasing resources.

Call this when your app/game loses focus. Calling this when already paused is a no-op. Thread-safe (call from any thread).

Details
Parameters
api
Pointer to a gvr_controller_context.

gvr_controller_resume

void gvr_controller_resume(
  gvr_controller_context *api
)

Resumes the controller.

Call this when your app/game regains focus. Calling this when already resumed is a no-op. Thread-safe (call from any thread).

Details
Parameters
api
Pointer to a gvr_controller_context.

gvr_controller_state_create

gvr_controller_state * gvr_controller_state_create()

Creates a gvr_controller_state.

Details
Returns
A gvr_controller_state instance that will receive state updates for a controller.

gvr_controller_state_destroy

void gvr_controller_state_destroy(
  gvr_controller_state **state
)

Destroys and sets to NULL a gvr_controller_state that was previously created with gvr_controller_state_create.

Details
Parameters
state
Pointer to a pointer to the controller state to be destroyed and nulled.

gvr_controller_state_get_accel

gvr_vec3f gvr_controller_state_get_accel(
  const gvr_controller_state *state
)

Current (latest) controller accelerometer reading, in Start Space.

The accelerometer indicates the direction in which the controller feels an acceleration, including gravity. The reading is given in meters per second squared (m/s^2). The axes are the same as for the gyro. To have an intuition for the signs used in the accelerometer, it is useful to imagine that, when at rest, the controller is being "pushed" by a force opposite to gravity. It is as if, by the equivalency princle, it were on a frame of reference that is accelerating in the opposite direction to gravity. For example:

  • If the controller is lying flat on a table top, it will read a positive acceleration of about 9.8 m/s^2 along the Y axis, corresponding to the acceleration of gravity (as if the table were pushing the controller upwards at 9.8 m/s^2 to counteract gravity).
  • If, in that situation, the controller is now accelerated upwards at 3.0 m/s^2, then the reading will be 12.8 m/s^2 along the Y axis, since the controller will now feel a stronger acceleration corresponding to the 9.8 m/s^2 plus the upwards push of 3.0 m/s^2.
  • If, the controller is accelerated downwards at 5.0 m/s^2, then the reading will now be 4.8 m/s^2 along the Y axis, since the controller will now feel a weaker acceleration (as the acceleration is giving in to gravity).
  • If you were to give in to gravity completely, letting the controller free fall towards the ground, it will read 0 on all axes, as there will be no force acting on the controller. (Please do not put your controller in a free-fall situation. This is just a theoretical example.)

Details
Parameters
state
The controller state to get the accelerometer reading from.
Returns
The accelerometer reading from the controller state.

gvr_controller_state_get_api_status

int32_t gvr_controller_state_get_api_status(
  const gvr_controller_state *state
)

Gets the API status of the controller state.

Returns one of the gvr_controller_api_status variants, but returned as an int32_t for ABI compatibility.

Details
Parameters
state
The controller state to get the status from.
Returns
The status code from the controller state, as a gvr_controller_api_status variant.

gvr_controller_state_get_battery_charging

bool gvr_controller_state_get_battery_charging(
  const gvr_controller_state *state
)

Returns whether the controller battery is currently charging.

This may not be real time information and may be slow to be updated. The last battery update time is available by calling gvr_controller_state_get_battery_timestamp.

Details
Parameters
state
The controller state to get the battery charging state from.
Returns
True iff the battery was charging at the last available update, false otherwise.

gvr_controller_state_get_battery_level

int32_t gvr_controller_state_get_battery_level(
  const gvr_controller_state *state
)

Returns the bucketed controller battery level at the last update.

Note this is a gvr_controller_battery_level and not a percent. The last battery update time is available by calling gvr_controller_state_get_battery_timestamp.

Details
Parameters
state
The controller state to get the battery level from.
Returns
The last known battery level as a gvr_controller_battery_level variant.

gvr_controller_state_get_button_down

bool gvr_controller_state_get_button_down(
  const gvr_controller_state *state,
  int32_t button
)

Returns whether the given button was just pressed (transient).

Details
Parameters
state
The controller state to get the button pressed data from.
Returns
True iff the button specified by the 'state' parameter was just pressed, false otherwise.

gvr_controller_state_get_button_state

bool gvr_controller_state_get_button_state(
  const gvr_controller_state *state,
  int32_t button
)

Returns whether the given button is currently pressed.

Details
Parameters
state
The controller state to get the button state from.
Returns
True iff the button specified by the 'state' parameter is pressed, false otherwise.

gvr_controller_state_get_button_up

bool gvr_controller_state_get_button_up(
  const gvr_controller_state *state,
  int32_t button
)

Returns whether the given button was just released (transient).

Details
Parameters
state
The controller state to get the button released data from.
Returns
True iff the button specified by the 'state' parameter was just released, false otherwise.

gvr_controller_state_get_connection_state

int32_t gvr_controller_state_get_connection_state(
  const gvr_controller_state *state
)

Gets the connection state of the controller.

Returns one of the gvr_controller_connection_state variants, but returned as an int32_t for ABI compatibility.

Details
Parameters
state
The controller state to get the connection state from.
Returns
The connection state from the controller state as a gvr_controller_connection_state variant.

gvr_controller_state_get_gyro

gvr_vec3f gvr_controller_state_get_gyro(
  const gvr_controller_state *state
)

Returns the current controller gyro reading, in Start Space.

The gyro measures the controller's angular speed in radians per second. Note that this is an angular speed, so it reflects how fast the controller's orientation is changing with time. In particular, if the controller is not being rotated, the angular speed will be zero on all axes, regardless of the current pose.

The axes are in the controller's device space. Specifically:

  • The X axis points to the right of the controller.
  • The Y axis points upwards perpendicular to the top surface of the controller.
  • The Z axis points backwards along the body of the controller, towards its rear, where the charging port is.

As usual in a right-handed coordinate system, the sign of the angular velocity is given by the right-hand rule. So, for example:

  • If the controller is flat on a table top spinning counter-clockwise as seen from above, you will read a positive angular velocity about the Y axis. Clockwise would be negative.
  • If the controller is initially pointing forward and lying flat and is then gradually angled up so that its tip points towards the sky, it will report a positive angular velocity about the X axis during that motion. Likewise, angling it down will report a negative angular velocity about the X axis.
  • If the controller is banked (rolled) to the right, this will report a negative angular velocity about the Z axis during the motion (remember the Z axis points backwards along the controller). Banking to the left will report a positive angular velocity about the Z axis.

Details
Parameters
state
The controller state to get the gyro reading from.
Returns
The gyro reading from the controller state.

gvr_controller_state_get_last_accel_timestamp

int64_t gvr_controller_state_get_last_accel_timestamp(
  const gvr_controller_state *state
)

Returns the timestamp (nanos) when the last accelerometer event was received.

Details
Parameters
state
The controller state to get the last accelerometer timestamp from.
Returns
A 64-bit integer representation of the timestamp when the last accelerometer event was recieved.

gvr_controller_state_get_last_battery_timestamp

int64_t gvr_controller_state_get_last_battery_timestamp(
  const gvr_controller_state *state
)

Returns the timestamp (nanos) when the last battery event was received.

Details
Parameters
state
The controller state to get battery event timestamp from.
Returns
A 64-bit integer representation of the timestamp when the last battery event was received.

gvr_controller_state_get_last_button_timestamp

int64_t gvr_controller_state_get_last_button_timestamp(
  const gvr_controller_state *state
)

Returns the timestamp (nanos) when the last button event was received.

Details
Parameters
state
The controller state to get the last button event timestamp from.
Returns
A 64-bit integer representation of the timestamp when the last button event was recieved.

gvr_controller_state_get_last_gyro_timestamp

int64_t gvr_controller_state_get_last_gyro_timestamp(
  const gvr_controller_state *state
)

Returns the timestamp (nanos) when the last gyro event was received.

Details
Parameters
state
The controller state to get the last gyro event timestamp from.
Returns
A 64-bit integer representation of the timestamp when the last gyro event was recieved.

gvr_controller_state_get_last_orientation_timestamp

int64_t gvr_controller_state_get_last_orientation_timestamp(
  const gvr_controller_state *state
)

Returns the timestamp (nanos) when the last orientation event was received.

Details
Parameters
state
The controller state to get the last orientation event timestamp from.
Returns
A 64-bit integer representation of the timestamp when the last orientation event was recieved.

gvr_controller_state_get_last_position_timestamp

int64_t gvr_controller_state_get_last_position_timestamp(
  const gvr_controller_state *state
)

Returns the timestamp (nanos) when the last position event was received.

Details
Parameters
state
The controller state to get the last position event timestamp from.
Returns
A 64-bit integer representation of the timestamp when the last position event was recieved.

gvr_controller_state_get_last_touch_timestamp

int64_t gvr_controller_state_get_last_touch_timestamp(
  const gvr_controller_state *state
)

Returns the timestamp (nanos) when the last touch event was received.

Details
Parameters
state
The controller state to get the last touch timestamp from.
Returns
A 64-bit integer representation of the timestamp when the last touch event was recieved.

gvr_controller_state_get_orientation

gvr_quatf gvr_controller_state_get_orientation(
  const gvr_controller_state *state
)

Returns the current controller orientation, in Start Space.

The Start Space is the same space as the headset space and has these three axes (right-handed):

  • The positive X axis points to the right.
  • The positive Y axis points upwards.
  • The positive Z axis points backwards.

The definition of "backwards" and "to the right" are based on the position of the controller when tracking started. For Daydream, this is when the controller was first connected in the "Connect your Controller" screen which is shown when the user enters VR.

The definition of "upwards" is given by gravity (away from the pull of gravity). This API may not work in environments without gravity, such as space stations or near the center of the Earth.

Since the coordinate system is right-handed, rotations are given by the right-hand rule. For example, rotating the controller counter-clockwise on a table top as seen from above means a positive rotation about the Y axis, while clockwise would mean negative.

Note that this is the Start Space for the controller, which initially coincides with the Start Space for the headset, but they may diverge over time due to controller/headset drift. A recentering operation will bring the two spaces back into sync.

Remember that a unit quaternion expresses a rotation. Given a rotation of theta radians about the (x, y, z) axis, the corresponding quaternion (in xyzw order) is:

(x * sin(theta/2), y * sin(theta/2), z * sin(theta/2), cos(theta/2))

Here are some examples of orientations of the controller and their corresponding quaternions, all given in xyzw order:

  • Initial pose, pointing forward and lying flat on a surface: identity quaternion (0, 0, 0, 1). Corresponds to "no rotation".
  • Flat on table, rotated 90 degrees counter-clockwise: (0, 0.7071, 0, 0.7071). Corresponds to a +90 degree rotation about the Y axis.
  • Flat on table, rotated 90 degrees clockwise: (0, -0.7071, 0, 0.7071). Corresponds to a -90 degree rotation about the Y axis.
  • Flat on table, rotated 180 degrees (pointing backwards): (0, 1, 0, 0). Corresponds to a 180 degree rotation about the Y axis.
  • Pointing straight up towards the sky: (0.7071, 0, 0, 0.7071). Corresponds to a +90 degree rotation about the X axis.
  • Pointing straight down towards the ground: (-0.7071, 0, 0, 0.7071). Corresponds to a -90 degree rotation about the X axis.
  • Banked 90 degrees to the left: (0, 0, 0.7071, 0.7071). Corresponds to a +90 degree rotation about the Z axis.
  • Banked 90 degrees to the right: (0, 0, -0.7071, 0.7071). Corresponds to a -90 degree rotation about the Z axis.

Details
Parameters
state
The controller state to get the orientation from.
Returns
The unit quaternion orientation from the controller state.

gvr_controller_state_get_position

gvr_vec3f gvr_controller_state_get_position(
  const gvr_controller_state *state
)

Current (latest) controller position.

This may be real position data from the controller if GVR_CONTROLLER_ENABLE_POSITION is used and real data is available, or it may be simulated data if GVR_CONTROLLER_ENABLE_ARM_MODEL and gvr_controller_apply_arm_model() are used. For more information, see gvr_controller_apply_arm_model().

Details
Parameters
state
The controller state to get the latest simulated position from.
Returns
The current controller simulated position (intended for use with an elbow model).

gvr_controller_state_get_recentered

bool gvr_controller_state_get_recentered(
  const gvr_controller_state *state
)

Returns true if a recenter operation just ended.

This is a transient event: (i.e., it is true only for one frame after the recenter ended). If this is true then the orientation field is already relative to the new center.

Details
Parameters
state
The controller state to get the recenter information from.
Returns
True iff a recenter operation just ended, false otherwise.

gvr_controller_state_get_recentering

bool gvr_controller_state_get_recentering(
  const gvr_controller_state *state
)

Deprecated. Use gvr_controller_state_get_recentered instead.

Returns whether the recenter flow is currently in progress.

Details
Parameters
state
The controller state to get the recenter information from.
Returns
True iff recenter flow is in progress, false otherwise.

gvr_controller_state_get_touch_down

bool gvr_controller_state_get_touch_down(
  const gvr_controller_state *state
)

Returns true iff user just started touching touchpad.

This is a transient event (i.e., it is true for only one frame after the event).

Details
Parameters
state
The controller state to get the touch down data from.
Returns
True iff the user just started touching the touchpad, false otherwise.

gvr_controller_state_get_touch_pos

gvr_vec2f gvr_controller_state_get_touch_pos(
  const gvr_controller_state *state
)

Returns the normalized coordinates on the touchpad.

Each value ranges from [0, 1]. The x value of the touch point aligns with the controller's x-axis, which points to the right of the controller, and the y value aligns with the controller's z-axis. See https://developers.google.com/vr/reference/gvr-ndk-controller#controller_space for more information. This is initially (0, 0) until an event is received. If the user is not touching the touchpad, then this is the position of the last touch. On circular touchpad hardware, the valid touch area will be a 0.5 radius circle centered around (0.5, 0.5).

Details
Parameters
state
The controller state to get the touchpad touch position from.
Returns
The touchpad touch position in normalized coordinates iff the user is touching the toucpad. The last touched coordinate otherwise.

gvr_controller_state_get_touch_up

bool gvr_controller_state_get_touch_up(
  const gvr_controller_state *state
)

Returns true if user just stopped touching touchpad.

This is a transient event: (i.e., it is true for only one frame after the event).

Details
Parameters
state
The controller state to get the touch up data from.
Returns
True iff the user just released the touchpad, false otherwise.

gvr_controller_state_is_touching

bool gvr_controller_state_is_touching(
  const gvr_controller_state *state
)

Returns whether the user is touching the touchpad.

Details
Parameters
state
The controller state to get the touchpad being touched state from.
Returns
True iff the user is touching the controller, false otherwise.

gvr_controller_state_update

void gvr_controller_state_update(
  gvr_controller_context *api,
  int32_t controller_index,
  gvr_controller_state *out_state
)

Updates the controller state.

Reading the controller state is not a const getter: it has side-effects. In particular, some of the gvr_controller_state fields (the ones documented as "transient") represent one-time events and will be true for only one read operation, and false in subsequent reads.

If the controller_index passed here does not correspond to an available controller (i.e. the controller_index is not in the range [0,N) where N is the number of controllers returned by gvr_controller_get_count), then the values of fields set for the gvr_controller_state instance passed in here are undefined.

The index of each controller device will remain constant the same across controller disconnects/connects during a given VR session. If the underlying set of controllers expected to be available to applications has changed, the gvr_controller_context may no longer be valid, and must be recreated by the applicaion when notified of this.

Details
Parameters
api
Pointer to a gvr_controller_context.
controller_index
The index of the controller to update the state from.
out_state
A pointer where the controller's state is to be written. This must have been allocated with gvr_controller_state_create().