Fix NGX Lifetime Management and Manual FSR FOV Conversion (#875)

* Clean up DLSS DX12 inputs

- Refactored CreateFeature() and EvaluateFeature() into smaller functions with shared utilities and distinct code paths for internal OptiScaler and passthrough features.

- Added documentation to clarify internal implementation details and behavior required by the NGX API.

- Added more descriptive error messages.

- Fixed a potential memory leak in GetParameters(). Per the DLSS Programming Guide (310.5.0), this deprecated API requires the SDK to manage the lifetime of the returned parameter table, as legacy applications do not free this memory.

- Identified a memory management issue: NVNGX_Parameter tables are incorrectly handled in Allocate/Destroy and FeatureProvider. C-style free() is being used on tables allocated with 'new' and on native NGX tables, leading to memory leaks and undefined behavior. Using free() here is actually worse than just willfully leaking memory. This needs fixing.

* Fix: Correct NGX Parameter table lifetime and deallocation

Problem:

The previous implementation incorrectly used C-style free() on NVSDK_NGX_Parameter objects within the DLSS feature providers. This was unsafe for several reasons:

- Non-trivial types: These structs often contain internal data/tables that free() does not account for, bypassing necessary destructors.
- Ambiguous ownership: Tables were inconsistently sourced from internal allocations (OptiScaler), external NGX API calls, or legacy persistent pointers.
- Heap/Stack corruption: Using free() on memory managed by the NGX API or on stack-allocated memory from legacy GetParameters() calls. This risked immediate crashes or heap instability.

Solution:

Introduced a tagging system to explicitly track memory ownership and determine the correct deallocation strategy. When a destruction request is made, the system now checks the table's tag and acts accordingly:

1. InternPersistent: Internal OptiScaler tables for legacy APIs. Lifetime is managed by the SDK; these persist until process exit.
2. InternDynamic: Internal tables explicitly created/destroyed by the client. Now correctly freed using delete with a static_cast to the implementation type.
3. NVPersistent: Native NGX legacy tables. These are ignored as the native SDK manages their lifetime.
4. NVDynamic: Native NGX modern tables. These are now properly forwarded to the native NGX DestroyParameters() function.

* Start gathering unique string literals in header

- Started organizing string literals being used as unique identifiers for things like feature selection and parameter lookup into a dedicated header. Less error prone and actually works with intellisense.
- The actual usages of these strings have yet to be replaced, but I am using them for new code.

* Fix incorrect configurable FOV conversion in FSR

- The conversions for manually configured horizontal FOV to vertical FOV used in upscaling have been corrected to use the following formula: vFov = 2 * arctan( tan( hFov / 2 ) * ( h / w ) )
- Added convenience variables for global singletons to Eval functions to help readability
- Streamlined ffxResolveTypelessFormat usages. More readable.

* Update ffxResolveTypelessFormat usage

* Run clang formatting

* Fix potential NGX handle memory leak if device couldn't be acquired

Fixed a preexisting edge case that could cause the NGX handle to be leaked if the D3D12 device could not be acquired.

* Fix Vulkan upscaler typo and DX11 init error

- Vulkan: Correct default upscaler key from FSR 2.1 to FSR 2.2.
- DX11: Removed redundant table initialization in DLSS inputs caused by copy-paste error.

* Add NGX table reset check and remove old DLSSD check

- Added extra check in NGX table to preserve usage keys for custom tables.
- Fixed incorrect feature release log error
- Reran clang-format
- Removed old DLSSD check for root signature restore
- Removed GetIsDlssModuleInited() helper utility

Author: ZachHembree

OptiScaler/Config.h

@@ -367,9 +367,9 @@ class Config
     CustomOptional<bool> DontCreateD3D12DeviceForLuma { false };
 
     // Upscalers
-    CustomOptional<std::string, SoftDefault> Dx11Upscaler { "fsr22" };
-    CustomOptional<std::string, SoftDefault> Dx12Upscaler { "xess" };
-    CustomOptional<std::string, SoftDefault> VulkanUpscaler { "fsr22" };
+    CustomOptional<std::string, SoftDefault> Dx11Upscaler { std::string(OptiKeys::FSR22) };
+    CustomOptional<std::string, SoftDefault> Dx12Upscaler { std::string(OptiKeys::XeSS) };
+    CustomOptional<std::string, SoftDefault> VulkanUpscaler { std::string(OptiKeys::FSR22) };
 
     // Output Scaling
     CustomOptional<bool> OutputScalingEnabled { false };

OptiScaler/MathUtils.h

@@ -0,0 +1,47 @@
+#pragma once
+#include <numbers>
+#include <cmath>
+
+namespace OptiMath
+{
+// Radians per degree. Used to convert from degrees to radians
+inline constexpr float DegToRad = std::numbers::pi_v<float> / 180.0f;
+// Degrees per radian. Used to convert from radians to degrees
+inline constexpr float RadToDeg = 180.0f / std::numbers::pi_v<float>;
+
+// Converts from an angle in degrees to radians
+[[nodiscard]] inline constexpr float GetRadiansFromDeg(const float deg) { return deg * DegToRad; }
+
+// Converts from an angle in radians to degrees
+[[nodiscard]] inline constexpr float GetDegreesFromRad(const float rad) { return rad * RadToDeg; }
+
+/**
+ * @brief Calculates the vertical field of view for a camera from its horizontal FOV and its
+ * viewport dimensions according to the formula: vFov = 2 * arctan( tan( hFov / 2 ) * ( h / w ) ).
+ * @param hFovRad: Horizontal field of view
+ * @param width: Width of the camera viewport
+ * @param height: Height of the camera viewport
+ * @return Vertical FOV in radians
+ */
+[[nodiscard]] inline float GetVerticalFovFromHorizontal(const float hFovRad, const float width, const float height)
+{
+    if (width <= 0.0f)
+        return 0.0f;
+    return 2.0f * std::atan(std::tan(hFovRad * 0.5f) * (height / width));
+}
+
+/**
+ * @brief Calculates the horizontal field of view for a camera from its vertical FOV and its
+ * viewport dimensions according to the formula: hFov = 2 * arctan( tan( vFov / 2 ) * ( w / h ) ).
+ * @param vFovRad: Vertical field of view in radians
+ * @param width: Width of the camera viewport
+ * @param height: Height of the camera viewport
+ * @return Horizontal FOV in radians
+ */
+[[nodiscard]] inline float GetHorizontalFovFromVertical(const float vFovRad, const float width, const float height)
+{
+    if (height <= 0.0f)
+        return 0.0f;
+    return 2.0f * std::atan(std::tan(vFovRad * 0.5f) * (width / height));
+}
+} // namespace OptiMath

OptiScaler/NVNGX_Parameter.h

@@ -1,8 +1,6 @@
 #pragma once
 #include "SysUtils.h"
-
 #include "Config.h"
-
 #include <ankerl/unordered_dense.h>
 
 // Use real NVNGX params encapsulated in custom one
@@ -18,6 +16,24 @@
 #define LOG_PARAM(msg, ...)
 #endif
 
+/** @brief Indicates the lifetime management required by an NGX parameter table. */
+namespace NGX_AllocTypes
+{
+// Key used to get/set enum from table
+constexpr std::string_view AllocKey = "OptiScaler.ParamAllocType";
+
+constexpr uint32_t Unknown = 0;
+// Standard behavior in modern DLSS. Created with NGX Allocate(). Freed with Destroy().
+constexpr uint32_t NVDynamic = 1;
+// Legacy DLSS. Lifetime managed internally by the SDK.
+constexpr uint32_t NVPersistent = 2;
+// OptiScaler implementation used internally with new/delete.
+constexpr uint32_t InternDynamic = 3;
+// OptiScaler implementation for legacy applications. Must maintain a persistent instance
+// for the lifetime of the application.
+constexpr uint32_t InternPersistent = 4;
+} // namespace NGX_AllocTypes
+
 /// @brief Calculates the resolution scaling ratio override based on the provided quality level and current
 /// configuration.
 /// @param input The performance quality value (e.g. Quality, Balanced, Performance).
@@ -670,6 +686,15 @@ struct NVNGX_Parameters : public NVSDK_NGX_Parameter
 {
     std::string Name;
 
+    NVNGX_Parameters(std::string_view name, bool isPersistent) : Name(name)
+    {
+        // Old flag used to indicate custom table. Obsolete?
+        Set("OptiScaler", 1);
+        // New tracking flag
+        Set(NGX_AllocTypes::AllocKey.data(),
+            isPersistent ? NGX_AllocTypes::InternPersistent : NGX_AllocTypes::InternDynamic);
+    }
+
 #ifdef ENABLE_ENCAPSULATED_PARAMS
     NVSDK_NGX_Parameter* OriginalParam = nullptr;
 #endif // ENABLE_ENCAPSULATED_PARAMS
@@ -934,8 +959,16 @@ struct NVNGX_Parameters : public NVSDK_NGX_Parameter
     void Reset() override
     {
         if (!m_values.empty())
+        {
+            // Preserve usage type if set
+            uint32_t allocType = NGX_AllocTypes::Unknown;
+            NVSDK_NGX_Result result = Get(NGX_AllocTypes::AllocKey.data(), &allocType);
             m_values.clear();
 
+            if (result != NVSDK_NGX_Result_Fail)
+                Set(NGX_AllocTypes::AllocKey.data(), allocType);
+        }
+
         LOG_DEBUG("Start");
 
         InitNGXParameters(this);
@@ -981,13 +1014,64 @@ struct NVNGX_Parameters : public NVSDK_NGX_Parameter
     }
 };
 
-/// @brief Allocates and populates a new NGX param map.
-inline static NVNGX_Parameters* GetNGXParameters(std::string InName)
+/**
+ * @brief Allocates and populates a new custom NGX param map. The persistence flag indicates
+ * whether the table should be destroyed when NGX DestroyParameters() is used.
+ */
+inline static NVNGX_Parameters* GetNGXParameters(std::string_view name, bool isPersistent)
 {
-    auto params = new NVNGX_Parameters();
-    params->Name = InName;
+    auto params = new NVNGX_Parameters(name, isPersistent);
     InitNGXParameters(params);
-    params->Set("OptiScaler", 1);
-
     return params;
 }
+
+/**
+ * @brief Sets a custom tracking tag to indicate the memory management strategy required by
+ * the table, indicated by NGX_AllocTypes.
+ */
+inline static void SetNGXParamAllocType(NVSDK_NGX_Parameter& params, uint32_t allocType)
+{
+    params.Set(NGX_AllocTypes::AllocKey.data(), allocType);
+}
+
+/**
+ * @brief Attempts to safely delete an NGX parameter table. Dynamically allocated NGX tables use the NGX API.
+ * OptiScaler tables use delete. Persistent tables are not freed.
+ */
+template <typename PFN_DestroyNGXParameters>
+static inline bool TryDestroyNGXParameters(NVSDK_NGX_Parameter* InParameters, PFN_DestroyNGXParameters NVFree = nullptr)
+{
+    if (InParameters == nullptr)
+        return false;
+
+    uint32_t allocType = NGX_AllocTypes::Unknown;
+    NVSDK_NGX_Result result = InParameters->Get(NGX_AllocTypes::AllocKey.data(), &allocType);
+
+    // Key not set. Either a bug, or the client application called Reset() on the table before destroying.
+    // Derived type unknown if this happens. Not safe to delete. Leaking is the best option.
+    if (result == NVSDK_NGX_Result_Fail)
+    {
+        LOG_WARN("Destroy called on NGX table with unset alloc type. Leaking.");
+        return false;
+    }
+
+    if (allocType == NGX_AllocTypes::NVDynamic)
+    {
+        if (NVFree != nullptr)
+        {
+            LOG_INFO("Calling NVFree");
+            result = NVFree(InParameters);
+            LOG_INFO("Calling NVFree result: {0:X}", (UINT) result);
+            return true;
+        }
+        else
+            return false;
+    }
+    else if (allocType == NGX_AllocTypes::InternDynamic)
+    {
+        delete static_cast<NVNGX_Parameters*>(InParameters);
+        return true;
+    }
+
+    return false;
+}

OptiScaler/OptiScaler.vcxproj

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <ItemGroup Label="ProjectConfigurations">
     <ProjectConfiguration Include="Debug|Win32">
@@ -340,6 +340,8 @@ copy NUL "$(SolutionDir)x64\Release\a\!! EXTRACT ALL FILES TO GAME FOLDER !!" /Y
     <ClInclude Include="inputs\FSR2_Dx11.h" />
     <ClInclude Include="inputs\FSR2_Vk.h" />
     <ClInclude Include="inputs\XeSS_Dx11.h" />
+    <ClInclude Include="MathUtils.h" />
+    <ClInclude Include="OptiTexts.h" />
     <ClInclude Include="shaders\depth_invert\DI_Common.h" />
     <ClInclude Include="shaders\depth_invert\DI_Dx12.h" />
     <ClInclude Include="shaders\depth_invert\precompiled\DI_Shader.h" />

OptiScaler/OptiScaler.vcxproj.filters

@@ -695,7 +695,7 @@
     <ClInclude Include="shaders\hud_copy\HudCopy_Dx12.h">
       <Filter>Header Files</Filter>
     </ClInclude>
-    <ClInclude Include="shaders\hud_copy\precompile\HudCopy_Shader.h">
+    <ClInclude Include="MathUtils.h">
       <Filter>Header Files</Filter>
     </ClInclude>
     <ClInclude Include="shaders\output_scaling\precompile\bcds_bicubic_Shader_Vk.h">
@@ -728,6 +728,9 @@
     <ClInclude Include="shaders\render_ui\RUI_Dx12.h">
       <Filter>Header Files</Filter>
     </ClInclude>
+    <ClInclude Include="OptiTexts.h">
+      <Filter>Header Files</Filter>
+    </ClInclude>
     <ClInclude Include="shaders\output_scaling\precompile\bcds_kaiser2_Shader.h">
       <Filter>Header Files</Filter>
     </ClInclude>

OptiScaler/OptiTexts.h

@@ -0,0 +1,52 @@
+#pragma once
+
+/**
+ * @brief Common strings and identifiers used internally by OptiScaler
+ */
+namespace OptiKeys
+{
+using CString = const char[];
+
+// Application name provided to upscalers
+inline constexpr CString ProjectID = "OptiScaler";
+
+// ID code used for the Vulkan input provider
+inline constexpr CString VkProvider = "OptiVk";
+// ID code used for the DX11 input provider
+inline constexpr CString Dx11Provider = "OptiDx11";
+// ID code used for the DX12 input provider
+inline constexpr CString Dx12Provider = "OptiDx12";
+
+// ID code used for the XeSS upscaler backend
+inline constexpr CString XeSS = "xess";
+// ID code used for the XeSS upscaler backend used with the DirectX 11 on 12 compatibility layer
+inline constexpr CString XeSS_11on12 = "xess_12";
+// ID code used for the FSR 2.1.x upscaler backend
+inline constexpr CString FSR21 = "fsr21";
+// ID code used for the FSR 2.1.x upscaler backend used with the DirectX 11 on 12 compatibility layer
+inline constexpr CString FSR21_11on12 = "fsr21_12";
+// ID code used for the FSR 2.2.x upscaler backend
+inline constexpr CString FSR22 = "fsr22";
+// ID code used for the FSR 2.2.x upscaler backend used with the DirectX 11 on 12 compatibility layer
+inline constexpr CString FSR22_11on12 = "fsr22_12";
+// ID code used for the FSR 3.1+ upscaler backend
+inline constexpr CString FSR31 = "fsr31";
+// ID code used for the FSR 3.1+ upscaler backend used with the DirectX 11 on 12 compatibility layer
+inline constexpr CString FSR31_11on12 = "fsr31_12";
+// ID code used for the DLSS upscaler backend
+inline constexpr CString DLSS = "dlss";
+// ID code used for the DLSS-D/Ray Reconstruction upscaler+denoiser backend
+inline constexpr CString DLSSD = "dlssd";
+
+inline constexpr CString FSR_UpscaleWidth = "FSR.upscaleSize.width";
+inline constexpr CString FSR_UpscaleHeight = "FSR.upscaleSize.height";
+
+inline constexpr CString FSR_NearPlane = "FSR.cameraNear";
+inline constexpr CString FSR_FarPlane = "FSR.cameraFar";
+inline constexpr CString FSR_CameraFovVertical = "FSR.cameraFovAngleVertical";
+inline constexpr CString FSR_FrameTimeDelta = "FSR.frameTimeDelta";
+inline constexpr CString FSR_ViewSpaceToMetersFactor = "FSR.viewSpaceToMetersFactor";
+inline constexpr CString FSR_TransparencyAndComp = "FSR.transparencyAndComposition";
+inline constexpr CString FSR_Reactive = "FSR.reactive";
+
+} // namespace OptiKeys

OptiScaler/SysUtils.h

@@ -183,3 +183,5 @@ inline static void to_lower_in_place(std::string& string)
 {
     std::transform(string.begin(), string.end(), string.begin(), ::tolower);
 }
+
+#include "OptiTexts.h"

OptiScaler/inputs/FG/FSR3_Dx12_FG.cpp

@@ -3,6 +3,7 @@
 
 #include "Config.h"
 #include "Util.h"
+#include "MathUtils.h"
 
 #include "resource.h"
 #include "NVNGX_Parameter.h"
@@ -23,6 +24,7 @@
 #include "fsr3/ffx_frameinterpolation.h"
 
 const UINT fgContext = 0x1337;
+using namespace OptiMath;
 
 // Swapchain create
 typedef FFX_API
@@ -1250,21 +1252,25 @@ void FSR3FG::SetUpscalerInputs(ID3D12GraphicsCommandList* InCmdList, NVSDK_NGX_P
 
     float tempCameraNear = 0.0f;
     float tempCameraFar = 0.0f;
-    InParameters->Get("FSR.cameraNear", &tempCameraNear);
-    InParameters->Get("FSR.cameraFar", &tempCameraFar);
 
-    if (!Config::Instance()->FsrUseFsrInputValues.value_or_default() ||
-        (tempCameraNear == 0.0f && tempCameraFar == 0.0f))
+    auto& state = State::Instance();
+    auto& cfg = *Config::Instance();
+    const auto& ngxParams = *InParameters;
+
+    ngxParams.Get(OptiKeys::FSR_NearPlane, &tempCameraNear);
+    ngxParams.Get(OptiKeys::FSR_FarPlane, &tempCameraFar);
+
+    if (!cfg.FsrUseFsrInputValues.value_or_default() || (tempCameraNear == 0.0f && tempCameraFar == 0.0f))
     {
         if (feature->DepthInverted())
         {
-            cameraFar = Config::Instance()->FsrCameraNear.value_or_default();
-            cameraNear = Config::Instance()->FsrCameraFar.value_or_default();
+            cameraFar = cfg.FsrCameraNear.value_or_default();
+            cameraNear = cfg.FsrCameraFar.value_or_default();
         }
         else
         {
-            cameraFar = Config::Instance()->FsrCameraFar.value_or_default();
-            cameraNear = Config::Instance()->FsrCameraNear.value_or_default();
+            cameraFar = cfg.FsrCameraFar.value_or_default();
+            cameraNear = cfg.FsrCameraNear.value_or_default();
         }
     }
     else
@@ -1273,20 +1279,23 @@ void FSR3FG::SetUpscalerInputs(ID3D12GraphicsCommandList* InCmdList, NVSDK_NGX_P
         cameraFar = tempCameraFar;
     }
 
-    if (!Config::Instance()->FsrUseFsrInputValues.value_or_default() ||
-        InParameters->Get("FSR.cameraFovAngleVertical", &cameraVFov) != NVSDK_NGX_Result_Success)
+    if (!cfg.FsrUseFsrInputValues.value_or_default() ||
+        ngxParams.Get(OptiKeys::FSR_CameraFovVertical, &cameraVFov) != NVSDK_NGX_Result_Success)
     {
-        if (Config::Instance()->FsrVerticalFov.has_value())
-            cameraVFov = Config::Instance()->FsrVerticalFov.value() * 0.0174532925199433f;
-        else if (Config::Instance()->FsrHorizontalFov.value_or_default() > 0.0f)
-            cameraVFov = 2.0f * atan((tan(Config::Instance()->FsrHorizontalFov.value() * 0.0174532925199433f) * 0.5f) /
-                                     (float) feature->TargetHeight() * (float) feature->TargetWidth());
+        if (cfg.FsrVerticalFov.has_value())
+            cameraVFov = GetRadiansFromDeg(cfg.FsrVerticalFov.value());
+        else if (cfg.FsrHorizontalFov.value_or_default() > 0.0f)
+        {
+            const float hFovRad = GetRadiansFromDeg(cfg.FsrHorizontalFov.value());
+            cameraVFov =
+                GetVerticalFovFromHorizontal(hFovRad, (float) feature->TargetWidth(), (float) feature->TargetHeight());
+        }
         else
-            cameraVFov = 1.0471975511966f;
+            cameraVFov = GetRadiansFromDeg(60);
     }
 
-    if (!Config::Instance()->FsrUseFsrInputValues.value_or_default())
-        InParameters->Get("FSR.viewSpaceToMetersFactor", &meterFactor);
+    if (!cfg.FsrUseFsrInputValues.value_or_default())
+        ngxParams.Get(OptiKeys::FSR_ViewSpaceToMetersFactor, &meterFactor);
 
     State::Instance().lastFsrCameraFar = cameraFar;
     State::Instance().lastFsrCameraNear = cameraNear;