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...

2 downloads 50 Views 8MB Size

Recommend Documents


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
As this is a significant API refactor, please refer to the Unity Development Guide: ... Menu localization support: English, French, Italian, German, Spanish, Korean. ..... Note: As of October 2014, the Windows x86 version of the JDK appears to be ...

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.6.2.0

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 the Mobile SDK.......................................................................... 5 Getting Started.................................................................................................................................................. 5 System and Hardware Requirements................................................................................................................ 5 Application Signing............................................................................................................................................6 SDK Contents.................................................................................................................................................... 7

0.6 Release Notes..............................................................................................10 Mobile SDK Setup Guide.................................................................................. 17 Device Setup....................................................................................................................................................17 Setting up your System to Detect your Android Device...........................................................................17 Configuring your Android Device for Debugging..................................................................................... 18 Android Development Environment Setup..................................................................................................... 19 Android Development Software Setup for Windows................................................................................ 19 Android Development Software Setup for OS X...................................................................................... 25 Troubleshooting............................................................................................................................................... 31 Device Troubleshooting............................................................................................................................. 31 Environment Troubleshooting.................................................................................................................... 32

Mobile VR Application Development................................................................ 35 Introduction to Mobile VR Design.................................................................................................................. 35 Performance Advice for Early Titles...........................................................................................................35 Frame Rate................................................................................................................................................. 36 Scenes.........................................................................................................................................................36 Resolution................................................................................................................................................... 37 Hardware Details..............................................................................................................................................37 Universal Menu................................................................................................................................................ 38 Reserved User Interactions.........................................................................................................................38 Implementation Overview.......................................................................................................................... 39 Runtime Threads.............................................................................................................................................. 39 Power Management.........................................................................................................................................40 Fixed Clock Level API................................................................................................................................ 40 Power Management and Performance...................................................................................................... 41 Power State Notification and Mitigation Strategy..................................................................................... 42 Front Buffer Rendering.................................................................................................................................... 42 TimeWarp.........................................................................................................................................................43 TimeWarp Minimum Vsyncs....................................................................................................................... 43 Consequences of not rendering at 60 FPS............................................................................................... 44 TimeWarp Debug Graph............................................................................................................................45 User Interface Guidelines................................................................................................................................ 46 In a Word: Stereoscopic!........................................................................................................................... 46 The Infinity Problem................................................................................................................................... 46 Depth In-Depth.......................................................................................................................................... 46 Gazing Into Virtual Reality..........................................................................................................................47

Media and Assets.............................................................................................. 49 Mobile VR Media Overview............................................................................................................................ 49 Panoramic Stills...........................................................................................................................................49 Panoramic Videos....................................................................................................................................... 49

4 | Contents | Mobile

Media Locations......................................................................................................................................... 50 Movies on Screens..................................................................................................................................... 50 Native VR Media Applications.........................................................................................................................52 Oculus Cinema Theater Creation....................................................................................................................54 Detailed Instructions...................................................................................................................................54 FBX Converter..................................................................................................................................................60 Overview..................................................................................................................................................... 60 Command-Line Interface............................................................................................................................ 63 Optimization............................................................................................................................................... 65

Native Development Guide...............................................................................67 Native Source Code........................................................................................................................................ 67 Overview..................................................................................................................................................... 67 Native User Interface..................................................................................................................................68 Input Handling............................................................................................................................................68 Importing the SDK into an Existing Project in Eclipse....................................................................................69 Creating New Native Applications..................................................................................................................72 Template Project Using the Application Framework................................................................................. 72 Integration with Third-Party Engines..........................................................................................................73 Android Manifest Settings..........................................................................................................................73 Running an Application on Device from Eclipse............................................................................................ 74 Native Samples................................................................................................................................................ 74 SDK Sample Overview............................................................................................................................... 74 Importing Native Samples in Eclipse.........................................................................................................76 Native SoundEffectContext............................................................................................................................. 77 Mobile Native SDK Migration......................................................................................................................... 78 Migrating to Mobile SDK 0.6.2.0...............................................................................................................78 Migrating to Mobile SDK 0.6.1.0...............................................................................................................80 Migrating to Mobile SDK 0.6.0..................................................................................................................82

