Compare commits

...
Author SHA1 Message Date
poli0981andClaude Fable 5.2 1578dde38b release: 0.1.0-beta.43 - two hooks installed only where asked for (what a game tells Streamline each frame, how it configures FSR frame generation), the guard reads a moving module list again, an FSR UPSCALE counted once (D123-D125): its changelog file, HANDOFF's beta.43 section, owner-only item 41, the release lines
docs/changelog/0.1.0-beta.43.md takes [Unreleased]; HANDOFF's beta.42 section moves verbatim to docs/handoff/history/0.1.0-beta.42.md and a new START HERE says what the release decided beyond D123-D125, the traps of the train and what is left open; owner-only item 41 is the first real games with the two new hooks, with what each outcome means written before the run.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 13:22:33 +07:00
poli0981andClaude Fable 5.2 3558284a75 feat(advanced): a session shows what the game told Streamline each frame and how it configured FSR frame generation - six catalog entries read inside the game, and for each of the two calls whether it was read, never called or not hooked; Privacy Policy 2.17 (beta.43 PR-4) (#417)
The Agent and the App for the two hooks of #415 and #416. InGameAdvancedSampler makes sl.constants.jitter, .motion_vectors, .depth, .projection, .resets and ffx.framegen.config from members region 5 already had; the count is brought up to the last publication when the session ends. AdvancedSources gains StreamlineConstants and FsrFrameGeneration (AdvancedInGameCall), from the hook families the writer state published and what the publications carried; the session's sources line says it in en, vi, ja. Privacy Policy 2.17 names the two readings and says the two calls are intercepted only once a session with the option on has started in the game; the accuracy block, LIMITATIONS, the guide and docs 06, 08, 18 follow. No schema change (23), no layout change (5).

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 06:22:01 +00:00
poli0981andClaude Fable 5.2 b2e90324c5 feat(overlay): hook ffxConfigure on the four ffx-api modules - how a game configures FSR frame generation, read only while the Agent asks and patched only once it has; never the swapchain, the callbacks, the HUD-less resource or the frame id (beta.43 PR-3) (#416)
Four inventory rows, family FL_HOOK_FFX_CONFIGURE (bit 14), installed only in a process asked for Advanced metrics at least once and published when every loaded ffx-api module is patched. fl_adv_fields.h reads frameGenerationEnabled, allowAsyncWorkloads, flags, onlyPresentGenerated and generationRect of a frame-generation configuration into region 5's ffxFg group, counted at the first module that saw one; the rectangle is kept in one word so it cannot tear, and one that does not fit is four -1. Every configure type is kept for the log (FFX_CONFIGURE). tools/overlay-fields-check.ps1 gains the parameter g and five list entries.

Measured on the headers with the Overlay's flags: +1.7 ns not asked, +15.2 ns on the counted module, +2.7 ns on the forwarded copy.

The test's 'is this export patched' compares the target's bytes with the file's own.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 06:05:06 +00:00
poli0981andClaude Fable 5.2 b4feea1b0b feat(overlay): hook slSetConstants - what a game tells Streamline about each frame, read only while the Agent asks and patched only once it has; never the matrices or the camera's position and axes (beta.43 PR-2) (#415)
A new inventory row, sl.interposer.dll!slSetConstants, family FL_HOOK_SL_CONSTANTS (bit 13). InstallByFamily returns before resolving the symbol in a process never asked for Advanced metrics (D111), so nothing is patched with the option off. The detour checks the request, MayObserve, the struct's GUID and version and the viewport handle's on every call; fl_adv_fields.h reads jitterOffset, mvecScale, cameraNear, cameraFar, cameraFOV, cameraAspectRatio and the seven Booleans into region 5's sl group, summarised for the first viewport seen. tools/overlay-fields-check.ps1 gains the parameter k and thirteen list entries; the camera's names are still refused everywhere.

Measured on the headers with the Overlay's flags: +0.6 ns not asked, +19.6 ns asked on the summarised viewport, +5.8 ns on another.

ctest fl_adv_fields and fl_guard [advanced]: never asked - the export's first 16 bytes in the target are the file's; asked - the first viewport's numbers and none of the second's; no longer asked - the region unchanged; stopped - the bytes restored.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 04:43:24 +00:00
poli0981andClaude Fable 5.2 31d79184eb fix(overlay): an FSR UPSCALE is counted at the first source that saw one - a loader that hands a dispatch on to the leaf's export brought it to two hooked modules, and the frame count would have doubled with frame generation off (beta.43 PR-1, D125; decisions D124-D125) (#414)
g_ffxUpscaleOwner gates the count and the source word through fl::adv::Owns; the FSR 3.0 host is a source like the four leaves; the render size and the quality byte are not gated. Measured on Cyberpunk 2077's loader 2.3.0 for frame-generation dispatches; no title run so far upscales through such a loader, so it is a precaution, held by the stub loader bound through the leaves' exports (hook-harness --ffx-topology 2x-export): 60 presents read as 120 frames before, 60 after.

Measured on the header's Owns with the Overlay's flags: +0.02 to +0.03 ns on the counted module.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 04:22:06 +00:00
poli0981andClaude Fable 5.2 ab8b4ac158 fix(guard): a module list that changed while it was read is read again before the guard refuses (D123) (#413)
* fix(guard): a module list that changed while it was read is read again, at most three times, before the guard refuses - launches were being lost as a safety unhook with no frame recorded (owner decision D123)

Collected::kUnsettled for a module that was in the list and could not be named (until now kIncomplete, an immediate refusal). CheckModules re-reads the whole scan set from a fresh snapshot after kScanRetryPauseMs, up to kMaxUnsettledRereads (3) times; a list still unsettled on the last read refuses kModuleScanFailed with its own signal. A finding - also among the modules that were read from a half-read list - a protected process and a list too long for the buffer still refuse at once; D48's re-read stays one. The launch poll's runtime probe asks again on an unsettled list.

ctest fl_guard [D123]: ten sections against fakes, and the real source against a process that loads and frees a module in a loop (hook-harness --churn-module): about one read in four unsettled, none anything else.

HANDOFF: D123; the Cyberpunk FSR 3 session cannot be run (the game's only FSR upscaler is 2.1), D121 closed.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* test(guard): the live D123 case counts its answers with an if-chain - Qodana's switch-enum on a switch that named two of five values

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 04:05:20 +00:00
poli0981andClaude Fable 5.2 6d4e799f68 docs(handoff): what the first four sessions on beta.42 showed - Cyberpunk's upscale was FSR 2.1, built into the game (D121) (#412)
* docs(handoff): what the owner's first four sessions on 0.1.0-beta.42 showed - Cyberpunk's upscale was FSR 2.1, built into the game (D121 answered); the 2.3 loader re-enters the leaf's export; the plane at infinity measured on two titles

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* docs(handoff): three more starts of Cyberpunk on beta.42 - the game was still on FSR 2 (the settings file says so), and the first start was lost to a module list read while the game was loading: five such ends in the Agent's logs since 2026-11-05, and a decision for the owner

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* docs(handoff): the owner's screenshot of Cyberpunk's Graphics menu confirms it - Resolution Scaling is FSR 2.1

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 03:29:32 +00:00
poli0981andClaude Fable 5.2 e2de7cfbc0 docs(handoff): 0.1.0-beta.42's release facts - the tag's run, the digests, the delta, the wiki run; SonarCloud's one finding fixed (a strlen in a test helper); two transient failures recorded (#411)
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 03:05:42 +00:00
54 changed files with 2673 additions and 187 deletions

No files matched your search

+1 -1
View File
@@ -9,7 +9,7 @@ barrier. It is written for the person who has just met one; the details for deve
FrameLedger is a desktop program: its own window, its dialogs, its document windows, the icon by the clock and the
notices Windows shows for it. It draws nothing inside a game, so it cannot make a game itself any easier to use.
*Beta software: this page describes version 0.1.0-beta.42. In the app: Help ▸ Accessibility.*
*Beta software: this page describes version 0.1.0-beta.43. In the app: Help ▸ Accessibility.*
## What FrameLedger aims for
+1
View File
@@ -41,6 +41,7 @@ Newest first. Each file holds that release's section exactly as it stood here.
| Version | Date | Notes |
|---|---|---|
| `0.1.0-beta.43` | 2026-11-12 | [`docs/changelog/0.1.0-beta.43.md`](docs/changelog/0.1.0-beta.43.md) |
| `0.1.0-beta.42` | 2026-11-12 | [`docs/changelog/0.1.0-beta.42.md`](docs/changelog/0.1.0-beta.42.md) |
| `0.1.0-beta.41` | 2026-11-12 | [`docs/changelog/0.1.0-beta.41.md`](docs/changelog/0.1.0-beta.41.md) |
| `0.1.0-beta.40` | 2026-11-12 | [`docs/changelog/0.1.0-beta.40.md`](docs/changelog/0.1.0-beta.40.md) |
+3
View File
@@ -122,6 +122,9 @@ src/
# memory's region 5 - what a hooked game told DLSS and FSR, read by the Overlay
# only while the session asks (ICaptureObserver.WantsInGameAdvanced) - into session
# facts and two adv.* series; reach `Game` in the catalog; no schema change.
# Since 0.1.0-beta.43 also what the game tells Streamline each frame and how it
# configures FSR frame generation, from two calls hooked only once Advanced has been
# asked for; AdvancedInGameCall says of each: read, never called, or not hooked.
FrameLedger.Infrastructure/ # SQLite, shm reader, vendor APIs, injector interop, parsers,
# and Capture/ (PR-C): ShmRingAttacher/ShmCaptureSink over the
# reader, HeldProcessLivenessSource, TargetResolver (path only,
+15 -3
View File
@@ -5,7 +5,7 @@ hooking on for — and reading the graphics calls the game makes. That is why it
resolution, the upscaler, frame generation and ray tracing apart. It is also where its limits come from. This
page lists them in plain words; each item links to the document that has the details.
*Beta software: this page describes version 0.1.0-beta.42.*
*Beta software: this page describes version 0.1.0-beta.43.*
## Games it will not measure
@@ -90,7 +90,9 @@ shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.md))
same games as *Render → output resolution* in the accuracy statement; elsewhere it says it was not measured.
- The upscaler is read from the game's calls: DLSS and NIS through NVIDIA Streamline, and FSR through AMD's
FidelityFX libraries. **Intel XeSS is not read** (its licence forbids it), FSR 2 and upscalers built into the
game are not identified, and Vulkan and OpenGL games read N/A. Where no hook saw DLSS but the NVIDIA driver
game are not identified — Cyberpunk 2077's FSR 2.1 is one: its sessions say "unknown" beside a measured render
size — and Vulkan and OpenGL games read N/A. A game that sends FSR upscaling through two unrelated libraries in
one run is counted from the first alone (none is known). Where no hook saw DLSS but the NVIDIA driver
reports it, the page says it is the driver's report.
- **The quality mode** (Quality, Balanced, DLAA, …) is shown only when it is known: the NVIDIA App's override
where the NVIDIA driver reports it applied (marked *· NVIDIA App*, since 0.1.0-beta.24), or the mode the game
@@ -182,7 +184,17 @@ shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.md))
library. The session says which it was — nothing seen, or not measured inside the game — and neither means the
game uses no upscaler. They are the game's words, not a check of what the upscaler did; the field of view is a
lowest and highest value, never a line over time; FSR's memory is a point where the game asked, so most sessions
have none. **None of it has been read from a real game yet.**
have none. FSR's upscaling values have been read from real games; **the DLSS options have not been confirmed on
one yet.**
- **What a game tells Streamline each frame, and how it configures FSR frame generation** (since 0.1.0-beta.43)
are read from two calls FrameLedger hooks **only once a session with Advanced metrics on has started in that
game** — a session recorded with the option off puts neither hook in. Streamline's values are those of **the
first viewport that called**: a game with several (split screen, a picture-in-picture view) shows one, and the
count of calls covers all. The frame-generation rows are **what the game asked for** — a game that asks for
generation and gets none still reads "on", and the session's summary is where what was generated is measured. A
setting the game changed during the session reads "on and off". The session's line says, for each of the two,
whether it was read, hooked and never called by the game, or not hooked (the game did not load the library).
Streamline 1.x is not read. **Neither has been confirmed on a real game yet.**
- **The driver's own figures** — the card's firmware and architecture, its memory in detail, what a display can do
with HDR and variable refresh, the driver's settings for the game — exist on **NVIDIA** cards only. On other cards
they read N/A; the card's sensors (fans, voltages, loads) are read on every brand, and none has been tested on an
+7 -3
View File
@@ -13,7 +13,7 @@ app too (Help ▸ User guide, Help ▸ Limitations, Help ▸ Accessibility), and
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-11-11.** The software is a beta; its latest
> **beta is `0.1.0-beta.42`** (2026-11-12), an unsigned installer built from that tag with its
> **beta is `0.1.0-beta.43`** (2026-11-12), an unsigned installer built from that tag with its
> checksums published beside it (alphas — experimental builds that try a newer .NET — are published apart). The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs (unless you switched its recording off), injects only into games you enabled
@@ -114,7 +114,11 @@ app too (Help ▸ User guide, Help ▸ Limitations, Help ▸ Accessibility), and
> range, field-of-view range, flags and frame time it hands FSR, are read from the arguments of the calls
> FrameLedger intercepts and shown as the game stated them — not checked against what the upscaler did. Most games
> set their DLSS options through a call that cannot be intercepted and show none; the FSR values need FSR 3.1 or
> later through AMD's own library. None of it has been read from a real game yet.
> later through AMD's own library. Since beta.43 also what a game tells NVIDIA Streamline about each frame (jitter,
> motion-vector scale, depth range, field-of-view range, how often it reset the upscaler's history — for the first
> viewport that called, where a game has several) and how it configures FSR frame generation (the settings it asked
> for, not whether frames were generated). FSR's upscaling values have been read from real games; the DLSS options,
> Streamline's constants and the frame-generation configuration have not been confirmed on one yet.
> - **Safety:** every pre-injection check runs before injection, including the signed-by-a-known-vendor
> half of the suspicious-module rule. During every capture the Agent re-runs the checks every 30 s and
> stops capturing on a refusal: a Direct3D or OpenGL game's hooks are removed, and the Vulkan layer
@@ -191,7 +195,7 @@ Elevation is **optional — for everything.** Hooked capture is the normal path
## Install
> **The latest beta is `v0.1.0-beta.42` (2026-11-12); before it `v0.1.0-beta.41` (2026-11-12), `v0.1.0-beta.40` (2026-11-12), `v0.1.0-beta.39` (2026-11-11), `v0.1.0-beta.38` (2026-11-11), `v0.1.0-beta.37` (2026-11-11), `v0.1.0-beta.36` (2026-11-10), `v0.1.0-beta.35` (2026-11-09), `v0.1.0-beta.34` (2026-11-06), `v0.1.0-beta.33` (2026-11-03), `v0.1.0-beta.32` (2026-10-31), `v0.1.0-beta.31` (2026-10-26), `v0.1.0-beta.30` (2026-10-26), `v0.1.0-beta.29` (2026-10-25), `v0.1.0-beta.28` (2026-10-20), `v0.1.0-beta.27` (2026-10-20), `v0.1.0-beta.26` (2026-10-19), `v0.1.0-beta.25` (2026-10-19), `v0.1.0-beta.24` (2026-10-19), `v0.1.0-beta.23` (2026-10-14), `v0.1.0-beta.22` (2026-10-13), `v0.1.0-beta.21` (2026-10-13), `v0.1.0-beta.20` (2026-10-12), `v0.1.0-beta.19` (2026-10-12), `v0.1.0-beta.18` (2026-10-07), `v0.1.0-beta.17` (2026-10-07), `v0.1.0-beta.16` (2026-10-06), `v0.1.0-beta.15` (2026-10-06), `v0.1.0-beta.14` (2026-10-06), `v0.1.0-beta.13` (2026-10-04), `v0.1.0-beta.12` (2026-10-04), `v0.1.0-beta.11` (2026-10-03), `v0.1.0-beta.10` (2026-09-28), `v0.1.0-beta.9` (2026-09-26), `v0.1.0-beta.8` (2026-09-25), `v0.1.0-beta.7` (2026-09-23), `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read the notes of the one you install — `CHANGELOG.md` links each release's own file under `docs/changelog/` — for what it measures, what it does not yet, and how to update, before installing. A source build is `docs/12_BUILD.md`.
> **The latest beta is `v0.1.0-beta.43` (2026-11-12); before it `v0.1.0-beta.42` (2026-11-12), `v0.1.0-beta.41` (2026-11-12), `v0.1.0-beta.40` (2026-11-12), `v0.1.0-beta.39` (2026-11-11), `v0.1.0-beta.38` (2026-11-11), `v0.1.0-beta.37` (2026-11-11), `v0.1.0-beta.36` (2026-11-10), `v0.1.0-beta.35` (2026-11-09), `v0.1.0-beta.34` (2026-11-06), `v0.1.0-beta.33` (2026-11-03), `v0.1.0-beta.32` (2026-10-31), `v0.1.0-beta.31` (2026-10-26), `v0.1.0-beta.30` (2026-10-26), `v0.1.0-beta.29` (2026-10-25), `v0.1.0-beta.28` (2026-10-20), `v0.1.0-beta.27` (2026-10-20), `v0.1.0-beta.26` (2026-10-19), `v0.1.0-beta.25` (2026-10-19), `v0.1.0-beta.24` (2026-10-19), `v0.1.0-beta.23` (2026-10-14), `v0.1.0-beta.22` (2026-10-13), `v0.1.0-beta.21` (2026-10-13), `v0.1.0-beta.20` (2026-10-12), `v0.1.0-beta.19` (2026-10-12), `v0.1.0-beta.18` (2026-10-07), `v0.1.0-beta.17` (2026-10-07), `v0.1.0-beta.16` (2026-10-06), `v0.1.0-beta.15` (2026-10-06), `v0.1.0-beta.14` (2026-10-06), `v0.1.0-beta.13` (2026-10-04), `v0.1.0-beta.12` (2026-10-04), `v0.1.0-beta.11` (2026-10-03), `v0.1.0-beta.10` (2026-09-28), `v0.1.0-beta.9` (2026-09-26), `v0.1.0-beta.8` (2026-09-25), `v0.1.0-beta.7` (2026-09-23), `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read the notes of the one you install — `CHANGELOG.md` links each release's own file under `docs/changelog/` — for what it measures, what it does not yet, and how to update, before installing. A source build is `docs/12_BUILD.md`.
1. Download the latest `FrameLedger.App-win-Setup.exe` from [Releases](https://github.com/poli0981/frameledger/releases). It installs into `%LOCALAPPDATA%\FrameLedger.App`; your data stays in `%LOCALAPPDATA%\FrameLedger`, and uninstalling asks before touching it.
2. SmartScreen may warn — releases are not code-signed (free, open-source project). Verify the SHA-256 checksum published with each release, then **More info → Run anyway**.
+4 -1
View File
@@ -761,7 +761,10 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
> 0.1.0-beta.40 (train B) the same row holds what the game told its upscaler** — the session facts of the entries
> whose reach is `Game`, after the driver's, and `sources.inGame` (`Reading`, `NothingSeen`, `NotHooked`; absent in
> a row beta.39 wrote, which reads as "not said") — and its two series are `adv.ffx.upscale.frame_time_delta` and
> `adv.ffx.memory_usage` in `sensor_blobs`. No column and no script: schema 23 as it was. A session deleted
> `adv.ffx.memory_usage` in `sensor_blobs`. **Since 0.1.0-beta.43** `sources` may also hold `streamlineConstants`
> and `fsrFrameGeneration` (`Read`, `NeverCalled`, `NotHooked`; `Application.Advanced.AdvancedInGameCall`) — what
> became, in that session, of the two calls hooked only for Advanced metrics; both absent in a row written before,
> and in a session not measured inside the game. No column and no script: schema 23 as it was. A session deleted
> takes its row with it; a profile no session points to is left, as a hardware snapshot is; the retention sweep
> removes a session's `adv.` series with its other raw series and keeps its row. Written by the Agent only, in the
> session's own transaction (`SqliteSessionRepository.InsertAdvancedAsync`). `LatestVersion` is 23;
+12 -1
View File
@@ -133,7 +133,18 @@ What the region is, as a contract between the two sides:
beta.43~~ 0.1.0-beta.43 and beta.44 fill *(renumbered twice on 2026-11-12 — D118: a fix release took beta.41;
D122: the second step became two releases, and beta.42 fills none of them. The comments in `fl_shm.h` and
`ShmLayout.cs` carry the new numbers since beta.42)* (`ffxFg*`,
`sl*`, `features`) are declared now and stay zero until then, so those releases bump no layout.
`sl*`, `features`) are declared now and stay zero until then, so those releases bump no layout. **The `sl*` group
is filled since 0.1.0-beta.43** by the `slSetConstants` hook (`17_HOOK_ENGINE` §Hook inventory), under
`FL_ADV_VALID_SL_CONSTANTS`: the call count of every viewport, and for the first viewport seen the resets, the
jitter's largest magnitude, the motion-vector scale, the two depth planes, the field of view's range, the aspect
ratio, and one bit per `Boolean` in each of two words — seen true, seen false. `FlHookFamily` gains
`FL_HOOK_SL_CONSTANTS` (bit 13): the hook is in, which it is only in a process that was asked at least once.
**The `ffxFg*` group is filled since the same release** by the `ffxConfigure` hook, under
`FL_ADV_VALID_FFX_FG_CONFIG`: the frame-generation configures of the one module counted, three switches as "seen
off / seen on" bit pairs (enabled, asynchronous, generated frames only), every flag any configure carried, and
the last generation rectangle as left, top, width, height — **four `-1` for a rectangle with a negative side or
one past 32,767**, never a clipped one. `FL_HOOK_FFX_CONFIGURE` (bit 14) is published when every ffx-api module
the process loaded has its `ffxConfigure` patched.
- The Vulkan layer never writes it. `ShmLayoutMirrorTests.TheAdvancedStateMirrorMatches` checks every member's
offset against `fl-layout-dump`; `ShmRingReaderTests` the three reads and that the request is stored either way.
+4 -1
View File
@@ -873,7 +873,10 @@ Tail view of `ui-*.log` / `agent-*.log` (toggle), level filter, search (`ui:Auto
> call* (`Advanced_Status_InGame`): it is not a state of the PC. What became of those entries in one session is in
> that session's sources line on the Session tab (`Advanced_InGameLine` with `AdvInGame_*`): read, the game made none
> of the calls, or the session was not measured inside the game; a session stored before beta.40 has no such
> sentence.
> sentence. **Since 0.1.0-beta.43** a session measured inside the game has one more
> (`Advanced_InGameCallsLine` with `AdvInGameCall_*`): for what the game tells Streamline each frame and for how it
> configures FSR frame generation, each *read*, *hooked - the game did not make the call*, or *not hooked - the
> game did not load the library that has the call*. "Nothing here" then says which of the two it is.
>
> **Words.** Every catalog entry, group, reason, source state and driver token is a `Strings.resx` key made from its own
> name (`Adv_<id>`, `AdvGroup_*`, `AdvReach_*`, `AdvSource_*`, `AdvToken_*`) in `en`, `vi`, `ja`; the English label of
+11 -4
View File
@@ -194,12 +194,14 @@ Every hook must be listed here with a purpose. Anything not on this list is not
|---|---|
| NGX: `NVSDK_NGX_D3D11/D3D12/VULKAN_CreateFeature`, `EvaluateFeature`, `ReleaseFeature` | Which NGX feature is *actually created and evaluated per frame*: SuperSampling (DLSS), RayReconstruction (DLSS-D), FrameGeneration (DLSS-G) |
| NGX parameter accessors (`NVSDK_NGX_Parameter_SetI/GetI/SetUI`) — **exported by `sl.common.dll` only; see below** | `Width`/`Height` (render) vs `OutWidth`/`OutHeight` (output), `PerfQualityValue` (quality preset), sharpness |
| ✅ Streamline: `slEvaluateFeature` · ⏳ `slInit`, `slSetFeatureLoaded`, `slSetConstants`, `slGetFeatureRequirements` | Feature set actually active when the game goes through SL rather than NGX directly (`kFeatureDLSS`, `DLSS_G`, `DLSS_RR`, `Reflex`, `NIS`; since beta.34 `kFeatureDLSS_NR` — DLSS 5's neural rendering, its own fact bit and family `FL_HOOK_SL_NEURAL_RENDERING`, D84; rule 4: the `feature` argument of the API hooked, nothing else). **Built 2026-08-09**, identity only: one MinHook detour on `sl.interposer.dll!slEvaluateFeature`, resolved **module-scoped** and installed lazily by the watchdog. Sets `FL_MEASURED_UPSCALER` + `FL_HOOK_UPSCALER_IDENTITY`; decodes `kFeatureDLSS`/`kFeatureNIS` and reports `FL_UPSCALER_UNKNOWN` for anything else. **Never `FL_UPSCALER_NONE`** — a Streamline-only writer cannot see FFX, XeSS or NGX-direct, and `NONE` is the only one of the three states that may be aggregated as a negative. **Since 0.1.0-beta.40 (Advanced metrics train B, D111), and only while the Agent asks** (`FlControlBlock.advancedRequested`): the `sl::DLSSOptions` a title chains into `inputs` — the struct the quality mode is read from — is read further: `outputWidth`/`outputHeight`, `preExposure`, `exposureScale`, `colorBuffersHDR`, the five presets of version 1, and where the struct's own `structVersion` proves them present `ultraQualityPreset` and `useAutoExposure` (≥ 2) and `alphaUpscalingEnabled` (≥ 3) — §Which struct version carries which field. Rule 4: more members of the same argument of the same call; `fl_adv_fields.h` is the one place, `tools/overlay-fields-check.ps1` holds it. No new patch site. **Measured** (the header's own functions, `/O2 /guard:cf /Qspectre /MT`, 20 M calls × 3): +9.5–11.7 ns per evaluation that chains the options while asked; with the word at 0, one relaxed load and a branch not taken — below what the bench resolves. Most titles set these through `slDLSSSetOptions`, which is not an export, and read N/A (train D) |
| ✅ Streamline: `slEvaluateFeature` · ⏳ `slInit`, `slSetFeatureLoaded`, ~~`slSetConstants`~~ *(its own row below since beta.43)*, `slGetFeatureRequirements` | Feature set actually active when the game goes through SL rather than NGX directly (`kFeatureDLSS`, `DLSS_G`, `DLSS_RR`, `Reflex`, `NIS`; since beta.34 `kFeatureDLSS_NR` — DLSS 5's neural rendering, its own fact bit and family `FL_HOOK_SL_NEURAL_RENDERING`, D84; rule 4: the `feature` argument of the API hooked, nothing else). **Built 2026-08-09**, identity only: one MinHook detour on `sl.interposer.dll!slEvaluateFeature`, resolved **module-scoped** and installed lazily by the watchdog. Sets `FL_MEASURED_UPSCALER` + `FL_HOOK_UPSCALER_IDENTITY`; decodes `kFeatureDLSS`/`kFeatureNIS` and reports `FL_UPSCALER_UNKNOWN` for anything else. **Never `FL_UPSCALER_NONE`** — a Streamline-only writer cannot see FFX, XeSS or NGX-direct, and `NONE` is the only one of the three states that may be aggregated as a negative. **Since 0.1.0-beta.40 (Advanced metrics train B, D111), and only while the Agent asks** (`FlControlBlock.advancedRequested`): the `sl::DLSSOptions` a title chains into `inputs` — the struct the quality mode is read from — is read further: `outputWidth`/`outputHeight`, `preExposure`, `exposureScale`, `colorBuffersHDR`, the five presets of version 1, and where the struct's own `structVersion` proves them present `ultraQualityPreset` and `useAutoExposure` (≥ 2) and `alphaUpscalingEnabled` (≥ 3) — §Which struct version carries which field. Rule 4: more members of the same argument of the same call; `fl_adv_fields.h` is the one place, `tools/overlay-fields-check.ps1` holds it. No new patch site. **Measured** (the header's own functions, `/O2 /guard:cf /Qspectre /MT`, 20 M calls × 3): +9.5–11.7 ns per evaluation that chains the options while asked; with the word at 0, one relaxed load and a branch not taken — below what the bench resolves. Most titles set these through `slDLSSSetOptions`, which is not an export, and read N/A (train D) |
| ✅ Streamline: `slSetConstants` (0.1.0-beta.43, Advanced metrics train B; owner decisions D111–D116, D122) | **What the game tells Streamline about a frame**, once per frame and viewport, read from the `sl::Constants` it passes — rule 4: an argument of the call hooked, and of it only the members named here. **Read:** `jitterOffset`, `mvecScale`, `cameraNear`, `cameraFar`, `cameraFOV`, `cameraAspectRatio` and the seven `Boolean`s (`depthInverted`, `cameraMotionIncluded`, `motionVectors3D`, `reset`, `orthographicProjection`, `motionVectorsDilated`, `motionVectorsJittered`). **Never read:** the five matrices (bytes 32..351 of the struct), `cameraPinholeOffset`, and the camera's position and three axes (bytes 368..423) — `tools/overlay-fields-check.ps1` refuses their names anywhere in code loaded into a game, and ctest `fl_adv_fields` publishes two structs that differ in every one of those bytes and gets the same bytes out. **The one row that is not installed unless asked for** (D111): `InstallByFamily` returns before it resolves the symbol in a process the Agent has never asked for Advanced metrics — resolving takes a reference on the module — so with the option off the export's first bytes are the file's (`fl_guard` `[advanced]` reads them from the target). Once asked, the patch goes in on that watchdog tick and stays for the life of the process; the detour forwards without looking while the request is off, and after a stop (`MayObserve`). **Every call** checks the struct's GUID and a `structVersion` of at least 1 before any member is read, and the viewport handle's the same way; every member read is one version 1 carries, so a version-1 struct laid against unreadable memory is read whole without a fault (the same ctest). **Summaries are the first viewport's**: a title with two viewports sets constants for each every frame, and "the last value" across them would flip twice a frame; the call count is of every viewport. `FLT_MAX` is Streamline's "not set" here and is kept nowhere (D119's plane at infinity is FidelityFX's). Family `FL_HOOK_SL_CONSTANTS` (bit 13), published with the patch: it entitles no field of a frame record, and tells "hooked, never called" from "not hooked". **Measured overhead** (the detour's body on the headers, the Overlay's flags, 20 million calls a run, three runs): not asked **+0.57 / +0.60 / +0.58 ns**; asked, the summarised viewport **+19.61 / +19.54 / +19.79 ns**; asked, another viewport +5.83 / +6.01 / +5.62 ns. |
| ✅ Streamline: `slSetTag` — **and, since 2026-09-05, every tag's TYPE** (`slTagCensus`; a HUD-less / UI tag marks the present `FL_FG_DLSS_G`, rule 4: the same argument) | The **global** resource tags, where a title states the size of the buffer it is upscaling *from*: `kBufferTypeScalingInputColor`'s extent → `renderW/H` — **or, since 2026-09-05, the size the tagged `sl::Resource` declares when the extent is zero** (`TagSize` in `fl_sl_inputs.h`, shared by all three tag routes; GUID-checked; a Resource declaring no size is still the honest unknown). **Built 2026-08-15** (`FL_HOOK_UPSCALER_PARAMS`), and it is an ALTERNATIVE to the local tags in `slEvaluateFeature`'s `inputs`, not a layer over them — `sl_core_api.h:258` says global and local tags "do NOT interact", so a title using one yields nothing from the other and both are read. Published only on a frame where an evaluation was also seen, because a tag is viewport state that outlives any one frame. This row was MISSING from this table while the hook shipped, which is the gap the banner above now names |
| ✅ Streamline: `slSetTagForFrame` — **and every tag's TYPE, as above** | The same global tags through **Streamline 2.8's frame-based entry point**, which deprecates `slSetTag`: `(const FrameToken&, const ViewportHandle&, const ResourceTag*, uint32_t, CommandBuffer*)` — the token first, then exactly `slSetTag`'s list, handed to the same tag walk. **Built 2026-09-04** (`FL_HOOK_UPSCALER_PARAMS`, its own trampoline; the family is now **published when whole** — once every tag export the loaded interposer has is patched — because publishing on the first row entitled records the second was not yet producing, 38 of 41 on the fixture: the ffx leaves' #110 defect again, fixed the same way). Measured need: Dying Light: The Beast (SL 2.8.0) published `Dlss` identity on every batch and the params bit on none across three captures, because a 2.8 title that tags per frame never calls the deprecated export. The token is not read; the frame count stays with `slGetNewFrameToken`. The installer picks this detour by SYMBOL (`kSymbolSlSetTagForFrame`, bound to the row by `static_assert`), not by family, since the two rows share a family bit and differ in signature |
| ✅ **FidelityFX ffx-api: `ffxDispatch` on the FOUR modules a game calls** — `amd_fidelityfx_dx12.dll` (SDK 1.1.x monolith), `amd_fidelityfx_upscaler_dx12.dll`, `amd_fidelityfx_framegeneration_dx12.dll`, **and `amd_fidelityfx_loader_dx12.dll`** (added the evening of 2026-09-04: three loader-shipping titles at FSR produced zero dispatches at any leaf export, so the loader is where their calls arrive) · ⏳ FSR 3.0 host route `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` / `ffxFsr3DispatchFrameGeneration` · ~~`ffxFsr2ContextCreate`~~ · ~~`ffxCreateContext`~~ | **Built 2026-09-04** (`HANDOFF` item 7c). One observer behind three trampolines reads the DESCRIPTOR the title passed — head type first, body only after the type matched a constant from the vendored MIT headers (`third_party/fidelityfx/`, tag v2.3.0): **UPSCALE** → identity (`FSR3` from the monolith, `FSR_UNVERSIONED` from the 2.x upscaler DLL, which hosts FSR 3.1 and FSR 4 behind one type) + `renderSize` → `renderW/H` (quality and sharpness `0xFF`: the dispatch carries neither — *since beta.25 the quality byte is the mode the `ffxQuery` row below names for the dispatched size, `0xFF` when none does*) + one COUNT; **PREPARE / PREPARE_V2** → `frameID` counted on a *new* index only — this vendor's `slGetNewFrameToken`, the `fgEvaluations` producer once a title has ever prepared, with the UPSCALE count as the fallback for a title that never does; **FRAMEGENERATION** → `fgMode = FSR_FG` on that present. Rule 4: the argument of the API we hooked, never `context`, `pNext`, a command list or a resource. **Why all four:** a UE5 title ships the two leaves with no loader and calls their exports; a loader-shipping title calls the loader's export and the signed loader reaches its providers through an object, not the leaves' exports (measured: Dying Light: The Beast, KCD2, Wukong). The morning's "never the loader" rested on the export tables alone and was reversed by the run. What guards against a loader that DID re-enter a leaf's export is the K = 1 control with all four hooked and the consumer's `frames/upscale-drained`, both of which read 2× in that case. `ffxCreateContext` is deliberately NOT a row — nothing it carries fills a field the dispatch does not, and its honest family would collide with `slEvaluateFeature`'s under the installer's equality binding. The family is compound (`IDENTITY \| PARAMS \| FG_EVALUATIONS`), pinned by `static_assert`s that also bind the leaf table to the rows both ways and refuse the loader as a row. Streamline keeps precedence for the count once it has ever issued a token, so every §S31-validated title is byte-identical. Second count: the consumer prints `frames/upscale-drained`, the AMD `tokens/batch`. **FSR 3.0 — BUILT 2026-09-05 as a fifth AMD target:** `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` (Cyberpunk's copy; named export, its own descriptor, vendored from tag **`fsr3-v3.0.4`** — the tag whose twelve `ffxFsr3*` declarations match the shipped module, not the `v1.1.4` first named). Rule 4: the detour reads `renderSize` of the descriptor the title passed and nothing else — never the context, a resource or the command list; the offset is pinned to a literal (1256) so a re-vendoring that moved it fails to compile. Same family and publish point as the four rows (`PublishFfxFamilyIfWhole` waits for a loaded host too), keyed by module in the installer; identity `FSR3` as a fact. `ffxFsr3DispatchFrameGeneration` is deliberately not a row (§H11 carries the reversal condition); the `ffx_fsr3upscaler_x64.dll` leaf is the pre-committed alternative if the facade reads silent (row B2) — never both, or `frames/upscale-drained` reads 2.00. **Since 0.1.0-beta.40 (Advanced metrics train B, D111), and only while the Agent asks:** the UPSCALE arm reads the rest of `ffxDispatchDescUpscale` — `enableSharpening`, `sharpness`, `jitterOffset`, `preExposure`, `cameraNear`, `cameraFar`, `cameraFovAngleVertical`, `flags`, `reset`, `frameTimeDelta` — into process-local summaries (an "ever seen" mask, a largest magnitude, a lowest and highest, a count and a sum; one module's dispatches are counted, so a dispatch that reaches the loader and a leaf is one). Never on the FSR 3.0 host's legacy descriptor, which is vouched for through `renderSize` and no further; never a PREPARE descriptor's camera arrays (`tools/overlay-fields-check.ps1` refuses their names anywhere in the Overlay). `cameraNear`/`cameraFar`/`cameraFovAngleVertical` are the depth range and the field of view, not where the camera is; the field of view is kept as a session's range, never a series (D114). **Measured** (as the row above): +22–23 ns per UPSCALE dispatch, i.e. per application frame, while asked; ≤ 0.7 ns, inside the bench's noise, with the word at 0 |
| ✅ **FidelityFX ffx-api: `ffxDispatch` on the FOUR modules a game calls** — `amd_fidelityfx_dx12.dll` (SDK 1.1.x monolith), `amd_fidelityfx_upscaler_dx12.dll`, `amd_fidelityfx_framegeneration_dx12.dll`, **and `amd_fidelityfx_loader_dx12.dll`** (added the evening of 2026-09-04: three loader-shipping titles at FSR produced zero dispatches at any leaf export, so the loader is where their calls arrive) · ⏳ FSR 3.0 host route `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` / `ffxFsr3DispatchFrameGeneration` · ~~`ffxFsr2ContextCreate`~~ · ~~`ffxCreateContext`~~ | **Built 2026-09-04** (`HANDOFF` item 7c). One observer behind three trampolines reads the DESCRIPTOR the title passed — head type first, body only after the type matched a constant from the vendored MIT headers (`third_party/fidelityfx/`, tag v2.3.0): **UPSCALE** → identity (`FSR3` from the monolith, `FSR_UNVERSIONED` from the 2.x upscaler DLL, which hosts FSR 3.1 and FSR 4 behind one type) + `renderSize` → `renderW/H` (quality and sharpness `0xFF`: the dispatch carries neither — *since beta.25 the quality byte is the mode the `ffxQuery` row below names for the dispatched size, `0xFF` when none does*) + one COUNT *(since 0.1.0-beta.43, owner decision D125: **counted at the first source that saw an UPSCALE and at no other** — `g_ffxUpscaleOwner`, `fl::adv::Owns`. Cyberpunk 2077's loader 2.3.0 hands a dispatch on to the leaf's export — its frame-generation dispatch types are logged on the loader and on the leaf — so an UPSCALE through such a loader reaches two hooked modules, and one count per module read K = 1 as 2.0 on the fixture bound that way (`--ffx-topology 2x-export`: 60 presents, 120 counted). No title run so far upscales through one; it is a precaution. Measured on the header with the Overlay's flags: +0.02 to +0.03 ns on the module that is counted, about 4 ns less on the forwarded copy)*; **PREPARE / PREPARE_V2** → `frameID` counted on a *new* index only — this vendor's `slGetNewFrameToken`, the `fgEvaluations` producer once a title has ever prepared, with the UPSCALE count as the fallback for a title that never does; **FRAMEGENERATION** → `fgMode = FSR_FG` on that present. Rule 4: the argument of the API we hooked, never `context`, `pNext`, a command list or a resource. **Why all four:** a UE5 title ships the two leaves with no loader and calls their exports; a loader-shipping title calls the loader's export and the signed loader reaches its providers through an object, not the leaves' exports (measured: Dying Light: The Beast, KCD2, Wukong). The morning's "never the loader" rested on the export tables alone and was reversed by the run. What guards against a loader that DID re-enter a leaf's export is the K = 1 control with all four hooked and the consumer's `frames/upscale-drained`, both of which read 2× in that case. `ffxCreateContext` is deliberately NOT a row — nothing it carries fills a field the dispatch does not, and its honest family would collide with `slEvaluateFeature`'s under the installer's equality binding. The family is compound (`IDENTITY \| PARAMS \| FG_EVALUATIONS`), pinned by `static_assert`s that also bind the leaf table to the rows both ways and refuse the loader as a row. Streamline keeps precedence for the count once it has ever issued a token, so every §S31-validated title is byte-identical. Second count: the consumer prints `frames/upscale-drained`, the AMD `tokens/batch`. **FSR 3.0 — BUILT 2026-09-05 as a fifth AMD target:** `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` (Cyberpunk's copy; named export, its own descriptor, vendored from tag **`fsr3-v3.0.4`** — the tag whose twelve `ffxFsr3*` declarations match the shipped module, not the `v1.1.4` first named). Rule 4: the detour reads `renderSize` of the descriptor the title passed and nothing else — never the context, a resource or the command list; the offset is pinned to a literal (1256) so a re-vendoring that moved it fails to compile. Same family and publish point as the four rows (`PublishFfxFamilyIfWhole` waits for a loaded host too), keyed by module in the installer; identity `FSR3` as a fact. `ffxFsr3DispatchFrameGeneration` is deliberately not a row (§H11 carries the reversal condition); the `ffx_fsr3upscaler_x64.dll` leaf is the pre-committed alternative if the facade reads silent (row B2) — never both, or `frames/upscale-drained` reads 2.00. **Since 0.1.0-beta.40 (Advanced metrics train B, D111), and only while the Agent asks:** the UPSCALE arm reads the rest of `ffxDispatchDescUpscale` — `enableSharpening`, `sharpness`, `jitterOffset`, `preExposure`, `cameraNear`, `cameraFar`, `cameraFovAngleVertical`, `flags`, `reset`, `frameTimeDelta` — into process-local summaries (an "ever seen" mask, a largest magnitude, a lowest and highest, a count and a sum; one module's dispatches are counted, so a dispatch that reaches the loader and a leaf is one). Never on the FSR 3.0 host's legacy descriptor, which is vouched Line truncated
| ✅ **FidelityFX ffx-api: `ffxQuery` on the same four modules** (beta.25, owner decision D65) — `amd_fidelityfx_dx12.dll`, `amd_fidelityfx_upscaler_dx12.dll`, `amd_fidelityfx_framegeneration_dx12.dll`, `amd_fidelityfx_loader_dx12.dll` | **Built 2026-10-19.** The mode an FSR title runs at reaches the vendor only as an argument of `ffxQuery` — "what render size (`…GETRENDERRESOLUTIONFROMQUALITYMODE`, `0x00010003`) or ratio (`…GETUPSCALERATIOFROMQUALITYMODE`, `0x00010002`) does this mode give at this display size?" — asked before the title sizes its targets; the per-frame dispatch carries the size alone. The detour calls the original FIRST, exactly once, and only when it returned `FFX_API_RETURN_OK` reads the descriptor's type, display size and mode and the values the vendor wrote through the title's own out pointers, into a five-slot table (one per `FfxApiUpscaleQualityMode`); the `ffxDispatch` UPSCALE arm names the ONE mode whose kept answer fits the dispatched `renderSize` (and `upscaleSize`, where stated) as `0x10 + mode` in `upscalerQuality`, else `0xFF` (`03_METRICS` §Upscaling). **Rule 4:** the arguments of the API we hooked — the descriptor the title passed and the out values of that same call — never `context`, a resource or anything the title did not hand the hooked export; nothing of the title's is written, and every read is under the hook's SEH guard. Both query layouts and type ids are pinned to literals by `static_assert`s, identical at SDK v1.1.4 and v2.3.0. **Its own family**, `FL_HOOK_UPSCALER_QUALITY` (bit 11 of `hooksInstalledMask`, mirrored in `FlHookFamily` and `HookFamilies`): `InstallByFamily` binds a row by equality, and the query entitles no measured field by itself — the byte rides under `FL_MEASURED_UPSCALER_PARAMS` from the dispatch arm — so the bit says only that the query was hooked, which tells "never asked" from "could not have seen it ask". Published like the dispatch family, once every loaded leaf is patched (`PublishFfxQueryFamilyIfWhole`); the FSR 3.0 host has no `ffxQuery` and no row (`static_assert`). A loader that passes a query on to a leaf's export refreshes one kept answer twice; nothing is counted, so nothing is counted twice. **Measured overhead** (a copy of the two bodies, `/O2 /guard:cf /Qspectre /MT`, 20 M calls × 3 runs, every slot holding both a size and a ratio — the worst case): 7.6–8.2 ns added per UPSCALE dispatch, i.e. per application frame, and 1.6 ns per query beside the trampoline; the per-present path gains one load. Harness: `--ffx-query sizes|ratios`; `fl_guard` "FSR's quality mode". **Since 0.1.0-beta.40 (Advanced metrics train B, D111), and only while the Agent asks:** when the query the vendor answered OK is the upscaler's memory — `FFX_API_QUERY_DESC_TYPE_UPSCALE_GPU_MEMORY_USAGE` (`0x00010008`, ffx-api 1.1.2) or `…_V2` (`0x00010009`, 2.0) — the `FfxApiEffectMemoryUsage` it wrote through the title's own out-pointer is kept (total and aliasable bytes), one module's queries counted. Only a title that asks is answered: FrameLedger never calls `ffxQuery` itself. The frame-generation memory queries (`0x00020007`, `0x0002000b`) are not read. +4.3–6.1 ns per such query while asked. Harness: `--ffx-memory-query v1|v2`; `fl_guard` "region 5 stays empty until the Agent asks". |
| ~~XeSS: `xessD3D12CreateContext`, `xessD3D12Init`, `xessD3D12Execute`~~ **Closed at the census by licence, 2026-09-04** (`20_OPEN_QUESTIONS` §Scope decisions, `18_GPU_VENDOR_APIS` §Intel XeSS SDK): no hook on any `libxess*.dll` export *(corrected 2026-10-04)* | ~~`outputResolution`, `qualitySetting`, XeSS version; `xess_fg` variants for XeFG~~ |
| ✅ **FidelityFX ffx-api: `ffxConfigure` on the same four modules** (0.1.0-beta.43, Advanced metrics train B; owner decisions D111–D116, D122) | **How the game configures FSR frame generation** — a title calls `ffxConfigure` with a frame-generation descriptor, usually every frame. Rule 4: an argument of the call hooked, and of it only what is named here. **Read**, and only when the header's type is `FFX_API_CONFIGURE_DESC_TYPE_FRAMEGENERATION` (`0x20002`): `frameGenerationEnabled`, `allowAsyncWorkloads`, `flags`, `onlyPresentGenerated`, `generationRect`. **Never read:** `swapChain`, the two callbacks and their contexts, `HUDLessColor`, `frameID`; and of every other configure type — key-value pairs, the distortion field, the camera info — nothing but the header's type. ctest `fl_adv_fields` publishes two descriptors that differ in all of those and gets the same bytes out, and hands the detour a key-value descriptor, which is shorter, without a read past it. **Installed only where asked for** (D111), as `slSetConstants` is: `InstallByFamily` returns before it resolves anything in a process never asked for Advanced metrics, so with the option off the export's first bytes in the target are the file's (`fl_guard` `[advanced]`). Published when every ffx-api module the process loaded is patched (`FL_HOOK_FFX_CONFIGURE`, bit 14), as the dispatch and query families are. **Counted at the first module that saw a frame-generation configure** — an owner slot of its own: the fixture's loader has always handed `ffxConfigure` on to the leaf's export, and Cyberpunk 2077's loader does the same with dispatches, so one call reaches two hooked modules (the injected case reads one configure a frame through the loader, not two). The rectangle is stored in one word, sixteen bits a side, so a publication never carries half of one rectangle beside half of the next; a side that is negative or past fifteen bits makes it four `-1`. The descriptor's type is kept for the log whatever it is (`FFX_CONFIGURE`, §Native logging). The detour consults `MayObserve()` first. **Measured overhead** (the detour's body on the headers, the Overlay's flags, 20 million calls a run, three runs): not asked **+1.72 / +1.68 / +1.78 ns** (the type kept for the log); asked, the counted module **+15.02 / +15.55 / +15.11 ns**; asked, the forwarded copy +2.70 / +2.81 / +2.65 ns; asked, another configure type +2.43 / +2.55 / +2.47 ns. |
| ✅ **Application frames per present** (`fgEvaluations`) — **`sl.interposer.dll!slGetNewFrameToken` since 2026-09-03** | Native vs Displayed frame counts at Tier 1 — see `03_METRICS` §Frame Generation. **The producer is the frame-token export**: Streamline hands a title one token per application frame and the title must ask; the detour counts distinct tokens between two presents (pointer changes, nothing dereferenced), `FL_HOOK_FG_EVALUATIONS` is its family, and it installs on every Streamline 2 title including the ones that evaluate nothing through `slEvaluateFeature`. Rule 4: the out-parameter of an API we hooked. Premise and its gate in `03_METRICS`; pre-committed table in `20_OPEN_QUESTIONS` §S31. *The row as it stood before:* ~~NGX/SL/FFX/XeSS FG feature evaluations per present. **Built 2026-08-15 for Streamline, and MEASURED TO YIELD NOTHING ON THAT ROUTE**~~ — `slEvaluateFeature(kFeatureDLSS_G)` is never called by Cyberpunk 2077 (0 across ~14,000 batches, four FG settings), so this row installs, is honest, and counts zero; see `docs/HANDOFF.md` item 3. Built on the detour that was already there: `kFeatureDLSS_G` contributes to a saturating COUNT in the same word the feature bits live in (`fl_sl_seen.h`) rather than to a bit, because a bit collapses several evaluations between two presents into one — and under multi-frame generation that is the common case, not the edge. The row's family is therefore compound (`FL_HOOK_UPSCALER_IDENTITY \| FL_HOOK_FG_EVALUATIONS`), pinned by a `static_assert` because `hookinventory-check` reads that column as an opaque identifier. **Counts EVALUATIONS, not generated frames** — the 2026-08-14 owner ruling; the multiplier lives in `sl::DLSSGOptions`, which is only reachable by the route §2b refused. ~~Non-NVIDIA FG vendors are **deferred with a written rationale**: `amd_fidelityfx_framegeneration_dx12.dll` 3.1.5 exports only the five generic `ffx*` entry points, identical to five sibling modules, so identity is in the arguments and we have no headers~~ — **AMD has a producer since 2026-09-04** (the FidelityFX row above: the PREPARE dispatch's `frameID`, or the UPSCALE count on a title that never prepares, feeds `fgEvaluations` when Streamline has never issued a token); Intel stays at the census (`20_OPEN_QUESTIONS` §Scope decisions, by licence); the FSR 3.0 host DLL's UPSCALE (`ffxFsr3ContextDispatchUpscale`, since 2026-09-05) counts like an ffx-api UPSCALE when neither Streamline nor a PREPARE has spoken |
> `GetFrameStatistics().PresentCount` is **not** in this inventory and must not be
@@ -326,7 +328,10 @@ v2.8.0, v2.9.0, v2.10.0, v2.10.3, v2.11.1, v2.12.0, v2.14.1, v2.14.16):
`sl::DLSSOptions` keeps those seventeen declarations, same types and order, through v2.14.16 (`9a875bd4f843`); v2.8.0
only re-spelled the deprecated `sharpness`. `sl::Constants` is unchanged from v2.4.0 through v2.14.16
(`15589e577df9`). Streamline 1.x is refused before any read (`SpeaksStreamline2`).
(`15589e577df9`). Streamline 1.x is refused before any read (`SpeaksStreamline2`). **Since 0.1.0-beta.43 the
Overlay reads `sl::Constants`, and only members of version 1** — nothing of version 2 — so no version test beyond
"at least 1" is needed, and the read ends before `minRelativeLinearDepthObjectSeparation`, the member version 2
added.
**FidelityFX** (`GPUOpen-LibrariesAndSDKs/FidelityFX-SDK`; tags v1.1.0 — FSR 3.1.0, the first ffx-api — v1.1.1,
v1.1.2, v1.1.3, v1.1.4, v2.0.0, v2.1.0, v2.2.0, v2.3.0, v2.4.0). The descriptor header carries a `type` and no size
@@ -788,7 +793,9 @@ No logging in hook bodies. A small fixed-size in-memory ring of structured event
> `FAULT`, `STOP` (the reason), `UNHOOK_RESTORED` / `UNHOOK_DECLINED` (one per patch), `LOADER_DETOUR`,
> `SUPERVISION_LOST`, since beta.24 `STOP_FLUSHED` (the last line after a stop: `a=1` when the stop had finished
> writing), and since beta.42 `PATCH_FAILED` (a patch that did not go in, once per target and reason — §Unhooking)
> and `FFX_DISPATCH`, `FFX_QUERY`, `UPSCALE_ROUTE`, `RUNTIME_CENSUS` (the note at the end of this section).
> and `FFX_DISPATCH`, `FFX_QUERY`, `UPSCALE_ROUTE`, `RUNTIME_CENSUS` (the note at the end of this section), and
> since beta.43 `FFX_CONFIGURE` — each configure type a hooked ffx module was handed, in a process where
> `ffxConfigure` is hooked at all (one asked for Advanced metrics).
> **Three flush points — four since beta.42, the same note —, none on a present path:** the end of `InitThread` (so the
> file exists from the start of the session and a crash mid-session still leaves it), the watchdog when
> `FlControlBlock.logFlushRequested` changes (a counter the Agent bumps at session end; nothing clears it),
+25 -7
View File
@@ -752,7 +752,7 @@ planning, the design reviewed against the code before it was approved.
`ICaptureObserver.WantsInGameAdvanced`; `CaptureSession` writes the word either way as the ring is attached, before
its first guard result, and from then on carries each publication of region 5 on `CaptureProgress.InGameAdvanced`
— one instance a publication, the same one on the ten ticks between two. `Application.Capture.InGameAdvancedSampler`
turns a publication into what a session stores: the session facts of the thirteen `Game` entries below, in the
turns a publication into what a session stores: the session facts of the thirteen `Game` entries below (nineteen since 0.1.0-beta.43), in the
vendor's own words (a preset is its letter, a member its name), and two series —
`adv.ffx.upscale.frame_time_delta`, the mean of one second's dispatches, and `adv.ffx.memory_usage`, a point for
each second the game asked. The facts are one list until a field they are made of moves, so the recorder's context
@@ -764,6 +764,20 @@ planning, the design reviewed against the code before it was approved.
`NotHooked`. The page says it in the session's sources line and, on Sources, that such an entry is read inside a
game FrameLedger measures when the game makes the call. The aliasable part of FSR's memory is published and not
shown: the catalog has one memory entry.
**The second step, 2026-11-12 (0.1.0-beta.43, PR-4).** Six more entries have reach `Game`: `sl.constants.jitter`,
`.motion_vectors`, `.depth`, `.projection`, `.resets` and `ffx.framegen.config`, from the two calls hooked only
for Advanced metrics (`17_HOOK_ENGINE` §Hook inventory, `slSetConstants` and `ffxConfigure`). The sampler makes
them from members region 5 already had (layout 5 as it was; schema 23 as it was): a switch is `on`, `off` or
`on_and_off` from the two words of what was seen, the flags are AMD's own names, the rectangle is the last one
the game gave and is left out where the capture side could not state it, the field of view is a range (D114).
**A count is not part of what makes the facts new** — `sl.constants.resets` grows all session, and a context
rewritten on each would be one a second — so `InGameAdvancedSampler.Conclude` brings it up to the last
publication once, when the session ends. `AdvancedSources.StreamlineConstants` and `.FsrFrameGeneration`
(`AdvancedInGameCall`; null in every row written before, and in a session not measured inside the game) say for
each call which of three things happened: `Read`; `NeverCalled` — the capture side published the hook's family
(`FlHookFamily.SlConstants`, `.FfxConfigure` in the writer state's mask) and no publication carried the group; or
`NotHooked` — the family was never published, which is a game that did not load the library, a Streamline 1.x
interposer, or a patch that was refused. The page says it in one more sentence of the session's sources line.
- **D113 — three releases, because a new patch site cannot be proven in CI.** A crash in a game under the user-mode
anti-cheat exception's trial ends that exception for good (D38), and every release already means restarting the
game. **beta.40**: more fields of calls *already* hooked — `sl::DLSSOptions` where the game chains it into
@@ -799,6 +813,10 @@ planning, the design reviewed against the code before it was approved.
- **What will read N/A, and says why.** Many titles set their DLSS options through `slDLSSSetOptions`, which is not
an export (train D), so `sl.dlss.*` is filled only for a title that passes its options with the evaluate call.
`slGetFeatureVersion` and `slGetFeatureRequirements` are calls a game makes while starting.
- **Privacy Policy 2.17** at beta.43 (approved with that release's plan): 2.16 listed DLSS's and FSR's upscaling
parameters by name, and Streamline's per-frame constants and the frame-generation configuration are in neither
list, so they are named — and §4 says the two calls are intercepted only once a session with the option on has
started in the game.
- **Privacy Policy 2.16** at beta.40, once for the three releases: with Advanced metrics on, for a game FrameLedger
injects into, the parameters the game gives its upscaler and frame generation through the intercepted calls are
*stored* — sizes, presets, exposure, sharpening, the jitter's, the depth's and the field of view's ranges, flags,
@@ -984,15 +1002,15 @@ that is not built — Train B), `Spike` (Trains C and D), `Refused`, `Deferred`,
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `sl.constants.jitter` | The jitter offsets the game gave Streamline | SessionFact | Streamline | NewHook | Text |
| `sl.constants.motion_vectors` | Motion-vector scale, and whether they are 3D, dilated, jittered | SessionFact | Streamline | NewHook | Text |
| `sl.constants.depth` | Near and far planes, and whether depth is inverted | SessionFact | Streamline | NewHook | Text |
| `sl.constants.projection` | Field of view, aspect ratio, orthographic or not | SessionFact | Streamline | NewHook | Text |
| `sl.constants.resets` | How often the game reset the upscaler's history | SessionFact | Streamline | NewHook | Count |
| `sl.constants.jitter` | The jitter offsets the game gave Streamline | SessionFact | Streamline | Game | Table |
| `sl.constants.motion_vectors` | Motion-vector scale, and whether they are 3D, dilated, jittered | SessionFact | Streamline | Game | Table |
| `sl.constants.depth` | Near and far planes, and whether depth is inverted | SessionFact | Streamline | Game | Table |
| `sl.constants.projection` | Field of view, aspect ratio, orthographic or not | SessionFact | Streamline | Game | Table |
| `sl.constants.resets` | How often the game reset the upscaler's history | SessionFact | Streamline | Game | Count |
| `ffx.framegen.config` | The game's FSR frame-generation configuration | SessionFact | FidelityFx | Game | Table |
| `sl.feature.versions` | Each Streamline feature's version and its NGX model version | SessionFact | Streamline | NewHook | Table |
| `sl.feature.requirements` | What each Streamline feature requires: operating system, driver, buffers | SessionFact | Streamline | NewHook | Table |
| `sl.init.preferences` | The preferences the game started Streamline with | SessionFact | Streamline | NewHook | Text |
| `ffx.framegen.config` | The game's FSR frame-generation configuration | SessionFact | FidelityFx | NewHook | Text |
| `sl.constants.camera` | Camera position, axes and matrices | SessionFact | Streamline | PlayerState | Text |
**Inside the game: routes a spike decides**
+21 -1
View File
@@ -60,10 +60,30 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
> at once), waits `kScanRetryPauseMs` (250 ms), takes a **fresh** scan set and scans it whole. A member still unreadable
> then refuses `kProcessUnreadable`, as before; one that has gone is not in the new set; a target that has gone leaves
> no set, which refuses `kProcessTreeUnavailable`. **`ERROR_ACCESS_DENIED` — a protected process — is never retried**,
> and no other answer of any source is. The sentence above stands: every failure still means REFUSE; what changed is
> and no other answer of any source is *(one more since D123, below)*. The sentence above stands: every failure still means REFUSE; what changed is
> how many times "still loading" is asked before it counts as one. ctest `fl_guard` `[D48]` holds both directions,
> against fakes and against the real source (a process created suspended, a pid with no process).
>
> **Amended 2026-11-12 (owner decision D123): a module list that changed while it was read is read again, at most
> three times — never a pass.** The module check lists a process's modules and then asks each one's name. A game at
> its launch loads and unloads modules for seconds, and a module that was in the list and could not be named a
> moment later made the whole answer "incomplete": a refusal before injection, or — 0.5 s after it, at the first
> supervision scan — a safety unhook with no frame recorded, the game then running on unrecorded. **Five such ends
> in one PC's Agent logs in a week** (Phantom Blade Zero three times on 2026-11-05, Crown & Coin on 11-10,
> Cyberpunk 2077 on 11-12), and twice in this repository's own gate. Asked with that, the owner chose: read it
> again. Such a list is now `Collected::kUnsettled`; the pass finishes — **a blocklisted module among those that
> were read still refuses at once** — waits `kScanRetryPauseMs`, takes a fresh scan set and reads it whole, up to
> `kMaxUnsettledRereads` (3) times: four reads and 750 ms of pauses at most. A list still unsettled on the last
> read refuses `kModuleScanFailed` ("a module list kept changing while it was read"). **What did not change:** a
> list too long for the guard's buffer is still `kIncomplete` and refuses at once (a second read would be as
> long); a protected process still refuses at once; D48's re-read is still one for the whole check; every read is
> of the whole scan set, and the read that allows is one in which every member was read whole and none held a
> finding. A failure to read is still never a pass — what changed is how many times a list that is moving is
> asked before it counts as unreadable. The launch poll's presentation-runtime probe treats an unsettled list as
> "ask again" rather than deciding on half of one. ctest `fl_guard` `[D123]`: against fakes, every direction
> above; against the real source, a process that loads and frees a module in a loop — read some 3,600 times in
> three seconds, about one read in four is unsettled and none is anything else.
>
> **Launch mode (2026-09-06, P1 item 2) does not weaken this.** `FlGuardedInjectWhenReady` polls
> the same enumeration to learn *when* the launched target has mapped a presentation runtime, and a
> failing enumeration there means "not yet" — the poll continues. That is not a pass: the poll
+107 -66
View File
@@ -81,6 +81,7 @@ owner-only items stay below; the history of every train, the passed owner-only i
| `§beta.39`, train B's plan as approved (its `§NEXT`) | [`handoff/history/0.1.0-beta.39.md`](handoff/history/0.1.0-beta.39.md) |
| `§beta.40`, what the owner's first sessions with it showed, train B's traps | [`handoff/history/0.1.0-beta.40.md`](handoff/history/0.1.0-beta.40.md) |
| `§beta.41`, what the owner's sessions on beta.40 and beta.41 showed, the plan of 2026-11-12 (D119–D122) | [`handoff/history/0.1.0-beta.41.md`](handoff/history/0.1.0-beta.41.md) |
| `§beta.42`, what the owner's seven sessions on beta.42 showed (D121 answered, the guard's lost launches), beta.43's design as planned | [`handoff/history/0.1.0-beta.42.md`](handoff/history/0.1.0-beta.42.md) |
| `§Owner-only`, an open item | [§Owner-only](#owner-only--no-pr-can-close-these) below |
| `§Owner-only`, a passed item (3, 12, 14–19, 38, 39) | [`handoff/owner-only-passed.md`](handoff/owner-only-passed.md) |
| `§Traps`, `§Two corrections carried forward` | [`handoff/traps.md`](handoff/traps.md) |
@@ -88,84 +89,88 @@ owner-only items stay below; the history of every train, the passed owner-only i
---
## **START HERE** — 2026-11-12, 0.1.0-beta.42: no new patch site — the label, the registry, a log that outlives the game, the plane at infinity
## **START HERE** — 2026-11-12, 0.1.0-beta.43: two hooks installed only where asked for, the guard reads a moving list again, an UPSCALE counted once
*Status is `docs/changelog/0.1.0-beta.42.md`; this is what no other file carries.* The owner marked items 38 and 39
passed on 2026-11-12 and train B's second step was planned the same morning. A review of the draft against the code
changed it, and the owner split it (D122): **this release adds no patch site**, and the two new hooks are
0.1.0-beta.43. Four pull requests and this one: #406 (the session's upscaler label, D120; the decisions D119–D122),
#407 (the patch registry), #408 (the native log and the descriptor-type census, D121), #409 (FSR's plane at
infinity, D119; Qodana's native report). **What the owner's sessions on beta.40 and beta.41 showed, and the plan as
approved, are [`handoff/history/0.1.0-beta.41.md`](handoff/history/0.1.0-beta.41.md)**; what each pull request built
is [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Unhooking and §Native logging, [`03_METRICS.md`](03_METRICS.md)
§Upscaling and [`07_IPC.md`](07_IPC.md) §Region 5.
*Status is `docs/changelog/0.1.0-beta.43.md`; this is what no other file carries.* The owner ran beta.42 the morning
it was released; seven sessions, a copy of the ledger and the logs answered D121 (Cyberpunk 2077's FSR is 2.1, built
into the game), showed the guard losing launches to a module list that moved while it was read, and showed the
FidelityFX 2.3 loader handing a call on to the leaf's export. The owner decided D123–D125 and approved the plan the
same morning, Privacy Policy 2.17's wording with it. Five pull requests and this one: #413 (the guard reads again,
D123), #414 (an UPSCALE is counted at the first source that saw one, D125; D124), #415 (`slSetConstants`), #416
(`ffxConfigure` on the four ffx-api modules), #417 (the Agent, the App, Privacy Policy 2.17). **What the owner's
sessions on beta.42 showed, and the design as planned, are
[`handoff/history/0.1.0-beta.42.md`](handoff/history/0.1.0-beta.42.md)**; what each pull request built is
[`19_SAFETY_AND_ANTICHEAT.md`](19_SAFETY_AND_ANTICHEAT.md) §Pre-injection checks,
[`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Hook inventory (the two rows, with their measured cost) and
[`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Train B.
### What this release decided, beyond D119–D122
### What this release decided, beyond D123–D125
- **The descriptor-type census is not behind the Advanced-metrics switch.** It is a diagnostic that reaches the log
file and nothing else — no record, no shared memory, no session — like `HOOK_INSTALLED`. Behind the switch it
could not answer D121 for a session recorded with the switch off, which is most of them. Its cost was measured
and stated instead (+3.8 ns a dispatch).
- **The log's text grew to 72 characters; nothing else about the ring did.** 256 events, static, 24 KiB.
- **A slot of the patch registry that was ever live is never reused**, and a failed create or enable leaves the
hook created in MinHook as it always did. Both are the smaller change: the first keeps the stop's walk lock-free
without a second word per slot, the second changes no failure path that has never been seen to run.
- **The live card still names the first upscaler a session saw** (`FgLadder.UpscalerIdentity`). The stored
session's name is the modal one (D120); for a session in progress the question is a different one.
- **Qodana's "never used" on the registry test's stand-in engines is switched off for that file**, not answered by
turning the template into function pointers: the header is loaded into a game, and D100 changes such code only
for a defect.
- **A hook that exists only for Advanced metrics is not put into a game that was never asked.** The two rows are
gated at the top of `InstallByFamily`, before the symbol is resolved (resolving holds the module). Once a
session with the option on has started in a process, the patch goes in on that watchdog tick and **stays for the
life of the process**: a later session with the option off finds the detour there, forwarding without looking.
Removing a patch between sessions would be a second patch event in a running game for nothing gained. So "off
means off" (D111) is, for these two: nothing read, nothing published — and, in a game no session ever asked,
nothing patched. Privacy Policy 2.17 §4 says it that way.
- **Privacy Policy 2.17, not 2.16 stretched.** beta.40's plan had 2.16 stand "once for the three releases"; its
text then listed DLSS's and FSR's parameters by name, and neither list holds Streamline's constants or the
frame-generation configuration. The plan of beta.43 carried the new sentences and the owner approved them with it.
**beta.44 reads feature versions and requirements — check 2.17's lists the same way before assuming it covers
them.**
- **For each of the two calls a session says which of three things happened** (`AdvancedInGameCall`): read; hooked
and the game never called; not hooked. "Not hooked" is three causes the session does not tell apart — the game
did not load the library, a Streamline 1.x interposer (refused), a patch the registry refused — and the Overlay's
log does: a `HOOK_INSTALLED` line naming the function, or a `PATCH_FAILED`.
- **A count is not part of what makes a session's facts new.** `sl.constants.resets` grows all session; the
recorder's context would be rewritten each second. `InGameAdvancedSampler.Conclude` brings it up to date once, at
the end. A session recovered after a crash holds the count as of the last time some other field moved — a lower
bound.
- **Streamline's summaries are the first viewport's**, and the configure count has an owner slot of its own (the
2.3 loader would otherwise bring one configure to two modules, as D125's dispatch).
- **The accuracy statement no longer says nothing of what a game tells its upscaler was read from a real game.**
FSR's upscaling values were (beta.41, beta.42: Lies of P, Dying Light: The Beast, Kingdom Come: Deliverance II).
The DLSS options, Streamline's constants and the frame-generation configuration are still unconfirmed, and the
three copies say so.
### Traps this train left
- **An unpatched export may already begin with a jump.** The loader stub's `ffxConfigure` starts with `E9` in the
file: "the first byte is not a jump" is not a test of "not patched". `ReadTargetExportBytes` compares the target's
bytes with the file's own (`inFile`).
- **A branch stacked on a pull request that is then squashed**: `git rebase --onto origin/main <the old tip>`, and
`git diff <old tip> <squash>` empty says the gate that ran still stands.
- **`mcp__ccd_pr__set_auto_merge` says "not bound" for a pull request opened from a script**: `gh pr merge <n>
--auto --squash`. A run's artifacts while it is still in progress: `gh api
repos/…/actions/artifacts/<id>/zip`.
- **clang-format re-wraps what an edit script wrote**, so a second script's anchors must be read from the formatted
file; a multi-file script that fails part-way has already written the earlier files.
- **One local gate printed 871 App tests where every other printed 872**, green. Not looked into.
### NEXT
1. **The owner runs item 40** — above all **one session of Cyberpunk 2077 with FSR upscaling** on beta.42, then
quits the game the ordinary way. Its `logs\overlay-<pid>-….log` is what beta.43 waits for.
2. **Read that log, then plan 0.1.0-beta.43** — `slSetConstants` and `ffxConfigure`, and the fix for D121 if the
log shows the route. What to look for: which `HOOK_INSTALLED` lines there are (which of the four ffx modules and
the FSR 3.0 host were patched); the `FFX_DISPATCH` lines — is `b=0x10001` (UPSCALE) on any module, or only
`0x20004` / `0x2000c` / `0x20003`; an `UPSCALE_ROUTE` line; `PATCH_FAILED`; the last `RUNTIME_CENSUS` word.
**No UPSCALE type anywhere and no route line means the upscale does not come through any export the Overlay
patches** — statically linked, or a module the inventory does not name — and then the fix is not a new arm in
a detour. The design for the two hooks, as the review left it, is the plan of 2026-11-12 (moved with the
section above) and these points: the new rows are gated at the top of `InstallByFamily`, **before**
`ResolveScoped`, and installed only once the process was ever asked; hook families 13 and 14 with latches of
their own; `slSetConstants` checks the struct's GUID and `structVersion ≥ 1` on every call and reads only
`jitterOffset`, `mvecScale`, `cameraNear` … `cameraAspectRatio` and the seven Booleans — never bytes 368..423,
pinned by `offsetof` of the allowed members; summaries from the first viewport seen; `ffxConfigure` has an
owner slot of its own and reads `frameGenerationEnabled`, `allowAsyncWorkloads`, `flags`,
`onlyPresentGenerated`, `generationRect` and nothing else; the detours also consult `MayObserve()`;
`overlay-fields-check` gains three parameter names, `structType` among the shared members and an `offsetof` per
listed `sl::Constants` member. The registry holds 48 and the worst case becomes 25
(`kPatchSitesOutsideTheInventory` stays 7; the inventory's row count goes from 13 to 18 and its
`static_assert` says so).
3. **0.1.0-beta.44** — `slGetFeatureVersion` and `slGetFeatureRequirements` — when the owner says beta.43 passed.
4. **Trains C and D** (beta.45, beta.46) each begin with a spike and end in the owner's go or no.
1. **The owner runs item 41** — the first time either new hook is in a real game. Not first on a game under the
user-mode exception's trial (D38: a crash there ends the exception for good).
2. **0.1.0-beta.44** — `slGetFeatureVersion` and `slGetFeatureRequirements` — when the owner says beta.43 passed.
Both are calls a game makes while starting, so most sessions will have missed them: plan what "not seen" says.
3. **Trains C and D** (beta.45, beta.46) each begin with a spike and end in the owner's go or no.
### Left open by this session
- **This release's own facts** — the tag's run, the digests, the delta — are not in any file yet: the release is cut
after this text. Record them in the next pull request.
- **No real game was run on this build.** The four changes were tested with the harness and the cost measured on
the headers. Item 40 is the first real session.
- **Whether the missing plane of Lies of P, Clair Obscur and Dying Light is `FLT_MAX`** is still the reading their
small `cameraFar` values point to, not a measurement. Item 40 (c).
- **A flake with a cause now, and a question in it for the owner.**
`ShmDrainIntegrationTests.TheGuardInjectsTheOverlayAndTheReaderDrainsRealFrames` was red once in this release's
local gate (and once on 2026-11-11, when the assertion did not yet print the verdict): the supervisor's first
re-scan, 0.8 s after the injection, came back `ModuleScanFailed` — *a module list came back incomplete* — while
the harness was still loading modules. The same gate was green on the same code before and after. In the test
it is a re-run. **In a real session the same answer is a safety unhook**: a re-scan that cannot read the module
list of a game that is still running stops the session (`19_SAFETY` §During a session; D48 covers only a game
that has exited). Whether the guard should read the list a second time before refusing is a change to rule 2's
checks and is the owner's to decide; nothing was changed.
- **SonarCloud has not answered for #406–#409**: `main`'s `sonarcloud` job was cancelled by the next merge each
time. It runs to its end on this release's commit; read it then.
after this text. Record them in the next pull request, with what SonarCloud and Qodana said of #413–#417 (the
`sonarcloud` job on `main` is cancelled by the next merge, so it answers on the release's commit).
- **No real game was run on this build.** Two new patch sites, tested with the harness and the stubs; their cost
measured on the headers. Whether a real `sl.interposer.dll` 2.x lays `sl::Constants` out as the vendored header
does is checked on every call by the struct's GUID and version, not by a real game yet.
- **Item 40 (d)** — a session that changes upscaler — was not exercised, and the owner has not said item 40 passed.
**Items 36 (d) and 37 are still open.**
- **What an empty process snapshot does to the watcher's tick in a real session** was not looked into
(`ToolhelpProcessSnapshotSource.Take` returns an empty list and says nothing; seen once in a test on 2026-11-12).
- **`LIMITATIONS.md` and the accuracy statement still say the processor's, the memory's and the motherboard's
sensors "have never been read on real hardware"** — the owner's to reword. **SonarCloud's `csharpsquid:S3869` on
`ParentDump.cs`** is the owner's to accept. **Items 36 (d) and 37 are still open.** The alpha line still rests
(D98).
sensors "have never been read on real hardware"** — the owner's to reword. The alpha line still rests (D98).
**Owner-only:** item 40.
**Owner-only:** item 41; item 40 (d).
## Owner-only — no PR can close these
@@ -482,6 +487,39 @@ is [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Unhooking and §Native logging, [`
and says *settings changed during session*. (e) **Any hooked game, ended by quitting it**: its overlay log has
lines after the first second — `HOOK_INSTALLED` with a module and a function, `RUNTIME_CENSUS` — and no
`PATCH_FAILED`; if there is one, its `a=` number is the reason.
**Four sessions were run on 2026-11-12 and read the same morning** (START HERE §What the owner's first four
sessions on beta.42 showed): (a) happened — the sessions carry the beta.42 build; (b) read, and D121 answered:
the session upscaled with FSR 2.1, built into the game; (c) Lies of P and Dying Light show `cameraNear = ∞`;
(e) all four logs are whole and none has a `PATCH_FAILED`. **(d) was not exercised**, and the owner has not
said the item passed.
41. **beta.43 — the first real games with the two new hooks, and the guard's re-read** (D123–D125). **Not first on
a game under the user-mode exception's trial** (D38): a crash there ends the exception for good. (a) **The
update from beta.42**: Help ▸ Check for updates, *Restart to update* with no game running; **the terms window
shows once, with Privacy Policy 2.17**. (b) **The guard**: over the games played, the Agent's log
(`logs\agent-<date>.log`) has no session that ended at a game's launch with `guard=ModuleScanFailed`. If one
does, its signal now says which kind — *kept changing while it was read* (four reads were not enough) or *came
back incomplete* — say which. (c) **A Streamline game with Advanced metrics on** (Dying Light: The Beast, or
Cyberpunk 2077 with DLSS): a session of a few minutes, quit from the game's menu. Its Advanced page shows the
Streamline rows — jitter, motion vectors, depth, projection, resets — and the line under the session says
*read*. **Read them for sense**: a field of view between about 0.3 and 2.5 rad, an aspect ratio near the
screen's, a jitter under 1, planes that are not both zero. Values that make no sense mean the game's struct is
not laid out as the one FrameLedger was built against: say so, with the numbers, and do not run further games.
(d) **FSR frame generation on** (Cyberpunk 2077 or Lies of P), Advanced metrics on: the page shows the
frame-generation rows — on, asynchronous or not, the flags, the rectangle — and the line says *read*. (e) **The
three answers of the line**: a game with neither library says *not hooked* for both; a game where it says
*hooked — the game did not make the call* for a library the game plainly uses is a finding, not a pass — say
which game. (f) **Off means off**: with Advanced metrics off, **start a game afresh** and record a session; it
has no Advanced button, and its `logs\overlay-<pid>-….log` has no `HOOK_INSTALLED` line naming `slSetConstants`
or `ffxConfigure`. (A game that was already running when a session with the option on was recorded keeps the
two patches until it exits — that is by design, and its log will have the lines.) (g) **Nothing else moved**:
no crash, no `PATCH_FAILED` in any overlay log, frame rates and the frame-generation factor as on beta.42 for
the same game and settings.
**What each outcome means, written before the run.** (c) or (d) empty with *not hooked*: the log of that
session says why — no `HOOK_INSTALLED` for the function (the library is a 1.x interposer or lacks the export)
or a `PATCH_FAILED` (its `a=` number is the reason). Empty with *hooked — the game did not make the call*: the
game reaches Streamline or FSR by a way that does not pass the export — beta.44's plan needs to know. A crash,
or a game that will not start: say so at once; *Disable all hooking* (Settings ▸ Capture) and switching Advanced
metrics off are the two ways to run without the hooks, and which of them cured it says which hook it was.
**Answered 2026-08-05, do not re-ask:** remove `gameguard` and keep `guard` (approved
over a red `Rules` gate, with the reasoning recorded in the merge commit); vendor NVAPI
@@ -618,6 +656,9 @@ Where each owner decision is recorded — the file and its section, and a label
| D120 | [`03_METRICS.md`](03_METRICS.md) §Upscaling | a session's upscaler is the technology named on the most samples, and its quality and render size are read from that technology's samples — not the first one named, with the others' values beside it |
| D121 | [`HANDOFF.md`](HANDOFF.md) §NEXT | Cyberpunk 2077 was set to FSR upscaling and FrameLedger named none: a detection gap, to be investigated — which first needs a native log that survives the game's exit |
| D122 | [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Train B | train B's second step is split: **beta.42** has no new patch site (D119–D121 and the patch registry's hardening); **beta.43** is the two new hooks, begun only after the owner has run Cyberpunk on beta.42 and its log was read. The third release is beta.44, train C beta.45, train D beta.46 |
| D123 | [`19_SAFETY_AND_ANTICHEAT.md`](19_SAFETY_AND_ANTICHEAT.md) §Pre-injection checks, check 1 | a module list that changed while the guard read it is read again, at most three times, before it refuses — five real sessions on one PC in a week had ended as a safety unhook with no frame recorded; a list that never settles still refuses, and nothing else about what refuses changed |
| D124 | [`HANDOFF.md`](HANDOFF.md) §NEXT | the guard's re-read (D123) ships with 0.1.0-beta.43 and not as a release of its own — the train's numbers do not move a third time; until then a launch can still be lost that way on beta.42 |
| D125 | [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Hook inventory | an FSR UPSCALE is counted at the first source that saw one and at no other — a precaution for a loader that hands a dispatch on to the leaf's export (Cyberpunk 2077's 2.3.0 does, for frame generation); no title run so far upscales through one |
| D109 | [`../legal/DISCLAIMER.md`](../legal/DISCLAIMER.md) §5, §5A | asked on 2026-11-11 with both sentences quoted: the Disclaimer goes to 2.15 with the Privacy Policy — PawnIO and the admin mode are no longer "for the CPU temperature" alone; with Advanced metrics on they also read the processor's, the memory's and the motherboard's sensors. The admin mode's disclosure follows (`agent-admin-dialog/2`) |
---
+86
View File
@@ -0,0 +1,86 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.43 was cut, 2026-11-12 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.43] - 2026-11-12
**The forty-third pre-release: a game that was still loading is no longer lost, and two more readings inside the
game.** Two fixes first. A game that FrameLedger looked at while it was still loading its modules could be left
unrecorded — the session ended as a safety stop with nothing in it; FrameLedger now reads the list again before it
gives up, and what stops a session has not changed. And an FSR upscale is counted once per frame whichever way the
game's FidelityFX loader passes it on. Then, with **Advanced metrics** on, a session of a game measured from inside
also keeps what the game tells NVIDIA Streamline about each frame and how it configures FSR frame generation —
from two calls FrameLedger hooks only once Advanced metrics has been asked for in that game. The same unsigned
installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
**What it is not, yet.** The two new readings have been tested with FrameLedger's own test program and **have not
been run in a real game**: this release is the first time either hook is put into one. They are what the game
asked for, not a check of what happened, and Streamline's values are those of the first view a game draws.
Streamline 1.x is not read. Where the game's camera is, which way it looks and its matrices are never read — they
sit in the same data, and a check in the build refuses code that names them. The cost was measured on the code
itself: about 20 billionths of a second per frame for Streamline's call and 15 per call for FSR's while the option
is on, under 2 while it is off; nothing measurable for the two fixes. A game whose FSR is built in (Cyberpunk 2077's
FSR 2.1) still reads "unknown" as its upscaler. Everything 0.1.0-beta.42's notes say is not yet done still stands.
**Updating from `0.1.0-beta.42`:** Help ▸ Check for updates, then *Restart to update* with no game running. **The
terms are shown once: Privacy Policy 2.17**, which names the two new readings. No change to the ledger (schema 23),
the detection rules stay at `2026.11.2`. **The code loaded into a game changed in this release**, so a game that
was running during the update keeps the old part until it is started again.
### Added
- **Advanced metrics: a session now shows what the game told Streamline each frame and how it configured FSR frame
generation.** For a game FrameLedger measures from inside, a session recorded with **Advanced metrics** on keeps
— beside what the game told DLSS and FSR — the largest jitter offset, the motion-vector scale and how motion
vectors are stored, the near and far planes and whether depth is inverted, the range of the field of view, the
aspect ratio, whether the projection is orthographic and how often the game reset the upscaler's history
(Streamline); and whether FSR frame generation was configured on, whether it may run asynchronously, its flags,
whether only generated frames are presented, and the part of the picture it generates in. A setting the game
changed during the session reads *on and off*. The line under the session now also says, for each of the two,
whether it was read, hooked and never called by the game, or not hooked because the game did not load the
library — so an empty page says which it is. These are what the game asked for, not a check of what happened;
neither has been confirmed on a real game yet. Never read: where the camera is, which way it looks, its
matrices.
- **The terms are shown once after this update: Privacy Policy 2.17.** It names the two new readings above and says
that the two calls they come from are intercepted in a game only once a session with Advanced metrics on has
started there. Nothing is sent anywhere, as before.
- **Advanced metrics, inside the game: how the game configures FSR frame generation** (the part inside the game;
what a session shows of it comes with the same release). With **Advanced metrics** on, FrameLedger now also
reads, from the call a game makes to configure AMD's frame generation, whether generation is on, whether it may
run asynchronously, its flags, whether only generated frames are presented, and the part of the picture it
generates in. Nothing else of that call is read. Like the Streamline hook, this one is put into a game only once
Advanced metrics has been asked for. Measured cost: about 15 billionths of a second per call while the option is
on, under 2 while it is off.
- **Advanced metrics, inside the game: what the game tells NVIDIA Streamline about each frame** (the part inside the
game; what a session shows of it comes with the same release). With **Advanced metrics** on, FrameLedger now also
reads, from a call a Streamline game makes every frame, the size of the jitter, the motion-vector scale, the depth
range, the range of the field of view, the aspect ratio and seven on/off settings (inverted depth, how motion
vectors are stored, whether the upscaler's history was reset). It never reads where the game's camera is, which
way it looks, or its matrices, which sit in the same data — a check in the build refuses any code that names
them. This is the first reading that needs a hook of its own, and that hook is put into a game only once
Advanced metrics has been asked for: with the option off, nothing in the game is touched for it. Measured cost:
about 20 billionths of a second per frame while the option is on, under one billionth while it is off.
### Fixed
- **FSR upscaling is counted once per frame whichever way the game's FidelityFX loader passes it on.** Newer
FidelityFX loaders hand a call on to the library behind them in a way that brought the same upscale to
FrameLedger twice; with frame generation off, the count of frames the game rendered would have doubled — Native
FPS twice too high. Seen in how Cyberpunk 2077's loader passes on its frame-generation calls; no game tested so
far upscales through such a loader, so this is a precaution. The upscale is now counted where the game calls it,
and nowhere else. (Owner decision D125. Measured cost: none that can be told from noise.)
- **A game is no longer left unrecorded because it was still loading when FrameLedger looked at it.** Before it
hooks a game, and again right after, FrameLedger lists the modules the game has loaded and checks them against
the anti-cheat list. A game that is starting loads and unloads modules for several seconds, and when the list
changed in the middle of being read FrameLedger treated it as unreadable and stopped: the session ended as a
safety stop with nothing recorded, and the game ran on unmeasured until it was restarted. It now reads the list
again — up to three more times, a quarter of a second apart — and only stops if the list never holds still. What
stops a session has not changed: an anti-cheat module found in any read stops it at once, a protected process
still stops it at once, and a list that cannot be read in the end is still a stop, never a pass. (Owner decision
D123; seen five times in one PC's logs in a week.)
- **A test of the Overlay's log reads its lines without `strlen`.** The helper that looks for a line in the log
took its text as C strings and measured one with `strlen`; it takes strings now. Test code only: nothing in the
installed software changes. (Found by SonarCloud after 0.1.0-beta.42 was merged.)
+204
View File
@@ -0,0 +1,204 @@
# HANDOFF history — 0.1.0-beta.42
*Moved verbatim from `docs/HANDOFF.md` when 0.1.0-beta.43 was cut, 2026-11-12 (owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" mean HANDOFF.md as it stood then, and a path it writes is relative to `docs/`. **Its §NEXT item 2 says 0.1.0-beta.43 is "under way"**: it was released the same day, and what it built and decided is HANDOFF.md's section for it.*
## **START HERE** — 2026-11-12, 0.1.0-beta.42: no new patch site — the label, the registry, a log that outlives the game, the plane at infinity
*Status is `docs/changelog/0.1.0-beta.42.md`; this is what no other file carries.* The owner marked items 38 and 39
passed on 2026-11-12 and train B's second step was planned the same morning. A review of the draft against the code
changed it, and the owner split it (D122): **this release adds no patch site**, and the two new hooks are
0.1.0-beta.43. Four pull requests and this one: #406 (the session's upscaler label, D120; the decisions D119–D122),
#407 (the patch registry), #408 (the native log and the descriptor-type census, D121), #409 (FSR's plane at
infinity, D119; Qodana's native report). **What the owner's sessions on beta.40 and beta.41 showed, and the plan as
approved, are [`handoff/history/0.1.0-beta.41.md`](handoff/history/0.1.0-beta.41.md)**; what each pull request built
is [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Unhooking and §Native logging, [`03_METRICS.md`](03_METRICS.md)
§Upscaling and [`07_IPC.md`](07_IPC.md) §Region 5.
### What this release decided, beyond D119–D122
- **The descriptor-type census is not behind the Advanced-metrics switch.** It is a diagnostic that reaches the log
file and nothing else — no record, no shared memory, no session — like `HOOK_INSTALLED`. Behind the switch it
could not answer D121 for a session recorded with the switch off, which is most of them. Its cost was measured
and stated instead (+3.8 ns a dispatch).
- **The log's text grew to 72 characters; nothing else about the ring did.** 256 events, static, 24 KiB.
- **A slot of the patch registry that was ever live is never reused**, and a failed create or enable leaves the
hook created in MinHook as it always did. Both are the smaller change: the first keeps the stop's walk lock-free
without a second word per slot, the second changes no failure path that has never been seen to run.
- **The live card still names the first upscaler a session saw** (`FgLadder.UpscalerIdentity`). The stored
session's name is the modal one (D120); for a session in progress the question is a different one.
- **Qodana's "never used" on the registry test's stand-in engines is switched off for that file**, not answered by
turning the template into function pointers: the header is loaded into a game, and D100 changes such code only
for a defect.
### What the owner's first four sessions on beta.42 showed (2026-11-12, 09:40–09:53)
Dying Light: The Beast, Kingdom Come: Deliverance II, Cyberpunk 2077 and Lies of P, each quit from its own menu;
read from the four `overlay-<pid>-….log` files, a copy of the ledger, and — for Cyberpunk — the game's own settings
file and executable on disk. All four hooked, no fault, no `PATCH_FAILED`, the Agent's log without an `advanced:`
line.
- **D121 is answered, and it is not a detection gap: in that session Cyberpunk 2077 upscaled with FSR 2.1, which is
compiled into the game.** Its `UserSettings.json`, written when the session ended, has `ResolutionScaling = FSR2`,
`FSR2 = Quality`, `FrameGeneration = FSR3`, `FSR3_FrameGeneration = true` — FSR **2** for the upscale, FSR **3**
for frame generation only. Quality is a ratio of 1.5, and the session's render size is 1707×960 at 2560×1440.
`Cyberpunk2077.exe` carries FSR 2's own function names (`ffxFsr2GetJitterPhaseCount`,
`ffxFsr2GetUpscaleRatioFromQualityMode`) and names one FidelityFX module, the loader; its folder has no FSR 2
DLL. **The log says the same from the other side**: the loader (2.3.0), the upscaler leaf (4.1.1) and the
frame-generation leaf (4.0.1) were all patched; the loader and the frame-generation leaf were handed `0x20004`
(PREPARE) and `0x20003` (FRAMEGENERATION); the loader and the upscaler leaf were asked `0x10002` (the ratio of a
quality mode) once at start; **no module was ever handed `0x10001`**, and there is no `UPSCALE_ROUTE` line. The
NVIDIA driver's words for the session say DLSS was not running. So the upscale goes through no export at all —
the case `LIMITATIONS.md` already names ("FSR 2 and upscalers built into the game are not identified"), and
"unknown" beside a measured render size is the true reading. ~~**The owner had said FSR 3 or 4; that the setting is
FSR 2.1 is read from the file, and is the owner's to confirm.**~~ **Confirmed by the owner the same morning with
a screenshot of the game's Graphics menu: Resolution Scaling reads "AMD FidelityFX Super Resolution 2.1"** (the
file's `FSR2`), with its own quality and sharpening rows under it. Nothing to fix for it in beta.43.
- **The loader of SDK 2.3 passes a dispatch on to the leaf's export — the older loader does not — and that is a
double count waiting for the first title that upscales through it.** In Cyberpunk each frame-generation dispatch
type is logged on the loader AND on the frame-generation leaf: the game calls the loader, the loader calls the
leaf's exported `ffxDispatch`. In Kingdom Come and Dying Light (loader 1.0.2) the UPSCALE is logged on the loader
alone, which is what `fl_hook_inventory.h` measured in September and what the fixture's loader stub copies.
Frame generation is unharmed — PREPARE is counted by its frame number, FRAMEGENERATION is a bit, and the
session's factor is ×2.0001. **An UPSCALE is counted once per hooked module that sees it**
(`g_ffxSeen`'s count): through a 2.3 loader that would be two a frame, and with frame generation off — no
PREPARE, so the count falls back to UPSCALE dispatches — the application-frame count would double. Not
observed: no UPSCALE was dispatched. **One session answers it: Cyberpunk with Resolution Scaling set to FSR 3
and frame generation off** — the log shows whether `0x10001` is on both modules, and the session's frame
counts show whether it was counted twice. If so, the fix is beta.43's: count at the first module seen, as
`fl::adv::Owns` already does for the Advanced reads.
- **The plane at infinity is measured, not a hypothesis any more (D119).** Lies of P: `cameraNear = ∞`,
`cameraFar = 10`. Dying Light: `cameraNear = ∞`, `cameraFar = 0.1`. Both gave one plane on beta.41. Kingdom
Come still gives both as numbers (0.05 and 8000). Clair Obscur was not run.
- **The logs are whole.** Each has its installs by module and symbol, the census as it grew, and lines long after
the first second — Dying Light's first UPSCALE at 71.6 s, Kingdom Come's at 37.5 s, when play began. One line
looks odd and was not looked into: Cyberpunk's frame-generation leaf's `ffxDispatch` is at `0x241cde7ba10`, far
from where the other modules sit (`0x7ff…`); the patch went in and was called.
- **Dying Light was named FSR, Quality, with DLSS frame generation ×3.99** — its settings as the owner gave them.
No session changed upscaler part-way, so D120's case was not exercised.
### And three more starts of Cyberpunk 2077, 10:05–10:15 the same morning
Asked for as "Resolution Scaling = FSR 3, frame generation off". Read the same way.
- **The game was still on FSR 2.** After the last of them `UserSettings.json` has `ResolutionScaling = FSR2`,
`FSR2 = Performance` (it was `Quality` at 09:50), `FSR3 = Auto` untouched, `FrameGeneration = Off`. So the quality
and the frame generation were changed and the upscaler was not: **the owner's screenshot of the menu, taken after
them, shows Resolution Scaling = "AMD FidelityFX Super Resolution 2.1", Performance, Frame Generation Off** —
the file's `FSR2` is the menu's FSR 2.1. Both
stored sessions (215 s and 158 s, attached to a game already running) agree with FSR 2.1 built in and frame
generation off: every hook in, **not one ffx dispatch or query of any type**, no Streamline evaluation, no render
size, upscaler "unknown", factor 1.0 from Streamline's frame tokens, ~290 FPS. **So the 2.3 loader's double count
is still unobserved either way**: what answers it is a session in which `UserSettings.json` says
`ResolutionScaling = FSR3` afterwards.
- **The first start was lost to the transient this file recorded an hour earlier — in a real session this time.**
10:05:20 the game appeared; the Overlay went in at 10:05:23; 0.47 s later it was told to stop, and the Agent's
log says why: `SafetyUnhook; Discarded (tier 1, exit=UnhookedSafety, frames=0); guard=ModuleScanFailed/a module
list came back incomplete`. The Overlay's log shows the four patches restored within 0.75 s. The game ran on
unrecorded for two minutes until the owner restarted it. **It is not new and not rare**: the Agent's logs kept on
this PC (2026-11-05 onwards) hold five such ends — Phantom Blade Zero three times on 2026-11-05 (two safety
unhooks and one refusal before injection), Crown & Coin on 2026-11-10, Cyberpunk today — beside the two test
runs. Each is a module list read while the target was still loading modules, at a launch. **The question for the
owner is no longer hypothetical**: a list that cannot be read is not a finding, and rule 2 treats it as a refusal
so that an unreadable game is never hooked; reading it again a bounded number of times before refusing would
keep that — a list that stays unreadable still refuses — and stop losing sessions to a moment of loading. It
changes what the guard does on a check, so it is the owner's decision, and it is not made here. *(Made the same
day: D123, §NEXT item 1b.)*
### NEXT
1. ~~**The owner runs item 40** — above all **one session of Cyberpunk 2077 with FSR upscaling** on beta.42, then
quits the game the ordinary way. Its `logs\overlay-<pid>-….log` is what beta.43 waits for.~~ **Run 2026-11-12;
the section above is what it showed.** What is left of item 40 is (d), a session that changes upscaler, and
the owner's word on the rest.
1a. ~~**Before beta.43's plan: one session of Cyberpunk 2077 with Resolution Scaling = FSR 3, frame generation
off** (the second bullet above), and a second with it on. It says whether FrameLedger names FSR 3 there —
the route through the loader that D121 was first taken to be about — and whether the 2.3 loader counts an
UPSCALE twice. *(Tried 2026-11-12 10:08 and 10:12: the game was still on FSR 2 — the section above. The check
that the right thing ran is the file: `ResolutionScaling = FSR3`.)*~~
**It cannot be run, the owner said the same day: Cyberpunk 2077 has FSR 2.1 as its only FSR upscaler and
FSR 3.1 as frame generation only — two separate settings, not a pair; there is no FSR 3 under Resolution
Scaling.** So D121 is closed for good — every Cyberpunk session upscaling with FSR reads "unknown", by the
limit `LIMITATIONS.md` states — and **no title run so far upscales through a 2.3 loader**. The double
count stays unobserved. What IS measured is that this loader hands a frame-generation dispatch to the leaf's
export; an UPSCALE through the same `ffxDispatch` would take the same path. beta.43's plan therefore counts
an UPSCALE at the first hooked module that sees it (as `fl::adv::Owns` does) as a precaution, with a fixture
whose loader forwards to the leaf's export — rather than wait for a session that cannot be had.
1b. ~~**The owner's decision on the guard's module-list read** (the section above): refuse at the first incomplete
list, as now, or read again a bounded number of times first. If the second, it is a pull request of its own
in the guard (`FrameLedger.Injector`), with `19_SAFETY` amended in it, before or with beta.43.~~ **Decided
2026-11-12 — read again (D123) — and built the same day**: `Collected::kUnsettled`, up to three re-reads,
`19_SAFETY` amended. Not released: it ships with the next pre-release, and until then a launch can still be
lost this way on beta.42. What the owner then checks is the Agent's log: no `guard=ModuleScanFailed` end at a
game's launch, and if one comes its signal now says which kind — *kept changing while it was read* (four reads
were not enough) or *came back incomplete* (more modules than the guard's buffer holds).
2. **0.1.0-beta.43 — planned and approved 2026-11-12 (D123–D125), and under way.** The guard's re-read (D123,
#413) ships with it and not on its own (D124). Five pull requests after it: (1) an UPSCALE is counted at the
first source that saw one (D125) — the fixture's loader bound through the leaves' exports read K = 1 as 2.0
before it; (2) `slSetConstants`; (3) `ffxConfigure` on the four ffx modules; (4) the Agent, the App and the
Privacy Policy 2.17, whose wording the plan carried and the owner approved with it; (5) the release, owner-only
item 41. The design is the one below, as the review of 2026-11-12's first plan left it; nothing in the logs
changed it except D125.
~~**Read that log, then plan 0.1.0-beta.43**~~ — `slSetConstants` and `ffxConfigure`, and the fix for D121 if the
log shows the route. What to look for: which `HOOK_INSTALLED` lines there are (which of the four ffx modules and
the FSR 3.0 host were patched); the `FFX_DISPATCH` lines — is `b=0x10001` (UPSCALE) on any module, or only
`0x20004` / `0x2000c` / `0x20003`; an `UPSCALE_ROUTE` line; `PATCH_FAILED`; the last `RUNTIME_CENSUS` word.
**No UPSCALE type anywhere and no route line means the upscale does not come through any export the Overlay
patches** — statically linked, or a module the inventory does not name — and then the fix is not a new arm in
a detour. The design for the two hooks, as the review left it, is the plan of 2026-11-12 (moved with the
section above) and these points: the new rows are gated at the top of `InstallByFamily`, **before**
`ResolveScoped`, and installed only once the process was ever asked; hook families 13 and 14 with latches of
their own; `slSetConstants` checks the struct's GUID and `structVersion ≥ 1` on every call and reads only
`jitterOffset`, `mvecScale`, `cameraNear` … `cameraAspectRatio` and the seven Booleans — never bytes 368..423,
pinned by `offsetof` of the allowed members; summaries from the first viewport seen; `ffxConfigure` has an
owner slot of its own and reads `frameGenerationEnabled`, `allowAsyncWorkloads`, `flags`,
`onlyPresentGenerated`, `generationRect` and nothing else; the detours also consult `MayObserve()`;
`overlay-fields-check` gains three parameter names, `structType` among the shared members and an `offsetof` per
listed `sl::Constants` member. The registry holds 48 and the worst case becomes 25
(`kPatchSitesOutsideTheInventory` stays 7; the inventory's row count goes from 13 to 18 and its
`static_assert` says so).
3. **0.1.0-beta.44** — `slGetFeatureVersion` and `slGetFeatureRequirements` — when the owner says beta.43 passed.
4. **Trains C and D** (beta.45, beta.46) each begin with a spike and end in the owner's go or no.
### Left open by this session
- ~~**This release's own facts** — the tag's run, the digests, the delta — are not in any file yet: the release is cut
after this text. Record them in the next pull request.~~ **Recorded 2026-11-12: 0.1.0-beta.42 was released
2026-11-12T02:31:07Z** (09:31 in the owner's time zone) from the signed tag on `a708ae8` (#410), by run
43139775713 — green at the first attempt, one run for the one tag push. Eight assets; the seven digests of
`SHA256SUMS.txt` equal the ones GitHub computed; the four shipped natives carry `FL_BUILD_ID v0.1.0-beta.42`. The
delta from beta.41 is 710,943 bytes beside a full package of 110,716,228 — "Delta processed 0452 files. 0023
patched, 0429 unchanged". The wiki was published by run 43142009098. The rehearsal on the release branch (run
43137520796) had made a delta of 735,485 bytes with the same file counts.
- **No real game was run on this build.** The four changes were tested with the harness and the cost measured on
the headers. Item 40 is the first real session.
- **Whether the missing plane of Lies of P, Clair Obscur and Dying Light is `FLT_MAX`** is still the reading their
small `cameraFar` values point to, not a measurement. Item 40 (c).
- **A flake with a cause now, and a question in it for the owner.**
`ShmDrainIntegrationTests.TheGuardInjectsTheOverlayAndTheReaderDrainsRealFrames` was red once in this release's
local gate (and once on 2026-11-11, when the assertion did not yet print the verdict): the supervisor's first
re-scan, 0.8 s after the injection, came back `ModuleScanFailed` — *a module list came back incomplete* — while
the harness was still loading modules. The same gate was green on the same code before and after. In the test
it is a re-run. **In a real session the same answer is a safety unhook**: a re-scan that cannot read the module
list of a game that is still running stops the session (`19_SAFETY` §During a session; D48 covers only a game
that has exited). Whether the guard should read the list a second time before refusing is a change to rule 2's
checks and is the owner's to decide; nothing was changed. **A second one within the hour, in the gate of the pull
request that records the release's facts:**
`ToolhelpProcessSnapshotSourceTests.ThisProcessIsInTheSnapshotWithItsNormalisedImagePathAndACreationTime` got an
empty snapshot — `ToolhelpProcessSnapshotSource.Take` returns an empty list when the snapshot cannot be taken or
walked, and says nothing. Green on the run after. Both are Windows refusing, for a moment, to enumerate something
on a PC that was building, testing and running FrameLedger itself at once; what an empty snapshot does to the
watcher's tick in a real session was not looked into.
- ~~**SonarCloud has not answered for #406–#409**: `main`'s `sonarcloud` job was cancelled by the next merge each
time. It runs to its end on this release's commit; read it then.~~ **It answered on `a708ae8`: the quality gate
passed, and one issue was open on `main`** — `cpp:S5813`, a `strlen` in the helper the new log case of
`guard_test.cpp` reads lines with (#408). Fixed in the pull request that records these facts: the helper takes
strings. **`csharpsquid:S3869` on `ParentDump.cs` is no longer open** — SonarCloud shows it accepted at
2026-11-11T21:13Z (04:13 on the 12th, the owner's time), which is before the texts that still called it open
were written; they were not checked against SonarCloud then. **Qodana's two reports are green on the release's
commit**; the native one was red from #407 to #408 on seven problems in test code, answered in #409.
- **`LIMITATIONS.md` and the accuracy statement still say the processor's, the memory's and the motherboard's
sensors "have never been read on real hardware"** — the owner's to reword. ~~**SonarCloud's `csharpsquid:S3869` on
`ParentDump.cs`** is the owner's to accept.~~ *(Done — the line above.)* **Items 36 (d) and 37 are still open.** The alpha line still rests
(D98).
**Owner-only:** item 40.
+18
View File
@@ -63,6 +63,24 @@ are kept because they record what each version changed and why (owner decision D
>
> Version 2.5 (2026-09-27, 0.1.0-beta.10) adds how a tracked game's window is shown — read from Windows — and the engine build name read from an Unreal Engine game's executable. It is also the first version to say two things the software already did: it reads the **content** of a library game's executable (markers in its first 8 MB and its import table, since the detection of engines and features; and, when a session starts, the graphics-library markers in the whole file), and it reads the processor load and the memory in use (since 0.1.0-beta.3). Nothing here leaves your device, as before.
### What version 2.17 of the Privacy Policy changed (0.1.0-beta.43)
**Two more calls read inside the game, only while Advanced metrics is on** (train B's second step, owner decisions
D122–D125; the wording approved with the plan of 0.1.0-beta.43). Version 2.16 named what a session stores of DLSS and
of FSR's upscaling item by item, and neither list holds what this release reads, so the version moves rather than
the words being stretched. §1's item on Advanced metrics gains **what the game told NVIDIA Streamline about each
frame** — the size of the jitter, the motion-vector scale, the depth range and whether depth is inverted, the lowest
and highest field of view, the aspect ratio, whether the projection is orthographic, how its motion vectors are
stored and how often it reset the upscaler's history — and **how it configured FSR frame generation** — on or off,
whether it may run asynchronously, its flags, whether only generated frames are presented, and the rectangle it
generates in. The sentence on what is never read (where the camera is, which way it looks, its matrices) stands as
it was: those sit in the same data as Streamline's constants, and a check in the build refuses code that names them.
§4 says what is new about *how*: until now every parameter read was of a call FrameLedger intercepted anyway; these
two calls are intercepted in a game **only once a session with the option on has started there**, and with the
option off nothing in the game is touched for them. The accuracy block's item on what a game tells its upscaler
names the two, and no longer says none of it was read from a real game — FSR's upscaling values were, on
0.1.0-beta.41 and beta.42. The Disclaimer stays 2.15, as before. §2 is unchanged: nothing is sent.
### What version 2.16 of the Privacy Policy changed (0.1.0-beta.40)
**Advanced metrics inside the game** (train B, owner decisions D111–D116; the content approved with the plan, once
+14
View File
@@ -45,10 +45,24 @@ also keeps what the game itself handed to DLSS and FSR:
- **FSR** — sharpening (on or off, and how strong), the largest jitter offset, the exposure, the near and far planes,
the **range** of the field of view over the session, the flags of the call, the frame time the game reported, and
FSR's own video memory at the moments the game asked for it.
- **Streamline** (NVIDIA's library that games use for DLSS; since 0.1.0-beta.43) — what the game tells it about
each frame: the largest jitter offset, the motion-vector scale and how the motion vectors are stored, the near and
far planes and whether depth is inverted, the **range** of the field of view, the aspect ratio, whether the
projection is orthographic, and how many times the game reset the upscaler's history (a camera cut, a loading
screen). Where a game draws several views, these are the first view's.
- **FSR frame generation** (since 0.1.0-beta.43) — how the game configured it: on or off, whether it may run
asynchronously, its flags, whether only generated frames are presented, and the part of the picture it generates
in. A setting the game changed during the session reads *on and off*. This is what the game **asked for**; how
many frames were generated is in the session's summary, as before.
These are the game's own words to the upscaler, shown in the vendor's notation (`preExposure`, preset `K`).
FrameLedger does not check what the upscaler did with them.
The last two are read from calls FrameLedger hooks **only for Advanced metrics**: in a game where no session has
been recorded with the option on since it started, those two hooks are not there. The line under the session says,
for each of the two, whether it was *read*, *hooked — the game did not make the call*, or *not hooked — the game did
not load the library that has the call*.
**Many games will show nothing here**, and the line under the session says why: *the game made none of the calls
these are read from* — most games set their DLSS options through a call FrameLedger cannot see, and only games that
use FSR 3.1 or later through AMD's own library show the FSR rows — or *the session was not measured inside the game*.
+6 -2
View File
@@ -12,7 +12,7 @@
HTML comments are not part of the block.
-->
> ⚠ **What FrameLedger actually measures today — 2026-11-11.** The software is a beta; its latest
> **beta is `0.1.0-beta.42`** (2026-11-12), an unsigned installer built from that tag with its
> **beta is `0.1.0-beta.43`** (2026-11-12), an unsigned installer built from that tag with its
> checksums published beside it (alphas — experimental builds that try a newer .NET — are published apart). The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs (unless you switched its recording off), injects only into games you enabled
@@ -113,7 +113,11 @@
> range, field-of-view range, flags and frame time it hands FSR, are read from the arguments of the calls
> FrameLedger intercepts and shown as the game stated them — not checked against what the upscaler did. Most games
> set their DLSS options through a call that cannot be intercepted and show none; the FSR values need FSR 3.1 or
> later through AMD's own library. None of it has been read from a real game yet.
> later through AMD's own library. Since beta.43 also what a game tells NVIDIA Streamline about each frame (jitter,
> motion-vector scale, depth range, field-of-view range, how often it reset the upscaler's history — for the first
> viewport that called, where a game has several) and how it configures FSR frame generation (the settings it asked
> for, not whether frames were generated). FSR's upscaling values have been read from real games; the DLSS options,
> Streamline's constants and the frame-generation configuration have not been confirmed on one yet.
> - **Safety:** every pre-injection check runs before injection, including the signed-by-a-known-vendor
> half of the suspicious-module rule. During every capture the Agent re-runs the checks every 30 s and
> stops capturing on a refusal: a Direct3D or OpenGL game's hooks are removed, and the Vulkan layer
+6 -2
View File
@@ -121,7 +121,7 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-11-11.** The software is a beta; its latest
> **beta is `0.1.0-beta.42`** (2026-11-12), an unsigned installer built from that tag with its
> **beta is `0.1.0-beta.43`** (2026-11-12), an unsigned installer built from that tag with its
> checksums published beside it (alphas — experimental builds that try a newer .NET — are published apart). The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs (unless you switched its recording off), injects only into games you enabled
@@ -222,7 +222,11 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
> range, field-of-view range, flags and frame time it hands FSR, are read from the arguments of the calls
> FrameLedger intercepts and shown as the game stated them — not checked against what the upscaler did. Most games
> set their DLSS options through a call that cannot be intercepted and show none; the FSR values need FSR 3.1 or
> later through AMD's own library. None of it has been read from a real game yet.
> later through AMD's own library. Since beta.43 also what a game tells NVIDIA Streamline about each frame (jitter,
> motion-vector scale, depth range, field-of-view range, how often it reset the upscaler's history — for the first
> viewport that called, where a game has several) and how it configures FSR frame generation (the settings it asked
> for, not whether frames were generated). FSR's upscaling values have been read from real games; the DLSS options,
> Streamline's constants and the frame-generation configuration have not been confirmed on one yet.
> - **Safety:** every pre-injection check runs before injection, including the signed-by-a-known-vendor
> half of the suspicious-module rule. During every capture the Agent re-runs the checks every 30 s and
> stops capturing on a refusal: a Direct3D or OpenGL game's hooks are removed, and the Vulkan layer
+3 -3
View File
@@ -1,6 +1,6 @@
# FrameLedger — Privacy Policy
**Version:** 2.16 · **Effective:** {{RELEASE_DATE}}
**Version:** 2.17 · **Effective:** {{RELEASE_DATE}}
**Short version: everything stays on your PC. FrameLedger has no accounts, no telemetry, no analytics, and never uploads your data anywhere.**
@@ -11,7 +11,7 @@ Stored in `%LOCALAPPDATA%\FrameLedger` on your device:
- Your game library entries (names, executable paths, metadata you or the app filled in, and whether each one is recorded).
- Images you choose for a game (Edit…), copied into the `covers` folder; choosing the store's image again, or removing the game together with its sessions, deletes the copy. Artwork a store's app keeps on your PC, or a game ships in its own folder, is shown from where it is and not copied.
- Performance sessions: frame timing series, computed statistics, hardware sensor series (temperatures, load, power, memory usage, and the graphics card's clock speeds, fan speed, memory temperature and whether its power limit or heat held it back), the game's own memory use (its dedicated and shared video memory, private working set, working set and commit, once a second), session duration, crash flags, the graphics driver's settings the game ran under (NVIDIA only), how the game's window was shown (full-screen, borderless or windowed, for how long, its size and the monitor's), tags and notes you write.
- **Only while Settings ▸ Advanced metrics is on** (it is off unless you switch it on), with each session: more hardware sensor series — the graphics card's memory use in detail, its load by part, its clocks, voltages, currents, power, each fan and its video encoder's use; and, when the capture agent runs as administrator with PawnIO installed, the processor's temperatures, load, clocks, power and voltages by core, the memory in use and its modules' temperatures, and the motherboard's temperatures, fans and voltages — and a description of the hardware: the graphics card's firmware version, architecture, bus and memory sizes, the graphics driver's package and the chipset it names, the motherboard's and the memory modules' model names, what each connected display can do (the HDR formats it accepts, its brightness range, variable refresh), whether variable refresh was in use on the display the game ran on and the colour space the game presented in, and the graphics driver's settings — its global ones and the ones it holds for the game (NVIDIA only). For a game FrameLedger injects into, a session then also stores what the game itself passed to its upscaler in the calls FrameLedger intercepts: the output size, the model presets and the exposure values it gave DLSS, whether it said its colour buffers are HDR, auto-exposure and alpha upscaling; and the sharpening, the size of the jitter, the exposure, the depth range, the lowest and highest field of view and the flags it gave FSR, the frame time it reported to FSR, and FSR's own video memory when the game asked for it — never where the game's camera is, which way it looks, or its matrices. No serial number, no display identification data (EDID) and no list of other programs is read or stored. Switching the option off stops the reading, inside a game as well; what earlier sessions stored stays with them until you delete those sessions.
- **Only while Settings ▸ Advanced metrics is on** (it is off unless you switch it on), with each session: more hardware sensor series — the graphics card's memory use in detail, its load by part, its clocks, voltages, currents, power, each fan and its video encoder's use; and, when the capture agent runs as administrator with PawnIO installed, the processor's temperatures, load, clocks, power and voltages by core, the memory in use and its modules' temperatures, and the motherboard's temperatures, fans and voltages — and a description of the hardware: the graphics card's firmware version, architecture, bus and memory sizes, the graphics driver's package and the chipset it names, the motherboard's and the memory modules' model names, what each connected display can do (the HDR formats it accepts, its brightness range, variable refresh), whether variable refresh was in use on the display the game ran on and the colour space the game presented in, and the graphics driver's settings — its global ones and the ones it holds for the game (NVIDIA only). For a game FrameLedger injects into, a session then also stores what the game itself passed to its upscaler in the calls FrameLedger intercepts: the output size, the model presets and the exposure values it gave DLSS, whether it said its colour buffers are HDR, auto-exposure and alpha upscaling; and the sharpening, the size of the jitter, the exposure, the depth range, the lowest and highest field of view and the flags it gave FSR, the frame time it reported to FSR, and FSR's own video memory when the game asked for it; what the game told NVIDIA Streamline about each frame — the size of the jitter, the motion-vector scale, the depth range and whether depth is inverted, the lowest and highest field of view, the aspect ratio, whether the projection is orthographic, how its motion vectors are stored and how often it reset the upscaler's history; and how it configured FSR frame generation — on or off, whether it may run asynchronously, its flags, whether only generated frames are presented, and the rectangle it generates in — never where the game's camera is, which way it looks, or its matrices. No serial number, no display identification data (EDID) and no list of other programs is read or stored. Switching the option off stops the reading, inside a game as well; what earlier sessions stored stays with them until you delete those sessions.
- A hardware snapshot per session (CPU/GPU model, driver version, RAM size, OS build, display mode) used for the "what changed between sessions" feature.
- App settings, logs (rotated daily — the app keeps 7 days, the capture agent 14 — including the logs written by the component loaded into games), and, after a crash of the app itself, crash dump files.
- Which games you enabled code injection for, and when you consented.
@@ -43,7 +43,7 @@ An exported session (CSV or JSON) and a bug report can contain your games' names
## 4. What the app can technically observe
To do its job, FrameLedger observes: which of *your tracked* executables — the entries in your library whose recording is on — are running, and their process trees; whether a game you enabled hooking for runs in an app container, and which of Windows' code-protection settings it runs under (for example, accepting only Microsoft-signed code), read from Windows before any injection; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation) — and, only while Advanced metrics is on, more of the parameters of the upscaling calls, which are then stored with the session (sizes, presets, exposure, sharpening, the jitter's size, the depth range, the range of the field of view, flags, the reported frame time, the upscaler's own memory), never the camera's position, direction or matrices; the memory use of a tracked game's process — its dedicated and shared video memory, from Windows' GPU performance counters, and its working sets and commit, from Windows' process-memory information, for which a game it does not inject into is opened with the least access Windows offers and closed again (never its memory's content); loaded module names of a game being captured, the version information of its upscaling, frame-generation and neural-rendering libraries, and whether each was loaded from the game's folder or from the graphics driver's own copy (for detection and for the anti-cheat safety check); the names of the files in each library game's install folder, the version information of its executable and of the upscaling and neural-rendering libraries it ships, the content of its executable file (the markers of the engine and of the graphics libraries it carries, the libraries it imports, and the engine build name an Unreal Engine game carries), the version marks an engine keeps in its own files (Unity's player library and the header of its data file, the header of a Godot data pack, an RPG Maker game's title, core script and Game.ini, the library Game.ini names, and the version file of a Ren'Py game's engine), and the store files that name it (Steam's and GOG's, on your disk) and, for a game the Xbox app or the Microsoft Store installed, the package files in its install folder that describe it (`MicrosoftGame.config` and `appxmanifest.xml`) — to detect its engine, its engine version and its features and to check it for anti-cheat before any injection is possible; the lists of installed games that the Steam, GOG GALAXY, Epic Games and itch apps keep on your disk, and where GOG GALAXY is installed, the folders the Xbox app installs games into on each drive (named by the `.GamingRoot` file at the drive's root) with each game's package files, and Windows' answer to whether that game's package is installed for you — read when you import your library and when you press Play, to find the store that installed a game and hand the game to that store's app — Steam's and GOG GALAXY's also when you open a game's page, to find the artwork their apps keep for it; the cover and banner images that the Steam and GOG GALAXY apps keep on your disk for a game in your library and the logo and splash-screen images a game from the Xbox app ships in its own folder — read to show them on its page, never copied or sent anywhere; the size, position and state of a tracked game's window and the monitor it is on, read from Windows and not from the game, and — for a game FrameLedger injects into — whether the game asked for exclusive full-screen; the NVIDIA driver's settings for your tracked executables (read only: the DLSS and frame-generation overrides the NVIDIA App set); hardware sensor values from your graphics driver's own libraries; and — only while Advanced metrics is on — that driver's description of the graphics card and of each connected display, what it reports about the display a tracked game's window is on, its settings for a tracked game and its global ones (read only), and, when the capture agent runs as administrator with PawnIO installed, the sensors and model names of the processor, the memory and the motherboard (never a drive's), all of which are also read with no game running while the Advanced page is open, to show them there, and are not stored then; how busy the processor is and how much memory is in use, from Windows' own counters; the crash reports Windows keeps in its Application log about a tracked game's executable while it ran (to tell a crash from an ordinary exit — the reports are read, never sent anywhere); and the names of the programs a tracked game starts, so that a game's own crash reporter is recognised.
To do its job, FrameLedger observes: which of *your tracked* executables — the entries in your library whose recording is on — are running, and their process trees; whether a game you enabled hooking for runs in an app container, and which of Windows' code-protection settings it runs under (for example, accepting only Microsoft-signed code), read from Windows before any injection; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation) — and, only while Advanced metrics is on, more of the parameters of the upscaling calls, and the parameters of two further calls it begins to intercept in a game only once a session with that option on has started there (the constants the game gives NVIDIA Streamline for each frame, and the game's configuration of FSR frame generation), which are then stored with the session (sizes, presets, exposure, sharpening, the jitter's size, the motion-vector scale, the depth range, the range of the field of view, flags, the reported frame time, the upscaler's own memory, how frame generation is configured), never the camera's position, direction or matrices; the memory use of a tracked game's process — its dedicated and shared video memory, from Windows' GPU performance counters, and its working sets and commit, from Windows' process-memory information, for which a game it does not inject into is opened with the least access Windows offers and closed again (never its memory's content); loaded module names of a game being captured, the version information of its upscaling, frame-generation and neural-rendering libraries, and whether each was loaded from the game's folder or from the graphics driver's own copy (for detection and for the anti-cheat safety check); the names of the files in each library game's install folder, the version information of its executable and of the upscaling and neural-rendering libraries it ships, the content of its executable file (the markers of the engine and of the graphics libraries it carries, the libraries it imports, and the engine build name an Unreal Engine game carries), the version marks an engine keeps in its own files (Unity's player library and the header of its data file, the header of a Godot data pack, an RPG Maker game's title, core script and Game.ini, the library Game.ini names, and the version file of a Ren'Py game's engine), and the store files that name it (Steam's and GOG's, on your disk) and, for a game the Xbox app or the Microsoft Store installed, the package files in its install folder that describe it (`MicrosoftGame.config` and `appxmanifest.xml`) — to detect its engine, its engine version and its features and to check it for anti-cheat before any injection is possible; the lists of installed games that the Steam, GOG GALAXY, Epic Games and itch apps keep on your disk, and where GOG GALAXY is installed, the folders the Xbox app installs games into on each drive (named by the `.GamingRoot` file at the drive's root) with each game's package files, and Windows' answer to whether that game's package is installed for you — read when you import your library and when you press Play, to find the store that installed a game and hand the game to that store's app — Steam's and GOG GALAXY's also when you open a game's page, to find the artwork their apps keep for it; the cover and banner images that the Steam and GOG GALAXY apps keep on your disk for a game in your library and the logo and splash-screen images a game from the Xbox app ships in its own folder — read to show them on its page, never copied or sent anywhere; the size, position and state of a tracked game's window and the monitor it is on, read from Windows and not from the game, and — for a game FrameLedger injects into — whether the game asked for exclusive full-screen; the NVIDIA driver's settings for your tracked executables (read only: the DLSS and frame-generation overrides the NVIDIA App set); hardware sensor values from your graphics driver's own libraries; and — only while Advanced metrics is on — that driver's description of the graphics card and of each connected display, what it reports about the display a tracked game's window is on, its settings for a tracked game and its global ones (read only), and, when the capture agent runs as administrator with PawnIO installed, the sensors and model names of the processor, the memory and the motherboard (never a drive's), all of which are also read with no game running while the Advanced page is open, to show them there, and are not stored then; how busy the processor is and how much memory is in use, from Windows' own counters; the crash reports Windows keeps in its Application log about a tracked game's executable while it ran (to tell a crash from an ordinary exit — the reports are read, never sent anywhere); and the names of the programs a tracked game starts, so that a game's own crash reporter is recognised.
It does **not** read game memory outside those API parameters, and does not read game saves, chat, input content, network traffic, or anything unrelated to performance measurement. It records only for programs you added to your library and did not switch recording off for — a program whose recording is off is not watched at all — and injects only into games you individually enabled.
+15
View File
@@ -260,6 +260,7 @@ public static class Strings
nameof(Advanced_Elevation_Hint),
nameof(Advanced_Facts_Header),
nameof(Advanced_Header),
nameof(Advanced_InGameCallsLine),
nameof(Advanced_InGameLine),
nameof(Advanced_Machine_Intro),
nameof(Advanced_Max),
@@ -302,6 +303,10 @@ public static class Strings
nameof(AdvInGame_NotHooked),
nameof(AdvInGame_Reading),
nameof(AdvInGame_Unknown),
nameof(AdvInGameCall_NeverCalled),
nameof(AdvInGameCall_NotHooked),
nameof(AdvInGameCall_Read),
nameof(AdvInGameCall_Unknown),
nameof(AdvReach_Deferred),
nameof(AdvReach_Game),
nameof(AdvReach_HookedCall),
@@ -1988,6 +1993,8 @@ public static class Strings
public static string Advanced_Header => ResourceManager.GetString(nameof(Advanced_Header), Culture) ?? nameof(Advanced_Header);
public static string Advanced_InGameCallsLine => ResourceManager.GetString(nameof(Advanced_InGameCallsLine), Culture) ?? nameof(Advanced_InGameCallsLine);
public static string Advanced_InGameLine => ResourceManager.GetString(nameof(Advanced_InGameLine), Culture) ?? nameof(Advanced_InGameLine);
public static string Advanced_Machine_Intro => ResourceManager.GetString(nameof(Advanced_Machine_Intro), Culture) ?? nameof(Advanced_Machine_Intro);
@@ -2072,6 +2079,14 @@ public static class Strings
public static string AdvInGame_Unknown => ResourceManager.GetString(nameof(AdvInGame_Unknown), Culture) ?? nameof(AdvInGame_Unknown);
public static string AdvInGameCall_NeverCalled => ResourceManager.GetString(nameof(AdvInGameCall_NeverCalled), Culture) ?? nameof(AdvInGameCall_NeverCalled);
public static string AdvInGameCall_NotHooked => ResourceManager.GetString(nameof(AdvInGameCall_NotHooked), Culture) ?? nameof(AdvInGameCall_NotHooked);
public static string AdvInGameCall_Read => ResourceManager.GetString(nameof(AdvInGameCall_Read), Culture) ?? nameof(AdvInGameCall_Read);
public static string AdvInGameCall_Unknown => ResourceManager.GetString(nameof(AdvInGameCall_Unknown), Culture) ?? nameof(AdvInGameCall_Unknown);
public static string AdvReach_Deferred => ResourceManager.GetString(nameof(AdvReach_Deferred), Culture) ?? nameof(AdvReach_Deferred);
public static string AdvReach_Game => ResourceManager.GetString(nameof(AdvReach_Game), Culture) ?? nameof(AdvReach_Game);
+21 -1
View File
@@ -653,6 +653,10 @@
<value>詳細メトリクス</value>
<comment>review</comment>
</data>
<data name="Advanced_InGameCallsLine" xml:space="preserve">
<value>ゲームが毎フレーム Streamline に伝える内容: {0}。FSR フレーム生成の設定方法: {1}。</value>
<comment>review</comment>
</data>
<data name="Advanced_InGameLine" xml:space="preserve">
<value>ゲーム内: {0}。</value>
<comment>review</comment>
@@ -821,6 +825,22 @@
<value>不明</value>
<comment>review</comment>
</data>
<data name="AdvInGameCall_NeverCalled" xml:space="preserve">
<value>フック済み - ゲームはこの呼び出しを行いませんでした</value>
<comment>review</comment>
</data>
<data name="AdvInGameCall_NotHooked" xml:space="preserve">
<value>未フック - この呼び出しを持つライブラリをゲームが読み込みませんでした</value>
<comment>review</comment>
</data>
<data name="AdvInGameCall_Read" xml:space="preserve">
<value>読み取りました</value>
<comment>review</comment>
</data>
<data name="AdvInGameCall_Unknown" xml:space="preserve">
<value>不明</value>
<comment>review</comment>
</data>
<data name="AdvReach_Deferred" xml:space="preserve">
<value>このリリースでは読み取らない</value>
<comment>review</comment>
@@ -1438,7 +1458,7 @@
<comment>review</comment>
</data>
<data name="Settings_Advanced_Body" xml:space="preserve">
<value>セッション中にグラフィックス ドライバーとハードウェア センサーからさらに多くを読み取り、セッションと一緒に保存します - グラフィックス カードのメモリと負荷の詳細、各ファンと電圧、ディスプレイの対応機能、ゲームに対するドライバーの設定など。FrameLedger が内部から計測するゲームでは、ゲームが DLSS と FSR に渡す内容 (サイズ、プリセット、シャープニング、露出) も読み取ります - カメラの位置は決して読み取りません。オフ: ゲーム内も含め、追加の読み取りも保存も行いません。次のセッションから適用され、オフの間に記録したセッションが後から補われることはありません。</value>
<value>セッション中にグラフィックス ドライバーとハードウェア センサーからさらに多くを読み取り、セッションと一緒に保存します - グラフィックス カードのメモリと負荷の詳細、各ファンと電圧、ディスプレイの対応機能、ゲームに対するドライバーの設定など。FrameLedger が内部から計測するゲームでは、ゲームが DLSS、Streamline、FSR に渡す内容 (サイズ、プリセット、シャープニング、露出、深度範囲、フレーム生成の設定) も読み取ります - カメラの位置は決して読み取りません。オフ: ゲーム内も含め、追加の読み取りも保存も行いません。次のセッションから適用され、オフの間に記録したセッションが後から補われることはありません。</value>
<comment>review</comment>
</data>
<data name="Settings_Advanced_Label" xml:space="preserve">
+16 -1
View File
@@ -495,6 +495,9 @@
<data name="Advanced_Header" xml:space="preserve">
<value>Advanced metrics</value>
</data>
<data name="Advanced_InGameCallsLine" xml:space="preserve">
<value>What the game tells Streamline each frame: {0}. How it configures FSR frame generation: {1}.</value>
</data>
<data name="Advanced_InGameLine" xml:space="preserve">
<value>Inside the game: {0}.</value>
</data>
@@ -621,6 +624,18 @@
<data name="AdvInGame_Unknown" xml:space="preserve">
<value>not known</value>
</data>
<data name="AdvInGameCall_NeverCalled" xml:space="preserve">
<value>hooked - the game did not make the call</value>
</data>
<data name="AdvInGameCall_NotHooked" xml:space="preserve">
<value>not hooked - the game did not load the library that has the call</value>
</data>
<data name="AdvInGameCall_Read" xml:space="preserve">
<value>read</value>
</data>
<data name="AdvInGameCall_Unknown" xml:space="preserve">
<value>not known</value>
</data>
<data name="AdvReach_Deferred" xml:space="preserve">
<value>Not read in this release</value>
</data>
@@ -1084,7 +1099,7 @@
<value>The agent did not answer the rules update.</value>
</data>
<data name="Settings_Advanced_Body" xml:space="preserve">
<value>Read more from the graphics driver and the hardware sensors during a session - the graphics card's memory and load in detail, each fan and voltage, what your display can do, the driver's settings for the game - and, in a game FrameLedger measures from inside, what the game tells DLSS and FSR (sizes, presets, sharpening, exposure - never where the camera is). All of it is stored with the session. Off: nothing more is read or stored, inside a game either. It applies from the next session, and a session recorded while it was off is not filled in later.</value>
<value>Read more from the graphics driver and the hardware sensors during a session - the graphics card's memory and load in detail, each fan and voltage, what your display can do, the driver's settings for the game - and, in a game FrameLedger measures from inside, what the game tells DLSS, Streamline and FSR (sizes, presets, sharpening, exposure, the depth range, how frame generation is configured - never where the camera is). All of it is stored with the session. Off: nothing more is read or stored, inside a game either. It applies from the next session, and a session recorded while it was off is not filled in later.</value>
</data>
<data name="Settings_Advanced_Label" xml:space="preserve">
<value>Advanced metrics</value>
+16 -1
View File
@@ -490,6 +490,9 @@
<data name="Advanced_Header" xml:space="preserve">
<value>Thông số nâng cao</value>
</data>
<data name="Advanced_InGameCallsLine" xml:space="preserve">
<value>Những gì game báo cho Streamline mỗi khung hình: {0}. Cách game cấu hình frame generation của FSR: {1}.</value>
</data>
<data name="Advanced_InGameLine" xml:space="preserve">
<value>Bên trong game: {0}.</value>
</data>
@@ -616,6 +619,18 @@
<data name="AdvInGame_Unknown" xml:space="preserve">
<value>không rõ</value>
</data>
<data name="AdvInGameCall_NeverCalled" xml:space="preserve">
<value>đã hook - game không thực hiện lời gọi</value>
</data>
<data name="AdvInGameCall_NotHooked" xml:space="preserve">
<value>chưa hook - game không nạp thư viện chứa lời gọi này</value>
</data>
<data name="AdvInGameCall_Read" xml:space="preserve">
<value>đã đọc</value>
</data>
<data name="AdvInGameCall_Unknown" xml:space="preserve">
<value>không rõ</value>
</data>
<data name="AdvReach_Deferred" xml:space="preserve">
<value>Không đọc trong bản phát hành này</value>
</data>
@@ -1079,7 +1094,7 @@
<value>Agent không phản hồi yêu cầu cập nhật quy tắc.</value>
</data>
<data name="Settings_Advanced_Body" xml:space="preserve">
<value>Đọc thêm từ driver đồ hoạ và các cảm biến phần cứng trong lúc ghi phiên - bộ nhớ và tải của card đồ hoạ ở mức chi tiết, từng quạt và điện áp, khả năng của màn hình, thiết lập của driver cho game - và, với game mà FrameLedger đo từ bên trong, những gì game đưa cho DLSS và FSR (kích thước, preset, làm nét, phơi sáng - không bao giờ là vị trí camera). Tất cả được lưu cùng phiên. Tắt: không đọc và không lưu thêm gì, kể cả bên trong game. Áp dụng từ phiên kế tiếp; phiên đã ghi lúc tắt sẽ không được bổ sung về sau.</value>
<value>Đọc thêm từ driver đồ hoạ và các cảm biến phần cứng trong lúc ghi phiên - bộ nhớ và tải của card đồ hoạ ở mức chi tiết, từng quạt và điện áp, khả năng của màn hình, thiết lập của driver cho game - và, với game mà FrameLedger đo từ bên trong, những gì game đưa cho DLSS, Streamline và FSR (kích thước, preset, làm nét, phơi sáng, khoảng độ sâu, cách cấu hình frame generation - không bao giờ là vị trí camera). Tất cả được lưu cùng phiên. Tắt: không đọc và không lưu thêm gì, kể cả bên trong game. Áp dụng từ phiên kế tiếp; phiên đã ghi lúc tắt sẽ không được bổ sung về sau.</value>
</data>
<data name="Settings_Advanced_Label" xml:space="preserve">
<value>Thông số nâng cao</value>
@@ -50,6 +50,9 @@ public static class AdvancedLabels
/// <summary>What became, in one session, of the entries read inside the game (0.1.0-beta.40).</summary>
public static string InGame(AdvancedInGameStatus status) => Lookup("AdvInGame_" + status) ?? status.ToString();
/// <summary>What became of one call hooked only for Advanced metrics, in a session (0.1.0-beta.43).</summary>
public static string InGameCall(AdvancedInGameCall call) => Lookup("AdvInGameCall_" + call) ?? call.ToString();
/// <summary>A token the driver's answer was mapped to; the token itself where this build has no word for it.</summary>
public static string Token(string token) => Lookup("AdvToken_" + token) ?? token;
@@ -188,9 +188,24 @@ public static class AdvancedPresenter
// A session's row also says what became of the entries read inside the game; the machine's live state and a
// row stored before 0.1.0-beta.40 do not, and then the sentence is not there.
return sources.InGame is { } inGame
? line + " " + string.Format(CultureInfo.CurrentCulture, Strings.Advanced_InGameLine, AdvancedLabels.InGame(inGame))
: line;
if (sources.InGame is { } inGame)
{
line += " " + string.Format(CultureInfo.CurrentCulture, Strings.Advanced_InGameLine, AdvancedLabels.InGame(inGame));
}
// The two calls hooked only for Advanced metrics (0.1.0-beta.43): for each, whether it was read, hooked and
// never made, or not hooked - so that "nothing here" says which of the two it is. A row stored before, and a
// session not measured inside the game, carry neither.
if (sources.StreamlineConstants is { } streamline && sources.FsrFrameGeneration is { } frameGeneration)
{
line += " " + string.Format(
CultureInfo.CurrentCulture,
Strings.Advanced_InGameCallsLine,
AdvancedLabels.InGameCall(streamline),
AdvancedLabels.InGameCall(frameGeneration));
}
return line;
}
private static string StatusOf(AdvancedMetric metric, AdvancedSources? now)
@@ -0,0 +1,28 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Advanced;
/// <summary>
/// What became, in one session, of the entries read from ONE call that FrameLedger hooks only for Advanced metrics
/// (0.1.0-beta.43: <c>slSetConstants</c>, <c>ffxConfigure</c>). Beside <see cref="AdvancedInGameStatus"/>, which
/// speaks for the session as a whole, this tells "the hook was in and the game never made the call" from "the hook
/// was not in" - two different reasons a value is absent, and only the first says something about the game.
/// </summary>
public enum AdvancedInGameCall
{
/// <summary>Not stated: a row stored before 0.1.0-beta.43.</summary>
Unknown = 0,
/// <summary>The game made the call and what it passed was read.</summary>
Read = 1,
/// <summary>The hook was in for the session and the game did not make the call where it could be seen.</summary>
NeverCalled = 2,
/// <summary>
/// The hook was not in: the game did not load the library that exports the call (it does not use Streamline, or
/// FSR through AMD's libraries), or the library is of a generation FrameLedger does not read.
/// </summary>
NotHooked = 3,
}
@@ -162,16 +162,18 @@ public static class AdvancedMetricCatalog
Sampled("ffx.upscale.frame_time_delta", FidelityFx, Game, Milliseconds, Upscaling, "The frame time the game reported to FSR"),
Sampled("ffx.memory_usage", FidelityFx, Game, Mebibytes, Upscaling, "FSR's own video memory, when the game asks it"),
// ---- Inside the game: two hooks of their own (0.1.0-beta.43), installed only where Advanced metrics was asked for
Session("sl.constants.jitter", Streamline, Game, Table, Upscaling, "The jitter offsets the game gave Streamline"),
Session("sl.constants.motion_vectors", Streamline, Game, Table, Upscaling, "Motion-vector scale, and whether they are 3D, dilated, jittered"),
Session("sl.constants.depth", Streamline, Game, Table, Upscaling, "Near and far planes, and whether depth is inverted"),
Session("sl.constants.projection", Streamline, Game, Table, Upscaling, "Field of view, aspect ratio, orthographic or not"),
Session("sl.constants.resets", Streamline, Game, Count, Upscaling, "How often the game reset the upscaler's history"),
Session("ffx.framegen.config", FidelityFx, Game, Table, FrameGeneration, "The game's FSR frame-generation configuration"),
// ---- Inside the game: hooks that are not built ----------------------------------------------------------
Session("sl.constants.jitter", Streamline, NewHook, Text, Upscaling, "The jitter offsets the game gave Streamline"),
Session("sl.constants.motion_vectors", Streamline, NewHook, Text, Upscaling, "Motion-vector scale, and whether they are 3D, dilated, jittered"),
Session("sl.constants.depth", Streamline, NewHook, Text, Upscaling, "Near and far planes, and whether depth is inverted"),
Session("sl.constants.projection", Streamline, NewHook, Text, Upscaling, "Field of view, aspect ratio, orthographic or not"),
Session("sl.constants.resets", Streamline, NewHook, Count, Upscaling, "How often the game reset the upscaler's history"),
Session("sl.feature.versions", Streamline, NewHook, Table, Upscaling, "Each Streamline feature's version and its NGX model version"),
Session("sl.feature.requirements", Streamline, NewHook, Table, Upscaling, "What each Streamline feature requires: operating system, driver, buffers"),
Session("sl.init.preferences", Streamline, NewHook, Text, Upscaling, "The preferences the game started Streamline with"),
Session("ffx.framegen.config", FidelityFx, NewHook, Text, FrameGeneration, "The game's FSR frame-generation configuration"),
Session("sl.constants.camera", Streamline, PlayerState, Text, Upscaling, "Camera position, axes and matrices"),
// ---- Inside the game: routes a spike decides ------------------------------------------------------------
@@ -22,6 +22,16 @@ public sealed record AdvancedSources(
/// </summary>
public AdvancedInGameStatus? InGame { get; init; }
/// <summary>
/// What became of what the game tells Streamline about each frame (<c>slSetConstants</c>, the
/// <c>sl.constants.</c> entries) in the session this describes (0.1.0-beta.43); null where that is not a
/// question - the machine's live state, a session not measured inside the game - and in every row stored before.
/// </summary>
public AdvancedInGameCall? StreamlineConstants { get; init; }
/// <summary>The same for how the game configures FSR frame generation (<c>ffxConfigure</c>, <c>ffx.framegen.config</c>).</summary>
public AdvancedInGameCall? FsrFrameGeneration { get; init; }
/// <summary>Nothing asked yet.</summary>
public static AdvancedSources Unknown { get; } = new(AdvancedSourceStatus.Unknown, NvapiCode: null, AdvancedSourceStatus.Unknown, AdvancedSourceStatus.Unknown);
}
@@ -45,6 +45,12 @@ public sealed class InGameAdvancedSampler
// FfxApiDispatchUpscaleFlags (ffx_upscale.h), by bit.
private static readonly string[] _flagTokens = ["draw_debug_view", "non_linear_color_srgb", "non_linear_color_pq"];
// FfxApiDispatchFramegenerationFlags (ffx_framegeneration.h), by bit: the vendor's own names, shown as they are.
private static readonly string[] _frameGenerationFlags =
[
"DRAW_DEBUG_TEAR_LINES", "DRAW_DEBUG_RESET_INDICATORS", "DRAW_DEBUG_VIEW", "NO_SWAPCHAIN_CONTEXT_NOTIFY", "DRAW_DEBUG_PACING_LINES",
];
/// <summary>
/// Every word a fact made here may carry for the App to translate (<c>AdvToken_*</c>): the three states of a
/// switch seen over a session, the flags of the dispatch that have a name, and "none". A flag bit nobody named
@@ -55,6 +61,8 @@ public sealed class InGameAdvancedSampler
private InGameAdvanced? _last;
private uint _memoryQueries;
private FactKey _key;
private uint _builtResets;
private FlAdvancedValid _everValid;
/// <summary>The session facts as of the last publication taken; empty until the game made a call they are read from.</summary>
public IReadOnlyList<AdvancedFact> Facts { get; private set; } = [];
@@ -66,6 +74,29 @@ public sealed class InGameAdvancedSampler
public AdvancedInGameStatus Status(bool hooked) =>
!hooked ? AdvancedInGameStatus.NotHooked : SawAnything ? AdvancedInGameStatus.Reading : AdvancedInGameStatus.NothingSeen;
/// <summary>
/// What became of the entries read from one call hooked only for Advanced metrics (0.1.0-beta.43):
/// <paramref name="group"/> is the bit a publication carries once the call was read, <paramref name="hookedIn"/>
/// whether the capture side said its hook was in. Read wins over the hook's bit: a publication is the proof.
/// </summary>
public AdvancedInGameCall Call(FlAdvancedValid group, bool hookedIn) =>
(_everValid & group) != FlAdvancedValid.None ? AdvancedInGameCall.Read : hookedIn ? AdvancedInGameCall.NeverCalled : AdvancedInGameCall.NotHooked;
/// <summary>
/// The session is ending: the facts are brought up to the last publication where they carry a COUNT. A count
/// is not part of what decides a rebuild while the session runs - it would rewrite the session's context every
/// second for a number that only matters at the end - so the one fact that is a count
/// (<c>sl.constants.resets</c>) is as of the last rebuild until this is called.
/// </summary>
public void Conclude()
{
if (_last is not null && Facts.Count != 0 && _last.State.SlResets != _builtResets)
{
Facts = Build(_last);
_builtResets = _last.State.SlResets;
}
}
/// <summary>
/// Takes a publication. Returns the readings it carries when it is one not taken before and it carries any;
/// null otherwise — nothing published, the same publication as last time, or a second in which the game neither
@@ -86,11 +117,13 @@ public sealed class InGameAdvancedSampler
}
SawAnything = true;
_everValid |= s.ValidMask;
FactKey key = FactKey.Of(published);
if (key != _key || Facts.Count == 0)
{
_key = key;
Facts = Build(published);
_builtResets = s.SlResets;
}
var readings = new List<AdvancedReading>(2);
@@ -124,9 +157,128 @@ public sealed class InGameAdvancedSampler
AddFfx(published, facts);
}
if (published.State.ValidMask.HasFlag(FlAdvancedValid.FfxFgConfig))
{
AddFrameGeneration(published, facts);
}
if (published.State.ValidMask.HasFlag(FlAdvancedValid.SlConstants))
{
AddStreamlineConstants(published, facts);
}
return facts;
}
// How the game configures FSR frame generation (ffxConfigure, 0.1.0-beta.43): three switches as seen over the
// session, the flags any configure carried, and the last rectangle it generates in.
private static void AddFrameGeneration(InGameAdvanced published, List<AdvancedFact> facts)
{
ref readonly FlAdvancedState s = ref published.State;
var rows = new List<AdvancedRow>(5);
AddSwitch(rows, "frameGenerationEnabled", s.FfxFgEnabledSeen);
AddSwitch(rows, "allowAsyncWorkloads", s.FfxFgAsyncSeen);
AddSwitch(rows, "onlyPresentGenerated", s.FfxFgOnlyGeneratedSeen);
if (s.FfxFgFlagsSeen != 0)
{
var names = new List<string>(4);
for (int bit = 0; bit < 32; bit++)
{
if ((s.FfxFgFlagsSeen & (1u << bit)) != 0)
{
names.Add(bit < _frameGenerationFlags.Length ? _frameGenerationFlags[bit] : string.Create(CultureInfo.InvariantCulture, $"bit {bit}"));
}
}
rows.Add(new AdvancedRow("flags", string.Join(", ", names)));
}
// left, top, width, height. A rectangle with no area is one the game did not give; four -1 is one the capture
// side could not state (a side that is negative or past 32,767).
int left = s.FfxFgRectAt(0);
int top = s.FfxFgRectAt(1);
int width = s.FfxFgRectAt(2);
int height = s.FfxFgRectAt(3);
if (width > 0 && height > 0 && left >= 0 && top >= 0)
{
rows.Add(new AdvancedRow("generationRect", string.Create(CultureInfo.InvariantCulture, $"{width} × {height} at {left}, {top}")));
}
if (rows.Count > 0)
{
facts.Add(Fact("ffx.framegen.config", AdvancedValue.OfRows(rows)));
}
}
// What the game told Streamline about each frame (slSetConstants, 0.1.0-beta.43), for the first viewport that
// called. FLT_MAX is Streamline's "not set" and never reaches here; a plane at infinity is FSR's convention (D119).
private static void AddStreamlineConstants(InGameAdvanced published, List<AdvancedFact> facts)
{
ref readonly FlAdvancedState s = ref published.State;
var jitter = new List<AdvancedRow>(2);
AddUpTo(jitter, "jitterOffset.x", s.SlJitterMaxXBits);
AddUpTo(jitter, "jitterOffset.y", s.SlJitterMaxYBits);
if (jitter.Count > 0)
{
facts.Add(Fact("sl.constants.jitter", AdvancedValue.OfRows(jitter)));
}
// Bits in the vendor header's order: depthInverted 0, cameraMotionIncluded 1, motionVectors3D 2, reset 3,
// orthographicProjection 4, motionVectorsDilated 5, motionVectorsJittered 6.
var motion = new List<AdvancedRow>(6);
AddNumber(motion, "mvecScale.x", s.SlMvecScaleXBits);
AddNumber(motion, "mvecScale.y", s.SlMvecScaleYBits);
AddSwitch(motion, "cameraMotionIncluded", SwitchOf(s.SlFlagsSeenTrue, s.SlFlagsSeenFalse, 1));
AddSwitch(motion, "motionVectors3D", SwitchOf(s.SlFlagsSeenTrue, s.SlFlagsSeenFalse, 2));
AddSwitch(motion, "motionVectorsDilated", SwitchOf(s.SlFlagsSeenTrue, s.SlFlagsSeenFalse, 5));
AddSwitch(motion, "motionVectorsJittered", SwitchOf(s.SlFlagsSeenTrue, s.SlFlagsSeenFalse, 6));
if (motion.Count > 0)
{
facts.Add(Fact("sl.constants.motion_vectors", AdvancedValue.OfRows(motion)));
}
var depth = new List<AdvancedRow>(3);
AddNumber(depth, "cameraNear", s.SlNearBits);
AddNumber(depth, "cameraFar", s.SlFarBits);
AddSwitch(depth, "depthInverted", SwitchOf(s.SlFlagsSeenTrue, s.SlFlagsSeenFalse, 0));
if (depth.Count > 0)
{
facts.Add(Fact("sl.constants.depth", AdvancedValue.OfRows(depth)));
}
var projection = new List<AdvancedRow>(3);
// A range, lowest to highest - never a series, which would say when the player aimed (D114).
if (Number(s.SlFovMinBits) is double low && Number(s.SlFovMaxBits) is double high)
{
projection.Add(new AdvancedRow("cameraFOV", s.SlFovMinBits == s.SlFovMaxBits
? string.Create(CultureInfo.InvariantCulture, $"{low:0.####} rad ({Degrees(low):0.#}°)")
: string.Create(CultureInfo.InvariantCulture, $"{low:0.####} – {high:0.####} rad ({Degrees(low):0.#}° – {Degrees(high):0.#}°)")));
}
AddNumber(projection, "cameraAspectRatio", s.SlAspectBits);
AddSwitch(projection, "orthographicProjection", SwitchOf(s.SlFlagsSeenTrue, s.SlFlagsSeenFalse, 4));
if (projection.Count > 0)
{
facts.Add(Fact("sl.constants.projection", AdvancedValue.OfRows(projection)));
}
// A count, of the first viewport's calls: 0 is "the game never reset the history", which is a fact.
facts.Add(Fact("sl.constants.resets", AdvancedValue.Of(s.SlResets)));
}
// The two bits a switch seen over a session leaves: bit 0 seen off, bit 1 seen on.
private static uint SwitchOf(uint seenTrue, uint seenFalse, int bit) =>
((seenFalse >> bit) & 1u) | (((seenTrue >> bit) & 1u) << 1);
private static void AddSwitch(List<AdvancedRow> rows, string member, uint seen)
{
string? state = (seen & 3u) switch { 1u => "off", 2u => "on", 3u => "on_and_off", _ => null };
if (state is not null)
{
rows.Add(new AdvancedRow(member, state, state));
}
}
private static void AddDlss(InGameAdvanced published, List<AdvancedFact> facts)
{
ref readonly FlAdvancedState s = ref published.State;
@@ -298,7 +450,14 @@ public sealed class InGameAdvancedSampler
_ => preset.ToString(CultureInfo.InvariantCulture),
};
/// <summary>The fields the facts are made of, and nothing that moves every second: no count, no frame time, no clock.</summary>
private static ulong Pair(uint low, uint high) => low | ((ulong)high << 32);
private static ulong Pair(int low, int high) => Pair(unchecked((uint)low), unchecked((uint)high));
/// <summary>
/// The fields the facts are made of, and nothing that moves every second: no count, no frame time, no clock. The
/// one fact that IS a count - the resets told to Streamline - is brought up to date by <see cref="Conclude"/>.
/// </summary>
[StructLayout(LayoutKind.Auto)]
private readonly record struct FactKey(
FlAdvancedValid Valid,
@@ -319,7 +478,17 @@ public sealed class InGameAdvancedSampler
uint Far,
uint FovMin,
uint FovMax,
uint Flags)
uint Flags,
ulong FrameGenerationSwitches,
uint FrameGenerationFlags,
ulong FrameGenerationRectLow,
ulong FrameGenerationRectHigh,
ulong SlJitter,
ulong SlMvecScale,
ulong SlDepth,
ulong SlFov,
uint SlAspect,
ulong SlFlags)
{
public static FactKey Of(InGameAdvanced published)
{
@@ -331,7 +500,7 @@ public sealed class InGameAdvancedSampler
}
return new FactKey(
s.ValidMask & (FlAdvancedValid.DlssOptions | FlAdvancedValid.FfxUpscale),
s.ValidMask & (FlAdvancedValid.DlssOptions | FlAdvancedValid.FfxUpscale | FlAdvancedValid.FfxFgConfig | FlAdvancedValid.SlConstants),
s.DlssOutputWidth,
s.DlssOutputHeight,
s.DlssPreExposureBits,
@@ -349,7 +518,17 @@ public sealed class InGameAdvancedSampler
s.FfxFarBits,
s.FfxFovMinBits,
s.FfxFovMaxBits,
s.FfxFlagsSeen);
s.FfxFlagsSeen,
s.FfxFgEnabledSeen | ((ulong)s.FfxFgAsyncSeen << 8) | ((ulong)s.FfxFgOnlyGeneratedSeen << 16),
s.FfxFgFlagsSeen,
Pair(s.FfxFgRectAt(0), s.FfxFgRectAt(1)),
Pair(s.FfxFgRectAt(2), s.FfxFgRectAt(3)),
Pair(s.SlJitterMaxXBits, s.SlJitterMaxYBits),
Pair(s.SlMvecScaleXBits, s.SlMvecScaleYBits),
Pair(s.SlNearBits, s.SlFarBits),
Pair(s.SlFovMinBits, s.SlFovMaxBits),
s.SlAspectBits,
Pair(s.SlFlagsSeenTrue, s.SlFlagsSeenFalse));
}
}
}
@@ -374,7 +374,8 @@ public sealed class SessionRecorder : ISessionRecorder
// records Advanced metrics - the same condition the shared reader is held under.
private readonly InGameAdvancedSampler? _inGame = advanced is null ? null : new InGameAdvancedSampler();
private IReadOnlyList<AdvancedReading>? _inGamePending;
private (IReadOnlyList<AdvancedFact> Facts, AdvancedInGameStatus Status) _inGameContext = ([], AdvancedInGameStatus.Unknown);
private (IReadOnlyList<AdvancedFact> Facts, AdvancedInGameStatus Status, AdvancedInGameCall? Streamline, AdvancedInGameCall? FrameGeneration) _inGameContext =
([], AdvancedInGameStatus.Unknown, null, null);
private IReadOnlyList<AdvancedFact> _sessionWithGame = [];
/// <summary>A session that records Advanced metrics asks the Overlay for what the game tells its upscaler (D111).</summary>
@@ -475,12 +476,20 @@ public sealed class SessionRecorder : ISessionRecorder
_sessionFactsRead = Task.Run(() => _sessionFacts = ReadSessionFacts(advanced, target));
}
if (atEnd)
{
// The one fact that is a count is brought up to the last publication (InGameAdvancedSampler.Conclude).
_inGame?.Conclude();
}
AdvancedSnapshot? snapshot = advanced.Latest;
IReadOnlyList<AdvancedFact>? session = _sessionFacts;
IReadOnlyList<AdvancedFact> game = _inGame?.Facts ?? [];
AdvancedInGameStatus status = InGameStatus();
(AdvancedInGameCall? streamline, AdvancedInGameCall? frameGeneration) = InGameCalls();
(IReadOnlyList<AdvancedFact>?, IReadOnlyList<AdvancedSeriesInfo>?, AdvancedSources?, IReadOnlyList<AdvancedFact>?) now = (snapshot?.MachineFacts, snapshot?.Series, snapshot?.Sources, session);
bool sameGame = ReferenceEquals(game, _inGameContext.Facts) && status == _inGameContext.Status;
bool sameGame = ReferenceEquals(game, _inGameContext.Facts) && status == _inGameContext.Status
&& streamline == _inGameContext.Streamline && frameGeneration == _inGameContext.FrameGeneration;
if ((snapshot is null && session is null && game.Count == 0)
|| (sameGame && ReferenceEquals(now.Item1, _context.Machine) && ReferenceEquals(now.Item2, _context.Series) && Equals(now.Item3, _context.Sources) && ReferenceEquals(now.Item4, _context.Session)))
{
@@ -494,12 +503,31 @@ public sealed class SessionRecorder : ISessionRecorder
}
_context = now;
_inGameContext = (game, status);
_inGameContext = (game, status, streamline, frameGeneration);
writer.SetAdvancedContext(new AdvancedSessionData(
snapshot?.MachineFacts ?? [],
_sessionWithGame,
snapshot?.Series ?? [],
(snapshot?.Sources ?? AdvancedSources.Unknown) with { InGame = status }));
(snapshot?.Sources ?? AdvancedSources.Unknown) with { InGame = status, StreamlineConstants = streamline, FsrFrameGeneration = frameGeneration }));
}
/// <summary>
/// What became of the two calls hooked only for Advanced metrics (0.1.0-beta.43), for a session measured
/// inside the game: read, hooked and never called, or not hooked - from the hook families the capture side
/// last published and from what its publications carried. Null for a session not measured inside the game:
/// <see cref="AdvancedInGameStatus.NotHooked"/> already says so.
/// </summary>
private (AdvancedInGameCall? Streamline, AdvancedInGameCall? FrameGeneration) InGameCalls()
{
if (_inGame is null || AttachedAt is null)
{
return (null, null);
}
var hooks = (FlHookFamily)(_last?.WriterState.HooksInstalledMask ?? 0u);
return (
_inGame.Call(FlAdvancedValid.SlConstants, hooks.HasFlag(FlHookFamily.SlConstants)),
_inGame.Call(FlAdvancedValid.FfxFgConfig, hooks.HasFlag(FlHookFamily.FfxConfigure)));
}
/// <summary>
@@ -29,4 +29,10 @@ public enum HookFamilies
/// <summary>The Streamline detour decodes DLSS 5's neural rendering (beta.34, D84).</summary>
SlNeuralRendering = 1 << 12,
/// <summary><c>slSetConstants</c> is hooked (0.1.0-beta.43) - only where Advanced metrics was ever asked for.</summary>
SlConstants = 1 << 13,
/// <summary><c>ffxConfigure</c> is hooked (0.1.0-beta.43) - only where Advanced metrics was ever asked for.</summary>
FfxConfigure = 1 << 14,
}
+20
View File
@@ -280,6 +280,18 @@ public enum FlHookFamily : uint
/// writer that looked for neural rendering is told from one built before it could (<see cref="FlFeatureFlags.SlNeuralRendering"/>).
/// </summary>
SlNeuralRendering = 1u << 12,
/// <summary>
/// <c>slSetConstants</c> is hooked (0.1.0-beta.43, Advanced metrics train B). Only in a process that was asked for
/// Advanced metrics at least once; it tells "hooked, never called" from "not hooked", and entitles no frame field.
/// </summary>
SlConstants = 1u << 13,
/// <summary>
/// <c>ffxConfigure</c> is hooked on every ffx-api module the process loaded (0.1.0-beta.43). Only in a process that
/// was asked for Advanced metrics at least once; it entitles no frame field.
/// </summary>
FfxConfigure = 1u << 14,
}
/// <summary>
@@ -917,6 +929,14 @@ public unsafe struct FlAdvancedState
/// <summary>left, top, width, height.</summary>
public fixed int FfxFgRect[4];
/// <summary>One side of <see cref="FfxFgRect"/>: 0 left, 1 top, 2 width, 3 height. Four -1 is a rectangle the capture side could not state.</summary>
public readonly int FfxFgRectAt(int side)
{
ArgumentOutOfRangeException.ThrowIfNegative(side);
ArgumentOutOfRangeException.ThrowIfGreaterThan(side, 3);
return FfxFgRect[side];
}
/// <summary>Must be zero.</summary>
public fixed uint ReservedFfx[2];
@@ -277,12 +277,26 @@ enum class Collected : std::uint8_t {
// kProcessUnreadable -- so it is never a pass. ACCESS_DENIED (a protected process) is kFailed and is never retried.
// Every other consumer of Collected treats anything but kOk as a failure.
kRetry,
// EnumerateModules ONLY (owner decision D123, 2026-11-12): the module list CHANGED WHILE IT WAS READ -- a module
// that was in the list could not be named a moment later, because the process unloaded it, or was still loading
// it, between the two calls. Not a finding and not a protected process: a game at its launch loads and unloads
// modules for seconds. Until D123 this was kIncomplete and refused at once, which ended real sessions as a safety
// unhook with no frame recorded (five in the Agent's logs of one PC in a week: Phantom Blade Zero, Crown & Coin,
// Cyberpunk 2077). The module check reads the whole scan set again, up to kMaxUnsettledRereads times, each
// after kScanRetryPauseMs; a list that is still unsettled on the last read refuses as kModuleScanFailed -- so it
// is never a pass, and nothing that was not read whole is ever allowed. A list too long for the buffer stays
// kIncomplete and is not read again: a second read would be as long.
kUnsettled,
};
// How long the module check waits before its one re-read (D48). A process that was still loading has its modules
// How long the module check waits before a re-read (D48, D123). A process that was still loading has its modules
// well within it; one that has exited is out of the fresh snapshot.
inline constexpr std::uint32_t kScanRetryPauseMs = 250;
// How many times the module check reads the scan set again for a list that changed under the read (D123): three, so
// four reads in all and at most 750 ms of pauses. D48's re-read for a process still being created stays ONE.
inline constexpr std::uint32_t kMaxUnsettledRereads = 3;
// Callbacks receive (context, name) for each item found. Returning false stops
// enumeration early — used when a match has already been found.
using NameSink = bool (*)(void* ctx, const char* name);
@@ -391,9 +391,12 @@ Verdict LoadRules(const Sources& s, Rules& rules) noexcept {
// One pass of check 1 over a fresh scan set. `allowRetry` (D48): on the first pass a member that is still being
// created or already gone (Collected::kRetry) is noted in `retryWanted` and the pass goes on -- a finding in any other
// member still refuses at once; on the second pass the same answer refuses as kProcessUnreadable, exactly as an
// unreadable member always has. Anything but the four answers refuses too: no answer is a pass by omission.
// unreadable member always has. `allowUnsettled` (D123): the same for a member whose module list changed while it
// was read (Collected::kUnsettled), noted in `unsettledWanted`; when it is not allowed -- the last read -- the same
// answer refuses as kModuleScanFailed. Anything but the answers named refuses too: no answer is a pass by omission.
Verdict ScanModulesOnce(const Sources& s, const Rules& rules, std::uint32_t targetPid, const Tolerance* tolerance,
ToleratedFinding& finding, bool allowRetry, bool& retryWanted) noexcept {
ToleratedFinding& finding, bool allowRetry, bool& retryWanted, bool allowUnsettled,
bool& unsettledWanted) noexcept {
ScanSet set;
if (s.EnumerateScanSet(targetPid, &ScanSetSink, &set) != Collected::kOk || set.overflowed || set.count == 0) {
// An empty scan set is not "nothing to scan" — it is "we do not know
@@ -427,6 +430,16 @@ Verdict ScanModulesOnce(const Sources& s, const Rules& rules, std::uint32_t targ
if (c == Collected::kFailed || c == Collected::kRetry) {
return Refuse(Reason::kProcessUnreadable, nullptr, "a process in the scan set could not be read");
}
// D123: a list that changed under the read is read again from a fresh scan set -- AFTER the finding check
// above, so a blocklisted module among those that were read still refuses at once. The members read whole
// in this pass are read again too: the pass that allows is one in which every member was read whole.
if (c == Collected::kUnsettled) {
if (allowUnsettled) {
unsettledWanted = true;
continue;
}
return Refuse(Reason::kModuleScanFailed, nullptr, "a module list kept changing while it was read");
}
if (c != Collected::kOk) {
return Refuse(Reason::kModuleScanFailed, nullptr, "a module list came back incomplete");
}
@@ -464,24 +477,40 @@ Verdict ScanModulesOnce(const Sources& s, const Rules& rules, std::uint32_t targ
// whole. A member still unreadable then refuses as before; one that is gone is not in the new set; a target that is
// gone makes the new set unavailable, which refuses. The re-read can only turn a refusal of "could not read" into a
// full read -- never into a pass that skipped anything.
//
// D123 (owner decision, 2026-11-12): a member whose module list CHANGED WHILE IT WAS READ -- a game at its launch,
// loading and unloading -- refused the session the same way, and five real sessions on one PC ended as a safety
// unhook with no frame recorded. Such a list is read again the same way, up to kMaxUnsettledRereads times; one that
// has not settled by the last read refuses as kModuleScanFailed. D48's re-read stays ONE for the whole check: a
// member still being created on a second read refuses, whichever read first saw it. Every read is of the whole
// scan set, and the read that allows is one in which every member was read whole and none held a finding.
Verdict CheckModules(const Sources& s, const Rules& rules, std::uint32_t targetPid, const Tolerance* tolerance,
ToleratedFinding& finding) noexcept {
if (s.EnumerateScanSet == nullptr || s.EnumerateModules == nullptr) {
return Refuse(Reason::kProcessTreeUnavailable, nullptr, "no process source");
}
bool retryWanted = false;
const Verdict first = ScanModulesOnce(s, rules, targetPid, tolerance, finding, true, retryWanted);
if (!first.Allowed() || !retryWanted) {
return first;
bool retryUsed = false; // D48's one re-read, for the whole check
std::uint32_t unsettledRereads = 0; // D123's, up to kMaxUnsettledRereads
for (;;) {
bool retryWanted = false;
bool unsettledWanted = false;
const Verdict pass = ScanModulesOnce(s, rules, targetPid, tolerance, finding, !retryUsed, retryWanted,
unsettledRereads < kMaxUnsettledRereads, unsettledWanted);
// A refusal is final, and so is a pass in which every member was read whole. A `wanted` flag is only ever
// set where the pass was allowed to ask, so this cannot loop past either bound.
if (!pass.Allowed() || (!retryWanted && !unsettledWanted)) {
return pass;
}
retryUsed = retryUsed || retryWanted;
if (unsettledWanted) {
++unsettledRereads;
}
if (s.Pause != nullptr) {
s.Pause(kScanRetryPauseMs);
}
finding = ToleratedFinding{}; // collected again from the pass that decides
}
if (s.Pause != nullptr) {
s.Pause(kScanRetryPauseMs);
}
finding = ToleratedFinding{}; // collected again from the pass that decides
bool again = false;
return ScanModulesOnce(s, rules, targetPid, tolerance, finding, false, again);
}
// Check 2 — machine-wide drivers. Independent of process identity, which is
@@ -893,8 +922,10 @@ PresentationRuntime FindPresentationRuntime(const Sources& s, std::uint32_t pid)
}
RuntimeProbe p;
const Collected c = s.EnumerateModules(pid, &RuntimeSinkFn, &p);
if (c == Collected::kFailed || c == Collected::kRetry) {
return PresentationRuntime::kNone; // still in its loader, or unreadable -- the full scan refuses the latter
if (c == Collected::kFailed || c == Collected::kRetry || c == Collected::kUnsettled) {
// Still in its loader, a list that moved under the read (D123: half a list could miss vulkan-1.dll and send
// the Overlay into a Vulkan title), or unreadable -- the full scan refuses the last. The poll asks again.
return PresentationRuntime::kNone;
}
if (p.vk) {
return PresentationRuntime::kVulkan;
@@ -119,7 +119,11 @@ Collected EnumerateModulesImpl(std::uint32_t pid, ModuleSink sink, void* ctx) no
char name[MAX_PATH]{};
if (GetModuleBaseNameA(h, mods[i], name, MAX_PATH) == 0) {
CloseHandle(h);
return Collected::kIncomplete; // a module we could not name is one we could not check
// A module we could not name is one we could not check -- and it WAS in the list a moment ago, so the
// list moved under the read (unloaded, or its loader entry not yet whole). The module check reads the
// scan set again a bounded number of times and refuses if it never settles (D123); until then this was
// kIncomplete, an immediate refusal.
return Collected::kUnsettled;
}
// The load path, for §S22(b)'s ownership question. Failing to get it is
@@ -45,6 +45,7 @@
#include <sl.h>
// After sl.h, as fl_sl_inputs.h explains: sl_dlss.h has no includes of its own.
#include <ffx_api.h>
#include <ffx_framegeneration.h>
#include <ffx_upscale.h>
#include <sl_dlss.h>
@@ -162,6 +163,31 @@ struct Accumulators {
std::atomic<uint64_t> ffxMemoryAliasableBytes{0u};
std::atomic<uint32_t> ffxMemoryQueries{0u};
std::atomic<uint32_t> ffxMemoryOwner{0u}; // leaf + 1 of the module whose answered queries are counted
// ffxConfigure with a frame-generation descriptor (0.1.0-beta.43)
std::atomic<uint32_t> ffxFgOwner{0u}; // leaf + 1 of the module whose configures are counted
std::atomic<uint32_t> ffxFgConfigures{0u};
std::atomic<uint32_t> ffxFgEnabledSeen{0u}; // bit 0: seen off; bit 1: seen on
std::atomic<uint32_t> ffxFgAsyncSeen{0u}; // the same two bits
std::atomic<uint32_t> ffxFgOnlyGeneratedSeen{0u}; // the same two bits
std::atomic<uint32_t> ffxFgFlagsSeen{0u};
std::atomic<uint64_t> ffxFgRect{0u}; // PackRect: the last rectangle, in ONE word so it is never half of two
// sl::Constants (0.1.0-beta.43), summarised - from the first viewport seen; the calls count every viewport
std::atomic<uint64_t> slViewport{0u}; // that viewport's id + 1; 0 = none yet
std::atomic<uint32_t> slConstantsCalls{0u};
std::atomic<uint32_t> slResets{0u};
std::atomic<uint32_t> slJitterMaxXBits{FL_ADV_FLOAT_NONE};
std::atomic<uint32_t> slJitterMaxYBits{FL_ADV_FLOAT_NONE};
std::atomic<uint32_t> slMvecScaleXBits{FL_ADV_FLOAT_NONE};
std::atomic<uint32_t> slMvecScaleYBits{FL_ADV_FLOAT_NONE};
std::atomic<uint32_t> slNearBits{FL_ADV_FLOAT_NONE};
std::atomic<uint32_t> slFarBits{FL_ADV_FLOAT_NONE};
std::atomic<uint32_t> slFovMinBits{FL_ADV_FLOAT_NONE};
std::atomic<uint32_t> slFovMaxBits{FL_ADV_FLOAT_NONE};
std::atomic<uint32_t> slAspectBits{FL_ADV_FLOAT_NONE};
std::atomic<uint32_t> slFlagsSeenTrue{0u};
std::atomic<uint32_t> slFlagsSeenFalse{0u};
};
// Whether `leaf` is the module whose calls a summary counts: the first one seen, and
@@ -307,6 +333,134 @@ inline void ObserveFfxMemoryQuery(uint32_t leaf, const ffxQueryDescHeader* desc,
}
}
// A rectangle in one 64-bit word, sixteen bits a side: left, top, width, height from the lowest. The detour stores
// it with one store and the watchdog reads it with one load, so a publication never carries the left edge of one
// rectangle beside the width of the next. A side that is negative or does not fit in fifteen bits makes the whole
// word kRectUnfit, which Publish writes as four -1: a rectangle nobody can state rather than a clipped one.
inline constexpr uint64_t kRectUnfit = 0xFFFFFFFFFFFFFFFFull;
inline uint64_t PackRect(int32_t left, int32_t top, int32_t width, int32_t height) noexcept {
const auto fits = [](int32_t v) noexcept { return v >= 0 && v <= 0x7FFF; };
if (!fits(left) || !fits(top) || !fits(width) || !fits(height)) {
return kRectUnfit;
}
return static_cast<uint64_t>(left) | (static_cast<uint64_t>(top) << 16) | (static_cast<uint64_t>(width) << 32) |
(static_cast<uint64_t>(height) << 48);
}
// How the game configures FSR frame generation (ffxConfigure, 0.1.0-beta.43). Read only when the header's type is
// the frame-generation configuration -- a key-value pair, a distortion field or the camera info arriving through the
// same call is passed over with nothing but its type looked at.
//
// WHAT IS READ: whether generation is on, whether it may run asynchronously, the flags, whether only generated
// frames are presented, and the rectangle generated in. WHAT IS NOT, EVER: the swapchain, the two callbacks and
// their contexts, the HUD-less resource and the frame id that sit in the same descriptor.
//
// ONE MODULE'S CONFIGURES ARE COUNTED (Owns), with a slot of its own: behind a loader the same call reaches the
// loader and the leaf, and a title's upscale may be owned by another module than its frame generation.
inline void ObserveFfxConfigure(uint32_t leaf, const ffxConfigureDescHeader* desc, Accumulators& a) noexcept {
if (desc == nullptr || desc->type != FFX_API_CONFIGURE_DESC_TYPE_FRAMEGENERATION) {
return;
}
if (!Owns(a.ffxFgOwner, leaf)) {
return;
}
const auto& g = *reinterpret_cast<const ffxConfigureDescFrameGeneration*>(desc);
a.ffxFgConfigures.fetch_add(1u, std::memory_order_relaxed);
NoteBits(a.ffxFgEnabledSeen, ByteIsSet(g.frameGenerationEnabled) ? 2u : 1u);
NoteBits(a.ffxFgAsyncSeen, ByteIsSet(g.allowAsyncWorkloads) ? 2u : 1u);
NoteBits(a.ffxFgOnlyGeneratedSeen, ByteIsSet(g.onlyPresentGenerated) ? 2u : 1u);
if (g.flags != 0u) {
NoteBits(a.ffxFgFlagsSeen, g.flags);
}
a.ffxFgRect.store(
PackRect(g.generationRect.left, g.generationRect.top, g.generationRect.width, g.generationRect.height),
std::memory_order_relaxed);
NoteBits(a.validMask, FL_ADV_VALID_FFX_FG_CONFIG);
}
// One sl::Boolean of sl::Constants into the two "seen" words: true sets its bit in `seenTrue`, false in `seenFalse`,
// the third state ("invalid": the game set nothing) in neither.
inline void NoteSlBoolean(sl::Boolean value, uint32_t bit, uint32_t& seenTrue, uint32_t& seenFalse) noexcept {
if (value == sl::Boolean::eTrue) {
seenTrue |= bit;
} else if (value == sl::Boolean::eFalse) {
seenFalse |= bit;
}
}
// What the game told Streamline about a frame (slSetConstants, 0.1.0-beta.43). The caller has matched the struct's
// GUID and found its version at least 1, on THIS call (fl_sl_inputs.h IsReadable): every member read below is one
// version 1 carries (17_HOOK_ENGINE "Which struct version carries which field").
//
// WHAT IS READ: the jitter, the motion-vector scale, the two depth planes, the field of view, the aspect ratio and
// the seven Booleans. WHAT IS NOT, EVER: the five matrices that precede them and the pinhole offset, the camera's
// position and its three axes that sit between the scale and the planes (rule 4). Nothing here names them, and
// tools/overlay-fields-check.ps1 fails the build if anything in the code loaded into a game does.
//
// THE SUMMARIES ARE THE FIRST VIEWPORT'S. A title with two viewports -- a scene and a picture-in-picture, a
// split screen -- sets constants for each every frame; "the last value seen" across them would flip twice a frame
// and a range would span two cameras. The first viewport that calls is the one summarised, for the life of the
// process. The call count is of every viewport: it says how often the game called.
//
// FLT_MAX IS "NOT SET" HERE (Streamline's INVALID_FLOAT) and is kept nowhere: the plane at infinity of D119 is
// FidelityFX's convention and stays on that route.
inline void ObserveSlConstants(const sl::Constants& k, uint32_t viewport, Accumulators& a) noexcept {
a.slConstantsCalls.fetch_add(1u, std::memory_order_relaxed);
const uint64_t me = static_cast<uint64_t>(viewport) + 1u;
uint64_t owner = a.slViewport.load(std::memory_order_relaxed);
if (owner == 0u && a.slViewport.compare_exchange_strong(owner, me, std::memory_order_relaxed)) {
owner = me;
}
if (owner != me) {
return;
}
if (Usable(k.jitterOffset.x) && Usable(k.jitterOffset.y)) {
KeepMax(a.slJitterMaxXBits, Magnitude(k.jitterOffset.x));
KeepMax(a.slJitterMaxYBits, Magnitude(k.jitterOffset.y));
}
if (Usable(k.mvecScale.x) && Usable(k.mvecScale.y)) {
a.slMvecScaleXBits.store(std::bit_cast<uint32_t>(k.mvecScale.x), std::memory_order_relaxed);
a.slMvecScaleYBits.store(std::bit_cast<uint32_t>(k.mvecScale.y), std::memory_order_relaxed);
}
if (Usable(k.cameraNear)) {
a.slNearBits.store(std::bit_cast<uint32_t>(k.cameraNear), std::memory_order_relaxed);
}
if (Usable(k.cameraFar)) {
a.slFarBits.store(std::bit_cast<uint32_t>(k.cameraFar), std::memory_order_relaxed);
}
// A range, lowest to highest, never a series (D114).
if (Usable(k.cameraFOV) && k.cameraFOV > 0.0f) {
KeepMin(a.slFovMinBits, k.cameraFOV);
KeepMax(a.slFovMaxBits, k.cameraFOV);
}
if (Usable(k.cameraAspectRatio) && k.cameraAspectRatio > 0.0f) {
a.slAspectBits.store(std::bit_cast<uint32_t>(k.cameraAspectRatio), std::memory_order_relaxed);
}
// One bit per Boolean, in the header's order (FlAdvancedState::slFlagsSeenTrue).
uint32_t seenTrue = 0u;
uint32_t seenFalse = 0u;
NoteSlBoolean(k.depthInverted, 1u << 0, seenTrue, seenFalse);
NoteSlBoolean(k.cameraMotionIncluded, 1u << 1, seenTrue, seenFalse);
NoteSlBoolean(k.motionVectors3D, 1u << 2, seenTrue, seenFalse);
NoteSlBoolean(k.reset, 1u << 3, seenTrue, seenFalse);
NoteSlBoolean(k.orthographicProjection, 1u << 4, seenTrue, seenFalse);
NoteSlBoolean(k.motionVectorsDilated, 1u << 5, seenTrue, seenFalse);
NoteSlBoolean(k.motionVectorsJittered, 1u << 6, seenTrue, seenFalse);
NoteBits(a.slFlagsSeenTrue, seenTrue);
NoteBits(a.slFlagsSeenFalse, seenFalse);
if ((seenTrue & (1u << 3)) != 0u) {
a.slResets.fetch_add(1u, std::memory_order_relaxed);
}
NoteBits(a.validMask, FL_ADV_VALID_SL_CONSTANTS);
}
// A NEW REQUEST: the summaries start afresh, so a session's ranges, masks and
// counts are its own and not those of the session before it in the same game.
// THE WATCHDOG'S. A detour running beside it loses nothing that matters: what it
@@ -343,6 +497,26 @@ inline void Reset(Accumulators& a) noexcept {
a.ffxMemoryTotalBytes.store(0u, relaxed);
a.ffxMemoryAliasableBytes.store(0u, relaxed);
a.ffxMemoryQueries.store(0u, relaxed);
a.ffxFgConfigures.store(0u, relaxed);
a.ffxFgEnabledSeen.store(0u, relaxed);
a.ffxFgAsyncSeen.store(0u, relaxed);
a.ffxFgOnlyGeneratedSeen.store(0u, relaxed);
a.ffxFgFlagsSeen.store(0u, relaxed);
a.ffxFgRect.store(0u, relaxed);
// Which viewport is summarised stays, as the owners do: a fact about the process.
a.slConstantsCalls.store(0u, relaxed);
a.slResets.store(0u, relaxed);
a.slJitterMaxXBits.store(FL_ADV_FLOAT_NONE, relaxed);
a.slJitterMaxYBits.store(FL_ADV_FLOAT_NONE, relaxed);
a.slMvecScaleXBits.store(FL_ADV_FLOAT_NONE, relaxed);
a.slMvecScaleYBits.store(FL_ADV_FLOAT_NONE, relaxed);
a.slNearBits.store(FL_ADV_FLOAT_NONE, relaxed);
a.slFarBits.store(FL_ADV_FLOAT_NONE, relaxed);
a.slFovMinBits.store(FL_ADV_FLOAT_NONE, relaxed);
a.slFovMaxBits.store(FL_ADV_FLOAT_NONE, relaxed);
a.slAspectBits.store(FL_ADV_FLOAT_NONE, relaxed);
a.slFlagsSeenTrue.store(0u, relaxed);
a.slFlagsSeenFalse.store(0u, relaxed);
}
// Copies the accumulators into region 5, under the request they answer. THE
@@ -410,6 +584,31 @@ inline void Publish(Accumulators& a, FlAdvancedState* region, uint32_t request,
put64(region->ffxMemoryAliasableBytes, a.ffxMemoryAliasableBytes.load(relaxed));
put32(region->ffxMemoryQueries, a.ffxMemoryQueries.load(relaxed));
put32(region->ffxFgConfigures, a.ffxFgConfigures.load(relaxed));
put32(region->ffxFgEnabledSeen, a.ffxFgEnabledSeen.load(relaxed));
put32(region->ffxFgAsyncSeen, a.ffxFgAsyncSeen.load(relaxed));
put32(region->ffxFgOnlyGeneratedSeen, a.ffxFgOnlyGeneratedSeen.load(relaxed));
put32(region->ffxFgFlagsSeen, a.ffxFgFlagsSeen.load(relaxed));
const uint64_t rect = a.ffxFgRect.load(relaxed);
for (uint32_t i = 0; i < 4u; ++i) {
const auto side = rect == kRectUnfit ? int32_t{-1} : static_cast<int32_t>((rect >> (16u * i)) & 0xFFFFu);
std::atomic_ref<int32_t>{region->ffxFgRect[i]}.store(side, relaxed);
}
put32(region->slConstantsCalls, a.slConstantsCalls.load(relaxed));
put32(region->slResets, a.slResets.load(relaxed));
put32(region->slJitterMaxXBits, a.slJitterMaxXBits.load(relaxed));
put32(region->slJitterMaxYBits, a.slJitterMaxYBits.load(relaxed));
put32(region->slMvecScaleXBits, a.slMvecScaleXBits.load(relaxed));
put32(region->slMvecScaleYBits, a.slMvecScaleYBits.load(relaxed));
put32(region->slNearBits, a.slNearBits.load(relaxed));
put32(region->slFarBits, a.slFarBits.load(relaxed));
put32(region->slFovMinBits, a.slFovMinBits.load(relaxed));
put32(region->slFovMaxBits, a.slFovMaxBits.load(relaxed));
put32(region->slAspectBits, a.slAspectBits.load(relaxed));
put32(region->slFlagsSeenTrue, a.slFlagsSeenTrue.load(relaxed));
put32(region->slFlagsSeenFalse, a.slFlagsSeenFalse.load(relaxed));
std::atomic_ref<uint32_t> samples{region->samples};
samples.store(samples.load(relaxed) + 1u, relaxed);
seq.store(odd + 1u, std::memory_order_release);
@@ -124,7 +124,8 @@ inline constexpr uint32_t kFamiliesEvaluateFeatureDoesNotImplement =
static_cast<uint32_t>(fl::FL_HOOK_RT_AS_BUILD) | static_cast<uint32_t>(fl::FL_HOOK_RT_PSO) |
static_cast<uint32_t>(fl::FL_HOOK_PSO) | static_cast<uint32_t>(fl::FL_HOOK_COLOR_SPACE) |
static_cast<uint32_t>(fl::FL_HOOK_REFLEX) | static_cast<uint32_t>(fl::FL_HOOK_VRAM) |
static_cast<uint32_t>(fl::FL_HOOK_UPSCALER_QUALITY);
static_cast<uint32_t>(fl::FL_HOOK_UPSCALER_QUALITY) | static_cast<uint32_t>(fl::FL_HOOK_SL_CONSTANTS) |
static_cast<uint32_t>(fl::FL_HOOK_FFX_CONFIGURE);
static_assert((kFamilyEvaluateFeature & kFamiliesEvaluateFeatureDoesNotImplement) == 0u,
"the slEvaluateFeature row claims a family its detour does not implement -- hookinventory-check "
@@ -183,6 +184,13 @@ static_assert((kFamilyEvaluateFeature & static_cast<uint32_t>(fl::FL_HOOK_FG_EVA
// prints against each other (frames/upscale-drained) and the K = 1 control in the
// fixtures are what would show a loader that re-entered a leaf's export: 2x on both.
//
// AND MEASURED A THIRD TIME, 2026-11-12, WITH A THIRD ANSWER: Cyberpunk 2077's loader 2.3.0 DOES hand a dispatch
// on to the leaf's export -- its frame-generation dispatch types are logged on the loader and on the
// frame-generation leaf. So "the leaves stay silent behind the loader" is a fact about the loader of September's
// three titles (1.0.2), not about loaders. The rows stand as they are -- whatever module the game calls -- and
// what a dispatch seen twice may count is decided where it is counted: PREPARE by its frame number, an UPSCALE at
// the first source that saw one (dllmain.cpp g_ffxUpscaleOwner, owner decision D125).
//
// The effect-DLL split is NOT a guess about the vendor's internals: the FidelityFX
// SDK's own getting-started text says the loader "only manages the loading of
// effect type DLLs" and is "interface- and behavior-compatible with
@@ -200,7 +208,8 @@ inline constexpr uint32_t kFamiliesFfxDispatchDoesNotImplement =
static_cast<uint32_t>(fl::FL_HOOK_RT_AS_BUILD) | static_cast<uint32_t>(fl::FL_HOOK_RT_PSO) |
static_cast<uint32_t>(fl::FL_HOOK_PSO) | static_cast<uint32_t>(fl::FL_HOOK_COLOR_SPACE) |
static_cast<uint32_t>(fl::FL_HOOK_REFLEX) | static_cast<uint32_t>(fl::FL_HOOK_VRAM) |
static_cast<uint32_t>(fl::FL_HOOK_UPSCALER_QUALITY) | static_cast<uint32_t>(fl::FL_HOOK_SL_NEURAL_RENDERING);
static_cast<uint32_t>(fl::FL_HOOK_UPSCALER_QUALITY) | static_cast<uint32_t>(fl::FL_HOOK_SL_NEURAL_RENDERING) |
static_cast<uint32_t>(fl::FL_HOOK_SL_CONSTANTS) | static_cast<uint32_t>(fl::FL_HOOK_FFX_CONFIGURE);
static_assert((kFamilyFfxDispatch & kFamiliesFfxDispatchDoesNotImplement) == 0u,
"the ffxDispatch rows claim a family their detour does not implement -- hookinventory-check reads "
@@ -271,6 +280,50 @@ static_assert(kFamilyFfxQuery != kFamilyFfxDispatch && kFamilyFfxQuery != kFamil
static_assert((kFamilyFfxDispatch & kFamilyFfxQuery) == 0u,
"the dispatch rows must not claim the query's bit: they do not hook ffxQuery");
// --- Streamline: slSetConstants (0.1.0-beta.43, Advanced metrics train B, owner decisions D111-D116) ---
//
// WHAT THE GAME TELLS STREAMLINE ABOUT A FRAME, once per frame and viewport: the jitter, the motion-vector scale,
// the depth range, the field of view, the aspect ratio and seven Booleans -- beside five matrices and the camera's
// position and axes, WHICH ARE NEVER READ (rule 4; tools/overlay-fields-check.ps1 refuses their names anywhere in
// the code loaded into a game). One exporter, sl.interposer.dll, like the other Streamline rows.
//
// THE ONE ROW THAT IS NOT INSTALLED UNLESS ASKED FOR. Every other row is patched when its module appears; this one
// only in a process the Agent has asked for Advanced metrics at least once (D111: with the option off, nothing more
// is read -- and nothing more is patched). dllmain's installer checks that BEFORE it resolves the symbol, because
// resolving takes a reference on the module. Once in, the patch stays for the life of the process and the detour
// forwards without looking while the request is off.
//
// ITS OWN BIT. It entitles no measured field of a frame record; the bit says the hook is in, so that a session can
// tell "hooked, and the game never called it" from "not hooked".
inline constexpr uint32_t kFamilySlConstants = static_cast<uint32_t>(fl::FL_HOOK_SL_CONSTANTS);
static_assert(kFamilySlConstants != kFamilyEvaluateFeature && kFamilySlConstants != kFamilyFfxDispatch &&
kFamilySlConstants != kFamilyFfxQuery &&
kFamilySlConstants != static_cast<uint32_t>(fl::FL_HOOK_UPSCALER_PARAMS) &&
kFamilySlConstants != static_cast<uint32_t>(fl::FL_HOOK_FG_EVALUATIONS),
"InstallByFamily binds a row by EQUALITY on this value -- a collision would hand slSetConstants' "
"detour to another export, or another's to it");
// --- AMD FidelityFX: ffxConfigure on the same four modules (0.1.0-beta.43, Advanced metrics train B) ---
//
// HOW THE GAME CONFIGURES FRAME GENERATION: a title calls ffxConfigure with a frame-generation descriptor, usually
// every frame, saying whether generation is on, whether it may run asynchronously, its flags, whether only generated
// frames are presented, and the rectangle it generates in. Those five are read; the swapchain, the two callbacks
// and their contexts, the HUD-less resource and the frame id in the same descriptor never are. Every other
// configure type -- key-value pairs, the distortion field, the camera info -- is passed over with only its header's
// type read. The rows are the four modules ffxDispatch is hooked on, for the reason those rows give.
//
// INSTALLED ONLY WHERE ASKED FOR, like slSetConstants above (D111), and published when whole, like the other two
// ffx families. One call reaches two hooked modules behind a loader that forwards to the leaf's export (Cyberpunk
// 2077's 2.3.0) and behind the fixture's loader, which has always forwarded ffxConfigure that way: the reads are
// counted at the first module that saw a frame-generation configure (fl_adv_fields.h).
inline constexpr uint32_t kFamilyFfxConfigure = static_cast<uint32_t>(fl::FL_HOOK_FFX_CONFIGURE);
static_assert(kFamilyFfxConfigure != kFamilyEvaluateFeature && kFamilyFfxConfigure != kFamilyFfxDispatch &&
kFamilyFfxConfigure != kFamilyFfxQuery && kFamilyFfxConfigure != kFamilySlConstants &&
kFamilyFfxConfigure != static_cast<uint32_t>(fl::FL_HOOK_UPSCALER_PARAMS) &&
kFamilyFfxConfigure != static_cast<uint32_t>(fl::FL_HOOK_FG_EVALUATIONS),
"InstallByFamily binds a row by EQUALITY on this value -- a collision would hand ffxConfigure's detour "
"to a dispatch or a query export, whose descriptors it does not share");
// The leaves, in the order dllmain's per-leaf trampoline and latch arrays are indexed.
enum FfxLeaf : uint32_t {
kFfxLeafMonolith = 0, // amd_fidelityfx_dx12.dll -- SDK 1.1.x, FSR 3.1 only
@@ -366,6 +419,7 @@ inline int FfxLeafOf(const wchar_t* moduleName) noexcept {
X(L"sl.interposer.dll", "slSetTag", fl::FL_HOOK_UPSCALER_PARAMS) \
X(L"sl.interposer.dll", "slSetTagForFrame", fl::FL_HOOK_UPSCALER_PARAMS) \
X(L"sl.interposer.dll", "slGetNewFrameToken", fl::FL_HOOK_FG_EVALUATIONS) \
X(L"sl.interposer.dll", "slSetConstants", fl::inventory::kFamilySlConstants) \
X(L"amd_fidelityfx_dx12.dll", "ffxDispatch", fl::inventory::kFamilyFfxDispatch) \
X(L"amd_fidelityfx_upscaler_dx12.dll", "ffxDispatch", fl::inventory::kFamilyFfxDispatch) \
X(L"amd_fidelityfx_framegeneration_dx12.dll", "ffxDispatch", fl::inventory::kFamilyFfxDispatch) \
@@ -374,6 +428,10 @@ inline int FfxLeafOf(const wchar_t* moduleName) noexcept {
X(L"amd_fidelityfx_upscaler_dx12.dll", "ffxQuery", fl::inventory::kFamilyFfxQuery) \
X(L"amd_fidelityfx_framegeneration_dx12.dll", "ffxQuery", fl::inventory::kFamilyFfxQuery) \
X(L"amd_fidelityfx_loader_dx12.dll", "ffxQuery", fl::inventory::kFamilyFfxQuery) \
X(L"amd_fidelityfx_dx12.dll", "ffxConfigure", fl::inventory::kFamilyFfxConfigure) \
X(L"amd_fidelityfx_upscaler_dx12.dll", "ffxConfigure", fl::inventory::kFamilyFfxConfigure) \
X(L"amd_fidelityfx_framegeneration_dx12.dll", "ffxConfigure", fl::inventory::kFamilyFfxConfigure) \
X(L"amd_fidelityfx_loader_dx12.dll", "ffxConfigure", fl::inventory::kFamilyFfxConfigure) \
X(L"ffx_fsr3_x64.dll", "ffxFsr3ContextDispatchUpscale", fl::inventory::kFamilyFsr3Host)
// How many rows the table has: one inline patch each at most. dllmain's patch registry is sized against it, so a
@@ -381,7 +439,7 @@ inline int FfxLeafOf(const wchar_t* moduleName) noexcept {
#define FL_COUNT_ROW(mod, sym, family) +1u
inline constexpr uint32_t kRowCount = 0u FL_HOOK_INVENTORY(FL_COUNT_ROW);
#undef FL_COUNT_ROW
static_assert(kRowCount == 13u, "a row was added or removed: say so here, and in 17_HOOK_ENGINE §Hook inventory");
static_assert(kRowCount == 18u, "a row was added or removed: say so here, and in 17_HOOK_ENGINE §Hook inventory");
// A row's "module!symbol", for the native log, built at compile time from the row's own two spellings -- so an
// install line names the module it patched, and no second list of names exists to drift from the table
@@ -549,6 +607,38 @@ static_assert(EveryFfxQueryRowIsALeaf(),
static_assert(!FfxQueryRowExistsFor(kModuleFfxFsr3Host),
"the FSR 3.0 host has its own query API, not ffxQuery; a row claiming one would resolve nothing");
// The ffxConfigure rows, bound to the leaf table the same way (0.1.0-beta.43).
inline constexpr const char* kSymbolFfxConfigure = "ffxConfigure";
constexpr bool FfxConfigureRowExistsFor(const wchar_t* moduleName) noexcept {
#define FL_FFX_CONFIGURE_ROW_FOR(mod, sym, family) \
if (SameW(mod, moduleName) && SameA(sym, kSymbolFfxConfigure)) { \
return true; \
}
FL_HOOK_INVENTORY(FL_FFX_CONFIGURE_ROW_FOR)
#undef FL_FFX_CONFIGURE_ROW_FOR
return false;
}
constexpr bool EveryFfxConfigureRowIsALeaf() noexcept {
#define FL_FFX_CONFIGURE_ROW_IS_LEAF(mod, sym, family) \
if (SameA(sym, kSymbolFfxConfigure) && FfxLeafOfExact(mod) < 0) { \
return false; \
}
FL_HOOK_INVENTORY(FL_FFX_CONFIGURE_ROW_IS_LEAF)
#undef FL_FFX_CONFIGURE_ROW_IS_LEAF
return true;
}
static_assert(FfxConfigureRowExistsFor(kFfxLeafModules[kFfxLeafMonolith]) &&
FfxConfigureRowExistsFor(kFfxLeafModules[kFfxLeafUpscaler]) &&
FfxConfigureRowExistsFor(kFfxLeafModules[kFfxLeafFrameGeneration]) &&
FfxConfigureRowExistsFor(kFfxLeafModules[kFfxLeafLoader]),
"every ffx leaf needs its ffxConfigure row, spelled identically -- the configure reaches whatever module "
"the game calls, as the dispatch does");
static_assert(EveryFfxConfigureRowIsALeaf(),
"an ffxConfigure row names a module the leaf table does not know -- InstallByFamily would find no slot");
static_assert(!FfxConfigureRowExistsFor(kModuleFfxFsr3Host),
"the FSR 3.0 host has its own configure API, not ffxConfigure; a row claiming one would resolve nothing");
// Does this module speak the Streamline 2 ABI the vendored headers describe?
//
// MEASURED 2026-08-14, and it cost an access violation to find. The Witcher 3
+165 -7
View File
@@ -163,6 +163,7 @@ enum FlLogCode : uint32_t {
kLogFfxQueryType,
kLogUpscaleRoute,
kLogRuntimeCensus,
kLogFfxConfigureType,
};
const char* LogCodeName(uint32_t code) noexcept {
@@ -201,6 +202,8 @@ const char* LogCodeName(uint32_t code) noexcept {
return "UPSCALE_ROUTE";
case kLogRuntimeCensus:
return "RUNTIME_CENSUS";
case kLogFfxConfigureType:
return "FFX_CONFIGURE";
default:
return "?";
}
@@ -1166,7 +1169,13 @@ std::atomic<uint32_t> g_slSetTagForFramePatched{0};
using PFN_SlGetNewFrameToken = ::PFun_slGetNewFrameToken*;
PFN_SlGetNewFrameToken g_origSlGetNewFrameToken = nullptr;
std::atomic<uint32_t> g_frameTokensLive{0};
std::atomic<uint32_t> g_frameTokens{0};
// slSetConstants (0.1.0-beta.43, Advanced metrics): patched only in a process that was asked for Advanced metrics at
// least once (InstallByFamily), and its detour forwards without looking while the request is off.
using PFN_SlSetConstants = ::PFun_slSetConstants*;
PFN_SlSetConstants g_origSlSetConstants = nullptr;
std::atomic<uint32_t> g_slConstantsLive{0};
std::atomic<uint32_t> g_frameTokens{0};
// The HIGHEST frame index seen so far, tagged in bit 32 so that index 0 is
// distinct from "no frame yet". Measured 2026-09-03 on Cyberpunk 2077
// (20_OPEN_QUESTIONS §S31, row P4): the title asks for a token 3 to 4.6 times per
@@ -1256,6 +1265,23 @@ std::atomic<uint64_t> g_ffxExtent{0};
// not say which -- so the same UPSCALE type decodes to FL_UPSCALER_FSR3 from one leaf
// and to FL_UPSCALER_FSR_UNVERSIONED from the other (fl_shm.h says why).
std::atomic<uint32_t> g_ffxUpscaleLeaf{0};
// WHICH SOURCE'S UPSCALES ARE COUNTED (owner decision D125, 2026-11-12): the first one that saw an UPSCALE, and from
// then on only it -- leaf + 1 for an ffx-api module, kFfxUpscaleSourceFsr3Host for the 3.0 host; fl::adv::Owns' slot.
//
// WHY. A loader that hands a dispatch on to the leaf's EXPORT delivers one UPSCALE to two hooked modules, and the
// count below was one per module that saw it. Measured on Cyberpunk 2077's loader 2.3.0 for the frame-generation
// dispatches (logged on the loader AND the leaf); the loader of the three titles of 2026-09-04 leaves the leaf
// exports silent, which is why the rows were written without this. With frame generation off no PREPARE arrives, the
// application-frame count falls back to this one, and K = 1 would read 2.0: Native FPS doubled and the factor halved,
// which rule 6 forbids in either direction. No title run so far upscales through such a loader -- this is a
// precaution, held by the fixture's loader bound through the exports.
//
// THE FIRST SOURCE, AND NOT THE OUTERMOST CALL ON THE STACK: knowing that a detour runs inside another's original
// would take state carried across the call to the original, which every detour here makes exactly once and outside
// its guard. The game's entry is the first to see a dispatch, so the first source IS the entry. What it gives up is
// said in LIMITATIONS: a process whose UPSCALEs come from two unrelated sources is counted from the first alone.
// The render size and the quality byte are NOT gated -- the same call writes the same values twice.
std::atomic<uint32_t> g_ffxUpscaleOwner{0};
using PFN_FfxDispatch = ::PfnFfxDispatch;
PFN_FfxDispatch g_origFfxDispatch[fl::inventory::kFfxLeafCount] = {};
@@ -1303,6 +1329,13 @@ PFN_FfxQuery g_origFfxQuery[fl::inventory::kFfxLeafCount] = {};
std::atomic<uint32_t> g_ffxQueryPatched[fl::inventory::kFfxLeafCount] = {};
std::atomic<uint32_t> g_ffxQueryLive{0};
// ffxConfigure on the same four modules (0.1.0-beta.43, Advanced metrics): patched only in a process that was asked
// for Advanced metrics at least once (InstallByFamily); one trampoline and one latch a leaf, as the query's.
using PFN_FfxConfigure = ::PfnFfxConfigure;
PFN_FfxConfigure g_origFfxConfigure[fl::inventory::kFfxLeafCount] = {};
std::atomic<uint32_t> g_ffxConfigurePatched[fl::inventory::kFfxLeafCount] = {};
std::atomic<uint32_t> g_ffxConfigureLive{0};
// THE VALUES AND LAYOUTS THE QUERY ARM READS, PINNED TO LITERALS. Identical at FidelityFX SDK v1.1.4 (the monolith's
// generation) and v2.3.0 (the vendored headers), checked against both on 2026-10-19: the two type ids, the mode enum,
// and both query descriptors -- a re-vendoring that moved a field fails here, not on a title's own descriptor.
@@ -1707,6 +1740,26 @@ sl::Result STDMETHODCALLTYPE Hook_SlSetTag(const sl::ViewportHandle& viewport, c
return g_origSlSetTag(viewport, tags, numTags, cmdBuffer);
}
// What the game tells Streamline about a frame (0.1.0-beta.43). THREE CONDITIONS BEFORE ANYTHING IS READ, in the
// order that costs least: the Agent is asking for Advanced metrics; observing has not stopped (after a stop nobody
// clears the request word, so the first test alone would keep reading); and the struct is the one these headers
// describe -- its GUID and a version of at least 1, checked on THIS call, because the game owns the struct and a
// Streamline generation that lays it out differently keeps the export's name. The struct is read in
// fl_adv_fields.h, which never touches its matrices or the camera's position and axes (rule 4). The viewport's id
// is the handle's own conversion to an integer, taken only from a handle that is one (the same GUID check).
sl::Result STDMETHODCALLTYPE Hook_SlSetConstants(const sl::Constants& values, const sl::FrameToken& frame,
const sl::ViewportHandle& viewport) {
FL_HOOK_GUARD({
if (g_advancedRequested.load(std::memory_order_relaxed) != 0u && MayObserve() &&
fl::slinputs::IsReadable<sl::Constants>(&values) &&
fl::slinputs::IsReadable<sl::ViewportHandle>(&viewport)) {
fl::adv::ObserveSlConstants(values, static_cast<uint32_t>(viewport), g_adv);
}
})
// ALWAYS exactly once, on every path including the fault path, with every argument forwarded untouched.
return g_origSlSetConstants(values, frame, viewport);
}
// slSetTagForFrame: the FrameToken first, then the same list slSetTag takes. The
// token is not read -- the frame count comes from slGetNewFrameToken -- and the tag
// list is handed to the same NoteTags, because a per-frame tag and a viewport tag
@@ -1918,8 +1971,10 @@ void NoteFfxExtent(const FfxApiDimensions2D& size) noexcept {
// a record or the shared memory.
fl::ffxtypes::Seen g_ffxDispatchTypes[fl::inventory::kFfxLeafCount];
fl::ffxtypes::Seen g_ffxQueryTypes[fl::inventory::kFfxLeafCount];
fl::ffxtypes::Reported g_ffxDispatchTypesLogged[fl::inventory::kFfxLeafCount]; // watchdog only
fl::ffxtypes::Reported g_ffxQueryTypesLogged[fl::inventory::kFfxLeafCount]; // watchdog only
fl::ffxtypes::Reported g_ffxDispatchTypesLogged[fl::inventory::kFfxLeafCount]; // watchdog only
fl::ffxtypes::Reported g_ffxQueryTypesLogged[fl::inventory::kFfxLeafCount]; // watchdog only
fl::ffxtypes::Seen g_ffxConfigureTypes[fl::inventory::kFfxLeafCount]; // only where ffxConfigure is hooked
fl::ffxtypes::Reported g_ffxConfigureTypesLogged[fl::inventory::kFfxLeafCount]; // watchdog only
// The answer one query returned, kept for the dispatch arm. Read only after the vendor answered OK; a mode, a size or a
// ratio the byte or the match cannot carry is not kept.
@@ -2014,8 +2069,12 @@ void ObserveFfxDispatch(uint32_t leaf, const ffxDispatchDescHeader* desc) noexce
g_ffxQuality.store(
FfxQualityOf(up->renderSize.width, up->renderSize.height, up->upscaleSize.width, up->upscaleSize.height),
std::memory_order_release);
g_ffxUpscaleLeaf.store(leaf + 1u, std::memory_order_relaxed);
g_ffxSeen.fetch_add(fl::slseen::kCountOne, std::memory_order_relaxed);
// Counted once, at the first source that saw an UPSCALE (D125): a loader that forwards to the leaf's export
// brings the same dispatch here twice.
if (fl::adv::Owns(g_ffxUpscaleOwner, leaf)) {
g_ffxUpscaleLeaf.store(leaf + 1u, std::memory_order_relaxed);
g_ffxSeen.fetch_add(fl::slseen::kCountOne, std::memory_order_relaxed);
}
// The rest of the same descriptor (sharpening, jitter, exposure, the depth range, the field of view, flags,
// the frame time) - Advanced metrics, only while the Agent asked (D111). Not on the FSR 3.0 host's route:
// its legacy descriptor is vouched for through renderSize and no further (17_HOOK_ENGINE §Which struct
@@ -2080,8 +2139,11 @@ fsr3host::FfxErrorCode Hook_FfxFsr3ContextDispatchUpscale(fsr3host::FfxFsr3Conte
FL_HOOK_GUARD({
if (MayObserve() && desc != nullptr) {
NoteFfxExtent(desc->renderSize.width, desc->renderSize.height);
g_ffxUpscaleLeaf.store(kFfxUpscaleSourceFsr3Host, std::memory_order_relaxed);
g_ffxSeen.fetch_add(fl::slseen::kCountOne, std::memory_order_relaxed);
// The host is a source like the four leaves (D125): Owns' slot value for it is its leaf index + 1.
if (fl::adv::Owns(g_ffxUpscaleOwner, kFfxUpscaleSourceFsr3Host - 1u)) {
g_ffxUpscaleLeaf.store(kFfxUpscaleSourceFsr3Host, std::memory_order_relaxed);
g_ffxSeen.fetch_add(fl::slseen::kCountOne, std::memory_order_relaxed);
}
}
})
return g_origFfxFsr3DispatchUpscale(context, desc);
@@ -2122,6 +2184,39 @@ ffxReturnCode_t Hook_FfxQueryT(ffxContext* context, ffxQueryDescHeader* desc) {
return rc;
}
// ffxConfigure's trampolines (0.1.0-beta.43), one per leaf. The descriptor's type is kept for the log whatever it
// is; the frame-generation configuration is read further only while the Agent asks, in fl_adv_fields.h, which never
// touches the swapchain, the callbacks, the HUD-less resource or the frame id. MayObserve first: after a stop nobody
// clears the request word. Every argument forwarded untouched, the original called exactly once on every path.
template <uint32_t Leaf>
ffxReturnCode_t Hook_FfxConfigureT(ffxContext* context, const ffxConfigureDescHeader* desc) {
static_assert(Leaf < fl::inventory::kFfxLeafCount, "a trampoline per leaf, and no more");
FL_HOOK_GUARD({
if (MayObserve() && desc != nullptr) {
fl::ffxtypes::Note(g_ffxConfigureTypes[Leaf], desc->type);
if (g_advancedRequested.load(std::memory_order_relaxed) != 0u) {
fl::adv::ObserveFfxConfigure(Leaf, desc, g_adv);
}
}
})
return g_origFfxConfigure[Leaf](context, desc);
}
void* FfxConfigureDetour(uint32_t leaf) noexcept {
switch (leaf) {
case fl::inventory::kFfxLeafMonolith:
return reinterpret_cast<void*>(&Hook_FfxConfigureT<fl::inventory::kFfxLeafMonolith>);
case fl::inventory::kFfxLeafUpscaler:
return reinterpret_cast<void*>(&Hook_FfxConfigureT<fl::inventory::kFfxLeafUpscaler>);
case fl::inventory::kFfxLeafFrameGeneration:
return reinterpret_cast<void*>(&Hook_FfxConfigureT<fl::inventory::kFfxLeafFrameGeneration>);
case fl::inventory::kFfxLeafLoader:
return reinterpret_cast<void*>(&Hook_FfxConfigureT<fl::inventory::kFfxLeafLoader>);
default:
return nullptr;
}
}
void* FfxQueryDetour(uint32_t leaf) noexcept {
switch (leaf) {
case fl::inventory::kFfxLeafMonolith:
@@ -2304,6 +2399,10 @@ void LogFfxObservations() noexcept {
g_ffxQueryTypes[leaf], g_ffxQueryTypesLogged[leaf],
[moduleName](uint64_t type) noexcept { LogNoteW(kLogFfxQueryType, moduleName, 0u, type); },
[moduleName](uint32_t more) noexcept { LogNoteW(kLogFfxQueryType, moduleName, more, 0u); });
fl::ffxtypes::ReportNew(
g_ffxConfigureTypes[leaf], g_ffxConfigureTypesLogged[leaf],
[moduleName](uint64_t type) noexcept { LogNoteW(kLogFfxConfigureType, moduleName, 0u, type); },
[moduleName](uint32_t more) noexcept { LogNoteW(kLogFfxConfigureType, moduleName, more, 0u); });
}
// g_ffxUpscaleLeaf: leaf + 1 for an ffx-api leaf, kFfxUpscaleSourceFsr3Host for the 3.0 host's own export, 0 for
// none yet. The host has no descriptor type, so this is the only line that says its export was called.
@@ -2402,6 +2501,43 @@ bool InstallByFamily(const wchar_t* moduleName, const char* symbol, uint32_t fam
// bit test would bind any future row that happens to include identity to THIS
// detour -- which is the neighbour's-body defect this function exists to stop,
// and it would arrive silently because the row would still install.
//
// THE ROWS THAT ARE INSTALLED ONLY WHERE ADVANCED METRICS WAS EVER ASKED FOR (owner decision D111), FIRST -- before
// anything is resolved, because ResolveScoped takes a reference on the module at every call: in a process never
// asked, these rows must change nothing, not even a reference count. g_advancedSeen is the watchdog's, and this
// runs on the watchdog, after the block that sets it. Once the patch is in it stays; the detour forwards without
// looking while the request is off.
if (family == fl::inventory::kFamilySlConstants) {
if (g_advancedSeen == 0u) {
return false;
}
return InstallRow(moduleName, symbol, family, reinterpret_cast<void*>(&Hook_SlSetConstants),
reinterpret_cast<void**>(&g_origSlSetConstants), g_slConstantsLive, name);
}
if (family == fl::inventory::kFamilyFfxConfigure) {
if (g_advancedSeen == 0u) {
return false;
}
// FOUR ROWS, ONE ARM, the query arm's shape: the row's MODULE picks the trampoline and the latch slot.
// Published in PublishFfxConfigureFamilyIfWhole, once every loaded leaf is in.
const int leaf = fl::inventory::FfxLeafOf(moduleName);
if (leaf < 0) {
return false; // the static_asserts make this unreachable for the rows as written
}
const auto slot = static_cast<uint32_t>(leaf);
if (g_ffxConfigurePatched[slot].load(std::memory_order_acquire) != 0) {
return true;
}
void* target = fl::inventory::ResolveScoped(moduleName, symbol);
if (target == nullptr) {
return false; // not loaded, or a module of the name that does not speak ffx-api
}
if (!PatchTarget(target, FfxConfigureDetour(slot), reinterpret_cast<void**>(&g_origFfxConfigure[slot]), name)) {
return false;
}
g_ffxConfigurePatched[slot].store(1, std::memory_order_release);
return true;
}
if (family == fl::inventory::kFamilyEvaluateFeature) {
return InstallRow(moduleName, symbol, family, reinterpret_cast<void*>(&Hook_SlEvaluateFeature),
reinterpret_cast<void**>(&g_origSlEvaluateFeature), g_upscalerIdentityLive, name);
@@ -2572,6 +2708,27 @@ void PublishFfxQueryFamilyIfWhole() noexcept {
}
}
// Publish kFamilyFfxConfigure once every ffx leaf the process has loaded has its configure patched, and at least one
// does -- the query family's rule. Nothing is patched in a process never asked, so nothing is published there.
void PublishFfxConfigureFamilyIfWhole() noexcept {
if (g_advancedSeen == 0u || g_ffxConfigureLive.load(std::memory_order_acquire) != 0) {
return;
}
bool anyPatched = false;
for (uint32_t i = 0; i < fl::inventory::kFfxLeafCount; ++i) {
if (g_ffxConfigurePatched[i].load(std::memory_order_acquire) != 0) {
anyPatched = true;
continue;
}
if (fl::inventory::IsModuleLoaded(fl::inventory::kFfxLeafModules[i])) {
return; // loaded and not yet patched: the family is not whole
}
}
if (anyPatched) {
PublishHookFamily(fl::inventory::kFamilyFfxConfigure, g_ffxConfigureLive);
}
}
// Publish FL_HOOK_UPSCALER_PARAMS once EVERY TAG EXPORT THE LOADED INTERPOSER HAS is
// patched, and at least one is. "Has" is the export table, not the module list: a
// 2.7 interposer exports slSetTag alone and is whole with that one row patched; a
@@ -2615,6 +2772,7 @@ bool InstallUpscalerHooks() noexcept {
PublishParamsFamilyIfWhole();
PublishFfxFamilyIfWhole();
PublishFfxQueryFamilyIfWhole();
PublishFfxConfigureFamilyIfWhole();
return any;
}
@@ -405,6 +405,16 @@ enum FlHookFamily : uint32_t {
// FL_FEAT_RAY_RECONSTRUCTION_OBSERVED and never bit 7, and without this family its silence would read as a
// measured "not running" -- a fabricated negative of the kind 03_METRICS §RT/PT/RR forbids for ray reconstruction.
FL_HOOK_SL_NEURAL_RENDERING = 1u << 12,
// Advanced metrics, train B's second step (0.1.0-beta.43): slSetConstants is hooked. Published only in a process
// that was asked for Advanced metrics at least once -- the patch is not made otherwise (owner decision D111) --
// so its absence beside FL_ADV_VALID_* bits says "the hook was not installed", and its presence beside a zero
// slConstantsCalls says "hooked, and the game never called it". It entitles no measured field of a frame record.
FL_HOOK_SL_CONSTANTS = 1u << 13,
// The same for ffxConfigure on the ffx-api modules (0.1.0-beta.43): hooked, in a process that was asked for
// Advanced metrics at least once. Published when every ffx-api module the process has loaded is patched, as the
// dispatch and query families are. Beside a zero ffxFgConfigures it says "hooked, and the game never configured
// frame generation"; it entitles no measured field of a frame record.
FL_HOOK_FFX_CONFIGURE = 1u << 14,
};
// FlWriterState::runtimeCensus -- which vendor RUNTIME MODULES the loader reported
+2
View File
@@ -137,6 +137,8 @@ target_compile_definitions(fl_guard_test PRIVATE
# late arrival must be hooked within milliseconds rather than on the next tick.
FL_STUB_SL_COMMON=L"$<TARGET_FILE:fl_stub_sl_common>"
FL_STUB_SL_INTERPOSER=L"$<TARGET_FILE:fl_stub_sl_interposer>"
# The ffx-api loader stub, so a test can read one of its exports' first bytes out of a target (0.1.0-beta.43).
FL_STUB_FFX_LOADER=L"$<TARGET_FILE:fl_stub_ffx_loader>"
FL_OVERLAY_DLL=L"${FL_STAGED_OVERLAY}"
# The un-staged original, so a test can prove the check discriminates on
# DIRECTORY rather than on filename: same bytes, same name, wrong place.
+424 -19
View File
@@ -1025,6 +1025,134 @@ TEST_CASE("D48 — a scan-set member still loading, or gone, is read again once"
}
}
// ===========================================================================
// D123 (owner decision, 2026-11-12) — a module list that CHANGED WHILE IT WAS READ
// is read again, a bounded number of times, and a list that never settles refuses.
//
// What it is for: a game at its launch loads and unloads modules for seconds. A
// module that was in the list and could not be named a moment later made the
// whole check "incomplete", and the session ended as a safety unhook with no
// frame recorded -- five times in a week in one PC's Agent logs (Phantom Blade
// Zero, Crown & Coin, Cyberpunk 2077). What it must never do is the same as
// D48: pass anything that was not read whole.
// ===========================================================================
TEST_CASE("D123 — a module list that changed under the read is read again, at most three times",
"[guard][failclosed][D123]") {
ResetFake();
g.scanSet = {1234, 1000, 4000}; // the target, its launcher, a child
SECTION("the target's list settles on the second read: one pause, two snapshots, allowed") {
g.moduleResultsInTurn[1234] = {Collected::kUnsettled, Collected::kOk};
CHECK(EvaluateWithSources(1234, FakeSources()).Allowed());
CHECK(g.pauses == 1);
CHECK(g.lastPauseMs == kScanRetryPauseMs);
CHECK(g.scanSetCalls == 2);
CHECK(g.moduleCallsByPid[1000] == 2); // the members that read whole are read again too
}
SECTION("it settles on the fourth read: three pauses, four snapshots, allowed") {
g.moduleResultsInTurn[1234] = {Collected::kUnsettled, Collected::kUnsettled, Collected::kUnsettled,
Collected::kOk};
CHECK(EvaluateWithSources(1234, FakeSources()).Allowed());
CHECK(g.pauses == 3);
CHECK(g.scanSetCalls == 4);
}
SECTION("a list that never settles refuses -- after four reads and not one more") {
g.moduleResultsInTurn[1234] = {Collected::kUnsettled}; // the last answer repeats
const Verdict v = EvaluateWithSources(1234, FakeSources());
REQUIRE_FALSE(v.Allowed());
CHECK(v.reason == Reason::kModuleScanFailed);
CHECK(std::string(v.signal) == "a module list kept changing while it was read");
CHECK(g.pauses == static_cast<int>(kMaxUnsettledRereads));
CHECK(g.scanSetCalls == static_cast<int>(kMaxUnsettledRereads) + 1);
CHECK(g.moduleCallsByPid[1234] == static_cast<int>(kMaxUnsettledRereads) + 1);
}
SECTION("a list too long for the buffer is not read again: it would be as long") {
g.moduleResultByPid[4000] = Collected::kIncomplete;
const Verdict v = EvaluateWithSources(1234, FakeSources());
REQUIRE_FALSE(v.Allowed());
CHECK(v.reason == Reason::kModuleScanFailed);
CHECK(std::string(v.signal) == "a module list came back incomplete");
CHECK(g.pauses == 0);
CHECK(g.scanSetCalls == 1);
}
SECTION("a finding among the modules that WERE read refuses at once, with no pause") {
// The half-read list held a blocklisted module: the re-read is for what could not be read, never a second
// chance for what was.
g.moduleResultsInTurn[4000] = {Collected::kUnsettled, Collected::kOk};
g.modulesByPid[4000] = {"kernel32.dll", "EasyAntiCheat_EOS.dll"};
const Verdict v = EvaluateWithSources(1234, FakeSources());
REQUIRE_FALSE(v.Allowed());
CHECK(v.reason == Reason::kBlockedModule);
CHECK(g.pauses == 0);
CHECK(g.scanSetCalls == 1);
}
SECTION("a finding in another member refuses at once, with no pause") {
g.moduleResultsInTurn[4000] = {Collected::kUnsettled, Collected::kOk};
g.modulesByPid[1000] = {"EasyAntiCheat_EOS.dll"};
const Verdict v = EvaluateWithSources(1234, FakeSources());
REQUIRE_FALSE(v.Allowed());
CHECK(v.reason == Reason::kBlockedModule);
CHECK(g.pauses == 0);
}
SECTION("a finding the re-read sees refuses") {
g.moduleResultsInTurn[4000] = {Collected::kUnsettled, Collected::kOk};
g.modulesByPid[1234] = {"kernel32.dll"};
g.modulesByPid[1000] = {"kernel32.dll"};
g.modulesLate = {"EasyAntiCheat_EOS.dll"};
g.moduleCallsBeforeLate = 3; // the first read's three; the module is there on the re-read
const Verdict v = EvaluateWithSources(1234, FakeSources());
REQUIRE_FALSE(v.Allowed());
CHECK(v.reason == Reason::kBlockedModule);
CHECK(g.pauses == 1);
}
SECTION("a protected process met on a re-read refuses as unreadable: the re-read excuses nothing else") {
g.moduleResultsInTurn[1234] = {Collected::kUnsettled, Collected::kOk};
g.moduleResultsInTurn[4000] = {Collected::kOk, Collected::kFailed};
const Verdict v = EvaluateWithSources(1234, FakeSources());
REQUIRE_FALSE(v.Allowed());
CHECK(v.reason == Reason::kProcessUnreadable);
CHECK(g.pauses == 1);
}
SECTION("D48's re-read stays ONE, whichever read first met the member still being created") {
// The target's list is unsettled on reads 1 and 2; a child is still being created on reads 2 and 3. Its first
// kRetry is excused -- D48 -- and its second refuses, though the unsettled list would have allowed a fourth
// read.
g.moduleResultsInTurn[1234] = {Collected::kUnsettled, Collected::kUnsettled, Collected::kOk};
g.moduleResultsInTurn[4000] = {Collected::kOk, Collected::kRetry, Collected::kRetry};
const Verdict v = EvaluateWithSources(1234, FakeSources());
REQUIRE_FALSE(v.Allowed());
CHECK(v.reason == Reason::kProcessUnreadable);
CHECK(g.pauses == 2);
CHECK(g.scanSetCalls == 3);
}
SECTION("...and the two together still end in a read of everything, whole") {
g.moduleResultsInTurn[1234] = {Collected::kUnsettled, Collected::kOk};
g.moduleResultsInTurn[4000] = {Collected::kRetry, Collected::kOk};
CHECK(EvaluateWithSources(1234, FakeSources()).Allowed());
CHECK(g.pauses == 1);
CHECK(g.scanSetCalls == 2);
}
}
TEST_CASE("D48 — the real module source answers kRetry for a process still loading and for one that is gone",
"[guard][D48][live]") {
const Sources s = SystemSources();
@@ -2921,6 +3049,40 @@ TEST_CASE("region 4 describes a swap chain on a real window: its window, its bac
CHECK(r.st->faultCount == 0u);
}
TEST_CASE("D123 — the real module source says a churning list is unsettled, never too long and never unreadable",
"[guard][D123][live]") {
// A process that loads and frees one module as fast as it can: a list that changes under every read. The real
// source may read it whole (kOk) or meet a module it can no longer name (kUnsettled); what it must not say is
// kIncomplete -- which is not read again -- or kFailed. How often it is unsettled is the machine's to decide, so
// the count is reported and not asserted: on the PC this was written on, about one read in four.
Child child;
REQUIRE(StartHarness(child, std::wstring(L"--churn-module \"") + FL_STUB_SL_COMMON + L"\" --hold 30"));
const Sources s = SystemSources();
REQUIRE(s.EnumerateModules != nullptr);
auto none = [](void*, const char*, const wchar_t*) noexcept -> bool { return true; };
int ok = 0;
int unsettled = 0;
int other = 0;
const ULONGLONG until = GetTickCount64() + 3000;
while (GetTickCount64() < until) {
// An if-chain, not a switch: the two answers are named and every other one is "other" on purpose.
const Collected c = s.EnumerateModules(child.pi.dwProcessId, none, nullptr);
if (c == Collected::kOk) {
++ok;
} else if (c == Collected::kUnsettled) {
++unsettled;
} else {
++other;
}
}
WARN("a churning module list, read " << (ok + unsettled + other) << " times in 3 s: " << ok << " whole, "
<< unsettled << " unsettled, " << other << " other");
CHECK(ok > 0);
CHECK(other == 0);
}
TEST_CASE("the native log: written at init, on the Agent's request, and on the stop -- and the stop restores each "
"patch by compare-and-restore",
"[guard][inject][shm][log]") {
@@ -3816,7 +3978,7 @@ TEST_CASE("an isolation seam that cannot answer refuses, and so does a guard wir
REQUIRE(StartHarness(child));
// Every fact clear beside a failed result: the result is what is honoured, never the facts next to it.
for (const Collected bad : {Collected::kFailed, Collected::kIncomplete, Collected::kRetry}) {
for (const Collected bad : {Collected::kFailed, Collected::kIncomplete, Collected::kRetry, Collected::kUnsettled}) {
ResetFake();
g.modules = {"kernel32.dll"};
g.scanSet = {child.pi.dwProcessId};
@@ -5926,6 +6088,26 @@ TEST_CASE("FSR through the SDK 2.x loader: identified, extent exact, the count t
}
}
TEST_CASE("a loader that hands a dispatch on to the leaf's export (D125): an UPSCALE is counted once, at the module "
"the game called",
"[guard][inject][shm][ffx]") {
// MEASURED ON CYBERPUNK 2077, 2026-11-12: its loader 2.3.0 forwards a dispatch to the leaf's EXPORT -- each
// frame-generation dispatch type was logged on the loader and on the frame-generation leaf -- where the loader of
// September's three titles left the leaf exports silent. With all four modules hooked an UPSCALE through such a
// loader arrives twice, and the count that stands in for application frames when no PREPARE is issued (frame
// generation off) was one per hooked module that saw it: K = 1 read 2.0. No title run so far upscales this way;
// the stub loader bound through the exports is how the rule is held. Frame generation ON is the second half:
// PREPARE is counted by its frame number and must read the same through either loader.
for (const int k : {1, 4}) {
CAPTURE(k);
FfxObservation obs;
REQUIRE(ObserveFfx(k, L"2x-export", /*prepare=*/k > 1, fl::FL_UPSCALER_FSR_UNVERSIONED, obs));
AssertFfxWindow(obs, k);
CHECK((obs.census & fl::FL_CENSUS_AMD_FFX_UPSCALER) != 0u);
CHECK((obs.census & fl::FL_CENSUS_AMD_FFX_FRAMEGENERATION) != 0u);
}
}
TEST_CASE("the SDK 1.1.x monolith is FSR3; with no PREPARE the count falls back to UPSCALE dispatches",
"[guard][inject][shm][ffx]") {
// TWO SHAPES A 1.1.x TITLE ACTUALLY HAS. Frame generation OFF: no PREPARE is ever
@@ -5988,7 +6170,7 @@ TEST_CASE("the FSR 3.0 host facade: Fsr3 identity and the count from its upscale
namespace {
// Whether the log has a line of this code whose text starts with `name` and which ends in `tail`.
bool LogHasLine(const std::string& text, const char* code, const char* name, const char* tail) {
bool LogHasLine(const std::string& text, const char* code, const std::string& name, const std::string& tail) {
const std::string head = std::string("s ") + code + " ";
std::size_t at = 0;
while (at < text.size()) {
@@ -6003,9 +6185,9 @@ bool LogHasLine(const std::string& text, const char* code, const char* name, con
while (n < line.size() && line[n] == ' ') {
++n;
}
const std::string tailText = tail;
if (line.compare(n, std::strlen(name), name) == 0 && line.size() >= tailText.size() &&
line.compare(line.size() - tailText.size(), tailText.size(), tailText) == 0) {
// The lengths are the strings' own (SonarCloud's cpp:S5813 was a strlen here).
if (line.compare(n, name.size(), name) == 0 && line.size() >= tail.size() &&
line.compare(line.size() - tail.size(), tail.size(), tail) == 0) {
return true;
}
}
@@ -6777,6 +6959,20 @@ constexpr float kAdvFfxFar = 1000.0f;
constexpr float kAdvFfxFovLow = 0.9f;
constexpr float kAdvFfxFovHigh = 1.1f;
constexpr uint32_t kAdvFfxFrameTimeUs = 16000u;
// ...and hands slSetConstants for viewport 0 (0.1.0-beta.43); a second viewport gets other numbers every frame.
constexpr float kAdvSlJitterX = 0.3125f;
constexpr float kAdvSlJitterY = 0.4375f;
constexpr float kAdvSlMvecScaleX = 0.5f;
constexpr float kAdvSlMvecScaleY = 0.25f;
constexpr float kAdvSlNear = 0.25f;
constexpr float kAdvSlFar = 4000.0f;
constexpr float kAdvSlFovLow = 0.8f;
constexpr float kAdvSlFovHigh = 1.2f;
constexpr float kAdvSlAspect = 1.75f;
// ...and hands ffxConfigure a frame-generation configuration before each frame's dispatches (0.1.0-beta.43).
constexpr uint32_t kAdvFfxFgFlags = 1u << 4; // FFX_FRAMEGENERATION_FLAG_DRAW_DEBUG_PACING_LINES
constexpr int32_t kAdvFfxFgRectWidth = 1920;
constexpr int32_t kAdvFfxFgRectHeight = 1080;
constexpr uint64_t kAdvMemoryTotal = 123456789ull;
constexpr uint64_t kAdvMemoryAliasable = 23456789ull;
@@ -6835,16 +7031,77 @@ uint32_t BitsOf(float v) {
return std::bit_cast<uint32_t>(v);
}
// What 0.1.0-beta.43 and beta.44 fill (beta.41 and beta.42 until D118 and D122): declared, written by nothing yet.
// What later releases fill: declared, written by nothing yet. (The sl::Constants and the ffxConfigure groups left
// this list with 0.1.0-beta.43, which fills them; the two helpers below are for a target that makes neither call.)
bool LaterGroupsAreZero(const fl::FlAdvancedState& a) {
bool zero = a.ffxFgConfigures == 0u && a.ffxFgEnabledSeen == 0u && a.ffxFgFlagsSeen == 0u &&
a.slConstantsCalls == 0u && a.slResets == 0u && a.slFlagsSeenTrue == 0u && a.slFlagsSeenFalse == 0u;
bool zero = true;
for (uint32_t i = 0; i < FL_ADV_FEATURE_SLOTS * FL_ADV_FEATURE_WORDS; ++i) {
zero = zero && a.features[i] == 0u;
}
return zero;
}
bool FfxFgConfigIsUnread(const fl::FlAdvancedState& a) {
return a.ffxFgConfigures == 0u && a.ffxFgEnabledSeen == 0u && a.ffxFgAsyncSeen == 0u &&
a.ffxFgOnlyGeneratedSeen == 0u && a.ffxFgFlagsSeen == 0u && a.ffxFgRect[2] == 0 && a.ffxFgRect[3] == 0 &&
(a.validMask & fl::FL_ADV_VALID_FFX_FG_CONFIG) == 0u;
}
bool SlConstantsAreUnread(const fl::FlAdvancedState& a) {
return a.slConstantsCalls == 0u && a.slResets == 0u && a.slFlagsSeenTrue == 0u && a.slFlagsSeenFalse == 0u &&
(a.validMask & fl::FL_ADV_VALID_SL_CONSTANTS) == 0u;
}
// The first 16 bytes of one export of a module AS THEY ARE IN ANOTHER PROCESS: the export's offset from this
// process's own mapping of the same file (mapped as an image, nothing run), the module's base from the target's
// module list. What a patch changes, and what a restore puts back.
//
// `inFile`, when given, receives the same 16 bytes as this process's own mapping of the file has them -- nothing has
// patched that copy, so an export whose bytes in the target equal them is unpatched. (Not "does it start with a
// jump": a stub export may be a jump to begin with -- the loader stub's ffxConfigure is.)
bool ReadTargetExportBytes(DWORD pid, const wchar_t* dllPath, const char* symbol, unsigned char out[16],
unsigned char* inFile = nullptr) {
const HMODULE mine = LoadLibraryExW(dllPath, nullptr, DONT_RESOLVE_DLL_REFERENCES);
if (mine == nullptr) {
return false;
}
const auto* entry = reinterpret_cast<const unsigned char*>(GetProcAddress(mine, symbol));
const size_t rva =
entry != nullptr ? static_cast<size_t>(entry - reinterpret_cast<const unsigned char*>(mine)) : 0u;
if (entry != nullptr && inFile != nullptr) {
std::memcpy(inFile, entry, 16);
}
FreeLibrary(mine);
const wchar_t* slash = wcsrchr(dllPath, L'\\');
const wchar_t* slash2 = wcsrchr(dllPath, L'/');
const wchar_t* leaf = slash != nullptr && (slash2 == nullptr || slash > slash2) ? slash + 1
: slash2 != nullptr ? slash2 + 1
: dllPath;
if (rva == 0u) {
return false;
}
HANDLE h = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION | PROCESS_VM_READ, FALSE, pid);
if (h == nullptr) {
return false;
}
HMODULE mods[1024]{};
DWORD needed = 0;
bool read = false;
if (EnumProcessModulesEx(h, mods, sizeof(mods), &needed, LIST_MODULES_ALL)) {
const size_t n = (needed > sizeof(mods) ? sizeof(mods) : needed) / sizeof(HMODULE);
for (size_t i = 0; i < n && !read; ++i) {
wchar_t name[MAX_PATH]{};
if (GetModuleBaseNameW(h, mods[i], name, MAX_PATH) != 0 && _wcsicmp(name, leaf) == 0) {
SIZE_T got = 0;
read = ReadProcessMemory(h, reinterpret_cast<const unsigned char*>(mods[i]) + rva, out, 16, &got) &&
got == 16;
}
}
}
CloseHandle(h);
return read;
}
} // namespace
TEST_CASE("region 5 stays empty until the Agent asks, then carries what an FSR title told its upscaler, per request",
@@ -6876,14 +7133,35 @@ TEST_CASE("region 5 stays empty until the Agent asks, then carries what an FSR t
REQUIRE(r.st->writeIndex > atHooks + 30u); // the hooks ran: this is not a target that sent nothing
CHECK(r.ctl->advancedRequested == 0u);
CHECK(RegionFiveIsZero(r));
// ...and ffxConfigure, which the target calls twice a frame, is not patched: never asked (D111). Its first bytes
// in the target's loader are the file's.
const auto ffxConfigure = static_cast<uint32_t>(fl::FL_HOOK_FFX_CONFIGURE);
unsigned char pristine[16]{};
unsigned char inFile[16]{};
unsigned char now[16]{};
CHECK((r.st->hooksInstalledMask & ffxConfigure) == 0u);
REQUIRE(ReadTargetExportBytes(child.pi.dwProcessId, FL_STUB_FFX_LOADER, "ffxConfigure", pristine, inFile));
CHECK(std::memcmp(pristine, inFile, sizeof(inFile)) == 0);
{
// The dispatch export beside it IS patched, since the module appeared: the same read tells the two apart.
unsigned char dispatch[16]{};
unsigned char dispatchInFile[16]{};
REQUIRE(
ReadTargetExportBytes(child.pi.dwProcessId, FL_STUB_FFX_LOADER, "ffxDispatch", dispatch, dispatchInFile));
CHECK(std::memcmp(dispatch, dispatchInFile, sizeof(dispatch)) != 0);
}
// ---- 2. ASKED. Within a tick or two the region answers THIS request with what the descriptor carried.
SetAdvancedRequest(r, 7u);
REQUIRE(WaitForHookFamily(r.st, ffxConfigure));
REQUIRE(ReadTargetExportBytes(child.pi.dwProcessId, FL_STUB_FFX_LOADER, "ffxConfigure", now));
CHECK(std::memcmp(pristine, now, sizeof(now)) != 0); // patched now
const uint32_t want = fl::FL_ADV_VALID_FFX_UPSCALE | fl::FL_ADV_VALID_FFX_MEMORY | fl::FL_ADV_VALID_FFX_FG_CONFIG;
fl::FlAdvancedState a{};
REQUIRE(ReadAdvanced(r, 7u, a, 0u, fl::FL_ADV_VALID_FFX_UPSCALE | fl::FL_ADV_VALID_FFX_MEMORY));
REQUIRE(ReadAdvanced(r, 7u, a, 0u, want));
// A few seconds of it, so the count is one a restart can be told from.
for (int i = 0; i < 20 && a.ffxDispatches < 300u; ++i) {
REQUIRE(ReadAdvanced(r, 7u, a, a.samples, fl::FL_ADV_VALID_FFX_UPSCALE | fl::FL_ADV_VALID_FFX_MEMORY));
REQUIRE(ReadAdvanced(r, 7u, a, a.samples, want));
}
INFO("mask 0x" << std::hex << a.validMask << std::dec << " dispatches " << a.ffxDispatches << " queries "
<< a.ffxMemoryQueries << " frameTime " << a.ffxFrameTimeCount << "/" << a.ffxFrameTimeSumUs
@@ -6912,9 +7190,26 @@ TEST_CASE("region 5 stays empty until the Agent asks, then carries what an FSR t
// hands the same query on to the leaf and both are hooked.
CHECK(a.ffxMemoryTotalBytes == kAdvMemoryTotal);
CHECK(a.ffxMemoryAliasableBytes == kAdvMemoryAliasable);
CHECK(SlConstantsAreUnread(a)); // an FSR title with no Streamline: nothing calls slSetConstants
CHECK(a.ffxMemoryQueries != 0u);
CHECK(a.ffxMemoryQueries <= a.ffxDispatches + 2u);
CHECK(LaterGroupsAreZero(a));
// How the target configures frame generation: one configure a frame, counted ONCE though the loader hands it on
// to the leaf's export and both are hooked (twice would be past the dispatches), and the key-value configure
// beside it not at all. On, never asynchronous, never generated-only, one flag, the whole 1920x1080.
INFO("fg configures " << a.ffxFgConfigures << " enabled " << a.ffxFgEnabledSeen << " async " << a.ffxFgAsyncSeen
<< " flags 0x" << std::hex << a.ffxFgFlagsSeen << std::dec);
CHECK(a.ffxFgConfigures != 0u);
CHECK(a.ffxFgConfigures <= a.ffxDispatches + 2u);
CHECK(a.ffxFgConfigures * 2u > a.ffxDispatches);
CHECK(a.ffxFgEnabledSeen == 2u);
CHECK(a.ffxFgAsyncSeen == 1u);
CHECK(a.ffxFgOnlyGeneratedSeen == 1u);
CHECK(a.ffxFgFlagsSeen == kAdvFfxFgFlags);
CHECK(a.ffxFgRect[0] == 0);
CHECK(a.ffxFgRect[1] == 0);
CHECK(a.ffxFgRect[2] == kAdvFfxFgRectWidth);
CHECK(a.ffxFgRect[3] == kAdvFfxFgRectHeight);
// ---- 3. NOT ASKED AGAIN. Nothing more is read, and nothing more is written: the region is what it was.
SetAdvancedRequest(r, 0u);
@@ -6940,6 +7235,30 @@ TEST_CASE("region 5 stays empty until the Agent asks, then carries what an FSR t
CHECK(r.st->faultCount == 0u);
CHECK(r.st->status == fl::FL_STATUS_READY);
// The log, written by the watchdog unasked: the two configure patches by module and symbol, and each configure
// type each module was handed -- the frame-generation one (0x20002) and the key-value one (0x20006).
std::wstring log;
std::string text;
for (int i = 0; i < 60; ++i) {
++r.ctl->guardTicks;
if (log.empty() && !FindOverlayLog(child.pi.dwProcessId, child.pi.hProcess, log)) {
Sleep(100);
continue;
}
text = ReadWholeFile(log);
if (LogHasLine(text, "FFX_CONFIGURE", "amd_fidelityfx_loader_dx12.dll", " b=0x20006")) {
break;
}
Sleep(100);
}
INFO("log:\n" << text);
CHECK(LogHasLine(text, "HOOK_INSTALLED", "amd_fidelityfx_loader_dx12.dll!ffxConfigure", ""));
CHECK(LogHasLine(text, "HOOK_INSTALLED", "amd_fidelityfx_framegeneration_dx12.dll!ffxConfigure", ""));
CHECK(LogHasLine(text, "FFX_CONFIGURE", "amd_fidelityfx_loader_dx12.dll", " b=0x20002"));
CHECK(LogHasLine(text, "FFX_CONFIGURE", "amd_fidelityfx_loader_dx12.dll", " b=0x20006"));
CHECK(LogHasLine(text, "FFX_CONFIGURE", "amd_fidelityfx_framegeneration_dx12.dll", " b=0x20002"));
CHECK(text.find("PATCH_FAILED") == std::string::npos);
}
TEST_CASE("FSR's plane at infinity (beta.42, D119): a far plane of FLT_MAX reaches region 5 as +infinity, beside "
@@ -6978,10 +7297,14 @@ TEST_CASE("FSR's plane at infinity (beta.42, D119): a far plane of FLT_MAX reach
CHECK(r.st->status == fl::FL_STATUS_READY);
}
TEST_CASE("region 5 carries the DLSS options a title chains into its evaluation, and only while asked",
TEST_CASE("region 5 carries what a Streamline title chains into its evaluation and tells slSetConstants, and "
"slSetConstants is patched only once the Agent has asked",
"[guard][inject][shm][advanced]") {
// ONE TARGET, FOUR STRETCHES: never asked -> asked -> no longer asked -> stopped. The target does the same thing
// throughout: it chains an sl::DLSSOptions into every evaluation and calls slSetConstants for two viewports every
// frame, with the matrices and the camera's position and axes set to loud, changing values.
Child child;
REQUIRE(StartHarness(child, L"--real --advanced --hold-presenting-upscaled 30"));
REQUIRE(StartHarness(child, L"--real --advanced --hold-presenting-upscaled 60"));
ResetFake();
g.modules = {"kernel32.dll"};
@@ -6994,19 +7317,42 @@ TEST_CASE("region 5 carries the DLSS options a title chains into its evaluation,
return; // not reached after the REQUIRE; said in the form a static analyser follows (cpp:S2259)
}
REQUIRE(WaitForIdentityHook(r.st));
const auto slConstants = static_cast<uint32_t>(fl::FL_HOOK_SL_CONSTANTS);
// Not asked: the evaluation is hooked, the options are chained into every one, and none of it is kept.
// ---- 1. NEVER ASKED (owner decision D111): the evaluation is hooked, the game calls slSetConstants every frame,
// and that export is not patched -- its first bytes in the target are the file's -- nor is anything kept.
unsigned char pristine[16]{};
unsigned char inFile[16]{};
unsigned char now[16]{};
REQUIRE(ReadTargetExportBytes(child.pi.dwProcessId, FL_STUB_SL_INTERPOSER, "slSetConstants", pristine, inFile));
CHECK(std::memcmp(pristine, inFile, sizeof(inFile)) == 0); // the file's bytes: nothing has patched it
const std::uint64_t atHooks = r.st->writeIndex;
TickFor(r, 2500);
TickFor(r, 2500); // two watchdog ticks and more: every row that installs unasked has had its chance
REQUIRE(r.st->writeIndex > atHooks + 30u);
CHECK(RegionFiveIsZero(r));
CHECK((r.st->hooksInstalledMask & slConstants) == 0u);
REQUIRE(ReadTargetExportBytes(child.pi.dwProcessId, FL_STUB_SL_INTERPOSER, "slSetConstants", now));
CHECK(std::memcmp(pristine, now, sizeof(now)) == 0);
// ---- 2. ASKED: the patch goes in on the tick that sees the request, and the next publications carry both groups.
SetAdvancedRequest(r, 1u);
REQUIRE(WaitForHookFamily(r.st, slConstants));
REQUIRE(ReadTargetExportBytes(child.pi.dwProcessId, FL_STUB_SL_INTERPOSER, "slSetConstants", now));
CHECK(std::memcmp(pristine, now, sizeof(now)) != 0); // patched now
fl::FlAdvancedState a{};
REQUIRE(ReadAdvanced(r, 1u, a, 0u, fl::FL_ADV_VALID_DLSS_OPTIONS));
INFO("mask 0x" << std::hex << a.validMask << std::dec << " version " << a.dlssStructVersion << " seen "
<< a.dlssOptionsSeen << " output " << a.dlssOutputWidth << "x" << a.dlssOutputHeight);
CHECK(a.validMask == static_cast<uint32_t>(fl::FL_ADV_VALID_DLSS_OPTIONS)); // no ffx call in this target
REQUIRE(ReadAdvanced(r, 1u, a, 0u, fl::FL_ADV_VALID_DLSS_OPTIONS | fl::FL_ADV_VALID_SL_CONSTANTS));
// A reset arrives on one frame in sixty-four and both halves of each alternation within two: read on until the
// summaries hold all of them (bounded by ReadAdvanced's own wait, a few publications).
for (int i = 0; i < 8 && (a.slResets == 0u || a.slFovMinBits == a.slFovMaxBits); ++i) {
REQUIRE(ReadAdvanced(r, 1u, a, a.samples, fl::FL_ADV_VALID_DLSS_OPTIONS | fl::FL_ADV_VALID_SL_CONSTANTS));
}
INFO("mask 0x" << std::hex << a.validMask << " true 0x" << a.slFlagsSeenTrue << " false 0x" << a.slFlagsSeenFalse
<< std::dec << " calls " << a.slConstantsCalls << " resets " << a.slResets << " version "
<< a.dlssStructVersion << " output " << a.dlssOutputWidth << "x" << a.dlssOutputHeight);
CHECK(a.validMask == static_cast<uint32_t>(fl::FL_ADV_VALID_DLSS_OPTIONS | fl::FL_ADV_VALID_SL_CONSTANTS));
// The options chained into the evaluation, as before.
CHECK(a.dlssStructVersion == 3u); // the version these headers declare, which is what entitles the tail
CHECK(a.dlssOptionsSeen != 0u);
CHECK(a.dlssOutputWidth == kAdvDlssOutputW);
@@ -7025,11 +7371,70 @@ TEST_CASE("region 5 carries the DLSS options a title chains into its evaluation,
CHECK(a.dlssColorBuffersHdr == 1u);
CHECK(a.dlssAutoExposure == 2u);
CHECK(a.dlssAlphaUpscaling == 2u);
CHECK(a.ffxDispatches == 0u);
// What the game told slSetConstants for the FIRST viewport: exactly the harness's numbers, and not one of the
// second viewport's (near 9, far 99, a field of view of 2, depth not inverted, an orthographic projection).
CHECK(a.slConstantsCalls > 60u); // both viewports' calls are counted
CHECK(a.slJitterMaxXBits == BitsOf(kAdvSlJitterX));
CHECK(a.slJitterMaxYBits == BitsOf(kAdvSlJitterY));
CHECK(a.slMvecScaleXBits == BitsOf(kAdvSlMvecScaleX));
CHECK(a.slMvecScaleYBits == BitsOf(kAdvSlMvecScaleY));
CHECK(a.slNearBits == BitsOf(kAdvSlNear));
CHECK(a.slFarBits == BitsOf(kAdvSlFar));
CHECK(a.slFovMinBits == BitsOf(kAdvSlFovLow)); // a range, never a series (D114)
CHECK(a.slFovMaxBits == BitsOf(kAdvSlFovHigh));
CHECK(a.slAspectBits == BitsOf(kAdvSlAspect));
// Bits in the header's order: depthInverted 0, cameraMotionIncluded 1, motionVectors3D 2, reset 3,
// orthographicProjection 4, motionVectorsDilated 5, motionVectorsJittered 6.
CHECK(a.slFlagsSeenTrue == ((1u << 0) | (1u << 1) | (1u << 3) | (1u << 6)));
CHECK(a.slFlagsSeenFalse == ((1u << 2) | (1u << 3) | (1u << 4) | (1u << 5)));
CHECK(a.slResets >= 1u);
CHECK(a.slResets * 32u < a.slConstantsCalls); // one frame in sixty-four of ONE viewport, not of both
CHECK(a.ffxDispatches == 0u); // no ffx call in this target
CHECK(a.ffxSharpnessMinBits == FL_ADV_FLOAT_NONE); // a float nobody saw is "none", never 0.0
CHECK(a.ffxMemoryQueries == 0u);
CHECK(FfxFgConfigIsUnread(a)); // a Streamline title with no FidelityFX: nothing calls ffxConfigure
CHECK(LaterGroupsAreZero(a));
// ---- 3. NO LONGER ASKED: the detour forwards without looking, the region is as it was left, and the patch stays
// (it is never taken out mid-session).
SetAdvancedRequest(r, 0u);
TickFor(r, 1500);
fl::FlAdvancedState held{};
std::memcpy(&held, RegionFive(r), sizeof(held));
TickFor(r, 2500);
CHECK(std::memcmp(&held, RegionFive(r), sizeof(held)) == 0);
CHECK((r.st->hooksInstalledMask & slConstants) != 0u);
REQUIRE(ReadTargetExportBytes(child.pi.dwProcessId, FL_STUB_SL_INTERPOSER, "slSetConstants", now));
CHECK(std::memcmp(pristine, now, sizeof(now)) != 0);
CHECK(r.st->faultCount == 0u);
CHECK(r.st->status == fl::FL_STATUS_READY);
// ---- 4. STOPPED: the export's first bytes are the file's again, and the log says which patch was restored.
r.ctl->unhookRequested = 1;
for (int i = 0; i < 60 && r.st->status != fl::FL_STATUS_UNHOOKED; ++i) {
++r.ctl->guardTicks;
Sleep(50);
}
REQUIRE(r.st->status == fl::FL_STATUS_UNHOOKED);
std::wstring log;
std::string text;
for (int i = 0; i < 100; ++i) {
if ((!log.empty() || FindOverlayLog(child.pi.dwProcessId, child.pi.hProcess, log))) {
text = ReadWholeFile(log);
if (text.find("STOP_FLUSHED") != std::string::npos) {
break;
}
}
Sleep(100);
}
INFO("after the stop:\n" << text);
REQUIRE(ReadTargetExportBytes(child.pi.dwProcessId, FL_STUB_SL_INTERPOSER, "slSetConstants", now));
CHECK(std::memcmp(pristine, now, sizeof(now)) == 0);
CHECK(text.find("HOOK_INSTALLED sl.interposer.dll!slSetConstants") != std::string::npos);
CHECK(text.find("UNHOOK_RESTORED sl.interposer.dll!slSetConstants") != std::string::npos);
CHECK(text.find("UNHOOK_DECLINED") == std::string::npos);
CHECK(text.find("PATCH_FAILED") == std::string::npos);
}
@@ -225,6 +225,8 @@ const char* CollectedName(fl::guard::Collected c) {
return "INCOMPLETE";
case fl::guard::Collected::kRetry:
return "RETRY (still loading, or gone)";
case fl::guard::Collected::kUnsettled:
return "UNSETTLED (the list changed while it was read)";
}
return "?";
}
+386 -12
View File
@@ -97,7 +97,7 @@
// an FSR title does: one UPSCALE and one PREPARE (issued twice,
// same frameID) per application frame, one FRAMEGENERATION per
// frame at K > 1, then K presents (--presents-per-eval K)
// --ffx-topology 1x|2x|ue|fsr3host|fsr3host+mono
// --ffx-topology 1x|2x|2x-export|ue|fsr3host|fsr3host+mono
// which vendor shape --hold-presenting-ffx stands in: 2x (default)
// is the SDK 2.x pair of effect DLLs behind the LOADER (the game
// calls the loader; the loader forwards NOT through the leaves'
@@ -115,7 +115,16 @@
// --advanced send what Advanced metrics reads (train B, 0.1.0-beta.40): --hold-presenting-upscaled chains an
// sl::DLSSOptions into slEvaluateFeature's inputs, --hold-presenting-ffx fills the rest of the
// UPSCALE descriptor (sharpening, jitter, exposure, depth range, field of view, flags, frame time).
// The values are the kAdv* constants below; the injected fl_guard cases assert them
// The values are the kAdv* constants below; the injected fl_guard cases assert them.
// Since 0.1.0-beta.43 the upscaled hold also calls slSetConstants every frame, for viewport 0
// (kAdvSl*) and for a second viewport whose numbers must never be shown, with the matrices and
// the camera's position and axes - which the Overlay never reads - set to loud, changing values;
// and the ffx hold calls ffxConfigure every frame with a frame-generation configuration
// (kAdvFfxFg*) and with a key-value one, the swapchain, the contexts, the HUD-less resource and
// the frame id - never read either - loud and changing
// --churn-module <dll>
// load and free the module in a loop on a thread of its own, for the life of the process: a
// module list that keeps changing under whoever reads it (the guard's D123, 2026-11-12)
// --ffx-infinite-far
// with --advanced: the UPSCALE descriptor's cameraFar is FLT_MAX, as an engine with an infinite
// depth states the plane at infinity (0.1.0-beta.42, D119), instead of kAdvFfxFar
@@ -1999,6 +2008,17 @@ bool ProbeSlInputs() {
// send. A UNIT PROBE, as --probe-sl-inputs is: what matters here is a struct of an OLDER VERSION than these headers
// declare, whose tail must not be read (owner decision D115), and the vendors' own sentinels and zeros, which must
// never leave the header as values. No fixture title can be made to send a version-1 DLSSOptions; this can.
// A read of sl::Constants at an address chosen by the caller, in a function of its own so that the SEH frame holds no
// object with a destructor. True when the read faulted.
bool ObserveSlConstantsFaults(const void* constants, fl::adv::Accumulators& a) {
__try {
fl::adv::ObserveSlConstants(*static_cast<const sl::Constants*>(constants), 0u, a);
return false;
} __except (EXCEPTION_EXECUTE_HANDLER) {
return true;
}
}
bool ProbeAdvFields() {
g_failures = 0;
const auto bitsOf = [](float v) { return std::bit_cast<uint32_t>(v); };
@@ -2308,6 +2328,228 @@ bool ProbeAdvFields() {
"and nothing of the session before: no mask, no count, no range, no size");
delete region;
}
// --- sl::Constants, what the game tells Streamline about a frame (0.1.0-beta.43) ------------------------------
{
fl::adv::Accumulators a;
sl::Constants c;
c.jitterOffset = {-0.375f, 0.25f};
c.mvecScale = {0.5f, 0.25f};
c.cameraNear = 0.1f;
c.cameraFar = 5000.0f;
c.cameraFOV = 1.0f;
c.cameraAspectRatio = 1.6f;
c.depthInverted = sl::Boolean::eTrue;
c.cameraMotionIncluded = sl::Boolean::eFalse;
c.reset = sl::Boolean::eFalse;
c.motionVectorsJittered = sl::Boolean::eTrue; // motionVectors3D is left in its third state
fl::adv::ObserveSlConstants(c, 3u, a);
c.jitterOffset = {0.125f, -0.4375f};
c.cameraFOV = 0.6f;
c.reset = sl::Boolean::eTrue;
fl::adv::ObserveSlConstants(c, 3u, a);
Check(a.validMask.load() == fl::FL_ADV_VALID_SL_CONSTANTS && a.slConstantsCalls.load() == 2u,
"two calls, counted, and the group marked read");
Check(a.slJitterMaxXBits.load() == bitsOf(0.375f) && a.slJitterMaxYBits.load() == bitsOf(0.4375f),
"the jitter is the largest magnitude on each axis");
Check(a.slMvecScaleXBits.load() == bitsOf(0.5f) && a.slMvecScaleYBits.load() == bitsOf(0.25f),
"the motion-vector scale is kept");
Check(a.slNearBits.load() == bitsOf(0.1f) && a.slFarBits.load() == bitsOf(5000.0f), "the depth range is kept");
Check(a.slFovMinBits.load() == bitsOf(0.6f) && a.slFovMaxBits.load() == bitsOf(1.0f),
"the field of view is a range, lowest and highest (D114)");
Check(a.slAspectBits.load() == bitsOf(1.6f), "the aspect ratio is kept");
// Bits in the header's order: depthInverted 0, cameraMotionIncluded 1, motionVectors3D 2, reset 3,
// orthographicProjection 4, motionVectorsDilated 5, motionVectorsJittered 6.
Check(a.slFlagsSeenTrue.load() == ((1u << 0) | (1u << 3) | (1u << 6)),
"a Boolean seen true sets its bit: depth inverted, reset, jittered");
Check(a.slFlagsSeenFalse.load() == ((1u << 1) | (1u << 3) | (1u << 4) | (1u << 5)),
"a Boolean seen false sets its bit in the other word; one in its third state sets neither");
Check(a.slResets.load() == 1u, "a reset is counted");
// A SECOND VIEWPORT is counted as a call and summarised nowhere.
sl::Constants other;
other.jitterOffset = {0.9f, 0.9f};
other.cameraNear = 9.0f;
other.cameraFar = 99.0f;
other.cameraFOV = 2.0f;
other.depthInverted = sl::Boolean::eFalse;
other.reset = sl::Boolean::eTrue;
fl::adv::ObserveSlConstants(other, 4u, a);
Check(a.slConstantsCalls.load() == 3u, "a call for another viewport is a call");
Check(a.slNearBits.load() == bitsOf(0.1f) && a.slFovMaxBits.load() == bitsOf(1.0f) &&
a.slJitterMaxXBits.load() == bitsOf(0.375f) && a.slResets.load() == 1u &&
(a.slFlagsSeenFalse.load() & 1u) == 0u,
"and the summaries stay the first viewport's: no value, range, flag or reset of the second");
// The handle's own "no viewport" value is a viewport like another.
fl::adv::Accumulators last;
fl::adv::ObserveSlConstants(c, 0xFFFFFFFFu, last);
fl::adv::ObserveSlConstants(other, 0u, last);
Check(last.slNearBits.load() == bitsOf(0.1f) && last.slConstantsCalls.load() == 2u,
"a first viewport of 0xFFFFFFFF owns the summaries; viewport 0 after it does not");
// SENTINELS: a struct the game set nothing in. FLT_MAX is Streamline's INVALID_FLOAT - on THIS route it is
// "not set", never the plane at infinity (D119 is the ffx route's).
fl::adv::Accumulators unset;
sl::Constants blank;
fl::adv::ObserveSlConstants(blank, 0u, unset);
Check(unset.slNearBits.load() == FL_ADV_FLOAT_NONE && unset.slFarBits.load() == FL_ADV_FLOAT_NONE &&
unset.slFovMinBits.load() == FL_ADV_FLOAT_NONE && unset.slAspectBits.load() == FL_ADV_FLOAT_NONE &&
unset.slJitterMaxXBits.load() == FL_ADV_FLOAT_NONE &&
unset.slMvecScaleXBits.load() == FL_ADV_FLOAT_NONE,
"INVALID_FLOAT - FLT_MAX - is 'no value' in every member, a depth plane included");
Check(unset.slFlagsSeenTrue.load() == 0u &&
unset.slFlagsSeenFalse.load() == ((1u << 4) | (1u << 5) | (1u << 6)),
"the four Booleans in their third state are neither; the three the vendor defaults to false are false");
blank.cameraFOV = -1.0f;
blank.cameraAspectRatio = 0.0f;
blank.jitterOffset = {0.5f, std::bit_cast<float>(0x7FC00000u)};
fl::adv::ObserveSlConstants(blank, 0u, unset);
Check(unset.slFovMinBits.load() == FL_ADV_FLOAT_NONE && unset.slAspectBits.load() == FL_ADV_FLOAT_NONE &&
unset.slJitterMaxXBits.load() == FL_ADV_FLOAT_NONE,
"a field of view or an aspect ratio that is not positive is not one; half a jitter is no jitter");
// WHERE THE MEMBERS ARE, by the addresses of this build's own struct: the two ranges never read are bytes
// 32..351 (five matrices) and 368..423 (the pinhole offset, the camera's position and its three axes).
const auto at = [&c](const void* member) {
return static_cast<size_t>(static_cast<const unsigned char*>(member) -
reinterpret_cast<const unsigned char*>(&c));
};
Check(at(&c.cameraViewToClip) == 32u && at(&c.jitterOffset) == 352u && at(&c.mvecScale) == 360u,
"the five matrices are bytes 32..351; the jitter and the scale follow at 352 and 360");
Check(at(&c.cameraPinholeOffset) == 368u && at(&c.cameraNear) == 424u,
"the pinhole offset, the camera's position and its axes are bytes 368..423; the near plane is at 424");
// NOTHING OF THOSE TWO RANGES REACHES WHAT IS PUBLISHED. Two structs alike in every member that is read and
// different in every byte that is not: the accumulators come out byte for byte the same.
sl::Constants p = c;
sl::Constants q = c;
std::memset(reinterpret_cast<unsigned char*>(&p) + 32u, 0x11, 352u - 32u);
std::memset(reinterpret_cast<unsigned char*>(&p) + 368u, 0x11, 424u - 368u);
std::memset(reinterpret_cast<unsigned char*>(&q) + 32u, 0xEE, 352u - 32u);
std::memset(reinterpret_cast<unsigned char*>(&q) + 368u, 0xEE, 424u - 368u);
auto* regionP = new fl::FlAdvancedState{};
auto* regionQ = new fl::FlAdvancedState{};
fl::adv::Accumulators ap;
fl::adv::Accumulators aq;
fl::adv::ObserveSlConstants(p, 0u, ap);
fl::adv::ObserveSlConstants(q, 0u, aq);
fl::adv::Publish(ap, regionP, 5u, 1u);
fl::adv::Publish(aq, regionQ, 5u, 1u);
Check(std::memcmp(regionP, regionQ, sizeof(fl::FlAdvancedState)) == 0 && regionP->slNearBits == bitsOf(0.1f) &&
regionP->slConstantsCalls == 1u,
"two structs that differ only in the matrices and the camera publish the same bytes");
delete regionP;
delete regionQ;
// A VERSION-1 STRUCT ENDS WHERE VERSION 2's MEMBER BEGINS, and is read no further: laid against a page that
// cannot be read, it is read whole and nothing faults.
const size_t v1Size = at(&c.minRelativeLinearDepthObjectSeparation);
auto* pages =
static_cast<unsigned char*>(VirtualAlloc(nullptr, 8192, MEM_COMMIT | MEM_RESERVE, PAGE_READWRITE));
DWORD old = 0;
if (pages == nullptr || !VirtualProtect(pages + 4096, 4096, PAGE_NOACCESS, &old)) {
Check(false, "two pages, the second unreadable, for the version-1 struct");
} else {
unsigned char* v1 = pages + 4096 - v1Size;
std::memcpy(v1, &c, v1Size);
fl::adv::Accumulators edge;
Check(!ObserveSlConstantsFaults(v1, edge),
"a version-1 struct at the end of readable memory is read without a fault");
Check(edge.slNearBits.load() == bitsOf(0.1f) && edge.slFlagsSeenTrue.load() != 0u,
"and what it carries is read: the last member version 1 has is the last one read");
VirtualFree(pages, 0, MEM_RELEASE);
}
}
// --- ffxConfigure with a frame-generation descriptor (0.1.0-beta.43) -------------------------------------------
{
fl::adv::Accumulators a;
ffxConfigureDescFrameGeneration c{};
c.header.type = FFX_API_CONFIGURE_DESC_TYPE_FRAMEGENERATION;
c.frameGenerationEnabled = true;
c.allowAsyncWorkloads = false;
c.onlyPresentGenerated = false;
c.flags = FFX_FRAMEGENERATION_FLAG_DRAW_DEBUG_VIEW;
c.generationRect = {10, 20, 2560, 1440};
fl::adv::ObserveFfxConfigure(3u, &c.header, a);
c.frameGenerationEnabled = false; // the player switched it off in the menu
c.flags = FFX_FRAMEGENERATION_FLAG_DRAW_DEBUG_TEAR_LINES;
c.generationRect = {0, 0, 1920, 1080};
fl::adv::ObserveFfxConfigure(3u, &c.header, a);
Check(a.validMask.load() == fl::FL_ADV_VALID_FFX_FG_CONFIG && a.ffxFgConfigures.load() == 2u,
"two frame-generation configures, counted, and the group marked read");
Check(a.ffxFgEnabledSeen.load() == 3u, "generation seen on and seen off: both bits");
Check(a.ffxFgAsyncSeen.load() == 1u && a.ffxFgOnlyGeneratedSeen.load() == 1u,
"a switch only ever seen off sets the 'off' bit alone");
Check(a.ffxFgFlagsSeen.load() ==
(FFX_FRAMEGENERATION_FLAG_DRAW_DEBUG_VIEW | FFX_FRAMEGENERATION_FLAG_DRAW_DEBUG_TEAR_LINES),
"the flags are every bit any configure carried");
Check(a.ffxFgRect.load() == fl::adv::PackRect(0, 0, 1920, 1080), "the rectangle is the last one, whole");
// The same call arriving at a second hooked module - the leaf behind the loader - is passed over.
fl::adv::ObserveFfxConfigure(2u, &c.header, a);
Check(a.ffxFgConfigures.load() == 2u, "one module's configures are counted, not one per hook");
// ANOTHER CONFIGURE TYPE through the same call is not a frame-generation configuration: only its type is
// looked at. A key-value descriptor is shorter than the one above, so reading it as one would run past it.
fl::adv::Accumulators other;
ffxConfigureDescFrameGenerationKeyValue kv{};
kv.header.type = FFX_API_CONFIGURE_DESC_TYPE_FRAMEGENERATION_KEYVALUE;
kv.key = 0xFFFFFFFFFFFFFFFFull;
kv.u64 = 0xFFFFFFFFFFFFFFFFull;
fl::adv::ObserveFfxConfigure(0u, &kv.header, other);
fl::adv::ObserveFfxConfigure(0u, nullptr, other);
Check(other.validMask.load() == 0u && other.ffxFgConfigures.load() == 0u && other.ffxFgOwner.load() == 0u,
"a configure of another type, and no descriptor at all, read nothing and own nothing");
// WHAT IS NEVER READ CHANGES NOTHING: two descriptors alike in the five members read and different in the
// swapchain, the callbacks' contexts, the HUD-less resource and the frame id publish the same bytes.
ffxConfigureDescFrameGeneration p = c;
ffxConfigureDescFrameGeneration q = c;
p.swapChain = reinterpret_cast<void*>(static_cast<uintptr_t>(0x1111));
p.presentCallbackUserContext = reinterpret_cast<void*>(static_cast<uintptr_t>(0x2222));
p.frameGenerationCallbackUserContext = reinterpret_cast<void*>(static_cast<uintptr_t>(0x3333));
p.HUDLessColor.resource = reinterpret_cast<void*>(static_cast<uintptr_t>(0x4444));
p.frameID = 5u;
q.swapChain = reinterpret_cast<void*>(static_cast<uintptr_t>(0xEEEE));
q.presentCallbackUserContext = reinterpret_cast<void*>(static_cast<uintptr_t>(0xDDDD));
q.frameGenerationCallbackUserContext = reinterpret_cast<void*>(static_cast<uintptr_t>(0xCCCC));
q.HUDLessColor.resource = reinterpret_cast<void*>(static_cast<uintptr_t>(0xBBBB));
q.frameID = 0xFFFFFFFFFFFFull;
auto* regionP = new fl::FlAdvancedState{};
auto* regionQ = new fl::FlAdvancedState{};
fl::adv::Accumulators ap;
fl::adv::Accumulators aq;
fl::adv::ObserveFfxConfigure(1u, &p.header, ap);
fl::adv::ObserveFfxConfigure(1u, &q.header, aq);
fl::adv::Publish(ap, regionP, 9u, 1u);
fl::adv::Publish(aq, regionQ, 9u, 1u);
Check(std::memcmp(regionP, regionQ, sizeof(fl::FlAdvancedState)) == 0 && regionP->ffxFgConfigures == 1u,
"two configurations that differ only in what is never read publish the same bytes");
Check(regionP->ffxFgRect[0] == 0 && regionP->ffxFgRect[1] == 0 && regionP->ffxFgRect[2] == 1920 &&
regionP->ffxFgRect[3] == 1080 && regionP->ffxFgEnabledSeen == 1u,
"the rectangle lands as left, top, width, height; the switches as their two bits");
delete regionP;
delete regionQ;
// A RECTANGLE THAT DOES NOT FIT IS NOBODY'S, never a clipped one.
Check(fl::adv::PackRect(-1, 0, 100, 100) == fl::adv::kRectUnfit &&
fl::adv::PackRect(0, 0, 0x8000, 100) == fl::adv::kRectUnfit &&
fl::adv::PackRect(0, 0, 0x7FFF, 0x7FFF) != fl::adv::kRectUnfit,
"a negative side or one past fifteen bits makes the rectangle 'unfit'; the largest that fits is kept");
fl::adv::Accumulators big;
c.generationRect = {0, 0, 100000, 1080};
fl::adv::ObserveFfxConfigure(0u, &c.header, big);
auto* regionBig = new fl::FlAdvancedState{};
fl::adv::Publish(big, regionBig, 9u, 1u);
Check(regionBig->ffxFgRect[0] == -1 && regionBig->ffxFgRect[1] == -1 && regionBig->ffxFgRect[2] == -1 &&
regionBig->ffxFgRect[3] == -1,
"and is published as four -1, which no rectangle is");
delete regionBig;
}
return g_failures == 0;
}
@@ -2760,6 +3002,23 @@ constexpr float kAdvFfxFar = 1000.0f;
constexpr float kAdvFfxFovLow = 0.9f; // radians; the two alternate, frame by frame
constexpr float kAdvFfxFovHigh = 1.1f;
constexpr float kAdvFfxFrameTimeMs = 16.0f;
// What --advanced hands slSetConstants (0.1.0-beta.43), for viewport 0. The jitter and the field of view alternate
// frame by frame; `reset` is true on one frame in sixty-four. A SECOND viewport (7) is set every frame with
// different numbers, which must never be the ones a session shows.
constexpr float kAdvSlJitterX = 0.3125f; // the larger magnitude of the two that alternate
constexpr float kAdvSlJitterY = 0.4375f;
constexpr float kAdvSlMvecScaleX = 0.5f;
constexpr float kAdvSlMvecScaleY = 0.25f;
constexpr float kAdvSlNear = 0.25f;
constexpr float kAdvSlFar = 4000.0f;
constexpr float kAdvSlFovLow = 0.8f;
constexpr float kAdvSlFovHigh = 1.2f;
constexpr float kAdvSlAspect = 1.75f;
constexpr uint32_t kAdvSlOtherViewport = 7u;
// What --advanced hands ffxConfigure before each frame's frame-generation dispatches (0.1.0-beta.43).
constexpr uint32_t kAdvFfxFgFlags = FFX_FRAMEGENERATION_FLAG_DRAW_DEBUG_PACING_LINES;
constexpr int32_t kAdvFfxFgRectWidth = 1920;
constexpr int32_t kAdvFfxFgRectHeight = 1080;
using StubTokenFn = sl::Result(STDMETHODCALLTYPE*)(sl::FrameToken*&, const uint32_t*);
alignas(16) unsigned char g_dummyFrameToken[64]{};
@@ -2860,6 +3119,41 @@ int HoldPresentingUpscaled(Gfx& g, int seconds, bool real, sl::Feature feature,
options.performancePreset = sl::DLSSPreset::ePresetM;
options.ultraPerformancePreset = sl::DLSSPreset::ePresetL;
const sl::BaseStructure* advancedInputs[] = {&options};
// --advanced, 0.1.0-beta.43: the per-frame constants, through the stub's slSetConstants. Everything the Overlay may
// read is a known value; EVERYTHING IT MAY NOT -- the five matrices, the pinhole offset, the camera's position and
// axes -- is filled with loud numbers that change every frame, so a read of them would show in what is published.
// The frame token by address, as the other stub entry points take it: a reference parameter is a pointer in
// the ABI, and the harness has no token object, only storage of the right size.
using StubSetConstantsFn =
sl::Result(STDMETHODCALLTYPE*)(const sl::Constants&, const void*, const sl::ViewportHandle&);
auto setConstants =
reinterpret_cast<StubSetConstantsFn>(reinterpret_cast<void*>(GetProcAddress(stub, "slSetConstants")));
if (advanced && setConstants == nullptr) {
Check(false, "the stub exports slSetConstants");
return 1;
}
sl::Constants constants;
sl::Constants otherConstants;
sl::ViewportHandle otherViewport{kAdvSlOtherViewport};
constants.mvecScale = {kAdvSlMvecScaleX, kAdvSlMvecScaleY};
constants.cameraNear = kAdvSlNear;
constants.cameraFar = kAdvSlFar;
constants.cameraAspectRatio = kAdvSlAspect;
constants.depthInverted = sl::Boolean::eTrue;
constants.cameraMotionIncluded = sl::Boolean::eTrue;
constants.motionVectors3D = sl::Boolean::eFalse;
constants.orthographicProjection = sl::Boolean::eFalse;
constants.motionVectorsDilated = sl::Boolean::eFalse;
constants.motionVectorsJittered = sl::Boolean::eTrue;
otherConstants.jitterOffset = {0.9f, 0.9f};
otherConstants.mvecScale = {9.0f, 9.0f};
otherConstants.cameraNear = 9.0f;
otherConstants.cameraFar = 99.0f;
otherConstants.cameraFOV = 2.0f;
otherConstants.cameraAspectRatio = 9.0f;
otherConstants.depthInverted = sl::Boolean::eFalse;
otherConstants.orthographicProjection = sl::Boolean::eTrue;
if (advanced) {
std::printf(" --advanced: an sl::DLSSOptions (version %zu, output %ux%u) chained into every evaluation\n",
options.structVersion, kAdvDlssOutputW, kAdvDlssOutputH);
@@ -2878,6 +3172,23 @@ int HoldPresentingUpscaled(Gfx& g, int seconds, bool real, sl::Feature feature,
} else {
setTag(viewport, tags, numTags, nullptr);
}
if (advanced) {
const bool odd = (evaluated & 1) != 0;
const float loud = static_cast<float>(evaluated % 977) + 1000.0f;
constants.jitterOffset = {odd ? -kAdvSlJitterX : 0.125f, odd ? 0.0625f : -kAdvSlJitterY};
constants.cameraFOV = odd ? kAdvSlFovLow : kAdvSlFovHigh;
constants.reset = (evaluated % 64) == 5 ? sl::Boolean::eTrue : sl::Boolean::eFalse;
// What must never be read: a different loud value in each, every frame.
constants.cameraViewToClip.row[0] = {loud, loud + 1.0f, loud + 2.0f, loud + 3.0f};
constants.clipToPrevClip.row[3] = {loud + 4.0f, loud + 5.0f, loud + 6.0f, loud + 7.0f};
constants.cameraPinholeOffset = {loud + 8.0f, loud + 9.0f};
constants.cameraPos = {loud + 10.0f, loud + 11.0f, loud + 12.0f};
constants.cameraUp = {loud + 13.0f, loud + 14.0f, loud + 15.0f};
constants.cameraRight = {loud + 16.0f, loud + 17.0f, loud + 18.0f};
constants.cameraFwd = {loud + 19.0f, loud + 20.0f, loud + 21.0f};
setConstants(constants, g_dummyFrameToken, viewport);
setConstants(otherConstants, g_dummyFrameToken, otherViewport);
}
// ONE EVALUATION PER PRESENT, which is what a real upscaled title does
// and what makes the drained record's identity checkable frame by frame.
eval(feature, g_dummyFrameToken, advanced ? advancedInputs : nullptr, advanced ? 1u : 0u, nullptr);
@@ -3019,7 +3330,9 @@ int HoldPresentingFg(Gfx& g, int seconds, bool real, int presentsPerEval) {
// DLL alone (its named UPSCALE export, no PREPARE, no frame generation -- the K = 1
// double-count control for that row), fsr3host+mono = Cyberpunk 2077's measured shape:
// the host upscales while the 1.1.x monolith prepares and generates.
enum class FfxTopology { Monolith, Loader, Ue, Fsr3Host, Fsr3HostMonolith };
// LoaderExport (2026-11-12, D125): the two leaves behind a loader that forwards a dispatch to their EXPORTS, as
// Cyberpunk 2077's loader 2.3.0 was measured to -- every dispatch then reaches two hooked modules.
enum class FfxTopology { Monolith, Loader, LoaderExport, Ue, Fsr3Host, Fsr3HostMonolith };
using PfnFsr3DispatchUpscale = decltype(&fsr3host::ffxFsr3ContextDispatchUpscale);
@@ -3078,6 +3391,19 @@ void AskQuality(PfnFfxQuery query, FfxQuery what) {
}
}
// --churn-module <dll>: one thread that loads and frees the module for as long as the process lives (D123's fixture).
wchar_t g_churnPath[MAX_PATH * 2]{};
DWORD WINAPI ChurnModuleThread(LPVOID) {
for (;;) {
if (HMODULE h = LoadLibraryW(g_churnPath); h != nullptr) {
FreeLibrary(h);
} else {
Sleep(1);
}
}
}
// --ffx-infinite-far (with --advanced): cameraFar is FLT_MAX rather than kAdvFfxFar.
bool g_ffxInfiniteFar = false;
@@ -3120,16 +3446,17 @@ int HoldPresentingFfx(Gfx& g, int seconds, bool real, int presentsPerEval, FfxTo
Check(false, "the SDK 2.x leaf stubs loaded for the ffx hold");
return 1;
}
if (topology == FfxTopology::Loader) {
if (topology == FfxTopology::Loader || topology == FfxTopology::LoaderExport) {
const HMODULE loader = LoadStubExactly(FL_STUB_FFX_LOADER);
if (loader == nullptr) {
Check(false, "the loader stub loaded for the ffx hold");
return 1;
}
auto bind =
reinterpret_cast<StubLoaderBindFn>(reinterpret_cast<void*>(GetProcAddress(loader, "FlStubLoaderBind")));
auto bind = reinterpret_cast<StubLoaderBindFn>(reinterpret_cast<void*>(
GetProcAddress(loader, topology == FfxTopology::LoaderExport ? "FlStubLoaderBindThroughExports"
: "FlStubLoaderBind")));
if (bind == nullptr) {
Check(false, "the loader stub exports FlStubLoaderBind");
Check(false, "the loader stub exports its bind entry");
return 1;
}
bind(upscaler, fg);
@@ -3166,9 +3493,12 @@ int HoldPresentingFfx(Gfx& g, int seconds, bool real, int presentsPerEval, FfxTo
return 1;
}
// The pre-V2 PREPARE is the 1.1.x monolith's, on both topologies that use it.
const bool topology2x = topology == FfxTopology::Loader || topology == FfxTopology::Ue;
const char* topologyName = topology == FfxTopology::Monolith ? "SDK 1.1.x (monolith)"
: topology == FfxTopology::Loader ? "SDK 2.x (two leaves behind the loader)"
const bool topology2x =
topology == FfxTopology::Loader || topology == FfxTopology::LoaderExport || topology == FfxTopology::Ue;
const char* topologyName = topology == FfxTopology::Monolith ? "SDK 1.1.x (monolith)"
: topology == FfxTopology::Loader ? "SDK 2.x (two leaves behind the loader)"
: topology == FfxTopology::LoaderExport
? "SDK 2.x (two leaves behind a loader that forwards to their exports)"
: topology == FfxTopology::Ue ? "UE5 (two leaves, no loader)"
: topology == FfxTopology::Fsr3Host ? "FSR 3.0 host DLL alone"
: "FSR 3.0 host DLL + SDK 1.1.x monolith";
@@ -3229,6 +3559,28 @@ int HoldPresentingFfx(Gfx& g, int seconds, bool real, int presentsPerEval, FfxTo
hostUp.renderSize.width = kTaggedRenderW;
hostUp.renderSize.height = kTaggedRenderH;
// --advanced, 0.1.0-beta.43: the frame-generation configuration a title sends every frame, and beside it a
// configure of another type, which the Overlay passes over. What may be read is a known value; WHAT MAY NOT --
// the swapchain, the callbacks' contexts, the HUD-less resource, the frame id -- is loud and changes every frame.
// Nothing is dereferenced: the stub looks at none of it.
const PfnFfxConfigure configureFg =
advanced && prepare && fgEntry != nullptr
? reinterpret_cast<PfnFfxConfigure>(reinterpret_cast<void*>(GetProcAddress(fgEntry, "ffxConfigure")))
: nullptr;
ffxConfigureDescFrameGeneration cfg{};
cfg.header.type = FFX_API_CONFIGURE_DESC_TYPE_FRAMEGENERATION;
cfg.frameGenerationEnabled = true;
cfg.allowAsyncWorkloads = false;
cfg.onlyPresentGenerated = false;
cfg.flags = kAdvFfxFgFlags;
cfg.generationRect = {0, 0, kAdvFfxFgRectWidth, kAdvFfxFgRectHeight};
ffxConfigureDescFrameGenerationKeyValue otherCfg{};
otherCfg.header.type = FFX_API_CONFIGURE_DESC_TYPE_FRAMEGENERATION_KEYVALUE;
if (advanced && prepare && fgEntry != nullptr && configureFg == nullptr) {
Check(false, "the frame-generation entry exports ffxConfigure");
return 1;
}
const ULONGLONG until = GetTickCount64() + static_cast<ULONGLONG>(seconds) * 1000ULL;
long long presented = 0;
long long frames = 0;
@@ -3254,6 +3606,16 @@ int HoldPresentingFfx(Gfx& g, int seconds, bool real, int presentsPerEval, FfxTo
} else {
dispatchUp(nullptr, &up.header);
}
if (configureFg != nullptr) {
const uintptr_t loud = 0x1000u + static_cast<uintptr_t>(frameId % 977u) * 0x10u;
cfg.swapChain = reinterpret_cast<void*>(loud);
cfg.presentCallbackUserContext = reinterpret_cast<void*>(loud + 1u);
cfg.frameGenerationCallbackUserContext = reinterpret_cast<void*>(loud + 2u);
cfg.HUDLessColor.resource = reinterpret_cast<void*>(loud + 3u);
cfg.frameID = frameId;
configureFg(nullptr, &cfg.header);
configureFg(nullptr, &otherCfg.header);
}
if (prepare && dispatchFg != nullptr) {
// TWICE, SAME frameID: the SDK's own sample re-issues the prepare when its
// configuration changes, and the vendor's contract is about the INDEX. A
@@ -3468,6 +3830,7 @@ int main(int argc, char** argv) {
} else if (std::strcmp(argv[i], "--ffx-topology") == 0 && i + 1 < argc) {
const char* t = argv[++i];
ffxTopology = std::strcmp(t, "1x") == 0 ? FfxTopology::Monolith
: std::strcmp(t, "2x-export") == 0 ? FfxTopology::LoaderExport
: std::strcmp(t, "ue") == 0 ? FfxTopology::Ue
: std::strcmp(t, "fsr3host") == 0 ? FfxTopology::Fsr3Host
: std::strcmp(t, "fsr3host+mono") == 0 ? FfxTopology::Fsr3HostMonolith
@@ -3505,6 +3868,17 @@ int main(int argc, char** argv) {
} else {
i += 2;
}
} else if (std::strcmp(argv[i], "--churn-module") == 0 && i + 1 < argc) {
// The fixture for D123: a process whose module list keeps changing, as a game's does at its launch. One
// thread loads and frees the named module for the life of the process.
const char* path = argv[++i];
MultiByteToWideChar(CP_ACP, 0, path, -1, g_churnPath, static_cast<int>(std::size(g_churnPath)));
HANDLE t = CreateThread(nullptr, 0, &ChurnModuleThread, nullptr, 0, nullptr);
std::printf(" --churn-module %s -> %s\n", path, t != nullptr ? "started" : "FAILED");
if (t == nullptr) {
return 3;
}
CloseHandle(t);
} else if (std::strcmp(argv[i], "--load") == 0 && i + 1 < argc) {
// The fixture for the guard's signer half: put a named module into
// THIS process before the guard looks. Loaded, not injected, and it
@@ -3529,11 +3903,11 @@ int main(int argc, char** argv) {
std::strcmp(argv[i], "--advanced") == 0 || std::strcmp(argv[i], "--ffx-memory-query") == 0 ||
std::strcmp(argv[i], "--ffx-infinite-far") == 0 || std::strcmp(argv[i], "--sl-tag-whole-resource") == 0 ||
std::strcmp(argv[i], "--sl-tag-dlssg-inputs") == 0 || std::strcmp(argv[i], "--load") == 0 ||
std::strcmp(argv[i], "--load-after-ms") == 0) {
std::strcmp(argv[i], "--churn-module") == 0 || std::strcmp(argv[i], "--load-after-ms") == 0) {
if (std::strcmp(argv[i], "--plus-ui") == 0 || std::strcmp(argv[i], "--present-interval-ms") == 0 ||
std::strcmp(argv[i], "--presents-per-eval") == 0 || std::strcmp(argv[i], "--ffx-topology") == 0 ||
std::strcmp(argv[i], "--ffx-query") == 0 || std::strcmp(argv[i], "--ffx-memory-query") == 0 ||
std::strcmp(argv[i], "--load") == 0) {
std::strcmp(argv[i], "--load") == 0 || std::strcmp(argv[i], "--churn-module") == 0) {
++i;
}
if (std::strcmp(argv[i], "--load-after-ms") == 0) {
@@ -26,6 +26,16 @@
//
// IT IS A FIXTURE, NOT A CLAIM ABOUT THE REAL LOADER'S INTERNALS beyond the one
// measured fact: the leaf exports stay silent behind it.
//
// AND A SECOND MEASURED FACT, 2026-11-12, FOR A LATER LOADER. Cyberpunk 2077's
// loader 2.3.0 hands a dispatch on to the leaf's EXPORT: each frame-generation
// dispatch type was logged on the loader and on the frame-generation leaf. So the
// stub has a second way to be bound -- FlStubLoaderBindThroughExports -- that
// forwards through the leaves' exported ffxDispatch, and with all four modules
// hooked the Overlay then sees every dispatch at two of them. What it does with
// that is owner decision D125: an UPSCALE is counted at the first module that
// sees it. No title run so far upscales through such a loader; the fixture is how
// the rule is held.
#include <ffx_api.h>
@@ -51,7 +61,7 @@ Bound g_upscaler;
Bound g_frameGeneration;
volatile LONG g_forwarded = 0;
void Bind(Bound& b, HMODULE h) {
void Bind(Bound& b, HMODULE h, bool dispatchThroughExport = false) {
if (h == nullptr) {
b = Bound{};
return;
@@ -60,9 +70,10 @@ void Bind(Bound& b, HMODULE h) {
b.destroy = reinterpret_cast<PfnFfxDestroyContext>(reinterpret_cast<void*>(GetProcAddress(h, "ffxDestroyContext")));
b.configure = reinterpret_cast<PfnFfxConfigure>(reinterpret_cast<void*>(GetProcAddress(h, "ffxConfigure")));
b.query = reinterpret_cast<PfnFfxQuery>(reinterpret_cast<void*>(GetProcAddress(h, "ffxQuery")));
// DISPATCH GOES THROUGH THE DIRECT ENTRY, NOT THE EXPORT -- see the header comment.
b.dispatch =
reinterpret_cast<PfnFfxDispatch>(reinterpret_cast<void*>(GetProcAddress(h, "FlStubFfxDispatchDirect")));
// DISPATCH GOES THROUGH THE DIRECT ENTRY, NOT THE EXPORT -- see the header comment -- unless this is the later
// loader's shape (FlStubLoaderBindThroughExports).
b.dispatch = reinterpret_cast<PfnFfxDispatch>(
reinterpret_cast<void*>(GetProcAddress(h, dispatchThroughExport ? "ffxDispatch" : "FlStubFfxDispatchDirect")));
}
// Route by EFFECT ID, which is what the real loader's provider lookup keys on
@@ -90,6 +101,12 @@ __declspec(dllexport) void FlStubLoaderBind(HMODULE upscaler, HMODULE frameGener
Bind(g_frameGeneration, frameGeneration);
}
// The loader 2.3 shape (measured on Cyberpunk 2077, 2026-11-12): dispatches are handed to the leaves' exports.
__declspec(dllexport) void FlStubLoaderBindThroughExports(HMODULE upscaler, HMODULE frameGeneration) {
Bind(g_upscaler, upscaler, true);
Bind(g_frameGeneration, frameGeneration, true);
}
__declspec(dllexport) unsigned int FlStubLoaderForwarded() {
return static_cast<unsigned int>(InterlockedCompareExchange(&g_forwarded, 0, 0));
}
@@ -62,6 +62,9 @@ StubFrameToken g_tokenPool[8];
static_assert(fl::stub::InventoryHas("slGetNewFrameToken"),
"fl_hook_inventory.h no longer contains \"slGetNewFrameToken\", so the frame-token fixture would "
"exercise a row the Overlay does not install.");
static_assert(fl::stub::InventoryHas("slSetConstants"),
"fl_hook_inventory.h no longer contains \"slSetConstants\", so the constants fixture would exercise a "
"row the Overlay does not install.");
static_assert(fl::stub::InventoryHas("slSetTagForFrame"),
"fl_hook_inventory.h no longer contains \"slSetTagForFrame\", so the frame-based tag fixture would "
"exercise a row the Overlay does not install.");
@@ -144,6 +147,16 @@ SL_API sl::Result slIsFeatureLoaded(sl::Feature feature, bool& loaded) {
return sl::Result::eOk;
}
// The per-frame constants (0.1.0-beta.43). Signature from the vendored header, like the others. The stub keeps
// nothing: the harness hands it known values and the injected cases assert what the Overlay read of them.
SL_API sl::Result slSetConstants(const sl::Constants& values, const sl::FrameToken& frame,
const sl::ViewportHandle& viewport) {
(void)values;
(void)frame;
(void)viewport;
return sl::Result::eOk;
}
SL_API sl::Result slGetNewFrameToken(sl::FrameToken*& token, const uint32_t* frameIndex) {
// The vendor's contract in miniature: an explicit index returns THAT frame's
// token (the same object on a re-request), no index advances to a new one.
@@ -302,6 +302,19 @@ public sealed class AgentEndToEndTests : IDisposable
facts.Single(static f => string.Equals(f.Id, "ffx.upscale.flags", StringComparison.Ordinal)).Value.Tokens.Should().Equal("non_linear_color_pq");
facts.Should().NotContain(static f => f.Id.StartsWith("sl.", StringComparison.Ordinal), "this target chains no DLSS options");
// 0.1.0-beta.43: the frame-generation configuration the harness sends through ffxConfigure before each frame
// (kAdvFfxFg*), read by a hook that was not in the game during the first session - nothing had asked - and
// was installed when this one did. Streamline's library is not in this target at all, and the row says that
// rather than "the game never called".
Rows("ffx.framegen.config").Should().Equal(
"frameGenerationEnabled=on",
"allowAsyncWorkloads=off",
"onlyPresentGenerated=off",
"flags=DRAW_DEBUG_PACING_LINES",
"generationRect=1920 × 1080 at 0, 0");
sources.FsrFrameGeneration.Should().Be(AdvancedInGameCall.Read, row.FactsJson);
sources.StreamlineConstants.Should().Be(AdvancedInGameCall.NotHooked, row.FactsJson);
IReadOnlyDictionary<string, Application.Recording.SensorSeriesStats> stats = AdvancedJson.ParseStats(row.StatsJson);
stats.Should().ContainKey(InGameAdvancedSampler.FrameTimeSeries, row.StatsJson);
stats[InGameAdvancedSampler.FrameTimeSeries].Mean.Should().BeApproximately(16.0, 0.01, "every dispatch states 16 ms");
@@ -241,7 +241,7 @@ public sealed class AdvancedPresenterTests
At(live, id).Status.Should().Be(Strings.Advanced_Status_InGame);
}
At(live, "ffx.framegen.config").Status.Should().Be(AdvancedLabels.Reach(AdvancedReach.NewHook), "a hook that is not built is still a later release");
At(live, "sl.feature.versions").Status.Should().Be(AdvancedLabels.Reach(AdvancedReach.NewHook), "a hook that is not built is still a later release");
live.Where(static r => r.IsRead).Should().HaveCount(AdvancedMetricCatalog.All.Count(static m => m.IsRead));
}
@@ -281,6 +281,36 @@ public sealed class AdvancedPresenterTests
}
}
[Fact]
public void ASessionsSourcesLineSaysForEachCallHookedOnlyForAdvancedMetricsWhichOfThreeThingsHappened()
{
// 0.1.0-beta.43: read, hooked and never made by the game, or not hooked. A row stored before has neither
// member, and a session not measured inside the game has none to speak of: the sentence is not there.
AdvancedSources hooked = AdvancedFixtures.Sources with { InGame = AdvancedInGameStatus.Reading };
string before = AdvancedPresenter.SourcesLine(hooked);
before.Should().NotContain(AdvancedLabels.InGameCall(AdvancedInGameCall.NeverCalled)).And.NotContain(AdvancedLabels.InGameCall(AdvancedInGameCall.NotHooked));
string line = AdvancedPresenter.SourcesLine(hooked with
{
StreamlineConstants = AdvancedInGameCall.NeverCalled,
FsrFrameGeneration = AdvancedInGameCall.Read,
});
line.Should().StartWith(before, "what was said before is said as before");
line.Should().EndWith(string.Format(
CultureInfo.CurrentCulture,
Strings.Advanced_InGameCallsLine,
AdvancedLabels.InGameCall(AdvancedInGameCall.NeverCalled),
AdvancedLabels.InGameCall(AdvancedInGameCall.Read)));
foreach (AdvancedInGameCall call in Enum.GetValues<AdvancedInGameCall>())
{
AdvancedLabels.InGameCall(call).Should().NotBe(call.ToString(), "every state has words of its own in every language");
}
AdvancedLabels.InGameCall(AdvancedInGameCall.NeverCalled).Should().NotBe(AdvancedLabels.InGameCall(AdvancedInGameCall.NotHooked), "the two reasons a value is absent are not one");
}
[Fact]
public void AValueIsShownInItsUnitAndAFlagAsYesOrNo()
{
@@ -145,7 +145,7 @@ public sealed class AdvancedJsonTests
new("nvapi.gpu.board_serial", Instance: null, AdvancedValue.OfText("0123456789")),
new("nvapi.display.edid", "1", AdvancedValue.OfText("00ffffffffffff00")),
new("sl.constants.camera", Instance: null, AdvancedValue.OfText("1.0 2.0 3.0")),
new("sl.constants.jitter", Instance: null, AdvancedValue.OfText("0.25 0.25")),
new("sl.feature.versions", Instance: null, AdvancedValue.OfText("DLSS 3.7.0")),
new("sl.dlss.presets", Instance: null, AdvancedValue.OfRows([new AdvancedRow("DLAA", "K")])),
new("no.such.metric", Instance: null, AdvancedValue.Of(1)),
new("lhm.board.model", Instance: null, AdvancedValue.OfText("ASUS ROG STRIX Z790-E")),
@@ -171,6 +171,30 @@ public sealed class AdvancedJsonTests
sources.InGame.Should().BeNull("a row that never said is not a row that said no");
}
[Fact]
public void WhatBecameOfTheTwoCallsHookedOnlyForAdvancedMetricsSurvivesTheLedgerAndAnOlderRowSaysNothingOfThem()
{
AdvancedSources written = AdvancedSources.Unknown with
{
InGame = AdvancedInGameStatus.Reading,
StreamlineConstants = AdvancedInGameCall.NeverCalled,
FsrFrameGeneration = AdvancedInGameCall.Read,
};
string json = AdvancedJson.OfSession([], written);
(_, AdvancedSources read) = AdvancedJson.ParseSession(json);
json.Should().Contain("\"streamlineConstants\":\"NeverCalled\"").And.Contain("\"fsrFrameGeneration\":\"Read\"");
read.Should().Be(written);
// 0.1.0-beta.42 wrote exactly this: the in-game state and neither of the two.
const string beta42 = """{"facts":[],"sources":{"nvapi":"Reading","sensors":"Reading","elevatedSensors":"Reading","inGame":"Reading"}}""";
(_, AdvancedSources older) = AdvancedJson.ParseSession(beta42);
older.InGame.Should().Be(AdvancedInGameStatus.Reading);
older.StreamlineConstants.Should().BeNull("a row that never said is not a row that said the hook was not in");
older.FsrFrameGeneration.Should().BeNull();
}
[Theory]
[InlineData(AdvancedInGameStatus.Reading)]
[InlineData(AdvancedInGameStatus.NothingSeen)]
@@ -106,12 +106,17 @@ public sealed partial class AdvancedMetricCatalogTests
{
// Train B, 0.1.0-beta.40: thirteen entries, each a member of a call the Overlay already hooked - and each
// matched by a name on tools/overlay-allowed-fields.txt, which a build gate holds to the Overlay's own code.
// 0.1.0-beta.43: six more, from the two calls hooked only for Advanced metrics (slSetConstants, ffxConfigure).
// Everything else of Streamline and FidelityFX is still named, not read; NGX and XeSS are never read.
string[] inGame = [.. _all.Where(static m => m.Reach == AdvancedReach.Game).Select(static m => m.Id)];
inGame.Should().Equal(
"sl.dlss.output_size", "sl.dlss.presets", "sl.dlss.hdr_input", "sl.dlss.auto_exposure", "sl.dlss.alpha_upscaling", "sl.dlss.exposure",
"ffx.upscale.sharpening", "ffx.upscale.jitter", "ffx.upscale.exposure", "ffx.upscale.depth", "ffx.upscale.flags",
"ffx.upscale.frame_time_delta", "ffx.memory_usage");
"ffx.upscale.frame_time_delta", "ffx.memory_usage",
"sl.constants.jitter", "sl.constants.motion_vectors", "sl.constants.depth", "sl.constants.projection", "sl.constants.resets",
"ffx.framegen.config");
// The camera's position, axes and matrices are in the same struct as the constants read, and are the player's.
AdvancedMetricCatalog.Find("sl.constants.camera")!.Reach.Should().Be(AdvancedReach.PlayerState);
_all.Where(static m => m.Reach == AdvancedReach.Game).Should().OnlyContain(static m => m.Source == AdvancedSource.Streamline || m.Source == AdvancedSource.FidelityFx);
_all.Where(static m => m.Reach == AdvancedReach.Game).Should().OnlyContain(static m => m.Scope != AdvancedScope.MachineFact, "what a game says is of a session, never of the PC");
@@ -215,13 +215,133 @@ public sealed class InGameAdvancedSamplerTests
Rows(Fact(sampler, "ffx.upscale.depth")).Should().Contain("cameraFovAngleVertical=0.9 – 1.3 rad (51.6° – 74.5°)");
}
[Fact]
public void WhatTheGameTellsStreamlineEachFrameBecomesFiveFactsOfTheFirstViewport()
{
// 0.1.0-beta.43: slSetConstants. The jitter as its largest magnitude, the field of view as a range, each
// Boolean as what it was seen to be over the session - and nothing of the camera's position, axes or
// matrices, which the capture side never reads.
var sampler = new InGameAdvancedSampler();
sampler.Take(new InGameAdvanced(InGameStates.Streamline()));
Rows(Fact(sampler, "sl.constants.jitter")).Should().Equal("jitterOffset.x=≤ 0.3125", "jitterOffset.y=≤ 0.4375");
AdvancedFact motion = Fact(sampler, "sl.constants.motion_vectors");
Rows(motion).Should().Equal(
"mvecScale.x=0.5", "mvecScale.y=0.25", "cameraMotionIncluded=on", "motionVectors3D=off", "motionVectorsDilated=off", "motionVectorsJittered=on");
motion.Value.Rows![2].Token.Should().Be("on", "the App translates the word");
Rows(Fact(sampler, "sl.constants.depth")).Should().Equal("cameraNear=0.25", "cameraFar=4000", "depthInverted=on");
Rows(Fact(sampler, "sl.constants.projection")).Should().Equal(
"cameraFOV=0.8 – 1.2 rad (45.8° – 68.8°)", "cameraAspectRatio=1.75", "orthographicProjection=off");
Fact(sampler, "sl.constants.resets").Value.Number.Should().Be(1);
sampler.Facts.Should().NotContain(static f => string.Equals(f.Id, "sl.constants.camera", StringComparison.Ordinal));
sampler.Facts.Should().Contain(static f => string.Equals(f.Id, "sl.dlss.presets", StringComparison.Ordinal), "the options of the same game stay beside them");
}
[Fact]
public void AStreamlineConstantNobodySetIsAbsentAndAPlaneAtInfinityIsNotStreamlines()
{
// FLT_MAX is Streamline's "not set" and never reaches the Agent; if the pattern D119 gives FSR's planes turned up
// here it would still be no value. A Boolean seen neither way has no row; a reset never seen is a count of 0.
var sampler = new InGameAdvancedSampler();
sampler.Take(new InGameAdvanced(InGameStates.Empty() with
{
ValidMask = FlAdvancedValid.SlConstants,
SlConstantsCalls = 60,
SlNearBits = FlAdvancedState.FloatInfinite,
SlFarBits = BitConverter.SingleToUInt32Bits(500f),
SlFlagsSeenFalse = 1u << 4,
}));
Rows(Fact(sampler, "sl.constants.depth")).Should().Equal("cameraFar=500");
Rows(Fact(sampler, "sl.constants.projection")).Should().Equal("orthographicProjection=off");
Fact(sampler, "sl.constants.resets").Value.Number.Should().Be(0, "the game called and never reset the history: that is a fact");
sampler.Facts.Should().NotContain(static f => f.Id == "sl.constants.jitter" || f.Id == "sl.constants.motion_vectors");
}
[Fact]
public void HowTheGameConfiguresFsrFrameGenerationIsOneFactOfSwitchesFlagsAndTheRectangle()
{
var sampler = new InGameAdvancedSampler();
sampler.Take(new InGameAdvanced(InGameStates.FrameGeneration()));
AdvancedFact config = Fact(sampler, "ffx.framegen.config");
Rows(config).Should().Equal(
"frameGenerationEnabled=on", "allowAsyncWorkloads=off", "onlyPresentGenerated=off", "flags=DRAW_DEBUG_PACING_LINES", "generationRect=1920 × 1080 at 0, 0");
config.Value.Rows![0].Token.Should().Be("on");
// Switched off in the menu part-way, a flag the vendor's header does not name, and a rectangle the capture side
// could not state (four -1): both states are said, the bit is shown as it is, and there is no rectangle row.
var other = new InGameAdvancedSampler();
other.Take(new InGameAdvanced(InGameStates.WithRect(
InGameStates.FrameGeneration() with { FfxFgEnabledSeen = 3, FfxFgFlagsSeen = (1u << 0) | (1u << 9), FfxFgAsyncSeen = 0 }, -1, -1, -1, -1)));
Rows(Fact(other, "ffx.framegen.config")).Should().Equal(
"frameGenerationEnabled=on_and_off", "onlyPresentGenerated=off", "flags=DRAW_DEBUG_TEAR_LINES, bit 9");
// A rectangle with no area is one the game did not give.
var none = new InGameAdvancedSampler();
none.Take(new InGameAdvanced(InGameStates.WithRect(InGameStates.FrameGeneration() with { FfxFgFlagsSeen = 0 }, 0, 0, 0, 0)));
Rows(Fact(none, "ffx.framegen.config")).Should().Equal("frameGenerationEnabled=on", "allowAsyncWorkloads=off", "onlyPresentGenerated=off");
}
[Fact]
public void ACountDoesNotRebuildTheFactsWhileTheSessionRunsAndIsExactOnceItConcludes()
{
// The resets told to Streamline are a count. While the session runs the list is rebuilt only when a value a
// fact is made of moves - the session's context is rewritten on every new list - so the count is as of the
// last rebuild; Conclude brings it to the last publication, once.
var sampler = new InGameAdvancedSampler();
sampler.Take(new InGameAdvanced(InGameStates.Streamline(1, resets: 1)));
IReadOnlyList<AdvancedFact> first = sampler.Facts;
sampler.Take(new InGameAdvanced(InGameStates.Streamline(2, resets: 5)));
sampler.Facts.Should().BeSameAs(first, "a count alone rebuilds nothing");
Fact(sampler, "sl.constants.resets").Value.Number.Should().Be(1);
sampler.Conclude();
sampler.Facts.Should().NotBeSameAs(first);
Fact(sampler, "sl.constants.resets").Value.Number.Should().Be(5);
IReadOnlyList<AdvancedFact> concluded = sampler.Facts;
sampler.Conclude();
sampler.Facts.Should().BeSameAs(concluded, "nothing moved since");
var empty = new InGameAdvancedSampler();
empty.Conclude();
empty.Facts.Should().BeEmpty("a session that read nothing has nothing to bring up to date");
}
[Fact]
public void ACallHookedOnlyForAdvancedMetricsIsReadOrHookedAndNeverMadeOrNotHooked()
{
var sampler = new InGameAdvancedSampler();
sampler.Call(FlAdvancedValid.SlConstants, hookedIn: false).Should().Be(AdvancedInGameCall.NotHooked);
sampler.Call(FlAdvancedValid.SlConstants, hookedIn: true).Should().Be(AdvancedInGameCall.NeverCalled);
sampler.Take(new InGameAdvanced(InGameStates.Streamline()));
sampler.Call(FlAdvancedValid.SlConstants, hookedIn: true).Should().Be(AdvancedInGameCall.Read);
sampler.Call(FlAdvancedValid.SlConstants, hookedIn: false).Should().Be(AdvancedInGameCall.Read, "a publication that carried it is the proof, whatever the hook word says");
sampler.Call(FlAdvancedValid.FfxFgConfig, hookedIn: true).Should().Be(AdvancedInGameCall.NeverCalled, "the other call is its own question");
// Read once is read for the session, though a later publication - a new request's - does not carry it.
sampler.Take(new InGameAdvanced(InGameStates.Ffx(2)));
sampler.Call(FlAdvancedValid.SlConstants, hookedIn: true).Should().Be(AdvancedInGameCall.Read);
}
[Fact]
public void EveryFactItMakesIsAnEntryTheCatalogSaysIsReadInsideAGame()
{
var sampler = new InGameAdvancedSampler();
FlAdvancedState both = InGameStates.Ffx() with
FlAdvancedState both = InGameStates.WithRect(InGameStates.Streamline(), 0, 0, 2560, 1440) with
{
ValidMask = FlAdvancedValid.DlssOptions | FlAdvancedValid.FfxUpscale | FlAdvancedValid.FfxMemory,
FfxFgConfigures = 60,
FfxFgEnabledSeen = 2,
FfxSharpenSeen = 2,
FfxFlagsSeen = 1u << 2,
FfxFrameTimeCount = 60,
FfxFrameTimeSumUs = 60 * 16_000,
FfxMemoryTotalBytes = 256UL * 1024 * 1024,
FfxMemoryQueries = 60,
ValidMask = FlAdvancedValid.DlssOptions | FlAdvancedValid.FfxUpscale | FlAdvancedValid.FfxMemory | FlAdvancedValid.FfxFgConfig | FlAdvancedValid.SlConstants,
DlssOutputWidth = 3840,
DlssOutputHeight = 2160,
DlssColorBuffersHdr = 2,
@@ -230,6 +350,7 @@ public sealed class InGameAdvancedSamplerTests
IReadOnlyList<AdvancedReading> readings = sampler.Take(new InGameAdvanced(both))!;
sampler.Facts.Should().OnlyContain(static f => AdvancedMetricCatalog.Find(f.Id)!.Reach == AdvancedReach.Game);
sampler.Facts.Select(static f => f.Id).Should().Contain(["sl.constants.jitter", "sl.constants.resets", "ffx.framegen.config", "ffx.upscale.flags", "sl.dlss.presets"]);
AdvancedJson.Storable(sampler.Facts).Should().HaveCount(sampler.Facts.Count, "what the game said may be stored");
readings.Select(static r => AdvancedMetricCatalog.Find(r.Series[AdvancedMetric.SeriesPrefix.Length..])!.Reach).Should().OnlyContain(static reach => reach == AdvancedReach.Game);
}
@@ -33,6 +33,15 @@ internal static class InGameStates
FfxFarBits = FlAdvancedState.FloatNone,
FfxFovMinBits = FlAdvancedState.FloatNone,
FfxFovMaxBits = FlAdvancedState.FloatNone,
SlJitterMaxXBits = FlAdvancedState.FloatNone,
SlJitterMaxYBits = FlAdvancedState.FloatNone,
SlMvecScaleXBits = FlAdvancedState.FloatNone,
SlMvecScaleYBits = FlAdvancedState.FloatNone,
SlNearBits = FlAdvancedState.FloatNone,
SlFarBits = FlAdvancedState.FloatNone,
SlFovMinBits = FlAdvancedState.FloatNone,
SlFovMaxBits = FlAdvancedState.FloatNone,
SlAspectBits = FlAdvancedState.FloatNone,
};
/// <summary>The DLSS options <c>hook-harness --advanced</c> chains into its evaluation, as the vendor's values plus one.</summary>
@@ -78,6 +87,57 @@ internal static class InGameStates
FfxMemoryQueries = 60 * samples,
};
/// <summary>
/// What <c>hook-harness --advanced</c> hands <c>slSetConstants</c> for its first viewport (0.1.0-beta.43), beside the
/// DLSS options of the same target. Bits in the vendor header's order: depthInverted 0, cameraMotionIncluded 1,
/// motionVectors3D 2, reset 3, orthographicProjection 4, motionVectorsDilated 5, motionVectorsJittered 6.
/// </summary>
public static FlAdvancedState Streamline(uint samples = 1, uint resets = 1) => Dlss(samples) with
{
ValidMask = FlAdvancedValid.DlssOptions | FlAdvancedValid.SlConstants,
SlConstantsCalls = 120 * samples,
SlResets = resets,
SlJitterMaxXBits = Bits(0.3125f),
SlJitterMaxYBits = Bits(0.4375f),
SlMvecScaleXBits = Bits(0.5f),
SlMvecScaleYBits = Bits(0.25f),
SlNearBits = Bits(0.25f),
SlFarBits = Bits(4000f),
SlFovMinBits = Bits(0.8f),
SlFovMaxBits = Bits(1.2f),
SlAspectBits = Bits(1.75f),
SlFlagsSeenTrue = (1u << 0) | (1u << 1) | (1u << 3) | (1u << 6),
SlFlagsSeenFalse = (1u << 2) | (1u << 3) | (1u << 4) | (1u << 5),
};
/// <summary>The frame-generation configuration the same harness hands <c>ffxConfigure</c> (0.1.0-beta.43), beside its FSR dispatch.</summary>
public static FlAdvancedState FrameGeneration(uint samples = 1) => WithRect(
Ffx(samples) with
{
ValidMask = FlAdvancedValid.FfxUpscale | FlAdvancedValid.FfxMemory | FlAdvancedValid.FfxFgConfig,
FfxFgConfigures = 60 * samples,
FfxFgEnabledSeen = 2,
FfxFgAsyncSeen = 1,
FfxFgOnlyGeneratedSeen = 1,
FfxFgFlagsSeen = 1u << 4,
},
0,
0,
1920,
1080);
/// <summary>The generation rectangle - left, top, width, height: a fixed buffer, set through the struct's bytes.</summary>
public static FlAdvancedState WithRect(FlAdvancedState state, int left, int top, int width, int height)
{
int at = (int)Marshal.OffsetOf<FlAdvancedState>(nameof(FlAdvancedState.FfxFgRect));
Span<int> sides = MemoryMarshal.Cast<byte, int>(MemoryMarshal.AsBytes(new Span<FlAdvancedState>(ref state)).Slice(at, 16));
sides[0] = left;
sides[1] = top;
sides[2] = width;
sides[3] = height;
return state;
}
/// <summary>The six preset bytes, DLAA first: a fixed buffer, set through the struct's bytes so no test needs unsafe code.</summary>
public static FlAdvancedState WithPresets(FlAdvancedState state, params ReadOnlySpan<byte> plusOne)
{
@@ -105,8 +105,14 @@ public sealed class SessionRecorderTests : IAsyncDisposable
/// <summary>What each publication carries; null publishes nothing. The count of publications goes in.</summary>
public Func<uint, FlAdvancedState>? Publish { get; init; }
/// <summary>The hook families the capture side says are in: the present hook alone unless a test says more.</summary>
public FlHookFamily Hooks { get; init; } = FlHookFamily.Present;
public List<bool> Asked { get; } = [];
/// <summary>How many publications were handed out.</summary>
public uint Published => _published;
/// <summary>A new publication on every read, as if the watchdog ticked as often as the test's loop.</summary>
public FlAdvancedState? Next() => Publish?.Invoke(++_published);
}
@@ -119,7 +125,7 @@ public sealed class SessionRecorderTests : IAsyncDisposable
public void SetAdvancedRequested(bool requested) => inGame?.Asked.Add(requested);
public FlWriterState WriterState => new() { Status = (uint)FlStatus.Ready, HooksInstalledMask = 1, RuntimeCensus = 0x8000_0000 };
public FlWriterState WriterState => new() { Status = (uint)FlStatus.Ready, HooksInstalledMask = (uint)(inGame?.Hooks ?? FlHookFamily.Present), RuntimeCensus = 0x8000_0000 };
public FlShmHandshake Handshake => new() { AdapterLuid = adapterLuid };
@@ -876,6 +882,10 @@ public sealed class SessionRecorderTests : IAsyncDisposable
facts.Single(static f => string.Equals(f.Id, "ffx.upscale.depth", StringComparison.Ordinal)).Value.Rows!.Select(static x => x.Value).Should().Contain("0.9 – 1.1 rad (51.6° – 63°)");
sources.InGame.Should().Be(AdvancedInGameStatus.Reading);
sources.Nvapi.Should().Be(AdvancedSourceStatus.Reading, "the Agent's own sources are said as before");
// The two calls hooked only for Advanced metrics: this game made neither, and the capture side said neither
// hook was in - "not hooked", which is not "the game never called".
sources.StreamlineConstants.Should().Be(AdvancedInGameCall.NotHooked);
sources.FsrFrameGeneration.Should().Be(AdvancedInGameCall.NotHooked);
// The two series, beside whatever the Agent's own reader gave the same tick.
stored.Sensors.Select(static b => b.Series).Should().Contain([InGameAdvancedSampler.FrameTimeSeries, InGameAdvancedSampler.MemorySeries]);
@@ -887,6 +897,56 @@ public sealed class SessionRecorderTests : IAsyncDisposable
r.Row.Tier.Should().Be(CaptureTier.Hooked);
}
[Fact]
public async Task TheTwoCallsHookedOnlyForAdvancedMetricsAreEachReadOrHookedAndNeverMade()
{
// 0.1.0-beta.43. A game that configures FSR frame generation and does not use Streamline's constants, with
// both hooks in: the configuration is read and stored; of slSetConstants the row says the hook was in and
// the game never made the call - which says something about the game, where "not hooked" would not.
var script = new InGameScript
{
Publish = static n => InGameStates.FrameGeneration(n),
Hooks = FlHookFamily.Present | FlHookFamily.SlConstants | FlHookFamily.FfxConfigure,
};
Harness h = await MakeAsync(advanced: new FakeAdvanced { Latest = FakeAdvanced.Snapshot() }, advancedOn: true, inGame: script);
await h.Recorder.RecordAsync(Request(), TestContext.Current.CancellationToken);
AdvancedSessionRow row = h.Sessions.Stored.Single().Advanced.Should().BeOfType<AdvancedSessionRow>().Subject;
(IReadOnlyList<AdvancedFact> facts, AdvancedSources sources) = AdvancedJson.ParseSession(row.FactsJson);
sources.InGame.Should().Be(AdvancedInGameStatus.Reading);
sources.FsrFrameGeneration.Should().Be(AdvancedInGameCall.Read);
sources.StreamlineConstants.Should().Be(AdvancedInGameCall.NeverCalled);
facts.Single(static f => string.Equals(f.Id, "ffx.framegen.config", StringComparison.Ordinal)).Value.Rows!
.Select(static x => x.Name + "=" + x.Value)
.Should().Contain(["frameGenerationEnabled=on", "generationRect=1920 × 1080 at 0, 0"]);
facts.Should().NotContain(static f => f.Id.StartsWith("sl.constants.", StringComparison.Ordinal));
}
[Fact]
public async Task WhatTheGameToldStreamlineIsStoredWithItsCountAsOfTheEndOfTheSession()
{
// The resets are a count, and a count does not rewrite the session's context while it runs: the stored fact is
// the count of the LAST publication, brought up to date when the session concludes.
var script = new InGameScript
{
Publish = static n => InGameStates.Streamline(n, resets: n),
Hooks = FlHookFamily.Present | FlHookFamily.SlConstants,
};
Harness h = await MakeAsync(advanced: new FakeAdvanced { Latest = FakeAdvanced.Snapshot() }, advancedOn: true, inGame: script);
await h.Recorder.RecordAsync(Request(), TestContext.Current.CancellationToken);
AdvancedSessionRow row = h.Sessions.Stored.Single().Advanced.Should().BeOfType<AdvancedSessionRow>().Subject;
(IReadOnlyList<AdvancedFact> facts, AdvancedSources sources) = AdvancedJson.ParseSession(row.FactsJson);
sources.StreamlineConstants.Should().Be(AdvancedInGameCall.Read);
sources.FsrFrameGeneration.Should().Be(AdvancedInGameCall.NotHooked);
facts.Select(static f => f.Id).Should().Contain(["sl.constants.jitter", "sl.constants.motion_vectors", "sl.constants.depth", "sl.constants.projection", "sl.constants.resets"]);
double resets = facts.Single(static f => string.Equals(f.Id, "sl.constants.resets", StringComparison.Ordinal)).Value.Number!.Value;
resets.Should().BeGreaterThan(1, "more than one publication was taken, each with a higher count");
resets.Should().Be(script.Published, "the count stored is the last publication's, not the first's");
}
[Fact]
public async Task AHookedSessionWhoseGameMadeNoneOfTheCallsSaysSoRatherThanNothing()
{
@@ -920,6 +980,8 @@ public sealed class SessionRecorderTests : IAsyncDisposable
(IReadOnlyList<AdvancedFact> facts, AdvancedSources sources) = AdvancedJson.ParseSession(row.FactsJson);
facts.Should().NotContain(static f => f.Id.StartsWith("ffx.", StringComparison.Ordinal) || f.Id.StartsWith("sl.", StringComparison.Ordinal));
sources.InGame.Should().Be(AdvancedInGameStatus.NotHooked);
sources.StreamlineConstants.Should().BeNull("a session not measured inside the game has no hook to speak of");
sources.FsrFrameGeneration.Should().BeNull();
}
[Fact]
@@ -936,7 +998,14 @@ public sealed class SessionRecorderTests : IAsyncDisposable
row.MachineFactsJson.Should().BeNull();
(IReadOnlyList<AdvancedFact> facts, AdvancedSources sources) = AdvancedJson.ParseSession(row.FactsJson);
facts.Should().BeEmpty("a read that threw costs the session its facts, not itself");
sources.Should().Be(AdvancedSources.Unknown with { InGame = AdvancedInGameStatus.NothingSeen }, "the Agent's sources never answered; the game was measured from inside and made none of the calls");
sources.Should().Be(
AdvancedSources.Unknown with
{
InGame = AdvancedInGameStatus.NothingSeen,
StreamlineConstants = AdvancedInGameCall.NotHooked,
FsrFrameGeneration = AdvancedInGameCall.NotHooked,
},
"the Agent's sources never answered; the game was measured from inside, made none of the calls, and the capture side published neither of the two hooks that are installed only for Advanced metrics");
hub.Released.Should().Be(1);
}
+27
View File
@@ -43,6 +43,33 @@ ffxDispatchDescUpscale::flags
ffxDispatchDescUpscale::reset
ffxDispatchDescUpscale::frameTimeDelta
# sl::Constants, what the game tells slSetConstants about a frame (parameter `k`; 0.1.0-beta.43). The jitter, the
# motion-vector scale, the depth range, the field of view, the aspect ratio and the seven Booleans - numbers and
# switches of the kind a settings menu or a debug overlay shows. The five matrices, the pinhole offset, the camera's
# position and its three axes sit in the same struct and are refused by name wherever they appear (rule 4).
sl::Constants::jitterOffset
sl::Constants::mvecScale
sl::Constants::cameraNear
sl::Constants::cameraFar
sl::Constants::cameraFOV
sl::Constants::cameraAspectRatio
sl::Constants::depthInverted
sl::Constants::cameraMotionIncluded
sl::Constants::motionVectors3D
sl::Constants::reset
sl::Constants::orthographicProjection
sl::Constants::motionVectorsDilated
sl::Constants::motionVectorsJittered
# ffxConfigureDescFrameGeneration, how the game configures FSR frame generation (parameter `g`; 0.1.0-beta.43):
# on or off, asynchronous or not, the flags, generated frames only or not, the rectangle generated in. The swapchain,
# the two callbacks and their contexts, the HUD-less resource and the frame id in the same descriptor are not read.
ffxConfigureDescFrameGeneration::frameGenerationEnabled
ffxConfigureDescFrameGeneration::allowAsyncWorkloads
ffxConfigureDescFrameGeneration::flags
ffxConfigureDescFrameGeneration::onlyPresentGenerated
ffxConfigureDescFrameGeneration::generationRect
# The upscaler's memory query: the header's type, the game's out-pointer in either version of the descriptor
# (parameter `q`), and what ffxQuery wrote through it after answering OK (parameter `m`)
ffxQueryDescHeader::type
+12 -3
View File
@@ -17,9 +17,10 @@
1. The reads are in ONE header, src/native/FrameLedger.Overlay/include/fl_adv_fields.h, through parameters with
fixed names - `o` (sl::DLSSOptions), `d` (ffxDispatchDescUpscale), `m` (FfxApiEffectMemoryUsage), `q` (the
memory query's descriptor) and `desc` (a query's header). Every member read through them is on
memory query's descriptor), `k` (sl::Constants) and `g` (ffxConfigureDescFrameGeneration), both since
0.1.0-beta.43, and `desc` (a query's or a configure's header: one type, ffxApiHeader). Every member read through them is on
tools/overlay-allowed-fields.txt, and every name on that list is read.
2. Those parameters are not aliased: each of the four letters appears only as `x.member` or where it is
2. Those parameters are not aliased: each of the six letters appears only as `x.member` or where it is
declared, and `->` is applied to nothing but `desc` and the Overlay's own `region`. So a member cannot be
read under a name this check does not look at.
3. No other source of the Overlay or the Vulkan layer reads a member the list names (the names every struct
@@ -55,6 +56,8 @@ $script:Parameter = [ordered]@{
d = 'ffxDispatchDescUpscale'
m = 'FfxApiEffectMemoryUsage'
q = 'ffxQueryDescUpscaleGetGPUMemoryUsage'
k = 'sl::Constants'
g = 'ffxConfigureDescFrameGeneration'
desc = 'ffxQueryDescHeader'
}
@@ -103,7 +106,7 @@ function Get-HeaderRead([string]$Code) {
$reads = [System.Collections.Generic.SortedSet[string]]::new([StringComparer]::Ordinal)
$problems = [System.Collections.Generic.List[string]]::new()
foreach ($m in [regex]::Matches($Code, '(?<![\w.>:])(o|d|m|q)\b(\s*\.\s*([A-Za-z_]\w*))?')) {
foreach ($m in [regex]::Matches($Code, '(?<![\w.>:])(o|d|m|q|k|g)\b(\s*\.\s*([A-Za-z_]\w*))?')) {
$name = $m.Groups[1].Value
if ($m.Groups[3].Success) {
[void]$reads.Add("$($script:Parameter[$name])::$($m.Groups[3].Value)")
@@ -210,6 +213,12 @@ inline void Publish(Accumulators& a, FlAdvancedState* region) noexcept { region-
@{ Name = 'a pointer to it, and offsetof into it, pass'; Header = $goodHeader; List = $goodList; Other = $goodOther; Expect = 0 },
@{ Name = 'a name listed twice FAILS'; Header = $goodHeader; List = $goodList + "sl::DLSSOptions::outputWidth`n"; Other = $goodOther; Expect = 1 },
@{ Name = 'a line that is not one Struct::member FAILS'; Header = $goodHeader; List = $goodList + "sl::DLSSOptions::outputWidth # the size`n"; Other = $goodOther; Expect = 1 },
@{ Name = 'sl::Constants read through its parameter, each member on the list, passes'; Header = $goodHeader + "`ninline void ObserveK(const sl::Constants& k, uint32_t viewport, Accumulators& a) noexcept { a.n.store(k.cameraNear + k.jitterOffset.x); }"; List = $goodList + "sl::Constants::cameraNear`nsl::Constants::jitterOffset`n"; Other = $goodOther; Expect = 0 },
@{ Name = 'a member of sl::Constants the list does not allow FAILS'; Header = $goodHeader + "`ninline void ObserveK(const sl::Constants& k, Accumulators& a) noexcept { a.n.store(k.cameraNear + k.cameraFOV); }"; List = $goodList + "sl::Constants::cameraNear`n"; Other = $goodOther; Expect = 1 },
@{ Name = 'the camera read through the sl::Constants parameter FAILS, listed or not'; Header = $goodHeader + "`ninline void ObserveK(const sl::Constants& k, Accumulators& a) noexcept { a.n.store(k.cameraPos.x); }"; List = $goodList + "sl::Constants::cameraPos`n"; Other = $goodOther; Expect = 2 },
@{ Name = 'the sl::Constants parameter handed on whole FAILS'; Header = $goodHeader + "`ninline void ObserveK(const sl::Constants& k, Accumulators& a) noexcept { a.n.store(k.cameraNear); Other(k); }"; List = $goodList + "sl::Constants::cameraNear`n"; Other = $goodOther; Expect = 1 },
@{ Name = 'the frame-generation configuration read through its parameter, each member on the list, passes'; Header = $goodHeader + "`ninline void ObserveG(const ffxConfigureDescHeader* desc, Accumulators& a) noexcept { const auto& g = *reinterpret_cast<const ffxConfigureDescFrameGeneration*>(desc); a.n.store(g.flags + g.generationRect.left); }"; List = $goodList + "ffxConfigureDescFrameGeneration::flags`nffxConfigureDescFrameGeneration::generationRect`n"; Other = $goodOther; Expect = 0 },
@{ Name = 'a member of the frame-generation configuration the list does not allow FAILS'; Header = $goodHeader + "`ninline void ObserveG(const ffxConfigureDescHeader* desc, Accumulators& a) noexcept { const auto& g = *reinterpret_cast<const ffxConfigureDescFrameGeneration*>(desc); a.n.store(g.flags); Keep(g.swapChain); }"; List = $goodList + "ffxConfigureDescFrameGeneration::flags`n"; Other = $goodOther; Expect = 1 },
@{ Name = 'a header with no read at all FAILS'; Header = '// o.outputWidth is somewhere else'; List = "# nothing`n"; Other = $goodOther; Expect = 1 }
)
foreach ($c in $cases) {