GvrApi

public class GvrApi

Java bindings for the native GVR API.

GvrApi is designed for clients writing VR experiences on head mounted displays consisting in a mobile phone and a Cardboard-like viewer. It should be obtained from its owning GvrLayout via getGvrApi(). Typical interaction involves obtaining the underlying gvr_context via getNativeGvrContext(), and using that context in native code via the native GVR API.

Note: Unless otherwise noted, the methods on this class may not be thread-safe, and it is up the caller to use GvrApi in a thread-safe manner.

Nested Classes

class GvrApi.Error Constants that represent GVR error codes. 
class GvrApi.Feature Constants that represent non-universal GVR features. 
class GvrApi.ViewerType Constants that represent possible GVR viewer types. 

Public Methods

int
clearError()
Clears the current GVR error code, and returns the error code that was cleared.
float[]
computeDistortedPoint(int eye, float[] uvIn)
Computes the distorted point for a given point in a given eye, if possible.
BufferSpec
createBufferSpec()
Creates a new buffer specification with default parameters.
BufferViewport
createBufferViewport()
Creates an empty buffer viewport.
BufferViewportList
createBufferViewportList()
Creates a new, empty list of render parameters.
SwapChain
createSwapChain(BufferSpec[] specs)
Creates a swap chain from the passed array of buffer specifications.
void
distortToScreen(int textureId, BufferViewportList bufferViewportList, float[] headSpaceFromStartSpace, long texturePresentationTimeNs)
This method is deprecated. This method is deprecated, and its use should be replaced with the more powerful and flexible SwapChain and Frame APIs.
boolean
getAsyncReprojectionEnabled()
Returns the current asynchronous reprojection setting.
Properties
getCurrentProperties()
Returns an object containing information about current properties.
int
getError()
Returns the current GVR error code, or Error.NONE if there is no error.
static String
getErrorString(int errorCode)
Returns a human-readable string representing the given error code.
void
getEyeFromHeadMatrix(int eye, float[] matrixOut)
Gets the transformation from head space to eye space for the given eye.
float[]
getEyeFromHeadMatrix(int eye)
This method is deprecated. This method will be removed in a future release. Use getEyeFromHeadMatrix(int, float[]) instead, which does not generate garbage.
void
getHeadSpaceFromStartSpaceRotation(float[] headSpaceFromStartSpaceRotationOut, long timeNs)
This method is deprecated. This method can be safely replaced with use of the getHeadSpaceFromStartSpaceTransform(float[], long) method. The new API reflects that the call *can* return a full 6DoF transform when supported by both the headset and the client application.
void
getHeadSpaceFromStartSpaceTransform(float[] headSpaceFromStartSpaceTransformOut, long timeNs)
Gets the position and rotation from start to head space.
void
getMaximumEffectiveRenderTargetSize(Point size)
Returns the maximum effective size for the client's render target, given the parameters of the head mounted device selected.
long
getNativeGvrContext()
Gets a raw pointer to the native GvrApi instance (a gvr_context struct).
void
getRecommendedBufferViewports(BufferViewportList bufferViewportOut)
Gets the recommended viewports, which include the dimensions of the render target in physical pixels, the per-eye recommended UV coordinates and field of view.
void
getScreenBufferViewports(BufferViewportList bufferViewportOut)
Gets the screen (non-distorted) viewports, which include the dimensions of the render target in physical pixels, the per-eye recommended UV coordinates and field of view.
void
getScreenTargetSize(Point size)
Gets the screen (non-distorted) size for the target, given the available data on the head mounted device selected, if possible.
UserPrefs
getUserPrefs()
Returns an object containing information about user preferences.
String
getViewerModel()
Gets the name of the viewer model as a string.
int
getViewerType()
Gets the type of the viewer model as defined in GvrApi.ViewerType.
String
getViewerVendor()
Gets the name of the viewer vendor as a string.
int[]
getWindowBounds()
Gets the window bounds, if possible.
void
initializeGl()
Initializes necessary GL-related objects and uses the current thread and GL context for rendering.
boolean
isFeatureSupported(int feature)
Queries whether a particular GVR feature is supported by the underlying platform.
boolean
isFeatureSupported(UserPrefs.RuntimeFeature feature)
Queries whether a particular runtime feature is supported by the underlying platform.
void
pauseTracking()
Pauses head tracking, disables all sensors (to save battery).
boolean
pollEvent(Event eventOut)
Polls the event queue, populating the provided event if available while also popping it from the event queue.
void
recenterTracking()
Recenters the head orientation (resets the yaw to zero, leaving pitch and roll unmodified).
void
refreshViewerProfile()
Refreshes GvrApi with the Cardboard viewer profile.
void
requestFeatures(RuntimeFeature[] requiredFeatures, RuntimeFeature[] optionalFeatures, PendingIntent resultActivity)
Request that the user enables one or more features.
void
resetTracking()
Resets head tracking.
void
resumeTracking()
Resumes head tracking, re-enables all sensors.
void
setDefaultFramebufferActive()
Sets the default offscreen framebuffer to be active.
boolean
setDefaultViewerProfile(String viewerProfileUri)
Sets the default Cardboard viewer profile specified by viewerProfileUri.
void
shutdown()
Shuts down the GvrApi instance, freeing associated resources including the native gvr_context handle.