Testing and Troubleshooting.............................................................................89 Oculus Testing Tools and Procedures............................................................................................................ 89 Developer Mode: Running Apps Outside of the Gear VR Headset..........................................................89 VrCapture and Oculus Remote Monitor.................................................................................................... 89 Local Preferences..................................................................................................................................... 103 Android Debugging.......................................................................................................................................104 Adb........................................................................................................................................................... 104 Logcat....................................................................................................................................................... 106 Application Performance Analysis................................................................................................................. 107 Basic Performance Stats through Logcat.................................................................................................107 SysTrace.................................................................................................................................................... 108 NDK Profiler..............................................................................................................................................109 Rendering Performance: Tracer for OpenGL ES..................................................................................... 110

Previous Release Notes................................................................................... 113 0.6 Release Notes..........................................................................................................................................113 0.5 Release Notes..........................................................................................................................................119 0.4 Release Notes..........................................................................................................................................122

Mobile | Introduction to the Mobile SDK | 5

Introduction to the Mobile SDK Welcome to mobile application development for Gear VR! This guide provides an overview of the SDK contents and details the requirements for development.

Getting Started Ready to start developing? The Mobile SDK Setup Guide is a one-time guide to preparing and configuring your development environment. We have compiled recommendations for developing, debugging, and analyzing VR applications that we recommend to all developers: • Mobile VR Application Development Guide • Android Debugging • Performance Analysis Unity Developers Once you have completed the setup process described by the Setup Guide, focus on our Utilities for Unity documentation (Unity 5.1+) or Unity Legacy Integration documentation (Unity 4.6+), available on our documentation site: https://developer.oculus.com/documentation/ Native Developers Once you have completed the setup process described by the Setup Guide, focus on the Native Development Guide. Application Submission For information on preparing to submit your mobile VR application to Oculus for distribution through the Oculus Store, see our Publishing Guide. Thank you for joining us at the forefront of virtual reality! Questions? Visit our developer support forums at https://developer.oculus.com. Our Support Center can be accessed at https://support.oculus.com/.

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.

6 | Introduction to the Mobile SDK | Mobile

Operating System Requirements The Oculus Mobile SDK currently supports the following operating systems: • Windows 7 or 8 • Mac OS: 10.6+ (x86 only) Minimum System Requirements The following computer system requirements for the Oculus Mobile SDK are based on the Android SDK system requirements: • 2.0+ GHz processor • 2 GB system RAM Supported VR Headsets • Samsung Gear VR Supported Devices • Samsung Note 4 • Samsung Galaxy S6 • Samsung Galaxy S6 Edge Target Device Requirements • API Level 19 (Android 4.4.2) or later Accessories 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, or another compatible gamepad. For more information about the Samsung El-GP20, including specifications and key bindings, see the following: http://developer.samsung.com/s-console. Bluetooth Keyboard (optional) It is useful (but not required) to have a Bluetooth keyboard during development. The Logitech K810 is known to function well.

Application Signing Oculus mobile apps require two distinct signatures at different stages of development. • Oculus Signature File (required during development, remove for submission) • Android Application Signature (required for submission) Oculus Signature File (osig) During development, your application must be signed with an Oculus-issued Oculus Signature File, or osig. This signature comes in the form of a file that you include in your application in order to access protected lowlevel VR functionality on your mobile device. Each signature file is tied to a specific device, so you will need

Mobile | Introduction to the Mobile SDK | 7

to generate osig files for each device that you use for development. When your application is submitted and approved, Oculus will modify the APK so that it can be used on all devices. Please see our osig self-service portal for more information and instructions on how to request an osig for development: https://developer.oculus.com/tools/osig/ Android Application Signing Android uses a digital certificate (also called a keystore) to cryptographically validate the identity of application authors. All Android applications must be digitally signed with such a certificate in order to be installed and run on an Android device. All developers must create their own unique digital signature and sign their applications before submitting them to Oculus for approval. For more information and instructions, please see Android's "Signing your Applications" documentation: http://developer.android.com/tools/publishing/app-signing.html Make sure to save the certificate file you use to sign your application. Every subsequent update to your application must be signed with the same certificate file, or it will fail. Note: Your application must be signed by an Android certificate before you submit it.

