NVRHI

Introduction

NVRHI (NVIDIA Rendering Hardware Interface) is a library that implements a common abstraction layer over multiple graphics APIs (GAPIs): Direct3D 11, Direct3D 12, and Vulkan 1.3. It works on Windows and Linux (x64 and ARM64).

Key features:

• Automatic tracking of resource states and barrier placement (optional).
• Automatic tracking of resource usage and lifetime, deferred and safe resource destruction.
• Convenient and efficient resource binding model with little runtime overhead.
• Easy direct interaction with the underlying GAPI when necessary.
• Easy portability of the rendering code between the supported GAPIs.
• Hidden sub-allocation of upload buffers and versioning of constant buffers.
• Parallel command list recording and multi-queue rendering.
• Supports all types of pipelines: Graphics, Compute, Ray Tracing, and Meshlet.
• Validation layer and resource reflection for easy debugging.

NVRHI is used in several NVIDIA SDKs:

• Adaptive and Variable-Rate Shading SDK
• Donut Framework and its Samples
• In-Game Inference (NVIGI) Sample
• Opacity Micro-Map SDK
• RTX Character Rendering SDK
• RTX Mega Geometry SDK
• RTX Neural Shading SDK
• RTX Neural Texture Compression SDK
• RTX Path Tracing SDK
• RTX Texture Filtering SDK
• RTX Texture Streaming SDK
• RTXDI SDK
• RTXGI SDK

Notable third-party projects using NVRHI:

• RBDoom3-BFG

Various early versions of NVRHI have been used in various projects created at NVIDIA, including:

• Asteroids demo
• DLSS SDK
• VRWorks
• VXGI
• WaveWorks

Requirements

• Windows or Linux (x64 or ARM64)
• CMake 3.10
• A C++ 17 compiler (Visual Studio 2019, GCC 8 or Clang 6)
• Windows SDK version 10.0.22621.0 or later for DX12 support

Building NVRHI

NVRHI can be configured to be used a set of static libraries in CMake-based projects, or as a single dynamic library.

To include NVRHI into a CMake project as static libraries:

1. Add this repository as a submodule.
2. Add a add_subdirectory(nvrhi) directive to the parent CMakeLists.txt.
3. Add dependencies to the necessary targets:
   • nvrhi for the interface headers, common utilities, and validation;
   • nvrhi_d3d11 for DX11 (enabled when NVRHI_WITH_DX11 is ON);
   • nvrhi_d3d12 for DX12 (enabled when NVRHI_WITH_DX12 is ON); and
   • nvrhi_vk for Vulkan (enabled when NVRHI_WITH_VULKAN is ON).

To build NVRHI as a shared library (DLL or .so):

1. Clone this repository.
2. Generate the project with CMake:
   • Set the NVRHI_BUILD_SHARED variable to ON.
   • Make sure to set the target platform to a 64-bit one. 32-bit builds are not supported.
3. Build and install as normal.

Configuring the Vulkan and DirectX header libraries

NVRHI depends on the Vulkan-Headers and DirectX-Headers libraries for platform headers (where applicable). These libraries can be provided externally by importing them into the CMake project before NVRHI, or they can be downloaded automatically at project configuration time using CMake FetchContent. This behavior is controlled with the following CMake variables:

• NVRHI_FETCH_VULKAN_HEADERS enables downloading of the Vulkan-Headers library (otherwise it must be provided externally if Vulkan is enabled)
  • NVRHI_VULKAN_HEADERS_GIT_REPOSITORY sets the git repository URL for Vulkan-Headers
  • NVRHI_VULKAN_HEADERS_GIT_TAG sets the git tag or commit hash for Vulkan-Headers
  • NVRHI_VULKAN_HEADERS_FETCH_DIR sets the path that Vulkan-Headers will be downloaded to - empty means the default location in build/_deps
