This site has been permanently archived. The content on this site was last updated in 2019.

All developers actively developing experiences for Google Cardboard should use the open source Cardboard SDKs for iOS, Android NDK, and Unity XR Plugin.
The Daydream View VR headset is no longer available for purchase as of October 15, 2019. As of November 2023, previously supported devices will no longer be able to download and install Google VR Serivces (Android application ID com.google.vr.vrcore) for new users.

Google VR Base C API

This is the Google VR C API.

Summary

It supports clients writing VR experiences for head mounted displays that consist of a mobile phone and a VR viewer.

Example API usage:

#ifdef __ANDROID__
// On Android, the gvr_context should almost always be obtained from
// the Java GvrLayout object via
// GvrLayout.getGvrApi().getNativeGvrContext().
gvr_context* gvr = ...;
#else
gvr_context* gvr = gvr_create();
#endif

gvr_initialize_gl(gvr);

gvr_buffer_viewport_list* viewport_list =
    gvr_buffer_viewport_list_create(gvr);
gvr_get_recommended_buffer_viewports(gvr, viewport_list);
gvr_buffer_viewport* left_eye_vp = gvr_buffer_viewport_create(gvr);
gvr_buffer_viewport* right_eye_vp = gvr_buffer_viewport_create(gvr);
gvr_buffer_viewport_list_get_item(viewport_list, 0, left_eye_vp);
gvr_buffer_viewport_list_get_item(viewport_list, 1, right_eye_vp);

while (client_app_should_render) {
  // A client app should be ready for the render target size to change
  // whenever a new QR code is scanned, or a new viewer is paired.
  gvr_sizei render_target_size =
      gvr_get_maximum_effective_render_target_size(gvr);
  // The maximum effective render target size can be very large, most
  // applications need to scale down to compensate.
  render_target_size.width /= 2;
  render_target_size.height /= 2;
  gvr_swap_chain_resize_buffer(swap_chain, 0, render_target_size);

  // This function will depend on your render loop's implementation.
  gvr_clock_time_point next_vsync = AppGetNextVsyncTime();

  const gvr_mat4f head_view =
      gvr_get_head_space_from_start_space_transform(gvr, next_vsync);
  const gvr_mat4f left_eye_view = MatrixMultiply(
      gvr_get_eye_from_head_matrix(gvr, GVR_LEFT_EYE), head_view);
  const gvr::Mat4f right_eye_view = MatrixMultiply(
      gvr_get_eye_from_head_matrix(gvr, GVR_RIGHT_EYE), head_view);

  // Insert client rendering code here.

  AppSetRenderTarget(offscreen_texture_id);

  AppDoSomeRenderingForEye(
      gvr_buffer_viewport_get_source_uv(left_eye_view),
      left_eye_matrix);
  AppDoSomeRenderingForEye(
      gvr_buffer_viewport_get_source_uv(right_eye_view),
      right_eye_matrix);
  AppSetRenderTarget(primary_display);

  gvr_frame_submit(&frame, viewport_list, head_view);
}

// Cleanup memory.
gvr_buffer_viewport_list_destroy(&viewport_list);
gvr_buffer_viewport_destroy(&left_eye_vp);
gvr_buffer_viewport_destroy(&right_eye_vp);

#ifdef __ANDROID__
// On Android, The Java GvrLayout owns the gvr_context.
#else
gvr_destroy(gvr);
#endif

Head tracking is enabled by default, and will begin as soon as the gvr_context is created. The client should call gvr_pause_tracking() and gvr_resume_tracking() when the app is paused and resumed, respectively.

Note: Unless otherwise noted, the functions in this API may not be thread-safe with respect to the gvr_context, and it is up the caller to use the API in a thread-safe manner.