Android Application Signing and Unity Unity automatically signs Android applications with a temporary debug certificate by default. Before building your final release build, create a new Android keystore and assign it with the Use Existing Keystore option, found in Edit > Project Settings > Player > Publishing Options. For more information, see the “Android” section of Unity's documentation here: http://docs.unity3d.com/Manual/class-PlayerSettings.html.

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

Native framework for building high-performance VR Applications. Example native and Unity Projects with source to provide a model for creating your own VR applications. Pre-built sample applications, some implemented in native and some in Unity. Tools to assist with native development.

Unity Resources The Oculus Utilities for Unity and Legacy Integration packages are available for download separately at our downloads page here: https://developer.oculus.com/downloads. The Unity samples included with the Mobile SDK are compatible with the Oculus Legacy Integration package only, for use with Unity 4. If you are using Unity’s first-party VR support in Unity 5.1 or later, you will find samples compatible with our Utilities package available for download, also at our downloads page. For more information on the Oculus Mobile SDK Example contents, please see our Unity documentation. Sample Applications and Media Note: The sample applications included with the SDK are provided as a convenience for development purposes. Some of these apps are similar to apps available for download from the Oculus 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. If you are using the

8 | Introduction to the Mobile SDK | Mobile

Samsung Note 4, 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 A sample scene of colorful cubes.

VR Cube World Table 2: Sample Unity Applications Application

Description A simple game example in which blocks can be thrown to knock over structures and collect stars. (source and APK, currently Unity 4 only)

BlockSplosion

Mobile | Introduction to the Mobile SDK | 9

Application

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

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.

10 | 0.6 Release Notes | Mobile

0.6 Release Notes This document provides an overview of new features, improvements, and fixes included in the latest version of the Oculus Mobile SDK. 0.6.2.0 Overview of Major Changes The 0.6.2.0 version of the Oculus Mobile SDK includes a change to how we link with OpenGL ES. Previous versions of the SDK had a hard link to libGLESv3.so, which is problematic for engines which integrate the VrApi and must support non-VR devices. Beginning with 0.6.2, the mobile SDK dynamically loads all OpenGL ES symbols. The source for the Unity SDKExample MediaSurface Plugin is now provided. The Media Surface Plugin provides a native library which is used with the Android MediaPlayer for hardware decoding of a single video to a texture. Note that the SDKExample MediaSurface Plugin is not intended to be production quality, and is provided for reference purposes. We have made the source available in case you would like to modify it for your use. The source and build files are located at the following SDK path: VrAppSupport/MediaSurfacePlugin. For detailed instructions on updating native projects to this SDK version, see Mobile Native SDK: Migration. New Features • VrApi • Dynamically loads OpenGL ES symbols instead of hard-linking to libGLESv3.so. • VrCapture • Added mode to capture straight to local flash storage instead of waiting for a remote connection. Useful for automated testing, capturing the startup sequence, and working around issues caused by lowbandwidth WiFi networks. API Changes • VrApi • Remove several non-VR android-specific interface calls. • Native Application Framework • VrGUI Library project now contains Java source and resources. • VrAppInterface::DrawEyeView() takes an additional parameter, see Migrating to Mobile SDK 0.6.2 for more information. Bug Fixes • VrApi • Fixed thread affinity failing to be set for the TimeWarp and DeviceManager threads. • Fixed device reset when repeatedly plugging and unplugging the Travel Adapter on the Samsung GALAXY S6. • VrAppFramework • Optimized GazeCursor to render in two draw calls per eye instead of 32. • Fixed GlGeometry BuildGlobe so that equirect center is at -Z (forward).

Mobile | 0.6 Release Notes | 11

