DirectPreview

Introduction

In the development process, repeatedly building APKs in Unreal is time-consuming. Direct Preview lets you skip the building process. You can preview in both Unreal Editor and your HMD device simultaneously.

Note

The rendering path for Android applications differs substantially from the rendering path used for game previews, and you may notice important differences in the look-and-feel and performance.

Contents

Architecture

../_images/Architecture_unreal.png

Direct Preview is separated into three parts:

  • dpServer

dpServer takes over the Unreal textures and the poses sent from wvr_plugins_directpreview.dll. And then, dpServer encodes these information and sends them to target device.

  • wvr_plugins_directpreview_agent_unreal.apk on your target device

There are 2 major tasks in wvr_plugins_directpreview_agent_unreal.apk.

  1. wvr_plugins_directpreview_agent_unreal.apk gets all data like pose, event and state of the HMD/controllers and sends to wvr_plugins_directpreview.dll via USB/Wifi.
  2. wvr_plugins_directpreview_agent_unreal.apk also takes over the images sent from dpServer, decodes the images, and displays the images on your target device.
  • wvr_plugins_directpreview.dll

Unreal editor will load wvr_plugins_directpreview.dll once you start VR preview. After initialization and connection, it provides all data (pose, event and state of device) from wvr_plugins_directpreview_agent_unreal.apk to Unreal which operates all routines and draws images on texture. After drawing texture is completed, wvr_plugins_directpreview.dll will send texture images from Unreal with corresponding pose data to dpServer.

Project Settings

You can navigate to setting page through Edit > Project Settings > Plugins > Wave VR > Direct Preview.

../_images/DP_ConnectTypeWiFi.png

Another alternative way is through the shortcut WaveVR > Plugin Settings.

../_images/DP_WaveVR_Tab.png

Preview in Editor only with USB

  • Project Settings

    • Connect Type

      Select USB.

      ../_images/DP_ConnectTypeUSB.png
  • How to Use

    1. Click WaveVR > Install Device APK

    The wvr_plugins_directpreview_agent_unreal.apk will be installed automatically to the HMD and create a “config.json” in the path “/sdcard/DirectPreview” in the HMD.

    1. Click WaveVR > Start Device APK

    The wvr_plugins_directpreview_agent_unreal.apk will be launched and show “Connecting…” or “Connection timeout”. If the app did not be launched, please check again that you can execute adb.exe in windows command prompt and go back to the step1 above.

    Note

    Connection timeout” is for Wi-Fi type, it doesn’t matter to USB type.

    Note

    If the Device APK did not launched and already make sure adb.exe is executable, please use command “adb shell pm list package | findstr agent” to check if package com.htc.vr.directpreview.agent.unreal is in the list. If yes, try “adb shell am start -n com.htc.vr.directpreview.agent.unreal/com.vive.rrclient.RRClient” to launch it manually. If not, please check if <Your Project Folder>/Plugins/WaveVR/Prebuilt/DirectPreview/deviceAPK/wvr_plugins_directpreview_agent_unreal.apk exist and use “adb install wvr_plugins_directpreview_agent_unreal.apk” to install it manually.

    1. Click the “VR Preview” button to open the preview window.

    Click Play Settings then choose VR Preview.

    ../_images/DP_VRPreview.png

    Then here comes the preview.

    ../_images/DP_VRPreviewScene.png

    Note

    Please ensure the P-sensor is covered during preview to keep the HMD awake or the tracking data will be lost.

