unreal - oculus vrstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · oculus unreal...

54
Unreal Version 1.12.0

Upload: vuthu

Post on 04-May-2018

335 views

Category:

Documents


3 download

TRANSCRIPT

Page 1: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal

Version 1.12.0

Page 2: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

2 | Introduction | Unreal

2 | |

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 theirrespective owners. Certain materials included in this publication are reprinted with the permission of thecopyright holder.

Page 3: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Contents | 3

Contents

Introduction and Version Compatibility...............................................................4

Visual Studio 2015 Quick Start............................................................................6

Getting Started.................................................................................................... 7

Unreal Mobile Development............................................................................. 13

Unreal Input....................................................................................................... 17Gear VR Controller.......................................................................................................................................... 17Haptics for Rift Controllers.............................................................................................................................. 18Guardian System Boundary Component.........................................................................................................21

Unreal VR Audio................................................................................................ 24

Advanced Rendering Features.......................................................................... 25Unreal Forward Shading Renderer (PC).......................................................................................................... 25VR Compositor Layers..................................................................................................................................... 25Multi-View (Mobile)..........................................................................................................................................27Adaptive Pixel Density.....................................................................................................................................27

Oculus Platform Features and Online Subsystems............................................30

Unreal Console Commands............................................................................... 33

Blueprints............................................................................................................35

Unreal Samples.................................................................................................. 38

Testing and Performance Analysis in Unreal..................................................... 42

Release Notes.................................................................................................... 46Oculus Unreal Engine 4 Integration 1.12 Release Notes............................................................................... 46Oculus Unreal Engine 4 Integration 1.11 Release Notes............................................................................... 46Oculus Unreal Engine 4 Integration 1.10 Release Notes............................................................................... 48Oculus Unreal Engine 4 Integration 1.9 Release Notes................................................................................. 48Oculus Unreal Engine 4 Integration 1.8 Release Notes................................................................................. 49Oculus Unreal Engine 4 Integration 1.7 Release Notes................................................................................. 50Oculus Unreal Engine 4 Integration 1.6 Release Notes................................................................................. 51Oculus Unreal Engine 4 Integration 1.5 Release Notes................................................................................. 52Oculus Unreal Engine 4 Integration 1.4 Release Notes................................................................................. 53Oculus Unreal Engine 4 Integration 1.3 Release Notes................................................................................. 54

Page 4: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

4 | Introduction and Version Compatibility | Unreal

Introduction and Version CompatibilityUnreal is distributed with Oculus plugins which make it easy to develop for the Oculus Rift and Gear VR.

Applications targeting Oculus devices automatically apply stereoscopic rendering, orientation tracking (Rift andGear VR), and positional tracking (Rift only). The OculusPlatform plugin provides an online subsystem whichinterfaces with Oculus Platform features. The OculusInput plugin provides support for Oculus Touch and OculusRemote controllers.

Unreal Engine Distributions

Epic provides a binary distribution of UE4 through the Launcher, and a source distribution available from theirGitHub repository. These distributions all contain Oculus support, but they may be a version or two behind thelatest SDK.

Oculus also distributes UE4 through our own GitHub repository. These distributions are always up to date withthe latest Oculus SDKs. We support the current release of UE4, the previous release of UE4, and any preview ofthe next release of UE4.

This development sequence is illustrated in the following chart:

Note that our features ship first to the GitHub versions we maintain in our own repository.

Which distribution should I use?

For beginning developers, we recommend the binary distribution of the Unreal engine available through theLauncher. It is the most stable, and does not require pulling from GitHub or compiling the engine source code.It is typically a few months behind the latest Oculus SDK features.

For most professional developers, we recommend the source distribution hosted on Epic’s private GitHubrepository here: https://github.com/EpicGames/UnrealEngine. It is available to developers who are subscribedto the private EpicGames/UnrealEngine repository. For more information on accessing this repository, seehttps://www.unrealengine.com/ue4-on-github.

For professional developers who would like access to the latest SDK features, we recommend thesource distributions hosted on Oculus’s private GitHub repository here: https://github.com/Oculus-VR/UnrealEngine.git.

Page 5: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Introduction and Version Compatibility | 5

What does this guide cover?

Unless otherwise noted, this documentation covers features included in Unreal versions available from Oculus’sprivate GitHub repository. Note that API changes may occur when these branches are merged back into Epic’sversion of the engine.

For Epic's documentation about Oculus development, go to https://docs.unrealengine.com/latest/INT/Platforms/VR/.

Unreal/Oculus SDK Version Compatibility

The Oculus Unreal SDK requires Windows 7 or later.

Table 1: Oculus GitHub Repository

Branch Oculus PC SDK Oculus MobileSDK

Tag

4.10 1.4.0 1.0.2 oculus-4.10.4-release-1.4.0

4.11 1.6.0 1.0.3 oculus-4.11.2-release-1.6.0

4.12 1.10.1 1.0.3 oculus-4.12.5-release-1.10.1

4.13 1.11.0 1.0.3 oculus-4.13.2-release-1.11.0

4.14 1.12.0 1.0.3 oculus-4.14.3-release-1.12.0

4.15 1.12.0 1.0.4 oculus-4.15.1-release-1.12.0

Table 2: Epic GitHub Repository

Branch Oculus PC SDK Oculus MobileSDK

Tag

4.10 0.8.0 0.6.2 4.10.4-release

4.11 1.3.0 1.0.1 4.11.2-release

4.12 1.3.2 1.0.1 4.12.5-release

4.13 1.6.0 1.0.3 4.13.2-release

4.14 1.8.0 1.0.3 4.14.3-release

4.15 1.10.0 1.0.3 4.15.1-release

Page 6: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

6 | Visual Studio 2015 Quick Start | Unreal

Visual Studio 2015 Quick StartThe following section describes how to download, compile, and launch UE4 from Oculus’s GitHub repository.

Professional developers who wish to take full advantage of the features available with our Unreal integrationshould download and build the source code. For more information and an overview of other options forworking with Unreal, see Introduction and Version Compatibility on page 4.

This guide assumes you have installed Visual Studio 2015 and are familiar with its use.

Several of these steps may take some time to complete - some of them typically take over an hour, dependingon your computer and the speed of your Internet connection.

Note: Visual Studio 2013 is no longer supported.

1. Clone or download the UE4 source code from Oculus’s GitHub repository here: https://github.com/Oculus-VR/UnrealEngine. To access this forum, you must hold a UE4 license, and you must have access to theprivate Epic GitHub repository (see https://www.unrealengine.com/ue4-on-github for details).

2. If you downloaded a zip archive of the code, extract the archive contents to a directory where you would liketo build the engine, e.g., C:\Unreal\4.13-oculus. We recommend installing to a short path, or you may haveerrors in the next step with files that exceed the Windows length limit for file names. Alternately, you canmap your install directory as a Windows drive to reduce the path length.

3. Run Setup.bat.4. Run GenerateProjectFiles.bat.5. Launch UE4.sln to open the project solution in Visual Studio 2015.6. In the menu bar, select Build > Configuration Manager. Verify that Active solution configuration is set to

Development Editor, and that Active solution platform is set to Windows 64.7. In the Solution Explorer, right-click UE4 under Engine and select Set as Startup Project. Then select Build in

the same context menu.8. To launch the engine:

• With command-line arguments: Right-click UE4 in the Solution Explorer and select Properties. In theUE Property Pages dialog, select Configuration Properties > Debugging on the left. Enter any desiredconfiguration options in the Command Arguments field on the top.

• Without command-line arguments: In the Solution Explorer on the right, right-click UE4 under Engineand, in the context menu, select Debug > Start New Instance to launch the engine.

9. Select the project you would like to open, or specify a new project. If you are creating a new project, don’tforget to specify a project name.

10.At this point, the engine will close and a new instance of Visual Studio will launch with your selected or newproject. Repeat step 6 to launch the engine with the specified project.

For Epic's instructions on building the Unreal Engine from source, see Building Unreal Engine from Sourceguide.

Page 7: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Getting Started | 7

Getting StartedOverview

The easiest way to get started with Oculus development in Unreal is to experiment with the HMD supportprovided by default as a Player Start. If Unreal detects an Oculus Rift runtime (e.g., the Oculus app is installed),it will automatically provide orientation and positional tracking and stereoscopic rendering for any game.

Standalone PC executables will automatically display in Oculus Rift when run in full-screen mode if a Rift isdetected on your system. You may build a project normally and preview it in the Engine by selecting the VRPreview mode in the Play button pulldown options.

Note: In order to play an in-development application, you will need to enable running applications fromunknown sources in the Oculus app settings, available through the gear icon in the upper-right. SelectSettings > General and toggle Unknown Sources on to allow.

To preview a level in the Rift while editing with the engine, select the dropdown arrow near the Play button andselect VR Preview.

To play a scene in the Rift with a standalone PC game, simply maximize the game window and it will bemirrored to the Rift display.

Note: While Unreal is running, you will not be able to access Oculus Home by putting on the headset.

Page 8: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

8 | Getting Started | Unreal

Adding a VR Camera

Using the default camera set to VR Preview is a good way to get a quick sense of VR development with minimaloverhead, but for actual development, we recommend adding a Camera actor to your map and enablingOculus support by selecting the camera in Viewport and checking the Lock to Hmd checkbox in the Details tab(available in UE4 11).

Placing a camera in the scene allows you to control the orientation of the camera view when the game loads, sothat you can control the exact perspective that will be visible to the user. This is not possible with the Play Startdescribed above.

An additional benefit to using the Camera actor is that you can attach meshes and they will update theirposition following the HMD view with very little latency. This is generally the best way to add head-lockedelements such as cockpit details. Note that we generally discourage head-locked UI elements, but it can be anattractive feature when used carefully.

