Mobile SDK

As this is a significant API refactor, please refer to the Unity Development Guide: ... Menu localization support: English, French, Italian, German, S...

3 downloads 76 Views 8MB Size

Recommend Documents


Mobile SDK
For detailed instructions on updating native projects to this SDK version, see Mobile ..... Once downloaded, extract the .zip file into a directory of your choice (e.g., ...... against VrApi, then calls nativeSetAppInterface() to allow the C++ code t

Mobile SDK
In theory, Gear VR applications may receive messages from System ...... 112 | Testing and Troubleshooting | Mobile or .... GLSL_ES_Specification_3.00.3.pdf ..... For projects which rely on the 3rdParty libraries, minizip or stb, the following ...

Mobile SDK
To become acquainted with the Oculus VR environment and with using Gear .... In your activity's onCreate method, add the following line: ... Bitmapfont - Fix for font info height not being y-scaled. ..... using native code languages such as C and C++

Mobile SDK
Native application framework for building high-performance VR Applications from scratch. ... Native project sample applications and source to provide reference model ... Mobile Development Basics: Information every developer should know about ......

Mobile SDK - Oculus
push notifications, or authentication via a separate Android application) do not make sense on Oculus Go. • No Camera. Oculus Go does not have a camera, and ...

Audio SDK
than the dimensions of a typical human head, allowing us to rely on timing ...... The Oculus Spatializer Plugin (OSP) is an add-on plugin for FMOD Studio that ...

PC SDK
The Oculus Debug Tool moved from the SDK to the runtime. The new ...... WPA is included in the Windows Assessment and Deployment Kit (Windows ADK): ..... can see that all of the GPU time used by the server is applied toward rendering:.

PC SDK
This guide describes major changes since the last release, provides instructions ... reason, and for future improvements, we recommend submitting depth data with your eye buffers. ...... profile, implement head-tracking, sensor fusion, stereoscopic 3

Mobile
obtain additional information. Enforcement. Corrective action must occur within 15 business days, unless otherwise provided. We may impose a fine for each day ...

Audio SDK
ignoring localization, if we are unable to compensate for head motion, then sound .... Bluetooth technology is not recommended for audio output. ... By the same token, an .... paradoxically make things seem less realistic, as we are conditioned by ..

Mobile SDK Version 0.4.3

2 | Introduction | Mobile

Copyrights and Trademarks ©

2017 Oculus VR, LLC. All Rights Reserved.

OCULUS VR, OCULUS, and RIFT are trademarks of Oculus VR, LLC. (C) Oculus VR, LLC. All rights reserved. BLUETOOTH is a registered trademark of Bluetooth SIG, Inc. All other trademarks are the property of their respective owners. Certain materials included in this publication are reprinted with the permission of the copyright holder.

2 |  | 

Mobile | Contents | 3

Contents Introduction to Mobile VR Development............................................................ 6 Getting Started.................................................................................................................................................. 6 System and Hardware Requirements................................................................................................................ 6 SDK Contents.................................................................................................................................................... 7 Contact...............................................................................................................................................................9

0.4 Release Notes..............................................................................................10 Device and Environment Setup......................................................................... 14 Introduction...................................................................................................................................................... 14 Install the SDK............................................................................................................................................14 Application Signing.................................................................................................................................... 14 VrPlatform Entitlement Checks.................................................................................................................. 14 Device Setup....................................................................................................................................................15 Setting up your System to Detect your Android Device...........................................................................16 Configuring your Android Device for Debugging..................................................................................... 17 Android Development Environment Setup..................................................................................................... 18 Android Development Software Setup for Windows................................................................................ 18 Android Development Software Setup for OS X...................................................................................... 24 Android Development Software Setup for Linux (Ubuntu 14.04).............................................................. 31 Troubleshooting............................................................................................................................................... 32 Device Troubleshooting............................................................................................................................. 32 Environment Troubleshooting.................................................................................................................... 34

Unity Development Guide................................................................................. 37 Introduction...................................................................................................................................................... 37 Requirements.............................................................................................................................................. 37 Installation...................................................................................................................................................38 Preparing for Development: PC SDK........................................................................................................ 38 Preparing for Development: Mobile SDK..................................................................................................39 Getting Started................................................................................................................................................ 39 Importing the Unity Integration................................................................................................................. 39 Importing Sample Applications..................................................................................................................40 Adding VR to an Existing Unity Project.....................................................................................................40 A Detailed Look at the Unity Integration........................................................................................................41 Contents..................................................................................................................................................... 41 Prefabs........................................................................................................................................................ 42 Unity Components......................................................................................................................................43 Oculus Mobile SDKExamples.....................................................................................................................46 Control Layout............................................................................................................................................49 Configuring for Build....................................................................................................................................... 50 PC Build Target: Microsoft Windows and Mac OS X................................................................................ 50 Mobile Build Target: Android.................................................................................................................... 52 Sample Unity Application Demos................................................................................................................... 56 Running Pre-Built demos: PC.....................................................................................................................56 Running Pre-Built demos: Mobile.............................................................................................................. 57 Pre-Built Demo Controls............................................................................................................................ 57 Migrating From Earlier Versions......................................................................................................................58 Known Issues and Troubleshooting................................................................................................................ 60

4 | Contents | Mobile

PC............................................................................................................................................................... 61 Mobile.........................................................................................................................................................61 Contact Information....................................................................................................................................62 Mobile Unity Performance Best Practices....................................................................................................... 62 Introduction................................................................................................................................................ 62 General CPU Optimizations....................................................................................................................... 62 Rendering Optimization............................................................................................................................. 63 Best Practices............................................................................................................................................. 65 Design Considerations............................................................................................................................... 65 Unity Profiling Tools................................................................................................................................... 66