Inherited Methods

Public Methods

public int clearError ()

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

Returns
  • The GVR error code that was cleared by this function, or Error.NONE if no error has occurred.

public float[] computeDistortedPoint (int eye, float[] uvIn)

Computes the distorted point for a given point in a given eye, if possible.

The distortion inverts the optical distortion caused by the lens for the eye. Due to chromatic aberration, the distortion is different for each color channel.

Parameters
eye the eye for which to compute distorted point (left or right)
uvIn a point in screen eye Viewport Space in [0,1]^2 with (0, 0) in the lower left corner of the eye's viewport and (1, 1) in the upper right corner of the eye's viewport
Returns
  • an array of (at least) 3 elements, with each element being a Point2f representing a point in render texture eye Viewport Space in [0,1]^2 with (0, 0) in the lower left corner of the eye's viewport and (1, 1) in the upper right corner of the eye's viewport. |*uvOut[0]| is the corrected position of |uvIn| for the red channel. |*uvOut[1]| is the corrected position of |uvIn| for the green channel. |*uvOut[2]| is the corrected position of |uvIn| for the blue channel.

public BufferSpec createBufferSpec ()

Creates a new buffer specification with default parameters.

public BufferViewport createBufferViewport ()

Creates an empty buffer viewport.

Returns

public BufferViewportList createBufferViewportList ()

Creates a new, empty list of render parameters. Render parameters are used internally to inform distortion rendering, and are a function of intrinisic screen and viewer parameters.

The caller should populate the returned params using one of:

Returns

public SwapChain createSwapChain (BufferSpec[] specs)

Creates a swap chain from the passed array of buffer specifications.

Parameters
specs

public void distortToScreen (int textureId, BufferViewportList bufferViewportList, float[] headSpaceFromStartSpace, long texturePresentationTimeNs)

This method was deprecated in API level .
This method is deprecated, and its use should be replaced with the more powerful and flexible SwapChain and Frame APIs.

Distorts the texture that is passed in based on the characteristics of the lenses, and renders it to the display.

It performs post-frame operations like distortion correction and more. Should be called after the app renders its frame. Note that the texture that is referenced by the textureId will be copied and post-processed, and the original texture will remain unmodified.

Parameters
textureId the OpenGL texture ID of the texture into which the frame was rendered by the app. The original texture referenced by the textureId will remain unmodified.
bufferViewportList the render parameters to be distorted
headSpaceFromStartSpace the 4x4, column-major transform with which the frame was rendered, representing the transform from start space (space with head at the origin at last tracking reset) to head space (space with head at the origin and axes aligned to the view vector). This should typically be the transform returned by getHeadSpaceFromStartSpaceRotation(float[], long).
texturePresentationTimeNs the expected time that this frame will appear on the screen.

public boolean getAsyncReprojectionEnabled ()

Returns the current asynchronous reprojection setting.

