GvrView

public class GvrView

A View that supports VR rendering.

Designed to work in full screen mode with a landscape or reverse landscape orientation.

This view can be used like a GLSurfaceView by implementing one of its rendering interfaces:

  • GvrView.StereoRenderer: abstracts all stereoscopic rendering details from the renderer.
  • GvrView.Renderer: for complex engines that need to handle all stereo rendering details by themselves.

The GvrView.StereoRenderer interface is recommended for all applications that can make use of it, while the GvrView.Renderer interface is discouraged and should only be used if really needed.

The view allows switching from stereo mode to mono rendering mode in stereo renderers at any time by calling the setStereoModeEnabled method.

Nested Classes

interface GvrView.Renderer Interface for renderers who need to handle all the stereo rendering details by themselves. 
interface GvrView.StereoRenderer Interface for renderers that delegate all stereoscopic rendering details to the view. 

Inherited Constants

Inherited Fields

Public Constructors

GvrView(Context context)
Creates a new GvrView instance.
GvrView(Context context, AttributeSet attrs)
Creates a new GvrView instance.

Public Methods

void
enableCardboardTriggerEmulation()
Enables emulation of Cardboard-style touch trigger input when using a Daydream headset.
boolean
getAsyncReprojectionEnabled()
Returns the current asynchronous reprojection setting.
boolean
getDistortionCorrectionEnabled()
Gets whether distortion correction is enabled.
GvrApi
getGvrApi()
See getGvrApi() for more information.
GvrViewerParams
getGvrViewerParams()
Returns the physical parameters of the current GVR viewer.
HeadMountedDisplay
getHeadMountedDisplay()
Returns the current head mounted display this view is rendering for.
float
getInterpupillaryDistance()
Gets the interpupillary distance.
float
getNeckModelFactor()
Gets the neck model factor for head tracking.
ScreenParams
getScreenParams()
Returns the screen parameters of the inserted display.
boolean
getStereoModeEnabled()
Returns the current stereo mode setting.
void
onBackPressed()
Optional hook the client can trigger from Activity.onBackPressed().
void
onPause()
Informs the view that the activity has been paused.
void
onResume()
Informs the view that the activity has been resumed.
void
queueEvent(Runnable r)
Queue a runnable to be run on the GL rendering thread.
void
recenterHeadTracker()
Recenters the head orientation (resets the yaw to zero, leaving pitch and roll unmodified).
void
resetHeadTracker()
This method is deprecated. This method will be removed in future versions of this API. All uses of this method can be safely replaced with calls to recenterHeadTracker().
boolean
setAsyncReprojectionEnabled(boolean enabled)
Enables or disables asynchronous reprojection.
void
setDepthStencilFormat(int format)
Sets the depth and stencil widths for the offscreen framebuffer.
void
setDistortionCorrectionEnabled(boolean enabled)
Sets whether distortion correction is enabled.
void
setEGLConfigChooser(int redSize, int greenSize, int blueSize, int alphaSize, int depthSize, int stencilSize)
Install a config chooser which will choose a config with at least the specified depthSize and stencilSize, and exactly the specified redSize, greenSize, blueSize and alphaSize.
void
setEGLContextClientVersion(int version)
Sets the desired EGLContext version to use.
void
setMultisampling(int numSamples)
Sets the number of samples per pixel, for multisampling.
void
setNeckModelEnabled(boolean enabled)
Fully enables or disables use of the neck model for head tracking.
void
setNeckModelFactor(float factor)
Sets the neck model factor for head tracking.
void
setOnCardboardTriggerListener(Runnable listener)
Sets a runnable that gets called back whenever a Cardboard trigger event occurs.
void
setOnCloseButtonListener(Runnable listener)
Sets a runnable that gets called back when the close button is clicked.
void
setOnTransitionViewDoneListener(Runnable listener)
Sets a runnable that gets called back when users have gone through the transition view.
void
setRenderTargetScale(float scale)
Sets the scaling factor for the buffer that the app renders to.
void
setRenderer(GvrView.StereoRenderer renderer)
Sets a renderer that delegates all details about stereoscopic rendering to the view.
void
setRenderer(GvrView.Renderer renderer)
Sets a renderer that handles all stereoscoping rendering details by itself.
void
setStereoModeEnabled(boolean enabled)
Enables or disables stereo rendering mode.
void
setTransitionViewEnabled(boolean enabled)
Enables/disables the transition view used to prompt the user to place their phone into a GVR viewer.
void
shutdown()
Shuts down the GvrView implementation, freeing associated resources.
void
updateGvrViewerParams(GvrViewerParams gvrViewerParams)
Updates the physical parameters of the GVR viewer used for rendering.
void
updateScreenParams(ScreenParams screenParams)
Updates the screen parameters used for rendering.