Native Development Guide...............................................................................69 Introduction...................................................................................................................................................... 69 Native Samples................................................................................................................................................ 69 SDK Sample Overview............................................................................................................................... 69 Importing Native Samples in Eclipse.........................................................................................................69 Native Source Code........................................................................................................................................ 71 Overview..................................................................................................................................................... 72 Native User Interface..................................................................................................................................74 Input Handling............................................................................................................................................75 Building New Native Applications.................................................................................................................. 76 Template Project........................................................................................................................................ 76 Integration.................................................................................................................................................. 77 Android Manifest Settings..........................................................................................................................77 Native SoundManager..................................................................................................................................... 77 Overview..................................................................................................................................................... 77 Implementation details...............................................................................................................................78

Mobile VR Application Development................................................................ 79 Introduction to Mobile VR Design.................................................................................................................. 79 Performance Advice for Early Titles...........................................................................................................79 Frame Rate................................................................................................................................................. 80 Scenes.........................................................................................................................................................80 Resolution................................................................................................................................................... 81 Hardware Details..............................................................................................................................................81 Power Management.........................................................................................................................................82 Fixed Clock Level API................................................................................................................................ 82 Power Management and Performance...................................................................................................... 83 Power State Notification and Mitigation Strategy..................................................................................... 84 Runtime Threads.............................................................................................................................................. 84 Front Buffer Rendering.................................................................................................................................... 85 User Interface Guidelines................................................................................................................................ 85 In a Word: Stereoscopic!........................................................................................................................... 85 The Infinity Problem................................................................................................................................... 86 Depth In-Depth.......................................................................................................................................... 86 Gazing Into Virtual Reality..........................................................................................................................87 Universal Menu................................................................................................................................................ 87 Reserved User Interactions.........................................................................................................................88 Universal Menu........................................................................................................................................... 88 TimeWarp.........................................................................................................................................................89 TimeWarp Minimum Vsyncs....................................................................................................................... 90 Consequences of not rendering at 60 FPS............................................................................................... 90 TimeWarp Chromatic Aberration Correction............................................................................................. 91 TimeWarp Debug Graph............................................................................................................................91

Mobile | Contents | 5

Media and Assets.............................................................................................. 93 Mobile VR Media Overview............................................................................................................................ 93 Introduction................................................................................................................................................ 93 Panoramic Stills...........................................................................................................................................93 Panoramic Videos....................................................................................................................................... 93 Movies on Screens..................................................................................................................................... 94 Media Locations......................................................................................................................................... 96 Oculus Media Applications..............................................................................................................................96 Native VR Media Applications................................................................................................................... 96 Oculus Cinema Theater Creation....................................................................................................................98 How to Create and Compile a Movie Theater FBX.................................................................................. 98 Detailed Instructions...................................................................................................................................99 FBX Converter................................................................................................................................................104 Overview................................................................................................................................................... 104 Command-Line Interface.......................................................................................................................... 107 Optimization............................................................................................................................................. 109

Testing and Troubleshooting...........................................................................111 Android Debugging.......................................................................................................................................111 Adb........................................................................................................................................................... 111 Logcat....................................................................................................................................................... 112 Application Performance Analysis................................................................................................................. 114 Performance Analysis............................................................................................................................... 114 Application Performance.......................................................................................................................... 114 Rendering Performance: Tracer for OpenGL ES..................................................................................... 116

Revision............................................................................................................ 120

6 | Introduction to Mobile VR Development | Mobile

Introduction to Mobile VR Development Welcome to mobile application development for Gear VR! This section will help you get oriented to the world of VR development before you jump in.

Getting Started To become acquainted with the Oculus VR environment and with using Gear VR, we recommend beginning with the Samsung Gear VR User Manual, which covers topics including: • • • •

Health and Safety Device Features and Functionality Connecting the Headset Navigation and App Selection

Ready to start developing? The Device and Environment Setup Guide will lead through setting up and configuring your development environment. If you are primarily interested in developing a Native Mobile VR Application, focus on the Native Development Guide. If you are primarily interested in developing a Unity Mobile VR Application, focus on the Unity Integration Guide and Unity Performance Best Practices documents. We recommend that all developers review the Mobile VR Application Development guide for performance guidelines and best practices. For both Native and Unity development, we also recommend: • Android Debugging • Performance Analysis and Performance Guidelines • Design Guidelines You will find Gear VR submission information and other helpful documents at https://developer.oculus.com. Thank you for joining us at the forefront of Virtual Reality!

System and Hardware Requirements Please begin by making sure that you are using supported hardware and devices for this release of the Oculus Mobile SDK v0.4. Operating System Requirements The Oculus Mobile SDK currently supports Windows 7, Mac OS X and Linux.

Mobile | Introduction to Mobile VR Development | 7

Minimum System Requirements The following computer system requirements for the Oculus Mobile SDK are based on the Android SDK system requirements: • Windows 7 • Mac OS: 10.6+ (x86 only) • Linux: Ubuntu 12.04 LTS • GNU C Library (glibc) 2.7 or later is required • 64-bit distributions capable of running 32-bit applications • 2.0+ GHz processor • 2 GB system RAM Supported Devices • Samsung Note 4 Target Device Requirements • API Level • 19 (Android 4.4.2) • VR Hardware • See "Supported Devices" above. • 3.0 Class 2 Bluetooth gamepad (see below) Bluetooth Gamepad A Bluetooth gamepad (3.0 Class 2) is necessary for testing the sample applications which come with this release. You may use the Samsung El-GP20 gamepad or a Moga Pro. For more information about the Samsung El-GP20, including specifications and key bindings, see the following: http://developer.samsung.com/s-console. Bluetooth Keyboard It is useful (but not required) to have a Bluetooth keyboard during development. The Logitech K810 is known to function well. Note: Please refer to your device product manual for additional information.