Note: This setting can only be configured via setAsyncReprojectionEnabled(boolean), before the first call to initializeGl().

Returns
  • true if asynchronous reprojection is enabled, false otherwise. Disabled by default.

public Properties getCurrentProperties ()

Returns an object containing information about current properties.

public int getError ()

Returns the current GVR error code, or Error.NONE if there is no error. This function doesn't clear the error code; see clearError().

Returns
  • The current GVR error code, or Error.NONE if there is no error.

public static String getErrorString (int errorCode)

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

Parameters
errorCode The error code to get a human-readable representation of.
Returns
  • A human-readable string representing the given error code.

public void getEyeFromHeadMatrix (int eye, float[] matrixOut)

Gets the transformation from head space to eye space for the given eye.

Parameters
eye The eye for which the matrix should be queried
matrixOut Array that receives the matrix. It is returned in column-major form and is compatible with operations in android.opengl.Matrix.

public float[] getEyeFromHeadMatrix (int eye)

This method was deprecated in API level .
This method will be removed in a future release. Use getEyeFromHeadMatrix(int, float[]) instead, which does not generate garbage.

Gets the transformation matrix to convert from Head Space to Eye Space for the given eye, if possible.

Parameters
eye the selected eye to render to
Returns
  • transformation matrix from Head Space to the selected Eye Space. The matrix represented in the array that is returned is column-major and it is compatible with operations in android.opengl.Matrix.

public void getHeadSpaceFromStartSpaceRotation (float[] headSpaceFromStartSpaceRotationOut, long timeNs)

This method was deprecated in API level .
This method can be safely replaced with use of the getHeadSpaceFromStartSpaceTransform(float[], long) method. The new API reflects that the call *can* return a full 6DoF transform when supported by both the headset and the client application.

Gets the rotation from start to head space. Head space is a space where the head is at the origin and faces the -Z direction.

Parameters
headSpaceFromStartSpaceRotationOut A matrix representation of the rotation from start space (the space where the head was last reset) to head space (the space with the head at the origin, and the axes aligned to the view vector). This should be provided as float[16] array, and will be populated as a 4x4 column-major transform.
timeNs the time of the monotonic system clock at which to get the head rotation. The time should be in the future.
Throws
IllegalArgumentException if the array that we will use to populate the pose data is null or does not have the valid length

public void getHeadSpaceFromStartSpaceTransform (float[] headSpaceFromStartSpaceTransformOut, long timeNs)

Gets the position and rotation from start to head space. Head space is a space where the head is at the origin and faces the -Z direction.

Note that, on headsets that support 6DoF head tracking, the app is required to declare 6DoF support in order to receive a fully formed 6DoF pose. 6DoF support can be declared with the following manifest declaration:

 
 

Parameters
headSpaceFromStartSpaceTransformOut A matrix representation of the transform from start space (the space where the head was last reset) to head space (the space with the head at the origin, and the axes aligned to the view vector). This should be provided as float[16] array, and will be populated as a 4x4 column-major transform.
timeNs the time of the monotonic system clock at which to get the head rotation. The time should be in the future.
Throws
IllegalArgumentException if the array that we will use to populate the pose data is null or does not have the valid length

public void getMaximumEffectiveRenderTargetSize (Point size)

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.

Parameters
size an out parameter, will be modified to equal the maximum effective size for the render target in format: {width, height}

public long getNativeGvrContext ()

Gets a raw pointer to the native GvrApi instance (a gvr_context struct).

Warning: This function is only useful if you want to do native rendering. As the Java GvrApi object owns the native gvr_context struct, it is up to the caller to ensure that any direct access to the native gvr_context object occurs while the Java GvrApi object is still alive.

public void getRecommendedBufferViewports (BufferViewportList bufferViewportOut)

Gets the recommended viewports, which include the dimensions of the render target in physical pixels, the per-eye recommended UV coordinates and field of view.

Parameters
bufferViewportOut

public void getScreenBufferViewports (BufferViewportList bufferViewportOut)

Gets the screen (non-distorted) viewports, which include the dimensions of the render target in physical pixels, the per-eye recommended UV coordinates and field of view.

