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)
|
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 | |
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 BufferViewport createBufferViewport ()
Creates an empty buffer viewport.
Returns
- A handle to an allocated instance of
BufferViewport
.
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
- A handle to an allocated
BufferViewportList
.
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 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.