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(JNIEnv *env, jobject app_context, jobject class_loader)	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_request_features(const gvr_context *gvr, const int32_t *required_features, int32_t required_count, const int32_t *optional_features, int32_t optional_count, void *on_complete_activity)	void Request that the user enables one or more features.
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.
gvr_user_prefs_is_feature_enabled(const gvr_user_prefs *user_prefs, int32_t runtime_feature)	bool Queries whether a particular GVR feature has been enabled by the user.

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(
  JNIEnv *env,
  jobject app_context,
  jobject class_loader
)

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
Parameters	env The JNIEnv associated with the current thread. app_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).
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_request_features

void gvr_request_features(
  const gvr_context *gvr,
  const int32_t *required_features,
  int32_t required_count,
  const int32_t *optional_features,
  int32_t optional_count,
  void *on_complete_activity
)

Request that the user enables one or more features.

This API will return immediately and will asynchronously ask the user to enable features using a new Activity.

Details

Parameters

required_features A list of required features of type gvr_runtime_feature. The user will not be returned to the app if they decline a required feature. This can be null if there are no required features. required_count Number of required features in the array. optional_features A list of optional features of type gvr_runtime_feature. This can be null if there are no optional features. optional_count Number of optional features in the array. on_complete_activity A Java PendingIntent (jobject) that is triggered once the user has accepted all required features. This can be null to return to this activity.

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.

gvr_user_prefs_is_feature_enabled

bool gvr_user_prefs_is_feature_enabled(
  const gvr_user_prefs *user_prefs,
  int32_t runtime_feature
)

Queries whether a particular GVR feature has been enabled by the user.

Details
Parameters	gvr The context to query against. feature The gvr_runtime_feature type being queried.
Returns	true if feature has been enabled by the user, false otherwise.