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
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 | |
| 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 |
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
GvrViewinstance.
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
GvrViewinstance.
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:
- Enable VR mode via
setVrModeEnabled(Activity, boolean). - Enable async reprojection via
setAsyncReprojectionEnabled(boolean). - Add the `com.google.intent.category.DAYDREAM` category to the Activity's `intent-filter`.
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
trueif asynchronous reprojection is enabled,falseotherwise. Disabled by default.
public boolean getDistortionCorrectionEnabled ()
Gets whether distortion correction is enabled.
Returns
trueif distortion correction is enabled,falseotherwise.
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
trueif stereo mode is currently enabled,falseotherwise. 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, |
|---|
Returns
trueif the new setting was successfully applied,falseotherwise. 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. |
|---|