HMD Pose Tracking Origin

The HMD pose is reported relative to a tracking origin, which may be set to two values in yourHeadMountedDisplay settings:

Eye Level The initial pose of the HMD when the camera activates.

Floor Level The origin set by the user during Rift calibration, typicallynear the center of their playable area. Unlike eye-level, thefloor-level origin's position is on the floor, at Y = 0.

When you recenter the tracking origin, the behavior is different for eye and floor level.

Eye level moves the origin's position (X, Y, and Z) and the yaw (Y rotation) to match the current head pose. Pitchand roll (X and Z rotation) are not modified because that would make the app's virtual horizon mismatch thereal-world horizon, disorienting the user.

Floor level moves the origin's X and Z position, but leaves the Y position alone to keep it consistent with thereal-world floor. Rotation is handled the same way as eye level.

For more information, see:

Page 9: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Getting Started | 9

• Tracking in our Intro to VR• IHeadMountedDisplay in the Unreal API Guide

VR Template

Unreal Engine v4.13 and later include a Virtual Reality Blueprint project template which may be selected whencreating a New Project.

VR Template contains two maps, accessible through the Content Browser in Content > VirtualRealityBP >Maps.

The HMD Locomotion Map is a simple level that demonstrates teleportation. Set your travel destination withthe blue gaze-controlled circle. Once the teleport target is set, press the spacebar or gamepad button toteleport. You may optionally control the the orientation you will be facing on arrival with the gamepad primaryjoystick.

Page 10: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

10 | Getting Started | Unreal

The Motion Controller Map also demonstrates teleportation control, in this case using tracked Touchcontrollers. Point in the direction you’d like to travel with the Touch controller and and control the destinationorientation with your gaze. Then press the A-button to teleport.

Page 11: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Getting Started | 11

Use the trigger buttons to pick up and manipulate the small blue blocks in the level.

Page 12: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

12 | Getting Started | Unreal

Page 13: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Unreal Mobile Development | 13

Unreal Mobile DevelopmentThis guide covers environment setup, project configuration, and development for the Oculus Mobile platformusing Unreal.

Overview

Unreal versions 4.10 and later provide built-in support for Oculus mobile development. Projects configured forVR automatically apply stereoscopic rendering and orientation tracking. Once your environment is set up withthe appropriate tools and your project settings are configured properly, you may build virtual reality projectstargeting Android, load APKs on your mobile device, and play them on the Oculus Mobile platform.

Note: Mobile applications are subject to more computational limitations compared to Rift applications,and this should be taken into consideration beginning in the early design phase.

Oculus Mobile SDK

Oculus provides a mobile SDK with native C/C++ libraries for Android development in addition to supportingmobile development for game engines such as Unreal. It is not necessary for Unreal developers to downloador install the Mobile SDK, but we recommend looking through our Mobile SDK Developer Guide for generalinformation on Gear VR development such as application signature, basic mobile development tools such asadb and Oculus Remote Monitor, and performance guidelines.

We recommend that Unreal mobile developers review the following sections:

• Mobile SDK Getting Started Guide• Mobile Development Basics• Mobile Best Practices• Testing and Troubleshooting

Developers interested in lower-level details about how the mobile VR rendering pipeline is handled by ournative libraries may wish to download the mobile SDK and review the headers, particularly for the VrApi, whichis responsible for returning headset orientation data and applying distortion, sensor fusion, and compositing.

Mobile Environment Setup

There are two ways to set up your environment for Gear VR development for Unreal: 1) using the Codeworksfor Android installation package (recommended), or 2) using the standard Android SDK.

Epic strongly recommends using the Codeworks for Android 1R4 installation package rather than the stockAndroid SDK. Using this package simplifies Unreal set up and may be necessary to successfully build GearVR projects. However, it requires uninstalling any standard Android SDK installation and may interfere withdevelopment using other engines or IDEs that require the standard Android SDK. To install Codeworks forAndroid 1R4, follow the instructions in Epic’s Required Android Setup guide.

Note: You will find the required version of Codeworks here: Engine\Extras\AndroidWorks\Win64.

To prepare for Gear VR development using the standard Android SDK, follow the instructions in our MobileAndroid Development Software Setup for Windows guide to install the Java Development Kit (JDK), NativeDevelopment Kit, and Android SDK. Unreal developers do not need to install Android Studio. Our Unreal SDKdoes not currently support OS X or Linux.

Page 14: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

14 | Unreal Mobile Development | Unreal

Once you have installed the required Android tools, follow the setup instructions described in the Device Setupguide in our Mobile SDK documentation. In this process you will enable Developer Options on your mobiledevice and make a few device configuration settings.

Application Signing

Oculus mobile applications must be signed by two different signatures at different stages of development.An Oculus Signature File (osig) is required for your application to run on Gear VR, and an Android distributionkeystore is required for submission to the Oculus Store.

Once you add an osig to the appropriate Unreal directory, it will be added automatically to every APK that youbuild. You will need one osig for each mobile device.

To add your osig to Unreal for development:

1. Follow the instructions in Application Signing to download your osig.2. Navigate to the directory <Unreal-directory>\Engine\Build\Android\Java\.3. Create a new directory inside \Engine\Build\Android\Java\ and name it assets. The name must not be

capitalized.4. Copy your osig to this directory.

When you are ready to build an APK for submission to release, we recommend that you exclude the osig inyour APK. To do so, select Edit > Project Settings > Android, scroll down to Advanced APKPackaging, andverify that Remove Oculus Signature Files from Distribution APK is checked.

Before building your final release build, create a new Android keystore by following the “Sign Your AppManually” instructions in Android's Sign your Applications guide. Once you have generated your distribution

Page 15: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Unreal Mobile Development | 15

keystore, go to Edit > Project Settings > Platforms > Android, scroll down to Distribution Signing, and enteredthe required information.

See the Application Signing section of the Mobile SDK documentation for more information.

Configure Unreal for Android SDK

If you do not have a project prepared but would like to try out the process, you may use create a scene withstarter content such as the C++ First Person project.

Once you have installed the Android SDK and required tools, configure Unreal for Android development.

1. Select Edit > Project Settings.2. In the Project Settings menu on the left, go to Platforms and select Android SDK (not Android - we will

configure that later).3. Configure all fields in SDKConfig with the appropriate paths to the necessary tools. Note: if you installed

Codeworks for Android, these fields should be populated automatically.

Project Configuration

This section describes how to configure any C++ or Blueprints Unreal project targeting desktop or mobile foruse with Oculus mobile devices.

If you do not have a project prepared but would like to try out the process, you may use create a scene withstarter content such as the C++ First Person project.

1. Select Edit > Plugins.2. Select Virtual Reality.3. Verify that the Enabled check box is checked for Gear VR. If you need to select it, click Restart Now in the

lower-right afterward. Close Plugins configuration.4. Select Edit > Project Settings.5. Fill in any other desired information in Project > Description.6. In the Project Settings menu on the left, go to Platforms and select Android.7. Under APKPackaging, set the Minimum SDK Version to 19, and set the Target SDK Version to 19.8. Scroll down to Advanced APKPackaging. Then:

a. Check Configure the AndroidManifest for deployment to GearVR.b. Verify that Remove Oculus Signature Files from Distribution APK is unchecked, unless you are building a

package to release.9. In Engine > Rendering, uncheck Mobile HDR in the Mobile section.10.Close the Project Settings configuration window.

Building and Running Projects

1. Connect your Samsung phone to your PC via USB.2. Open a shell terminal and verify that your device is communicating with your PC using adb devices.

Note that depending on the device you are using, you may need to configure your connection for softwareinstallation. For more information, see Adb in our Mobile SDK Developer Guide.

3. We recommend using ASTC compression, though ETC2 will also work. Select File > Package Project >Android > Android (ASTC).

4. When prompted, browse to the destination folder where you would like your APK to be installed.5. Once the build process is completed, navigate to the destination folder. Run the .bat file beginning with

Install_ to install the application to your phone.

Page 16: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

16 | Unreal Mobile Development | Unreal

6. Once the build process is complete, your application will be visible on your mobile devices under Apps.Note that it will not be visible in Oculus Home.

7. Click the application to launch. You will be prompted to insert it into your Gear VR headset.

Note: You may also set your phone to Developer Mode, which allows you to run VR applications onyour mobile device without inserting it into an HMD.

Launching a Project Directly onto your Phone

You may also directly build and launch an application to your phone without saving the APK locally.

1. Connect your phone to your PC by USB.2. Select the Launch menu from the Unreal toolbar and select your phone under Devices. If you do not see

your phone listed, verify your USB connection, and check if you need to set your connection to Connectedas an Installer - some Samsung phones default to Charge Only connection.

3. Your application will build and install to your Android device. When the build is complete, you will beprompted to insert the phone into your headset to launch.

Workflow

We recommend setting your phone to Developer Mode, so you can run VR apps on your phone withoutinserting it into the Gear VR headset. This allows you to quickly review your progress on the device withoutmuch overhead.

You may also launch the engine with a configuration option to use the GearVR plugin and Mobile rendereron the PC. This allows you to preview mobile development from the desktop using an Oculus Rift. To do so,disable OculusRift and SteamVR plugins for your project, and add -OpenGL -FeatureLevelES2 to yourcommand line.

To run your app during development, we generally recommend connecting your phone via USB, selectingthe Launch pulldown menu, and then selecting your phone under the listed devices. Particularly if you aremodifying maps and shaders but not changing the code, this is often much faster than building an APK.

