Skip to content

Commit 4f0f48c

Browse files
Nullpoint56claude
andcommitted
Upscalers record the vendor runtimes they were built against; beta.2 notes
build-native.ps1 writes upscaler-runtimes.json beside each Upscalers payload: each upscaler SDK at NRI's pin (FidelityFX 2.4.0, XeSS 3.0.2, NIS 1.0.3, NGX 310.9.16 at v191) and each runtime NRI's build fetched, by file version and SHA-256. The package carries it as runtimes/<rid>/upscaler-runtimes.json, release.yml lists it under the notes' NRI line (tools/ci/upscaler-runtimes.ps1), and the pack step requires it and the XML docs. NativePayloadTests holds the manifest to the pins and to GetRuntimeFiles. The beta.2 notes cover everything since beta.1. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01NvXTk6Roe4sQLHFx9Zykv8
1 parent b75f617 commit 4f0f48c

7 files changed

Lines changed: 171 additions & 15 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 23 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -350,10 +350,10 @@ jobs:
350350
run: |
351351
Add-Type -AssemblyName System.IO.Compression.FileSystem
352352
$must = @{
353-
"SharpNRI" = "runtimes/win-x64/native/NRI.dll", "runtimes/linux-x64/native/libNRI.so", "lib/net11.0/SharpNRI.dll", "README.md"
354-
"SharpNRI.Descs" = "lib/net11.0/SharpNRI.Descs.dll", "README.md"
355-
"SharpNRI.Testing" = "lib/net11.0/SharpNRI.Testing.dll", "README.md"
356-
"SharpNRI.Native.Upscalers" = "runtimes/win-x64/native/NRI.dll", "runtimes/linux-x64/native/libNRI.so", "README.md"
353+
"SharpNRI" = "runtimes/win-x64/native/NRI.dll", "runtimes/linux-x64/native/libNRI.so", "lib/net11.0/SharpNRI.dll", "lib/net11.0/SharpNRI.xml", "README.md"
354+
"SharpNRI.Descs" = "lib/net11.0/SharpNRI.Descs.dll", "lib/net11.0/SharpNRI.Descs.xml", "README.md"
355+
"SharpNRI.Testing" = "lib/net11.0/SharpNRI.Testing.dll", "lib/net11.0/SharpNRI.Testing.xml", "README.md"
356+
"SharpNRI.Native.Upscalers" = "runtimes/win-x64/native/NRI.dll", "runtimes/linux-x64/native/libNRI.so", "runtimes/win-x64/upscaler-runtimes.json", "runtimes/linux-x64/upscaler-runtimes.json", "README.md"
357357
}
358358
$version = "${{ needs.version.outputs.version }}"
359359
$failed = @()
@@ -449,17 +449,28 @@ jobs:
449449
steps:
450450
- uses: actions/checkout@v4
451451
with:
452-
sparse-checkout: docs/releases
452+
sparse-checkout: |
453+
docs/releases
454+
tools/ci
453455
454-
# docs/releases/<tag>.md, plus where the macOS library comes from.
456+
# The vendor runtimes the Upscalers payload was built against, from the manifest
457+
# tools/build-native.ps1 wrote beside it (the package carries the same file)
458+
- uses: actions/download-artifact@v4
459+
with:
460+
name: runtimes-upscalers-win-x64
461+
path: upscalers
462+
463+
# docs/releases/<tag>.md with the upscaler runtimes listed under its first line (the NRI pin),
464+
# plus where the macOS library comes from.
455465
- name: Release body
466+
shell: pwsh
456467
run: |
457-
cp "docs/releases/${RELEASE_TAG}.md" body.md
458-
{
459-
echo
460-
echo "The macOS (osx-arm64) library is not in the packages: it is attached here as a zip once a macOS runner has built it."
461-
} >> body.md
462-
cat body.md
468+
$notes = Get-Content "docs/releases/$env:RELEASE_TAG.md"
469+
if ($notes[0] -notmatch '^\*\*NRI v\d+\*\*$') { throw "the notes must start with the NRI pin line (**NRI vNNN**)" }
470+
$runtimes = & ./tools/ci/upscaler-runtimes.ps1 upscalers/win-x64/upscaler-runtimes.json
471+
$body = @($notes[0]) + $runtimes + $notes[1..($notes.Count - 1)] + @("", "The macOS (osx-arm64) library is not in the packages: it is attached here as a zip once a macOS runner has built it.")
472+
$body | Set-Content body.md -Encoding utf8NoBOM
473+
Get-Content body.md
463474
464475
- uses: actions/download-artifact@v4
465476
with:

‎AGENTS.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1239,6 +1239,15 @@ Homebrew loader 1.4.357; device "Apple Paravirtual device", Vulkan 1.4.357, 18 d
12391239
without `nvngx_dlssd.dll` beside the application (NGX loads its feature DLLs from outside it too);
12401240
XeSS an `SEHException` from the delay-load stub (0xC06D007E). FSR loads `amd_fidelityfx_loader_dx12.dll` / `amd_fidelityfx_loader_vk.dll` by name
12411241
(the VK loader then loads `amd_fidelityfx_upscaler_vk.dll`).
1242+
- **The vendor runtimes a payload was built against** (`upscaler-runtimes.json`): `build-native.ps1`
1243+
writes it beside each Upscalers payload (`runtimes-upscalers/<rid>/`, outside `native/` so it is not
1244+
copied next to applications): each SDK at NRI's pin (FidelityFX and XeSS archive tags and `NGX_VERSION`
1245+
in `nri/CMakeLists.txt`, NIS from `nri/Shaders/NIS.hlsl`) and each runtime NRI's build fetched, by file
1246+
version and SHA-256. At v191: NIS 1.0.3 (compiled in), FidelityFX SDK 2.4.0 (loaders 2.3.0.4555 and
1247+
1.0.2.4555, upscalers 4.1.2.4555), XeSS SDK 3.0.2 (`libxess.dll` 2.0.2.68), NGX 310.9.16 (not built).
1248+
The package carries it; `release.yml` lists it under the notes' NRI line
1249+
(`tools/ci/upscaler-runtimes.ps1`); `NativePayloadTests` holds it to the pins and to
1250+
`GetRuntimeFiles`.
12421251
- **`GetRuntimeFiles` must name what the pinned NRI loads**; check it whenever the pin moves. v190
12431252
loaded `amd_fidelityfx_vk.dll` for FSR on Vulkan; naming that file on v191 made the guard refuse
12441253
FSR with the right files installed (`UpscalerExtensionTests`).

‎docs/guide.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,10 @@ headers do not say. NRI v191.
6666
| XeSS | `libxess.dll` | not offered |
6767
| DLSR / DLRR | `nvngx_dlss*.dll` (DLSS build only) | same |
6868

69-
`NriUpscalerExtension.GetRuntimeFiles(type, api)` names them for the running build.
69+
`NriUpscalerExtension.GetRuntimeFiles(type, api)` names them for the running build. Which versions:
70+
`SharpNRI.Native.Upscalers` carries `runtimes/<rid>/upscaler-runtimes.json`, each SDK at NRI's pin and
71+
each runtime NRI's build fetched with its file version and SHA-256, and each release lists them
72+
under its NRI version. Ship those, or a later version the vendor declares compatible.
7073
- DLSS: `pwsh tools/build-native.ps1 -WithDlss <DLSS SDK dir>` builds an NGX-linked `NRI.dll` into
7174
`runtimes-upscalers-dlss/<rid>/native/`. NGX is linked statically, so that `NRI.dll` is under
7275
NVIDIA's RTX SDK licence: yours to ship, never packed here.

‎docs/releases/v1.0.0-beta.2.md‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,30 @@
33
## Changes
44