SDK Contents Included with this SDK, you will find the following: • • • •

VrLib, the native framework for building high-performance VR Applications. Unity Standalone Integration for adding the VR framework to your Unity project. Example native and Unity Projects with source to provide a basis for creating your own VR applications. Several pre-built sample applications, some implemented in native and some in Unity.

8 | Introduction to Mobile VR Development | Mobile

Sample Applications and Media Note: The sample applications included with the SDK are provided as a convenience for development purposes. Some of these apps also have similar versions downloadable from our app store. Due to the potential for conflict with these versions, we do not recommend running these sample apps on the same device on which you have installed your retail Gear VR Innovator experience. Please take care to secure the retail media content bundled with the SM-R320. It will be difficult if not impossible to replace. Table 1: Sample Native Applications Application

Description A viewer for panoramic stills.

Oculus 360 Photos A viewer for panoramic videos.

Oculus 360 Videos Plays 2D and 3D movies in a virtual movie theatre.

Oculus Cinema Loads a scene which can be navigated using a gamepad.

VrScene Table 2: Sample Unity Applications Application

Description A simple game example in which blocks can be thrown to knock over structures and collect stars.

BlockSplosion

Mobile | Introduction to Mobile VR Development | 9

Application

Description An example app that renders a scene and character from Shadowgun by Madfinger Games.

Shadowgun, by Madfinger Games For the Mobile SDK, we have limited pre-loaded media. Please add your own media by consulting the following table and media creation guidelines for compatibility: Table 3: Sample Media Application

Path for Media on the SD Card

Oculus Cinema - 2D Movie

Movies\ DCIM\ Oculus \Movies\My Videos

Oculus Cinema - 3D Movie

Movies\3D DCIM\3D Oculus\Movies\My Videos \3D

Oculus 360 Video - 360 degree Panoramic video

Oculus\360Videos

Oculus 360 Photo (360 degree static photos)

Oculus\360Photos

Note: non-360 degree photos will not render properly. For more information on media management, see Mobile Media VR Overview.

Contact Questions? Visit our developer support forums at https://developer.oculus.com. Our Support Center can be accessed at https://developer.oculus.com.

10 | 0.4 Release Notes | Mobile

0.4 Release Notes This document provides an overview of new features, improvements, and fixes included in version 0.4 of the Oculus Mobile SDK. 0.4.3.1 Overview of Major Changes This release adds support for Unity 5.0.0p2. Developers using Unity 5 must update to this version, and make sure that they are using the latest patch release from Unity. We would like to highlight the inclusion of the new Mobile Unity Integration with full DK2 support based on the Oculus PC SDK 0.4.4. As this is a significant API refactor, please refer to the Unity Development Guide: Migrating From Earlier Versions section for information on how to upgrade projects built with previous versions of the Mobile Unity Integration. Note: Before installing or integrating this distribution, we strongly recommend that you backup your project before attempting any merge operations. 0.4.3 New Features • Android Manifest • Applications will now be required to specify the following permission to support distortion configuration updates by the system service.

• Note: Always refer to the Oculus Mobile Submission Guidelines for the latest information regarding the submission process. • VrPlatform • Support for entitlement checking with VrPlatform. Integration steps and instructions are included in the Oculus Mobile Developer Guide’s Device and Environment Setup section. • Unity Integration • New Mobile Unity Integration Based on Oculus PC SDK 0.4.4 • Miscellaneous • The Mobile SDK Documentation folder hierarchy has been re-organized into a single document. API Changes • VrLib • • • • •

Localized string updates for the Universal Menu. Improvements to yaw drift correction. Fixed vsync possibly being turned off by the Universal Menu when selecting reorient. Pre-register nativeSetAppInterface to work around a JNI bug where JNI functions are not always linked. Do not allow nativeSurfaceChanged to use a deleted AppLocal in case surfaceDestroyed is executed after onDestroy.

Mobile | 0.4 Release Notes | 11

• Removed resetting the time warp when sensor device information is not populated on application launch. • Improved Passthrough Camera latency by disabling Optical Image Stabilization (Exynos chipset only). • Free EGL sync objects on time warp thread shutdown. Bug Fixes • 360 Videos SDK • Fixed bug where a few 360 videos would not play. • Fixed several UI bugs. • Added extra error handling. • 360 Photos SDK • Fixed several UI bugs. 0.4.2 Overview of Major Changes If you are developing with Unity, we recommend updating to Unity 4.6.1, which contains Android 5.0 – Lollipop support. We would like to highlight the inclusion of the new Mobile Unity Integration with full DK2 support based on the Oculus PC SDK 0.4.4. As this is a significant API refactor, please refer to the Unity Development Guide: Migrating From Earlier Versions section for information on how to upgrade projects built with previous versions of the Mobile Unity Integration. Note: Before installing or integrating this distribution, we strongly recommend that you backup your project before attempting any merge operations. API Changes • VrLib • Universal Menu localization support: English, French, Italian, German, Spanish, Korean. • Move Direct Render out of VrApi and into TimeWarp. • Print battery temperature to logcat. • Fix rendering of TimeWarp Debug Graph. • Unity Integration • Fix for camera height discrepancies between the Editor and Gear VR device. • Moonlight Debug Util class names now prefixed with OVR to prevent namespace pollution. • Provide callback for configuring VR Mode Parms on OVRCameraController; see OVRModeParms.cs for an example. • Native Framework • Fixed bug in which Volume toast is not dismissed if user transitions to Universal Menu while the toast is active. • Allow for app-specific handling when the user selects Reorient in the Universal Menu. • SearchPaths: Now correctly queries Android storage paths. • SearchPaths: Refactored to OvrStoragePaths. • FolderBrowser: Improved load time by removing check for thumbnails in the application package.