It is possible to preview a Gear VR application in the Oculus Rift during development. However, it is notgenerally useful to do so, because Rift applications are subject to substantially different performancerequirements (see "Performance Targets" in Testing and Performance Analysis in Unreal on page 42). Youmay find it easiest to use the 2D preview in Unreal, and then either build an APK or use Launch on Device whenyou need to view the app in VR.

Note: Mobile Content Scale Factor is not currently supported for Oculus development.

Blueprints

We provide Blueprints for common Gear VR operations such as querying battery level and headphoneconnection status. To access Blueprints for Gear VR, you must enable the Gear VR plugin in Edit > Plugins >Virtual Reality.

For more information, see Blueprints on page 35.

Multi-view

Multi-view is an advanced rendering feature for Gear VR, available in experimental form in Unreal 4.14 andlater. If your application is CPU-bound, we strongly recommend using multi-view to improve performance.

For more information, see Multi-View (Mobile) on page 27 in Advanced Rendering.

Page 17: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Unreal Input | 17

Unreal InputThis section describes input handling for Oculus devices.

Gear VR ControllerThe Gear VR Controller is an orientation-tracked input device available through Unreal as a Motion Controller.

For instructions on how to add a Motion Controller component to your Pawn or Character, see MotionController Component Setup in Epic’s Unreal documentation. Unreal has also provided a detailed trainingtutorial called Setting Up VR Motion Controllers.

Gear VR positions the controller relative to the user by using a body model to estimate the controller’s position.Whether the controller is visualized on the left or right side of the body is determined by left-handedness versusright-handedness, which is specified by users during controller pairing.

Orientation tracking is handled automatically by the Motion Controller Component. If you need to query thecontroller orientation, you can query the Motion Controller rotation.

Motion Controller Components must be specified as either left or right controllers when they are added, andeach Gear VR Controller button mapping has a left/right equivalent. However, any button click sends both leftand right events, so the setting you choose when add the Motion Controller component has no effect.

Gear VR Controller Sample

We provide a sample called GearVRControllerSample in the directory <install>/Samples/Oculus. Please see thesample and its Level Blueprint for a full illustration of how to use the controller in your game.

GearVRControllerSample includes two Blueprints:

• Enable Arm Model: enabled by default.• Get Gear VR Controller Handedness: gets the handedness of the controller per the user configuration.

Button Mapping

The touchpad distinguishes between a touch, in which the user’s finger is touching the pad without pushing itdown, and a click.

The touchpad may be queried using FaceButtons to check for clicks on the 12:00, 3:00, 6:00, and 9:00positions, or with Thumbstick_X/Thumbstick_Y to check for the finger position anywhere on the pad using axisvalues from -1.0,-1.0 (lower-left corner) to 1.0,1.0 (upper-right corner).

All left/right button events are equivalent. The volume and home buttons are reserved.

Motioncontroller_Left_Thumbstick/Right_Thumbstick touchpad click anywhere

MotionController_Left_FaceButton1/Right_FaceButton1 click at 12:00

MotionController_Left_FaceButton2/Right_FaceButton2 click at 3:00

MotionController_Left_FaceButton3/Right_FaceButton3 click at 6:00

Page 18: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

18 | Unreal Input | Unreal

MotionController_Left_FaceButton4/Right_FaceButton4 click at 9:00

MotionController_Left_FaceButton5/Right_FaceButton5 back button

MotionController_Left_Thumbstick_X/Right_Thumbstick_X touchpad contact position from-1.0 (left) to 1.0 (right)

MotionController_Left_Thumbstick_Y/Right_Thumbstick_Y touchpad contact position from-1.0 (bottom) to 1.0 (top)

MotionController_Left_FaceButton6/Right_FaceButton6 touchpad touch

Motioncontroller_Left_Trigger/Right_Trigger trigger

Haptics for Rift ControllersYou may use the standard Play Haptic Effect Blueprint to send a specified haptic curve to the Oculus Touch orXbox controller. For more information, see Unreal’s Play Haptic Effect guide.

Haptics in Unreal Engine 4.13

PlayHapticEffects may be configured to play haptic waves based on three types of input. Right-click ContentBrowser to bring up the context menu, then select Miscellaneous. and select one of the following three options:

• Haptic Feedback Buffer: Plays a buffer of bytes 0-255,• Haptic Feedback Curve: Draw the haptic linear curve you wish to play using the Haptic Curve Editor, or• Haptic Feedback Soundwave: Select a mono audio file to be converted into a haptic effect of corresponding

amplitude.

The following Blueprint illustrates a simple haptics sequence on the Oculus Touch controller using Play HapticEffect. This example sends vibrations using Play Haptic Effect when the left controller grip button is pressed.When the button is released, Stop Haptic Effect sends a stop command to the Touch controller.

When the left controller X button is pressed, a constant vibration is sent by Set Haptics by Value until thebutton is released. Note that Set Haptics by Value calls are limited to 30 Hz; additional calls will be disregarded.

Page 19: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Unreal Input | 19

Haptics in Unreal Engine 4.12

In addition to Play Haptic Effects, Unreal 4.12 adds Play Haptic Soundwave.

The following Blueprint illustrates a simple haptics sequence on the Oculus Touch controller using Play HapticEffects and Play Haptic Soundwave. This example sends vibrations using Play Haptic Effect when the leftcontroller grip button is pressed. When the button is released, Play Haptic Soundwave sends a second vibrationto the controller.

Page 20: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

20 | Unreal Input | Unreal

When the left controller X button is pressed, a constant vibration is sent by Set Haptics by Value until thebutton is released. Note that Set Haptics by Value calls are limited to 30 Hz; additional calls will be disregarded.

APlayerController::PlayHapticSoundWave takes a mono soundwave as an argument. It downsamplesthe wave into a series of bytes that serially describe the amplitude of the wave (uint8 values 0-255). Each byteis then multiplied by the factor specified in Scale (max = 255), and haptic vibrations are sent to the targetedOculus Touch controller. Each controller must be targeted individually. Call Stop Haptic Effect to stop hapticplayback.

Haptics Sample

The TouchSample, available from our Unreal GitHub repository, illustrates basic use of Oculus Touch, includinghaptics control using PlayHapticEffect() and PlayHapticSoundWave(). For more information, seeUnreal Samples on page 38.

Page 21: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Unreal Input | 21

Guardian System Boundary ComponentOculusRiftBoundaryComponent exposes an API for interacting with the Oculus Guardian System.

Note: The Guardian System is not yet supported by public versions of the Oculus runtime.

During Touch setup, users define an interaction area by drawing a perimeter called the Outer Boundary inspace with the controller. An axis-aligned bounding box called the Play Area is calculated from this perimeter.

When tracked devices approach the Outer Boundary, the Oculus runtime automatically provides visual cues tothe user demarcating the Outer Boundary. This behavior may not be disabled or superseded by applications,though the Guardian System visualization may be disabled via user configuration in the Oculus App.

Additional handling may be implemented by applications using the class UOculusRiftBoundaryComponent.Possible use cases include pausing the game if the user leaves the Play Area, placing geometry in the worldbased on boundary points to create a “natural” integrated barrier with in-scene objects, disabling UI when theboundary is being rendered to avoid visual discomfort, et cetera.

All UOculusRiftBoundaryComponent public methods are available as Blueprints.

Please see OculusRiftBoundaryComponent.h for additional details.

Basic Use

Boundary types are Boundary_Outer and Boundary_PlayArea.

Device types are HMD, LTouch, RTouch, Touch (i.e., both controllers), and All.

Page 22: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

22 | Unreal Input | Unreal

Applications may query the interaction between devices and the Outer Boundary orPlay Area by using UOculusRiftBoundaryComponent::GetTriggeredPlayAreaInfo() orUOculusRiftBoundaryComponent::GetTriggeredOuterBoundaryInfo().

Applications may also query arbitrary points relative to the Play Area or OuterBoundary using UOculusRiftBoundaryComponent::CheckIfPointWithinOuterBounds() orUOculusRiftBoundaryComponent::CheckIfPointWithinPlayArea(). This may be useful for determining thelocation of particular Actors in a scene relative to boundaries so, for example, they are spawned within reach, etcetera.

Results are returned as a struct called FBoundaryTestResult, which includes the following members:

Member Type Description

IsTriggering bool Returns true if the device or point triggers the queried boundarytype.

DeviceType ETrackedDeviceTypeDevice type triggering boundary.

ClosestDistance float Distance between the device or point and the closest point of thetest area.

ClosestPoint FVector Describes the location in tracking space of the closest boundarypoint to the queried device or point.

ClosestPointNormal FVector Describes the normal of the closest boundary point to the querieddevice or point.

All dimensions, points, and vectors are returned in Unreal world coordinate space.

Applications may request that boundaries be displayed or hidden usingRequestOuterBoundaryVisible(). Note that the Oculus runtime will override application requests undercertain conditions. For example, setting Boundary Area visibility to false will fail if a tracked device is closeenough to trigger the boundary’s automatic display. Setting the visibility to true will fail if the user has disabledthe visual display of the boundary system.

Applications may query the current state of the boundary system usingUOculusRiftBoundaryComponent::IsOuterBoundaryDisplayed() andUOculusRiftBoundaryComponent::IsOuterBoundaryTriggered().

You may bind delegates using the object OnOuterBoundaryTriggered.

Additional Features

You may set the boundary color of the automated Guardian System visualization (alpha isunaffected) using UOculusRiftBoundaryComponent::SetOuterBoundaryColor(). UseUOculusRiftBoundaryComponent::ResetOuterBoundaryColor()to reset to default settings.