Functions
`gvr_clear_error(gvr_context *gvr)`	`int32_t` Clears the current GVR error code, and returns the error code that was cleared.
`gvr_create()`	`gvr_context *` Creates a new gvr instance.
`gvr_destroy(gvr_context **gvr)`	`void` Destroys a gvr_context instance.
`gvr_distort_to_screen(gvr_context gvr, int32_t texture_id, const gvr_buffer_viewport_list viewport_list, gvr_mat4f head_space_from_start_space, gvr_clock_time_point target_presentation_time)`	`void` Deprecated. Use the Swap Chain API instead. This function exists only to support legacy rendering pathways for Cardboard devices. It is incompatible with the low-latency experiences supported by async reprojection.
`gvr_get_async_reprojection_enabled(const gvr_context *gvr)`	`bool` Gets whether asynchronous reprojection is currently enabled.
`gvr_get_current_properties(gvr_context *gvr)`	`const gvr_properties *` Gets a read-only handle to the current global set of GVR-related properties.
`gvr_get_error(gvr_context *gvr)`	`int32_t` Gets the current GVR error code, or GVR_ERROR_NONE if there is no error.
`gvr_get_error_string(int32_t error_code)`	`const char *` Gets a human-readable string representing the given error code.
`gvr_get_maximum_effective_render_target_size(const gvr_context *gvr)`	`gvr_sizei` Returns the maximum effective size for the client's render target, given the parameters of the head mounted device selected.
`gvr_get_recommended_buffer_viewports(const gvr_context gvr, gvr_buffer_viewport_list viewport_list)`	`void` Gets the recommended buffer viewport configuration, populating a previously allocated gvr_buffer_viewport_list object.
`gvr_get_screen_buffer_viewports(const gvr_context gvr, gvr_buffer_viewport_list viewport_list)`	`void` Gets the screen (non-distorted) buffer viewport configuration, populating a previously allocated gvr_buffer_viewport_list object.
`gvr_get_screen_target_size(const gvr_context *gvr)`	`gvr_sizei` Returns a non-distorted size for the screen, given the parameters of the phone and/or the head mounted device selected.
`gvr_get_user_prefs(gvr_context *gvr)`	`const gvr_user_prefs *` Returns an opaque struct containing information about user preferences.
`gvr_get_version()`	`gvr_version` Gets the current GVR runtime version.
`gvr_get_version_string()`	`const char *` Gets a string representation of the current GVR runtime version.
`gvr_initialize_gl(gvr_context *gvr)`	`void` Initializes necessary GL-related objects and uses the current thread and GL context for rendering.
`gvr_is_feature_supported(const gvr_context *gvr, int32_t feature)`	`bool` Queries whether a particular GVR feature is supported by the underlying platform.
`gvr_poll_event(gvr_context gvr, gvr_event event_out)`	`int32_t` Polls the event queue, populating the provided event if available while also popping it from the event queue.
`gvr_properties_get(const gvr_properties properties, int32_t property_key, gvr_value value_out)`	`int32_t` Queries the given property's value, populating the provided value if available.
`gvr_set_surface_size(gvr_context *gvr, gvr_sizei surface_size_pixels)`	`void`
`gvr_user_prefs_get_controller_handedness(const gvr_user_prefs *user_prefs)`	`int32_t` Returns the controller handedness of the given gvr_user_prefs struct.

Functions

gvr_clear_error

int32_t gvr_clear_error(
  gvr_context *gvr
)

Clears the current GVR error code, and returns the error code that was cleared.

Details

Parameters

gvr

Pointer to the gvr instance.

Returns

The gvr_error code that was cleared by this function, or GVR_ERROR_NONE if no error has occurred.

gvr_create

gvr_context * gvr_create()

Creates a new gvr instance.

The instance must remain valid as long as any GVR object is in use. When the application no longer needs to use the GVR SDK, call gvr_destroy().

On Android, the gvr_context should almost always be obtained from the Java GvrLayout object, rather than explicitly created here. The GvrLayout should live in the app's View hierarchy, and its use is required to ensure consistent behavior across all varieties of GVR-compatible viewers. See the Java GvrLayout and GvrApi documentation for more details.

Details
Returns	Pointer to the created gvr instance, NULL on failure.

gvr_destroy

void gvr_destroy(
  gvr_context **gvr
)

Destroys a gvr_context instance.

The parameter will be nulled by this operation. Once this function is called, the behavior of any subsequent call to a GVR SDK function that references objects created from this context is undefined.

Details

Parameters

gvr

Pointer to a pointer to the gvr instance to be destroyed and nulled.

gvr_distort_to_screen