12 | 0.4 Release Notes | Mobile

• FolderBrowser: Improved scrolling and swiping physics. FolderBrowser: Added bound back and wrap around effects. • Sample Project Changes • 360 Photos SDK • Fixed bug in which the user could easily close the menu unintentionally when returning from a photo. • Fixed crash that occurred when photos stored in the physical “Favorites” folder were untagged as “Favorites”. • Fixed crash caused by swiping on the “no media found” screen. • 360 Videos SDK • Background star scene now fades to black when starting a video. • Changed corrupted media message to show only filename so it fits in the view. • Fixed rendering artifact that occurred when starting to play a video. 0.4.1 Overview of Major Changes Added support for Android 5.0 (Lollipop) and Unity Free. New Features • Mobile SDK • Added support for Android 5.0 (Lollipop). • Unity • Added Unity Free support for Gear VR developers. 0.4.0 Overview of Major Changes First public release of the Oculus Mobile SDK. New Features • First public release of the Oculus Mobile SDK. API Changes • The Mobile SDK is now using API Level 19. Please make the following change to your manifest file:

Bug Fixes • • • • •

Health and Safety Message no longer required on mount. Lens distortion updated for final Gear VR lenses. Improved Mag Yaw drift correction. Option ability to update distortion file without the need for app rebuild. Changed default font to Clear Sans.

Mobile | 0.4 Release Notes | 13

• Unity vignette rendering updated to match native (slightly increases effective FOV). • Unity volume popup distance to match native. • Fix Gaze Cursor Timer scale.

14 | Device and Environment Setup | Mobile

Device and Environment Setup A guide to setting up your device and environment for mobile VR application development.

Introduction This guide contains detailed instructions for setting up your Android device and development environment. Welcome to the Oculus VR Mobile Software Development Kit! This SDK will demonstrate how to implement high-performance, high-quality and fully-immersive Virtual Reality applications for Samsung Gear VR.

Install the SDK

Begin by installing the mobile SDK archive. The mobile SDK is composed of a compressed archive in .zip format which contains both source and media files: ovr_mobile_sdk_.zip. Once downloaded, extract the .zip file into a directory of your choice (e.g., C:\Oculus\Mobile).

Application Signing

Application signing is a key part of the development process. All mobile VR applications must be signed by an Android digital certificate in order to install and run on an Android device, and they must also be signed with an Oculus Signature File (osig) during development to gain full access to the phone's full VR capabilities. For more information on application signing, see "Create Your Signature Files" in the Oculus Mobile Submission Guidelines.

VrPlatform Entitlement Checks Mobile SDK v0.4.3 and higher include support for entitlement checking with VrPlatform. This feature is typically used to protect applications sold through the store from unauthorized distribution. During an entitlement check, the application's package name is compared with a list of applications that the currently logged-in user is entitled to use. This check is performed invisibly and automatically with the Oculus background service. If the application package name is not found on the user's entitlement list, the application is killed, and Home automatically launches to display an error message. If the check runs into any error, applications are treated as though an entitlement were not found, in order to prevent circumvention. Possible failures in this check are: 1. 2. 3. 4. 5.

No service installed/problem connecting to service Invalid service signature Calling app is neither developer (osig) nor VR signed No user logged in User is not entitled

Mobile | Device and Environment Setup | 15

Note: Entitlement checking may be left enabled during development, as any development build with a valid osig file will automatically skip the check. When Oculus signs your package for release, we will test the integration to confirm that your application's entitlement is verified correctly. Native: Java Copy the vrplatlib.jar library from /sdk/VRPlatform/libs/ into your project's /libs/ directory and add to your project's build path. In your activity's onCreate method, add the following line: OVREntitlementChecker.doAutomatedCheck(this);

Native: C++ Follow the procedure described in the “Native: Java” section above. Every native project must subclass VrActivity. This is usually called MainActivity, so add the entitlement check in the onCreate as with Java. Unity Entitlement checking is enabled by default in Unity. To disable entitlement checking: 1. Select Edit > Project Settings > Player 2. In the PlayerSettings window, select the Android icon and expand the Other Settings tab 3. In the Scripting Define Symbols field, add INHIBIT_ENTITLEMENT_CHECK. Note: disabling entitlement checking is not necessary for development, as it is automatically disabled for any application signed with an osig file. Verifying Entitlement Integration You can verify your integration by checking the logcat output after starting your app. For example: D/OVREntitlementChecker(19779): Package oculussig verified, entitlement check was skipped.

Note: oculussig is the same as osig.

Device Setup This section will provide information on how to setup your supported device and gamepad for running, debugging, and testing your Gear VR application. Please review the Supported Devices above for the list of supported devices for this SDK release. Note: This information is accurate at the time of publication of this document. Unfortunately, we cannot guarantee the consistency or reliability of any of the third-party applications discussed in these pages, nor can we offer support for any of the third-party applications we describe.

16 | Device and Environment Setup | Mobile

Setting up your System to Detect your Android Device

You must set up your system to detect your Android device over USB in order to run, debug, and test your application on an Android device. If the device is not automatically detected by your system when connected over USB, update the drivers manually. More information can be found in the “Using Hardware Devices” section at http:// developer.android.com/tools/device.html.

Windows If you are developing on Windows, you need to install a USB driver for adb. For an installation guide and links to OEM drivers, see the Android OEM USB Drivers document. Samsung Android drivers may be found on their developer site: http://developer.samsung.com/android/toolssdks/Samsung-Android-USB-Driver-for-Windows Windows may automatically detect the correct device and install the appropriate driver when you connect your device to a USB port on your computer. However, if Windows is unable to detect your device, you may still need to update the drivers through the Windows Device Manager, even if your device was automatically detected. Access the Device Manager through the Windows Control Panel. If the device was automatically detected, it will show up under Portable Devices in the Device Manager. Otherwise, look under Other Devices in the Device Manager and select the device to manually update the driver. To verify that the driver successfully recognized the device, open a command prompt and type the command: adb devices