UOculusRiftBoundaryComponent::GetOuterBoundaryPoints() andUOculusRiftBoundaryComponent::GetPlayAreaPoints()return an array ofup to 256 3D points that define the Boundary Area or Play Area in clockwise orderat floor level. You may query the dimensions of a Boundary Area or Play Area usingUOculusRiftBoundaryComponent::GetOuterBoundaryDimensions() or

UOculusRiftBoundaryComponent::GetPlayAreaDimensions(), which return a vectors containing thewidth, height, and depth in tracking space units, with height always returning 0.

Page 23: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Unreal Input | 23

Boundary Sample

BoundarySample, available from our Unreal GitHub repository, illustrates the use of the Boundary ComponentAPI for interacting with our Guardian System. For more information, see Unreal Samples on page 38.

Page 24: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

24 | Unreal VR Audio | Unreal

Unreal VR AudioAudio is critical for creating a persuasive VR experience and can contribute strongly to the user's sense ofimmersion.

Audio Basics

When Unreal PC applications are launched, if the OculusRift plugin is enabled and the Oculus VR RuntimeService is installed, then the application will automatically override the default Windows graphics and audiodevices and target the Rift. The Oculus VR Runtime Service is installed with the Oculus App.

Unless your application is intended to run in VR, do not enable the OculusRift plugin. Otherwise, it is possiblethat audio and/or video will be incorrectly targeted to the Oculus Rift when the application is run.

Alternatively, users can disable loading all HMD plugins by specifying "-nohmd" on the command line.

Audio Spatialization

The Oculus Audio SDK includes spatialization plugins (OSPs) that provide HRTF spatialization and reverbmodeling for audio editing tools commonly used with Unreal, including Audiokinetic Wwise and FMOD Studio.

FMOD supports both Rift and mobile development, and Wwise supports Rift development. For more details onintegrating our spatialization plugins with FMOD and Wwise for use in Unreal, see the Rift Audio section of ourRift developer guide.

We recommend using FMOD or Wwise with the appropriate OSP, which will provide access to our fullspatialization feature set as well as the full functionality of the audio tools themselves. Epic also offers built-inaudio spatialization for Rift with HRTF-spatialization only. Epic’s 4.15-preview branch offers preview support forGear VR which does not support some features such as ducking and filtering, and which may contain bugs. Foran example of how to implement it, see AmbientSound Spatialize in the Unreal Audio Content Example.

For more information on our plugins, and for general information about audio design for VR, please see ourAudio SDK developer guide.

Page 25: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Advanced Rendering Features | 25

Advanced Rendering FeaturesThis section describes important rendering options and tools that can significantly improve your application.

Unreal Forward Shading Renderer (PC)Unreal Engine 4.14 introduced an experimental forward shading renderer optimized for VR. We recommendthat all future PC titles use the forward shading renderer.

The primary advantage of the forward renderer is that it is substantially faster than the deferred renderer. Itoutputs lit pixels directly, whereas the deferred renderer outputs material properties to a set of buffers, andthen reads them back to apply lighting in a separate pass.

Because the forward renderer does not render to intermediate buffers, it can take advantage of MSAA. Werecommend using MSAA for anti-aliasing, as it not only reduces motion blur, but often provides a significantsavings in GPU utilization over TAA.

Not all features from the deferred renderer are available in the forward renderer, but many of these featuresrequire tradeoffs that disproportionately impact VR development. For example, space screen effects mayintroduce stereo disparities that can be uncomfortable for users.

Given the substantial advantages the forward shading renderer offers VR developers, we anticipate that theforward shading renderer will become the target for future VR optimizations.

For more information on the forward shading renderer, see Epic’s New: Forward Shading Renderer with MSAA.

VR Compositor LayersIn some versions of Unreal, you may add transparent or opaque quadrilateral, cubemap, or cylindrical overlaysto your level as compositor layers.

TimeWarp compositor layers are rendered at the same frame rate as the compositor, rather than rendering atthe application frame rate. They are less prone to judder, and are raytraced through the lenses, which improvesthe clarity of textures displayed on them.

We recommend using compositor layers for text and for headlocked elements. Text rendered on compositorlayers is more legible, and headlocked layers remain headlocked when Asynchronous TimeWarp interpolatesdropped frames.

Gaze cursors and UIs are good candidates for rendering as quadrilateral compositor layers. Cylinders may beuseful for smooth-curve UI interfaces. Cubemaps may be used for startup scenes or skyboxes.

We recommend using a cubemap compositor layer for your loading scene, so it will always display at a steadyminimum frame rate, even if the application performs no updates whatsoever. This can significantly improveapplication startup times.

Quadrilateral, cylinder, and cubemap layers are supported in Unreal versions 4.13 and later. Cylinder andcubemap support currently support mobile development only.

By default, VR compositor layers are always displayed on top of all other objects in the scene. You may setcompositor layers to respect depth positioning by enabling Supports Depth. If you are using multiple layers,use the Priority setting to control the depth order in which the layers will be displayed, with lower valuesindicating greater priority (e.g., 0 is before 1).

Page 26: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

26 | Advanced Rendering Features | Unreal

Note that enabling Supports Depth may affect performance, so use it with caution and be sure to assess itsimpact.

To create an overlay:

1. Create an Actor and add it to the level. If you don’t want the Actor to be visible in the scene, use an EmptyActor.

2. Select the Actor, select Add Component, and choose Stereo Layer.3. Under the Stereo Layer options, set Stereo Layer Type to Quad Layer or Cylinder Layer.4. Set Stereo Layer Type to Face Locked, Torso Locked, or World Locked.5. Set the overlay dimensions in world units in Quad Stereo Layer Properties or Cylinder Stereo Layer

Properties.6. Select Supports Depth in Stereo Layer to set your compositor layer to not always appear on top of other

scene geometry. Note that this may affect performance.7. Configure Texture and additional attributes as appropriate.

The Actor you slave the component to will be fixed at the center of the quad or the cylinder.

You may add up to three VR compositor layers to Gear VR applications, and up to fifteen to Rift applications.

Layers Sample

The LayerSample, available from our Unreal GitHub repository, illustrates the use of VR Compositor Layers todisplay a UMG UI. For more information, see Unreal Samples on page 38.

Page 27: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Advanced Rendering Features | 27

Multi-View (Mobile)Multi-view is an advanced rendering feature for Gear VR, available in experimental form in Unreal 4.14 andlater. If your application is CPU-bound, we strongly recommend using multi-view to improve performance.

In typical OpenGL stereo rendering, each eye buffer must be rendered in sequence, doubling applicationand driver overhead. When multi-view is enabled, objects are rendered once to the left eye buffer, and arethen automatically duplicated to the right buffer with appropriate modifications for vertex position and view-dependant variables such as reflection.

Multi-view is currently supported by Note5, S6, S7, and S7 Edge phones using ARM Exynos processors andrunning Android M or N. It is also supported on S7 and S7 Edge phones using Qualcomm processors andrunning Android N.

Multi-View requires OpenGL ES 2, and does not currently support OpenGL ES 3.1.

Although multi-view can substantially reduce CPU overhead, keep in mind that applications submitted to theOculus Store must maintain minimum frame rate per our requirements, even on devices that do not supportmulti-view.

Enabling Multi-View

Open Edit > Editor Preferences > Engine > Rendering. In the VR section, enable Mobile Multi-View.

For Exynos devices, verify that Support OpenGL ES2 is checked in the Build section in Platforms > Android, andthat Support OpenGL ES3 is not selected.

Direct Multi-View

Oculus versions 4.15 and higher using integration 1.12 or later support an enhanced version of Multi-Viewthat reduces the number of full-screen copies that must be rendered. In most cases, it provides a substantialreduction in GPU overhead.

To enable Direct Multi-View, add the following to defaultengine.ini:

[GearVR.Settings]bEnableDirectMultiview=True

Adaptive Pixel DensityAdaptive Pixel Density allows applications to scale down the application viewport as GPU resources exceed85% utilization, and to scale up as they become more available.

For CPU-bound applications, this feature has the potential to improve visual quality.

The following charts illustrate pixel density (gold) and frames per second (blue) on a demo application withAdaptive Pixel Density off and on, respectively.

Page 28: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

28 | Advanced Rendering Features | Unreal

Page 29: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Advanced Rendering Features | 29

To enable Adaptive Pixel Density, use the console command hmd pdadaptive on. You may specify aminimum and maximum scaling factor (default 1 = normal density). See Unreal Console Commands on page33 for more information.

To enable Adaptive Pixel Density on startup, specify the appropriate settings in Engine/Config/BaseEngine.ini.For example:

[Oculus.Settings]PixelDensityMin=0.5PixelDensityMax=1.0PixelDensityAdaptive=true

See Loading Console Variables in Epic’s Console Manager: Console Variables in C++ for more information.

If you do not want some Actors within your level (e.g., text displays) to be scaled, they should be drawn usingseparate VR Compositor Layers which are not scaled by pixel density. For more information, see VR CompositorLayers on page 25.

Note: To minimize the perceived artifacts from changing resolution, there is a two-second minimumdelay between every resolution change.

Page 30: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

30 | Oculus Platform Features and Online Subsystems | Unreal

Oculus Platform Features and OnlineSubsystemsThe Oculus Platform supports several features related to security, community, revenue, and engagement,including matchmaking, in-app purchase, entitlement checking, VoIP, cloudsaves, and more.

Unreal developers may access Oculus Platform features in two ways:

1. A subset of Platform functionality is built into the engine and is available through the Unreal OnlineSubsystem interface, and

2. The Platform SDK includes an Unreal plugin providing full access to all Oculus Platform features

Some Platform features support Blueprints, such as Entitlement Checking. For more information andinstructions, see the Platform section of Blueprints on page 35

