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<gvr::BufferSpec> 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()