1 - Getting Started

1.1 Machine Configuration

Operating System
  • Windows PC with Windows 7 (32-bit or 64-bit) or newer
Hardware
Development Environment

1.2 Unity Project Configuration

To enable VRWorks in your projects you need to:

  • Import VRWorks package from the asset store
  • In VR projects select "Single pass stereo" option in Player Settings
  • Use forward rendering

NOTE: Version 1.0.0 is PC only and supports only forward rendering using DirectX 11.


2 - INTEGRATING PLUGIN WITH YOUR VR EXPERIENCE

2.1 Adding VRWorks Script to your Scene

VRWorks plugin comes with two C# scripts VRWorks and VRWorksPresent located in Assets\Plugins\VRWorks\Scripts folder. Both of these scripts need to be attached to the main camera in order for VRWorks to work properly. Please make sure that VRWorksPresent is attached after all image effects since it needs to execute last in order to present correct image on the screen. In addition to C# scripts VRWorks also contains native plugin GfxPluginVRWorks32/64.DLL located in Assets\Plugins\VRWorks\Plugins\x86/_64 folders. Please make sure that DLLs are correctly imported in your project and assigned to correct platform (either 32 or 64 bit).

If VRWorks is integrated correctly in your project you should see the following message in the editor console window once you press play:

  
  VRWorks: MRS SPS LMS detected
  

NOTE:You might see different set of features depending on what sort of GPU configuration is available on your system. The above line is an example of what you should see if you have Pascal or newer GPU(s) running in non-SLI configuration.

If VRWorks is not integrated correctly or your project is running on unsupported hardware you will see the following message:

  
  VRWorks: Not supported or GfxPluginVRWorks DLL was not loaded properly.
  

2.2 Activating VRWorks Features

As we already mentioned scripting language is used to toggle VRWorks features as needed. Valid features include Multi-Resolution Shading (MRS), Single-Pass-Stereo (SPS), Lens-Matched-Shading (LMS) and VR SLI.

NOTE: Single-Pass-Stereo (SPS) should not be confused with Unity's single pass stereo mode. VRWorks SPS is a hardware feature on Pascal or newer GPUs which enables rendering of both left and right eyes at the same time. Without VRWorks SPS Unity's single pass stereo still has to process each geometry twice on the GPU.

For example, to check if SPS is available and to toggle it on from anywhere within your script code you should simply do the following:

  
  using NVIDIA.VRWorks;
  
  if (IsFeatureAvailable(Feature.SinglePassStereo))
  {
    SetActiveFeature(Feature.SinglePassStereo);            
  }
  

To disable all VRWorks features use:

  
  using NVIDIA.VRWorks;
  
  SetActiveFeature(Feature.None);
  

Here are the valid feature configurations based on your project type:

  • Desktop (non-VR) projects
    • MRS
  • VR projects (SLI not detected)
    • MRS, SPS, SPS + LMS
  • VR projects (SLI detected)
    • MRS

NOTE:

  • SPS + MRS is a valid combination but it is not implemented in v1.0.0
  • In current implementation LMS mode requires SPS which is automatically enabled when LMS mode is set.
  • VR SLI is automatically detected and enabled in VR projects. There is no way to manually enable or disable VR SLI in Unity since SLI configuration is controlled through NVIDIA Graphics driver control panel.

2.3 Configuring Multi-Resolutions Parameters

In MRS mode there are 9 viewports (3x3 grid) and it is possible to change viewport areas and pixel density. This can be achieved by changing viewport splits in X and Y direction and pixel density parameters in the VRWorks component.

Viewport splits are values in range [0,0.5] and represent a percentage of the entire viewport area used to split the screen in horizontal and vertical direction (mirrored left/right and top/bottom). Pixel density is a value in range [0.05,0.95] used to control rendering quality in the viewports on the outskirts. Please note that viewport in the middle always remains at 100% pixel density. Default value for horizontal and vertical split is 0.25 while default value for pixel density is 0.7.


2.4 Setting Up Image Effects

In order to work correctly with MRS/LMS some image effects need to be modified. This is required because MRS/LMS use less pixels in color and depth render targets so adjustments are required to process pixels correctly.

⚠️ Support for image effects is limited since certain image effects might cause visual artifacts when MRS/LMS is used. If your project needs certain image effect which does not work correctly with MRS/LMS please let us know and we will do our best to help.