For instructions on using the Oculus Platform Plugin for Unreal, please see our Platform SDK documentationand the readme included in the Unreal folder of the Platform SDK archive (available from our Downloads page).

Unreal Online Subsystems

Several Oculus Platform features may be accessed through Unreal’s Online Subsystems (OSS) interface inUnreal Engine 4.12 and 4.13. For more information on available UE4 versions and compatibility, see ourIntroduction and Version Compatibility on page 4.

For each supported feature, only a subset of functionality is exposed by the Online Subsystems interface.Developers who wish to use Platform features not available through Online Subsystems should code againstthe native C headers located in Engine\Source\ThirdParty\Oculus\LibOVRPlatform and include them in theirbuild.

The following features are available through the Online Subsystems.

Feature Online Subsystem Interface

Achievements Achievements

Top Players Leaderboards

Friends Leaderboards

Rooms Sessions

Matchmaking Sessions

Cloudsaves Cloudsaves

Identity Identity

Entitlements Identity

VoIP Voice

Page 31: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Oculus Platform Features and Online Subsystems | 31

Feature Online Subsystem Interface

P2P Networking Netdriver

To enable the OSS plugin, select Edit > Plugin Settings > Built-In > Online Platform > Online SubsystemOculus, and check Enabled.

To access Oculus Platform features through Online Subsystems, you must adjust your defaultEngine.ini file touse Oculus:

[OnlineSubsystem]DefaultPlatformService=Oculus [OnlineSubsystemOculus]bEnabled=trueOculusAppId=<app_id_here>

For more information on Unreal Subsystems, see Epic’s Online Subsystems Overview.

Entitlement Checking

Entitlement checking may be used to protect apps from unauthorized distribution. Unreal developers usingBlueprints can use the Verify Entitlements Blueprint under Oculus > Entitlement. For more information andinstructions, see the Platform section of Blueprints on page 35 and Entitlements: App Authorizations in ourPlatform guide.

Applications should always have entitlement checks enabled for submissions to the Oculus store.

VoIP

Our Online Subsystems implementation of VoIP extends the Unreal class IOnlineVoice. See Unreal’sIOnlineVoice reference for more information.

To enable VoIP in DefaultEngine.ini:

[OnlineSubsystem]DefaultPlatformService=OculusbHasVoiceEnabled=true [Voice]bEnabled=true

To connect to someone else:

Online::GetVoiceInterface()->RegisterRemoteTalker(<FUniqueNetIdOculus>);

To disconnect from someone:

Online::GetVoiceInterface()->UnregisterRemoteTalker(<FUniqueNetIdOculus>);

To see if a remote user is talking:

Online::GetVoiceInterface()->IsRemotePlayerTalking(<FUniqueNetIdOculus>);

To unmute yourself:

Online::GetVoiceInterface()->StartNetworkedVoice(0);

Page 32: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

32 | Oculus Platform Features and Online Subsystems | Unreal

To mute yourself:

Online::GetVoiceInterface()->StopNetworkedVoice(0);

P2P

Our Online Subsystem implementation of P2P extends the Unreal class UNetDriver. See Unreal's UNetDriverreference for more information.

To enable P2P in DefaultEngine.ini:

[/Script/Engine.GameEngine] +NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="OnlineSubsystemOculus.OculusNetDriver",DriverClassNameFallback="OnlineSubsystemUtils.IpNetDriver") [/Script/OnlineSubsystemOculus.OculusNetDriver] NetConnectionClassName="OnlineSubsystemOculus.OculusNetConnection"

To act as the host of a game, open the map as a listen server.

To act as the client of the game, open a connection to <oculus_id_of_host>.oculus.

Page 33: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Unreal Console Commands | 33

Unreal Console CommandsThis document reviews useful console commands available for Unreal development.

Rift: Press the tab keys while your game is running to bring up the console.

