1# OpenHMD 2This project aims to provide a Free and Open Source API and drivers for immersive technology, such as head mounted displays with built in head tracking. 3 4## License 5OpenHMD is released under the permissive Boost Software License (see LICENSE for more information), to make sure it can be linked and distributed with both free and non-free software. While it doesn't require contribution from the users, it is still very appreciated. 6 7## Supported Devices 8For a full list of supported devices please check https://github.com/OpenHMD/OpenHMD/wiki/Support-List 9 10## Supported Platforms 11 * Linux 12 * Windows 13 * OS X 14 * Android 15 * FreeBSD 16 17## Requirements 18 * Option 1: Meson + Ninja 19 * http://mesonbuild.com 20 * https://ninja-build.org 21 * Option 2: GNU Autotools (if you're building from the git repository) 22 * Option 3: CMake 23 * HIDAPI 24 * http://www.signal11.us/oss/hidapi/ 25 * https://github.com/signal11/hidapi/ 26 27## Language Bindings 28 * GO bindings by Marko (Apfel) 29 * https://github.com/Apfel/OpenHMD-GO 30 * Java bindings by Joey Ferwerda and Koen Mertens 31 * https://github.com/OpenHMD/OpenHMD-Java 32 * .NET bindings by Jurrien Fakkeldij 33 * https://github.com/jurrien-fakkeldij/OpenHMD.NET 34 * Perl bindings by CandyAngel 35 * https://github.com/CandyAngel/perl-openhmd 36 * Python bindings by Lubosz Sarnecki 37 * https://github.com/lubosz/python-rift 38 * Rust bindings by The\_HellBox 39 * https://github.com/TheHellBox/openhmd-rs 40 41## Other FOSS HMD Drivers 42 * libvr - http://hg.sitedethib.com/libvr 43 44## Compiling and Installing 45Using Meson: 46 47With Meson, you can enable and disable drivers to compile OpenHMD with. 48Current available drivers are: rift, deepon, psvr, vive, nolo, wmr, external, and android. 49These can be enabled or disabled by adding -Ddrivers=... with a comma separated list after the meson command (or using meson configure ./build -Ddrivers=...). 50By default all drivers except android are enabled. 51 52 meson ./build [-Dexamples=simple,opengl] 53 ninja -C ./build 54 sudo ninja -C ./build install 55 56Using make: 57 58 ./autogen.sh # (if you're building from the git repository) 59 ./configure [--enable-openglexample] 60 make 61 sudo make install 62 63Using CMake: 64 65With CMake, you can enable and disable drivers to compile OpenHMD with. 66Current Available drivers are: OPENHMD_DRIVER_OCULUS_RIFT, OPENHMD_DRIVER_DEEPOON, OPENHMD_DRIVER_WMR, OPENHMD_DRIVER_PSVR, OPENHMD_DRIVER_HTC_VIVE, OPENHMD_DRIVER_NOLO, OPENHMD_DRIVER_EXTERNAL and OPENHMD_DRIVER_ANDROID. 67These can be enabled or disabled adding -DDRIVER_OF_CHOICE=ON after the cmake command (or using cmake-gui). 68 69 mkdir build 70 cd build 71 cmake .. 72 make 73 sudo make install 74 75### Configuring udev on Linux 76To avoid having to run your applications as root to access USB devices you have to add a udev rule (this will be included in .deb packages, etc). 77 78A full list of known usb devices and instructions on how to add them can be found on: 79https://github.com/OpenHMD/OpenHMD/wiki/Udev-rules-list 80 81After this you have to unplug your device and plug it back in. You should now be able to access the HMD as a normal user. 82 83### Compiling on Windows 84CMake has a lot of generators available for IDE's and build systems. 85The easiest way to find one that fits your system is by checking the supported generators for you CMake version online. 86Example using VC2013. 87 88 cmake . -G "Visual Studio 12 2013 Win64" 89 90This will generate a project file for Visual Studio 2013 for 64 bit systems. 91Open the project file and compile as you usually would do. 92 93### Cross compiling for windows using mingw 94Using Make: 95 96 export PREFIX=/usr/i686-w64-mingw32/ (or whatever your mingw path is) 97 PKG_CONFIG_LIBDIR=$PREFIX/lib/pkgconfig ./configure --build=`gcc -dumpmachine` --host=i686-w64-mingw32 --prefix=$PREFIX 98 make 99 100the library will end up in the .lib directory, you can use microsoft's lib.exe to make a .lib file for it 101 102Using CMake: 103 104For MinGW cross compiling, toolchain files tend to be the best solution. 105Please check the CMake documentation on how to do this. 106A starting point might be the CMake wiki: http://www.vtk.org/Wiki/CmakeMingw 107 108### Static linking on windows 109If you're linking statically with OpenHMD using windows/mingw you have to make sure the macro OHMD_STATIC is set before including openhmd.h. In GCC this can be done by adding the compiler flag -DOHMD_STATIC, and with msvc it can be done using /DOHMD_STATIC. 110 111Note that this is *only* if you're linking statically! If you're using the DLL then you *must not* define OHMD_STATIC. (If you're not sure then you're probably linking dynamically and won't have to worry about this). 112 113## Pre-built packages 114A list of pre-built backages can be found on http://www.openhmd.net/index.php/download/ 115 116## Using OpenHMD 117See the examples/ subdirectory for usage examples. The OpenGL example is not built by default, to build it use the --enable-openglexample option for the configure script. It requires SDL2, glew and OpenGL. 118 119An API reference can be generated using doxygen and is also available here: http://openhmd.net/doxygen/0.1.0/openhmd_8h.html 120