0.6.1.0 Overview of Major Changes The 0.6.1.0 version of the Oculus Mobile SDK includes major structural changes to the native VrAppFramework library. Several subsystems that were previously part of VrAppFramework have been moved into individual libraries under the VrAppSupport folder, making the application framework leaner and reducing its focus to handling the Android application lifecycle. LibOVR has now been renamed to LibOVRKernel to better represent its intended functionality and to maintain parity with the PC SDK. The Java activity code has been refactored to remove dependencies on the VrActivity class for applications that do not use VrAppFramework. The SDK Native Samples were updated to a cross-platform friendly structure. Android Library Projects are now found at [ProjectName]/Projects/Android. Changes to Unity Integration The Oculus Unity Integration is no longer bundled with the Mobile SDK and must now be downloaded separately from our Downloads page: https://developer.oculus.com/downloads/ We now provide a Utilities for Unity package for use with Unity’s first-party VR support (available in Unity 5.1+). For legacy project development, we currently offer a legacy Unity Integration package for use with Unity 4.6.7 and later. Please see our Unity documentation for more information. If you are using the Utilities for Unity Package with Unity 5.1+, the SDKExamples are now available for download separately. If you are using the Legacy Unity Integration, update to Oculus Runtime for OS X 0.5.0.1. Before updating your runtime, be sure to run uninstall.app (found in /Applications/Oculus/) to remove your previous installation. New Features • VrApi • Images composited by the time warp are now allocated through the VrApi as “texture swap chains”. • Performance params (CPU/GPU level, thread ids) can now be adjusted every frame through vrapi_SubmitFrame. • adb logcat -s VrApi now reports the thread affinity. • ovr_GetSystemProperty now provides options for querying GpuType, Device external memory, and max fullspeed framebuffer samples, see ovrSystemProperty in VrApi_Types.h • VrCubeWorld • Added example to VrCubeWorld_SurfaceView and VrCubeWorld_NativeActivity samples to reduce the latency by re-sampling the tracking state later in the frame. • VrTemplate • make_new_project script is now converted to Python for cross-compatibility. • VrCapture / OVRMonitor • VrCapture may now be integrated into and collect data from multiple shared libraries in your app simultaneously (previously you could capture from VrApi or from your app, but not both at the same time). • OpenGL and logcat calls are now captured throughout the entire process. • Applications may now expose user-adjustable variables via OVR::Capture::GetVariable() and tweak the values in real-time in OVRMonitor.

12 | 0.6 Release Notes | Mobile

• Frame Buffer capturing now does basic block-based compression on the GPU, reducing network bandwidth by 50%. • GPU Zones are enabled, but we recommend only using them on the Samsung GALAXY S6. • Added Settings View for toggling VR Developer Mode. • Sensor Graphs now turn red when values exceed max defined by SetSensorRange(). API Changes • Native Application Framework • VRMenu, OvrGuiSys, OvrGazeCursor and related classes have been moved to the VrAppSupport/VrGui library. • OvrSceneView, ModelFile and related classes have been moved to the VrAppSupport/VrModel library. • Localization-related functionality has been moved to the VrAppSupport/VrLocale library. • The sound pool and related classes have been moved to the VrAppSupport/VrSound library. • The VrGui library now uses the SoundEffectPlayer interface for sound playback, replacing SoundManager. This simple interface can be overloaded to allow VrGui sounds to be played by any sound library. • VrActivity java class now subclasses Android Activity instead of ActivityGroup. Bug Fixes • VrAPI • Fixed adb logcat -s VrApi failure to report memory stats. • Native Application Framework • Fixed a bug where missing font glyphs were skipped instead of rendering as an asterisk. • Cinema SDK • • • •

Fixed last media poster showing up as the first poster for another category. Play/Pause icon does not function correctly after unmount/mount. Unmount/Mount does not pause media immediately. Fixed bad camera orientation in Void theater when auto-switching from another theater due to starting a video with a resolution greater than 1920x1080. • 360 Photos SDK • Fixed Favorites and Folder Browser icon switching in the attribution menu. • Fixed menu state bug causing background scene not to be drawn. • Fixed menu orientations not resetting on reorient. • Increased vertical spacing between categories in Folder Browser to improve thumbnail scrollbar fit. • 360 Videos SDK • Fixed media failure to pause immediately when unmounted. • Fixed movie not pausing on launching system activities. • Fixed menu orientation when resuming app. • Fixed gaze cursor not showing up when in Browser. • Build Scripts • Fix for devices over adb tcpip: If the phone was connected over TCP, it was trying to find oculussig_WWW.XXX.YYY.ZZZ:PPP when checking for the oculussig file. • If an install and run was requested but no devices found, now reports to user rather than quitting silently.