55
### Added
6-
- Published on NuGet.org: `dotnet add package SharpNRI --prerelease`. The packages carry a readme.
6+
- Published on NuGet.org: `dotnet add package SharpNRI --prerelease`. The packages carry a readme and XML documentation (IntelliSense).
7+
- `SharpNRI.Native.Upscalers` records the vendor runtimes it was built against (listed above) in `runtimes/<rid>/upscaler-runtimes.json`, with each file's version and SHA-256: the versions an application ships beside it.
8+
- A failed vendor upscaler call reports why through the message callback, in release builds too: a missing or incomplete FSR loader, `ffxCreateContext`, the XeSS calls, NGX initialization and feature creation, and a failed dispatch (`ffxDispatch`, `xessD3D12Execute`, NGX evaluation), which used to leave the output unchanged without a word.
9+
- Zero allocation covers every per-frame call of the binding, not only a representative frame: every command and overload, submission, queue, fence, query and descriptor call, the static helpers, and every extension's per-frame calls (guide: Zero allocation). A test fails for any public call added later until it is measured.
710

811
### Fixed
12+
- Vulkan applications presenting while RivaTuner Statistics Server runs (the overlay of MSI Afterburner, CapFrameX and HWiNFO) ended at the first present with 0xC0000409. NRI now lists physical devices with `vkEnumeratePhysicalDevices`, as the layer expects, without the extra call beta.1 made after device creation.
13+
- D3D12 micromaps: the debug layer refused every micromap creation (`[1162] ... InputBuffer and PerOmmDescs can't be null`); the size query now passes the dummy addresses the DXR specification asks for.
14+
- Vulkan AV1 encode: session parameters from a sequence without a colour description were refused (`VK_ERROR_INVALID_VIDEO_STD_PARAMETERS_KHR`); the colours are now passed as "unspecified", as AV1 defines them.
15+
- `CreateStreamer` with the default (zero) constant buffer size was refused by NRI validation for its constant buffer location, which is not used then.
16+
- Lavapipe on Windows: every pipeline without a logic op crashed the driver; NRI now passes a valid value for the disabled logic op (a driver workaround, harmless everywhere).
917
- `WriteShaderGroupIdentifiers` with a group range past the pipeline's groups ended the process on D3D12 and Vulkan, also with NRI validation on; validation now refuses the range with `INVALID_ARGUMENT`.
1018
- Vulkan pipeline-statistics query pools on a device with mesh shaders but without mesh-shader queries drew a validation error at creation and reported a query size two counters too large.
1119
- `ENABLE_DRAW_PARAMETERS_EMULATION` on Vulkan: indirect draws with the plain `DrawDesc` / `DrawIndexedDesc` records were refused. The flag is D3D12 and Metal only and now has no effect on Vulkan, so it can be set on every backend.
20+
- `NriAccelerationStructure.Buffer` and `NriMicromap.Buffer` made a new wrapper on every read (a barrier per frame allocated); the wrapper is now made once per object.
21+
- Command-buffer, queue and thread annotations allocated native memory for their name on every call; names up to 255 UTF-8 bytes are now encoded on the stack.
1222
- Documentation: `SwapChainBits.LATEST_READY` with `VSYNC` does not cap rendering at the refresh rate; the display shows the newest ready image at each vblank.
1323

