November 6, 2019 update:
  • There's a new open source Cardboard SDK for iOS and Android NDK that offers a streamlined API, improved device compatibility, and built-in viewer profile QR code scanning. A corresponding Unity package (SDK) is planned for a future release. We recommend that all developers actively building for Google Cardboard migrate (iOS, Android NDK) to the new Cardboard SDK.
October 15, 2019 update:
  • The Daydream View VR headset is no longer available for purchase. However, you can continue to use the existing Google VR SDK to update and distribute your apps to the Google Play Store, and make them available to users in the Daydream app.

gvr::GvrApi

#include <gvr.h>

This is a convenience C++ wrapper for the Google VR C API.

Summary

This wrapper strategy prevents ABI compatibility issues between compilers by ensuring that the interface between client code and the implementation code in libgvr.so is a pure C interface. The translation from C++ calls to C calls provided by this wrapper runs entirely in the client's binary and is compiled by the client's compiler.

Methods in this class are only documented insofar as the C++ wrapping logic is concerned; for information about the method itself, please refer to the corresponding function in the C API.

Example API usage:

// Functionality supplied by the application in the example below has
// the "app-" prefix.
#ifdef __ANDROID__
// On Android, the gvr_context should almost always be obtained from the
// Java GvrLayout object via
// GvrLayout.getGvrApi().getNativeGvrContext().
std::unique_ptr gvr = GvrApi::WrapNonOwned(gvr_context);
#else
std::unique_ptr gvr = GvrApi::Create();
#endif

gvr->InitializeGl();

gvr::BufferViewportList viewport_list =
    gvr->CreateEmptyBufferViewportList();
gvr->GetRecommendedBufferViewports(&viewport_list);
gvr::BufferViewport left_eye_viewport = gvr->CreateBufferViewport();
gvr::BufferViewport right_eye_viewport = gvr->CreateBufferViewport();
viewport_list.Get(0, &left_eye_view);
viewport_list.Get(1, &right_eye_view);

std::vector specs;
specs.push_back(gvr->CreateBufferSpec());
specs[0].SetSamples(app_samples);
gvr::SwapChain swap_chain = gvr->CreateSwapChain(specs);

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->GetRecommendedRenderTargetSize();
  swap_chain.ResizeBuffer(0, render_target_size);
  gvr::Frame frame = swap_chain.AcquireFrame();
  while (!frame) {
    std::this_thread::sleep_for(2ms);
    frame = swap_chain.AcquireFrame();
  }

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

  const gvr::Mat4f head_view =
      gvr->GetHeadSpaceFromStartSpaceRotation(next_vsync);
  const gvr::Mat4f left_eye_view = MatrixMultiply(
      gvr->GetEyeFromHeadMatrix(kLeftEye), head_view);
  const gvr::Mat4f right_eye_view = MatrixMultiply(
      gvr->GetEyeFromHeadMatrix(kRightEye), head_view);

  frame.BindBuffer(0);
  // App does its rendering to the current framebuffer here.
  AppDoSomeRenderingForEye(
      left_eye_viewport.GetSourceUv(), left_eye_view);
  AppDoSomeRenderingForEye(
      right_eye_viewport.GetSourceUv(), right_eye_view);
  frame.Unbind();
  frame.Submit(viewport_list, head_view);
}

Constructors and Destructors

GvrApi(const GvrApi &)
~GvrApi()

Error handling

ClearError()
For more information, see gvr_clear_error().
GetCurrentProperties()
For more information, see gvr_get_current_properties().
GetError()
For more information, see gvr_get_error().
GetErrorString(Error error_code)
const char *
For more information, see gvr_get_error_string().
GetUserPrefs() const
For more information, see gvr_get_user_prefs().
PollEvent(Event *event_out)
bool
For more information, see gvr_poll_event().

Rendering

BindDefaultFramebuffer()
void
For more information, see gvr_bind_default_framebuffer().
CreateBufferSpec()
For more information, see gvr_buffer_spec_create().
CreateBufferViewport() const
Constructs a C++ wrapper for a gvr_buffer_viewport object.
CreateEmptyBufferViewportList() const
Constructs a C++ wrapper for a gvr_buffer_viewport_list object.
CreateSwapChain(const std::vector< BufferSpec > & specs)
For more information, see gvr_swap_chain_create().
DistortToScreen(int32_t texture_id, const BufferViewportList & viewport_list, const Mat4f & rendered_head_pose_in_start_space_matrix, const ClockTimePoint & texture_presentation_time)
void
For more information, see gvr_distort_to_screen().
GetAsyncReprojectionEnabled() const
bool
For more information, see gvr_get_async_reprojection_enabled().
GetMaximumEffectiveRenderTargetSize() const
GetScreenTargetSize() const
For more information, see gvr_get_screen_target_size().
InitializeGl()
void
For more information, see gvr_initialize_gl().
IsFeatureSupported(int32_t feature) const
bool
For more information, see gvr_is_feature_supported().
RequestFeatures(const int32_t *required_features, int32_t required_count, const int32_t *optional_features, int32_t optional_count, void *on_complete_activity) const
void
For more information, see gvr_request_features().
SetSurfaceSize(Sizei surface_size_pixels)
void
For more information, see gvr_set_surface_size().