Mobile | 0.6 Release Notes | 13

• Change directories in an exception-safe manner. • VrCapture / Remote Monitor • Fixed rare crash when disconnecting from remote host on OS X. • Reconnecting to an app multiple times no longer puts the capture library in an undefined state. Known Issues • Unity 4 with Oculus Runtime for OS X 0.4.4 and Legacy Integration 0.6.1.0 or 0.6.0.2 • Editor crashes when building APK or pressing play in Play View; Mac standalone player crashes. To fix, update to Oculus Runtime for OS X 0.5.0.1. Before updating your runtime, be sure to run uninstall.app (found in /Applications/Oculus/) to remove your previous installation.VrApi implicitly links to libGLESv3.so, so currently you cannot load libvrapi.so on devices without OpenGL ES 3.0 support. • VrCapture / Remote Monitor • • • •

GPU Zones currently work on the Galaxy S6 only. Timer Queries are not functional on Adreno based devices. Integrated systrace support is under development and is currently disabled. Some VPNs break auto-discovery.

0.6.0.1 Overview This release of the Mobile SDK includes a fix to performance issues related to our Universal Menu and a hitching problem associated with data logging in VrApi, as well as some other minor updates. If you are upgrading from Mobile SDK v 0.5, be sure to review the 0.6.0 release notes for additional information on significant changes to our native development libraries as well as other updates. Note that our Mobile SDK documentation is now available online here: https://developer.oculus.com/ documentation/mobilesdk/latest/ New Features • Allow Unity MediaSurface dimensions to be modified via plugin interface. Bug Fixes • Fixed performance regression triggered when coming back from the Universal Menu. • Fixed not being able to enable chromatic aberration correction in the Unity plugin. • Reduced once per second frame drop due to gathering stats. • Fixed Do Not Disturb setting. • Fixed adjusting clock levels from Unity during load. Known Issues • adb logcat -s VrApi always reports the amount of available memory as 0.

14 | 0.6 Release Notes | Mobile

0.6.0 Overview of Native Changes The 0.6.0 version of the Oculus Mobile SDK introduces several major changes that necessitate updates to the VRLib structure, native app interface, and development workflow. If you are migrating from a previous SDK, please refer to the “Migrating from Earlier Versions” sections of the Native Development guide. VRLib has been restructured into three separate libraries in order to make the code more modular and to provide a smoother workflow: • LibOVR – the Oculus Library • VrApi – the minimal API for VR • VrAppFramework – the application framework used by native apps Both LibOVR and VrAppFramework ship with full source. The VrApi is shipped as a set of public include files, a pre-built shared library, and a jar file. Shipping VrApi as a separate shared library allows the VrApi implementation to be updated and/or changed after an application has been released. This allows us to apply hot fixes, implement new optimizations, and add support for new devices without requiring applications to be recompiled with a new SDK. VrApi source is no longer included with the SDK. The Vr App Interface (now part of VrAppFramework) has been simplified and now has a clearly-defined lifecycle. The order in which functions are called has been clarified – previously, some functions could be called either in VR mode or outside of VR mode. The lifecycle can be found in VrAppFramework/Src/App.h. The VRMenu code has been refactored in preparation for moving it into its own static library. User Interfacerelated interfaces that were previously passed to functions individually are now part of OvrGuiSys. There are three new native samples. These samples implement the same simple scene in three different ways, illustrating three approaches to Native application development • VrCubeWorld_SurfaceView – uses a plain Android SurfaceView and handles all Activity and Surface life cycle events in native code. This sample uses only the VrApi and uses neither the Oculus Mobile Application Framework nor LibOVR. • VrCubeWorld_NativeActivity – uses the Android NativeActivity class. This sample uses only the VrApi and uses neither the Oculus Mobile Application Framework nor LibOVR. • VrCubeWorld_NativeActivity – uses the Oculus Mobile Application Framework. For developers who prefer to use command-line scripts to build native projects, this SDK provides a robust cross-platform set of python build scripts to replace the platform specific build scripts provided with previous SDKs. Overview of Unity Integration Changes • Oculus Runtime is no longer required for mobile development. • Synced with the Oculus PC SDK 0.6.0.0 beta. • Allows clients to re-map plugin event IDs. For both the PC and Mobile SDKs we recommend the following Unity versions or higher: Unity Pro 4.6.3, Unity Professional 5.0.2.p2, Unity Free 4.6, or Unity Personal 5.0.2.p2. For mobile development, compatibility issues are known to exist with Unity 5 and OpenGL ES 3.0 – please check back for updates. Earlier versions of Unity 5 should not be used with the Mobile SDK. Note: Before installing or integrating this distribution, we strongly recommend backing up your project before attempting any merge operations.