24+
### Notes
25+
- NVIDIA's Vulkan driver (617.14 and 621.14 measured) fails an AV1 encode into a bitstream buffer without `HOST_VISIBLE` memory, silently: put the AV1 bitstream in `HOST_READBACK` memory there (guide: Video).
26+
27+
## Breaking changes
28+
- `NriDeviceOptions.VkEnumeratePhysicalDevicesAfterCreation` is gone: NRI enumerates physical devices itself, so the option has nothing left to do. Remove it from device options.
29+
- `NriApi.HAS_BUFFER` is `static readonly`; it could be assigned, process-wide. Use `NriBuffer.HasBuffer`.
30+
- `NriCopyImguiDataDesc`, `NriStreamBufferDataDesc` and `NriStreamTextureDataDesc` are `readonly ref struct`s; their properties were already init-only.
31+
1432
## Verified
15-
NVIDIA GeForce RTX 4070 SUPER (Vulkan, D3D12) at c213de0 ([coverage](https://github.com/Nullpoint56/SharpNRI/blob/v1.0.0-beta.2/docs/coverage.md)); Microsoft Basic Render Driver (WARP, D3D12) and Mesa llvmpipe (lavapipe, Vulkan) at 42797cb, whose library code c213de0 changes only in a documentation comment.

‎tests/SharpNRI.Tests/NativePayloadTests.cs‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,45 @@ private static void AssertExactly(string dir, string[] expected)
137137
[UpscalersFact]
138138
public void Upscalers_is_exactly_the_contract() => AssertExactly(Dir("runtimes-upscalers"), Upscalers[Rid]);
139139

140+
/// <summary>
141+
/// upscaler-runtimes.json beside the Upscalers payload (the package carries it, the release notes
142+
/// list it) names each upscaler SDK at NRI's pin, and on Windows each runtime NRI's build fetched,
143+
/// with a file version and SHA-256.
144+
/// </summary>
145+
[UpscalersFact]
146+
public void Upscalers_records_the_vendor_runtimes_it_was_built_against()
147+
{
148+
var path = Path.Combine(RepoRoot, "runtimes-upscalers", Rid, "upscaler-runtimes.json");
149+
Assert.True(File.Exists(path), $"{path} is absent. Run: pwsh tools/build-native.ps1 -Rid {Rid} -Variant Upscalers");
150+
using var manifest = System.Text.Json.JsonDocument.Parse(File.ReadAllText(path));
151+
var root = manifest.RootElement;
152+
Assert.Equal(NriHeader.PinnedVersion.ToString(System.Globalization.CultureInfo.InvariantCulture), root.GetProperty("nri").GetString());
153+
Assert.Equal(Rid, root.GetProperty("rid").GetString());
154+
155+
var cmake = File.ReadAllText(Path.Combine(RepoRoot, "nri", "CMakeLists.txt"));
156+
string Pin(string pattern) => System.Text.RegularExpressions.Regex.Match(cmake, pattern).Groups[1].Value;
157+
var sdks = root.GetProperty("sdks").EnumerateArray().ToDictionary(s => s.GetProperty("name").GetString()!);
158+
Assert.Equal(Pin(@"set\(NGX_VERSION ""([\d.]+)""\)"), sdks["NVIDIA DLSS (NGX)"].GetProperty("version").GetString());
159+
Assert.Contains("NVIDIA Image Scaling", sdks.Keys);
160+
if (OperatingSystem.IsWindows())
161+
{
162+
Assert.Equal(Pin(@"FidelityFX-SDK/archive/refs/tags/v([\d.]+)\.zip"), sdks["AMD FidelityFX SDK"].GetProperty("version").GetString());
163+
Assert.Equal(Pin(@"intel/xess/archive/refs/tags/v([\d.]+)\.zip"), sdks["Intel XeSS SDK"].GetProperty("version").GetString());
164+
// What NRI loads (NriUpscalerExtension.GetRuntimeFiles) is what the manifest records
165+
string[] Files(string sdk) => [.. sdks[sdk].GetProperty("runtimes").EnumerateArray().Select(r => r.GetProperty("file").GetString()!)];
166+
foreach (var api in new[] { SharpNRI.Native.GraphicsAPI.D3D12, SharpNRI.Native.GraphicsAPI.VK })
167+
Assert.Subset(Files("AMD FidelityFX SDK").ToHashSet(), NriUpscalerExtension.GetRuntimeFiles(SharpNRI.Native.UpscalerType.FSR, api).ToHashSet());
168+
Assert.Subset(Files("Intel XeSS SDK").ToHashSet(), NriUpscalerExtension.GetRuntimeFiles(SharpNRI.Native.UpscalerType.XESS, SharpNRI.Native.GraphicsAPI.D3D12).ToHashSet());
169+
}
170+
foreach (var runtime in sdks.Values.SelectMany(s => s.GetProperty("runtimes").EnumerateArray()))
171+
{
172+
Assert.Matches(@"^\d+(\.\d+)+$", runtime.GetProperty("version").GetString());
173+
Assert.Matches("^[0-9a-f]{64}$", runtime.GetProperty("sha256").GetString());
174+
}
175+
GpuWork.Record(string.Join("; ", sdks.Values.Select(s => $"{s.GetProperty("name").GetString()} {s.GetProperty("version").GetString()}: "
176+
+ string.Join(", ", s.GetProperty("runtimes").EnumerateArray().Select(r => $"{r.GetProperty("file").GetString()} {r.GetProperty("version").GetString()}")))));
177+
}
178+
140179
[AgilityFact]
141180
public void Agility_is_exactly_the_contract() => AssertExactly(Dir("runtimes-agility"), Agility[Rid]);
142181

‎tools/build-native.ps1‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -431,6 +431,55 @@ foreach ($u in $unexpected) {
431431
else { Write-Warning "not staged: $u (review whether NRI needs it at run time)" }
432432
}
433433

434+
# ------------------------------------------------------------------------------- vendor runtimes
435+
# What this NRI was built against, for the application that ships the runtimes: each upscaler SDK
436+
# at NRI's pin (nri/CMakeLists.txt) and each runtime NRI's build fetched with it, by file version
437+
# and SHA-256. Beside native/, so the package carries it (runtimes/<rid>/upscaler-runtimes.json)
438+
# and it is not copied next to the application; the release notes list it (release.yml).
439+
if ($variantKey -ne "base") {
440+
$cmake = Get-Content (Join-Path $nri "CMakeLists.txt") -Raw
441+
function PinOf([string]$Pattern, [string]$What) {
442+
if ($cmake -notmatch $Pattern) { throw "the $What pin was not found in nri/CMakeLists.txt" }
443+
$Matches[1]
444+
}
445+
function RuntimesOf([string]$Pattern) {
446+
@(Get-ChildItem $bin -File | Where-Object { $_.Name -match $Pattern } | Sort-Object Name | ForEach-Object {
447+
$version = $_.VersionInfo.FileVersion
448+
if (-not $version -and $_.Name -match '\.so\.([\d.]+)$') { $version = $Matches[1] }
449+
[ordered]@{ file = $_.Name; version = "$version".Trim(); sha256 = (Get-FileHash $_.FullName -Algorithm SHA256).Hash.ToLowerInvariant() }
450+
})
451+
}
452+
$sdks = [System.Collections.Generic.List[object]]::new()
453+
if (& $on NRI_ENABLE_NIS_SDK) {
454+
$nisVersion = if ((Get-Content (Join-Path $nri "Shaders" "NIS.hlsl") -Raw) -match 'NVIDIA Image Scaling SDK\s+-\s+v([\d.]+)') { $Matches[1] } else { throw "the NIS SDK version was not found in nri/Shaders/NIS.hlsl" }
455+
$sdks.Add([ordered]@{ name = "NVIDIA Image Scaling"; version = $nisVersion; runtimes = @(); note = "compiled into NRI; no runtime" })
456+
}
457+
if (& $on NRI_ENABLE_FFX_SDK) {
458+
$sdks.Add([ordered]@{ name = "AMD FidelityFX SDK"; version = (PinOf 'FidelityFX-SDK/archive/refs/tags/v([\d.]+)\.zip' "FidelityFX SDK"); runtimes = [object[]](RuntimesOf '^amd_fidelityfx_(loader|upscaler)_(dx12|vk)\.dll$'); note = "loaded by name at upscaler creation" })
459+
}
460+
if (& $on NRI_ENABLE_XESS_SDK) {
461+
$sdks.Add([ordered]@{ name = "Intel XeSS SDK"; version = (PinOf 'intel/xess/archive/refs/tags/v([\d.]+)\.zip' "XeSS SDK"); runtimes = [object[]](RuntimesOf '^libxess\.dll$'); note = "delay-loaded at upscaler creation" })
462+
}
463+
$ngxVersion = PinOf 'set\(NGX_VERSION "([\d.]+)"\)' "NGX"
464+
if (& $on NRI_ENABLE_NGX_SDK) {
465+
$sdks.Add([ordered]@{ name = "NVIDIA DLSS (NGX)"; version = $ngxVersion; runtimes = [object[]](RuntimesOf '^(nvngx_dlssd?\.dll|libnvidia-ngx-dlssd?\.so\..*)$'); note = "NGX linked statically; feature DLLs loaded at creation" })
466+
} else {
467+
$sdks.Add([ordered]@{ name = "NVIDIA DLSS (NGX)"; version = $ngxVersion; runtimes = @(); note = "not built (only with -WithDlss, never packed)" })
468+
}
469+
foreach ($s in $sdks) {
470+
if ($s.note -notmatch '^(compiled|not built)' -and $s.runtimes.Count -eq 0) { throw "$($s.name): NRI's build fetched no runtime to record" }
471+
foreach ($r in $s.runtimes) { if (-not $r.version) { throw "$($s.name): $($r.file) has no version" } }
472+
}
473+
$manifest = [ordered]@{ nri = $NriVersion; rid = $Rid; sdks = $sdks }
474+
$manifestPath = Join-Path $root $stageRoot $Rid "upscaler-runtimes.json"
475+
$manifest | ConvertTo-Json -Depth 5 | Set-Content $manifestPath -Encoding utf8NoBOM
476+
Write-Host " vendor runtimes recorded in $manifestPath"
477+
foreach ($s in $sdks) {
478+
$files = ($s.runtimes | ForEach-Object { "$($_.file) $($_.version)" }) -join ", "
479+
Write-Host (" {0} {1}: {2}" -f $s.name, $s.version, $(if ($files) { $files } else { $s.note }))
480+
}
481+
}
482+
434483
# ------------------------------------------------------------------------------------------ licences
435484
# Only for what is inside the staged files: compiled into NRI, linked into NRI, or shipped beside it.
436485
StageLicense "NRI" (Join-Path $nri "LICENSE.txt")

‎tools/ci/upscaler-runtimes.ps1‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<#
2+
.SYNOPSIS
3+
Renders the vendor runtimes an Upscalers payload was built against as the Markdown list the
4+
release notes show under the NRI version line.
5+
6+
.DESCRIPTION
7+
Reads upscaler-runtimes.json, which tools/build-native.ps1 writes beside each Upscalers payload
8+
(runtimes-upscalers/<rid>/upscaler-runtimes.json; the package carries it as
9+
runtimes/<rid>/upscaler-runtimes.json), and prints one list item per upscaler SDK: its version at
10+
NRI's pin and each runtime file with its file version. release.yml inserts the output under the
11+
first line of docs/releases/<tag>.md. Run it locally to preview:
12+
13+
pwsh tools/ci/upscaler-runtimes.ps1 runtimes-upscalers/win-x64/upscaler-runtimes.json
14+
#>
15+
param(
16+
[Parameter(Mandatory)] [string]$Manifest
17+
)
18+
19+
$ErrorActionPreference = "Stop"
20+
$m = Get-Content $Manifest -Raw | ConvertFrom-Json
21+
if (-not $m.sdks) { throw "$Manifest lists no upscaler SDK" }
22+
23+
"- Upscalers (``SharpNRI.Native.Upscalers``, $($m.rid)) built against, runtimes shipped by the application:"
24+
foreach ($s in $m.sdks) {
25+
$files = @($s.runtimes | ForEach-Object { "``$($_.file)`` $($_.version)" })
26+
$what = if ($files.Count) { $files -join ", " } else { $s.note }
27+
" - $($s.name) $($s.version): $what"
28+
}

0 commit comments

Comments
 (0)