Inherited Methods

Public Constructors

public GvrView (Context context)

Creates a new GvrView instance.

Parameters
context The current Context. This *must* be, or wrap, an Activity instance.
Returns
  • The newly created GvrView instance.
Throws
IllegalArgumentException if the provided Context is not an Activity context.

public GvrView (Context context, AttributeSet attrs)

Creates a new GvrView instance.

Parameters
context The current Context. This *must* be, or wrap, an Activity instance.
attrs The custom AttributeSet.
Returns
  • The newly created GvrView instance.
Throws
IllegalArgumentException if the provided context is not an Activity context.

Public Methods

public void enableCardboardTriggerEmulation ()

Enables emulation of Cardboard-style touch trigger input when using a Daydream headset.

A Cardboard viewer supports touch-trigger based input, whereas a Daydream headest supports controller input. Enabling Cardboard trigger emulation will simulate Cardboard-style touch trigger input (see setOnCardboardTriggerListener(Runnable) using app and touchpad button events from a Daydream controller. This allows Cardboard-supporting apps to simply and easily support operation on a Daydream headset. Enabling this emulation will have no effect when the paired viewer is already a Cardboard viewer.

Note: It is not sufficient to enable Cardboard trigger emulation to run a Cardboard app on a Daydream headset. The following adjustments to a regular Cardboard app need also be made:

Note: Enabling trigger emulation will *only* translate controller clicks into trigger events. The client reticle (if present) will continue to track the user's head motion, which may be less than intuitive for users accustomed to controller-driven reticle motion in a typical Daydream app.

public boolean getAsyncReprojectionEnabled ()

Returns the current asynchronous reprojection setting.

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

public boolean getDistortionCorrectionEnabled ()

Gets whether distortion correction is enabled.

Returns
  • true if distortion correction is enabled, false otherwise.

public GvrApi getGvrApi ()

See getGvrApi() for more information.

Returns

public GvrViewerParams getGvrViewerParams ()

Returns the physical parameters of the current GVR viewer.

This is a convenience method for getHeadMountedDisplay().getGvrViewerParams.

Changes to the returned object do not have any effect on rendering. To make them effective use the updateGvrViewerParams method.

Returns
  • The physical parameters of the current GVR viewer.

public HeadMountedDisplay getHeadMountedDisplay ()

Returns the current head mounted display this view is rendering for.

Contains various parameters about the screen and GVR viewer that combined make up the head mounted display.

Changes to the returned object do not have any effect on rendering.

Returns
  • The parameters of the target head mounted display.

public float getInterpupillaryDistance ()

Gets the interpupillary distance. The GVR framework currently assumes that user IPD matches inter-lens distance of the viewer.

Returns
  • The current interpupillary distance in meters.

public float getNeckModelFactor ()

Gets the neck model factor for head tracking.

Refer to {link #setNeckModelEnabled()} for more detail on neck model and {link #setNeckModelFactor()} for more detail on neck model factor.

Returns
  • the neck model factor.

public ScreenParams getScreenParams ()

Returns the screen parameters of the inserted display.

This is a convenience method for getHeadMountedDisplay().getScreenParams().

Changes to the returned object do not have any effect on rendering. To make them effective use the updateScreenParams method.

Returns
  • The screen parameters of the inserted display.

public boolean getStereoModeEnabled ()

Returns the current stereo mode setting.

Returns
  • true if stereo mode is currently enabled, false otherwise. Enabled by default.

public void onBackPressed ()

Optional hook the client can trigger from Activity.onBackPressed().

This will invoke the currently configured "close" behavior for the view. For Daydream-compatible Activities this will quit VR and restore the Android launcher. If the user has configured an override for the close button behavior, that action will be invoked. Otherwise, this call will simply invoke Activity.finish().

public void onPause ()

Informs the view that the activity has been paused.

public void onResume ()

Informs the view that the activity has been resumed.

public void queueEvent (Runnable r)

Queue a runnable to be run on the GL rendering thread. This can be used to communicate with the Renderer on the rendering thread. If the renderer has not been set, the task will be run synchronously.

Parameters
r The Runnable to be run on the GL rendering thread.

public void recenterHeadTracker ()

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

This will make the scene's Z axis align with the current phone heading (compass direction). In other words, after calling this method, the direction that the user is currently looking at will be redefined as "forward" (zero yaw). Pitch and roll are not modified.

Warning: This method must only be used by Cardboard apps. Do not call this on Daydream apps. On the Daydream platform, recentering is handled automatically and should never be programatically triggered by apps. Hybrid apps that work both in Cardboard and Daydream mode must only call this method when in Cardboard mode (that is, when the phone is paired with a Cardboard viewer), never in Daydream mode.

public void resetHeadTracker ()

This method was deprecated in API level .
This method will be removed in future versions of this API. All uses of this method can be safely replaced with calls to recenterHeadTracker().

Ask the head-tracker to reset itself.

This method is deprecated. Use recenterHeadTracker() instead, which accomplishes the same effects but avoids the undesirable side-effects of a full reset (temporary loss of tracking quality).

Among other things, this will make the scene's Z axis align with the current phone heading (compass direction). Warning resetHeadTracker() wipes out all the head-tracking state, so recenterHeadTracker() should be used instead in most cases.

Warning: This method must only be used by Cardboard apps. Do not call this on Daydream apps. On the Daydream platform, recentering is handled automatically and should never be programatically triggered by apps. Hybrid apps that work both in Cardboard and Daydream mode must only call this method when in Cardboard mode (that is, when the phone is paired with a Cardboard viewer), never in Daydream mode.

public boolean setAsyncReprojectionEnabled (boolean enabled)

Enables or disables asynchronous reprojection.

Must be called on the UI thread. If enabled, buffers will be submitted to an asynchronous thread, for stabilized reprojection and rendering.

Note: Async reprojection may not be available on every platform. Once enabled, async reprojection cannot be disabled.

Parameters
enabled true to enable asynchronous reprojection, false to disable.
Returns
  • true if the new setting was successfully applied, false otherwise. Disabled by default.

public void setDepthStencilFormat (int format)

Sets the depth and stencil widths for the offscreen framebuffer.

Note that this applies to the framebuffer that the app renders to, not the window's backbuffer.

If this method is called, it must be called before setRenderer(Renderer) is called.

Parameters
format One of the available formats from BufferSpec.DepthStencilFormat. Defaults to DEPTH_16.

public void setDistortionCorrectionEnabled (boolean enabled)

Sets whether distortion correction is enabled.

Enabled by default. Changes will be effective from the first frame after this call.

Parameters
enabled true to enable distortion correction, false to disable.

public void setEGLConfigChooser (int redSize, int greenSize, int blueSize, int alphaSize, int depthSize, int stencilSize)

Install a config chooser which will choose a config with at least the specified depthSize and stencilSize, and exactly the specified redSize, greenSize, blueSize and alphaSize.

If this method is called, it must be called before setRenderer(Renderer) is called.

If this method is not called, then by default the view will choose an RGB_888 surface with a depth buffer depth of at least 16 bits.

Parameters
redSize
greenSize
blueSize
alphaSize
depthSize
stencilSize

public void setEGLContextClientVersion (int version)

Sets the desired EGLContext version to use.

If this method is called, it must be called before setRenderer(Renderer) is called. If this function is not called, OpenGL ES 2.0 is used.

Parameters
version The EGLContext client version to choose. Use 2 for OpenGL ES 2.0.

public void setMultisampling (int numSamples)

Sets the number of samples per pixel, for multisampling. Multisampling is disabled by default.

Note that this applies to the framebuffer that the app renders to, not the window's backbuffer.

If this method is called, it must be called before setRenderer(Renderer) is called.

If this method is called, it is recommended to reduce the distortion correction scale via setRenderTargetScale(float) to improve performance.

Parameters
numSamples The number of samples to use. 0 and 1 indicate that multisampling should be disabled.

public void setNeckModelEnabled (boolean enabled)

Fully enables or disables use of the neck model for head tracking.

The neck model simulates how head rotations naturally happen relative to the base of the neck, not around the midpoint between the eyes, causing translational viewpoint movement in addition to rotation.

Parameters
enabled true to enable the neck model, false to disable. It is equivalent to calling setNeckModelFactor(enabled ? 1.0 : 0.0).

public void setNeckModelFactor (float factor)

Sets the neck model factor for head tracking.

Refer to {link #setNeckModelEnabled()} for more detail on neck model.

Parameters
factor Neck model factor between 0.0f and 1.0f. Set factor to 0.0f will completely disable the neck model, and 1.0f will completely activate the neck model. Value beturn 0.0f and 1.0f will partially use the neck model by linear interpolating the full neck model and no neck model according to the factor value.

public void setOnCardboardTriggerListener (Runnable listener)

Sets a runnable that gets called back whenever a Cardboard trigger event occurs.

This is only useful if you're not using GvrActivity and want to handle trigger events at the GvrView level. If you're using GvrActivity, then it's recommended to use the onCardboardTrigger method from GvrActivity instead of using this function.

Parameters
listener Runnable that gets called back whenever a Cardboard trigger event occurs.

public void setOnCloseButtonListener (Runnable listener)

Sets a runnable that gets called back when the close button is clicked.

For Daydream-compatible activities, the default close behavior is to finish the activity and navigate back to the 2D Android home launcher. For Cardboard activities, the default close behavior is to simply navigate back.

The client can and should override this if they desire custom behavior, particularly with hybrid VR apps where there are 2D activity components.

Parameters
listener The task to execute when the close button is clicked. A null argument restores the default behavior.

public void setOnTransitionViewDoneListener (Runnable listener)

Sets a runnable that gets called back when users have gone through the transition view.

This must be called from the UI thread.

Note: Transition view behavior can vary for Daydream Activities and viewers, and it cannot be assumed that the transition view will be displayed to the user in all cases. As such, this callback should not be used to gate any critical functionality or logic.

Parameters
listener Runnable called on the UI thread when the transition view is dismissed.

public void setRenderTargetScale (float scale)

Sets the scaling factor for the buffer that the app renders to.

Sets the factor by which we multiply the resolution of the image we render off-screen before passing it into the DistortionRenderer. This factor must be greater than 0.0 and at most 1.0. The renderer's onDrawFrame method will receive a Viewport with size (W * scale) x (H * scale) where W and H is the full size of the render target. When set to 1.0, the scene is rendered at approximately 150% of the device's display resolution. This results in a 1-to-1 pixel size ratio at the center of the distorted image but has a significant performance impact.

This factor has no effect if distortion correction is not enabled.

1.0 by default. Changes will be effective from the first frame after this call.

Parameters
scale The factor by which the resolution is multiplied. Greater than 0.0 and at most 1.0.

public void setRenderer (GvrView.StereoRenderer renderer)

Sets a renderer that delegates all details about stereoscopic rendering to the view.

Only one renderer should be set during the entire lifetime of this object. See the StereoRenderer interface for details.

Parameters
renderer Stereo renderer to set. Cannot be null.

public void setRenderer (GvrView.Renderer renderer)

Sets a renderer that handles all stereoscoping rendering details by itself.

Only one renderer should be set during the entire lifetime of this object. See the Renderer interface for details.

Parameters
renderer Renderer to set. Cannot be null.

public void setStereoModeEnabled (boolean enabled)

Enables or disables stereo rendering mode.

Controls stereo rendering and distortion correction. Enabled by default. Changes will be effective from the first frame after this call.

If disabled, no interpupillary distance will be applied to the eye transformations, automatic distortion correction will not take place, field of view and perspective may look off especially if the view is not set to fullscreen. Changes will be applied to the next frames being drawn.

See the documentation of the Renderer and StereoRenderer interfaces for details on how they are affected by stereo mode.

Parameters
enabled true to enable stereo mode, false to disable.

public void setTransitionViewEnabled (boolean enabled)

Enables/disables the transition view used to prompt the user to place their phone into a GVR viewer.

Note: Transition view behavior can vary for Daydream Activities and viewers, and may not respect the user setting.

Parameters
enabled Whether the transition view is enabled. Disabled by default.

public void shutdown ()

Shuts down the GvrView implementation, freeing associated resources.

This method should typically be called from the hosting activity's onDestroy() method.

Note: This method should *always* be called by the creator to properly dispose of resources. After shutdown, the caller is responsible for ensuring that the GvrView instance is no longer explicitly used.

public void updateGvrViewerParams (GvrViewerParams gvrViewerParams)

Updates the physical parameters of the GVR viewer used for rendering.

Changes will be effective from the first frame after this call until the next call to onResume(). The caller is responsible for injecting the parameters again after onResume().

Note: This method is only supported when using a Cardboard headset, and only updates the parameters for the current application.

Parameters
gvrViewerParams Physical parameters of a GVR-compatible viewer. Ignores the request if the object is null or same as current.

public void updateScreenParams (ScreenParams screenParams)

Updates the screen parameters used for rendering.

Updates the screen parameters of the display inserted in the Cardboard. Changes will be effective from the first frame after this call until the next call to onResume(). The caller is responsible for injecting the parameters again after onResume().

Note: This method is only supported when using a Cardboard headset, and only updates the parameters for the current application.

Parameters
screenParams Parameters to update. Ignored if null.