Google cardBoard Android API (三)：CardboardView

public class  CardboardView

Convenience extension of GLSurfaceView that can be used for VR rendering.

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

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

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

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

The view allows switching from VR mode to normal rendering mode in stereo renderers at any time by calling the setVRModeEnabled method.

Nested Classes

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

Public Constructors

CardboardView(Context context)

CardboardView(Context context, AttributeSet attrs)

Public Methods

boolean	getAlignmentMarkerEnabled()
CardboardDeviceParams	getCardboardDeviceParams()
boolean	getDistortionCorrectionEnabled()
boolean	getElectronicDisplayStabilizationEnabled()
boolean	getGyroBiasEstimationEnabled()
HeadMountedDisplay	getHeadMountedDisplay()
float	getInterpupillaryDistance()
float	getNeckModelFactor()
boolean	getRestoreGLStateEnabled()
ScreenParams	getScreenParams()
boolean	getSettingsButtonEnabled()
boolean	getVRMode()
boolean	getVignetteEnabled()
void	onPause()
void	onResume()
void	resetHeadTracker()
void	setAlignmentMarkerEnabled(boolean enabled)
void	setDistortionCorrectionEnabled(boolean enabled)
void	setElectronicDisplayStabilizationEnabled(boolean enabled)
void	setGyroBiasEstimationEnabled(boolean enabled)
void	setNeckModelEnabled(boolean enabled)
void	setNeckModelFactor(float factor)
void	setOnCardboardTriggerListener(Runnable listener)
void	setRenderer(CardboardView.Renderer renderer)
void	setRenderer(CardboardView.StereoRenderer renderer)
void	setRestoreGLStateEnabled(boolean enabled)
void	setSettingsButtonEnabled(boolean enabled)
void	setVRModeEnabled(boolean enabled)
void	setVignetteEnabled(boolean enabled)
void	undistortTexture(int inputTexture)
void	updateCardboardDeviceParams(CardboardDeviceParams cardboardDeviceParams)
void	updateScreenParams(ScreenParams screenParams)

Inherited Methods

▸ From class java.lang.Object

Public Constructors

public CardboardView (Context context)

public CardboardView (Context context, AttributeSet attrs)

Public Methods

public boolean getAlignmentMarkerEnabled ()

Returns whether the alignment marker is drawn.

Returns

• true if the alignment marker is enabled, false otherwise. Enabled by default.

public CardboardDeviceParams getCardboardDeviceParams ()

Returns the physical parameters of the current Cardboard device.

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

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

Returns

• The physical parameters of the current Cardboard device.

public boolean getDistortionCorrectionEnabled ()

Gets whether distortion correction is enabled.

Returns

• true if distortion correction is enabled, false otherwise.

public boolean getElectronicDisplayStabilizationEnabled ()

