DaydreamApi

public class DaydreamApi

Entry point for Daydream-specific API calls. Create an instance of this class using the create(Context) method. When you no longer need it, you must clean it up with a call to the close() method. Once closed, this object cannot be reused. This object maintains a service connection to Google VR Services and dispatches calls to it asynchronously. Therefore, creating and closing this object is a somewhat heavy operation that involves binding to a service. It is advisable, therefore, to reuse a single instance (or a small number of instances) rather than create them frequently. A typical pattern is to create a DaydreamApi object on the Activity's onStart() method and close it on onStop(). This class is NOT thread-safe and must only be used from the main (UI) thread.

Public Methods

void	close() Cleans up and finalizes this instance.
static DaydreamApi	create(Context context) Create a DaydreamApi object.
static Intent	createVrIntent(ComponentName componentName) Create an Intent to launch a VR activity with the given component name.
void	exitFromVr(Activity activity, int requestCode, Intent data) Gracefully exits from the current VR Activity.
int	getCurrentViewerType() Gets the type of the currently paired viewer, as defined by GvrApi.ViewerType.
static boolean	isDaydreamReadyPlatform(Context context) Returns whether the current Android platform is considered "Daydream-ready".
void	launchInVr(PendingIntent pendingIntent) Launches the VR Activity specified by the given PendingIntent.
void	launchInVr(ComponentName componentName) Launches the VR Activity specified by the given ComponentName.
void	launchInVr(Intent intent) Launches the VR Activity specified by the given Intent.
void	launchInVrForResult(Activity activity, PendingIntent pendingIntent, int requestCode) Launches the VR Activity specified by the given PendingIntent that will return a result to the given Activity.
void	launchVrHomescreen() Launch the stereoscopic, 3D VR launcher homescreen.
static void	setVrContentIntent(Bundle extras) Marks a notification as safe to launch in VR.
static Intent	setupVrIntent(Intent intent) Format an Intent to launch a VR activity.

Inherited Methods

From class java.lang.Object

boolean	equals(Object arg0)
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

From interface java.lang.AutoCloseable

abstract void

close()

Public Methods

public void close ()

Cleans up and finalizes this instance.

After calling this method, you must release all references to this object and must not call any other methods. Doing so will throw an exception.

Calling this on an object that is already closed is a no-op.

public static DaydreamApi create (Context context)

Create a DaydreamApi object.

The created object must be finalized by calling close() once it's no longer needed.

Please note that this method may return null if the device does not support Daydream features or if Google VR Services is out of date, so your code must be prepared to handle the null return value gracefully.

Parameters

context

Returns

• The DaydreamApi object, if the device is Daydream-ready and the service is available and sufficiently up-to-date, null otherwise.

public static Intent createVrIntent (ComponentName componentName)

Create an Intent to launch a VR activity with the given component name.

It is recommended that applications use an Intent formatted in this way to launch VR activities.

Daydream-ready applications must not directly send intents created this way, but should instead use one of the launchInVr methods provided in this API.

Parameters

componentName	for the VR activity to launch.

Returns

• the properly formatted VR intent to launch.

public void exitFromVr (Activity activity, int requestCode, Intent data)

Gracefully exits from the current VR Activity.

Daydream-ready apps should use this when they need to transition from a Daydream Activity back to 2D content, e.g., to request a permission.

Calling this will trigger a transition from the current Activity to an intermediate VR Activity, where the user is prompted to remove their phone from the headset. After phone removal is detected, the target activity will be notified via onActivityResult(), using the provided requestCode and a result code of RESULT_OK. If the user cancels or interrupts the exit for any reason, or there is an error during the request flow, a result code of RESULT_CANCELED will be sent to the Activity result callback.

Parameters

activity	The Activity to receive the result of the exit flow, via Activity.onActivityResult().
requestCode	The private request code that will be used to indicate exit flow success or cancellation via Activity.onActivityResult().
data	Optional Intent data to supply to the Activity result callback. May be null.

public int getCurrentViewerType ()