Mobile | 0.6 Release Notes | 15

New Features • VrAPI • Improved frame prediction, in particular for Unity. • Leaving the CPU clock unlocked until the application starts rendering frames to make application loading/resuming faster. • Improved Performance Metrics via Logcat (see Basic Performance Stats through Logcat section of the Native Development Guide for more information). • Native Application Framework • Improved Android Activity and Android Surface life cycle handling. • Fixed volume bar not showing on first click of the volume adjustment. • 360 Photos SDK • Gaze Cursor now disappears when looking away from Attribution menu. • Blocksplosion • Added OS X input mappings. API Changes • Native Application Framework • Automatic caching of files extracted from apk. Bug Fixes • VrAPI • Removed additional frame of latency between synthesis and display. • Fixed intra frame object motion judder due to TimeWarp displaying eye buffers too early when eye buffer rendering completed early. • Fixed TimeWarp getting more than one frame behind after a bad hitch. • Workaround for "loss of head tracking" after closing and re-opening the device 96 times. • Native Application Framework • Fixed volume bar not showing on first click of the volume adjustment. • Unity Integration • Fixed prediction glitch every 64 frames. • Use correct prediction for OVR_GetCameraPositionOrientation. • Fixed location of the PlatformMenu Gaze Cursor Timer. • Cinema SDK • Fixed playback control reorienting screen in Void theater when user clicks on controls when they're off the screen on portrait videos. • Fixed divide by zero in SceneManager::GetFreeScreenScale() which caused Void theater to crash when starting a movie. • 360 Photos SDK • Fixed Favorites button not creating Favorites folder. • Blocksplosion

16 | 0.6 Release Notes | Mobile

• Fixed launch blocks falling straight down when launched when built with Unity 5. • Fixed touch triggering “next level” after returning from the System Activity. • Fixed launch block being offset when looking left or right. Known Issues • Initial launch of 360Photos SDK Sample can crash if a duplicate category folder name is present on the target device’s sdcard. Subsequent launches of the app will not crash. A fix is in the works for the next release.

Mobile | Mobile SDK Setup Guide | 17

Mobile SDK Setup Guide This guide will walk you through setting up your Samsung device and preparing your environment for mobile VR application development. Install the SDK Download the Mobile SDK here: https://developer.oculus.com/downloads/. The Mobile SDK is composed of a compressed archive in .zip format, which contains both source and media files: ovr_sdk_mobile_.zip. Once downloaded, extract the .zip file into a directory of your choice (e.g., C:\Oculus\Mobile).

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 System and Hardware Requirements above for the list of supported devices for this SDK release. Note: This information is accurate at the time of publication. Unfortunately, we cannot guarantee the consistency or reliability of third-party applications discussed in these pages, nor can we offer support for any of the third-party applications we describe.

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, you may need to manually update the drivers. 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.

18 | Mobile SDK Setup Guide | Mobile

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 are 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.

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.

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 seven 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.

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.

Mobile | Mobile SDK Setup Guide | 19