• NVRHI_FETCH_DIRECTX_HEADERS enables downloading of the DirectX-Headers library (otherwise it must be provided externally if Vulkan is enabled)
  • NVRHI_DIRECTX_HEADERS_GIT_REPOSITORY sets the git repository URL for DirectX-Headers
  • NVRHI_DIRECTX_HEADERS_GIT_TAG sets the git tag or commit hash for DirectX-Headers
  • NVRHI_DIRECTX_HEADERS_FETCH_DIR sets the path that DirectX-Headers will be downloaded to - empty means the default location in build/_deps

The default values of these configuration variables should be OK for most use cases.

Using NVRHI in Applications

See the programming guide, the tutorial, and the optional memory query reference.

NVAPI Support

NVRHI includes optional support for certain DX11 and DX12 extensions available through the NVAPI library. The library is not distributed with NVRHI but is available separately here.

To enable NVAPI support, extract the NVAPI SDK into the nvapi subfolder of your main project and set the NVRHI_WITH_NVAPI CMake variable to ON.

Windows on ARM64 needs the R615 or later NVAPI SDK, the first to ship the ARM64 library (aarch64/nvapia64.lib). The library matching the target architecture is picked automatically.

The following extensions are supported:

• Cluster Level Acceleration Structures (DX12)
• Linear Swept Spheres (DX12, Blackwell+)
• Opacity Micro-Maps (DX12, Ada+)
• Shader Execution Reordering on DX12 (DX12, Ada+)
• Single Pass Stereo (Pascal+)
• Fast Geometry Shader with optional coordinate swizzling (Maxwell+)
• Conservative Raster and other rasterizer features (Maxwell+)
• HLSL Extensions through a fake UAV slot (see this blog post)

DXR Clusters Support (Preview)

Set the NVRHI_D3D12_WITH_DXRCLUSTER CMake variable to ON to add native DXR cluster operations to the DX12 backend. Using them requires:

• Exactly version 1.722 of the preview D3D12 Agility SDK, with NVRHI_D3D12_DXRCLUSTER_INCLUDE_DIR set to its include directory; later previews are not guaranteed to work with NVIDIA driver 621.01
• Windows Developer Mode, and a call to nvrhi::d3d12::enableExperimentalFeatures() before the D3D12 device is created
• NVIDIA driver 621.01 or later

When NVRHI is also built with NVRHI_WITH_NVAPI and an NVAPI SDK that supports cluster operations, the NVAPI cluster operations stay compiled in, and each device picks one API at creation: DXR clusters when the device supports it, NVAPI otherwise. Without NVAPI cluster support, a device without DXR clusters has no cluster operations. d3d12::DeviceDesc::enableDxrClusters and enableNvapiClusters remove an API from that choice. Query Feature::RayTracingClusters with a RayTracingClustersFeatureInfo to find the API in use: DXR clusters read the nvrhi::rt::cluster::dxr argument layouts and writes 64-bit result sizes, while NVAPI and Vulkan use the nvrhi::rt::cluster::nv layouts and 32-bit sizes. The cluster argument structs in nvrhiHLSL.h have 16-bit fields, so HLSL only declares them when compiled with -enable-16bit-types.

RTXMU Integration

NVRHI includes an optional integration of the RTXMU library. The library is downloaded at project configuration time using CMake FetchContent when the NVRHI_WITH_RTXMU CMake variable is set to ON. Similar to the platform header libraries, the RTXMU dependency can be configured using the following CMake variables:

• NVRHI_RTXMU_GIT_REPOSITORY sets the git repository URL for RTXMU
• NVRHI_RTXMU_GIT_TAG sets the git tag or commit hash for RTXMU
• NVRHI_RTXMU_FETCH_DIR sets the path that RTXMU will be downloaded to - empty means the default location in build/_deps

When RTXMU integration is enabled, all bottom-level ray tracing acceleration structures (BLAS'es) are managed by that library. All built BLAS'es that have the AllowCompaction flag set are automatically compacted when ICommandList::compactBottomLevelAccelStructs method is called. No other configuration is necessary.

License

NVRHI is licensed under the MIT License.