Note: You will need to successfully setup your Android development environment in order to use this command. For more information, see the next section: Android Development Environment Setup If the device does not show up, verify that the device is turned on with enough battery power, and that the driver is installed properly.

Mac OS

If you're developing on Mac OS X, you do not need to install USB drivers. Your Samsung device may display a notification recommending you install Android File Transfer. A handy application for transferring files between OS X and Android.

Linux

If you're developing on Ubuntu Linux, you need to add a udev rules file that contains a USB configuration for each type of device you want to use for development. In the rules file, each device manufacturer is identified by a unique vendor ID, as specified by the ATTR{idVendor} property. For a list of vendor IDs, see USB Vendor IDs. To set up device detection on Ubuntu Linux: 1. Log in as root and create this file: /etc/udev/rules.d/51-android.rules. 2. Use this format to add each vendor to the file: SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", MODE="0666", GROUP="plugdev"

Mobile | Device and Environment Setup | 17

3. Now execute chmod a+r /etc/udev/rules.d/51-android.rules

In this example, the vendor ID is for Samsung. The MODE assignment specifies read/write permissions, and GROUP defines which Unix group owns the device node. Note: The rule syntax may vary slightly depending on your environment. Consult the udev documentation for your system as needed. For an overview of rule syntax, see this guide to writing udev rules.

Configuring your Android Device for Debugging

In order to test and debug applications on your Android device, you will need to enable specific developer options on the device.

Note 4 Developer Options Developer options may be found under:Home -> All Apps -> Settings -> System -> Developer options. Developer options may be hidden by default. If so, you can expose these options with the following steps: 1. Go to Home -> All Apps -> Settings -> System -> About device. 2. Scroll down to Build number. 3. Press Build number 7 times. You should be informed that Developer options has been enabled. Once you have found Developer options, enable the following: USB Debugging: This will allow the tools to install and launch deployed apps over USB. You should see the screen shown on the accompanying figure. Figure 1: Samsung Galaxy S5

Note: If the above screen does not appear, ensure that your system recognizes the device and toggle USB Debugging off then back on. Check Always allow this computer and hit OK. To purge the authorized whitelist for USB Debugging, press Revoke USB debugging authorizations from the Developer options menu and press OK.

18 | Device and Environment Setup | Mobile

Allow mock locations: This will allow you to send mock location information to the device (convenient for apps which use Location Based Services). Verify apps via USB: This will check installed apps from ADB/ADT for harmful behavior.

Display Options The following display options are found in: Home -> Apps -> Settings -> Sound and Display Lock screen/Screen Security/Screen lock: When set to None the Home screen is instantly available, without swipe or password. Useful to quickly get in and out of the phone. Display/Screen timeout: Set the time to your desired duration. Useful if you are not actively accessing the device but wish to keep the screen awake longer than the default 30 seconds. See Android Debugging for more information.

Android Development Environment Setup This section describes setup and configuration of the Android Development Environment necessary for building Oculus Android mobile applications. Note: As of February 2015, Android has officially deprecated the Eclipse-based SDK in favor of the Android Studio system. We are in the process of updating our developer instructions for integration with their new IDE. Unity that is complete, we recommend that developers continue to download and install the tools and versions referenced in this guide. When this guide was published, they were still available from download at the specified addresses. Please check back for updates.

Android Development Software Setup for Windows In order to develop Android applications, you must have the following software installed on your system: 1. 2. 3. 4.

Java Development Kit (JDK) Android Development Tools (ADT) Bundle Android Native Development Kit (NDK) Apache Ant

Java Development Kit (JDK)

The Java Development Kit is a prerequisite for the Android Eclipse IDE (which comes with the ADT Bundle) as well as Apache Ant. The latest version which has been tested with this release is JDK 8u11. You may download the appropriate version for your OS from the following location: http://www.oracle.com/technetwork/java/javase/downloads/ java-archive-javase8-2177648.html Note: As of October 2014, the Windows x86 version of the JDK appears to be incompatible with Eclipse and cannot be used. Once downloaded and installed, add the environment variable JAVA_HOME, which should be set to the JDK install location, e.g.: • C:\Program Files\Java\jdk1.8.0_11 if you have installed the x64 version, or • C:\Program Files (x86)\Java\jdk1.8.0_11 if you have installed the x86 version.

Mobile | Device and Environment Setup | 19

Make sure your JAVA_HOME variable does not include quotation marks. If you use set from the command line, the correct syntax is: set JAVA_HOME=C:\Program Files (x86)\Java\jdk1.8.0_11

Do not use quotes with the set command, even though the path has a space in it. Also, please verify your installation path - this example is based on the default installation of Java SE 8u11.

Android Development Tools Bundle The Android Development Tools (ADT) Bundle includes everything needed to begin developing Java Android Apps: • • • • •

Android SDK Tools Android Platform Tools Latest Android Platform Eclipse with integrated ADT Plugin Latest System Image for Emulator

The ADT bundle comes in either a 32-bit or 64-bit version. This must match the JDK option you selected above. Download the appropriate version of the ADT Bundle at the following locations: • 32-bit .zip download • 64-bit .zip download Once downloaded, unpack the zip file and save to your Android development folder, e.g.: C:\Dev\Android\adt-bundle-\ Add the ADT SDK tools and platform-tools to your PATH, e.g. • C:\Dev\Android\android_adt_bundle_20140702\sdk\tools • C:\Dev\Android\android_adt_bundle_20140702\sdk\platform-tools Add the environment variable ANDROID_HOME which should be set to your Android SDK location, e.g.: • C:\Dev\Android\android_adt_bundle_20140702\sdk set ANDROID_HOME=C:\Dev\Android\adt-bundle-windows-x86-20140702\sdk