Preview not only in Editor but also in HMD with Wi-Fi

  • Project Settings

    • Connect Type

      Select Wi-Fi.

      ../_images/DP_ConnectTypeWiFi.png
    • Device Wi-Fi IP

      Fill in the HMD’s Wi-Fi IP.

    • Render Target Device Name

      Assign which render target device is using. Please re-install Device APK if you change the device name.

      Note

      It will cause abnormal rendering if choosing the wrong Render target.

    • Enable preview image

      Enable to show preview in HMD. Or, the preview will just show in Editor only.

    • Update frequency

      Choose how many images per second are sent to the HMD based on network conditions. Choose from: Runtime defined, 15 FPS, 30 FPS, 45 FPS, 60 FPS, and 75 FPS. When “Runtime defined” is selected, the FPS will be set to the default refresh rate of the HMD. If the HMD default refresh rate is not supported or doesn’t exist, Update frequency will be set to 75 FPS.

      Note

      FPS here means how fast dpServer sends images to the APK. It does not mean the scene rendering speed in Unreal Editor.

    • Regularly save images

      Enable to regularly save VR Preview’s picture to D:/dp_unreal_image_<number>.jpg.

    • Rendered Quality (Recommended)

      You can increase the Editor > Preference > Level Editor > Play > New Viewport Resolution to get better rendered quality. Please note that the New Viewport Resolution is limited to the resolution of your monitor.

      ../_images/NewViewportResolution.png
  • How to Use

    ../_images/DP_WaveVR_Tab.png
    1. Click WaveVR > Install Device APK (with USB connected)

    The wvr_plugins_directpreview_agent_unreal.apk will be installed automatically to the HMD and create a “config.json” in the path “/sdcard/DirectPreview” in the HMD.

    1. Click WaveVR > Start DPServer
    ../_images/DP_DPServerWindowStartServer.png

    Note

    Developer can manually start dpServer.exe in <Your Project Folder>/Plugins/WaveVR/Prebuilt/DirectPreview/dpServer/ in case automatically start failed or whenever the command window disappear right after executing. You may need to update your graphic card driver if it showed like this:

    ../_images/DP_DPServerStartFail.png
    1. Click WaveVR > Start Device APK (with USB connected)

    The wvr_plugins_directpreview_agent_unreal.apk will be launched and show “Connecting…”. If the app did not be launched, please check again that you can execute adb.exe in windows command prompt and go back to the step1 above.

    Note

    If the Device APK did not launched and already make sure adb.exe is executable, please use command “adb shell pm list package | findstr agent” to check if package com.htc.vr.directpreview.agent.unreal is in the list. If yes, try “adb shell am start -n com.htc.vr.directpreview.agent.unreal/com.vive.rrclient.RRClient” to launch it manually. If not, please check if <Your Project Folder>/Plugins/WaveVR/Prebuilt/DirectPreview/deviceAPK/wvr_plugins_directpreview_agent_unreal.apk exist and use “adb install wvr_plugins_directpreview_agent_unreal.apk” to install it manually.

    Then, the dpServer window will show client connects and keep streaming logs. It means the connecting process is success.

    ../_images/DP_DPServerWindowStartDeviceApp.png
    1. Click the “VR Preview” button to open the preview window.

    Click Play Settings then choose VR Preview.

    ../_images/DP_VRPreview.png

    Then here comes the preview. And you will see the preview in HMD as well if Enable preview image is selected.

    ../_images/DP_VRPreviewScene.png

    Note

    Please ensure the P-sensor is covered during preview to keep the HMD awake or the tracking data will be lost.

    1. Please click WaveVR > Stop Device APK (with USB connected) and WaveVR > Stop DPServer to close the whole process completely.

Troubleshooting

  1. If the preview window showed abnormally compared with the above one like these two cases:
../_images/DP_Troubleshooting1.png ../_images/DP_Troubleshooting2.png

Please navigate to Editor > Editor Preferences > Level Editor > Play > New Viewport Resolution and enlarge it to resolve this problem.

../_images/NewViewportResolution.png
  1. [UE4.27] If the right eye of preview window showed abnormally compared with the above one like this:
../_images/DP_RighEyeBroken.png

Please navigate to Editor > Project Settings > Engine > Rendering > VR > Instanced Stereo and ENABLE it to resolve this problem.

../_images/EnableInstancedStereo.png
  1. [UE4.26] If the preview window showed as non-stereo like this:
../_images/DP_NonStereo.png

Please navigate to Editor > Project Settings > Engine > Rendering > VR > Instanced Stereo and DISABLE it to resolve this problem.

../_images/DisableInstancedStereo.png