NVIDIA RENDER INTERFACE (NRI)

NRI is a modular, extensible, low-level abstract rendering interface that was designed to support all low-level features of D3D12 and Vulkan GAPIs. At the same time, it aims to simplify usage and reduce the amount of code needed (especially compared with VK).

Goals:

• Generalization and unification of D3D12 (spec) and VK (spec)
• Explicitness (providing access to low-level features of modern GAPIs)
• Quality-of-life and high-level extensions (e.g., streaming and upscaling)
• Low overhead
• Cross-platform and platform independence (AMD/INTEL friendly)
• D3D11 support (spec) (as much as possible)

Non-goals:

• Exposing entities not existing in GAPIs
• High-level (D3D11-like) abstraction
• Hidden management of any kind (except for some high-level extensions where it's desired)
• Automatic barriers (better handled in a higher-level abstraction)

Supported GAPIs:

• Vulkan
• D3D12
• D3D11
• Metal (through MoltenVK)
• None / dummy (everything is supported but does nothing)

WHY NRI?

There is NVRHI, which offers a D3D11-like abstraction layer, implying some overhead. There is vkd3d-proton, which was designed for D3D12 emulation using Vulkan. There is nvpro-samples, which explores all "dark corners" of Vulkan usage, but does not offer any cross-API support. There are some other good, unmentioned projects, but NRI was designed to offer a reasonably simple, low-overhead, and high-performance render interface suitable for game development, professional rendering and hobby projects. Additionally, NRI can serve as a middleware for integrations. For instance, the NRD integration layer is based on NRI, unifying multiple GAPI support within a single codebase.

KEY FEATURES

• Multi-API support - generalized common denominator for D3D12, Vulkan, and D3D11 (default D3D11 behavior is changed to match D3D12/VK using NVAPI or AMD AGS libraries, where applicable)
• C/C++ compatible - native interface, compatible with both languages (can be used as a shared or static library)
• High performance - low overhead with zero memory allocations at runtime, honored user-provided memory allocator
• Modern hardware tech - support for Ray Tracing, Mesh Shaders, descriptor indexing (including directly indexed descriptor heaps) and more
• Mobile-ready - optimized for Tile-Based Rendering (TBR/TBDR) architectures
• D3D12 Ultimate - full support, including Enhanced Barriers
• Platform Flexibility - Windows, Linux, MacOS, and Android support
• Developer Experience - integrated GAPI- and NRI- validation, VK printf, and timeline annotations (GAPI, NVTX and PIX, if "WinPixEventRuntime.dll" is nearby)
• Memory Management - deep integration with AMD Virtual Memory Allocator to ease memory management and memory reuse

Available interfaces:

• NRI.h - core functionality
• NRIDeviceCreation.h - device creation and related functionality
• NRIHelper.h - a collection of various helpers to ease use of the core interface
• NRIImgui.h - a light-weight ImGui renderer (no ImGui dependency)
• NRILowLatency.h - low latency support (aka NVIDIA REFLEX)
• NRIMeshShader.h - mesh shaders
• NRIRayTracing.h - ray tracing
• NRIStreamer.h - a convenient way to stream data into resources
• NRISwapChain.h - swap chain and related functionality
• NRIUpscaler.h - a configurable collection of common upscalers (NIS, FSR, DLSS-SR, DLSS-RR)

Repository organization:

• there is only main branch used for development
• stable versions are in Releases section

BUILD INSTRUCTIONS

• Install Cmake 3.30+
• Build (variant 1) - using Git and CMake explicitly
  • Clone project and init submodules
  • Generate and build the project using CMake
  • To build the binary with static MSVC runtime, add -DCMAKE_MSVC_RUNTIME_LIBRARY="MultiThreaded$<$<CONFIG:Debug>:Debug>" parameter when deploying the project
• Build (variant 2) - by running scripts:
  • Run 1-Deploy
  • Run 2-Build

Notes:

• Xlib and Wayland can be both enabled
• Minimal supported client is Windows 8.1+. Windows 7 support requires minimal effort and can be added by request

CMAKE OPTIONS

• NRI_AGILITY_SDK_DIR - Directory where Agility SDK will be copied relative to the directory with binaries
• NRI_AGILITY_SDK_VERSION_MAJOR- Agility SDK major version
• NRI_AGILITY_SDK_VERSION_MINOR - Agility SDK minor version
• NRI_SHADERS_PATH - Shader output path override
• NRI_NVAPI_CUSTOM_PATH - Path to a custom NVAPI library directory
• NRI_STATIC_LIBRARY - Build static library
• NRI_ENABLE_NVTX_SUPPORT - Annotations for NVIDIA Nsight Systems
• NRI_ENABLE_DEBUG_NAMES_AND_ANNOTATIONS - Enable debug names, host and device annotations
• NRI_ENABLE_NONE_SUPPORT - Enable NONE backend
• NRI_ENABLE_VK_SUPPORT - Enable Vulkan backend
• NRI_ENABLE_VALIDATION_SUPPORT - Enable Validation backend (otherwise enableNRIValidation is ignored)
• NRI_ENABLE_NIS_SDK - Enable NVIDIA Image Sharpening SDK
• NRI_ENABLE_IMGUI_EXTENSION - Enable NRIImgui extension
• NRI_STREAMER_THREAD_SAFE - NRIStreamer thread safety (OFF is faster)
• NRI_ENABLE_D3D11_SUPPORT - Enable D3D11 backend
• NRI_ENABLE_D3D12_SUPPORT - Enable D3D12 backend
• NRI_ENABLE_AMDAGS- Enable AMD AGS library for D3D
• NRI_ENABLE_NVAPI - Enable NVAPI library for D3D
• NRI_ENABLE_AGILITY_SDK_SUPPORT - Enable Agility SDK support to unlock access to latest D3D12 features
• NRI_ENABLE_XLIB_SUPPORT - Enable X11 support
• NRI_ENABLE_WAYLAND_SUPPORT - Enable Wayland support
• NRI_ENABLE_NGX_SDK - Enable NVIDIA NGX (DLSS) SDK
• NRI_ENABLE_FFX_SDK - Enable AMD FidelityFX SDK
• NRI_ENABLE_XESS_SDK - Enable INTEL XeSS SDK

AGILITY SDK

The bare minimum requirement for D3D12 backend is D3D12 Ultimate (Windows SDK 10.0.20348, last pre-Agility SDK release). Using latest Agility SDK is highly recommended to get access to most recent D3D12 features and improved validation. See Overview and Download sections here for more details about Agility SDK.

Steps (already enabled by default):

• modify NRI_AGILITY_SDK_VERSION_MAJOR and NRI_AGILITY_SDK_VERSION_MINOR to the desired value
• enable or disable NRI_ENABLE_AGILITY_SDK_SUPPORT
• re-deploy project
• (optional) include auto-generated NRIAgilitySDK.h header in the code of your executable using NRI

It's safe to compile NRI using the default (most likely latest) Agility SDK and export some specific D3D12SDKVersion in the executable using NRI. In this case, NRI queries latest "available" interfaces according to the actually loaded D3D12Core.dll.

KNOWN VULKAN EXTENSIONS

Required:

• VK_KHR_synchronization2
• VK_KHR_dynamic_rendering
• VK_KHR_copy_commands2
• VK_EXT_extended_dynamic_state
• VK_KHR_portability_enumeration (for APPLE)
• VK_KHR_get_physical_device_properties2 (for APPLE)
• VK_KHR_portability_subset (for for APPLE)

Supported:

• (Instance) VK_KHR_get_surface_capabilities2
• (Instance) VK_KHR_surface
• (Instance) VK_KHR_win32_surface (VK_KHR_xlib_surface, VK_KHR_wayland_surface, VK_EXT_metal_surface)
• (Instance) VK_EXT_swapchain_colorspace
• (Instance) VK_EXT_debug_utils
• VK_KHR_swapchain
• VK_KHR_present_id
• VK_KHR_present_wait
• VK_KHR_swapchain_mutable_format
• VK_KHR_push_descriptor
• VK_KHR_maintenance4 (optional, but recommended)
• VK_KHR_maintenance5 (optional, but recommended)
• VK_KHR_maintenance6 (optional, but recommended)
• VK_KHR_maintenance7
• VK_KHR_maintenance8
• VK_KHR_maintenance9
• VK_KHR_line_rasterization
• VK_KHR_fragment_shading_rate
• VK_KHR_pipeline_library
• VK_KHR_ray_tracing_pipeline
• VK_KHR_acceleration_structure (depends on VK_KHR_deferred_host_operations)
• VK_KHR_ray_query
• VK_KHR_ray_tracing_position_fetch
• VK_KHR_ray_tracing_maintenance1
• VK_KHR_fragment_shader_barycentric
• VK_KHR_shader_clock
• VK_KHR_compute_shader_derivatives
• VK_KHR_unified_image_layouts
• VK_KHR_shader_integer_dot_product
• VK_KHR_dynamic_redering_local_read
• VK_EXT_pipeline_robustness
• VK_EXT_image_robustness
• VK_EXT_subgroup_size_control
• VK_EXT_mutable_descriptor_type
• VK_EXT_swapchain_maintenance1
• VK_EXT_present_mode_fifo_latest_ready
• VK_EXT_opacity_micromap
• VK_EXT_sample_locations
• VK_EXT_conservative_rasterization
• VK_EXT_mesh_shader
• VK_EXT_shader_atomic_float
• VK_EXT_shader_atomic_float2
• VK_EXT_memory_budget
• VK_EXT_memory_priority
• VK_EXT_image_sliced_view_of_3d
• VK_EXT_custom_border_color
• VK_EXT_robustness2
• VK_EXT_fragment_shader_interlock
• VK_EXT_present_mode_fifo_latest_ready
• VK_EXT_zero_initialize_memory
• VK_EXT_mutable_descriptor_type
• VK_NV_low_latency2
• VK_NVX_binary_import
• VK_NVX_image_view_handle

SAMPLES OVERVIEW

NRD sample:

• main sample demonstrating path tracing best practices

NRI samples:

• many samples demonstrating NRI usage

C/C++ INTERFACE DIFFERENCES

C++	C
nri::Interface	NriInterface
nri::Enum::MEMBER	NriEnum_MEMBER
nri::CONST	NRI_CONST
nri::nriFunction	nriFunction
nri::Function	nriFunction
Reference &	Pointer *

ENTITIES

NRI	D3D11	D3D12	VK
Device	ID3D11Device	ID3D12Device	VkDevice
CommandBuffer	ID3D11DeviceContext (deferred)	ID3D12CommandList	VkCommandBuffer
CommandQueue	ID3D11DeviceContext (immediate)	ID3D12CommandQueue	VkQueue
Fence	ID3D11Fence	ID3D12Fence	VkSemaphore (timeline)
CommandAllocator	N/A	ID3D12CommandAllocator	VkCommandPool
Buffer	ID3D11Buffer	ID3D12Resource	VkBuffer
Texture	ID3D11Texture	ID3D12Resource	VkImage
Memory	N/A	ID3D12Heap	VkDeviceMemory
Descriptor	ID3D11*View or ID3D11SamplerState	D3D12_CPU_DESCRIPTOR_HANDLE	Vk*View or VkSampler
DescriptorSet	N/A	N/A	VkDescriptorSet
DescriptorPool	N/A	ID3D12DescriptorHeap	VkDescriptorPool
PipelineLayout	N/A	ID3D12RootSignature	VkPipelineLayout
Pipeline	ID3D11*Shader and ID3D11*State	ID3D12StateObject	VkPipeline
AccelerationStructure	N/A	ID3D12Resource	VkAccelerationStructure

LICENSE

NRI is licensed under the MIT License.