Parameters
bufferViewportOut

public void getScreenTargetSize (Point size)

Gets the screen (non-distorted) size for the target, given the available data on the head mounted device selected, if possible.

Parameters
size
Returns
  • the screen (non-distorted) size for the target in format: {width, height}

public UserPrefs getUserPrefs ()

Returns an object containing information about user preferences. This method may block the first time it's called.

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

Returns
  • A UserPreferences object containing current user preferences.

public String getViewerModel ()

Gets the name of the viewer model as a string.

public int getViewerType ()

Gets the type of the viewer model as defined in GvrApi.ViewerType.

public String getViewerVendor ()

Gets the name of the viewer vendor as a string.

public int[] getWindowBounds ()

Gets the window bounds, if possible.

Returns
  • window bounds in physical pixels: format {left, top, right, bottom}

public void initializeGl ()

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

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

public boolean isFeatureSupported (int feature)

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

Parameters
feature The gvr_feature type being queried.
Returns
  • true if feature is supported, false otherwise.

public boolean isFeatureSupported (UserPrefs.RuntimeFeature feature)

Queries whether a particular runtime feature is supported by the underlying platform. Even if the feature is supported, the user may have disabled it. Whether a feature is enabled or disabled can be queried via isFeatureEnabled(UserPrefs.RuntimeFeature).

Parameters
feature The UserPrefs.RuntimeFeature being queried.
Returns
  • true if feature is supported, false otherwise.

public void pauseTracking ()

Pauses head tracking, disables all sensors (to save battery).

public boolean pollEvent (Event eventOut)

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.

Parameters
eventOut The event to put the result in; must not be null.
Returns
  • Whether an event was returned in eventOut. If false, eventOut is unchanged.

public void recenterTracking ()

Recenters the head orientation (resets the yaw to zero, leaving pitch and roll unmodified).

public void refreshViewerProfile ()

Refreshes GvrApi with the Cardboard viewer profile.

If it cannot find the Cardboard viewer profile, nothing will happen.

public void requestFeatures (RuntimeFeature[] requiredFeatures, RuntimeFeature[] optionalFeatures, PendingIntent resultActivity)

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.

Parameters
requiredFeatures A list of required features. 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.
optionalFeatures A list of optional features. This can be null if there are no optional features.
resultActivity PendingIntent that is triggered once the user has accepted all required features.

public void resetTracking ()

Resets head tracking. Warning ResetTracking() wipes out all the states, so RecenterTracking() should be used instead in most cases.

public void resumeTracking ()

Resumes head tracking, re-enables all sensors.

public void setDefaultFramebufferActive ()

Sets the default offscreen framebuffer to be active. Binds the default framebuffer to the renderer.

public boolean setDefaultViewerProfile (String viewerProfileUri)

Sets the default Cardboard viewer profile specified by viewerProfileUri.

The viewerProfileUri that is passed in will be ignored if a valid Cardboard viewer profile has already been stored on the device that the app is running on.

If the valid Cardboard viewer profile can be found on the device, the URI that is passed in will be ignored and nothing will happen. Otherwise, GvrApi will look for the Cardboard viewer profile specified by viewerProfileUri, and it will be stored if found. Also, the values will be applied to GvrApi.

Warning: This function has the potential of blocking for up to 30 seconds for each redirect if a shortened URI is passed in as argument. It will try to unroll the shortened URI for a maximum number of 5 times if the redirect continues. In that case, it is recommended to create a separate thread to call this function so that other tasks like rendering will not be blocked on this. The blocking can be avoided if a standard URI is passed in.

Parameters
viewerProfileUri a string that contains either the shortened URI or the standard URI representing the Cardboard viewer profile that the app should be using.
Returns
  • true if the Cardboard viewer profile specified by viewerProfileUri was successfully stored and applied

public void shutdown ()

Shuts down the GvrApi instance, freeing associated resources including the native gvr_context handle.

Note: The caller is responsible for ensuring that neither this GvrApi instance, nor the native gvr_context instance it owns, are used after shutdown.