Head tracking

ApplyNeckModel(const Mat4f & head_space_from_start_space_rotation, float factor) const
For more information, see gvr_apply_neck_model().
GetHeadSpaceFromStartSpaceRotation(const ClockTimePoint & time_point) const
For more information see gvr_get_head_space_from_start_space_rotation.
GetHeadSpaceFromStartSpaceTransform(const ClockTimePoint & time_point) const
For more information see gvr_get_head_space_from_start_space_transform.
GetTimePointNow()
For more information, see gvr_get_time_point_now().
PauseTracking()
void
For more information, see gvr_pause_tracking().
RecenterTracking()
void
ResetTracking()
void
For more information, see gvr_reset_tracking().
ResumeTracking()
void
For more information, see gvr_resume_tracking().

Viewer parameters

ComputeDistortedPoint(Eye eye, const Vec2f & uv_in)
std::array< Vec2f, 3 >
For more information, see gvr_compute_distorted_point().
GetEyeFromHeadMatrix(Eye eye) const
For more information, see gvr_get_eye_from_head_matrix().
GetViewerModel() const
const char *
For more information, see gvr_get_viewer_model().
GetViewerType() const
For more information, see gvr_get_viewer_type().
GetViewerVendor() const
const char *
For more information, see gvr_get_viewer_vendor().
GetWindowBounds() const
For more information, see gvr_get_window_bounds().
RefreshViewerProfile()
void
For more information, see gvr_refresh_viewer_profile().
SetDefaultViewerProfile(const char *viewer_profile_uri)
bool
For more information, see gvr_set_default_viewer_profile().

Wrapper manipulation

GetContext() Deprecated. Use cobj() instead.
GetContext() const
const gvr_context *
Deprecated. Use cobj() instead.
GvrApi(gvr_context *context, bool owned)
WrapNonOwned(gvr_context *context)
std::unique_ptr< GvrApi >
Instantiates a GvrApi instance that wraps a non-owned gvr_context.
cobj()
Returns the wrapped C object. Does not affect ownership.
cobj() const
const gvr_context *
release()
Returns the wrapped C object and transfers its ownership to the caller.

Public static functions

Create(JNIEnv *env, jobject app_context, jobject class_loader)
std::unique_ptr< GvrApi >
Instantiates and returns a GvrApi instance that owns a gvr_context.

Public functions

operator=(const GvrApi &)=delete
void

Error handling

ClearError

Error ClearError()

For more information, see gvr_clear_error().

GetCurrentProperties

Properties GetCurrentProperties()

For more information, see gvr_get_current_properties().

GetError

Error GetError()

For more information, see gvr_get_error().

GetErrorString

const char * GetErrorString(
  Error error_code
)

For more information, see gvr_get_error_string().

GetUserPrefs

UserPrefs GetUserPrefs() const 

For more information, see gvr_get_user_prefs().

PollEvent

bool PollEvent(
  Event *event_out
)

For more information, see gvr_poll_event().

Rendering

BindDefaultFramebuffer

void BindDefaultFramebuffer()

For more information, see gvr_bind_default_framebuffer().

CreateBufferSpec

BufferSpec CreateBufferSpec()

For more information, see gvr_buffer_spec_create().

CreateBufferViewport

BufferViewport CreateBufferViewport() const 

Constructs a C++ wrapper for a gvr_buffer_viewport object.

For more information, see gvr_buffer_viewport_create().

Details
Returns
A new BufferViewport instance with memory allocated for an underlying gvr_buffer_viewport.

CreateEmptyBufferViewportList

BufferViewportList CreateEmptyBufferViewportList() const 

Constructs a C++ wrapper for a gvr_buffer_viewport_list object.

For more information, see gvr_buffer_viewport_list_create().

Details
Returns
A new, empty BufferViewportList instance. Note: The validity of the returned object is closely tied to the lifetime of the member gvr_context. The caller is responsible for ensuring correct usage accordingly.

CreateSwapChain

SwapChain CreateSwapChain(
  const std::vector< BufferSpec > & specs
)

For more information, see gvr_swap_chain_create().

DistortToScreen

void DistortToScreen(
  int32_t texture_id,
  const BufferViewportList & viewport_list,
  const Mat4f & rendered_head_pose_in_start_space_matrix,
  const ClockTimePoint & texture_presentation_time
)

