OCULUS VR, LLC
Oculus Developer Guide
SDK Version 0.4
Date:
July 23, 2014
2014 Oculus VR, LLC. All rights reserved.
Oculus VR, LLC
Irvine CA
Except as otherwise permitted by Oculus VR, LLC (”Oculus”) , this publication, or parts thereof, may not be
reproduced in any form, by any method, for any purpose. Certain materials included in this publication are
reprinted with the permission of the copyright holder.
All brand names, product names or trademarks belong to their respective holders.
Disclaimer
THIS PUBLICATION AND THE INFORMATION CONTAINED HEREIN IS MADE AVAILABLE BY
OCULUS VR, LLC AS IS. OCULUS VR, LLC DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABIL-
ITY OR FITNESS FOR A PARTICULAR PURPOSE REGARDING THESE MATERIALS.
1
Contents
1 Introduction 5
2 Introducing DK2 and SDK 0.4 5
3 Oculus Rift Hardware Setup 7
3.1 Oculus Rift DK1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2 Oculus Rift DK2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.3 Monitor Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4 Oculus Rift SDK Setup 9
4.1 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.1.1 Operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.1.2 Minimum system requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.3 Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.4 Compiler Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.5 Makefiles, Projects, and Build Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.5.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.5.2 MacOS (Coming Soon) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.5.3 Linux (Coming Soon) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.6 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5 Getting Started 12
5.1 OculusWorldDemo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.1.1 Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.1.2 Using OculusWorldDemo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.2 Using the SDK Beyond the OculusWorldDemo . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2.1 Software developers and integration engineers . . . . . . . . . . . . . . . . . . . . . 15
5.2.2 Artists and game designers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6 LibOVR Integration Outline 17
6.1 Integration tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2
7 Initialization and Sensor Enumeration 18
7.1 Head tracking and sensors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
7.1.1 Position Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.1.2 User input integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.2 Health and Safety Warning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
8 Rendering to the Oculus Rift 25
8.1 Stereo rendering concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
8.2 SDK distortion rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.2.1 Render texture initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8.2.2 Configure rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
8.2.3 Frame rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
8.2.4 Frame timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
8.3 Client distortion rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
8.3.1 Setting up rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
8.3.2 Setting up distortion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
8.3.3 Game rendering loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.4 Multi-threaded engine support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
8.4.1 Update and render on different threads . . . . . . . . . . . . . . . . . . . . . . . . . 38
8.4.2 Render on different threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
8.5 Advanced rendering configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
8.5.1 Render target size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
8.5.2 Forcing a symmetrical field of view . . . . . . . . . . . . . . . . . . . . . . . . . . 42
8.5.3 Improving performance by decreasing pixel density . . . . . . . . . . . . . . . . . . 44
8.5.4 Improving performance by decreasing field of view . . . . . . . . . . . . . . . . . . 45
8.5.5 Improving performance by rendering in mono . . . . . . . . . . . . . . . . . . . . . 46
A Oculus API Changes 48
A.1 Changes since release 0.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
A.2 Changes since release 0.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
B Display Device Management 51
B.1 Display Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
3
B.2 Display Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
B.2.1 Duplicate display mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
B.2.2 Extended display mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
B.2.3 Standalone display mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
B.3 Selecting A Display Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
B.3.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
B.3.2 MacOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
B.4 Rift Display Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
B.4.1 Duplicate mode VSync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
B.4.2 Extended mode problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
B.4.3 Observing Rift output on a monitor . . . . . . . . . . . . . . . . . . . . . . . . . . 56
B.4.4 Windows: Direct3D enumeration . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
C Chromatic Aberration 57
C.1 Correction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
C.2 Sub-channel aberration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
D SDK Samples and Gamepad Usage 58
E Low-Level Sensor Details 60
E.0.1 Sensor Fusion Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
4