Installing Additional Packages and Tools

The Android SDK does not include everything you will need for development by default. You will need to download additional packages via the SDK Manager before you begin. Note: Before launching the SDK Manager, make sure you have installed the JDK as outlined in Section IV.1.1 of this document. SDK Manager may fail to launch if it has not been installed. 1. Launch the Android SDK Manager located at: C:/Dev/Android/adt-bundle-/SDKManager.exe You may also launch it via Eclipse by selecting the SDK Manager in the toolbar. 2. Under the Tools section within Packages, select the following (if they are unselected): • Android SDK Tools Rev. 23.0.5 • Android SDK Platform-tools Rev. 21 • Android SDK Build-tools Rev. 20

20 | Device and Environment Setup | Mobile

3. Our current Android build target is Android 4.4.2 (API 19). Select at least the following under the API 19 section: • SDK Platform • ARM EABI v7a System Image Additionally, you may also wish to install Sources for Android SDK, which is invaluable for dealing with the Android API. 4. Finally, under Extras at the bottom, select the following: • Android Support Library Rev. 21.0.1

Mobile | Device and Environment Setup | 21

• Google USB Driver Rev. 11 Figure 2: Android SDK Manager

5. Open Android 4.4.2 (API 19) and select the items for SDK Platform and ARM EABI v7a System Image. Note that Oculus Mobile SDK projects use API level 19.

22 | Device and Environment Setup | Mobile

6. Click Install X Packages, where X is the number of selected packages (it may vary based on what needs to be updated). 7. On the next dialog, choose Accept License. 8. Click Install to install and update packages. You may install additional packages above API 19 if you wish. Android SDK Tools 23.0.2, Android SDK Platform-tools 20 and Android SDK Build-tools 20 have all been verified to work correctly with the SDK. If you have problems compiling after an update, close the Android SDK Manager and re-open it to make sure you have everything required for the installed packages. In some cases you may get the warning “Could not load definitions from resource emma_ant.properties”. This is usually due to missing components in the install or improper file permissions. If the problem persists after verifying everything is up to date, try deleting the local.properties files from your project folders and updating them in each project folder with the command: android update project -p .

and then rebuild.

Verify Eclipse Configuration

Verify that Eclipse has the proper location for your Android Development Tools. Launch the Eclipse executable which came with the ADT bundle, e.g.: C:\Dev\Android \android_adt_bundle_20140702\eclipse\eclipse.exe. 1. In the Eclipse menu go to Window -> Preferences -> Android. 2. The Android Preferences SDK Location should be set to the location where you installed the ADT bundle SDK in the previous section, e.g.: C:\Dev\Android\android_adt_bundle_20140702\sdk.

Android Native Development Kit

The Android Native Development Kit (NDK) is a toolset that allows you to implement parts of your app using native-code languages such as C and C++. It is used extensively by the sample applications which come with this release. 1. Download the latest version of NDK at the following location:https://developer.android.com/tools/sdk/ndk/ index.html 2. Once downloaded, install NDK to your Android development folder, e.g.: C:\Dev\Android\android-ndk-r10c \. 3. Add the NDK location to your PATH, e.g.: C:\Dev\Android\android-ndk-r10c\. 4. Add the environment variable ANDROID_NDK which should be set to your Android NDK location, e.g.: C: \Dev\Android\android-ndk-r10c. set ANDROID_NDK=C:\Dev\Android\android-ndk-r10c

Configure Eclipse for NDK Usage 1. Start Eclipse from the location it was installed to, e.g.: C:\Dev\Android\adt-bundle-windowsx86_64-20140702\eclipse\eclipse.exe. 2. Download and install the Eclipse ADT Plugin. 1. In the Eclipse menu go to: Help -> Install New Software. 2. Click Add in the top-right corner. 3. In the Add Repository dialog that appears, enter “ADT Plugin” for the Name and the following URL: https://dl-ssl.google.com/android/eclipse

Mobile | Device and Environment Setup | 23

4. Click OK. 5. 6. 7. 8.

In the Available Software dialog, select the checkbox for Developer Tools and click Next. Click OK. In the next window, you’ll see a list of tools to be download. Click Next. Read and accept the license agreements, then click Finish. Click OK if you get any prompts regarding the security and authenticity of the software. 9. When the installation completes, restart Eclipse. 3. Configure the NDK path: 1. In the Eclipse menu go to: Window -> Preferences -> Android. 2. Under Android select NDK. 3. Set the NDK Location field to the directory where the NDK is installed. Figure 3: Android NDK

If the NDK option under the Android section is missing, something went wrong with the Eclipse ADT Plugin installation. Full instructions and troubleshooting information may be found here: http:// developer.android.com/sdk/installing/installing-adt.html#Troubleshooting

Apache Ant

Apache Ant is a Java library and command-line build system. It provides a number of built-in tasks which simplify building Java projects. The Apache Ant project is part of the Apache Software Foundation. The latest version which has been tested with this release is Apache Ant 1.9.3 and is available for download at the following location: http://ant.apache.org/bindownload.cgi Note: The Ant download page is explicit about verifying the Ant binary, but this is not strictly necessary for using Ant or for getting Android development up and running. Once downloaded, unpack the zip file and save to your Android development folder, e.g.: C:/Dev/Android/ apache-ant-1.9.3.

24 | Device and Environment Setup | Mobile

Next, add the Ant bin folder to your PATH, e.g.: C:\Dev\Android\apache-ant-1.9.3\bin. For more information on using Ant to automate building Android Apps, see: http:// www.androidengineer.com/2010/06/using-ant-to-automate-building-android.html

