= Virtual Reality Legacy support
:revnumber: 2.0
:revdate: 2020/07/27


== Introduction

The jMonkeyEngine module jme3-vr is deprecated and will be removed in a future version. This documents that deprecated functionality.

jMonkeyEngine 3 supports several VR specifications. The most modern of those is OpenVR, which is currently a widely supported standard. However, vendors are beginning to move towards OpenXR as a fully open cross-platform standard. OpenXR is available with jMonkeyEngine via xref:contributions:vr/topic_contributions_vr.adoc[user contributed virtual reality libraries].

The known supported systems are:

HTC Vive and systems supporting SteamVR/OpenVR

Native Oculus Rift support (and through SteamVR)

Oculus Quest 2 (through SteamVR with Virtual Desktop)

Razer HDK and systems supporting OSVR

Google Cardboard / GoogleVR

Two implementations exist for OpenVR. A community maintained JNA based binding and LWJGL's JNI based.

To use the JNA based bindings, put:

    settings.put(VRConstants.SETTING_VRAPI, VRConstants.SETTING_VRAPI_OPENVR_VALUE);

in your settings. To use LWJGL, instead put:

    settings.put(VRConstants.SETTING_VRAPI, VRConstants.SETTING_VRAPI_OPENVR_LWJGL_VALUE);

Note that the LWJGL bindings require LWJGL3 (jme3-lwjgl3) to be used.

== Required dependencies

    - org.jmonkeyengine:jme3-core
    - org.jmonkeyengine:jme3-lwjgl3
    - org.jmonkeyengine:jme3-vr

== Sample Application

[source,java]
----
public class Main extends SimpleApplication {

    public static void main(String[] args) {
        AppSettings settings = new AppSettings(true);
        settings.put(VRConstants.SETTING_VRAPI, VRConstants.SETTING_VRAPI_OPENVR_LWJGL_VALUE);
        settings.put(VRConstants.SETTING_ENABLE_MIRROR_WINDOW, true);

        VREnvironment env = new VREnvironment(settings);
        env.initialize();

    	// Checking if the VR environment is well initialized
    	// (access to the underlying VR system is effective, VR devices are detected).
    	if (env.isInitialized()){
            VRAppState vrAppState = new VRAppState(settings, env);
            vrAppState.setMirrorWindowSize(1024, 800);
            Main app = new Main(vrAppState);
            app.setLostFocusBehavior(LostFocusBehavior.Disabled);
            app.setSettings(settings);
            app.setShowSettings(false);
            app.start();
        }
    }

    public Main(AppState... appStates) {
        super(appStates);
    }

    @Override
    public void simpleInitApp() {
        Box b = new Box(1, 1, 1);
        Geometry geom = new Geometry("Box", b);

        Material mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
        mat.setColor("Color", ColorRGBA.Blue);
        geom.setMaterial(mat);

        rootNode.attachChild(geom);
    }

    @Override
    public void simpleUpdate(float tpf) {
        //TODO: add update code
    }

    @Override
    public void simpleRender(RenderManager rm) {
        //TODO: add render code
    }
}
----
Project source: https://github.com/neph1/VRSampleApplication


== Google Cardboard VR SDK 1.0 integration
gvr-android-jme (https://github.com/nordfalk/gvr-android-jme)


== Legacy
The following projects are not up to date, but may provide functionality not found in the other packages.
Google Cardboard up to version 0.6: https://github.com/neph1/jme-cardboard