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()
|
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
|
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)
|
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)
|
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()
|
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 |
|
||
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_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_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 |
|
||
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 |
|
||
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 |
|
||
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 |
|
||
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 |
|
||
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_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_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 |
|
||
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 |
|
||
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_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 |
|
||||
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 |
|
||||
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 |
|
||||
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 |
|
||
Returns |
Either GVR_CONTROLLER_RIGHT_HANDED or GVR_CONTROLLER_LEFT_HANDED depending on which hand the user holds the controller in.
|