For more information, see gvr_distort_to_screen().

GetAsyncReprojectionEnabled

bool GetAsyncReprojectionEnabled() const 

For more information, see gvr_get_async_reprojection_enabled().

GetMaximumEffectiveRenderTargetSize

Sizei GetMaximumEffectiveRenderTargetSize() const 

GetScreenTargetSize

Sizei GetScreenTargetSize() const 

For more information, see gvr_get_screen_target_size().

InitializeGl

void InitializeGl()

For more information, see gvr_initialize_gl().

IsFeatureSupported

bool IsFeatureSupported(
  int32_t feature
) const 

For more information, see gvr_is_feature_supported().

RequestFeatures

void RequestFeatures(
  const int32_t *required_features,
  int32_t required_count,
  const int32_t *optional_features,
  int32_t optional_count,
  void *on_complete_activity
) const 

For more information, see gvr_request_features().

SetSurfaceSize

void SetSurfaceSize(
  Sizei surface_size_pixels
)

For more information, see gvr_set_surface_size().

Head tracking

ApplyNeckModel

Mat4f ApplyNeckModel(
  const Mat4f & head_space_from_start_space_rotation,
  float factor
) const 

For more information, see gvr_apply_neck_model().

GetHeadSpaceFromStartSpaceRotation

Mat4f GetHeadSpaceFromStartSpaceRotation(
  const ClockTimePoint & time_point
) const 

For more information see gvr_get_head_space_from_start_space_rotation.

GetHeadSpaceFromStartSpaceTransform

Mat4f GetHeadSpaceFromStartSpaceTransform(
  const ClockTimePoint & time_point
) const 

For more information see gvr_get_head_space_from_start_space_transform.

GetTimePointNow

ClockTimePoint GetTimePointNow()

For more information, see gvr_get_time_point_now().

PauseTracking

void PauseTracking()

For more information, see gvr_pause_tracking().

RecenterTracking

void RecenterTracking()

ResetTracking

void ResetTracking()

For more information, see gvr_reset_tracking().

ResumeTracking

void ResumeTracking()

For more information, see gvr_resume_tracking().

Viewer parameters

ComputeDistortedPoint

std::array< Vec2f, 3 > ComputeDistortedPoint(
  Eye eye,
  const Vec2f & uv_in
)

For more information, see gvr_compute_distorted_point().

GetEyeFromHeadMatrix

Mat4f GetEyeFromHeadMatrix(
  Eye eye
) const 

For more information, see gvr_get_eye_from_head_matrix().

GetViewerModel

const char * GetViewerModel() const 

For more information, see gvr_get_viewer_model().

GetViewerType

ViewerType GetViewerType() const 

For more information, see gvr_get_viewer_type().

GetViewerVendor

const char * GetViewerVendor() const 

For more information, see gvr_get_viewer_vendor().

GetWindowBounds

Recti GetWindowBounds() const 

For more information, see gvr_get_window_bounds().

RefreshViewerProfile

void RefreshViewerProfile()

For more information, see gvr_refresh_viewer_profile().

SetDefaultViewerProfile

bool SetDefaultViewerProfile(
  const char *viewer_profile_uri
)

For more information, see gvr_set_default_viewer_profile().

Wrapper manipulation

GetContext

gvr_context * GetContext()

Deprecated. Use cobj() instead.

GetContext

const gvr_context * GetContext() const 

Deprecated. Use cobj() instead.

GvrApi

 GvrApi(
  gvr_context *context,
  bool owned
)

WrapNonOwned

std::unique_ptr< GvrApi > WrapNonOwned(
  gvr_context *context
)

Instantiates a GvrApi instance that wraps a non-owned gvr_context.

Ownership of the provided context remains with the caller, and they are responsible for ensuring proper disposal of the context.

Details
Parameters
context
Pointer to a non-null, non-owned gvr_context instance.
Returns
unique_ptr to the created GvrApi instance. Never null.

cobj

gvr_context * cobj()

Returns the wrapped C object. Does not affect ownership.

cobj

const gvr_context * cobj() const 

release

gvr_context * release()

Returns the wrapped C object and transfers its ownership to the caller.

The wrapper becomes invalid and should not be used.

Public static functions

Create

std::unique_ptr< GvrApi > Create(
  JNIEnv *env,
  jobject app_context,
  jobject class_loader
)

Instantiates and returns a GvrApi instance that owns a gvr_context.

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
unique_ptr to the created GvrApi instance, nullptr on failure.

Public functions

GvrApi

 GvrApi(
  const GvrApi &
)=delete

operator=

void operator=(
  const GvrApi &
)=delete

~GvrApi

 ~GvrApi()