(Experimental) Returns whether or not Electronic Display Stabilization (EDS) is enabled. Refer to {link #setElectronicDisplayStabilizationEnabled} for more details about EDS.

Returns

• true if EDS is currently enabled false otherwise.

public boolean getGyroBiasEstimationEnabled ()

Whether gyroscope bias estimation is enabled.

Returns

• true if gyroscope bias estimation is enabled.

public HeadMountedDisplay getHeadMountedDisplay ()

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

Contains various parameters about the screen and Cardboard device that combined make up the head mounted display.

Note that changing the returned object will not make any changes to rendering. For that purpose the updateCardboardDeviceParams and updateScreenParams methods should be used instead.

Returns

• The parameters of the target head mounted display.

public float getInterpupillaryDistance ()

Gets the interpupillary distance. The Cardboard framework currently assumes that user IPD matches inter-lens distance of the viewing device.

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 boolean getRestoreGLStateEnabled ()

Returns whether or not the application's GL state after postprocessing is restored.

Returns

• true if GL state restoration is currently enabled, false otherwise. Enabled by default.

public ScreenParams getScreenParams ()

Returns the screen parameters of the inserted device.

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

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

Returns

• The screen parameters of the inserted device.

public boolean getSettingsButtonEnabled ()

Returns whether the settings button is drawn.

Returns

• true if the settings button is enabled, false otherwise. Enabled by default.

public boolean getVRMode ()

Returns the current VR mode setting.

Returns

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

public boolean getVignetteEnabled ()

Returns whether or not vignetting is enabled.

Returns

• true if vignetting is currently enabled, false otherwise. Enabled by default.

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 resetHeadTracker ()

Ask the head-tracker to reset itself.

Among other things, this will make the scene's Z axis align with the current phone heading (compass direction).

public void setAlignmentMarkerEnabled (boolean enabled)

Enables or disables drawing a vertical line dividing the viewport in half. This is designed to help users correctly align the cardboard to the screen.

Only applies when VR mode is enabled.

Parameters

enabled	true to enable drawing the alignment marker, false to disable.

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 setElectronicDisplayStabilizationEnabled (boolean enabled)

(Experimental) Enables or disables Electronic Display Stabilization (EDS).

Electronic Display Stabilization is done during the distortion rendering pass (so it only works if distortion correction is enabled). It reads the latest sensor input and, if the head has rotated since the app rendered the frame, it uses the difference in head rotation to warp the frame rendered by the app to account for the change in head rotation. This can reduce latency.

This is an experimental feature, and is disabled by default.

Parameters

enabled	true to enable EDS, false to disable it.

public void setGyroBiasEstimationEnabled (boolean enabled)

Enables or disables the use of gyroscope bias estimation for head tracking.

Gyroscopes often exhibit a bias, meaning that they don't return zero values when at rest. This can lead to spurious drift in head tracking. When gyroscope bias estimation is enabled, the framework will constantly attempt to estimate the gyroscope bias. This bias is then subtracted from the raw gyroscope values to reduce unwanted drift in head tracking. Note that gyroscope bias estimation is enabled by default.

Parameters

enabled	whether gyroscope bias estimation should be enabled.

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 CardboardActivity and want to handle trigger events at the CardboardView level. If you're using CardboardActivity, then it's recommended to use the onCardboardTrigger method from CardboardActivity instead of using this function.

Parameters

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

public void setRenderer (CardboardView.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 theRenderer interface for details.

Parameters

renderer	Renderer to set. Cannot be null.

public void setRenderer (CardboardView.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 theStereoRenderer interface for details.

Parameters

renderer	Stereo renderer to set.

public void setRestoreGLStateEnabled (boolean enabled)

Enables or disables restoration of the application's GL state after postprocessing.

CardboardView may perform certain postprocessing steps at the end of each frame. For example, application imagery might be rendered into a texture instead of on-screen. If this flag is enabled, the framework ensures that the GL state at the beginning of the next frame is equivalent to the GL state at the end of the last frame. Enabled by default.

If disabled, applications may gain a performance boost but can't make any assumptions about the following subset of the GL state machine at the beginning of each frame:

• Viewport
• Clear color
• Active texture unit
• Shader program that is being used
• Vertex attributes (pointers and whether or not they are enabled)
• Whether GL_CULL_FACE and GL_SCISSOR_TEST are enabled
• Bindings for GL_ARRAY_BUFFER and GL_ELEMENT_ARRAY_BUFFER
• Binding for GL_TEXTURE_2D in texture unit 0

There are two exceptions: 1. The currently bound frame buffer will always be restored, regardless of the state of this setting. 2. Vertex attribute bindings are never restored. Any calls to glVertexAttribPointer at the end of last frame will not be in effect anymore at the beginning of next frame.

Parameters

enabled	true to enable GL state restoration, false to disable.

public void setSettingsButtonEnabled (boolean enabled)

Enables or disables drawing a settings button at the bottom center of the screen. Tapping the button sends the user to the Google Cardboard app where they can configure user parameters and Cardboard viewer parameters. The configuration will automatically apply to all of the user's apps that are using the vrtoolkit.

Only applies when VR mode is enabled.

Parameters

enabled	true to enable drawing the settings button, false to disable.

public void setVRModeEnabled (boolean enabled)

Enables or disables VR 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 VR mode.

Parameters

enabled	true to enable VR mode, false to disable.

public void setVignetteEnabled (boolean enabled)

Enables or disables vignetting around the frame edge.

If this flag is enabled, the distortion shader applies a darkening effect to the edges of the visible viewport, simulating vignetting.

Enabled by default.

Parameters

enabled	true to enable vignette effect, false to disable.

public void undistortTexture (int inputTexture)

Undistorts the provided texture by rendering into the current output buffer.

This method is designed for API users that have their own rendering loop and cannot use the standard CardboardView.Renderer and CardboardView.StereoRenderer interfaces. Its use is discouraged for other purposes.

If a renderer has been set, texture undistortion will take place in the renderer thread. Otherwise the operation will happen in the calling thread. It is the responsibility of the caller to ensure the validity of the texture in the GL context of the thread where is used.

Parameters

inputTexture	Texture name to undistort.

public void updateCardboardDeviceParams (CardboardDeviceParamscardboardDeviceParams)

Updates the physical parameters of the Cardboard device used for rendering.

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

Parameters

cardboardDeviceParams	Physical parameters of a Cardboard-compatible device. 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 device inserted in the Cardboard. Changes will be effective from the first frame after this call.

Parameters

screenParams	Parameters to update. Ignored if null.