To purge the authorized whitelist for USB Debugging, press Revoke USB debugging authorizations from the Developer options menu and press OK. 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: Set to None to make 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. Android has announced that version 1.3 of Android Studio will add NDK support, so we will update our developer instructions for integration with their new IDE when it is available. For now, 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 for 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 8u45. You may download the appropriate version for your OS from the following location: http://www.oracle.com/technetwork/java/javase/downloads/ jdk8-downloads-2133151.html Once downloaded and installed, add the environment variable JAVA_HOME, which should be set to the JDK install location. Depending on where it was installed, it may look like C:\Program Files\Java \jdk1.8.0_45, if you have installed the x64 version.

20 | Mobile SDK Setup Guide | Mobile

Make sure your JAVA_HOME variable does not include quotation marks. Based on the default installation path of Java SE 8u45, the correct syntax when using set from the command line is: set JAVA_HOME=C:\Program Files (x86)\Java\jdk1.8.0_45

Do not use quotes with the set command, even though the path has a space in it. Also, be sure to use your actual path, which may differ from these examples.

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 must 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 above. 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

Mobile | Mobile SDK Setup Guide | 21

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 • Sources for Android SDK (optional, but invaluable for dealing with the Android API) 4. Finally, under Extras at the bottom, select the following: • Android Support Library Rev. 21.0.1

22 | Mobile SDK Setup Guide | Mobile

• Google USB Driver Rev. 11 Figure 1: 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.

Mobile | Mobile SDK Setup Guide | 23

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 .

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++. The NDK is used extensively by the sample applications which come with this release. The last version of the NDK known to work with the Mobile SDK is r10e. 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-ndkr10e\. 3. Add the NDK location to your PATH, e.g.: C:\Dev\Android\android-ndk-r10e\. 4. Add the environment variable ANDROID_NDK, which should be set to your Android NDK location, e.g.: C: \Dev\Android\android-ndk-r10e. set ANDROID_NDK=C:\Dev\Android\android-ndk-r10e

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.

24 | Mobile SDK Setup Guide | Mobile

3. In the Add Repository dialog that appears, enter “ADT Plugin” in the Name field and the following URL: https://dl-ssl.google.com/android/eclipse 4. Click OK. 5. In the Available Software dialog, select the checkbox for Developer Tools and click Next. 6. Click OK. 7. In the next window, you will see a list of tools to be download. Click Next. 8. 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.

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.4. It 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.4.

Mobile | Mobile SDK Setup Guide | 25

Next, add the Ant bin folder to your PATH, e.g.: C:\Dev\Android\apache-ant-1.9.4\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 Note: The tilde character followed by a forward slash (~/) is shorthand for the current user’s home folder. It is used throughout this section.

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 later) 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/jdk8-downloads-2133151.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

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. 4. Browse to ~/dev/adt-bundle-/eclipse and double-click the Eclipse icon. You may receive a warning like the following:

26 | Mobile SDK Setup Guide | Mobile

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:

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:

7. Select Browse and locate or create the directory for your workspace:

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.

Mobile | Mobile SDK Setup Guide | 27

In Eclipse go to Window -> Android SDK Manager to open a window similar to the following:

1. Note that some packages are already selected for installation by default. Leave these projects selected. 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 r10e - 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:

28 | Mobile SDK Setup Guide | Mobile

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 Eclipse -> Preferences window. 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” in the Name field and the following URL: https://dl-ssl.google.com/android/eclipse d. Click OK. e. In the Available Software dialog, select the checkbox for Developer Tools and click Next. f. Click OK. g. In the next window, you will see a list of tools to be download. Click Next. h. 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.

Mobile | Mobile SDK Setup Guide | 29

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

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.

30 | Mobile SDK Setup Guide | Mobile

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-r10e’ >> ~/.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. If you have already installed Xcode, you may be able to skip this step. The latest version which has been tested with this release is Apache Ant 1.9.3. 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. 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.

Mobile | Mobile SDK Setup Guide | 31

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, press Ctrl+X to save, answer Y to overwrite, and press Enter to select the current file.

Troubleshooting Troubleshooting your device and environment.

Device Troubleshooting 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. 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:

32 | Mobile SDK Setup Guide | Mobile

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.