Gear VR: To bring up the console on a mobile device, set it to developer mode (instructions https://developer.oculus.com/documentation/mobilesdk/latest/concepts/mobile-troublesh-device-run-app-outside/),launch the application, and tap the screen with four fingers.

To specify console commands to be loaded on startup, in most cases you should add them to Engine/Config/ConsoleVariables.ini. See Loading Console Variables in Epic’s Console Manager: Console Variables in C++ formore information.

For more information, see "Useful VR Console Commands" in Unreal's VR Cheat Sheet.

Table 3: Configuration Commands

Command Description

stereo on|off Enables/Disables stereo mode.

stereo e=0.064 Eye distance (m).

stereo w2m=100 Overrides default world-units-to-meters scale.

stereo ncp=10 fcp=10000 Overrides near clipping and/or far clipping planes for stereo rendering (in cm).

stereo cs=1 ps=1 Overrides camera and position scale.

stereo show Shows current ipd and head model offset.

stereo reset Resets stereo settings.

hmd enable|disable Enables/Disables HMD.

hmd pd [0..3.0] Sets pixel density in the center (default is 1.0).

hmd pdadaptive on|off Enables/Disables adaptive pixel density (see Adaptive Pixel Density on page 27 for more details).

hmd pdmax [0.5..2.0] Sets maximum adaptive pixel density (ignored if hmd pdadaptive is off).

hmd pdmin [0.5..2.0] Sets minimum adaptive pixel density (ignored if hmd pdadaptive is off).

hmd sp [30..300] Overrides screenpercentage for stereo mode. (Deprecated, use 'hmd pd xxx' instead).

hmd hqdistortion on|off Enables/Disables high-quality distortion.

hmd mirror on|off Enables/Disables mirroring to the desktop window.

Page 34: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

34 | Unreal Console Commands | Unreal

Command Description

hmd mirror mode [0..4] Sets mirror mode: 0=Distorted, 1=Undistorted, 2=SingleEye, 3=SingleEye Letterboxed,4=SingleEye Cropped

hmdpos on|off|toggle Enables/Disables/Toggles positional tracking.

hmdpos enforce on|off Enables/Disables head tracking even if not in stereo (for testing purposes).

hmdpos reset yaw Resets position and rotation, applies yaw (in degrees) if provided.

hmdpos resetrot yaw Resets rotation only, applies yaw (in degrees) if provided.

hmdpos resetpos Resets position only.

hmdpos show Outputs status of positional tracking to log.

hmdpos floor|eye Selects tracking origin.

Table 4: Misc Commands

Command Description

hmd stats Shows HMD-related stats.

hmd grid Toggles lens-centered grid.

hmd updateongt on|off Enables/Disables updating HMD pose on game thread. On by default.

hmd updateonrt on|off Enables/Disables updating HMD pose on render thread, for lower latency. On by default.

hmd cubemap [gearvr] [xoff=N][yoff=N] [zoff=N] [yaw=N]

Generates a cube map image of your application. May be used for VR app previews in the OculusStore. Cube map PNGs will be saved in the directory GameDir/Saved/Cubemaps.

gearvr: If specified, cube map size will be 6x1024x1024, otherwise it will be 6*2048x2048.

xoff, yoff, zoff: Offset from the current player's location.

yaw: override yaw rotation (degrees).

hmd setint PerfHUDMode [0..4] Selects performance HUD mode, set to 0 to disable.

hmd setintDebugHudStereoMode [0..3]

Selects debug HUD stereo mode, set to 0 to disable.

hmdversion Prints Oculus SDK version used and Oculus Plugin info.

Page 35: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Blueprints | 35

BlueprintsOculus Blueprints are available for developer use.

Gear VR

To access Blueprints for Gear VR, you must enable the Gear VR plugin in Edit > Plugins > Virtual Reality.

The following Blueprints under the Gear VR class are provided to assist with mobile development:

• Are Head Phones Plugged In - returns bool• Get Battery Level - returns float• Get Temperature in Celsius - returns float• Is Power Level State Minimum - returns bool• Is Power Level State Throttled - returns bool• Set CPU And GPU Levels - passes floats to Gear VR Function Library

Oculus Rift

To access these Blueprints, you must enable the Online Subsystem Oculus in Edit > Plugin > Online Platform.

The following Blueprints are available for Rift development:

• Add Oculus Rift Boundary Component - Creates a new Guardian System boundary component and assignsownership of it to an actor.

• Cast to Oculus Rift Boundary Component• Cast to Oculus Rift Boundary Component Class

Oculus Rift Input

To access these Blueprints, you must enable the Online Subsystem Oculus in Edit > Plugin > Online Platform.

• Gamepad events

• return Oculus Remote button events (bool)• return Oculus Touch button events (bool)

• Gamepad Values - return Oculus Touch values (floats)

Page 36: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

36 | Blueprints | Unreal

• Oculus Library - provides a number of Blueprints for querying and controlling splash screen, HMD pose,loading icon, user profile, raw sensor data, position scale, and more.

Oculus Touch

The following Blueprints are not Oculus-specific, but may be used to control haptics for the Xbox or OculusTouch controllers. For detailed information, see Haptics for Rift Controllers on page 18

• Play Haptic Effect• Stop Haptic Effect• Set Haptics by Value• Play Haptic Soundwave

Platform

To access these Blueprints, you must enable the Online Subsystem Oculus in Edit > Plugin > Online Platform.

• Verify Entitlements - verifies the user is authorized to run the application.• Get Oculus Identity - returns Oculus ID and Oculus username as strings; provides flow control for On

Success/On Failure

In this simple example of the Verify Entitlement Blueprint, the application will verify that the user has anentitlement when the application launches, and quit if the check fails. In reality, we recommend providing anappropriate error message before shutting down.

This example of the Get Oculus Identity Blueprint illustrates how to print the user’s Oculus ID to the log orscreen.

Page 37: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Blueprints | 37

Page 38: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

38 | Unreal Samples | Unreal

Unreal SamplesOculus provides samples which illustrate basic VR concepts in Unreal such as Touch, haptics, and the BoundaryComponent API for interacting with the Guardian System.

Samples are available from the Oculus Unreal GitHub repository.

All samples require a compatible version of the Unreal Engine which supports the illustrated features. Toexplore samples, we generally recommend using Unreal versions that we ship from our GitHub repository,which always include the latest features. For a review of which Unreal versions support which features, seeIntroduction and Version Compatibility on page 4.

Boundary Sample

BoundarySample is a Blueprint sample that illustrates the use of the Boundary Component API for interactingwith our Guardian System. This API allows developers to query the Guardian System trigger state, return theclosest boundary point to a queried device or point, and more.

In this sample, the Guardian System Boundary Area is visualized on the ground in orange-yellow, and the PlayArea is visualized on the ground in purple.

Two spheres track the Touch controllers. When they approach the Boundary Area, they project a colored arrowtoward the nearest sample point in the Guardian Area.

NewGameMode and VRCharacter are used to initialize the scene and make the scene display at theappropriate height, et cetera.

Controls and Behavior

These behaviors are controlled by the BoundarySampleMap, which you can use as a reference forimplementing related functionality.

Page 39: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Unreal Samples | 39

Test Control or Behavior

RequestOuterBoundaryVisible()Press 'V' on keyboard/right Touch button A to request boundaryon. Press 'X'/right Touch button B to cancel.

SetOuterBoundaryColor()Press 'G' on keyboard/left Touch button X to set boundary togreen. Press 'P'/left Touch button Y to make purple.

IsOuterBoundaryDisplayed()If so, cylinder is not visible.

IsOuterBoundaryTriggered()If so, cone is not visible (cone should remain if boundaries arerequested on by application).

GetTriggeredOuterBoundaryInfo()Visualize normals.

GetTriggeredPlayAreaInfo()Visualize normals.

OnOuterBoundaryTriggeredEvent

Cube made visible.

OnOuterBoundaryReturnedEvent

Cube made invisible.

Layer Sample

LayerSample is a Blueprint sample that illustrates the use of VR Compositor Layers to display a UMG UI.

This sample includes two spheres that track with the Touch controllers and two UMG widgets rendered as VRCompositor layers. One is rendered as a quad layer and the other as a cylinder layer.

Because cylinder layers are not currently supported on the Rift, note that the cylinder layer only appearscylindrical when viewed on Gear VR. When the scene is viewed on the Rift, you will only see a quad.

Page 40: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

40 | Unreal Samples | Unreal

Actor_Blueprint illustrates rendering a UMG widget into a stereo layer. The widget is first rendered into aMaterial, then the SlateUI texture is pulled from the Material into the stereo layer. This is the UMG widget thatis rendered to the quad and cylindrical layers in the sample.

Open MenuBlueprint to open the UMG widget in the UMG Editor.

NewGameMode and VRCharacter are used to initialize the scene and make the scene display at theappropriate height, et cetera.

Touch SampleTouchSample illustrates basic use of Oculus Touch including controller tracking and thumbstick control. It alsoillustrates haptics control using PlayHapticEffect() and PlayHapticSoundWave(). Two spheres track with theTouch controllers. The right controller thumbstick may be used to control the position of the light gray box.Touch capacitance sensors detect whether the right thumb is in a touch or near-touch position, which controlsthe height of the box. Press and hold the left Touch grip button to play a haptics clip. Press and hold the leftTouch X button to create a haptics effect by setting the haptics value directly.

Page 41: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Unreal Samples | 41

You will find the Haptics control Blueprint and the Thumbstick control Blueprint in the sample Level Blueprint.NewGameMode and VRCharacter are used to initialize the scene and make the scene display at theappropriate height, et cetera.

Page 42: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

42 | Testing and Performance Analysis in Unreal | Unreal

Testing and Performance Analysis in UnrealVR application debugging is a matter of getting insight into how the application is structured and executed,gathering data to evaluate actual performance, evaluating it against expectation, then methodically isolatingand eliminating problems.

When analyzing or debugging, it is crucial to proceed in a controlled way so that you know specifically whatchange results in a different outcome. Focus on bottlenecks first. Only compare apples to apples, and changeone thing at a time (e.g., resolution, hardware, quality, configuration).

Always be sure to profile, as systems are full of surprises. We recommend starting with simple code, andoptimizing as you go - don’t try to optimize too early.

Performance Targets

Before debugging performance problems, establish clear targets to use as a baseline for calibrating yourperformance.

These targets can give you a sense of where to aim, and what to look at if you’re not making frame rate or arehaving performance problems.

Below you will find some general guidelines for establishing your baselines, given as approximate ranges unlessotherwise noted.

Mobile

• 60 FPS (required by Oculus Store)• 50-100 draw calls per frame• 50,000-100,000 triangles or vertices per frame

PC

• 90 FPS (required by Oculus Store)• 500-1,000 draw calls per frame• 1-2 million triangles or vertices per frame

For more information, see:

• PC SDK Developer Guide• Mobile VR Application Development• Oculus Store Submission Requirements

• Oculus Rift App Requirements• Gear VR App Requirements

Rift Performance HUD

The Oculus Performance Heads-Up Display (HUD) is an important, easy-to-use tool for viewing timings forrender, latency, and performance headroom in real-time as you run an application in the Oculus Rift. TheHUD is easily accessible through the Oculus Debug Tool provided with the PC SDK. You may activate it in theViewport by pressing the ~ key.

For more details, see the Performance Heads-Up Display and Oculus Debug Tool sections of the Oculus RiftDevelopers Guide.

Page 43: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Testing and Performance Analysis in Unreal | 43

Debug Console (Mobile)

If your phone is set to Developer Mode, you may bring up a debug console for VR apps by pressing the screenwith four fingers simultaneously while the application is running.

Enter stat unit in the console for information about your application frame rate and CPU performance.

Oculus Remote Monitor (Mobile)

The Oculus Remote Monitor client connects to VR applications running on remote mobile devices to capture,store, and display the streamed-in data. The VrCapture library is automatically included in Unreal projects, sosetup and use of the Oculus Remote Monitor is easy.

Oculus Remote Monitor is available from our Downloads page. For more information about setup, features, anduse, see Oculus Remote Monitor in our Mobile SDK guide.

• The Frame Buffer Viewer provides a mechanism for inspecting the frame buffer as the data is received inreal-time, which is particularly useful for monitoring play test sessions. When enabled, the Capture librarywill stream a downscaled pre-distortion eye buffer across the network.

• The Performance Data Viewer provides real-time and offline inspection of the following on a single,contiguous timeline:

• CPU/GPU events• Sensor readings• Console messages, warnings, and errors• Frame buffer captures

• The Logging Viewer provides raw access to various messages and errors tracked by thread IDs.• Nearly any constant in your code may be turned into a knob that can be updated in real-time during a play

test.

Page 44: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

44 | Testing and Performance Analysis in Unreal | Unreal

GDB Debugging (Mobile)

Oculus branches of Unreal add support for debugging mobile sessions using ndk-gdb, a small shell scriptwrapped around GNU GDB that is included with the Android NDK.

Using ndk-gdb from the command line adds convenient features to your debugging workflow by allowing, forexample, adding breakpoints, stepping through code, and inspecting variables with a command line interface.

To use ndk-gdb for debugging:

1. Enable remote port forwarding to link your target mobile port to a PC port: adb forward tcp:$porttcp:$port

2. Set your device to Developer Mode (as described in our Mobile Developer Guide here).3. Launch the application you wish to debug.4. Start gdbserver on the mobile device with the following Unreal console command: gdbserver $port

where $port is your port number. You application should freeze, and will now be ready for debugging.5. Launch the ndk-gdb client from the command line on your computer with the command gdb.exe. When it

launches, type target remote :$port in the GDB command line to attach to your mobile device.

For more information on using GDB for debugging, see the GNU GDB documentation.

Additional Third-Party Tools

ETW + GPUView

Event Tracing for Windows (ETW) is a trace utility provided by Windows for performance analysis. GPUViewview provides a window into both GPU and CPU performance with DirectX applications. It is precise, has lowoverhead, and covers the whole Windows system. Custom event manifests.

ETW profiles the whole system, not just the GPU. For a sample debug workflow using ETW to investigatequeuing and system-level contention, see Example Workflow: PC below.

Windows 10 replaces ETW with Tracelogging.

Systrace

Reports complete Android system utilization. Available here: http://developer.android.com/tools/help/systrace.html

NVIDIA NSight

NSight is a CPU/GPU debug tool for NVIDIA users, available in a Visual Studio version and an Eclipse version.

Mac OpenGL Monitor

An OpenGL debugging and optimizing tool for OS X. Available here: https://developer.apple.com/library/mac/technotes/tn2178/_index.html#//apple_ref/doc/uid/DTS40007990

APITrace

https://apitrace.github.io/

Other Resources

For detailed information about Oculus development, go to:

• Unreal: Virtual Reality Development: https://docs.unrealengine.com/latest/INT/Platforms/VRZ/• Unreal: Oculus Rift wiki: https://wiki.unrealengine.com/Oculus_Rift• Oculus Forums/Unreal: https://forums.oculus.com/developer/categories/unreal• Unreal Forums/VR Development: https://forums.unrealengine.com/forumdisplay.php?27-VR-Development

Page 45: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Testing and Performance Analysis in Unreal | 45

Contact

Visit our developer support forums at https://developer.oculus.com.

Our Support Center can be accessed at https://support.oculus.com.

Page 46: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

46 | Release Notes | Unreal

Release NotesThis section describes changes for each version release.

Oculus Unreal Engine 4 Integration 1.12 ReleaseNotesThese release notes describe changes to Oculus's Unreal Engine 4.14 and 4.15 available from the OculusGitHub repository.

1.12.0

New Features

• Added support for Gear VR Controller. See Gear VR Controller on page 17 for more information.• Added Direct Multi-View support, which can substantially reduce GPU overhead. See Multi-View (Mobile) on

page 27 for more information.

Bug Fixes

• Fixed Adaptive Pixel Density flickering when ASW is enabled.

Known Issues

• A significant drop in frame rate occurs when UE4 is not in focus in VR preview mode. To avoid this issue,uncheck the Use Less CPU when in Background in Edit > Editor Preferences > General (left sidebar) >Miscellaneous (left sidebar) > Performance.

• Exclusive Mode issues: Setting the mirror window to full-screen exclusive mode will not work correctly if themonitor and HMD are connected to different GPUs.

• Stereo Layer Depth Ordering: Doesn’t support head-locked layers, only world-locked and tracker-locked.• Oculus Blueprints not visible in Level Blueprint in Epic launcher and Epic source versions when Gear

VR Plugin is enabled. Workaround for source version: open the file GearVR.uplugin and replace"WhitelistPlatforms" : ["Android"] with "WhitelistPlatforms" : [ "Android", "Win64", "Win32" ]. This doesnot affect source shipped through the Oculus Unreal GitHub repository.

Oculus Unreal Engine 4 Integration 1.11 ReleaseNotesThese release notes describe changes to Oculus's Unreal Engine 4.13, 4.14, and 4.15 available from the OculusGitHub repository.

1.11.0

Oculus distributes integrations of the Unreal Engine which include the latest Oculus SDKs to provide up-to-datesupport for Oculus Rift and Gear VR.

New Features

Page 47: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Release Notes | 47

• Added GDB debugging support. See “GDB” in Testing and Performance Analysis in Unreal on page 42 inUnreal for more information.

• Added three Blueprint samples, available from our GitHub repository. For more on how to access ourrepository, see our Developer Guide Introduction.

• BoundarySample illustrates use of the Boundary Component API for interacting with our GuardianSystem.

• LayerSample illustrates the use of VR Compositor Layers.• TouchSample illustrates basic use of Oculus Touch, including haptics.

• Online Subsystems

• LeaderboardInterface now allows for querying of just the user's entry by calling ReadLeaderboards() withan array of just the current user id.

• SessionInterface

• Added the ability to populate the LocalOwnerId with the current user.• DumpSessionState() now dumps out all individual existing named sessions.

Bug Fixes

• Added support for wire frame representation of objects while using the 11:11:10 LDR format• Online Subsystems

• AchievementInterface: Fixed casting WriteAchievement for Count values for Int64, UInt32, and UInt64.• Fixed bug preventing the UE4 Read Leaderboard blueprint node from working with the Oculus OSS.• SessionInterface: Fixed a NullPointerException when getting the oculus id from a session

• Allow for updating the Room Data Store through the UpdateSession(). Will save the UE4 SessionSettings into the Room Data Store.

• Fixed a bug causing TriggerMatchmakingCompleteDelegates to fire too early• Session.bHosting now returns if the current user is the host/owner of the session.

Known Issues

• Adaptive Pixel Density is not currently working and should be disabled. If applications using Adaptive PixelDensity reach 45 Hz, they will remain stuck at that frame rate until relaunched. A fix is planned for the Rift1.12 runtime release and should not require any application changes.

• A significant drop in frame rate occurs when UE4 is not in focus in VR preview mode. To avoid this issue,uncheck the Use Less CPU when in Background in Edit > Editor Preferences > General (left sidebar) >Miscellaneous (left sidebar) > Performance.

• Exclusive Mode issues: Multiple initializations of the DXGISwapChain may cause flickering as the screenswitches modes and a black screen when rendering to the Rift with a different GPU from the one the game isusing to render the eye buffers.

• Stereo Layer Depth Ordering: Doesn’t support head-locked layers, only world-locked and tracker-locked.• Oculus Blueprints not visible in Level Blueprint in Epic launcher and Epic source versions when Gear

VR Plugin is enabled. Workaround for source version: open the file GearVR.uplugin and replace"WhitelistPlatforms" : ["Android"] with "WhitelistPlatforms" : [ "Android", "Win64", "Win32" ]. This doesnot affect source shipped through the Oculus Unreal GitHub repository.

Page 48: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

48 | Release Notes | Unreal

Oculus Unreal Engine 4 Integration 1.10 ReleaseNotes

1.10.0

These release notes describe changes to Oculus's Unreal Engine 4.12, 4.13, and 4.14 available from the OculusGitHub repository.

New Features

• Added experimental multi-view support for mobile development, which reduces CPU overhead byduplicating objects to both eye buffers during rendering. Currently supports Note5, S6, S7, and S7 Edgephones running Android M or N and using ARM Exynos processors. Requires OpenGL ES 2. For moreinformation, see Multi-View in Unreal Mobile Development on page 13.

• Added “Browse” matchmaking support in OnlineSessionOculus.

• Added ability to create a matchmaking room.• Added ability to find matchmaking rooms in Browse mode.• Added Blueprints to Create and Find matchmaking rooms.

Bug Fixes

• Fixed Oculus Blueprints error calling Activate() twice.• Fixed crash when Oculus Cloud Saves used when the application is not installed.

Known Issues

• A significant drop in framerate occurs when UE4 is not in focus in VR preview mode. To avoid this issue,uncheck the Use Less CPU when in Background in Edit > Editor Preferences > General (left sidebar) >Miscellaneous (left sidebar) > Performance.

• Exclusive Mode issues: Multiple initializations of the DXGISwapChain may cause flickering as the screenswitches modes and a black screen when rendering to the Rift with a different GPU from the one the game isusing to render the eye buffers.

• Stereo Layer Depth Ordering: Doesn’t support head-locked layers, only world-locked and tracker-locked.

Oculus Unreal Engine 4 Integration 1.9 ReleaseNotes

1.9.0

These release notes describe changes to Oculus's Unreal Engine 4.12 and 4.13 available from the OculusGitHub repository.

New Features

• Added VoIP and moderated room finding/joining support, available through the Online Subsystemsinterface. For more information, see Oculus Platform Features and Online Subsystems on page 30.

Bug Fixes

Page 49: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Release Notes | 49

• Fixed near clipping plane calculation, which was incorrect when WorldToMetersScale was set to a valueother than 100.

Known Issues

• UE4.12 and 4.13 in Oculus GitHub repository: A significant drop in frame rate occurs when UE4 is not infocus in VR preview mode. To avoid this issue, uncheck the Use Less CPU when in Background in Edit >Editor Preferences > General (left sidebar) > Miscellaneous (left sidebar) > Performance.

• Exclusive Mode issues: Multiple initializations of the DXGISwapChain may cause flickering as the screenswitches modes and a black screen when rendering to the Rift with a different GPU from the one the game isusing to render the eye buffers.

• Stereo Layer Position Type: World Locked is not currently supported for cylinder TimeWarp overlays.

Oculus Unreal Engine 4 Integration 1.8 ReleaseNotes

1.8.0

These release notes describe changes to the Unreal Engine versions 4.12 and 4.13 available from the OculusGitHub repository.

The Oculus UE4 integration ships with various versions of Unreal, and there is no external SDK per se. Clickingon the "Download" link above will redirect you to our Introduction and Version Compatibility on page 4, whichwalks through various options for working with the Oculus Unreal integration.

Unreal provides built-in support for Oculus Rift and Gear VR development on Windows, and Unreal apps run onthe Oculus platform automatically apply stereoscopic rendering to the main camera as well as positional andorientation tracking for the Rift, or orientation tracking for Gear VR.

New Features

• Added support for the Oculus Guardian System, which visualizes the bounds of a user-defined Play Area.Note that it is currently unsupported by public versions of the Oculus runtime. See Guardian SystemBoundary Component on page 21 for more information.

• Added depth ordering support to VR compositor layers.• Added cubemap support for VR compositor overlays to 4.13 (mobile only).• Added Online Subsystem support for Regular Leaderboards and Cloudsaves.• Added a Blueprint for retrieving Oculus ID/Username.• Added Blueprints for UOculusRiftBoundaryComponent public methods.

API Changes

• Added OculusRiftBoundaryComponent API for the Oculus Guardian System.

Bug Fixes

• Fixed black screen issue affecting Samsung Note4 and certain Adreno-based devices.

Known Issues

• UE4.12 and 4.13 in Oculus GitHub repository: A significant drop in frame rate occurs when UE4 is not infocus in VR preview mode. To avoid this issue, uncheck the Use Less CPU when in Background in Edit >Editor Preferences > General (left sidebar) > Miscellaneous (left sidebar) > Performance.

Page 50: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

50 | Release Notes | Unreal

• Exclusive Mode issues: Multiple initializations of the DXGISwapChain may cause flickering as the screenswitches modes and a black screen when rendering to the Rift with a different GPU from the one the game isusing to render the eye buffers.

• Stereo Layer Position Type: World Locked is not currently supported for cylinder TimeWarp overlays.

Oculus Unreal Engine 4 Integration 1.7 ReleaseNotes

1.7.0

Unreal provides built-in support for Oculus Rift and Gear VR development on Windows.

Unreal apps run on the Oculus platform automatically apply stereoscopic rendering to the main camera as wellas positional and orientation tracking for the Rift, or orientation tracking for Gear VR.

For more information on downloading and using the Oculus Unreal integration, please see Introduction andVersion Compatibility on page 4.

Online Subsystems

Several features of the Oculus Platform SDK may be accessed through the Unreal Online Subsystems interface:

• Achievements• Rooms• Matchmaking• Identity• Entitlements• P2P networking• Friends leaderboards

Friends leaderboards is not currently available through Online Subsystems in Epic’s 4.13 Preview build.

Not all functionality of these features is available through the Online Subsystems interface. Developers whoneed unsupported features should use the Oculus Platform Plugin available with our Platform SDK.

Online Subsystems access is available in the following ways:

• Oculus Platform SDK v. 1.6 and 1.7 include a standalone OSS plugin (Rift only)• Epic GitHub: 4.13.0-preview-2 includes OSS support (Rift and Gear VR)• Oculus GitHub: oculus-4.12.5-release-1.7.0 and oculus-4.13.0-preview-2-1.7.0 includes OSS support (Rift

and Gear VR)

For more information on Unreal Subsystems, see Epic’s Online Subsystems Overview.

New Features

• Added adaptive viewport scaling, which automatically changes pixel density based on resource availability,with configurable min/max. See Unreal Console Commands on page 33 for details. (Rift only)

• Added Oculus Platform SDK support to mobile VR applications to 4.12 and 4.13 in the Oculus repository.• Added Blueprint for Oculus Platform entitlement checks (available in SI 1.6).• A subset of Oculus Platform features are now available through the Unreal Online Subsystems interface.

Page 51: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Release Notes | 51

• Added cylinder TimeWarp overlay support (Gear VR only) for UI components, etc. For more information, seeVR Compositor Layers on page 25.

• Added ability develop using GearVR plugin and Mobile renderer on the PC using the Oculus Rift. To use,disable OculusRift and SteamVR plugins for your project, and add -OpenGL -FeatureLevelES2 to yourcommand line.

API Changes

• Added Cylinder layer type to FHMDLayerDesc in HeadMountedDisplayCommon.h.• In IInputInterface.h, FHapticFeedbackBuffer uint8* RawData was changed to TArray<uint8> RawData, and

uint8 *CurrentPtr; was changed to uint32 CurrentPtr.• IInputInterface::SetHapticFeedbackBuffer was removed and HapticBuffer was added to

FHapticFeedbackValues::FHapticFeedbackBuffer* HapticBuffer. You should now useIInputInterface::SetHapticFeedbackValues, whether you are using a buffer or not.

• APlayerController::SetHatpicsByValue calls to Oculus Touch are now limited to 30 per second due toperformance issues. Additional calls with a value other than zero (i.e., stop commands) are discarded uponreceipt.

Known Issues

• UE4.12 and 4.13 in Oculus GitHub repository: A significant drop in frame rate occurs when UE4 is not infocus in VR preview mode. To avoid this issue, uncheck the Use Less CPU when in Background in Edit >Editor Preferences > General (left sidebar) > Miscellaneous (left sidebar) > Performance.

• Stereo Layer Position Type: World Locked is not currently supported for cylinder TimeWarp overlays.

Oculus Unreal Engine 4 Integration 1.6 ReleaseNotes

1.6.0

Unreal provides built-in support for Oculus Rift and Gear VR development on Windows.

Unreal apps run on the Oculus platform automatically apply stereoscopic rendering to the main camera as wellas positional and orientation tracking for the Rift, or orientation tracking for Gear VR.

For more information on downloading and using the Oculus Unreal integration, please see Introduction andVersion Compatibility on page 4.

The Wwise redirection patch is no longer required in Unreal Engine 4.11 or 4.12. Requires the WwiseUE4Pluginfrom AudioKinetic’s ‘master’ branch on GitHub.

4.12

New Features

• Added adaptive viewport scaling, which automatically changes pixel density based on resource availability,with configurable min/max. See Unreal Console Commands on page 33 for details. (Rift only) UPDATE: Thisfeature has been delayed until a future release.

• Added Blueprints plugin that supports calls for Gear VR functionality such as GPU/GPU throttling, queryingheadphone connection, querying device temperature, and more.

• Added Blueprint for Oculus Platform entitlement checks.

API Changes

Page 52: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

52 | Release Notes | Unreal

• Oculus Touch: Added PlayHapticsSoundwave to Blueprints, which permits playback of soundwaves (storedin UE4 in USoundWave assets) directly to the Oculus Touch controller.

• Added SetHapticFeedbackBuffer to the C++ Haptics interface, to submit byte arrays to be played at 320 Hzon the Oculus Touch controller.

Bug Fixes

• Fixed bug where unfocused Wwise apps continued playing audio. Requires the WwiseUE4Plugin fromAudioKinetic’s ‘master’ branch on Github.

4.11

New Features

• Added adaptive viewport scaling, which automatically changes pixel density based on resource availability,with configurable min/max. See Unreal Console Commands on page 33 for details. (Rift only) UPDATE: Thisfeature has been delayed until a future release.

API Changes

• Oculus Touch: Added PlayHapticsSoundwave to Blueprints, which permits playback of soundwaves (storedin UE4 in USoundWave assets) directly to the Touch controller.

• Added SetHapticFeedbackBuffer to the C++ Haptics interface, to submit byte arrays to be played at 320 Hzon the Touch controller.

Bug Fixes

• Fixed bug where unfocused Wwise apps continued playing audio. Requires the WwiseUE4Plugin fromAudioKinetic’s ‘master’ branch on GitHub.

Oculus Unreal Engine 4 Integration 1.5 ReleaseNotes

1.5.0

Unreal provides built-in support for Oculus Rift and Gear VR development on Windows.

Unreal apps run on the Oculus platform automatically apply stereoscopic rendering to the main camera as wellas positional and orientation tracking for the Rift, or orientation tracking for Gear VR.

For more information on downloading and using the Oculus Unreal integration, please see Introduction andVersion Compatibility on page 4.

4.12

New Features

• Added async splash (Gear VR).• Refactored layers management (Gear VR).• Enabled default loading icon mode (Gear VR).• Added ability to capture cube maps for Oculus Store preview (see Unreal Console Commands on page 33

for usage instructions).• Added call ovr_IdentifyClient to identify client to service.• Added OnlineSubsystemOculus to interface Oculus platform.

Page 53: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

Unreal | Release Notes | 53

API Changes

• Added GetNumOfTrackingSensors / GetTrackingSensorProperies to IHeadMountedDisplay.

Bug Fixes

• Fixed issue with BeginPlay.• Fixed rounding error that could cause incorrect viewport sizes.• Now use ovr_GetSessionStatus() instead of SubmitFrame result to determine VR focus.• Fixed crash creating HMD when it is attached to D3D11 adapter with no other monitors.• Fixed issue where IHeadMountedDisplayModule::IsHMDConnected would be called more than necessary.

4.11

New Features

• Added async splash (Gear VR).• Refactored layers management (Gear VR).• Enabled default loading icon mode (Gear VR).• Added ability to capture cube maps for Oculus Store preview (see Unreal Console Commands on page 33

for usage instructions).• Added ovr_IdentifyClient call to identify client to service.

API Changes

• Added GetNumOfTrackingSensors / GetTrackingSensorProperies to IHeadMountedDisplay.

Bug Fixes

• Now uses ovr_GetSessionStatus() instead of SubmitFrame result to determine VR focus.• Fixed issue where IHeadMountedDisplayModule::IsHMDConnected would be called more than necessary.

Oculus Unreal Engine 4 Integration 1.4 ReleaseNotes

1.3.2

Unreal provides built-in support for Oculus Rift and Gear VR development on Windows.

Unreal apps run on the Oculus platform automatically apply stereoscopic rendering to the main camera as wellas positional and orientation tracking for the Rift, or orientation tracking for Gear VR.

For more information on downloading and using the Oculus Unreal integration, please see Introduction andVersion Compatibility on page 4.

New Features

• Updated integration up to 4.11.2.• Added Oculus Rift video layer support to 4.11 integration.• Upgraded Oculus Mobile SDK to VrApi 1.0.2; Volume Control layer is now rendered correctly.

Page 54: Unreal - Oculus VRstatic.oculus.com/documentation/pdfs/unreal/1.12/unreal.pdf · Oculus Unreal Engine 4 Integration 1.4 Release Notes..... 53 Oculus Unreal Engine 4 Integration 1.3

54 | Release Notes | Unreal

Bug Fixes

• Fixed potential Gear VR crash when EnterVRMode is called before RenderThread is started.• Switched LOD calculation from view-vector dot product to pure distance for more consistent result

(otherwise, LOD could be different for each eye).• Fixed incorrect logic for ATW splash rotation (PC).

Known Issues

• Mirror window may appear stretched with hmd mirror mode 2 until you switch focus to another applicationand back.

Oculus Unreal Engine 4 Integration 1.3 ReleaseNotes

1.3.2

Unreal provides built-in support for Oculus Rift and Gear VR development on Windows.

Unreal apps run on the Oculus platform automatically apply stereoscopic rendering to the main camera as wellas positional and orientation tracking for the Rift, or orientation tracking for Gear VR.

For more information on downloading and using the Oculus Unreal integration, please see Introduction andVersion Compatibility on page 4.

New Features

• Updated integration up to 4.11.1 and 4.10.4.• Added quad layer support for Gear VR.• Added Gear VR video layer support to 4.11 integration.• Separated Alt-Enter from switching between stereo/mono; currently, Alt-Enter switches between fullscreen/

windowed mode for mirror window.• Added proper support for fullscreen mirror window.

Bug Fixes

• Fixed base orientation issue with quad layers rendering.• Fixed Steam VR compatibility issue.• Fixed Oculus Touch haptic logic: vibration won’t be send to Oculus Touch unless the controllers are

currently active.