Android Development Software Setup for OS X In order to develop Android applications, you must have the following software installed on your system: 1. 2. 3. 4.

Xcode Android Development Tools (ADT) Bundle Android Native Development Kit (NDK) Apache Ant

Xcode

Before installing any Android development tools, you must install Xcode. Once Xcode is installed, some of the following steps (such as installing Apache Ant or the JDK) may be unnecessary - some versions of OS X (10.5 and higher) include Apache Ant, and some do not. On Mavericks 10.9, Ant does not appear to be installed by default or included with Xcode 5.0.2.

Java Development Kit

The Java Development Kit (JDK 8) is a prerequisite for the Android Eclipse IDE (included with the ADT Bundle) as well as Apache Ant. Install the JDK if it is not already present on your system. If you already installed Xcode, this step may be unnecessary. The latest version tested with this release is JDK 8 - it may be downloaded at the following location: http:// www.oracle.com/technetwork/java/javase/downloads/java-archive-javase8-2177648.html.

Android Development Tools Bundle

The Android Development Tools ADT Bundle includes almost everything needed to begin developing Android Apps. The ADT Bundle includes: • Android SDK Tools • Android Platform Tools • Latest Android Platform • Eclipse with integrated ADT Plugin • Latest System Image for Emulator Note: The tilde character followed by a forward slash (~/) is shorthand for the current user’s home folder. It is used throughout this section. 1. In your home folder, create a new folder named “dev”. To get to home folder in OS X, open Finder and press CMD+Shift+H. 2. Download the ADT package at http://dl.google.com/android/adt/adt-bundle-mac-x86_64-20140702.zip. 3. Once downloaded, unzip the ADT archive (if necessary) and save to your “dev” folder.

Mobile | Device and Environment Setup | 25

4. Browse to ~/dev/adt-bundle-/eclipse and double-click the Eclipse icon. You may receive a warning like the following: Figure 4: Apple Safari

Note: Please refer to Apple’s knowledge base regarding this security feature and safeguards for apps downloaded and installed from the internet. 5. To remedy this, right click the Eclipse icon and choose Open. You will get a warning again, but it will now present an Open option: Figure 5: Apple Safari

6. Select Open to start Eclipse. If you get a message that Eclipse needs JRE 6 in order to run, allow it to download and install JRE 6. Next, you should see a window asking you to select your workspace: Figure 6: Eclipse

26 | Device and Environment Setup | Mobile

7. Select Browse and locate or create the directory for your workspace: Figure 7: OS X Finder

8. If you plan to always use this same workspace, you can select the checkbox labeled Use this as the default and do not ask again. Choose OK.

Installing Additional Packages and Tools

The Android SDK does not include everything you will need for development by default. You will need to download additional packages via the SDK Manager before you begin. In Eclipse go to Window -> Android SDK Manager to open a window similar to the following: Figure 8: Android SDK Manager

1. Note that some packages are already selected for installation by default. Leave these projects selected.

Mobile | Device and Environment Setup | 27

2. If not already selected under Tools, select Android SDK Tools, Android SDK Platform-tools, and Android SDK Build-tools. 3. Open Android 4.4.2 (API 19) and select the items for SDK Platform and ARM EABI v7a System Image under it. 4. Click Install X Packages, where X is the number of selected packages (it may vary based on what needs to be updated). 5. On the next dialog, choose Accept License. 6. Click Install to install and update packages. You may install additional packages above API 19 if you wish. Android SDK Tools 23.0.2, Android SDK Platform-tools 20 and Android SDK Build-tools 20 have all been verified to work correctly with the SDK.

Android Native Development Kit

The 2.4 Android Native Development Kit (NDK) is a toolset that allows you to implement parts of your app using native-code languages such as C and C++. It is used extensively by the sample applications which come with this release. The latest version which has been tested with this release is NDK 10 - it is available for download at the following location: https://developer.android.com/tools/sdk/ndk/index.html. Once downloaded, extract the NDK to your home/dev folder (~/dev). Your dev folder should look something like the following: Figure 9: OS X Finder

Note that the ADT bundle and the NDK are extracted into their own folders within the Dev folder (in this case, folders that were in the root of their archive). The names of the folders, where the ADT bundle and the NDK reside, are not vitally important. As long as they are in separate folders and are not extracted directly into the Dev folder, any conflict between the two packages can be avoided. It is recommended you use the above naming scheme so that there is no question which version of the ADT bundle and the NDK are installed. You can read more about installation and use of the NDK here: http://developer.android.com/tools/sdk/ndk/ index.html#installing.

Configure Eclipse for NDK Usage 1. Launch Eclipse and go to the ADT -> Preferences window.

28 | Device and Environment Setup | Mobile

2. Under Android, verify that Eclipse knows the location of the Android Development Tools. If the NDK option is missing in the Preferences -> Android section, update the Eclipse ADT Plugin as follows. 1. Download and install the Eclipse ADT Plugin. a. In the Eclipse menu go to: Help->Install New Software. b. Click Add in the top-right corner. c. In the Add Repository dialog that appears, enter “ADT Plugin” for the Name and the following URL: https://dl-ssl.google.com/android/eclipse d. Click OK. e. f. g. h.

In the Available Software dialog, select the checkbox for Developer Tools and click Next. Click OK. In the next window, you’ll see a list of tools to be download. Click Next. Read and accept the license agreements, then click Finish. Click OK if you get any prompts regarding the security and authenticity of the software. i. When the installation completes, restart Eclipse. 2. Configure the NDK path. a. In the Eclipse menu go to: Window -> Preferences -> Android. b. Under Android select NDK. c. Set the NDK Location field to the directory where the NDK is installed. Figure 10: Eclipse

Mobile | Device and Environment Setup | 29