Here is the list of things to take under consideration when working with image effects:

  • VRWorks.cginc should be included in image effects to access VRWorks related shader API
  • In VR projects UV coordinates which are produced by vertex shaders in image effects need to be transformed correctly. Here is one example:
  
  float4 _MainTex_ST; // scale offset parameter
  v2f vert(appdata_img v)
  {
    ...
    // TRANSFORM_TEX ensures that UV coordinates are correct when double wide RT is used
    o.uv = TRANSFORM_TEX(v.texcoord.xy, _MainTex);
    return o;
  }
  
  • VRWorks is using special keywords to control shader execution. These keywords should be set on each image effect material like this:
  
  void OnRenderImage (RenderTexture source, RenderTexture destination)
  {
    ...
    NVIDIA.VRWorks.SetKeywords(myFXMaterial)
    ...
  }
  
  • #pragma multi_compile VRWORKS_MRS VRWORKS_LMS VRWORKS_NONE should be added to image effect shaders
  • If SAMPLE_DEPTH_TEXTURE macro is used no modification is needed, otherwise depth samplers should be replaced as follows:
    • _CameraDepthTexture should be replaced with VRWorksGetDepthSampler()
    • _CameraDepthNormalsTexture should be replaced with VRWorksGetDepthNormalsSampler()
    • UV coordinate which is used to sample depth buffer needs to be remapped. Here is an example:
      
      // Standard code
      float depth = tex2D(_CameraDepthTexture, uv).r;
      // VRWorks modification
      float depth = tex2D(VRWorksGetDepthSampler(), VRWorksRemapUV(uv)).r;
      
    
  • In some cases it might be necessary to bypass VRWorksRemapUV and explicitly transform UV coordinates from linear to non-linear (MRS/LMS) space and back. For those purposes you can use VRWorksUVToLinear and VRWorksUVFromLinear APIs. For example, VRWorksUVFromLinear transformation is used internaly by VRWorksPresent to present final image on screen (effectively converts MRS/LMS image into a full resolution).

NOTE:If the final image is flipped upside down when MRS/LMS is used please toggle the "VerticalFlip" checkbox in VRWorksPresent component.

For more details please have a look at the VRWorks compatible image effects in the example projects.


3 - EXAMPLES

There are two complete projects available on the asset store. First project is modified version of Unity's "Viking Village" demo which includes implementation of desktop MRS together with modified versions of image effects like ScreenSpaceAmbientOcclusion and Obscurance,GlobalFog and DOF. The other project is modified version of Unity's "VR Samples" demo which demonstrates MRS/SPS and LMS in VR mode. Here are the links:

NOTE: To avoid problems please use 64bit 2017.1.b6+ and VRWorks 1.0.2+. When using “NVIDIA VR Samples” or “NVIDIA Viking Village” sample projects please update VRWorks plugin to v1.0.2+


NVIDIA VR Samples


4 - PERFORMANCE AND VISUAL QUALITY

VRWorks features can provide boost in performance in certain scenarios where botleneck is on the GPU side. SPS can improve performance in geometry bound scenes while MRS/LMS can help in pixel bound scenarios. For VR projects the best results can be achieved on Pascal or newer GPUs by enabling LMS feature (which also enables SPS indirectly). In addition to potential performance benefits, MRS/LMS features can help improve visual quality by allowing you to render your scene at higher resolution or by adding more advanced post processing effects.

⚠️ If your project is CPU bound you should not expect to see any performance benefits by integrating and enabling VRWorks features.


5 - SUPPORT

For any Unity VRWorks related questions please email UnitySupport@nvidia.com


6 - ADDITIONAL RESOURCES


When custom shaders are used (like in case of Valve's "The Lab Renderer") it is quite easy to enable support for SPS. Since SPS renders both eyes in a single pass each vertex or domain shader needs to be modified so it outputs homogenous coordinates for the right eye. Here is, for example, how to modify vr_standard.shader from "The Lab Renderer":

        
        ...
        // define our matrix for the right eye
        #ifndef PLUGIN_STEREOX_VARS_DECLARED
          CBUFFER_START(UnityPerDrawVRWorks)
            float4x4 _WorldToClipXRight;
          CBUFFER_END
        #endif
        
        struct PS_INPUT
        {
        ...
        // right eye position at the end of the VS output (PS input) structure
        #ifdef PLUGIN_STEREOX
          float4 pos_right : NV_X_RIGHT;
        #endif                    
        };
        
        // MainVs --------------------------------------------------------------------------
        PS_INPUT MainVs( VS_INPUT i )
        {
        ...
        // in VS we need to provide homogenous coordinates for the right eye
         #ifdef PLUGIN_STEREOX
        o.pos_right = mul(_WorldToClipXRight, mul(unity_ObjectToWorld, i.vPositionOs.xyzw));
         #endif
        ...
        }
        ...
        
        

NOTE: View projection matrix _WorldToClipXRight is set in OnPreRender method inside VRWorks.cs script which as we mentioned earlier needs to be attached to the main camera in your scene.