void gvr_distort_to_screen(
  gvr_context *gvr,
  int32_t texture_id,
  const gvr_buffer_viewport_list *viewport_list,
  gvr_mat4f head_space_from_start_space,
  gvr_clock_time_point target_presentation_time
)

Deprecated. Use the Swap Chain API instead. This function exists only to support legacy rendering pathways for Cardboard devices. It is incompatible with the low-latency experiences supported by async reprojection.

Performs postprocessing, including lens distortion, on the contents of the passed texture and shows the result on the screen. Lens distortion is determined by the parameters of the viewer encoded in its QR code. The passed texture is not modified.

If the application does not call gvr_initialize_gl() before calling this function, the results are undefined.

Details

Parameters

`gvr`	Pointer to the gvr instance which will do the distortion.
`texture_id`	The OpenGL ID of the texture that contains the next frame to be displayed.
`viewport_list`	Rendering parameters.
`head_space_from_start_space`	This parameter is ignored.
`target_presentation_time`	This parameter is ignored.

gvr_get_async_reprojection_enabled

bool gvr_get_async_reprojection_enabled(
  const gvr_context *gvr
)

Gets whether asynchronous reprojection is currently enabled.

If enabled, frames will be collected by the rendering system and asynchronously re-projected in sync with the scanout of the display. This feature may not be available on every platform, and requires a high-priority render thread with special extensions to function properly.

Note: On Android, this feature can be enabled solely via the GvrLayout Java instance which (indirectly) owns this gvr_context. The corresponding method call is GvrLayout.setAsyncReprojectionEnabled().

Note: Because of the above requirements, asynchronous reprojection is only currently available on Daydream-ready Android devices. This function will always return false on other devices.

Details

Parameters

gvr

Pointer to the gvr instance.

Returns

Whether async reprojection is enabled. Defaults to false.

gvr_get_current_properties

const gvr_properties * gvr_get_current_properties(
  gvr_context *gvr
)

Gets a read-only handle to the current global set of GVR-related properties.

Details

Parameters

gvr_context

The current context.

Returns

gvr_properties An opaque handle to the current, global properties instance. Note that this handle is valid only as long as the provided context is valid, and must not be used after the context is destroyed.

gvr_get_error

int32_t gvr_get_error(
  gvr_context *gvr
)

Gets the current GVR error code, or GVR_ERROR_NONE if there is no error.

This function doesn't clear the error code; see gvr_clear_error().

Details

Parameters

gvr

Pointer to the gvr instance.

Returns

The current gvr_error code, or GVR_ERROR_NONE if no error has occurred.

gvr_get_error_string

const char * gvr_get_error_string(
  int32_t error_code
)

Gets a human-readable string representing the given error code.

Details

Parameters

error_code

The gvr_error code.

Returns

A human-readable string representing the error code.

gvr_get_maximum_effective_render_target_size

gvr_sizei gvr_get_maximum_effective_render_target_size(
  const gvr_context *gvr
)

Returns the maximum effective size for the client's render target, given the parameters of the head mounted device selected.

At this resolution, we have a 1:1 ratio between source pixels and screen pixels in the most magnified region of the screen. Applications should rarely, if ever, need to render to a larger target, as it will simply result in sampling artifacts.

Note that this is probably too large for most applications to use as a render target size. Applications should scale this value to be appropriate to their graphical load.

Details

Parameters

gvr

Pointer to the gvr instance from which to get the size.

Returns

Maximum effective size for the target render target.

gvr_get_recommended_buffer_viewports

void gvr_get_recommended_buffer_viewports(
  const gvr_context *gvr,
  gvr_buffer_viewport_list *viewport_list
)

Gets the recommended buffer viewport configuration, populating a previously allocated gvr_buffer_viewport_list object.

The updated values include the per-eye recommended viewport and field of view for the target.

When the recommended viewports are used for distortion rendering, this method should always be called after calling refresh_viewer_profile(). That will ensure that the populated viewports reflect the currently paired viewer.

This function assumes that the client is not using multiview to render to multiple layers simultaneously.

Details

Parameters

`gvr`	Pointer to the gvr instance from which to get the viewports.
`viewport_list`	Pointer to a previously allocated viewport list. This will be populated with the recommended buffer viewports and resized if necessary.

gvr_get_screen_buffer_viewports