3. Under Android -> NDK set the NDK folder to the location where you installed the NDK: Figure 11: Eclipse

4. To set environment variables specifying the locations of Android SDK and NDK on your system, and to add Android tools to your global path: 1. Launch a terminal. 2. At the prompt type the following three lines: echo ‘export echo ‘export echo ‘export ANDROID_NDK’

ANDROID_HOME=~/dev/adt-bundle-mac-x86_64-20140702/sdk’ >> ~/.profile ANDROID_NDK=~/dev/android-ndk-r9c’ >> ~/.profile PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools:$ >> ~/.profile

5. To verify that the Android NDK environment is set up correctly, launch a new terminal and go to the samples/hello-jni folder in the Android NDK. Execute the command ndk-build, which will compile the sample hello-jni application if everything is set up correctly.

Apache Ant

Apache Ant is a Java library and command-line build system. It provides a number of built-in tasks which simplify building Java projects. The Apache Ant project is part of the Apache Software Foundation. 1. Download Apache Ant here: http://ant.apache.org/bindownload.cgi. The latest version which has been tested with this release is Apache Ant 1.9.3. If you have already installed Xcode you may be able to skip this step. 2. Once downloaded, unzip Ant (or copy/move it if your web browser auto-expands .zip files for you) into your Dev folder alongside the ADT bundle and the NDK. As with the other packages, Ant should be in its own folder within Dev. 3. Set environment variables to specify the locations of JRE and ADT on your system, and add Ant to your path.

30 | Device and Environment Setup | Mobile

1. Launch a terminal 2. Type the following three lines at the prompt: echo ‘export ANT_HOME=~/dev/apache-ant-1.9.3’ >> ~/.profile echo ‘export JAVA_HOME=$(/usr/libexec/java_home)’ >>~/.profile echo 'export PATH="$PATH":~/dev/apache-ant-1.9.3/bin' >> ~/.profile

For additional information about the JAVA_HOME folder and how to determine its location, see: • http://stackoverflow.com/questions/18144660/what-is-path-of-jdk-on-mac • http://www.mkyong.com/java/how-to-set-java_home-environment-variable-on-mac-os-x/ 4. Verify the $PATH variable and *_HOME variables are set correctly. 1. Launch a new terminal window (from Terminal, press Cmd+N). BE SURE to do this from a new Terminal window. The original Terminal window where you set the environment variables will not have an updated version of the environment variables, because it hasn’t re-run ~/.profile. 2. At the prompt type: echo $PATH

3. You should see the full path with your Ant bin folder at the end. 4. At the same terminal window prompt, type: echo $ANT_HOME

5. Verify the Ant home path is the folder you installed it to. This particular path should NOT have /bin on the end. 6. To ensure the Ant binaries are accessible through the path, type ant -version 7. You should see the Ant version information output as in the screen capture below. If you receive any errors, verify that the paths are all correct. If you have to correct anything, you can edit the ~/.profile file from Terminal using the following command: sudo nano ~/.profile

You should see something like the following screen where you can use the arrow keys to navigate the file and edit text:

When you are finished editing, hit Ctrl+X to save, answer Y to overwrite and Enter to select the current file.

Mobile | Device and Environment Setup | 31

Android Development Software Setup for Linux (Ubuntu 14.04) In order to develop Android applications, you must have the following software installed on your system: 1. Java Development Kit (JDK) 2. Android Software Development Kit (SDK) 3. Android Native Development Kit (NDK)

Java Development Kit Installing the Java Development Kit (JDK) with apt-get is very straightforward. Just type the following into a console: sudo apt-get update sudo apt-get install default-jdk

Android SDK 1. Download the SDK (ADT bundle) from http://developer.android.com/sdk/index.html. 2. Unpack the ZIP file (adt-bundle-linux.zip) and save it to ~/android-sdk 3. Run ~/android-sdk/tools/android Figure 12: Android SDK Manager

1. Note that some packages are already selected for installation by default. Leave these projects selected. 2. Check Android 4.4.2 (API 19).

32 | Device and Environment Setup | Mobile

3. Click the Install X Packages button, where X is the number of selected packages (it may vary based on what needs to be updated). 4. On the next dialog, choose Accept License. 5. Click Install to install and update packages. 6. Some examples may use an older API version than 19. You may need to download other API versions if you have trouble building a particular project. 4. Edit your ~/.bashrc and put this at the top of the file: export PATH=${PATH}:~/android-sdk/tools export PATH=${PATH}:~/android-sdk/platform-tools

Android NDK 1. Download the Linux NDK from https://developer.android.com/tools/sdk/ndk/index.html#download. 2. Unpack the .tar.bz2 to ~/ndk.

Troubleshooting Troubleshooting your device and environment.

Device Troubleshooting Troubleshooting your Samsung device.

View is tilted If the headset view is tilted to the left or right, there is probably an issue with sensor calibration. Take off the headset and place it face down on a flat surface for around 5 seconds to prompt the device to reorient the sensors. When you put the device back on your head, the view should be level.

Mobile | Device and Environment Setup | 33

Device not (or no longer) recognized Even if a device worked fine previously, it may enter a state in which it is no longer recognized. When using Windows you may get the following dialog: Figure 13: Windows 7

In most cases, rebooting the device should be sufficient. Windows appears to sometimes auto-update or auto-rollback the correct Samsung USB driver when the phone is reconnected. If this occurs, you should see a Windows notification that it is installing a driver when you connect your phone via USB. Should this happen, reinstall the correct driver.

Device regularly reconnects The device may enter a state in which it reconnects regularly, or in the middle of sessions. In Eclipse you may get the following message: [

Life Enjoy

" Life is not a problem to be solved but a reality to be experienced! "

Get in touch

Social

© Copyright 2013 - 2019 DOKUMENTIX.COM - All rights reserved.