Gets the type of the currently paired viewer, as defined by GvrApi.ViewerType.

By default, the viewer type is Cardboard (*not* Daydream). Daydream viewers are supported only on Daydream-ready platforms (see also isDaydreamReadyPlatform(Context)).

Note: The viewer type can change at any time when a pairing event occurs. However, it will typically happen when the VR application is in the backround (paused).

Warning: This method will block on an expensive Binder call (potentially taking several milliseconds). Plan accordingly and minimize usage on critical paths.

Returns

• The type of the viewer as defined by GvrApi.ViewerType. If no viewer has been explicitly paired by the user, this will be GvrApi.ViewerType.CARDBOARD.

public static boolean isDaydreamReadyPlatform (Context context)

Returns whether the current Android platform is considered "Daydream-ready".

Only Daydream-ready platforms support Daydream headsets, ensuring a consistent, smooth and low-latency VR experience.

Parameters

context	The current Context.

Returns

• Whether the current platform is Daydream-ready.

public void launchInVr (PendingIntent pendingIntent)

Launches the VR Activity specified by the given PendingIntent.

Calling this will cause the given PendingIntent to be launched after the appropriate Daydream-specific transition.

This is reserved for use with the Play Store VR In-App-Purchase (IAP) APIs.

Parameters

pendingIntent	for the VR play store activity to launch.

public void launchInVr (ComponentName componentName)

Launches the VR Activity specified by the given ComponentName.

Calling this will cause the Activity identified by the given ComponentName to be launched after the appropriate Daydream-specific transition.

This is the recommended way for Daydream-ready apps to launch another VR Activity, be it from a 2D Activity (typically through an "enter VR" button), or from a VR Activity.

Parameters

componentName	for the VR activity to launch.

Throws

ActivityNotFoundException	if no activity to handle the given intent is present on this device.

public void launchInVr (Intent intent)

Launches the VR Activity specified by the given Intent.

Calling this will cause the given Intent to be launched after the appropriate Daydream-specific transition.

Daydream-ready apps may use this method to launch a VR Activity when specifying additional intent flags, extras, or data fields. Intents passed to this should generally be instantiated with createVrIntent(ComponentName) and modified with additional fields needed.

Parameters

intent	for the VR activity to launch.

Throws

ActivityNotFoundException	if no activity to handle the given intent is present on this device.

public void launchInVrForResult (Activity activity, PendingIntent pendingIntent, int requestCode)

Launches the VR Activity specified by the given PendingIntent that will return a result to the given Activity.

Calling this will cause the given PendingIntent to be launched after the appropriate Daydream-specific transition.

This is reserved for use with the Play Store VR In-App-Purchase (IAP) APIs.

Parameters

activity	the activity to receive the result via onActivityResult().
pendingIntent	for the VR play store activity to launch.
requestCode	the requestCode to deliver in onActivityResult().

public void launchVrHomescreen ()

Launch the stereoscopic, 3D VR launcher homescreen.

Calling this will cause the VR homescreen to be launched after the appropriate Daydream-specific transition.

Daydream-ready apps must use this method whenever they launch the VR homescreen, be it from a 2D context, or from a VR context when one VR Activity wishes to return to the VR homescreen.

public static void setVrContentIntent (Bundle extras)

Marks a notification as safe to launch in VR.

This is meant to be called on a Notification.Builder's extras Bundle and signifies that the contentIntent set on the notification will resolve to a VR Activity if launched.

Expected usage: Notification.Builder builder; DaydreamApi.setVrContentIntent(builder.getExtras());

Parameters

extras	The extras Bundle from the Notification.Builder.

public static Intent setupVrIntent (Intent intent)

Format an Intent to launch a VR activity.

It is recommended that applications use an Intent formatted in this way to launch VR activities.

Daydream-ready applications must not directly send intents created this way, but should instead use one of the launchInVr methods provided in this API.

Parameters

intent	for a VR activity to launch.

Returns

• the properly formatted VR intent to launch.