void gvr_get_screen_buffer_viewports(
  const gvr_context *gvr,
  gvr_buffer_viewport_list *viewport_list
)

Gets the screen (non-distorted) buffer viewport configuration, populating a previously allocated gvr_buffer_viewport_list object.

The updated values include the per-eye recommended viewport and field of view for the target.

Details

Parameters

`gvr`	Pointer to the gvr instance from which to get the viewports.
`viewport_list`	Pointer to a previously allocated viewport list. This will be populated with the screen buffer viewports and resized if necessary.

gvr_get_screen_target_size

gvr_sizei gvr_get_screen_target_size(
  const gvr_context *gvr
)

Returns a non-distorted size for the screen, given the parameters of the phone and/or the head mounted device selected.

Details

Parameters

gvr

Pointer to the gvr instance from which to get the size.

Returns

Screen (non-distorted) size for the render target.

gvr_get_user_prefs

const gvr_user_prefs * gvr_get_user_prefs(
  gvr_context *gvr
)

Returns an opaque struct containing information about user preferences.

The returned struct will remain valid as long as the context is valid. The returned struct may be updated when the user changes their preferences, so this function only needs to be called once, and calling it multiple times will return the same object each time.

Details

Parameters

gvr

Pointer to the gvr instance.

Returns

An opaque struct containing information about user preferences.

gvr_get_version

gvr_version gvr_get_version()

Gets the current GVR runtime version.

Note: This runtime version may differ from the version against which the client app is compiled, as defined by the semantic version components in gvr_version.h.

Details
Returns	The version as a gvr_version.

gvr_get_version_string

const char * gvr_get_version_string()

Gets a string representation of the current GVR runtime version.

This is of the form "MAJOR.MINOR.PATCH".

Note: This runtime version may differ from the version against which the client app is compiled, as defined in gvr_version.h by GVR_SDK_VERSION_STRING.

Details
Returns	The version as a static char pointer.

gvr_initialize_gl

void gvr_initialize_gl(
  gvr_context *gvr
)

Initializes necessary GL-related objects and uses the current thread and GL context for rendering.

Please make sure that a valid GL context is available when this function is called.

Details

Parameters

gvr

Pointer to the gvr instance to be initialized.

gvr_is_feature_supported

bool gvr_is_feature_supported(
  const gvr_context *gvr,
  int32_t feature
)

Queries whether a particular GVR feature is supported by the underlying platform.

This should be called after gvr_initialize_gl().

Details

Parameters

`gvr`	The context to query against.
`feature`	The gvr_feature type being queried.

Returns

true if feature is supported, false otherwise.

gvr_poll_event

int32_t gvr_poll_event(
  gvr_context *gvr,
  gvr_event *event_out
)

Polls the event queue, populating the provided event if available while also popping it from the event queue.

Note that it is the caller's responsibility for querying the event queue in a timely fashion, as it will otherwise be flushed periodically.

Details

Parameters

`gvr_context`	The current context.
`event_out`	The event to populate. This will be populated with a valid gvr_event iff the result is GVR_NO_ERROR.

Returns

GVR_ERROR_NONE if an event was available, otherwise GVR_ERROR_NO_EVENT_AVAILABLE.

gvr_properties_get

int32_t gvr_properties_get(
  const gvr_properties *properties,
  int32_t property_key,
  gvr_value *value_out
)

Queries the given property's value, populating the provided value if available.

Details

Parameters

`gvr_properties`	The set of properties to query.
`property_key`	The property being queried.

Returns

GVR_ERROR_NONE if the property was available, otherwise GVR_ERROR_NO_PROPERTY_AVAILABLE.

gvr_set_surface_size

void gvr_set_surface_size(
  gvr_context *gvr,
  gvr_sizei surface_size_pixels
)

gvr_user_prefs_get_controller_handedness

int32_t gvr_user_prefs_get_controller_handedness(
  const gvr_user_prefs *user_prefs
)

Returns the controller handedness of the given gvr_user_prefs struct.

Details

Parameters

user_prefs

Pointer to the gvr_user_prefs object returned by gvr_get_user_prefs.

Returns

Either GVR_CONTROLLER_RIGHT_HANDED or GVR_CONTROLLER_LEFT_HANDED depending on which hand the user holds the controller in.