Compare commits

...
Author SHA1 Message Date
poli0981 0378b7dfa2 Merge main (#466 squashed) into feat/input-reader: the trees are the same below this branch's own commits 2026-11-14 23:04:44 +07:00
poli0981andClaude Fable 5.2 5d6434c360 feat(input): a session can store what it was played with - schema 0024, the .partial file's chunk 11, both tiers (D160) (#466)
* feat(input): the arithmetic of controller statistics - classes, batteries, makers, one pad seen twice (D155-D163)

Nothing reads a device yet. Domain.Input says whether an XInput state or a DualSense report is a pad in use and what
its battery is, adds a battery's readings up, counts switches and decides when two entries are one pad;
Application.Input holds one session's slices and turns them into a reading a second; InputSessionBuilder turns a
session's readings into its totals, its controllers as JSON and its timeline. TelemetrySample can carry a reading.

Every byte and reading under test was written by hand: no report from a real controller has passed through this code.

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

* feat(input): a session can store what it was played with - schema 0024, the .partial file's chunk 11, both tiers (D160)

Nine columns on sessions (the time in front and its four classes, the switches of method, the sources that answered,
the controllers as JSON) and three on games (what a store lists of controller support), ADD COLUMN only. The .partial
file gains chunk 11, so a session recovered after the Agent died keeps its readings. SessionFinalizer.Build stores
them before the tier branch: hooked, unhooked and recovered sessions alike. The input series are sensor_blobs rows
named input.*, which the sensors' read now leaves out and FindInputSensorsAsync returns.

Nothing produces a reading yet. A ledger this build has opened cannot be opened by 0.1.0-beta.49 or earlier.

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

* fix(input): an arm of XInputPad.Battery's switch said what the default says (Qodana, on #464 after it merged)

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

* test(input): no using that makes the file's own qualified names redundant (InspectCode)

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

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 16:02:29 +00:00
poli0981 102dcdd3f1 Merge feat/input-storage (main at 1d1d4ff) into feat/input-reader 2026-11-14 22:52:58 +07:00
poli0981 43e0c2b347 Merge branch 'main' into feat/input-storage 2026-11-14 22:48:46 +07:00
poli0981andClaude Fable 5.2 1d1d4ff855 docs(roadmap): the owner's order of work after the controller train (#465)
* docs(roadmap): the owner's order of work after the controller train - time played, more from stored data, shader-compilation stutter, the in-game overlay, winget and the Microsoft Store

The owner was shown six directions on 2026-11-14 and chose four, and added distribution; the
Store upload and its listing are the owner's by hand. What must be verified before anything is
promised of the two channels is listed as leads, not findings. Documents only.

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

* docs(roadmap): FrameLedger has no product in Partner Center yet - the one there is another program of the owner's

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

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 15:31:51 +00:00
poli0981andClaude Fable 5.2 f7129807e6 test(input): what InspectCode reported in the reader's tests - redundant casts, a hub disposed twice, a suppression not needed
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 22:20:52 +07:00
poli0981 be96564a8f Merge feat/input-storage (the inspection fix) into feat/input-reader 2026-11-14 22:19:55 +07:00
poli0981andClaude Fable 5.2 e24f09ae8a test(input): no using that makes the file's own qualified names redundant (InspectCode)
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 22:19:52 +07:00
poli0981 80155d7638 Merge feat/input-storage (main at 8f24854, the Qodana fix) into feat/input-reader 2026-11-14 22:14:22 +07:00
poli0981andClaude Fable 5.2 8b4cccbb25 fix(input): an arm of XInputPad.Battery's switch said what the default says (Qodana, on #464 after it merged)
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 22:14:11 +07:00
poli0981 2dd0e4f271 Merge main (8f24854, #464 squashed) into feat/input-storage: the trees are the same below this branch's own commit 2026-11-14 22:13:56 +07:00
poli0981andClaude Fable 5.2 e2675cd91c feat(input): the input reader, which the Agent does not start yet - raw input for controllers, XInput, the time of the last input (D155, D158, D159)
Application.Input.InputReader takes a slice about ten times a second from Infrastructure.Input.Win32InputBackend, on
the thread of InputDeviceHub, which exists only while a session has a view of it. It opens no device, sends nothing
to one and registers for no keyboard or mouse. tools/input-readonly-check.ps1 holds its Windows calls to a list.

With no controller at hand, what the reader does with one connected is not established.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 22:12:33 +07:00
poli0981andClaude Fable 5.2 8f24854aa5 feat(input): the arithmetic of controller statistics - classes, batteries, makers, one pad seen twice (D155-D163) (#464)
Nothing reads a device yet. Domain.Input says whether an XInput state or a DualSense report is a pad in use and what
its battery is, adds a battery's readings up, counts switches and decides when two entries are one pad;
Application.Input holds one session's slices and turns them into a reading a second; InputSessionBuilder turns a
session's readings into its totals, its controllers as JSON and its timeline. TelemetrySample can carry a reading.

Every byte and reading under test was written by hand: no report from a real controller has passed through this code.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 15:02:57 +00:00
poli0981andClaude Fable 5.2 dca740e94b feat(input): a session can store what it was played with - schema 0024, the .partial file's chunk 11, both tiers (D160)
Nine columns on sessions (the time in front and its four classes, the switches of method, the sources that answered,
the controllers as JSON) and three on games (what a store lists of controller support), ADD COLUMN only. The .partial
file gains chunk 11, so a session recovered after the Agent died keeps its readings. SessionFinalizer.Build stores
them before the tier branch: hooked, unhooked and recovered sessions alike. The input series are sensor_blobs rows
named input.*, which the sensors' read now leaves out and FindInputSensorsAsync returns.

Nothing produces a reading yet. A ledger this build has opened cannot be opened by 0.1.0-beta.49 or earlier.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 21:54:13 +07:00
poli0981andClaude Fable 5.2 b29993ba82 feat(input): the arithmetic of controller statistics - classes, batteries, makers, one pad seen twice (D155-D163)
Nothing reads a device yet. Domain.Input says whether an XInput state or a DualSense report is a pad in use and what
its battery is, adds a battery's readings up, counts switches and decides when two entries are one pad;
Application.Input holds one session's slices and turns them into a reading a second; InputSessionBuilder turns a
session's readings into its totals, its controllers as JSON and its timeline. TelemetrySample can carry a reading.

Every byte and reading under test was written by hand: no report from a real controller has passed through this code.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 21:44:42 +07:00
poli0981andClaude Fable 5.2 e20bf9abc0 feat(advanced): Advanced metrics is closed - the ten Streamline readings that waited for a spike are not read, with the reason (D154) (#463)
The owner was shown the catalog (140 entries, 110 read) and what the ten entries of reach
Spike hold, read from Streamline 2.14.16's own headers, with what reading them takes: none
is an export, a game gets each function through slGetFeatureFunction and keeps the pointer,
so seeing its calls means handing the game a function of ours in place of Streamline's
(rule 4) - and a game that fetched its functions before the attach never calls it. The
owner closed it.

The ten are RefusedRoute; that reach's sentence names the third refused route in English,
Vietnamese and Japanese; the guide no longer says a later release reads more; 18_GPU's
inventory, 20_OPEN_QUESTIONS M15 and HANDOFF say train D is not built. Nothing that was
read stops being read; no hook, layout, schema or stored value changes.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 14:04:54 +00:00
poli0981andClaude Fable 5.2 5440f8a34a fix(app): the two GPU labels say what each figure is, not which holds the other (D152) (#462)
* docs: owner-only item 47 read (the Cyberpunk difference is the driver's; the holes are gone from steady play); Streamline's Reflex and DLSS-RR guides read against the code

Item 47, run by the owner on 0.1.0-beta.49 (sessions 236-245), read from a copy of the
ledger and the Overlay's logs: in Cyberpunk 2077 without frame generation the driver's
active GPU time is longer than its two marks are apart on 4 917 of 5 394 frames, and on
none of 129 900 frames in five other games; samples without a report are confined to a
game's start; off means off; D141's stop fired in a real game for the first time.

NVIDIA's Streamline guides for Reflex and DLSS Ray Reconstruction (2.14.16), read whole:
the guide's page on Advanced metrics now says what bUseGameSleep and bLowLatencyMode
mean; two design tables no longer promise PC latency (D147); spike-notes 30 has what the
guides add. Two comments (fl_shm.h, dllmain.cpp) said super resolution and ray
reconstruction run together - they do not; comments only, no object code changes.

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

* docs(handoff): item 47 (f) and (g) in the owner's words - the NVIDIA App's Low Latency Mode is off, no hitch

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

* docs(handoff): item 47 (f) as the owner showed it - the NVIDIA App's Low Latency Mode is off for Cyberpunk 2077, the game's own Reflex is on

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

* fix(app): the two GPU labels say what each figure is, not which holds the other (D152)

"GPU active render (idle time excluded)" and "GPU render, start to end (idle time included)"
followed NVIDIA's header, which defines the active time as the span between the driver's two
GPU marks less its idle time. Item 47 counted it on 0.1.0-beta.49: in Cyberpunk 2077 without
frame generation the active time is the longer of the two on 4 917 of 5 394 frames. The owner
chose to reword the labels. They now read "GPU active render (the driver's own figure)" and
"GPU render (between the driver's start and end marks)", in English, Vietnamese and Japanese;
the guide says why. Strings only: the numbers and the means are unchanged.

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

* docs(handoff): D153 - of Reflex it is enough to tell whether a game has it: Reflex and PCL leave train D, D141's stop is unchanged

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

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 13:13:15 +00:00
poli0981andClaude Fable 5.2 dc329c09b4 docs: owner-only item 47 read; Streamline's Reflex and DLSS-RR guides read against the code (#461)
* docs: owner-only item 47 read (the Cyberpunk difference is the driver's; the holes are gone from steady play); Streamline's Reflex and DLSS-RR guides read against the code

Item 47, run by the owner on 0.1.0-beta.49 (sessions 236-245), read from a copy of the
ledger and the Overlay's logs: in Cyberpunk 2077 without frame generation the driver's
active GPU time is longer than its two marks are apart on 4 917 of 5 394 frames, and on
none of 129 900 frames in five other games; samples without a report are confined to a
game's start; off means off; D141's stop fired in a real game for the first time.

NVIDIA's Streamline guides for Reflex and DLSS Ray Reconstruction (2.14.16), read whole:
the guide's page on Advanced metrics now says what bUseGameSleep and bLowLatencyMode
mean; two design tables no longer promise PC latency (D147); spike-notes 30 has what the
guides add. Two comments (fl_shm.h, dllmain.cpp) said super resolution and ray
reconstruction run together - they do not; comments only, no object code changes.

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

* docs(handoff): item 47 (f) and (g) in the owner's words - the NVIDIA App's Low Latency Mode is off, no hitch

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

* docs(handoff): item 47 (f) as the owner showed it - the NVIDIA App's Low Latency Mode is off for Cyberpunk 2077, the game's own Reflex is on

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

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 12:55:35 +00:00
poli0981andClaude Fable 5.2 1a8a3cb713 docs(handoff): 0.1.0-beta.49's release facts - the tag's run, the digests, the delta, the wiki, the two rehearsals, what SonarCloud and Qodana said on the release's commit (#460)
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 11:32:35 +00:00
102 changed files with 7411 additions and 87 deletions

No files matched your search

+63
View File
@@ -35,6 +35,69 @@ numeric core and does not move; the heading is the full version — corrected 20
## [Unreleased]
### Added
- **For developers: the arithmetic of controller statistics, with nothing reading a device yet** (D155–D163, the
owner's decisions of 2026-11-14; `docs/21_INPUT_DEVICES.md`, `docs/03_METRICS.md` §Input). `FrameLedger.Domain.Input`
says whether an XInput state or a DualSense report is a pad in use and what its battery is, adds a battery's readings
up, counts switches, and decides when two entries are one pad seen twice; `Application.Input` holds one session's
slices and turns them into a reading a second; `InputSessionBuilder` turns a session's readings into its totals, its
controllers as JSON and its timeline. A telemetry sample can carry a reading; none does. **Every byte and reading
under test was written by hand — no report from a real controller has passed through this code.**
- **For developers: a session can store what it was played with — schema 0024** (D160; `docs/06_DATA_MODEL.md`). Nine
columns on `sessions` (the time in front and its four classes, the switches of method, the sources that answered,
the controllers as JSON) and three on `games` (what a store lists of controller support), ADD COLUMN only; the
`.partial` file gains chunk 11, so a session recovered after the Agent died keeps its readings; the finalizer
stores them for hooked and unhooked sessions alike; the input series are `sensor_blobs` rows named `input.*`, which
the sensors' read leaves out. Nothing produces a reading yet. **A ledger this build has opened cannot be opened by
0.1.0-beta.49 or earlier.**
- **For developers: the input reader, which the Agent does not start yet** (D155, D158, D159; `docs/21_INPUT_DEVICES.md`
§The reader). `Application.Input.InputReader` takes a slice about ten times a second from
`Infrastructure.Input.Win32InputBackend` — raw input for joysticks and gamepads delivered to a window that is never
shown, three of XInput's getters, the time of the last keyboard or mouse input, the window in front — on the thread
of `InputDeviceHub`, which exists only while a session has a view of it. It opens no device, sends nothing to one,
and registers for no keyboard or mouse. A new gate, `tools/input-readonly-check.ps1`, holds the reader's Windows
calls to a committed list and refuses, on the list or off it, a call that sends to a device, injects input or reads
a key; no other managed source and no native source may name an input function. **With no controller at hand, what
the reader does with one connected is not established**: its tests use a Windows whose answers they write, and one
suite runs it on the real Windows of the machine and asserts only that it opens, answers and closes.
### Changed
- **Advanced metrics is closed: the ten readings that were "being studied" are now "not read", with the reason**
(D154, the owner's decision). What a game sets and asks through Streamline's own functions for a feature — DLSS
frame generation's options and state, the video memory DLSS estimates for itself, the options of ray
reconstruction, Image Scaling and Dynamic Vibrance, the PC-latency markers — is reached only by handing the game
a function of FrameLedger's in place of Streamline's, which is refused. The *Sources* list says so, in English,
Vietnamese and Japanese, and the guide no longer says a later release reads more. Nothing that was read stops
being read.
- **The two lines of the graphics card's time say what each is, not which holds the other** (D152, the owner's
decision). *GPU active render (idle time excluded)* and *GPU render, start to end (idle time included)* are now
*GPU active render (the driver's own figure)* and *GPU render (between the driver's start and end marks)*, in
English, Vietnamese and Japanese, and the guide says why: in Cyberpunk 2077 without frame generation the
driver's active time is longer than its two marks are apart. The numbers are unchanged.
- **The guide's page on Advanced metrics says what two of the driver's switches mean** (`guide/12`): the latency
report is there in a game that has Reflex built in, whether Reflex is on or off in its menu; `bUseGameSleep`
says the game calls Reflex's sleep — NVIDIA asks for that even with Reflex off — and `bLowLatencyMode` is the
one that says the mode is on; frame generation needs Reflex, not the reverse. From NVIDIA's Streamline guide
for Reflex, and from the owner's ten sessions on 0.1.0-beta.49.
### Documentation
- **Owner-only item 47 was run and read** (`docs/HANDOFF.md`): in Cyberpunk 2077 without frame generation the
driver's active GPU time is longer than its own two marks are apart on 4 917 of 5 394 frames (1 849 µs beside
1 571 µs) and on none of 129 900 frames in five other games — the difference is the driver's; samples without a
report are now confined to a game's start; a session with the option off has no latency line; and the stop of
D141 fired in a real game for the first time (Kingdom Come: Deliverance II, one call of 5.3 ms while it
started).
- **Streamline's programming guides for Reflex and for DLSS Ray Reconstruction (2.14.16) read against the code**
(`docs/spike-notes/30-reflex-latency.md`, *Added 2026-11-14*). Ray reconstruction was already measured the way
the guide describes; two comments in the Overlay's source and one line of `17_HOOK_ENGINE` said super
resolution and ray reconstruction run together, and they do not. `03_METRICS` and `05_DETECTION` no longer
promise "PC latency as reported by Reflex" (D147). No code changed: comments only.
## Releases
Newest first. Each file holds that release's section exactly as it stood here.
+5 -1
View File
@@ -208,7 +208,11 @@ tools/ # accuracy-check, changelog-check, chokepoint-che
# the two on overlay-nvapi-allowed.txt),
# overlay-fields-check (D116, 2026-11-12: every member of a vendor's struct the
# Overlay reads for Advanced metrics is in fl_adv_fields.h and on
# overlay-allowed-fields.txt; a camera's position, axes and matrices nowhere)
# overlay-allowed-fields.txt; a camera's position, axes and matrices nowhere),
# input-readonly-check (D155-D163, 2026-11-14: every Windows function the input reader
# calls is declared in Infrastructure/Input/Win32Input.cs and on input-allowed-calls.txt;
# none sends to a device, injects input or reads a key; raw input is registered for
# joysticks and gamepads only; no native source names an input function)
# (six names added 2026-10-04)
# (PowerShell). This line used to name three, one of which
# — resx-audit — ~~does not exist~~ exists since 2026-09-13 with
+9
View File
@@ -499,6 +499,15 @@ function Invoke-ProjectGates {
Invoke-Checked 'overlay-fields-check (self-test)' { & $fieldsTool -SelfTest }
Invoke-Checked 'overlay-fields-check' { & $fieldsTool -RepoRoot $repo }
# 2026-11-14 (D155-D163): what is asked of Windows about controllers, the keyboard and the mouse. The reader's
# calls are declared in one file and held to tools/input-allowed-calls.txt in both directions; a call that sends to
# a device, injects input or reads a key is red even when the list names it; no managed source outside the reader
# and no native source names an input function; raw input is registered for joysticks and gamepads only. Text only.
Write-Step 'input-readonly-check'
$inputTool = Join-Path $repo 'tools/input-readonly-check.ps1'
Invoke-Checked 'input-readonly-check (self-test)' { & $inputTool -SelfTest }
Invoke-Checked 'input-readonly-check' { & $inputTool -RepoRoot $repo }
Write-Step 'docs-split-check'
$splitTool = Join-Path $repo 'tools/docs-split-check.ps1'
Invoke-Checked 'docs-split-check (self-test)' { & $splitTool -SelfTest }
+55 -1
View File
@@ -976,6 +976,60 @@ min / max in `sensor_stats_json` (§Sensor aggregates). MiB stored; shown in GB
~~`vramUsedMb` from `IDXGIAdapter3::QueryVideoMemoryInfo(LOCAL)` inside the game = **this game's** usage and budget. **MiB, truncating, and it must use the same divisor as `vramBudgetMb`** — the two are compared, and mismatched rounding would put a systematic bias into `budget_exceeded_pct`. Residual: a flip within 1 MiB of the budget, 0.004% of a 24 GiB card. Stored as its own series and clearly labelled apart from the adapter-wide figure from `18_GPU_VENDOR_APIS`. Aggregates: avg, max, and `budget_exceeded_pct` (share of samples where `CurrentUsage > Budget`, i.e. the driver was likely evicting — a genuinely useful stutter explanation).~~
## Input — what a session was played with, both tiers (owner decisions D155–D163)
**Owner request, 2026-11-14:** the share of a session played with a controller and with the keyboard, how often a
controller connected and dropped, the battery state that lasted longest, the switches between makers' controllers.
What is read and what never is: [`21_INPUT_DEVICES.md`](21_INPUT_DEVICES.md). The arithmetic is
`Domain.Input` and `Application.Recording.InputSessionBuilder`. **Not built end to end yet** — nothing reads a device
until the pull requests after the one that wrote this section; until then these are definitions under test.
**What it can say, and what it cannot.** Everything is read from outside the game. So a number here says that a
controller, or the keyboard or mouse, was *in use while the game's window was in front* — never what the game did with
it, and never which button or key.
**The unit is a slice** of about a tenth of a second, and a slice counts for a session only when a window of the
session's game was in front and the session was not paused (a pause is a gap, as for frames). A slice with another
program in front is not classified: typing in a browser beside the game is not the game played with the keyboard.
| Class | A slice in front in which |
|---|---|
| Controller | a controller was in use and the time of the last keyboard-or-mouse input did not move |
| Keyboard & mouse | that time moved and no controller was in use. One class: only a time is read (D158) |
| Both | both |
| No input | neither |
- **A controller is in use** when a button is down, a trigger is past its threshold, or a stick is outside its dead
zone. A stick held counts. One that drifts inside the dead zone does not — a pad lying on a desk is not played with.
- **A share** is a class's time over the time the game was in front (`input_foreground_ms`). The four add up to it.
- **A switch of method** is a change between *controller* and *keyboard & mouse* from one tick (a second) to a later
one. A tick played with both, or with neither, is no one thing and does not end the run before it: putting the
controller down and picking it up again is not a switch.
- **Connections** are counted from the session's second slice: a controller that is there when the session starts has
not connected. A Bluetooth pad that goes to sleep has disconnected.
- **A battery** is timed by the clock, in front or not: the time at each level, the level that lasted longest, the
first and the last. Each source keeps its own steps — XInput's four words, a DualSense's per cent in tens — and none
is converted into another's. **A rate**, in per cent an hour, is the fall from the first to the last reading on
battery over the time read on battery; it is given only for a level in per cent that fell, was not put on power in
between, and was read on battery for ten minutes or more.
- **A maker's share** is the time its controllers were in use over that time for every maker. **A switch of maker**
is counted like a switch of method, between ticks in which one maker's controllers alone were in use.
- **One pad seen twice is one controller.** With Steam Input in front of a controller Windows shows the controller the
player holds and an Xbox pad Steam presents for it. One of XInput's pads that was in use at the same moments as
another controller — nine tenths of the busier one's time, over ten seconds or more — is folded into it: into a
controller that is not XInput's at any time, into another of XInput's pads only in a session in which Steam's
virtual gamepad was seen. Two players pressing in step are two players.
**The timeline** is one series, `input.class`: what each tick was mostly played with, as the class's number (0 no
input, 1 controller, 2 keyboard & mouse, 3 both), and no value for a tick with the game not in front. Each of the
first eight controllers has `input.dev.N.active` (the part of the tick's time in front it was in use; no value where
it was not connected) and, with a battery that has a level, `input.dev.N.battery`.
**Known limits.** Keyboard and mouse cannot be told apart. Input a program injects counts as keyboard and mouse — Steam
Input mapping a pad to keys, a macro tool — so a pad mapped that way reads as *both*. A game whose window belongs to
another process reads as never in front (the focus sample's limit). Whether a controller's own input moves Windows'
last-input time has not been checked on a real PC.
## Sensor aggregates
Per session over 1 Hz samples: `avg` (mean of non-null), `max` — and since beta.12 the `median` (the linear-interpolation
@@ -1019,7 +1073,7 @@ processor's, not the whole PC's — averaged over the session's sensor ticks. `D
| RT active | measured per frame | not available |
| Path tracing | heuristic, confidence-scored, never asserted | not available |
| ~~Per-process VRAM~~ Game process memory (beta.12) | ~~exact~~ dedicated / shared GPU memory as Task Manager counts it — a known 512 MiB allocation read +512.0 MiB (`spike-notes` §16); private working set equal to Windows' own counter; read from outside the game | ~~not available~~ the same, from outside; an unpinned hold sums the executable's processes |
| PC latency | as reported by Reflex | not available |
| PC latency | ~~as reported by Reflex~~ **not available** (D147, *corrected 2026-11-14*): the driver's report ends at the end of the GPU's work, not at the display. The stages it does give are Advanced metrics — the driver's numbers, unchecked | not available |
| Display mode (beta.10) | per 100 ms sample: exclusive fullscreen as the swap chain answers it (DXGI; OpenGL and Vulkan cannot say), borderless, windowed, minimised; the window's size from user32 | per 1 s sample, from the window alone: windowed, minimised, or *fullscreen or borderless* — never split |
| GPU temp / load / power | vendor API accuracy, ±1 s sampling | same |
| GPU clocks / fan / memory temperature (beta.14) | vendor API accuracy, ±1 s sampling | same |
+2 -2
View File
@@ -22,8 +22,8 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
| Render resolution vs output resolution (incl. mid-session changes) | upscaler parameter reads + `ResizeBuffers` |
| Frame Generation mode + factor | NGX/SL/FFX FG feature evaluation, then cadence — **Tier 1 only**. ~~then (Tier 2 only) PresentMon `FrameType`~~ retired (§S31 row P2), and Tier 2 no longer produces frames to run cadence over either |
| Ray Tracing active | AS builds + `DispatchRays` (both, to catch inline RayQuery) |
| Ray Reconstruction | NGX `RayReconstruction` feature evaluated |
| Reflex on + PC latency | NVAPI Reflex hooks |
| Ray Reconstruction | ~~NGX `RayReconstruction` feature evaluated~~ Streamline's `slEvaluateFeature(kFeatureDLSS_RR)` — it runs **instead of** super resolution, in DLSS's own quality mode (Streamline's guide; measured 2026-08-15), so the upscaler is DLSS and this is a yes/no beside it. A game that calls NGX directly reads N/A (`03_METRICS` §RT/PT/RR) *(corrected 2026-11-14)* |
| ~~Reflex on + PC latency~~ The driver's latency report and sleep status (0.1.0-beta.47, Advanced metrics only) | ~~NVAPI Reflex hooks~~ two read-only getters of the driver, called by the Overlay (`17_HOOK_ENGINE` §Calls the Overlay makes into a driver). **PC latency — input to display — is not read** (D147): the report ends where the GPU's work ends, and NVIDIA's own figure is taken from outside the game (`spike-notes` §30, route E) *(corrected 2026-11-14)* |
| Per-process VRAM | `QueryVideoMemoryInfo` |
| PSO compilation events | pipeline-creation hooks |
| Display mode — exclusive fullscreen / borderless / windowed / minimised, with the window, back buffer and monitor (beta.10) | `GetFullscreenState` + `GetDesc` polled on the presenting chain (≤ 2 Hz, shared-memory region 4), and the window's geometry read by the Agent **out of process** — so this row is **both tiers**: a Tier-2 session has the window alone, and never splits exclusive from borderless (`03_METRICS` §Display mode) |
+57 -1
View File
@@ -342,7 +342,25 @@ CREATE TABLE sessions (
display_source TEXT, -- swapchain | opengl | window: the strongest witness any sample had
display_window_w INTEGER, display_window_h INTEGER, -- client area, in the mode that lasted longest (the last seen, beta.27)
display_buffer_w INTEGER, display_buffer_h INTEGER, -- the swap chain's back buffer, same mode
display_monitor_w INTEGER, display_monitor_h INTEGER, display_monitor_hz INTEGER
display_monitor_w INTEGER, display_monitor_h INTEGER, display_monitor_hz INTEGER,
-- schema 0024 (2026-11-14, beta.50, D155-D163): what the session was played with, both tiers (03_METRICS §Input) -
-- read by the Agent from outside the game. Milliseconds. NULL before, with the option off, and before the terms
-- that describe the reading were accepted - N/A, never 0. From the samples, so a recovered session has them.
input_observed_ms INTEGER, -- the reader ran and the session was not paused
input_foreground_ms INTEGER, -- of it, a window of the game was in front: the four below add up to this
input_controller_ms INTEGER, -- a controller in use, the keyboard and mouse not
input_km_ms INTEGER, -- the keyboard or mouse in use (one class - only a time is read), no controller
input_both_ms INTEGER,
input_idle_ms INTEGER, -- no input at all
input_method_switches INTEGER, -- changes between a controller and the keyboard and mouse
input_source TEXT, -- the sources that answered: rawinput, xinput, lastinput, joined by +
input_devices TEXT -- InputDevicesRecord's JSON: {"V":1,"Devices":[{"Index","Family","VendorId",
-- "ProductId","Model","Connection","XInputSlot","Virtual","Remapped",
-- "ConnectedMs","ActiveMs","Connects","Disconnects","Battery":{"Scale",
-- "States":[{"State","Level","Ms"}],"First","Last","DrainPercentPerHour"}}],
-- "Families":[{"Family","ActiveMs","Share"}],"FamilySwitches","VirtualPad",
-- "Health":{...counts...}} - no serial number, no address, no path
);
CREATE INDEX ix_sessions_game_started ON sessions(game_id, started_at DESC);
@@ -402,6 +420,12 @@ CREATE TABLE sensor_blobs (
-- since schema 0023 (2026-11-11, D102) also the ADVANCED series, every one under a name
-- that starts with `adv.` (Application.Advanced.AdvancedMetricCatalog): NaN, not -1,
-- for a tick with no reading, and read by FindAdvancedSensorsAsync only
-- since schema 0024 (2026-11-14, D155-D163) also the INPUT series, every one under a
-- name that starts with `input.`: input.class (what the tick was mostly played with:
-- 0 no input, 1 controller, 2 keyboard and mouse, 3 both), input.dev.N.active (the
-- part of the tick's time in front controller N was in use, 0-1) and
-- input.dev.N.battery (its level, in its own scale) - NaN for a tick with nothing to
-- say, and read by FindInputSensorsAsync only
-- cpu_load / ram_mb / cpu_temp and sessions.avg_cpu_load, avg_cpu_temp, max_cpu_temp,
-- avg_ram_mb were in schema 0001 with NO producer until 2026-09-21 (Telemetry.SystemTelemetrySource
-- on the poller's tick). Rows before that date hold NULL, which is what they measured; no migration.
@@ -528,6 +552,15 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
> (`AdvancedSessionBuilder.MaxSeries`); what is beyond is counted in its directory, not stored.
> **Size, measured 2026-11-11** on values shaped like the dev box's reader (17 series with a reading every tick, 41
> with one every fifth): one hour is 816 KiB raw and **189 KiB stored** — well inside NFR-5's 3 MB an hour.
>
> **The input series follow the same rule under their own name (schema 0024, owner decisions D155–D163).** A series
> whose name starts with `input.` stores NaN for a tick with nothing to say — the game was not in front, the
> controller was not connected, the tick carried no reading — through the same sparse encoder. `FindSensorsAsync`
> leaves them out as well (`series NOT LIKE 'input.%'`): a class's number is not a sensor's value, and the sensors'
> statistics and chart would take it for one. `FindInputSensorsAsync` returns them with `t_ms` first. A session
> stores `input.class` and, for each of its first eight controllers (`InputSessionBuilder.MaxDevices`),
> `input.dev.N.active` and — where the battery has a level — `input.dev.N.battery`: at most seventeen, a few KiB an
> hour stored.
## The `.partial` file
@@ -552,6 +585,7 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
> | 8 `SensorsWide` | the same samples under a 32-bit presence mask that carries the game process's memory (D43) | each flush, since beta.12 *(row added 2026-10-04)* |
> | 9 `SensorsAdvanced` | the advanced readings of the samples of the type-8 chunk before it (D101): `u16` names, then per name `u16` bytes and UTF-8; `u32` samples, then per sample `i64` QPC, `u16` readings and per reading `u16` name, `f64` value. Each chunk carries its own names, so it reads without any earlier chunk | each flush **in which a sample carries any** — with Advanced metrics off, never; the file is then byte for byte what it was (2026-11-11) |
> | 10 `AdvancedContext` | UTF-8 JSON (`AdvancedJson.OfContext`): the PC's facts, the session's, its series' directory, each source's state; the last one wins | the first flush after the recorder set it, and again only when it changed (2026-11-11) |
> | 11 `SensorsInput` | the input readings of the samples of the type-8 chunk before it (D155–D163, `InputSampleCodec`): `u32` samples, then per sample `i64` QPC, seven `i32` (span, observed, in front, controller, keyboard and mouse, both, no input), `u8` flags, the reader's health (`u8` answers, six `i64` counts, `i32` faults), `u8` controllers and 23 bytes a controller — what it is (maker, the two USB ids, connection, XInput pad) and its part of the tick (connected, time in use, battery, connections, drops). Each sample describes every controller it counts, so a chunk reads without any earlier one | each flush **in which a sample carries one** — with the option off, never; the file is then byte for byte what it was (2026-11-14) |
>
> **A chunk of a type the reader does not know is skipped, not the end of the file (owner decision D106,
> 2026-11-11).** Its length and checksum have been verified by then, so it is a whole chunk a newer build wrote.
@@ -802,6 +836,28 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
> **Nothing produces a row yet**: the option that switches the reader on is the next pull request's.
> **A beta.38 cannot open a ledger a later build migrated.**
> **`0024_input_devices.sql` (0.1.0-beta.50, 2026-11-14, owner decisions D155–D163) — what a session was played
> with, and what a store lists.** ADD COLUMN only, twelve columns. **Nine on `sessions`**: `input_observed_ms`,
> `input_foreground_ms` and the four classes that add up to it (`input_controller_ms`, `input_km_ms`,
> `input_both_ms`, `input_idle_ms`), `input_method_switches`, `input_source`, and `input_devices` — the session's
> controllers as `Application.Recording.InputDevicesRecord`'s JSON (`03_METRICS` §Input). **On `sessions` and not in
> a table of their own, on purpose** (D160) — the opposite of 0023's choice, for the opposite reason: the trend and
> the comparison read a session's row, and these numbers are meant to be in the JSON export and the bug bundle,
> which carry the whole row; the Privacy Policy's §3A says so. What may never be a column or a key of that JSON: a
> controller's serial number, its Bluetooth address, its device path
> (`LedgerDatabaseTests.ScriptTwentyFourOnlyAddsColumnsAndNamesNoIdentifier`,
> `InputSessionBuilderTests.TheStoredJsonHasNoKeyThatCouldCarryASerialNumberAnAddressOrAPath`). **Three on
> `games`**: `controller_support` (`full`, `partial`, or `none` for a game the store knows and lists no support
> for), `controller_support_source` (`steam-appinfo`) and `controller_support_at` — the store's own word, from its
> file on the disk, never a verdict of FrameLedger's (D163). Written by `SessionFinalizer.Build` from the session's
> samples, before the tier branch — both tiers, and a session recovered from its crash file, which carries the
> readings in chunk 11. NULL before; with the option off; before the terms that describe the reading were accepted
> (D156); on a game no store file describes. The series are `sensor_blobs` rows named `input.*` (§Blob encoding).
> `LatestVersion` is 24; `LedgerDatabaseTests.ScriptTwentyFourAddsTheInputColumnsAndAnEarlierSessionAndGameHaveNone`,
> the repository round trip. **Nothing produces a reading yet, and nothing writes the three `games` columns yet**:
> the reader, the switch and the store file are the pull requests after this one.
> **A beta.49 cannot open a ledger a later build migrated.**
> **`0022_dlss_nr.sql` (beta.34, 2026-11-06, owner decision D84) — DLSS 5's neural rendering, measured.** One REAL column,
> ADD COLUMN only: `dlss_nr_pct`, the share (0–100) of the presents that drained a Streamline evaluation on which the game
> evaluated `kFeatureDLSS_NR` (`Domain.Metrics.NeuralRendering`). Written by the recorder's aggregation
+1
View File
@@ -411,6 +411,7 @@ Seven self-test cases, both directions; `./tools/notice-check.ps1 -Fix` writes a
14. `tools/changelog-check.ps1 -SelfTest` — nine cases, five expected RED. The live half needs a pull request's changed-file list and is supplied by `ci.yml`
14b. `tools/release-notes.ps1 -SelfTest` — five cases over a fixture changelog (a dated and an undated section, a missing one, a prefix that must not match, an empty one), and since beta.24 three over a temporary tree: a version with its own `docs/changelog/<version>.md` is read from it, one without from `CHANGELOG.md`, a prefix of a file name is not that file. The live half needs a tag's version and runs in `release.yml`, where a missing or empty section is a red release (P4 PR-5)
14e. **`tools/nvapi-readonly-check.ps1 -SelfTest`, then live** (owner decision D108, 2026-11-11) — every `NvAPI_*` call in `src/native/FrameLedger.NvapiBridge/src/fl_nvapi_bridge.cpp`, the one translation unit that links `nvapi64.lib` into a shipped binary, is on `tools/nvapi-allowed-calls.txt` and every name there is called; a name that sets, saves, restores, deletes, registers, resets, enables, disables or controls something is red **even when the list names it**, and so is one that returns an identifier (D104) — three reads the verb rule would refuse are exempt by name, each with its reason. Comments and string literals are taken out first, so a setter named in the comment that says it is never called is not a call. Seventeen self-test cases, both directions. Text only: it runs with or without the native build. `18_GPU_VENDOR_APIS` §Runtime policy's "never call a setter", which was a sentence until the bridge went from fourteen calls to forty-four
14g. **`tools/input-readonly-check.ps1 -SelfTest`, then live** (owner decisions D155–D163, 2026-11-14) — what FrameLedger asks Windows about controllers, the keyboard and the mouse. Every Windows function the input reader calls is declared in ONE file, `src/FrameLedger.Infrastructure/Input/Win32Input.cs`, and is on `tools/input-allowed-calls.txt`; every name there is declared; a name that sends to a controller (`XInputSetState`, any `HidD_*`), injects input (`SendInput`), reads a key (`GetAsyncKeyState`, `GetKeyState`, `GetKeyboardState`, `XInputGetKeystroke`) or installs a hook is red **even when the list names it**; no managed source outside `src/FrameLedger.Infrastructure/Input/` names an input function at all, and `NativeMethods.txt` asks CsWin32 for none; raw input is registered for joysticks and gamepads only — `InputReader.RegisteredUsages` is exactly usage page 1, usages 4 and 5, and the backend builds its registration from it and writes no usage as a number; and **no native source names an input function** — nothing loaded into a game reads input. Comments and string literals are taken out first. Seventeen self-test cases, both directions. Text only; it does not look at the tests, which may drive a real keyboard for the App's own shortcuts. `21_INPUT_DEVICES` §What is never read, which the Privacy Policy repeats to the user
14f. **`tools/overlay-fields-check.ps1 -SelfTest`, then live** (owner decision D116, 2026-11-12) — the same for the code loaded into a game: every member of a vendor's struct the Overlay reads for Advanced metrics is read in ONE header, `src/native/FrameLedger.Overlay/include/fl_adv_fields.h`, through parameters with fixed names, and is on `tools/overlay-allowed-fields.txt`; every name there is read; the parameters are not aliased and `->` reaches nothing but `desc` and the Overlay's own `region`; no other Overlay or Vulkan-layer source reads a listed member; **a camera's position, axes and matrices** (`cameraPos`, `cameraUp`, `cameraRight`, `cameraFwd`, the five matrices, `cameraPinholeOffset`, `cameraPosition`, `cameraForward`) **are named nowhere in those sources and not on the list, whatever the list says**; and neither `sl::Constants` nor `ffxDispatchDescFrameGenerationPrepareV2` is copied by value or measured with `sizeof`. Comments and string literals are taken out first. Nineteen self-test cases, both directions. Text only. It reads names, not types — which struct version carries a member is `17_HOOK_ENGINE` §Which struct version carries which field and ctest `fl_adv_fields`
14d. **`tools/docs-split-check.ps1 -SelfTest`, then live** (beta.24, owner decision D66) — `CHANGELOG.md` holds no released section beside `[Unreleased]`; each `docs/changelog/<version>.md` holds one `## ` heading, its own `## [<version>] - date`, and no relative link (the App renders release notes as `CHANGELOG.md`); `CHANGELOG.md` and the files under `docs/changelog/`, and `docs/HANDOFF.md` and the files under `docs/handoff/` — and since PR-5 `docs/20_OPEN_QUESTIONS.md` and `docs/open-questions/`, `docs/spike-notes.md` and `docs/spike-notes/` — name each other in both directions. Eleven self-test cases, both directions
14c. **`tools/buildid-check.ps1 -SelfTest`** (beta.18) — eight cases, both directions: a binary built from a dirty tree (`-dirty`, or the short form's `+`), one with no id, a missing one, and an expected id that is dirty or not an id are red. The live half needs the release's clean-checkout id and runs in `release.yml` over the published tree (§Release-time token substitution)
+44
View File
@@ -332,6 +332,50 @@ CI/CD with the native build (`release.yml` exists since P4 PR-5, 2026-09-14 —
**Total ≈ 5.5–6.5 weeks full-time** — roughly 1.5–2 weeks more than the ETW design, which is the honest price of the accuracy.
## After the controller train — the owner's order (2026-11-14)
Advanced metrics is closed (D154) and the controller feature is being built as 0.1.0-beta.50's train. Asked what
comes after, the owner was shown six directions and chose four of them, and added distribution. **This is the
order of work after the controller train; each begins with a plan of its own and the owner's approval.** Nothing
here is designed yet, and what is marked *to verify* is a lead, not a finding.
1. **Time actually played (AFK segmentation).** The v2 backlog's "AFK segmentation via `GetLastInputInfo`", moved
up: the controller train already stores when the keyboard, the mouse or a controller was in use, so the time
nobody was at the game can be told apart and left out of a session's averages. Timestamps of activity only —
never a key, as that train's Privacy text says.
2. **More from what is already stored — interface only, no hook.** The comparison of two stretches of one
session ("before and after I changed DLSS Quality to Balanced", v1.1 below), and a timeline for a game that
marks where the driver, the game's build or the settings changed, so a drop in frame rate has a date. *To
verify*: which of those changes the ledger already records for every session.
3. **Stutter from shader compilation (PSO).** `03_METRICS` defines *PSO stutter %* and `05_DETECTION` says no
writer exists. New hooks at pipeline creation: staged like Advanced metrics' train B — small releases, the
overhead measured, the owner's real games between them, never first on a game inside the user-mode
exception's trial (D38).
4. **The in-game overlay (FR-15).** v1.1's first line below: live frame rate, frame time, upscaler and
ray-tracing state drawn in the game, per game, off by default. The largest and the riskiest of the four — it
draws in the game's process — so it comes last, with a risk review of its own (rule 5, and what an
anti-cheat makes of a drawing module).
5. **Distribution: winget and the Microsoft Store.** The owner uploads to the Store and fills in its listing by
hand. FrameLedger has no product in Partner Center yet — the one there today is another program of the
owner's — so which type it is submitted as (*EXE or MSI app*, or *MSIX or PWA app*) is part of what the plan
settles. The repository's part is what the two channels need from a release. *To verify, before anything is promised*:
- whether the Store accepts an **unsigned** installer for an *EXE or MSI app* — the installer is unsigned
today (`CLAUDE.md`, Packaging), and if the Store wants a certificate that is a cost and a decision of the
owner's; whether an MSIX package is a real alternative for a program that loads a library into games and
registers a Vulkan layer;
- the installer's silent switch and a versioned, permanent download address for each release, which both
channels ask for; whether either takes a pre-release version;
- who updates an installation that came from winget or the Store — the App's own updater (Velopack) or the
channel — and that the two cannot fight;
- a winget manifest per release (address, SHA-256, switches) and whether `release.yml` writes it or the owner
submits it;
- rule 8 is untouched: a channel that delivers the installer is not a network call of the App's.
**Not chosen, and not refused**: a stabilising pass with a cross-check against another tool (the limits page
still says no reading has been checked against one), and export for CapFrameX and for video overlays. Two things
only the owner can settle stay open beside them: what leaving beta takes, and code signing — which direction 5
may force.
## v1.1 — earned features (only after the data path is stable)
- **In-game overlay** (FR-15): we are already in the process; draw live FPS/frametime/upscaler/RT state. Opt-in per game, off by default. Borderless and fullscreen-flip both handled since we own the swapchain.
+5 -3
View File
@@ -657,9 +657,11 @@ static_assert(sizeof(FlFrameRecord) == 64);
> v3 makes it safe by CONSTRUCTION. Every enum's 0 is now `NOT_REPORTED`, and
> `rtFlags`' polarity is flipped so its bits mean *observed*.
>
> Four answers items 4/6/7 owe had no home and now do: DLSS-SR **and** Ray
> Reconstruction concurrently (`featureFlags`, since RR was a mutually exclusive
> `upscaler` value), `upscalerSharpness`, and — in `FlWriterState`, because they
> Four answers items 4/6/7 owe had no home and now do: DLSS **with** Ray
> Reconstruction (`featureFlags`, since RR was a mutually exclusive
> `upscaler` value — *corrected 2026-11-14: this said "DLSS-SR and Ray
> Reconstruction concurrently"; RR runs instead of super resolution, it is still
> DLSS*), `upscalerSharpness`, and — in `FlWriterState`, because they
> are session facts and not per-frame — the device **RT tier** without which
> `03_METRICS`' definite RT `No` had no producer at all, plus `rtStateObjectsCreated`
> and `rasterPsoCreated`.
+18 -14
View File
@@ -724,7 +724,7 @@ Rules 4 and 5, the hook inventory, the measured overhead and the anti-cheat guar
every hook. `sl::Constants` is read without its camera position, axes and matrices: where the camera is, is where the
player is (rule 4). NGX stays closed by its licence (`17_HOOK_ENGINE` §NGX).
**Train D re-examines a refusal; it does not lift it.** `handoff/history/p0-queue-1-6.md` refused, on five grounds,
**Closed 2026-11-14 (owner decision D154): train D is not built, and the refusal stands.** The ten entries it would have read — what a game sets and asks through Streamline's feature functions — have reach `RefusedRoute`: seeing those calls takes handing the game a function of FrameLedger's in place of Streamline's, and a game that fetched its functions before the attach would never call it. What follows is the plan as it stood. **Train D re-examines a refusal; it does not lift it.** `handoff/history/p0-queue-1-6.md` refused, on five grounds,
hooking `slGetFeatureFunction` and patching the function it returns. The route to try is a different one:
`slGetFeatureFunction` is itself an export (`vendor-exports.json`), so its hook is an ordinary inventory row, and
what it hands back could be a wrapper for a fixed list of names instead of a patch at an address learned at run time
@@ -910,7 +910,7 @@ the catalog differ in either direction. **Reach** is where a value can be read f
FrameLedger measures, from the arguments of a call the Overlay hooks, while the session records Advanced metrics —
since 0.1.0-beta.40), `HookedCall` (an argument of a call the Overlay already hooks, not read yet), `NewHook` (a hook
that is not built — Train B; no entry carries it since 0.1.0-beta.45), `BeforeAttach` (a call the game makes once,
before FrameLedger is inside it, so no hook could read it — D129), `Spike` (Trains C and D), `Refused`, `Deferred`, `Identifier` (D104), `PlayerState`
before FrameLedger is inside it, so no hook could read it — D129), `Spike` (Trains C and D; no entry since D154), `Refused`, `Deferred`, `Identifier` (D104), `PlayerState`
(rule 4), `Licence`, `NotInHeaders`. ~~Only the first two are read by a build of Train A.~~ The first three are read
(`AdvancedMetric.IsRead`).
@@ -1099,7 +1099,11 @@ session that ended in a menu read 1). **Since 0.1.0-beta.48 (D142) two more seri
`adv.nvapi.reflex.gpu_times.` and `active_render`, `frame_time` — the driver's `gpuActiveRenderTimeUs` and
`gpuFrameTimeUs`, each the mean over the frames of that read that gave one. They are the driver's own figures, not
spans between two of its marks: in Phantom Blade Zero `gpu_render` (the two GPU marks, idle time included) was
longer than `total`, which is why its label now says what it includes (D143). An entry of their own keeps the
longer than `total`, which is why its label now says what it includes (D143). **Reworded 2026-11-14 (D152)**:
NVIDIA's header defines the active time as that span "excluding the idles in between", and in Cyberpunk 2077
without frame generation the active time is the longer of the two on nine frames in ten (HANDOFF, item 47) — so
the labels now say what each is (*the driver's own figure*; *between the driver's start and end marks*) and no
longer that one is the other less its idle time. The numbers and the means are unchanged. An entry of their own keeps the
seven spans within what one chart draws as lines. What the *game* asked of Reflex (`nvapi.reflex.mode`) is an argument of a function no module exports:
reading it takes a patch at an address learned at run time, which is refused.
@@ -1110,21 +1114,21 @@ reading it takes a patch at an address learned at run time, which is refused.
| `nvapi.reflex.frame_report` | Latency per frame: simulation, render submit, present, driver, OS queue, GPU render | Series, one per device | Nvapi | GameDriver | Microseconds |
| `nvapi.reflex.gpu_times` | The graphics card's time per frame, as the driver works it out: active render, frame to frame | Series, one per device | Nvapi | GameDriver | Microseconds |
**Inside the game: routes a spike decides**
**Inside the game: Streamline's feature functions — not read (D154, 2026-11-14)**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `sl.dlss.optimal_settings` | The render size and sharpness DLSS recommends | SessionFact | Streamline | Spike | Text |
| `sl.dlss.vram_estimate` | DLSS's own estimate of its video memory | Series | Streamline | Spike | Mebibytes |
| `sl.dlssg.options` | DLSS frame generation: mode, frames to generate | SessionFact | Streamline | Spike | Text |
| `sl.dlssg.state` | DLSS frame generation: status, the most frames it can generate | SessionFact | Streamline | Spike | Text |
| `sl.dlssg.frames_presented` | Frames DLSS frame generation presented, by its own count | Series | Streamline | Spike | Count |
| `sl.dlssg.vram_estimate` | DLSS frame generation's estimate of its video memory | Series | Streamline | Spike | Mebibytes |
| `sl.dlssd.options` | Ray reconstruction's options | SessionFact | Streamline | Spike | Text |
| `sl.nis.options` | NVIDIA Image Scaling's options | SessionFact | Streamline | Spike | Text |
| `sl.deepdvc.options` | RTX Dynamic Vibrance's options | SessionFact | Streamline | Spike | Text |
| `sl.dlss.optimal_settings` | The render size and sharpness DLSS recommends | SessionFact | Streamline | RefusedRoute | Text |
| `sl.dlss.vram_estimate` | DLSS's own estimate of its video memory | Series | Streamline | RefusedRoute | Mebibytes |
| `sl.dlssg.options` | DLSS frame generation: mode, frames to generate | SessionFact | Streamline | RefusedRoute | Text |
| `sl.dlssg.state` | DLSS frame generation: status, the most frames it can generate | SessionFact | Streamline | RefusedRoute | Text |
| `sl.dlssg.frames_presented` | Frames DLSS frame generation presented, by its own count | Series | Streamline | RefusedRoute | Count |
| `sl.dlssg.vram_estimate` | DLSS frame generation's estimate of its video memory | Series | Streamline | RefusedRoute | Mebibytes |
| `sl.dlssd.options` | Ray reconstruction's options | SessionFact | Streamline | RefusedRoute | Text |
| `sl.nis.options` | NVIDIA Image Scaling's options | SessionFact | Streamline | RefusedRoute | Text |
| `sl.deepdvc.options` | RTX Dynamic Vibrance's options | SessionFact | Streamline | RefusedRoute | Text |
| `sl.reflex.state` | Reflex through Streamline: availability and its frame reports | SessionFact | Streamline | RefusedRoute | Table |
| `sl.pcl.markers` | PC-latency markers the game sets | Series | Streamline | Spike | Count |
| `sl.pcl.markers` | PC-latency markers the game sets | Series | Streamline | RefusedRoute | Count |
**Closed by a licence**
+1 -1
View File
@@ -1874,7 +1874,7 @@ Moved verbatim, in this order.
| M13 ❓ | **Advanced metrics — LibreHardwareMonitor's CPU, memory, motherboard and storage groups, elevated, with PawnIO (D103, 2026-11-11).** Never opened by any build: §M10's elevated run has not been taken either, and this is a larger surface — a sensor chip on the LPC bus, the embedded controller, SPD over SMBus, SMART. Unknown: whether each group opens on the owner's board, what a refresh costs, whether opening the storage group touches removable drives (this PC once had a failing USB drive), and whether any group enables a privilege (`PrivilegeFootprintTests`). | **One elevated run with the probe verb, before the option exists.** Pre-committed: the storage group cannot be opened without touching removable drives → `lhm.storage.*` stays N/A in beta.39 and its reach reads `Deferred`; a node that throws twice → skipped for the session; the Agent above 1% of one core or 150 MB with the option on (NFR-2) → the slow groups are read less often or dropped before the release; a privilege enabled by a group → that group is not opened, and the owner is asked. **Two of the four answered 2026-11-11, before the option exists.** (1) **Storage: not opened, by the first outcome.** LibreHardwareMonitor 0.9.6's `StorageGroup` lists every drive through DiskInfoToolkit's `ReloadStorages` with no filter by bus and follows drives plugged in later — it cannot be opened without touching removable drives. `lhm.storage.*` reads `Deferred`, and `LhmGroups` has no member for it. (2) **Cost, unelevated, measured with `probe-advanced`** on the dev box: one refresh of the graphics-card group alone is 14 ms of processor time (62 ms elapsed) — 1.4% of one core at one a second, above NFR-2 — and one NVAPI read 0.4 ms. By the third outcome the sensor library is read every fifth tick (0.28%). **Still open, and the owner's**: the same probe as administrator with PawnIO — whether the processor, memory and motherboard groups open on this board, what they cost, and `PrivilegeFootprintTests`' new case on a token that holds the privileges (CI's does; the dev box's unelevated run passes by construction). **The first run was taken on 2026-11-12, by the owner, in ordinary use** (0.1.0-beta.40, the Agent as administrator with PawnIO, an i7-14700KF on a board with an IT8689E chip, an RTX 5080), and read here from a copy of the ledger and the Agent's log, not from a probe. **The groups open and read**: nine of ten sessions stored 119 processor series (a clock and a load per thread, temperatures, powers, voltages), 14 memory series and 21 motherboard series (six fans, six temperatures, nine voltages) beside the card's 41 — 195 from the sensor library in all. **No value was compared with another tool**; that is still the owner's. **Two faults, one cause** (`Infrastructure.Telemetry.LhmLibrary`): the Agent held up to three `Computer`s at once, and the library keeps the driver it reads the processor through and its bus mutexes per process — closing one `Computer` let go of them under the others. After seven sessions the Advanced reader's processor device threw `NullReferenceException` twice and was left alone (the page lost the processor until the reader reopened); once a session's start met another instance's close, the reader's `Open` threw `ObjectDisposedException`, and that session stored 17 series instead of 212. **Fixed 2026-11-12**: opens and closes are serialised and a `Computer` is parked, not closed, while another is in use. The cause is read from the log's timing and was not reproduced — it needs this elevation — so **whether the faults are gone is the owner's next sessions to show**: no `advanced: a device is left alone` and no `did not open` in the Agent's log. **First evidence, 2026-11-12, 0.1.0-beta.41, the same PC:** seven sessions between 06:38 and 07:01 with no `advanced:` line at all, each with the option on storing 212 or 213 series; on beta.40 that morning the processor device faulted out after each of six sessions (04:34–05:07) — thirteen of sixteen over the night. The reader failing to open was seen once in sixteen, so this is not yet enough to call that one gone. Still open: any value beside another tool. |
| M16 ✅ | **The L2 telemetry layer's cost — the first number, and it is above NFR-2 (found 2026-11-11, measuring something else).** `LhmTelemetrySource` refreshes LibreHardwareMonitor's graphics-card group once a second in every recorded session. `probe-advanced` measured that refresh, through the same library and the same group, at **14 ms of processor time** on the dev box (RTX 5080, 41 mapped sensors, about twenty of them the Direct3D engine nodes the library enumerates per card) — 1.4% of one core, where NFR-2 allows the whole Agent 1% during capture and `14_TESTING` §Hook overhead's Agent figure has never been measured. This is a measurement of the call, not yet of a session: L2's own poller was not instrumented. | **Measure L2 in a session** (the Agent's processor time over a ten-minute capture, telemetry at 1000 ms and at 2000 ms). Pre-committed: at or under 1% → this row closes with the number; above → the owner chooses between a slower default for `telemetry.interval_ms`, reading the sensors the layer keeps from NVAPI on NVIDIA cards (L3 already has most, at 0.4 ms), or amending NFR-2 to what is measured. Not decided here, and nothing about L2 changes in the Advanced-metrics train. **Measured in a real Agent, 2026-11-11 (owner decision D110), and answered (D117).** `tools/agent-cost.ps1` runs the shipped `FrameLedger.Agent.exe --console capture` against a copy of hook-harness in a scratch data folder — a session that is not hooked, so the telemetry poller runs as in every session and nothing drains frames — and reads the Agent process's own processor time at exit; the cost per second is the slope between a 45 s and a 165 s session, two runs of each. Dev box (RTX 5080, not elevated, layers `l1+lhm+nvapi`): **19.3 ms of processor time per second of session = 1.93 % of one core with Advanced metrics off** (2,312 and 2,312 ms over 45 s; 4,594 and 4,656 ms over 165 s), **20.4 ms = 2.04 % with it on** (2,984 and 3,000; 5,547 and 5,344); peak working set 113 MiB and 119 MiB. A first pass with 30 s and 90 s sessions gave 1.56 % and 2.21 % — its two short runs differed by 670 ms, which is why the lengths were raised. So the probe's number holds in a session: the Agent's steady cost is about twice NFR-2's 1 %, nearly all of it the layer every session has always used, and the new option adds about a tenth of a percent. **The owner's answer: NFR-2 is amended to ≤ 2.5 % of one core** — the limit had never been measured, the sensors keep their one reading a second, and nothing in the code changes. Not measured: a hooked session (the drain's cost on top), a session with the Agent elevated and PawnIO's groups open, another PC. |
| M14 ❓ | **Reflex latency per frame — is there a route within rules 4 and 5? (Train C, 2026-11-11.)** `17_HOOK_ENGINE` §Memory / latency names hooks on `NvAPI_D3D_SetSleepMode` / `SetLatencyMarker` and a call to `NvAPI_D3D_GetLatency`. NVAPI resolves all three through `nvapi_QueryInterface` by id — they are not exports, so a hook on them is a patch at an address learned at run time, the class refused on 2026-08-09. The route to try first needs no hook: the Overlay's own background thread **calls** `GetLatency` with the device of the swap chain it already hooks, once a second (the call returns the last 64 frames' reports). Unknown: whether calling into the driver from that thread is safe on every device kind, what it costs, what it returns when the game never enabled Reflex, and what it means for the Disclaimer's sentence about that thread. | **A spike on `hook-harness` and a stub first, then one real title.** Pre-committed: no route without a patch at a run-time address or a loader-lock call on the game's thread → Reflex stays N/A and the page says why; overhead above NFR-1 → the same. The owner says go or no on the spike's result. **2026-11-12 — the reading that comes before that spike is `spike-notes` §30** (owner decision D130: a document first, beside 0.1.0-beta.45; nothing was run). It finds: a hook on NVAPI's latency functions is the refused class, and a hook on Streamline's Reflex and PCL functions is train D's wrapper (§M15) — and would miss a game that fetched them before the attach, as `slInit` is missed (D129); the Overlay calling `slReflexGetState` itself breaks the thread contract the vendor's header states; **what remains is the route named in this row**, the Overlay calling two driver getters with the game's device, and a no-injection ETW route that gives the game-side markers only and makes the game post messages to its own window. Corrected there: `nvapi64.dll` exports **two** functions on the dev box (`nvapi_Direct_GetMethod` beside `nvapi_QueryInterface`), not one. The go or no is the owner's, and a go needs the owner's ruling that calling a driver getter with the game's device is inside rule 4. **2026-11-13 — the owner answered (D132, D133).** Route D goes to the spike this row names, on `hook-harness` and a stub `nvapi64.dll`, with the ruling: a driver's read-only getter called with the device of the swap chain the Overlay hooks is inside rule 4 (`CLAUDE.md`, the rule's note of that day). No real game before the owner has seen the result, and nothing shipped changes for the spike (`spike-notes` §31, written after 0.1.0-beta.46). Route C is **refused**; the ETW route **stays closed**, and §G is not reopened. **2026-11-13 — the harness spike is done (`spike-notes` §31), and none of its stop conditions fired.** With a stand-in module: nothing is called or loaded when `nvapi64.dll` is absent, a missing getter is refused whole, an error and a report of nothing read as what they are, and a call the driver holds for seconds stops only the thread that made it — so not the watchdog. With the installed driver (32.0.16.2114, RTX 5080), in the probe's own process and with the probe setting the markers a game would: no fault before `NvAPI_Initialize`, without markers, or across 38 million reads beside a marker-setting thread; a call costs half a microsecond to a microsecond and a half; the report is readable from markers alone, in microseconds; and the Direct3D 12 **device** — the object the Overlay already holds — is what the driver takes. What only a game can say is unanswered: a game's own device, a real report, another driver. **The owner's next word is go or no for one real title**; a go is a plan of its own first. **2026-11-13, the same evening — go (D136)**: a plan for one title, Cyberpunk 2077; no code before the plan is approved, and no release carrying it before a stop while a game runs has been exercised on 0.1.0-beta.46 (owner-only item 44 (d)). **2026-11-13, the plan and four more answers (D138–D141).** The read has **no switch of its own**: it is part of Advanced metrics, so after the release it reaches every Direct3D 12 game that loaded the driver's `nvapi64.dll`, for everyone who switched Advanced metrics on — "one title" is the order of the owner's first runs, not a limit in code (D138). The probe ran a leg with a sleep mode first (D139; `spike-notes` §31, *The leg with a sleep*): **the getters do not wait behind `NvAPI_D3D_Sleep`** — thirty-one million reads beside a thread that slept 97 % of the time, none of a millisecond; a read after a sleeping frame costs about 2.6 µs. An `nvapi64.dll` loaded from the game's own folder is refused with the reason (D140). One call of 2 ms or more switches the read off until the game exits (D141). The plan's design, as reviewed against the source, is in [`handoff/history/0.1.0-beta.46.md`](handoff/history/0.1.0-beta.46.md) §The train after 0.1.0-beta.46. **2026-11-13, night — written; released as 0.1.0Line truncated
| M15 ❓ | **The Streamline state behind `slGetFeatureFunction` — re-examined, not reopened (Train D, 2026-11-11).** The owner asked for the refusal in `handoff/history/p0-queue-1-6.md` to be looked at again. `18_GPU_VENDOR_APIS` §The trains states the route to try (hook the export, hand back a wrapper for a fixed list of names) and what it raises: the wrapper is a write to what the game receives, which rule 4 forbids as written; a wrapper must outlive the Overlay's unhook; a game that fetched its functions before the hook existed is never seen. | **A written design against each of the five grounds, then a spike.** Pre-committed: any ground unanswered → the route stays refused, and `sl.dlssg.*`, `sl.reflex.*` and the rest of that block read N/A with "refused" as the reason. Proceeding needs the owner's amendment of rule 4, asked with the rule quoted. |
| M15 🅓 | **Decided 2026-11-14 (D154): not built. The owner closed Advanced metrics with the refusal standing; the ten entries are listed as not read, with the reason.** ~~**The Streamline state behind `slGetFeatureFunction` — re-examined, not reopened (Train D, 2026-11-11).**~~ The owner asked for the refusal in `handoff/history/p0-queue-1-6.md` to be looked at again. `18_GPU_VENDOR_APIS` §The trains states the route to try (hook the export, hand back a wrapper for a fixed list of names) and what it raises: the wrapper is a write to what the game receives, which rule 4 forbids as written; a wrapper must outlive the Overlay's unhook; a game that fetched its functions before the hook existed is never seen. | **A written design against each of the five grounds, then a spike.** Pre-committed: any ground unanswered → the route stays refused, and `sl.dlssg.*`, `sl.reflex.*` and the rest of that block read N/A with "refused" as the reason. Proceeding needs the owner's amendment of rule 4, asked with the rule quoted. |
| M10 ✅ | ~~PDH `\GPU Engine(*)\Utilization Percentage` summed across engines does not reproduce the Task Manager figure the doc invokes. Decide what we actually report and label it accordingly~~ **Decided 2026-09-09 (PR-E1): L1 does not read the engine counters at all.** `LoadPct` is L2's vendor-reported `GPU Core` load (measured ✓ on NVIDIA, §M5 row R1) and is labelled *GPU load (vendor)* wherever it is shown; on a machine without L2 the field is N/A, never a sum that is not the number the user expects. What L1 does read from PDH is one counter, `\GPU Adapter Memory(luid_…_phys_0)\Dedicated Usage`, bound by LUID — the figure Task Manager labels "Dedicated GPU memory", measured 1301 MB at an idle desktop on the RTX 5080. Reopening this needs a measurement of `max(engine)` against Task Manager's own number, not a decision |
#### §M5 — the decision table, pre-committed 2026-09-03 BEFORE the first run
+156
View File
@@ -0,0 +1,156 @@
# 21 — Input devices: controllers, and keyboard-and-mouse activity
What FrameLedger reads about game controllers and about the keyboard and mouse, from where, and what it never reads.
The numbers a session makes of it are in [`03_METRICS.md`](03_METRICS.md) §Input; the columns are in
[`06_DATA_MODEL.md`](06_DATA_MODEL.md).
> **Status, 2026-11-14 — the reader exists and the Agent does not start it yet.** The model and the arithmetic
> (`FrameLedger.Domain.Input`, `FrameLedger.Application.Input`, `Application.Recording.InputSessionBuilder`), the
> storage (schema 0024, the `.partial` file's chunk 11, the finalizer for both tiers — `06_DATA_MODEL`) and the reader
> itself (`Application.Input.InputReader`, `Infrastructure.Input`) are written and under test. Nothing composes the
> reader into the Agent: the switch, the terms and the screens come in the pull requests after this one, and this
> note is rewritten by each. **No report from a real controller has passed through any of this code**
> (owner decision D157): the developer has no controller, and what happens on a real one is owner-only item 48.
## The owner's request and decisions (2026-11-14)
The request: whether a game supports controllers, on the game's page; the share of a session played with a controller
and with the keyboard; how often a controller connected and disconnected in a session; the battery state that lasted
longest; switches between makers' controllers and each maker's share; stored, and drawn; Xbox controllers and the
DualSense first.
| | Decision |
|---|---|
| **D155** | Controllers are read **by the Agent, from outside the game**. No hook is added to a game and CLAUDE.md rule 4 is untouched. A session that is not hooked has the numbers as a hooked one does. |
| **D156** | The reading is **on unless switched off** (Settings ▸ Controllers and input, `capture.input_devices`), and **reads nothing until the Privacy Policy that describes it — 2.22 or later — has been accepted on the PC**. An Agent that the logon task started after an update records sessions without it until the App has been opened once. |
| **D157** | **Built without a probe.** Asked whether to run a probe tool with real controllers first, the owner chose to build straight. So every source says what it did (§What the reader says about itself), and each pull request and `LIMITATIONS.md` say what was verified against hand-made data only. |
| **D158** | Keyboard and mouse are **one class, known only by the time of the last input** (`GetLastInputInfo`). No Raw Input registration for a keyboard or a mouse, no hook: no key ever enters FrameLedger's process. |
| **D159** | **Nothing is ever sent to a controller**: no output report, no feature-report request, no `XInputSetState`. A DualSense on Bluetooth therefore has a battery level only when Steam or the game has already switched it to its long report (§DualSense). |
| **D160** | The numbers are **in the CSV/JSON export and in a bug bundle** — they are columns of `sessions`, as the display mode's are — and the Privacy Policy's §3A says so. |
| **D161** | **A session that is not hooked is: duration, hardware telemetry, the reason — and what the Agent reads from outside the game** (the game's memory since beta.12, controllers now). Every field measured inside the game still reads N/A. CLAUDE.md's sentence is amended with the pull request that makes it true. |
| **D162** | Also built: the number of switches between a controller and the keyboard and mouse, and the share of time with no input; marks on the frame-time chart where a controller connected, dropped or ran low; a battery's first and last level and its rate; the kind of connection; a note where Steam Input presented the controller as an Xbox pad; a trend metric, a row in Compare, and "usually played with" on the game's page. |
| **D163** | "Supports controllers" is **three pieces of evidence, never a verdict**: what Steam's own file on the disk says (no network: rule 8), which input libraries the game loaded, and how the game was actually played. From outside a game one can know that a controller was in use while the game was in front — not what the game did with it. |
## What is read, and from where
Everything is a Windows API in a library Windows ships. **No third-party library is added.**
| Source | What it gives | Why this one |
|---|---|---|
| Raw Input (`RegisterRawInputDevices`, usage page 1, usages 4 and 5, `RIDEV_INPUTSINK \| RIDEV_DEVNOTIFY`; `GetRawInputBuffer`, `GetRawInputData`, `GetRawInputDeviceInfo`, `GetRawInputDeviceList`) | the reports game controllers send, while the Agent is in the background; a controller arriving and leaving; its vendor and product ids | the documented way to receive a HID controller's reports without being in front, and it opens no handle to the device |
| XInput 1.4 (`XInputGetState`, `XInputGetCapabilities`, `XInputGetBatteryInformation`) | each of its four pads: its state, wired or wireless, a battery in four levels | what an Xbox pad's battery is reported through |
| `GetLastInputInfo` | the time of the last keyboard or mouse input in the user's session | a time and nothing else (D158) |
| `GetForegroundWindow`, `GetWindowThreadProcessId` | whose window is in front | already used for the focus sample (`04_CAPTURE`) |
| Steam's `appcache\appinfo.vdf`, on the disk | whether the store lists controller support for a library game | a local file: no request is made (rule 8) |
**Rejected, with the reason** (the checklist of `18_GPU_VENDOR_APIS` §Checklist applies to any library):
- **Windows.Gaming.Input** — its readings stop when the program is not in front, which the Agent never is.
- **GameInput** — on a PC it is a NuGet package under Microsoft's licence terms with a redistributable to install.
- **Opening the HID device** (`CreateFile`) — a handle of FrameLedger's on a controller can make a game's, or a
remapper's, exclusive open of it fail. Raw Input needs none.
- **A sixth native library** — parsing bytes a device controls in C++, inside an Agent that may run as administrator.
The reader is C#, and what parses a report is `FrameLedger.Domain.Input`, with no pointer in it.
- **Windows' own HID parser** (`hid.dll`'s `HidP_*`), to read *any* controller generically. It would have let a
controller of a maker this build does not know count as *in use* — and nothing here could be tried on one. A
controller whose layout this build does not know is listed, with its connections and drops, and is never *in
use*: a guess would be a made-up number (§The reader).
## What is never read
Which button, where a stick or a trigger is, the motion sensors, the touchpad; which key, what was typed, where the
mouse is; a controller's serial number, its Bluetooth address, its device path. A report is looked at to answer one
question — *is anything on this pad in use?* — and, for a DualSense, to take its battery byte; the answer is kept and
the report is not. `InputSessionBuilderTests` hold the stored JSON to a list of keys, so a key that could carry an
identifier has to be added to a test first.
## Who a controller is
By its USB vendor and product ids only (`Domain.Input.ControllerCatalog`): Microsoft is the Xbox family, Sony
PlayStation, Nintendo Nintendo, anything else *other* — except that a pad Windows presents through XInput is in the
Xbox family whoever made it, because that is all Windows says of it. A model has a name only where the catalog lists
its ids; a wrong name would be worse than none. Two pads of one model on one kind of connection cannot be told apart
across a reconnect, and are not.
## XInput
A state is a pad *in use* when a button is down, a trigger is past `XINPUT_GAMEPAD_TRIGGER_THRESHOLD` or a stick is
outside its `XINPUT_GAMEPAD_*_THUMB_DEADZONE` (`Domain.Input.XInputPad`) — a stick held counts, one that drifts inside
the dead zone does not. Its battery is XInput's words: a wired pad, or four levels with no word for charging.
Two things about XInput are not established and are what item 48 is for: Microsoft's page for `XInputEnable` says
that on Windows 10 and later "game controller input is automatically enabled/disabled by the system based on the
application window focus", which may mean a program in the background reads a neutral state; and a pad on Bluetooth
is reported not to answer `XInputGetBatteryInformation`. XInput also has no documented way to say which device one of
its four pads is.
## DualSense
Sony's 054C:0CE6, and the Edge, 054C:0DF2 (`Domain.Input.DualSenseReport`). Three reports:
| Connection | Report | What it carries |
|---|---|---|
| USB | `0x01`, 64 bytes | sticks, triggers, buttons — and the battery: a level in tenths and what the battery is doing |
| Bluetooth, as connected | `0x01`, 10 bytes | sticks, buttons, triggers. **No battery** |
| Bluetooth, once switched | `0x31`, 78 bytes | the USB report's body, one byte later |
The pad sends the short report until some program asks it for a feature report or sends it an output report; from then
until it reconnects it sends the long one. **FrameLedger never asks** (D159): a game that reads the short report through
DirectInput would lose its input. So over Bluetooth the level is there when Steam or the game switched the pad, and is
not otherwise. Windows hands every report of a device over at the length of the device's longest, so the short report
arrives padded to 78 bytes with the id the USB report has: the connection, not the length, says which layout a report
`0x01` has.
The layout was written from the open descriptions of the protocol. No code was taken from the Linux kernel's driver,
which is under a licence this project cannot take code from.
## The reader
`Application.Input.InputReader` over `Infrastructure.Input.Win32InputBackend`, on the thread of
`Infrastructure.Input.InputDeviceHub` — named `fl-input`, and **there only while a session has a view of the hub**:
with no session there is no thread, no window and no registration.
**A slice, about ten times a second.** The reader takes what Windows has: the controllers that came and went, the
reports that arrived (in bulk — `GetRawInputBuffer` — not one message at a time: a DualSense sends some hundreds a
second, and the Agent's whole budget is 2.5 % of one core, NFR-2), the state of XInput's connected pads, the time of
the last keyboard or mouse input, and the process whose window is in front. From that it makes one `InputSlice`,
the same for every session that is running; each session's view counts it when a window of *its* game was in front
(`Application.Input.InputTickAccumulator`), and the telemetry poller takes the sum once a second.
**The window.** Raw input is delivered to a window. The reader's is a child of `HWND_MESSAGE`: never shown, in no
task bar, receiving no broadcast, answered by Windows' default procedure. It is registered for HID usage page 1,
usages 4 (joystick) and 5 (gamepad) — `InputReader.RegisteredUsages` — and for nothing else.
**What a controller is.** Each of XInput's pads that is connected is one; each controller Windows does *not* present
through XInput is one. A device Windows presents through XInput is also seen by raw input and is **not** a second
controller: it gives the pads their name where that cannot be mistaken — every XInput-class device a player could
hold has the same two ids — and is otherwise only the witness of the next paragraph. An empty XInput slot is asked
about once in twenty slices (XInput looks for a device each time) and at once when a controller arrives or leaves;
a connected pad's battery once in fifty.
**Where XInput says nothing.** If XInput returns a pad at rest for ever because the Agent's window is never in front
(§XInput), the device's own reports are the evidence: a slice in which an XInput-class device's reports *changed*
while no pad's packet number moved — in that slice or the one before — is counted (`XInputSilent`). After ten of
them, **and only if XInput has never once been seen to move**, such a slice counts the lowest connected pad as in
use. That is coarser than XInput's dead zones — a stick that drifts counts — and is used only where the better
source is silent; a session's stored counts say which it was.
**Which controllers are read for use.** XInput's pads, and a DualSense by its own reports. Any other controller —
a DualShock 4, a Switch Pro controller — is listed with its connections and drops and is never *in use*.
**Faults.** A slice that throws is counted and skipped; twenty in a row end the run with one line in the Agent's
log, and the sessions go on without readings. When a run ends, one line says what it did: slices, whether Windows
accepted the registration, reports received and not read, XInput's reads and silent slices, whether the time of the
last input could be read, the thread's processor time, faults. Nothing in it names a device.
**Held by a gate.** `tools/input-readonly-check.ps1` (`12_BUILD` step 14g): the reader's calls are a committed list,
none of which sends to a device, injects input or reads a key; no other managed source and no native source names
an input function.
## What the reader says about itself
`Application.Input.InputHealth`, carried by every reading and stored with the session: whether Windows accepted the
registration, how many reports came and how many could not be read, whether XInput's library was there and how many
states it returned, how often a controller's own reports said *in use* while XInput said nothing, whether the time of
the last input could be read, how many slices were taken and how much processor time the reader's thread used. Counts
and yes-or-no answers; nothing in it names a device.
+91 -8
View File
@@ -151,18 +151,42 @@ and its release facts are [`handoff/history/0.1.0-beta.48.md`](handoff/history/0
### NEXT
1. **The owner runs item 47** — pairs, frame generation off and on, and a handful of short sessions. Every
outcome's meaning is written there.
2. **Then the owner's to say**: what to do about *GPU render* once the counts say whose the difference is — a
label, or the mean; more titles; D141 on a larger sample (the slowest call seen in a game is 123 µs).
1. ~~**The owner runs item 47**~~ **Run and read 2026-11-14** (item 47, *Run 2026-11-14*): the difference in
Cyberpunk 2077 is the driver's, the holes are gone from steady play, off means off, and the stop fired once.
2. **The two GPU labels were reworded on the owner's word** (D152, 2026-11-14; strings in three languages, the
guide — in `[Unreleased]`, not in a release yet). **D141's stop stays as it is, and nothing more of Reflex is read** (D153, the owner
the same evening: "it only has to tell whether the game has it or not; Kingdom Come: Deliverance II has no
Reflex in its settings" — so that session lost nothing to the stop). (f) and (g) are said: the App's *Low
Latency Mode* is off, and no hitch.
3. **`slAllocateResources`** keeps its patch (D135); looked at again when there are more sessions.
4. **Train D** after it, the same way: a spike first — `sl.pcl.markers` waits for it, and §30 found its hook
would miss a game that fetched its functions before the attach.
4. ~~**Train D**~~ **Advanced metrics is closed (D154, 2026-11-14): train D is not built.** The owner was shown
the catalog — 140 entries, 110 read — and what the ten entries of reach `Spike` hold (Streamline's own headers,
2.14.16: DLSS frame generation's options and state, the video-memory estimates, ray reconstruction's, Image
Scaling's and Dynamic Vibrance's options, the PCL markers), with what reading them takes: a function of ours
handed to the game in place of Streamline's (rule 4), which a game that fetched its functions before the
attach never calls. The owner: "Đóng luôn". The ten are `RefusedRoute` now, the guide no longer says a later
release reads more, and §M15 is decided. **What is next is the controller feature**, planned in a session of
its own.
### 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, with what SonarCloud and Qodana said.
- ~~**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, with what SonarCloud and Qodana said.~~ **Recorded
2026-11-14: 0.1.0-beta.49 was released 2026-11-14T11:12:44Z** (18:12 in the owner's time zone) from the signed
tag on `afe4984` (#459), by run 43587336452 — 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, and the portable package hashed
here equals its line; the five native libraries in it carry `FL_BUILD_ID v0.1.0-beta.49`, none of them
`-dirty`. The delta from beta.48 is 1 100 211 bytes beside a full package of 110 803 443 — "Delta processed
0452 files. 0023 patched, 0429 unchanged". The wiki was published by run 43588972123. **Two rehearsals on the
release branch**: run 43580081466 at `1ab2809`, and — after a test-only fix reached the branch — run
43581734484 at `9f94356`, whose tree is the released one (a delta of 1 134 949 bytes, the same file counts).
**SonarCloud analysed `afe4984`: the quality gate passed and no issue is open on `main`. Qodana's two reports,
CodeQL and `check` are green on that commit.** On the way two advisory checks did find something, each in a
test of this train and each fixed before its pull request merged: Qodana's native report on #456 (two
products widened after the multiplication), SonarCloud on #457 (a line of the log handed to `printf`). **The
train stopped once for the owner**: two signed merges timed out at the passphrase prompt after #457; it went on
when the owner had unlocked the key. The tag's message reads `FrameLedger 0.1.0-beta.49` where the tags before
it read the bare version — nothing reads it, and a pushed tag is not moved.
- **Why Cyberpunk 2077's active render is longer than its span without frame generation** — item 47's to say. A
third session that afternoon repeated it (233: 3.40 against 3.13 ms at 292 of 296 samples) and a session of
menus did not (232: 0 of 126).
@@ -940,6 +964,53 @@ left unexercised; item 40 (d).
*(e) has a `LATENCY` or `LATENCY_FRAMES` line* — off does not mean off: say so at once, with the log.
**A fault, a freeze, a game closing by itself, a hitch every second, or a session that says *stopped***: as
item 45 says for each — say so at once.
**Run 2026-11-14 (sessions 236–245, ten on 0.1.0-beta.49), read the same day** from a copy of the ledger and
the Overlay's logs. All ten tier 1, exit code 0, no fault, nothing dropped. Phantom Blade Zero twice (236
without frame generation, 1 108 s; 237 with ×2, 811 s), Kingdom Come: Deliverance II (238), Clair Obscur (239),
Black Myth: Wukong (240), Lies of P (241, and 245 with the option off), Hogwarts Legacy (242), Dying Light: The
Beast (243), Cyberpunk 2077 (244). 239 and 240 ran at the same time, and so did 241, 242 and 243.
(a) **No new acceptance row** after the update: the terms window did not appear.
(b) **Cyberpunk 2077 was one session of 125 s without frame generation** (374 FPS); ×2 and the menus were not
run. It is enough for the question. 88 reads in one state — low-latency mode on, the game sleeping, ×1 — summed
5 394 frames: **4 917 in "active longer than span", mean span 1 571 µs, mean active 1 849 µs**; 96 within
(3 866 / 3 431 µs); 381 with a span of no length and an active time; none absent, none refused. **So the
difference is the driver's**: on frames that have a real span, its active time is 278 µs (18 %) longer than
the two marks are apart. A small part is ours as well — 7 % of the frames have a span of no length and pull the
span's mean down (the stored means are 1 892 and 2 138 µs). With frame generation on it is not measured on
this build (0.1.0-beta.48's means: never longer).
(c) **The count is not what is wrong**: in the six other sessions that reported (five games), **not one frame of 129 900** is
in "active longer", and no span is absent or of no length. Phantom Blade Zero: without frame generation
63 123 frames, span 16.4 ms, active 11.1 ms; with ×2 21 209 frames, span 33.2 ms, active 12.6 ms.
(d) **The holes**: in batches of twenty reads or more a read took 1 000.94 ms (236), 997.18 (237), 999.99 (242,
244), and up to 1 013 ms in the sessions that shared the PC with another game. Samples without a
report: 236 — 40 of 1 106, **39 of them in the first 46**, while the game started; 237 — 36 of 809, in the first 42 and
the last two; 244 — 9 of 123, in the first ten. Before, they were spread through a session (0.4–16 %). **D150 did what
it was for.** Where two or three games ran at once the holes are blocks in which the game did not present
(240: 103 of 477; 242: 80 of 402, 68 of them at its start; 243: 37 of 414; 239: 23 of 184): a read is taken on
the presenting thread, so a game that presents nothing is not read — Lies of P's log has sixty reads in 189 s.
(e) **Off means off**: session 245 has no `LATENCY` line and no Advanced row.
**The stop fired in a real game for the first time** (D141): Kingdom Come: Deliverance II, 12 s after the
attach, while the game was starting — the seventh read took 5 337 µs, and no further read was made; the
session says so (`Slow`), the game ran 287 s and closed normally. No frame had been reported in those seven
reads. **The owner: that game has no Reflex in its settings** — so there was no report to lose; the
session's line says *stopped* where, without the slow call, it would have said *the driver reported no
frame*. Elsewhere the slowest call was 22–235 µs. In Lies of P the driver reported no frame at all.
**What the states say of Reflex and frame generation** (each batch carries its own): low-latency mode was
**on at a multiplier of 1** in Cyberpunk 2077 (88 reads), Black Myth: Wukong (253), Hogwarts Legacy (299) and
Dying Light: The Beast (345); Phantom Blade Zero without frame generation sleeps through Reflex with
low-latency mode **off** (1 062 reads) and switches it on with ×2; Clair Obscur without frame generation has
both off and still reports its frames. The logs cannot say whether a game's menu or the NVIDIA App switched
the mode on. NVIDIA's own guide makes frame generation need Reflex and not the reverse
(`spike-notes` §30, *Added 2026-11-14*). Hogwarts Legacy gave a multiplier of 6 for seventeen reads.
(f), (g) **The owner, the same evening: "App reflex off, không khựng"** — *Low Latency Mode* is off in the
NVIDIA App, and no hitch. Read with (f) as it was asked, for Cyberpunk 2077: the low-latency mode its 88
reads show at a multiplier of 1 is then the game's own Reflex and not the App's override — Reflex on without
frame generation, as NVIDIA's guide allows. **Then shown, in two screenshots**: the NVIDIA App's *Program
Settings* for Cyberpunk 2077 have *Low Latency Mode* **Off**, set for that program (the rows that follow the
global setting read "Global - …"; this one does not); and the game's own *Video* page has **NVIDIA Reflex Low
Latency: On**, V-Sync off, borderless at 2560×1440, 378 FPS on the game's counter. So the driver's
`bLowLatencyMode` on, at a multiplier of 1, is the game's menu, seen from both sides. **The owner's**: the wording of the two GPU labels — *idle time excluded /
included* does not describe a game whose active time is the longer.
**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
@@ -1105,6 +1176,18 @@ Where each owner decision is recorded — the file and its section, and a label
| D149 | [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Native logging | told that a bug report carries the five newest Overlay logs and so these lines: **no change to the legal texts** — the Privacy Policy names the logs of the component loaded into games, and the lines are counts and sums of microseconds |
| D150 | [`07_IPC.md`](07_IPC.md) §Region 5 | the samples that carry no report are mended **on both sides**: the Overlay reads and publishes on a grid of one second, and the Agent no longer overwrites a reading that waits for a sample |
| D151 | [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Native logging | the owner's word: Reflex is checked together with frame generation — without it the owner's games do not switch Reflex on, and a low-latency switch that reads on and off is the NVIDIA App's override. A batch of counts belongs to one state of the sleep status |
| D152 | [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §The inventory | the two GPU labels say what each figure is — *the driver's own figure*, *between the driver's start and end marks* — not "idle time excluded / included": item 47 counted the active time as the longer in Cyberpunk 2077. Strings only; numbers and means unchanged |
| D153 | [`spike-notes/30-reflex-latency.md`](spike-notes/30-reflex-latency.md) *Added 2026-11-14* | the owner's word: of Reflex it is enough to tell whether a game has it. Reflex and PCL leave train D (`sl.pcl.markers` stays refused), and D141's stop is not changed for a game's first seconds. My reading of one sentence; nothing shipped is removed by it |
| D154 | [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §The trains, [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) §M15 | Advanced metrics is closed: train D is not built, the ten Streamline entries that waited for a spike are not read (`RefusedRoute`), rule 4 is not amended for them. Nothing shipped is removed |
| D155 | [`21_INPUT_DEVICES.md`](21_INPUT_DEVICES.md) §The owner's request and decisions | controllers are read by the Agent, from outside the game: no hook is added, rule 4 is untouched, and a session that is not hooked has the numbers too |
| D156 | [`21_INPUT_DEVICES.md`](21_INPUT_DEVICES.md) §The owner's request and decisions | the reading is on unless switched off (`capture.input_devices`), and reads nothing until the Privacy Policy that describes it (2.22 or later) has been accepted on the PC |
| D157 | [`21_INPUT_DEVICES.md`](21_INPUT_DEVICES.md) §The owner's request and decisions | built without a probe run on real controllers first ("Xây thẳng"): every source reports what it did, and what was verified against hand-made data only is said in each pull request |
| D158 | [`21_INPUT_DEVICES.md`](21_INPUT_DEVICES.md) §The owner's request and decisions | keyboard and mouse are one class known only by `GetLastInputInfo`'s time: no Raw Input for them, no hook, no key in the process |
| D159 | [`21_INPUT_DEVICES.md`](21_INPUT_DEVICES.md) §DualSense | nothing is ever sent to a controller; a DualSense on Bluetooth has a battery level only where Steam or the game switched it |
| D160 | [`21_INPUT_DEVICES.md`](21_INPUT_DEVICES.md) §The owner's request and decisions | the numbers are columns of `sessions`, so they are in the CSV/JSON export and in a bug bundle, and the Privacy Policy's §3A says so |
| D161 | [`21_INPUT_DEVICES.md`](21_INPUT_DEVICES.md) §The owner's request and decisions | a session that is not hooked is duration, hardware telemetry, the reason — and what the Agent reads from outside the game; CLAUDE.md's sentence is amended with the pull request that makes it true |
| D162 | [`03_METRICS.md`](03_METRICS.md) §Input | also built: switches of method and the share with no input, marks on the frame-time chart, a battery's first and last level and its rate, the kind of connection, the Steam Input note, a trend metric, a Compare row, "usually played with" |
| D163 | [`21_INPUT_DEVICES.md`](21_INPUT_DEVICES.md) §The owner's request and decisions | "supports controllers" is three pieces of evidence and never a verdict: Steam's own file on the disk (no network), the input libraries the game loaded, how the game was played |
| 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`) |
---
+1
View File
@@ -69,6 +69,7 @@ are safety items, and something listed there as unresolved should not be built t
| [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) | Telemetry layers (DXGI/PDH, LibreHardwareMonitor, NVAPI), the game process's memory, licences |
| [`19_SAFETY_AND_ANTICHEAT.md`](19_SAFETY_AND_ANTICHEAT.md) | The anti-cheat guard, what a finding does, the user-mode exception, what will never be built |
| [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) | Every unresolved question, defect and measurement, with its status marker |
| [`21_INPUT_DEVICES.md`](21_INPUT_DEVICES.md) | Controllers and keyboard-and-mouse activity: what is read from outside the game, from where, and what never is |
| [`HANDOFF.md`](HANDOFF.md) | Sequencing, the open owner-only items, the index of the owner's decisions |
| [`handoff/`](handoff/) | Since beta.24 (D66): the history of every train and phase, the passed owner-only items, the traps — moved out of `HANDOFF.md` verbatim |
| [`open-questions/`](open-questions/) | Since beta.24 (D66): the entries §S24 marks resolved, moved out of `20_OPEN_QUESTIONS.md` verbatim — a table there lists them |
+55
View File
@@ -175,3 +175,58 @@ route.
The spike is [`spike-notes` §31](31-reflex-route-d-harness.md), run on 2026-11-13: none of the stop conditions
above fired on the harness, and it ends in the question of one real title.
### Added 2026-11-14: Streamline's two programming guides, read against this note and the code
`docs/ProgrammingGuideReflex.md` and `docs/ProgrammingGuideDLSS_RR.md` of NVIDIA's Streamline repository, both
"Version 2.14.16", fetched as text and read whole — at the owner's request. What they add, and what they change.
**Reflex**
- **Low latency and frame generation: the dependency runs one way.** The guide lists the plugin's parts as
"distinct to each other without any cross-dependencies", wants Reflex's default to be *On*, and its checklist
tests *Reflex On* with frame generation **off**. Frame generation is what needs Reflex. The owner's "without
frame generation the game cannot switch Reflex on" is true of some of the owner's games' menus, not of Reflex.
The sessions of 2026-11-14 agree (HANDOFF, item 47): low-latency mode on at a multiplier of 1 in four games;
Phantom Blade Zero switches it on with frame generation; Clair Obscur without frame generation has it off.
- **The sleep and the markers are sent whatever the mode.** "`slReflexSleep` and `slPCLSetMarker` must always be
called even when Reflex Low Latency mode is Off"; the verification overlay's *App Called Sleep* stays 1 with
Reflex off. So `bUseGameSleep` says the game calls the sleep, **not** that Reflex is on, and a report exists
with Reflex off — which is what the sessions on 0.1.0-beta.48 showed (HANDOFF, item 46). Phantom Blade Zero
without frame generation is exactly this: the game sleeps, low-latency mode off, 1 062 reads.
- **`slReflexSetOptions` is called once, and again only when an option changes.** A hook on it would see nothing
in most sessions even if it could be placed: `nvapi.reflex.mode` stays refused for a second reason.
- **The markers are the report.** `slPCLSetMarker` replaces `NvAPI_D3D_SetLatencyMarker`, and the times the
markers carry (simulation, render submit, present) are the ones the driver hands back in the report this
product already reads (route D). `sl.pcl.markers` would add a count of calls, the ping and the flash trigger —
nothing a player reads. **Recommended to the owner: leave Reflex and PCL out of train D** — **decided the
same evening (D153)**: whether a game has Reflex is all that is wanted.
- **PC latency is not in the report, and NVIDIA takes it from outside the game**: its PCL statistics, read by
tools started from an administrator's prompt (route E here). D147 stands on that; two design tables that still
promised "PC latency as reported by Reflex" were corrected today (`03_METRICS`, `05_DETECTION`).
- **The stages, in NVIDIA's words** (the verification overlay's table): *driver* is from the first buffer
submission to the last present submission; *OS queue* from the first significant buffer submission to the end
of the GPU's work; *GPU* from where its rendering starts to where it ends; *total render time* is "time spent
by GPU rendering". With frame generation the test's own columns split the GPU's part at "DLSS FG start". **Not
reconciled with what is stored**: an OS queue that ends with the GPU's work should not be shorter than the
GPU's span, and in Phantom Blade Zero it is (12.9 ms beside 16.4 ms). The guide's table describes an overlay,
not the fields of `NV_LATENCY_RESULT_PARAMS`; nothing is concluded from it, and no label was changed on it.
- **Where Reflex helps**, by the guide: GPU-bound, or V-Sync with variable refresh; not CPU-bound. FrameLedger
shows the driver's switches and draws no conclusion about benefit.
**DLSS Ray Reconstruction**
- **The code already has it right, and two comments had the reason wrong.** The guide: "When DLSS-RR is switched
on, it completely overrides DLSS (Super Resolution)", in the quality mode set for DLSS, through
`slEvaluateFeature(sl::kFeatureDLSS_RR, …)`. That is the present detour's RR arm (upscaler DLSS, the RR fact
beside it), measured on Cyberpunk 2077 on 2026-08-15. `fl_shm.h` and `dllmain.cpp` still said super resolution
and RR "run together" / "in the SAME frame"; they do not, and the comments now say what is true.
- **Off is a mode, not a release**: "set `sl::DLSSDOptions.mode` to `sl::DLSSDMode::eOff`, note that this does
NOT release any resources". So *loaded* and *allocated* (the Advanced tables of 0.1.0-beta.45) are not *in
use*; the RR verdict is taken from evaluations and from nothing else, which is why it is right.
- **If `sl.dlssd.options` is ever read** (it is a spike entry, set through a call no hook sees): the structure
carries `worldToCameraView` and `cameraViewToWorld` — camera matrices, never read (rule 4) — and RR ignores the
DLSS options `sharpness` and `useAutoExposure`, so a session's DLSS rows do not describe RR on those two.
What the entry would add is RR's preset for each mode and how normals and roughness are packed. Little.
- **No dynamic resolution under RR**: a change of input size re-initialises the denoiser. Nothing here depends
on it.
+23 -12
View File
@@ -85,8 +85,9 @@ under which of the three happened to each.
### What NVIDIA's driver says about each frame's stages
On an NVIDIA card, in a **Direct3D 12** game that uses **NVIDIA Reflex**, a session with Advanced metrics on also
stores the driver's own latency report: how long the driver says each stage of a frame took — *simulation*,
On an NVIDIA card, in a **Direct3D 12** game that has **NVIDIA Reflex** built in, a session with Advanced metrics
on also stores the driver's own latency report — whether Reflex is on or off in the game's menu, because a game
with Reflex marks its frames either way: how long the driver says each stage of a frame took — *simulation*,
*render submit*, *present*, *driver*, *operating system's render queue*, *GPU render*, and the *total* from the start
of simulation to the end of the graphics card's work. They are seven lines under **Latency**, one point about every
second, each the average of the frames of one reading, in microseconds. A table beside them shows the driver's
@@ -95,14 +96,20 @@ low-latency state as five switches, by NVIDIA's own names, each *On*, *Off* or *
generated frames at ×2 for part of it). **They are the driver's switches, not the game's menu.** `bLowLatencyMode`
is on when the game switched Reflex on *and* when **Low Latency Mode** is set for that game in the NVIDIA App —
an override there shows here, and can read *On at times, off at others* in a game whose own setting never
changed. `bUseGameSleep` says whether the game itself is pacing its frames through Reflex; some games do that
only while frame generation is on, so read the two together.
changed. `bUseGameSleep` says whether the game calls Reflex's sleep each frame. NVIDIA asks games to call it even
while Reflex is off, so *On* there does not say Reflex is on — `bLowLatencyMode` does; some games call it only
while frame generation is on. Frame generation needs Reflex and not the other way round: the mode can be on
with `fgMultiplier` at 1.
**The stages overlap; they are not parts that add up to the total.** And *GPU render, start to end* includes the
time the card spent waiting between pieces of work — in one game it is longer than the whole frame. So a second
chart, **the graphics card's time per frame, as the driver works it out**, has two lines of the driver's own
figures: *GPU active render*, the same stage without the waiting, and *GPU frame time*, from the end of one
frame's work to the end of the next. A driver may give neither; the chart is then not there, and nothing is wrong.
**The stages overlap; they are not parts that add up to the total.** And *GPU render* is the time between two
marks the driver sets, at the start and at the end of the card's work on a frame: where the card waits between
pieces of work, the waiting is in it — in one game it is longer than the whole frame. So a second chart, **the
graphics card's time per frame, as the driver works it out**, has two lines of the driver's own figures: *GPU
active render*, how long the driver says the card worked on the frame, and *GPU frame time*, from the end of one
frame's work to the end of the next. **The active time is usually the shorter of the two, and not always**: in
Cyberpunk 2077 without frame generation it is about a fifth longer than the two marks are apart, frame after
frame — the driver counts work its marks do not enclose. Both are shown as the driver gives them. A driver may
give neither; the chart is then not there, and nothing is wrong.
Three things to know about them:
@@ -148,10 +155,14 @@ comes from, and whether it is read. Where it is not, the reason is written out:
administrator*);
- **not present on this PC** — the driver's own figures exist on NVIDIA cards only;
- **read inside a game FrameLedger measures, when the game makes the call** — what the game tells DLSS and FSR
(above). Some further readings inside the game **come with a later release**;
(above);
- **read inside a game FrameLedger measures, from the graphics driver** — NVIDIA's latency report (above);
- **not read: it would take a patch at an address found while the game runs, or a call the vendor forbids from
outside the game's own threads** — what the game asked of Reflex, and Reflex's state through Streamline;
- **not read: it would take a patch at an address found while the game runs, a function of FrameLedger's handed
to the game in place of the vendor's, or a call the vendor forbids from outside the game's own threads** — what
the game asked of Reflex, Reflex's state through Streamline, and what a game sets and asks through Streamline's
own functions for a feature: DLSS frame generation's options and state, the video memory DLSS estimates for
itself, and the options of ray reconstruction, Image Scaling and Dynamic Vibrance. No later release will read
these;
- **the game makes this call once, before FrameLedger is inside it** — what the game started Streamline with. It is
not read, and no later release will read it;
- **never read** — a serial number, a display's identification data, which other programs are encoding, the camera's
+3 -3
View File
@@ -958,7 +958,7 @@
<comment>review</comment>
</data>
<data name="AdvReach_RefusedRoute" xml:space="preserve">
<value>読み取りません: ゲーム実行中にしか分からないアドレスへのパッチ、またはゲーム自身のスレッド以外からの呼び出しをベンダーが禁じている関数が必要になるためです - どちらも行いません</value>
<value>読み取りません: ゲーム実行中にしか分からないアドレスへのパッチ、ベンダーの関数の代わりに FrameLedger の関数をゲームに渡すこと、またはゲーム自身のスレッド以外からの呼び出しをベンダーが禁じている関数が必要になるためです - いずれも行いません</value>
<comment>review</comment>
</data>
<data name="AdvReach_Spike" xml:space="preserve">
@@ -1054,7 +1054,7 @@
<comment>review</comment>
</data>
<data name="AdvToken_active_render" xml:space="preserve">
<value>GPU 実描画 (待機時間を除く)</value>
<value>GPU 実描画 (ドライバーの算出値)</value>
<comment>review</comment>
</data>
<data name="AdvToken_frame_time" xml:space="preserve">
@@ -1062,7 +1062,7 @@
<comment>review</comment>
</data>
<data name="AdvToken_gpu_render" xml:space="preserve">
<value>GPU 描画、開始から終了まで (待機時間を含む)</value>
<value>GPU 描画 (ドライバーの開始マークから終了マークまで)</value>
<comment>review</comment>
</data>
<data name="AdvToken_gsync_module" xml:space="preserve">
+3 -3
View File
@@ -724,7 +724,7 @@
<value>Not read: it would make the sensor library search every USB device</value>
</data>
<data name="AdvReach_RefusedRoute" xml:space="preserve">
<value>Not read: it would take a patch at an address found while the game runs, or a call the vendor forbids from outside the game's own threads - both refused</value>
<value>Not read: it would take a patch at an address found while the game runs, a function of FrameLedger's handed to the game in place of the vendor's, or a call the vendor forbids from outside the game's own threads - all refused</value>
</data>
<data name="AdvReach_Spike" xml:space="preserve">
<value>Being studied; not decided</value>
@@ -796,13 +796,13 @@
<value>Game Ready</value>
</data>
<data name="AdvToken_active_render" xml:space="preserve">
<value>GPU active render (idle time excluded)</value>
<value>GPU active render (the driver's own figure)</value>
</data>
<data name="AdvToken_frame_time" xml:space="preserve">
<value>GPU frame time, one frame's end to the next</value>
</data>
<data name="AdvToken_gpu_render" xml:space="preserve">
<value>GPU render, start to end (idle time included)</value>
<value>GPU render (between the driver's start and end marks)</value>
</data>
<data name="AdvToken_gsync_module" xml:space="preserve">
<value>G-SYNC module</value>
+3 -3
View File
@@ -719,7 +719,7 @@
<value>Không đọc: việc này khiến thư viện cảm biến dò mọi thiết bị USB</value>
</data>
<data name="AdvReach_RefusedRoute" xml:space="preserve">
<value>Không đọc: việc đó cần vá mã tại một địa chỉ chỉ tìm được khi game đang chạy, hoặc một lời gọi mà nhà cung cấp cấm thực hiện từ ngoài luồng của game - cả hai đều bị từ chối</value>
<value>Không đọc: việc đó cần vá mã tại một địa chỉ chỉ tìm được khi game đang chạy, hoặc đưa cho game một hàm của FrameLedger thay cho hàm của nhà cung cấp, hoặc một lời gọi mà nhà cung cấp cấm thực hiện từ ngoài luồng của game - tất cả đều bị từ chối</value>
</data>
<data name="AdvReach_Spike" xml:space="preserve">
<value>Đang nghiên cứu; chưa quyết định</value>
@@ -791,13 +791,13 @@
<value>Game Ready</value>
</data>
<data name="AdvToken_active_render" xml:space="preserve">
<value>GPU thực sự vẽ (không tính lúc nghỉ)</value>
<value>GPU thực sự vẽ (số do driver tự tính)</value>
</data>
<data name="AdvToken_frame_time" xml:space="preserve">
<value>nhịp khung của GPU, từ lúc xong khung này tới lúc xong khung kế</value>
</data>
<data name="AdvToken_gpu_render" xml:space="preserve">
<value>GPU vẽ, từ lúc bắt đầu tới lúc xong (gồm cả lúc nghỉ)</value>
<value>GPU vẽ (giữa mốc bắt đầu và mốc kết thúc của driver)</value>
</data>
<data name="AdvToken_gsync_module" xml:space="preserve">
<value>Mô-đun G-SYNC</value>
@@ -193,20 +193,24 @@ public static class AdvancedMetricCatalog
// its two GPU marks includes the card's idle time and was longer than a frame's whole in a real game.
SampledFamily("nvapi.reflex.gpu_times", Nvapi, GameDriver, Microseconds, Latency, "The graphics card's time per frame, as the driver works it out: active render, frame to frame"),
// ---- Inside the game: routes a spike decides ------------------------------------------------------------
Session("sl.dlss.optimal_settings", Streamline, Spike, Text, Upscaling, "The render size and sharpness DLSS recommends"),
Sampled("sl.dlss.vram_estimate", Streamline, Spike, Mebibytes, Upscaling, "DLSS's own estimate of its video memory"),
Session("sl.dlssg.options", Streamline, Spike, Text, FrameGeneration, "DLSS frame generation: mode, frames to generate"),
Session("sl.dlssg.state", Streamline, Spike, Text, FrameGeneration, "DLSS frame generation: status, the most frames it can generate"),
Sampled("sl.dlssg.frames_presented", Streamline, Spike, Count, FrameGeneration, "Frames DLSS frame generation presented, by its own count"),
Sampled("sl.dlssg.vram_estimate", Streamline, Spike, Mebibytes, FrameGeneration, "DLSS frame generation's estimate of its video memory"),
Session("sl.dlssd.options", Streamline, Spike, Text, Upscaling, "Ray reconstruction's options"),
Session("sl.nis.options", Streamline, Spike, Text, Upscaling, "NVIDIA Image Scaling's options"),
Session("sl.deepdvc.options", Streamline, Spike, Text, Upscaling, "RTX Dynamic Vibrance's options"),
// ---- Inside the game: Streamline's feature functions - not read ---------------------------------------
// Advanced metrics is closed (owner decision D154, 2026-11-14). None of these is an export: a game gets each
// function through slGetFeatureFunction and keeps the pointer, so seeing its calls would take handing the game
// a function of ours in place of Streamline's - a write to what the game receives (rule 4) - and would still
// miss every game that fetched its functions before the attach. They stay listed, with the reason.
Session("sl.dlss.optimal_settings", Streamline, RefusedRoute, Text, Upscaling, "The render size and sharpness DLSS recommends"),
Sampled("sl.dlss.vram_estimate", Streamline, RefusedRoute, Mebibytes, Upscaling, "DLSS's own estimate of its video memory"),
Session("sl.dlssg.options", Streamline, RefusedRoute, Text, FrameGeneration, "DLSS frame generation: mode, frames to generate"),
Session("sl.dlssg.state", Streamline, RefusedRoute, Text, FrameGeneration, "DLSS frame generation: status, the most frames it can generate"),
Sampled("sl.dlssg.frames_presented", Streamline, RefusedRoute, Count, FrameGeneration, "Frames DLSS frame generation presented, by its own count"),
Sampled("sl.dlssg.vram_estimate", Streamline, RefusedRoute, Mebibytes, FrameGeneration, "DLSS frame generation's estimate of its video memory"),
Session("sl.dlssd.options", Streamline, RefusedRoute, Text, Upscaling, "Ray reconstruction's options"),
Session("sl.nis.options", Streamline, RefusedRoute, Text, Upscaling, "NVIDIA Image Scaling's options"),
Session("sl.deepdvc.options", Streamline, RefusedRoute, Text, Upscaling, "RTX Dynamic Vibrance's options"),
// A refused route (owner decision D133): the Overlay calling slReflexGetState itself breaks the thread
// contract the vendor's header states.
Session("sl.reflex.state", Streamline, RefusedRoute, Table, Latency, "Reflex through Streamline: availability and its frame reports"),
Sampled("sl.pcl.markers", Streamline, Spike, Count, Latency, "PC-latency markers the game sets"),
Sampled("sl.pcl.markers", Streamline, RefusedRoute, Count, Latency, "PC-latency markers the game sets"),
// ---- Closed by a licence --------------------------------------------------------------------------------
Session("ngx.parameters", Ngx, Licence, Table, Upscaling, "NGX parameters: the quality value, the DLSS hints"),
@@ -25,7 +25,10 @@ public enum AdvancedReach
/// <summary>Needs a hook on a function its module exports; the hook is not built. No entry carries it since 0.1.0-beta.45.</summary>
NewHook = 4,
/// <summary>A route nobody has proven safe: a spike decides, and the owner says go or no.</summary>
/// <summary>
/// A route nobody has proven safe: a spike decides, and the owner says go or no. No entry carries it since the
/// owner closed Advanced metrics (D154, 2026-11-14): the ten that did are <see cref="RefusedRoute"/>.
/// </summary>
Spike = 5,
/// <summary>A source the project decided not to open (D103).</summary>
@@ -70,7 +73,8 @@ public enum AdvancedReach
/// <summary>
/// Reading it needs a route the project refused, whatever the source: a patch at an address learned at run time
/// (what a game asks of Reflex is an argument of a function no module exports), or a call the vendor's own header
/// forbids from a thread that is not the game's (owner decision D133). Never read.
/// forbids from a thread that is not the game's (owner decision D133), or a function of ours handed to the game in
/// place of the vendor's (what a game sets and asks through Streamline's feature functions - D154). Never read.
/// </summary>
RefusedRoute = 15,
}
@@ -0,0 +1,20 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Diagnostics.CodeAnalysis;
using FrameLedger.Application.Telemetry;
namespace FrameLedger.Application.Input;
/// <summary>
/// One session's view of <see cref="IInputDevices"/>: the slices in which a window of the session's own game was in
/// front, added up between two reads. Several sessions can run at once; each has its own.
/// </summary>
public interface IInputActivitySource : IDisposable
{
/// <summary>The processes whose windows count as the session's game. Called from the session's loop.</summary>
void Follow(GameProcess target);
/// <summary>What was seen since the last read; false when the reader took no slice since then. Called from the telemetry thread, and never throws into it.</summary>
bool TryRead([NotNullWhen(true)] out InputReading? reading);
}
@@ -0,0 +1,38 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Input;
/// <summary>
/// The Windows calls the input reader makes, behind one interface (<c>21_INPUT_DEVICES</c> §What is read): raw input
/// for game controllers, XInput, the time of the last keyboard or mouse input, the window in front. Everything here
/// reads; nothing writes to a device, and nothing asks about a keyboard or a mouse beyond that one time
/// (<c>tools/input-readonly-check.ps1</c> holds the calls behind it to a list).
/// </summary>
/// <remarks>Every member is called on the reader's own thread, the one that called <see cref="Open"/>.</remarks>
public interface IInputBackend : IDisposable
{
/// <summary>Makes what the reader needs on the calling thread; returns whether Windows accepted the registration for game controllers' reports.</summary>
bool Open();
/// <summary>Hands over what arrived since the last call: the controllers that came and went, then their reports.</summary>
void Drain(IInputBackendSink sink);
/// <summary>Whether XInput's library is there to ask.</summary>
bool XInputAvailable { get; }
/// <summary>The state of one of XInput's four pads; false when it is not connected.</summary>
bool TryReadPad(int slot, out XInputReading pad);
/// <summary>Whether the pad is wireless, and its battery; false when XInput did not answer.</summary>
bool TryReadPadDetails(int slot, out XInputDetails details);
/// <summary>The time of the last keyboard or mouse input in the user's session, as Windows' tick count; false when Windows did not give it.</summary>
bool TryReadLastInputTick(out uint tick);
/// <summary>The process whose window is in front; 0 when there is none.</summary>
uint ForegroundProcessId();
/// <summary>The processor time the calling thread has used, in milliseconds.</summary>
long ThreadCpuMs();
}
@@ -0,0 +1,17 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Input;
/// <summary>What <see cref="IInputBackend.Drain"/> hands over. A device is named by the handle Windows gave it for as long as it is connected: a key, never stored.</summary>
public interface IInputBackendSink
{
/// <summary>A game controller is there: at the start, or newly connected.</summary>
void Arrived(nint device, RawController controller);
/// <summary>It left.</summary>
void Removed(nint device);
/// <summary>One input report of a controller, its report id first, at the length Windows hands the device's reports over.</summary>
void Report(nint device, ReadOnlySpan<byte> report);
}
@@ -0,0 +1,15 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Input;
/// <summary>
/// The Agent's one reader of game controllers and of keyboard-and-mouse activity (owner decisions of 2026-11-14,
/// <c>21_INPUT_DEVICES</c>). It reads from outside every game - nothing is hooked, nothing in a game is opened - and
/// only while a session holds a view of it: with no session it does not run at all.
/// </summary>
public interface IInputDevices
{
/// <summary>One session's view of the reader. The reader runs from the first view opened to the last disposed.</summary>
IInputActivitySource Open();
}
@@ -0,0 +1,39 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FrameLedger.Domain.Input;
namespace FrameLedger.Application.Input;
/// <summary>
/// One game controller the Agent saw, as far as a session keeps it (<c>21_INPUT_DEVICES</c> §Who a controller is): its
/// maker and model by their USB ids, how it is connected, and whether it is one of XInput's four pads.
/// </summary>
/// <remarks>
/// <b>What is not here is not read:</b> no serial number, no Bluetooth address, no device path. Two pads of one model
/// on one kind of connection cannot be told apart across a reconnect, and are not.
/// </remarks>
public sealed record InputDevice
{
/// <summary>The reader's own number for the device, the same for as long as the reader runs. It names nothing outside the Agent.</summary>
public required int Id { get; init; }
public ControllerFamily Family { get; init; }
/// <summary>The USB vendor id; 0 for one of XInput's pads that nothing could name.</summary>
public int VendorId { get; init; }
/// <summary>The USB product id; 0 with a <see cref="VendorId"/> of 0.</summary>
public int ProductId { get; init; }
public ControllerConnection Connection { get; init; }
/// <summary>Whether the ids are those of a pad a program presents - Steam's virtual gamepad - rather than one a player holds.</summary>
public bool IsVirtual { get; init; }
/// <summary>Which of XInput's four pads this is (0-3); null for a controller Windows does not present through XInput.</summary>
public int? XInputSlot { get; init; }
/// <summary>The model's product name, or null for ids this build does not list.</summary>
public string? Model => ControllerCatalog.ModelOf(VendorId, ProductId);
}
@@ -0,0 +1,17 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.InteropServices;
using FrameLedger.Domain.Input;
namespace FrameLedger.Application.Input;
/// <summary>One controller during one tick.</summary>
/// <param name="DeviceId">The <see cref="InputDevice.Id"/> it is about.</param>
/// <param name="Connected">Whether it was connected at the end of the tick.</param>
/// <param name="ActiveMs">The time it was in use while the game was in front and the session was not paused.</param>
/// <param name="Battery">Its battery at the tick's last reading, when it reported one.</param>
/// <param name="Connects">How many times it connected during the tick. Being there when the session began is not a connection.</param>
/// <param name="Disconnects">How many times it disconnected during the tick.</param>
[StructLayout(LayoutKind.Auto)]
public readonly record struct InputDeviceReading(int DeviceId, bool Connected, int ActiveMs, BatteryReading? Battery, int Connects, int Disconnects);
@@ -0,0 +1,85 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Input;
/// <summary>
/// What each source of the input reader did, as counts (<c>21_INPUT_DEVICES</c> §What the reader says about itself).
/// The reader was built without a controller to try it on (owner decision, 2026-11-14), so a session carries the
/// evidence of what answered on the PC it ran on: whether Windows accepted the registration, how many reports came,
/// whether XInput said anything while the Agent was in the background. Counts only - nothing here names a device.
/// </summary>
public sealed record InputHealth
{
/// <summary>Whether Windows accepted the registration for game controllers' reports.</summary>
public bool RawInputRegistered { get; init; }
/// <summary>Reports of game controllers received.</summary>
public long RawReports { get; init; }
/// <summary>Reports that could not be read: a layout the parser does not know, or one Windows' own parser refused.</summary>
public long RawReportsUnread { get; init; }
/// <summary>Whether XInput's library was there to ask.</summary>
public bool XInputAvailable { get; init; }
/// <summary>States XInput returned for a connected pad.</summary>
public long XInputReads { get; init; }
/// <summary>
/// Slices in which a controller Windows presents through XInput sent reports that are a pad in use while XInput's
/// own state said nothing was. More than a handful means XInput does not answer a program in the background on
/// this PC, and its pads were then read from their reports alone.
/// </summary>
public long XInputSilent { get; init; }
/// <summary>Whether Windows gave the time of the last keyboard or mouse input.</summary>
public bool LastInputAvailable { get; init; }
/// <summary>Slices the reader took.</summary>
public long Slices { get; init; }
/// <summary>Processor time the reader's thread used, in milliseconds.</summary>
public long ThreadCpuMs { get; init; }
/// <summary>Slices that failed with an error and were skipped.</summary>
public int Faults { get; init; }
/// <summary>What happened since <paramref name="start"/>: the counts less the ones it holds; the yes-or-no answers are the later ones.</summary>
public InputHealth Since(InputHealth start)
{
ArgumentNullException.ThrowIfNull(start);
return this with
{
RawReports = RawReports - start.RawReports,
RawReportsUnread = RawReportsUnread - start.RawReportsUnread,
XInputReads = XInputReads - start.XInputReads,
XInputSilent = XInputSilent - start.XInputSilent,
Slices = Slices - start.Slices,
ThreadCpuMs = ThreadCpuMs - start.ThreadCpuMs,
Faults = Faults - start.Faults,
};
}
/// <summary>The sources that answered, as <c>sessions.input_source</c> stores them: <c>rawinput</c>, <c>xinput</c> and <c>lastinput</c>, joined by <c>+</c>; empty when none did.</summary>
public string Sources()
{
var parts = new List<string>(3);
if (RawInputRegistered)
{
parts.Add("rawinput");
}
if (XInputAvailable)
{
parts.Add("xinput");
}
if (LastInputAvailable)
{
parts.Add("lastinput");
}
return string.Join('+', parts);
}
}
@@ -0,0 +1,84 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FrameLedger.Domain.Input;
namespace FrameLedger.Application.Input;
/// <summary>
/// The words a ledger stores for a controller's family, its connection and its battery (<c>06_DATA_MODEL</c>
/// §<c>sessions.input_devices</c>). They are data, not text shown to anyone: the App has its own, translated, and a
/// word here is never renamed once a release has written it.
/// </summary>
public static class InputNames
{
public const string Other = "other";
public const string Unknown = "unknown";
public const string None = "none";
public static string Of(ControllerFamily family) => family switch
{
ControllerFamily.Xbox => "xbox",
ControllerFamily.PlayStation => "playstation",
ControllerFamily.Nintendo => "nintendo",
_ => Other,
};
public static ControllerFamily FamilyOf(string? name) => name switch
{
"xbox" => ControllerFamily.Xbox,
"playstation" => ControllerFamily.PlayStation,
"nintendo" => ControllerFamily.Nintendo,
_ => ControllerFamily.Other,
};
public static string Of(ControllerConnection connection) => connection switch
{
ControllerConnection.Usb => "usb",
ControllerConnection.Bluetooth => "bluetooth",
ControllerConnection.Wireless => "wireless",
_ => Unknown,
};
public static ControllerConnection ConnectionOf(string? name) => name switch
{
"usb" => ControllerConnection.Usb,
"bluetooth" => ControllerConnection.Bluetooth,
"wireless" => ControllerConnection.Wireless,
_ => ControllerConnection.Unknown,
};
public static string Of(BatteryState state) => state switch
{
BatteryState.Discharging => "discharging",
BatteryState.Charging => "charging",
BatteryState.Full => "full",
BatteryState.Wired => "wired",
_ => Unknown,
};
public static BatteryState StateOf(string? name) => name switch
{
"discharging" => BatteryState.Discharging,
"charging" => BatteryState.Charging,
"full" => BatteryState.Full,
"wired" => BatteryState.Wired,
_ => BatteryState.Unknown,
};
public static string Of(BatteryScale scale) => scale switch
{
BatteryScale.FourLevels => "levels",
BatteryScale.Percent => "percent",
_ => None,
};
public static BatteryScale ScaleOf(string? name) => name switch
{
"levels" => BatteryScale.FourLevels,
"percent" => BatteryScale.Percent,
_ => BatteryScale.None,
};
}
@@ -0,0 +1,373 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FrameLedger.Domain.Input;
namespace FrameLedger.Application.Input;
/// <summary>
/// The input reader itself (<c>21_INPUT_DEVICES</c> §The reader): about ten times a second it takes what Windows has
/// to say - the controllers' reports that arrived, XInput's four pads, the time of the last keyboard or mouse input,
/// the window in front - and makes one <see cref="InputSlice"/> of it. It is the same for every session running; whose
/// game a slice counts for is <see cref="InputTickAccumulator"/>'s to decide.
/// </summary>
/// <remarks>
/// <para>
/// <b>What a controller is here.</b> Each of XInput's pads that is connected is one; each controller Windows does not
/// present through XInput is one. A device Windows presents through XInput is ALSO seen by raw input, and is not a
/// second controller: it gives the pads their name, when that cannot be mistaken, and is the witness of the next
/// paragraph.
/// </para>
/// <para>
/// <b>XInput in the background is not documented</b>: Microsoft's page for <c>XInputEnable</c> says that since
/// Windows 10 the system switches a program's controller input by its window's focus, and the Agent has no window in
/// front, ever. So the reader watches for it. A slice in which an XInput-class device's own reports changed while no
/// pad's packet number moved - not in this slice nor the one before - is counted
/// (<see cref="InputHealth.XInputSilent"/>). Once there are <see cref="SilentBeforeFallback"/> of them and XInput has
/// never once been seen to move, XInput is taken to be answering nothing here, and from then on such a slice counts
/// the lowest connected pad as in use: its reports changed, which a pad at rest does not do. That is coarser than
/// XInput's own dead zones - a drifting stick counts - and it is used only where the better source is silent.
/// </para>
/// <para>
/// <b>Which controllers are read for use.</b> XInput's pads, and a DualSense by its own reports
/// (<see cref="DualSenseReport"/>). Any other controller is listed, with its connections and drops, and is never "in
/// use": its report layout is not known to this build, and a guess would be a made-up number.
/// </para>
/// </remarks>
public sealed class InputReader : IInputBackendSink
{
/// <summary>XInput's four pads.</summary>
public const int Slots = 4;
/// <summary>A pad that is not connected is asked about once in this many slices - XInput looks for a device each time it is asked about an empty one - and at once when a controller arrives or leaves.</summary>
public const int ProbeEverySlices = 20;
/// <summary>A connected pad's battery is asked for once in this many slices.</summary>
public const int DetailsEverySlices = 50;
/// <summary>How many silent slices, with XInput never seen to move, before a device's own reports stand in for it.</summary>
public const int SilentBeforeFallback = 10;
/// <summary>The number the first controller that is not one of XInput's gets; the pads are 1 to 4.</summary>
private const int _firstRawId = 16;
private readonly IInputBackend _backend;
private readonly Dictionary<nint, Raw> _raw = [];
private readonly Dictionary<(RawController Controller, int Instance), int> _rawIds = [];
private readonly Pad[] _pads = [new(0), new(1), new(2), new(3)];
private bool _registered;
private bool _lastInputAvailable;
private uint? _lastInputTick;
private bool _probeNow = true;
private bool _renamePads = true;
private bool _movedLastSlice;
private bool _xinputEverMoved;
private long _slices;
private long _rawReports;
private long _rawReportsUnread;
private long _xinputReads;
private long _xinputSilent;
private int _faults;
public InputReader(IInputBackend backend) => _backend = backend ?? throw new ArgumentNullException(nameof(backend));
/// <summary>
/// The only device classes the reader registers raw input for: HID usage page 1 (generic desktop), usages 4
/// (joystick) and 5 (gamepad). Never 2 (mouse) or 6 (keyboard): what is known of those is one time, from
/// <see cref="IInputBackend.TryReadLastInputTick"/> (owner decision D158).
/// </summary>
public static IReadOnlyList<(ushort UsagePage, ushort Usage)> RegisteredUsages { get; } = [(1, 4), (1, 5)];
/// <summary>Opens the backend on the calling thread, which is the one every <see cref="Slice"/> must then be called on.</summary>
public void Open() => _registered = _backend.Open();
/// <summary>A slice that threw is counted and skipped.</summary>
public void Fault() => _faults++;
/// <summary>What Windows has to say since the slice before, <paramref name="elapsedMs"/> ago.</summary>
public InputSlice Slice(int elapsedMs)
{
_slices++;
foreach (Raw raw in _raw.Values)
{
raw.Active = false;
raw.Changed = false;
}
_backend.Drain(this);
bool moved = ReadPads();
WatchForSilence(moved);
if (_renamePads)
{
NamePads();
}
bool keyboardMouse = false;
if (_backend.TryReadLastInputTick(out uint tick))
{
_lastInputAvailable = true;
keyboardMouse = _lastInputTick is { } before && tick != before;
_lastInputTick = tick;
}
var devices = new List<InputSliceDevice>(Slots + _raw.Count);
foreach (Pad pad in _pads)
{
if (pad.Connected)
{
devices.Add(new InputSliceDevice(pad.Device, pad.Active, pad.Details is { } d ? XInputPad.Battery(d.BatteryType, d.BatteryLevel) : null));
}
}
foreach (Raw raw in _raw.Values.Where(static r => !r.Controller.XInputClass).OrderBy(static r => r.Device.Id))
{
devices.Add(new InputSliceDevice(raw.Device, raw.Active, raw.Battery));
}
return new InputSlice
{
ElapsedMs = Math.Max(0, elapsedMs),
ForegroundProcessId = _backend.ForegroundProcessId(),
KeyboardMouseActive = keyboardMouse,
VirtualPad = _raw.Values.Any(static r => r.Controller is { XInputClass: true, IsVirtual: true }),
Devices = devices,
Health = new InputHealth
{
RawInputRegistered = _registered,
RawReports = _rawReports,
RawReportsUnread = _rawReportsUnread,
XInputAvailable = _backend.XInputAvailable,
XInputReads = _xinputReads,
XInputSilent = _xinputSilent,
LastInputAvailable = _lastInputAvailable,
Slices = _slices,
ThreadCpuMs = _backend.ThreadCpuMs(),
Faults = _faults,
},
};
}
void IInputBackendSink.Arrived(nint device, RawController controller)
{
if (_raw.TryGetValue(device, out Raw? known) && known.Controller == controller)
{
// Windows names the controllers that are already there when the registration is made, and the reader has
// asked for the list as well: the same device twice is one device.
return;
}
int id = 0;
if (!controller.XInputClass)
{
int instance = _raw.Values.Count(r => r.Controller == controller);
if (!_rawIds.TryGetValue((controller, instance), out id))
{
id = _firstRawId + _rawIds.Count;
_rawIds[(controller, instance)] = id;
}
}
_raw[device] = new Raw(controller, new InputDevice
{
Id = id,
Family = ControllerCatalog.FamilyOf(controller.VendorId, xinput: false),
VendorId = controller.VendorId,
ProductId = controller.ProductId,
Connection = controller.Connection,
});
DevicesChanged(controller);
}
void IInputBackendSink.Removed(nint device)
{
if (_raw.Remove(device, out Raw? gone))
{
DevicesChanged(gone.Controller);
}
}
void IInputBackendSink.Report(nint device, ReadOnlySpan<byte> report)
{
_rawReports++;
if (!_raw.TryGetValue(device, out Raw? raw))
{
_rawReportsUnread++;
return;
}
if (raw.Controller.XInputClass)
{
// The witness only: did the device say something new. What it said is XInput's to tell.
raw.Changed |= raw.Last is not null && !report.SequenceEqual(raw.Last);
if (raw.Last is null || raw.Last.Length != report.Length)
{
raw.Last = report.ToArray();
}
else
{
report.CopyTo(raw.Last);
}
}
else if (raw.Controller.IsDualSense)
{
if (DualSenseReport.TryRead(report, raw.Controller.Connection == ControllerConnection.Bluetooth, out bool active, out BatteryReading? battery))
{
raw.Active |= active;
raw.Battery = battery ?? raw.Battery;
}
else
{
_rawReportsUnread++;
}
}
}
private void DevicesChanged(RawController controller)
{
if (controller.XInputClass)
{
_probeNow = true;
_renamePads = true;
}
}
/// <summary>Asks XInput about its pads; returns whether any connected pad's packet number moved since the slice before.</summary>
private bool ReadPads()
{
bool moved = false;
bool probe = _probeNow || _slices % ProbeEverySlices == 1;
_probeNow = false;
foreach (Pad pad in _pads)
{
pad.Active = false;
if (!_backend.XInputAvailable || (!pad.Connected && !probe))
{
continue;
}
if (!_backend.TryReadPad(pad.Slot, out XInputReading state))
{
if (pad.Connected)
{
pad.Connected = false;
pad.Details = null;
_renamePads = true;
}
continue;
}
_xinputReads++;
if (!pad.Connected)
{
pad.Connected = true;
pad.Details = null;
_renamePads = true;
}
else if (state.Packet != pad.Packet)
{
moved = true;
}
pad.Packet = state.Packet;
pad.Active = XInputPad.IsActive(state.Buttons, state.LeftTrigger, state.RightTrigger, state.ThumbLx, state.ThumbLy, state.ThumbRx, state.ThumbRy);
if (pad.Details is null || _slices - pad.DetailsAt >= DetailsEverySlices)
{
pad.DetailsAt = _slices;
if (_backend.TryReadPadDetails(pad.Slot, out XInputDetails details))
{
_renamePads |= pad.Details?.Wireless != details.Wireless;
pad.Details = details;
}
}
}
return moved;
}
private void WatchForSilence(bool moved)
{
_xinputEverMoved |= moved;
bool deviceSpoke = _raw.Values.Any(static r => r.Controller.XInputClass && r.Changed);
if (deviceSpoke && !moved && !_movedLastSlice && !_pads.Any(static p => p is { Connected: true, Active: true }))
{
_xinputSilent++;
if (!_xinputEverMoved && _xinputSilent >= SilentBeforeFallback && _pads.FirstOrDefault(static p => p.Connected) is { } lowest)
{
lowest.Active = true;
}
}
_movedLastSlice = moved;
}
/// <summary>
/// What each connected pad is. XInput does not say which device a pad is, so a pad is named only when it cannot be
/// another: every XInput-class device a player could hold has the same two ids, or the only ones there are
/// Steam's. Otherwise it is "one of XInput's pads" - the Xbox family, no ids, no model.
/// </summary>
private void NamePads()
{
_renamePads = false;
RawController[] presented = [.. _raw.Values.Where(static r => r.Controller.XInputClass).Select(static r => r.Controller)];
RawController[] held = [.. presented.Where(static c => !c.IsVirtual)];
RawController? name = held.Length > 0
? held.All(c => c.VendorId == held[0].VendorId && c.ProductId == held[0].ProductId) ? held[0] : null
: presented.Length > 0 ? presented[0] : null;
bool bluetooth = name is not null && held.Length > 0 && held.All(static c => c.Connection == ControllerConnection.Bluetooth);
foreach (Pad pad in _pads)
{
pad.Device = new InputDevice
{
Id = pad.Slot + 1,
XInputSlot = pad.Slot,
Family = ControllerCatalog.FamilyOf(name?.VendorId ?? 0, xinput: true),
VendorId = name?.VendorId ?? 0,
ProductId = name?.ProductId ?? 0,
IsVirtual = name?.IsVirtual ?? false,
Connection = bluetooth
? ControllerConnection.Bluetooth
: pad.Details switch
{
{ Wireless: true } => ControllerConnection.Wireless,
{ } => ControllerConnection.Usb,
_ => ControllerConnection.Unknown,
},
};
}
}
/// <summary>One of XInput's pads.</summary>
private sealed class Pad(int slot)
{
public int Slot { get; } = slot;
public bool Connected { get; set; }
public uint Packet { get; set; }
public bool Active { get; set; }
public XInputDetails? Details { get; set; }
public long DetailsAt { get; set; }
public InputDevice Device { get; set; } = new() { Id = slot + 1, XInputSlot = slot, Family = ControllerFamily.Xbox };
}
/// <summary>A controller raw input named.</summary>
private sealed class Raw(RawController controller, InputDevice device)
{
public RawController Controller { get; } = controller;
public InputDevice Device { get; } = device;
public bool Active { get; set; }
public bool Changed { get; set; }
public BatteryReading? Battery { get; set; }
public byte[]? Last { get; set; }
}
}
@@ -0,0 +1,45 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Input;
/// <summary>
/// What the input reader saw for one session during one tick of the telemetry poller (<c>03_METRICS</c> §Input): how
/// the time the game was in front divides between a controller, the keyboard and mouse, both and neither, and each
/// controller's part in it.
/// </summary>
/// <remarks>
/// It holds times and counts. Which button, where a stick was, which key, what was typed and where the mouse was are
/// not in it because the reader never keeps them (<c>21_INPUT_DEVICES</c> §What is never read).
/// </remarks>
public sealed record InputReading
{
/// <summary>The time the tick covers: every slice, in front or not, paused or not. What a battery level and a connection are timed by.</summary>
public int SpanMs { get; init; }
/// <summary>Of <see cref="SpanMs"/>, the time the session was not paused.</summary>
public int ObservedMs { get; init; }
/// <summary>Of <see cref="ObservedMs"/>, the time a window of the game was in front. The four below add up to it.</summary>
public int ForegroundMs { get; init; }
public int ControllerMs { get; init; }
public int KeyboardMouseMs { get; init; }
public int BothMs { get; init; }
public int IdleMs { get; init; }
/// <summary>Whether a pad a program presents - Steam's virtual gamepad - was among XInput's pads during the tick.</summary>
public bool VirtualPad { get; init; }
/// <summary>The controllers that were connected at some moment of the tick.</summary>
public IReadOnlyList<InputDeviceReading> Devices { get; init; } = [];
/// <summary>What each controller in <see cref="Devices"/> is. A reading stands alone: it names every device it counts.</summary>
public IReadOnlyList<InputDevice> Table { get; init; } = [];
/// <summary>What the reader's sources did since the session began reading.</summary>
public InputHealth Health { get; init; } = new();
}
@@ -0,0 +1,30 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Input;
/// <summary>
/// What the input reader saw of the whole PC in one slice - about a tenth of a second (<c>21_INPUT_DEVICES</c> §The
/// reader). It is the same for every session running: which session a slice counts for is decided by whose window was
/// in front (<see cref="InputTickAccumulator"/>).
/// </summary>
public sealed record InputSlice
{
/// <summary>The time since the slice before.</summary>
public int ElapsedMs { get; init; }
/// <summary>The process whose window was in front; 0 when Windows named none.</summary>
public uint ForegroundProcessId { get; init; }
/// <summary>Whether Windows' time of the last keyboard or mouse input moved during the slice.</summary>
public bool KeyboardMouseActive { get; init; }
/// <summary>Whether a pad a program presents was among XInput's pads.</summary>
public bool VirtualPad { get; init; }
/// <summary>The controllers connected during the slice.</summary>
public IReadOnlyList<InputSliceDevice> Devices { get; init; } = [];
/// <summary>What the reader's sources did since the reader started.</summary>
public InputHealth Health { get; init; } = new();
}
@@ -0,0 +1,14 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.InteropServices;
using FrameLedger.Domain.Input;
namespace FrameLedger.Application.Input;
/// <summary>One connected controller during one slice.</summary>
/// <param name="Device">What it is.</param>
/// <param name="Active">Whether anything on it was in use during the slice.</param>
/// <param name="Battery">Its battery, when it reported one.</param>
[StructLayout(LayoutKind.Auto)]
public readonly record struct InputSliceDevice(InputDevice Device, bool Active, BatteryReading? Battery);
@@ -0,0 +1,205 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FrameLedger.Domain.Input;
namespace FrameLedger.Application.Input;
/// <summary>
/// One session's slices added up into one <see cref="InputReading"/> per tick (<c>03_METRICS</c> §Input). The reader
/// adds a slice about ten times a second on its own thread; the telemetry poller takes the sum once a second on its.
/// </summary>
/// <remarks>
/// <para>
/// <b>Only time the game was in front is classified.</b> A slice in which another program's window was in front counts
/// for nothing but <see cref="InputReading.SpanMs"/>: typing in a browser beside the game is not the game played with
/// the keyboard. A slice of a paused session is not observed either (a pause is a gap, <c>03_METRICS</c>).
/// </para>
/// <para>
/// <b>A controller that is there when the session starts has not connected.</b> Connections and disconnections are
/// counted from the second slice on, by comparing each slice's controllers with those of the slice before - paused or
/// not, in front or not: a pad that drops out while the player is in another window still dropped out.
/// </para>
/// </remarks>
public sealed class InputTickAccumulator
{
private readonly Lock _gate = new();
private readonly Dictionary<int, Entry> _devices = [];
private HashSet<int> _connected = [];
private bool _started;
private InputHealth? _healthAtStart;
private InputHealth _health = new();
private int _spanMs;
private int _observedMs;
private int _foregroundMs;
private int _controllerMs;
private int _keyboardMouseMs;
private int _bothMs;
private int _idleMs;
private bool _virtualPad;
private bool _any;
/// <summary>Adds one slice.</summary>
/// <param name="slice">What the reader saw.</param>
/// <param name="inFront">Whether the process in front is one of the session's.</param>
/// <param name="paused">Whether the session is paused.</param>
public void Add(InputSlice slice, bool inFront, bool paused)
{
ArgumentNullException.ThrowIfNull(slice);
int elapsed = Math.Max(0, slice.ElapsedMs);
lock (_gate)
{
_any = true;
_healthAtStart ??= slice.Health;
_health = slice.Health;
_spanMs += elapsed;
_virtualPad |= slice.VirtualPad;
bool counted = inFront && !paused;
bool controller = Track(slice.Devices, counted ? elapsed : 0);
if (paused)
{
return;
}
_observedMs += elapsed;
if (!inFront)
{
return;
}
_foregroundMs += elapsed;
switch (controller, slice.KeyboardMouseActive)
{
case (true, true):
_bothMs += elapsed;
break;
case (true, false):
_controllerMs += elapsed;
break;
case (false, true):
_keyboardMouseMs += elapsed;
break;
default:
_idleMs += elapsed;
break;
}
}
}
/// <summary>The sum since the last take, or null when no slice was added since then.</summary>
public InputReading? Take()
{
lock (_gate)
{
if (!_any)
{
return null;
}
var devices = new List<InputDeviceReading>(_devices.Count);
var table = new List<InputDevice>(_devices.Count);
foreach ((int id, Entry entry) in _devices.OrderBy(static p => p.Key))
{
devices.Add(new InputDeviceReading(id, _connected.Contains(id), entry.ActiveMs, entry.Battery, entry.Connects, entry.Disconnects));
table.Add(entry.Device);
}
var reading = new InputReading
{
SpanMs = _spanMs,
ObservedMs = _observedMs,
ForegroundMs = _foregroundMs,
ControllerMs = _controllerMs,
KeyboardMouseMs = _keyboardMouseMs,
BothMs = _bothMs,
IdleMs = _idleMs,
VirtualPad = _virtualPad,
Devices = devices,
Table = table,
Health = _health.Since(_healthAtStart ?? _health),
};
// The next tick starts with the controllers still connected and nothing counted for them yet.
foreach (int id in _devices.Keys.Where(id => !_connected.Contains(id)).ToArray())
{
_devices.Remove(id);
}
foreach (Entry entry in _devices.Values)
{
entry.Reset();
}
_spanMs = _observedMs = _foregroundMs = _controllerMs = _keyboardMouseMs = _bothMs = _idleMs = 0;
_virtualPad = false;
_any = false;
return reading;
}
}
/// <summary>Notes each controller of the slice and what changed since the slice before; returns whether any was in use.</summary>
private bool Track(IReadOnlyList<InputSliceDevice> devices, int countedMs)
{
var now = new HashSet<int>(devices.Count);
bool anyActive = false;
foreach (InputSliceDevice device in devices)
{
int id = device.Device.Id;
if (!now.Add(id))
{
continue;
}
if (!_devices.TryGetValue(id, out Entry? entry))
{
entry = new Entry(device.Device);
_devices[id] = entry;
}
entry.Device = device.Device;
entry.Battery = device.Battery ?? entry.Battery;
if (_started && !_connected.Contains(id))
{
entry.Connects++;
}
if (device.Active)
{
anyActive = true;
entry.ActiveMs += countedMs;
}
}
foreach (int gone in _connected)
{
if (!now.Contains(gone) && _devices.TryGetValue(gone, out Entry? entry))
{
entry.Disconnects++;
}
}
_connected = now;
_started = true;
return anyActive;
}
private sealed class Entry(InputDevice device)
{
public InputDevice Device { get; set; } = device;
public int ActiveMs { get; set; }
public BatteryReading? Battery { get; set; }
public int Connects { get; set; }
public int Disconnects { get; set; }
public void Reset()
{
ActiveMs = 0;
Connects = 0;
Disconnects = 0;
}
}
}
@@ -0,0 +1,24 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.InteropServices;
using FrameLedger.Domain.Input;
namespace FrameLedger.Application.Input;
/// <summary>
/// A game controller as Windows' raw input describes it, reduced to what the reader keeps: its two USB ids, whether
/// Windows presents it through XInput, and how it is connected. The name these were read from is not here - it can
/// carry an address - and nothing else of the device is asked for.
/// </summary>
/// <param name="VendorId">The USB vendor id.</param>
/// <param name="ProductId">The USB product id.</param>
/// <param name="XInputClass">Whether Windows presents the device through XInput (<see cref="RawDeviceName.IsXInputClass"/>).</param>
/// <param name="Connection">How it is connected (<see cref="RawDeviceName.ConnectionOf"/>).</param>
[StructLayout(LayoutKind.Auto)]
public readonly record struct RawController(int VendorId, int ProductId, bool XInputClass, ControllerConnection Connection)
{
public bool IsVirtual => ControllerCatalog.IsVirtual(VendorId, ProductId);
public bool IsDualSense => !XInputClass && ControllerCatalog.IsDualSense(VendorId, ProductId);
}
@@ -0,0 +1,13 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.InteropServices;
namespace FrameLedger.Application.Input;
/// <summary>What XInput says of one of its pads beside its state: whether it is wireless, and its battery in XInput's own words.</summary>
/// <param name="Wireless"><c>XINPUT_CAPS_WIRELESS</c>.</param>
/// <param name="BatteryType"><c>XINPUT_BATTERY_INFORMATION.BatteryType</c>; 0 (disconnected) when XInput did not answer.</param>
/// <param name="BatteryLevel"><c>XINPUT_BATTERY_INFORMATION.BatteryLevel</c>.</param>
[StructLayout(LayoutKind.Auto)]
public readonly record struct XInputDetails(bool Wireless, int BatteryType, int BatteryLevel);
@@ -0,0 +1,22 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.InteropServices;
namespace FrameLedger.Application.Input;
/// <summary>
/// One of XInput's pads at one read: <c>XINPUT_STATE</c> as it came. The reader asks one thing of it - is this a pad
/// in use (<c>Domain.Input.XInputPad.IsActive</c>) - and whether its packet number moved; neither it nor anything
/// derived from a single button or axis is kept.
/// </summary>
/// <param name="Packet"><c>dwPacketNumber</c>: it moves whenever anything on the pad changed.</param>
/// <param name="Buttons"><c>wButtons</c>.</param>
/// <param name="LeftTrigger"><c>bLeftTrigger</c>, 0-255.</param>
/// <param name="RightTrigger"><c>bRightTrigger</c>, 0-255.</param>
/// <param name="ThumbLx"><c>sThumbLX</c>.</param>
/// <param name="ThumbLy"><c>sThumbLY</c>.</param>
/// <param name="ThumbRx"><c>sThumbRX</c>.</param>
/// <param name="ThumbRy"><c>sThumbRY</c>.</param>
[StructLayout(LayoutKind.Auto)]
public readonly record struct XInputReading(uint Packet, int Buttons, int LeftTrigger, int RightTrigger, int ThumbLx, int ThumbLy, int ThumbRx, int ThumbRy);
@@ -128,6 +128,19 @@ public sealed record GameRow
/// </summary>
public AntiCheatExceptionState AcException { get; init; } = AntiCheatExceptionState.None;
/// <summary>
/// What the store's own file on the disk says of controller support (schema 0024, D163): <c>full</c>, <c>partial</c>,
/// or <c>none</c> for a game the store knows and lists no support for. Null when no store file describes the game or
/// none was read yet. It is the store's word, one of three pieces of evidence - never a verdict of FrameLedger's.
/// </summary>
public string? ControllerSupport { get; init; }
/// <summary>The file <see cref="ControllerSupport"/> was read from: <c>steam-appinfo</c> (schema 0024).</summary>
public string? ControllerSupportSource { get; init; }
/// <summary>When <see cref="ControllerSupport"/> was read (schema 0024).</summary>
public DateTimeOffset? ControllerSupportAt { get; init; }
public bool InLibrary => RemovedAt is null;
/// <summary>
@@ -88,6 +88,14 @@ public interface ISessionRepository
/// </summary>
ValueTask<IReadOnlyList<SensorBlob>> FindAdvancedSensorsAsync(long sessionId, CancellationToken ct = default);
/// <summary>
/// The session's input series (schema 0024, <c>03_METRICS</c> §Input), still encoded, with <c>t_ms</c> first: what
/// each tick was mostly played with, and each controller's part and battery. For a session that stored none that
/// is <c>t_ms</c> alone, or nothing. They are not among <see cref="FindSensorsAsync"/>'s for the reason the advanced
/// ones are not: NaN marks a tick with nothing to say, and their values are not a sensor's.
/// </summary>
ValueTask<IReadOnlyList<SensorBlob>> FindInputSensorsAsync(long sessionId, CancellationToken ct = default);
/// <summary>
/// The session's row of <c>session_advanced</c> with the machine profile it points to, or null: it was recorded
/// with Advanced metrics off (or before they existed).
@@ -401,4 +401,38 @@ public sealed record SessionRow
/// <summary>Application frames per joule of the card's power — FPS per watt; never over displayed frames (rule 6).</summary>
public double? AppFramesPerJoule { get; init; }
// --- Schema 0024 (beta.50, D155-D163): what the session was played with (03_METRICS §Input), both tiers - read by the
// Agent from outside the game. Null on a row written before it, with the option off, and before the terms that
// describe the reading were accepted.
/// <summary>The time the input reader ran and the session was not paused, in milliseconds.</summary>
public long? InputObservedMs { get; init; }
/// <summary>Of <see cref="InputObservedMs"/>, the time a window of the game was in front: what every share is a share of.</summary>
public long? InputForegroundMs { get; init; }
/// <summary>The time in front a controller was in use and the keyboard and mouse were not.</summary>
public long? InputControllerMs { get; init; }
/// <summary>The time in front the keyboard or mouse was in use and no controller was. One class: only the time of the last input is read (D158).</summary>
public long? InputKeyboardMouseMs { get; init; }
public long? InputBothMs { get; init; }
/// <summary>The time in front with no input at all.</summary>
public long? InputIdleMs { get; init; }
/// <summary>How many times the player went from a controller to the keyboard and mouse or back.</summary>
public int? InputMethodSwitches { get; init; }
/// <summary>The sources that answered: <c>rawinput</c>, <c>xinput</c>, <c>lastinput</c>, joined by <c>+</c>.</summary>
public string? InputSource { get; init; }
/// <summary>The session's controllers, their batteries and makers, and what the reader's sources did, as <c>InputDevicesRecord</c>'s JSON.</summary>
public string? InputDevicesJson { get; init; }
/// <summary>The share of the time in front spent in one class, 0-100; null when nothing was read or the game was never in front.</summary>
public double? InputSharePercent(long? classMs) =>
InputForegroundMs is > 0 and var front && classMs is { } ms ? 100d * ms / front : null;
}
@@ -0,0 +1,25 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FrameLedger.Application.Input;
namespace FrameLedger.Application.Recording;
/// <summary>A controller's battery over the session, in <see cref="InputDeviceRecord"/>.</summary>
public sealed record InputBatteryRecord
{
/// <summary><c>levels</c> (0 empty to 3 full), <c>percent</c>, or <c>none</c> for a wired pad.</summary>
public string Scale { get; init; } = InputNames.None;
/// <summary>Every state it was read in, the longest first.</summary>
public IReadOnlyList<InputBatteryStateRecord> States { get; init; } = [];
/// <summary>The first level read, in <see cref="Scale"/>; null when no reading had a level.</summary>
public int? First { get; init; }
/// <summary>The last level read.</summary>
public int? Last { get; init; }
/// <summary>How fast it ran down, in per cent an hour, when that could be worked out (<c>03_METRICS</c> §Input).</summary>
public double? DrainPercentPerHour { get; init; }
}
@@ -0,0 +1,10 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Recording;
/// <summary>One battery state and the time it was read, in <see cref="InputBatteryRecord"/>.</summary>
/// <param name="State">What the battery was doing, in <c>InputNames</c>' words.</param>
/// <param name="Level">The level, in the battery's scale.</param>
/// <param name="Ms">The time it was read in this state.</param>
public sealed record InputBatteryStateRecord(string State, int Level, long Ms);
@@ -0,0 +1,42 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FrameLedger.Application.Input;
namespace FrameLedger.Application.Recording;
/// <summary>One controller of a session, in <see cref="InputDevicesRecord"/>.</summary>
public sealed record InputDeviceRecord
{
/// <summary>The controller's number in the session, from 1: what its series are named by (<c>input.dev.N.active</c>).</summary>
public int Index { get; init; }
public string Family { get; init; } = InputNames.Other;
public int VendorId { get; init; }
public int ProductId { get; init; }
public string? Model { get; init; }
public string Connection { get; init; } = InputNames.Unknown;
public int? XInputSlot { get; init; }
/// <summary>The pad is one a program presents and no controller a player holds was found behind it.</summary>
public bool Virtual { get; init; }
/// <summary>A second pad moved exactly as this one did and was folded into it: Steam Input, or another remapper, was presenting this controller to games as an Xbox pad.</summary>
public bool Remapped { get; init; }
public long ConnectedMs { get; init; }
/// <summary>The time it was in use while the game was in front.</summary>
public long ActiveMs { get; init; }
public int Connects { get; init; }
public int Disconnects { get; init; }
public InputBatteryRecord? Battery { get; init; }
}
@@ -0,0 +1,56 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Text.Json;
using FrameLedger.Application.Input;
namespace FrameLedger.Application.Recording;
/// <summary>
/// <c>sessions.input_devices</c> (schema 0024, owner decisions of 2026-11-14): the controllers of a session as JSON -
/// what each was, how long it was connected and in use, how often it connected and dropped, its battery - with each
/// maker's share, how often the maker changed, and what the reader's sources did.
/// </summary>
/// <remarks>
/// The words for a family, a connection and a battery state are <see cref="InputNames"/>'s, lower case, and are never
/// renamed: a ledger keeps them. A model is a product name or absent. No serial number, address or path is here, and
/// <c>InputSessionBuilderTests</c> hold that no key of the JSON could carry one.
/// </remarks>
public sealed record InputDevicesRecord
{
/// <summary>The format's version; 1.</summary>
public int V { get; init; } = 1;
public IReadOnlyList<InputDeviceRecord> Devices { get; init; } = [];
/// <summary>Each maker's part of the time controllers were in use, the largest first.</summary>
public IReadOnlyList<InputFamilyRecord> Families { get; init; } = [];
/// <summary>How many times the maker of the controller in use changed.</summary>
public int FamilySwitches { get; init; }
/// <summary>Whether a pad a program presents - Steam's virtual gamepad - was seen.</summary>
public bool VirtualPad { get; init; }
public InputHealth Health { get; init; } = new();
public static string ToJson(InputDevicesRecord record) => JsonSerializer.Serialize(record, RecordingJsonContext.Default.InputDevicesRecord);
/// <summary>The column's text back, or null for a null, empty or unparsable column.</summary>
public static InputDevicesRecord? Parse(string? json)
{
if (string.IsNullOrWhiteSpace(json))
{
return null;
}
try
{
return JsonSerializer.Deserialize(json, RecordingJsonContext.Default.InputDevicesRecord);
}
catch (JsonException)
{
return null;
}
}
}
@@ -0,0 +1,10 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Recording;
/// <summary>One maker's part of the time controllers were in use, in <see cref="InputDevicesRecord"/>.</summary>
/// <param name="Family">The maker, in <c>InputNames</c>' words.</param>
/// <param name="ActiveMs">The time its controllers were in use while the game was in front.</param>
/// <param name="Share">That time over the same time of every maker, 0 to 1.</param>
public sealed record InputFamilyRecord(string Family, long ActiveMs, double Share);
@@ -0,0 +1,316 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Globalization;
using FrameLedger.Application.Input;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.Telemetry;
using FrameLedger.Domain.Input;
namespace FrameLedger.Application.Recording;
/// <summary>
/// What a session stores of its input readings (<c>03_METRICS</c> §Input, owner decisions of 2026-11-14): the totals,
/// the controllers with their batteries and makers, and the series a timeline is drawn from - all from the samples, so
/// a session recovered from its <c>.partial</c> file has them as a finished one does.
/// </summary>
/// <remarks>
/// <para>
/// <b>Nothing in, nothing out.</b> A session none of whose samples carries a reading - the option was off, or the
/// terms that say what is read were not accepted yet - stores no series and no summary, and is byte for byte what it
/// was before this existed.
/// </para>
/// <para>
/// <b>One pad seen twice is one controller.</b> Windows shows a controller that Steam Input stands in front of twice:
/// the one the player holds, and an Xbox pad Steam presents for it. An XInput pad that was in use at the same moments
/// as another controller is folded into it (<see cref="VirtualPad"/>) - into a controller that is not XInput's at any
/// time, into another of XInput's pads only in a session where Steam's virtual gamepad was seen.
/// </para>
/// </remarks>
public static class InputSessionBuilder
{
/// <summary>The most controllers one session stores series for; more are counted in the totals and not listed.</summary>
public const int MaxDevices = 8;
public const string ClassSeries = "input.class";
/// <summary>What every series of this builder starts with: how a reader tells them from the sensors' and the advanced ones.</summary>
public const string SeriesPrefix = "input.";
public static string ActiveSeries(int index) => string.Create(CultureInfo.InvariantCulture, $"input.dev.{index}.active");
public static string BatterySeries(int index) => string.Create(CultureInfo.InvariantCulture, $"input.dev.{index}.battery");
/// <summary>The session's input series as blobs and its summary - nothing when no sample carries a reading.</summary>
/// <param name="sensors">The session's samples, in order.</param>
/// <param name="codec">How a series is encoded.</param>
/// <param name="hz">The rate the samples had, stored with each series as the fallback for a reader with no <c>t_ms</c>.</param>
public static (IReadOnlyList<SensorBlob> Blobs, InputSessionSummary? Summary) Build(IReadOnlyList<TelemetrySample> sensors, ISeriesCodec codec, double hz = 1)
{
ArgumentNullException.ThrowIfNull(sensors);
ArgumentNullException.ThrowIfNull(codec);
if (!sensors.Any(static s => s.Input is not null))
{
return ([], null);
}
List<Track> tracks = Tracks(sensors);
bool virtualPad = sensors.Any(static s => s.Input?.VirtualPad == true);
Fold(tracks, virtualPad);
Track[] kept = [.. tracks.Where(static t => !t.Folded)];
var blobs = new List<SensorBlob> { Blob(ClassSeries, ClassColumn(sensors), codec, hz) };
var devices = new List<InputDeviceRecord>(kept.Length);
for (int d = 0; d < kept.Length; d++)
{
devices.Add(kept[d].ToRecord(d + 1));
if (d < MaxDevices)
{
blobs.Add(Blob(ActiveSeries(d + 1), kept[d].ActiveColumn(sensors), codec, hz));
if (kept[d].Battery.Any(static b => b is { Scale: not BatteryScale.None }))
{
blobs.Add(Blob(BatterySeries(d + 1), kept[d].BatteryColumn(), codec, hz));
}
}
}
InputHealth health = sensors.Last(static s => s.Input is not null).Input!.Health;
var record = new InputDevicesRecord
{
Devices = devices,
Families = Families(kept),
FamilySwitches = InputSwitches.Count(FamilyTicks(kept, sensors.Count)),
VirtualPad = virtualPad,
Health = health,
};
return (blobs, new InputSessionSummary
{
ObservedMs = sensors.Sum(static s => (long)(s.Input?.ObservedMs ?? 0)),
ForegroundMs = sensors.Sum(static s => (long)(s.Input?.ForegroundMs ?? 0)),
ControllerMs = sensors.Sum(static s => (long)(s.Input?.ControllerMs ?? 0)),
KeyboardMouseMs = sensors.Sum(static s => (long)(s.Input?.KeyboardMouseMs ?? 0)),
BothMs = sensors.Sum(static s => (long)(s.Input?.BothMs ?? 0)),
IdleMs = sensors.Sum(static s => (long)(s.Input?.IdleMs ?? 0)),
MethodSwitches = InputSwitches.Count(sensors.Select(static s => s.Input is { } r
? InputSwitches.Exclusive(r.ControllerMs, r.KeyboardMouseMs, r.BothMs)
: null)),
Source = health.Sources(),
DevicesJson = InputDevicesRecord.ToJson(record),
});
}
private static SensorBlob Blob(string series, float[] column, ISeriesCodec codec, double hz) =>
new() { Series = series, Hz = hz, Codec = codec.Tag, Data = codec.EncodeSparseFloat32(column) };
/// <summary>What each tick was mostly played with, as <see cref="InputClass"/>'s number; NaN for a tick with no reading or with the game not in front.</summary>
private static float[] ClassColumn(IReadOnlyList<TelemetrySample> sensors)
{
float[] column = new float[sensors.Count];
for (int i = 0; i < sensors.Count; i++)
{
column[i] = sensors[i].Input is { } r && InputSwitches.Dominant(r.ControllerMs, r.KeyboardMouseMs, r.BothMs, r.IdleMs) is { } dominant
? (int)dominant
: float.NaN;
}
return column;
}
/// <summary>One track per controller the samples name, in the order they first appear.</summary>
private static List<Track> Tracks(IReadOnlyList<TelemetrySample> sensors)
{
var tracks = new List<Track>();
var byId = new Dictionary<int, Track>();
for (int i = 0; i < sensors.Count; i++)
{
if (sensors[i].Input is not { } reading)
{
continue;
}
foreach (InputDevice device in reading.Table)
{
if (!byId.TryGetValue(device.Id, out Track? track))
{
track = new Track(device, sensors.Count);
byId[device.Id] = track;
tracks.Add(track);
}
track.Device = device;
}
foreach (InputDeviceReading d in reading.Devices)
{
if (byId.TryGetValue(d.DeviceId, out Track? track))
{
track.Add(i, d, reading.SpanMs);
}
}
}
return tracks;
}
/// <summary>Folds each of XInput's pads that moved with another controller into that controller.</summary>
private static void Fold(List<Track> tracks, bool virtualPad)
{
foreach (Track pad in tracks.Where(static t => t.Device.XInputSlot is not null))
{
// A controller that is not XInput's first: it is the one the player holds. Then, only with Steam's pad seen,
// an XInput pad of a lower number - which of the two Steam presents cannot be told, and it does not matter.
Track? into = tracks.FirstOrDefault(t => !t.Folded && t.Device.XInputSlot is null && VirtualPad.IsSamePad(pad.ActiveMs, t.ActiveMs));
if (into is null && virtualPad)
{
into = tracks.FirstOrDefault(t => !t.Folded && !ReferenceEquals(t, pad) && t.Device.XInputSlot < pad.Device.XInputSlot
&& VirtualPad.IsSamePad(pad.ActiveMs, t.ActiveMs));
}
if (into is not null)
{
pad.Folded = true;
into.Remapped = true;
}
}
}
private static List<InputFamilyRecord> Families(Track[] kept)
{
long total = kept.Sum(static t => t.TotalActiveMs);
return [.. kept
.GroupBy(static t => t.Device.Family)
.Select(g => (Family: g.Key, Ms: g.Sum(static t => t.TotalActiveMs)))
.Where(static f => f.Ms > 0)
.OrderByDescending(static f => f.Ms)
.ThenBy(static f => f.Family)
.Select(f => new InputFamilyRecord(InputNames.Of(f.Family), f.Ms, Math.Round((double)f.Ms / total, 4)))];
}
/// <summary>The one maker whose controller was in use on each tick, or null where none or more than one was.</summary>
private static IEnumerable<ControllerFamily?> FamilyTicks(Track[] kept, int ticks)
{
for (int i = 0; i < ticks; i++)
{
ControllerFamily? only = null;
bool several = false;
foreach (Track track in kept)
{
if (track.ActiveMs[i] <= 0)
{
continue;
}
several |= only is { } seen && seen != track.Device.Family;
only = track.Device.Family;
}
yield return several ? null : only;
}
}
/// <summary>One controller across the session's ticks.</summary>
private sealed class Track(InputDevice device, int ticks)
{
private readonly bool[] _connected = new bool[ticks];
private readonly BatteryTally _tally = new();
private long _connectedMs;
private int _connects;
private int _disconnects;
public InputDevice Device { get; set; } = device;
public int[] ActiveMs { get; } = new int[ticks];
public BatteryReading?[] Battery { get; } = new BatteryReading?[ticks];
public long TotalActiveMs => ActiveMs.Sum(static ms => (long)ms);
/// <summary>Another controller's, and not listed.</summary>
public bool Folded { get; set; }
/// <summary>A pad that moved with it was folded into it.</summary>
public bool Remapped { get; set; }
public void Add(int tick, InputDeviceReading reading, int spanMs)
{
ActiveMs[tick] = reading.ActiveMs;
_connected[tick] = reading.Connected;
_connects += reading.Connects;
_disconnects += reading.Disconnects;
if (!reading.Connected)
{
return;
}
_connectedMs += spanMs;
if (reading.Battery is { } battery)
{
Battery[tick] = battery;
_tally.Add(battery, spanMs);
}
}
/// <summary>The part of each tick's time in front that the controller was in use, 0 to 1; NaN where it was not connected.</summary>
public float[] ActiveColumn(IReadOnlyList<TelemetrySample> sensors)
{
float[] column = new float[ActiveMs.Length];
for (int i = 0; i < column.Length; i++)
{
int front = sensors[i].Input?.ForegroundMs ?? 0;
column[i] = !_connected[i] ? float.NaN : front <= 0 ? 0f : Math.Clamp((float)ActiveMs[i] / front, 0f, 1f);
}
return column;
}
/// <summary>The battery's level on each tick, in its own scale; NaN where there was none.</summary>
public float[] BatteryColumn()
{
float[] column = new float[Battery.Length];
for (int i = 0; i < column.Length; i++)
{
column[i] = Battery[i] is { Scale: not BatteryScale.None } b ? b.Level : float.NaN;
}
return column;
}
public InputDeviceRecord ToRecord(int index) => new()
{
Index = index,
Family = InputNames.Of(Device.Family),
VendorId = Device.VendorId,
ProductId = Device.ProductId,
Model = Device.Model,
Connection = InputNames.Of(Device.Connection),
XInputSlot = Device.XInputSlot,
Virtual = Device.IsVirtual,
Remapped = Remapped,
ConnectedMs = _connectedMs,
ActiveMs = TotalActiveMs,
Connects = _connects,
Disconnects = _disconnects,
Battery = BatteryRecord(),
};
private InputBatteryRecord? BatteryRecord()
{
if (!_tally.Any)
{
return null;
}
BatterySummary summary = _tally.Summary();
BatteryScale scale = summary.States.Select(static s => s.Scale).FirstOrDefault(static s => s != BatteryScale.None);
return new InputBatteryRecord
{
Scale = InputNames.Of(scale),
States = [.. summary.States.Select(static s => new InputBatteryStateRecord(InputNames.Of(s.State), s.Level, s.Ms))],
First = summary.First is { Scale: not BatteryScale.None } first ? first.Level : null,
Last = summary.Last is { Scale: not BatteryScale.None } last ? last.Level : null,
DrainPercentPerHour = summary.DrainPercentPerHour,
};
}
}
}
@@ -0,0 +1,33 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FrameLedger.Application.Input;
namespace FrameLedger.Application.Recording;
/// <summary>What <see cref="InputSessionBuilder"/> makes of a session's input readings: the totals a session row stores, and the controllers as JSON.</summary>
public sealed record InputSessionSummary
{
/// <summary>The time the reader ran and the session was not paused.</summary>
public long ObservedMs { get; init; }
/// <summary>Of that, the time a window of the game was in front: what every share is a share of.</summary>
public long ForegroundMs { get; init; }
public long ControllerMs { get; init; }
public long KeyboardMouseMs { get; init; }
public long BothMs { get; init; }
public long IdleMs { get; init; }
/// <summary>How many times the player went from a controller to the keyboard and mouse or back.</summary>
public int MethodSwitches { get; init; }
/// <summary>The sources that answered (<see cref="InputHealth.Sources"/>).</summary>
public string Source { get; init; } = string.Empty;
/// <summary><c>sessions.input_devices</c>.</summary>
public string DevicesJson { get; init; } = string.Empty;
}
@@ -14,6 +14,7 @@ namespace FrameLedger.Application.Recording;
[JsonSerializable(typeof(FgMixRecord))]
[JsonSerializable(typeof(DriverProfileRecord))]
[JsonSerializable(typeof(Dictionary<string, SensorSeriesStats>))]
[JsonSerializable(typeof(InputDevicesRecord))]
public sealed partial class RecordingJsonContext : JsonSerializerContext
{
}
@@ -61,6 +61,12 @@ public sealed class SessionFinalizer
// hooked has them all the same. Nothing when the option was off - no series, no row.
double hz = SampleRate(input.Sensors, row.QpcFrequency);
(IReadOnlyList<SensorBlob> advancedBlobs, AdvancedSessionRow? advanced) = AdvancedSessionBuilder.Build(input.Sensors, input.Advanced, _codec, hz);
// What the session was played with (D155-D163), both tiers and for the same reason: the Agent reads it from outside
// the game. From the samples alone, so a session recovered from its .partial file has it. Nothing when no sample
// carries a reading - the option was off, or the terms that describe the reading were not accepted yet.
(IReadOnlyList<SensorBlob> inputBlobs, InputSessionSummary? played) = InputSessionBuilder.Build(input.Sensors, _codec, hz);
row = WithInput(row, played);
if (input.Hooked is null)
{
// A Tier-2 row has no frames and every sensor the machine provided (2026-09-22): the same averages a
@@ -68,7 +74,7 @@ public sealed class SessionFinalizer
return new FinalizedSession
{
Row = SessionAggregator.WithSensorAggregates(row with { Tier = CaptureTier.NotHooked }, input.Sensors),
Sensors = [.. EncodeSensors(input.Sensors, row.QpcEpoch, row.QpcFrequency, hz), .. advancedBlobs],
Sensors = [.. EncodeSensors(input.Sensors, row.QpcEpoch, row.QpcFrequency, hz), .. advancedBlobs, .. inputBlobs],
Advanced = advanced,
};
}
@@ -83,11 +89,27 @@ public sealed class SessionFinalizer
{
FirstPresentMs = FirstPresentMs(r.Dominant, row.QpcEpoch, row.QpcFrequency),
},
Sensors = [.. EncodeSensors(input.Sensors, row.QpcEpoch, row.QpcFrequency, hz), .. advancedBlobs],
Sensors = [.. EncodeSensors(input.Sensors, row.QpcEpoch, row.QpcFrequency, hz), .. advancedBlobs, .. inputBlobs],
Advanced = advanced,
};
}
/// <summary>The row with what the session was played with (schema 0024); unchanged when nothing was read.</summary>
private static SessionRow WithInput(SessionRow row, InputSessionSummary? played) => played is null
? row
: row with
{
InputObservedMs = played.ObservedMs,
InputForegroundMs = played.ForegroundMs,
InputControllerMs = played.ControllerMs,
InputKeyboardMouseMs = played.KeyboardMouseMs,
InputBothMs = played.BothMs,
InputIdleMs = played.IdleMs,
InputMethodSwitches = played.MethodSwitches,
InputSource = played.Source,
InputDevicesJson = played.DevicesJson,
};
/// <summary>
/// The rate the session's samples had, a second (owner decision D146): the gaps between the first and the last
/// over the time between them, to a thousandth. 1 where there are fewer than two samples or no time between them.
@@ -3,6 +3,7 @@
using System.Runtime.InteropServices;
using FrameLedger.Application.Advanced;
using FrameLedger.Application.Input;
namespace FrameLedger.Application.Telemetry;
@@ -32,5 +33,11 @@ namespace FrameLedger.Application.Telemetry;
/// was new at this poll, or null — the option is off, or that reader published nothing since the last poll. Null on
/// every sample recorded before it existed. Never a repeat of an earlier tick's readings: a reading is of one tick.
/// </param>
/// <param name="Input">
/// What the input reader saw for this session since the sample before (owner decisions of 2026-11-14,
/// <c>21_INPUT_DEVICES</c>): how the time the game was in front divides between a controller, the keyboard and mouse,
/// both and neither, and each controller's part. Null when the option is off, when the terms that say what is read
/// were not accepted yet, and on every sample recorded before it existed.
/// </param>
[StructLayout(LayoutKind.Auto)]
public readonly record struct TelemetrySample(long QpcTicks, GpuSample Sample, SystemReading System = default, ProcessReading Game = default, IReadOnlyList<AdvancedReading>? Advanced = null);
public readonly record struct TelemetrySample(long QpcTicks, GpuSample Sample, SystemReading System = default, ProcessReading Game = default, IReadOnlyList<AdvancedReading>? Advanced = null, InputReading? Input = null);
@@ -0,0 +1,28 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.InteropServices;
namespace FrameLedger.Domain.Input;
/// <summary>A controller's battery at one reading: what it was doing and how full it was, in the source's own steps.</summary>
/// <param name="State">What the battery was doing.</param>
/// <param name="Scale">What <paramref name="Level"/> counts in.</param>
/// <param name="Level">The level in <paramref name="Scale"/>; 0 when the scale is <see cref="BatteryScale.None"/>.</param>
[StructLayout(LayoutKind.Auto)]
public readonly record struct BatteryReading(BatteryState State, BatteryScale Scale, int Level)
{
/// <summary>A wired controller: no battery.</summary>
public static BatteryReading Wired { get; } = new(BatteryState.Wired, BatteryScale.None, 0);
/// <summary>
/// Whether a player would call the level low while the controller runs on its battery: XInput's "empty" or "low",
/// or 10 % and under. Never while it charges, and never for a reading with no level.
/// </summary>
public bool IsLow => State is BatteryState.Discharging or BatteryState.Unknown && Scale switch
{
BatteryScale.FourLevels => Level <= 1,
BatteryScale.Percent => Level <= 10,
_ => false,
};
}
@@ -0,0 +1,17 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>What a <see cref="BatteryReading.Level"/> counts in: each source keeps its own steps, none is converted into another's.</summary>
public enum BatteryScale
{
/// <summary>No level: a wired controller, or one that reported a state only.</summary>
None = 0,
/// <summary>XInput's four words: 0 empty, 1 low, 2 medium, 3 full.</summary>
FourLevels,
/// <summary>Per cent, 0 to 100 - a DualSense reports it in steps of ten.</summary>
Percent,
}
@@ -0,0 +1,23 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>What a controller's battery was doing at one reading.</summary>
public enum BatteryState
{
/// <summary>The controller reported a battery and not what it was doing, or reported a fault.</summary>
Unknown = 0,
/// <summary>Running on its battery.</summary>
Discharging,
/// <summary>Charging.</summary>
Charging,
/// <summary>Charged and on power.</summary>
Full,
/// <summary>A wired controller with no battery to report (XInput's word).</summary>
Wired,
}
@@ -0,0 +1,11 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>One battery state a controller held during a session, and for how long.</summary>
/// <param name="State">What the battery was doing.</param>
/// <param name="Scale">What <paramref name="Level"/> counts in.</param>
/// <param name="Level">The level, in <paramref name="Scale"/>.</param>
/// <param name="Ms">The time it was read in this state, in milliseconds.</param>
public sealed record BatteryStateTime(BatteryState State, BatteryScale Scale, int Level, long Ms);
@@ -0,0 +1,27 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>What <see cref="BatteryTally"/> adds up to for one controller.</summary>
public sealed record BatterySummary
{
/// <summary>Every state the battery was read in, the longest first.</summary>
public IReadOnlyList<BatteryStateTime> States { get; init; } = [];
/// <summary>The state that lasted longest - the first of <see cref="States"/> - or null when nothing was read.</summary>
public BatteryStateTime? Longest => States.Count > 0 ? States[0] : null;
/// <summary>The first reading of the session.</summary>
public BatteryReading? First { get; init; }
/// <summary>The last reading of the session.</summary>
public BatteryReading? Last { get; init; }
/// <summary>
/// How fast the battery ran down, in per cent an hour: the fall between the first and the last reading on battery
/// over the time read on battery. Null unless the level is in per cent, it fell, it was not put on power in
/// between, and at least <see cref="BatteryTally.MinimumDrainTime"/> was read on battery.
/// </summary>
public double? DrainPercentPerHour { get; init; }
}
@@ -0,0 +1,76 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>
/// One controller's battery readings over a session, accumulated by the time each stood for (<c>03_METRICS</c> §Input):
/// how long it spent at each level, which lasted longest, where it started and ended, and how fast it ran down.
/// </summary>
public sealed class BatteryTally
{
/// <summary>The least time on battery a rate is worked out over: a level moves in steps of ten, and less says nothing.</summary>
public static readonly TimeSpan MinimumDrainTime = TimeSpan.FromMinutes(10);
private readonly Dictionary<BatteryReading, long> _ms = [];
private BatteryReading? _first;
private BatteryReading? _last;
private int? _drainFrom;
private int _drainTo;
private long _drainMs;
private bool _drainBroken;
/// <summary>Whether any reading was added.</summary>
public bool Any => _first is not null;
/// <summary>Adds one reading that stood for <paramref name="elapsedMs"/> milliseconds (negative is treated as 0).</summary>
public void Add(BatteryReading reading, long elapsedMs)
{
long ms = Math.Max(0, elapsedMs);
_ms[reading] = _ms.GetValueOrDefault(reading) + ms;
_first ??= reading;
_last = reading;
if (reading.Scale != BatteryScale.Percent)
{
return;
}
if (reading.State == BatteryState.Discharging)
{
_drainFrom ??= reading.Level;
_drainTo = reading.Level;
_drainMs += ms;
}
else if (_drainFrom is not null && reading.State is BatteryState.Charging or BatteryState.Full)
{
// It was put on power after it had begun to run down: the fall between first and last is not one run.
_drainBroken = true;
}
}
public BatterySummary Summary()
{
BatteryStateTime[] states = [.. _ms
.Select(static p => new BatteryStateTime(p.Key.State, p.Key.Scale, p.Key.Level, p.Value))
.OrderByDescending(static s => s.Ms)
.ThenBy(static s => s.State)
.ThenByDescending(static s => s.Level)];
return new BatterySummary
{
States = states,
First = _first,
Last = _last,
DrainPercentPerHour = Drain(),
};
}
private double? Drain()
{
if (_drainBroken || _drainFrom is not { } from || from <= _drainTo || _drainMs < MinimumDrainTime.TotalMilliseconds)
{
return null;
}
return Math.Round((from - _drainTo) / (_drainMs / 3_600_000d), 1);
}
}
@@ -0,0 +1,72 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>
/// What a controller's USB vendor and product ids say about it (<c>21_INPUT_DEVICES</c> §Who a controller is): its
/// family, a model name for the ones this build knows, and whether it is a pad a program presents rather than one a
/// player holds. The ids are the only thing read of a device's identity - never a serial number, never an address.
/// </summary>
/// <remarks>
/// The model names are product names, the same in every language. A product id that is not listed has no name, and the
/// App then shows the family and the two ids: a wrong name would be worse than none.
/// </remarks>
public static class ControllerCatalog
{
public const int Microsoft = 0x045E;
public const int Sony = 0x054C;
public const int Nintendo = 0x057E;
public const int Valve = 0x28DE;
/// <summary>The Xbox 360 pad the Steam client presents when Steam Input stands between a controller and a game.</summary>
public const int SteamVirtualGamepad = 0x11FF;
public const int DualSense = 0x0CE6;
public const int DualSenseEdge = 0x0DF2;
private static readonly Dictionary<(int Vendor, int Product), string> _models = new()
{
[(Microsoft, 0x028E)] = "Xbox 360 Controller",
[(Microsoft, 0x028F)] = "Xbox 360 Wireless Controller",
[(Microsoft, 0x02D1)] = "Xbox One Controller",
[(Microsoft, 0x02DD)] = "Xbox One Controller",
[(Microsoft, 0x02E3)] = "Xbox Elite Wireless Controller",
[(Microsoft, 0x02EA)] = "Xbox One S Controller",
[(Microsoft, 0x02FD)] = "Xbox One S Controller",
[(Microsoft, 0x0B00)] = "Xbox Elite Wireless Controller Series 2",
[(Microsoft, 0x0B05)] = "Xbox Elite Wireless Controller Series 2",
[(Microsoft, 0x0B22)] = "Xbox Elite Wireless Controller Series 2",
[(Microsoft, 0x0B12)] = "Xbox Wireless Controller",
[(Microsoft, 0x0B13)] = "Xbox Wireless Controller",
[(Microsoft, 0x0B20)] = "Xbox Wireless Controller",
[(Sony, 0x05C4)] = "DualShock 4",
[(Sony, 0x09CC)] = "DualShock 4",
[(Sony, DualSense)] = "DualSense",
[(Sony, DualSenseEdge)] = "DualSense Edge",
[(Nintendo, 0x2009)] = "Switch Pro Controller",
[(Valve, SteamVirtualGamepad)] = "Steam Virtual Gamepad",
};
/// <summary>The family of a device with this vendor id; a device Windows presents through XInput is <see cref="ControllerFamily.Xbox"/> whoever made it.</summary>
public static ControllerFamily FamilyOf(int vendorId, bool xinput) => vendorId switch
{
Microsoft => ControllerFamily.Xbox,
Sony => ControllerFamily.PlayStation,
Nintendo => ControllerFamily.Nintendo,
_ => xinput ? ControllerFamily.Xbox : ControllerFamily.Other,
};
/// <summary>The model's product name, or null for ids this build does not list.</summary>
public static string? ModelOf(int vendorId, int productId) => _models.GetValueOrDefault((vendorId, productId));
/// <summary>Whether the ids are those of a pad a program presents - Steam's - rather than one a player holds.</summary>
public static bool IsVirtual(int vendorId, int productId) => vendorId == Valve && productId == SteamVirtualGamepad;
/// <summary>Whether the ids are a DualSense's or a DualSense Edge's, whose reports <see cref="DualSenseReport"/> reads.</summary>
public static bool IsDualSense(int vendorId, int productId) => vendorId == Sony && productId is DualSense or DualSenseEdge;
}
@@ -0,0 +1,20 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>How a controller reached the PC, as far as Windows says.</summary>
public enum ControllerConnection
{
/// <summary>Nothing said how.</summary>
Unknown = 0,
/// <summary>A cable.</summary>
Usb,
/// <summary>Bluetooth, classic or low energy.</summary>
Bluetooth,
/// <summary>A wireless link that is not known to be Bluetooth - XInput's own word, with no more detail.</summary>
Wireless,
}
@@ -0,0 +1,24 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>
/// Whose controller a device is, from its USB vendor id (<c>03_METRICS</c> §Input). <see cref="Xbox"/> is also what
/// Windows presents through XInput with no vendor id: a pad of another maker that says it is an Xbox pad is one here,
/// because that is all Windows tells.
/// </summary>
public enum ControllerFamily
{
/// <summary>A game controller of a maker this build has no name for.</summary>
Other = 0,
/// <summary>Microsoft's, and every pad Windows presents through XInput with no vendor id.</summary>
Xbox,
/// <summary>Sony's: DualSense, DualSense Edge, DualShock 4.</summary>
PlayStation,
/// <summary>Nintendo's.</summary>
Nintendo,
}
@@ -0,0 +1,133 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>
/// What one input report of a DualSense says that a session keeps (<c>21_INPUT_DEVICES</c> §DualSense): whether
/// anything on the pad was in use, and its battery when the report carries one. The buttons and sticks are looked at to
/// answer the first and are not returned - nothing here can say which was pressed.
/// </summary>
/// <remarks>
/// <para>
/// <b>Three reports.</b> Over USB the pad sends report <c>0x01</c>, 64 bytes. Over Bluetooth it sends a short report
/// <c>0x01</c> of 10 bytes - sticks, buttons and triggers, no battery - until some program asks it for a feature report
/// or sends it an output report; from then until it reconnects it sends report <c>0x31</c>, 78 bytes, whose body is the
/// USB one moved by one byte. FrameLedger never asks: a game that reads the short report would lose its input (owner
/// decision, 2026-11-14). So over Bluetooth the battery is there only when Steam or the game switched the pad.
/// </para>
/// <para>
/// The layout is the one the pad's makers' drivers and the open descriptions of the protocol agree on; it was written
/// from those descriptions, and <b>no report from a real pad had passed through it when it was written</b>.
/// </para>
/// </remarks>
public static class DualSenseReport
{
public const int UsbLength = 64;
public const int BluetoothShortLength = 10;
public const int BluetoothLength = 78;
/// <summary>How far a stick must be from its centre (128) to count: a quarter of its travel, as XInput's own dead zone is.</summary>
public const int StickDeadzone = 32;
/// <summary>How far a trigger must be pulled (0-255) to count: XInput's threshold.</summary>
public const int TriggerThreshold = 30;
private const int _usbReportId = 0x01;
private const int _bluetoothReportId = 0x31;
private const int _hatNeutral = 8;
// Offsets in the full report's body, which starts after the report id over USB and one byte later over Bluetooth.
private const int _fullTriggers = 4;
private const int _fullButtons = 7;
private const int _fullStatus = 52;
private const int _fullBodyLength = 53;
/// <summary>Reads one report; false for anything that is not one of the three, which is then not counted as a report of this pad.</summary>
/// <param name="report">The report as Windows hands it over, its id first.</param>
/// <param name="bluetooth">
/// Whether the pad is on Bluetooth. The length cannot say: Windows hands every report of a device over at the length
/// of its longest, so the short Bluetooth report arrives padded to 78 bytes with the same id as the USB one.
/// </param>
/// <param name="active">Whether anything on the pad was in use.</param>
/// <param name="battery">The battery, when the report carries it.</param>
public static bool TryRead(ReadOnlySpan<byte> report, bool bluetooth, out bool active, out BatteryReading? battery)
{
active = false;
battery = null;
if (report.IsEmpty)
{
return false;
}
if (!bluetooth)
{
if (report.Length < 1 + _fullBodyLength || report[0] != _usbReportId)
{
return false;
}
ReadFull(report[1..], out active, out battery);
return true;
}
if (report[0] == _bluetoothReportId && report.Length >= 2 + _fullBodyLength)
{
ReadFull(report[2..], out active, out battery);
return true;
}
if (report[0] == _usbReportId && report.Length >= BluetoothShortLength)
{
// x, y, rx, ry, three bytes of buttons (the third's upper six bits are a counter), the two triggers.
active = SticksMoved(report[1..5]) || ButtonsDown(report[5], report[6], report[7] & 0x03) || TriggersPulled(report[8], report[9]);
return true;
}
return false;
}
private static void ReadFull(ReadOnlySpan<byte> body, out bool active, out BatteryReading? battery)
{
// x, y, rx, ry, the two triggers, a counter, then the buttons: hat and face, shoulders and sticks, the rest.
active = SticksMoved(body[..4])
|| TriggersPulled(body[_fullTriggers], body[_fullTriggers + 1])
|| ButtonsDown(body[_fullButtons], body[_fullButtons + 1], body[_fullButtons + 2]);
battery = BatteryOf(body[_fullStatus]);
}
private static bool SticksMoved(ReadOnlySpan<byte> axes)
{
foreach (byte axis in axes)
{
if (Math.Abs(axis - 128) > StickDeadzone)
{
return true;
}
}
return false;
}
private static bool TriggersPulled(byte left, byte right) => left > TriggerThreshold || right > TriggerThreshold;
private static bool ButtonsDown(byte hatAndFace, byte shoulders, int rest) =>
(hatAndFace & 0x0F) < _hatNeutral || (hatAndFace & 0xF0) != 0 || shoulders != 0 || rest != 0;
/// <summary>The status byte: the low four bits are the level in tenths (10 is 100 %), the high four what the battery is doing.</summary>
private static BatteryReading BatteryOf(byte status)
{
int level = Math.Min(status & 0x0F, 10) * 10;
return (status >> 4) switch
{
0x0 => new BatteryReading(BatteryState.Discharging, BatteryScale.Percent, level),
0x1 => new BatteryReading(BatteryState.Charging, BatteryScale.Percent, level),
0x2 => new BatteryReading(BatteryState.Full, BatteryScale.Percent, 100),
// 0xA and 0xB are "not charging" for voltage or temperature, 0xF a charging fault: a level and no state.
_ => new BatteryReading(BatteryState.Unknown, BatteryScale.Percent, level),
};
}
}
@@ -0,0 +1,24 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>
/// What a stretch of a session was played with (<c>03_METRICS</c> §Input): decided for each slice of time the game was
/// in front, from outside the game. It says a device was in use while the game was in front, never what the game did
/// with it.
/// </summary>
public enum InputClass
{
/// <summary>Neither a controller nor the keyboard or mouse was in use.</summary>
None = 0,
/// <summary>A controller was in use and the keyboard and mouse were not.</summary>
Controller,
/// <summary>The keyboard or the mouse was in use and no controller was. The two are one class: only the time of the last input is read.</summary>
KeyboardMouse,
/// <summary>A controller and the keyboard or mouse were both in use.</summary>
Both,
}
@@ -0,0 +1,79 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>
/// How many times a session went from one thing to another (<c>03_METRICS</c> §Input): from a controller to the
/// keyboard and mouse and back, or from one maker's controller to another's.
/// </summary>
public static class InputSwitches
{
/// <summary>
/// The number of changes in a sequence of ticks, where each tick is either one value or nothing. A tick with
/// nothing - no input, or two things at once - is skipped and does not end what came before it: a player who puts
/// the controller down, waits, and picks it up again has not switched.
/// </summary>
public static int Count<T>(IEnumerable<T?> ticks)
where T : struct
{
ArgumentNullException.ThrowIfNull(ticks);
int switches = 0;
T? previous = null;
foreach (T? tick in ticks)
{
if (tick is not { } now)
{
continue;
}
if (previous is { } before && !EqualityComparer<T>.Default.Equals(before, now))
{
switches++;
}
previous = now;
}
return switches;
}
/// <summary>The one class a tick was played with, or null when it was played with both or with neither.</summary>
public static InputClass? Exclusive(long controllerMs, long keyboardMouseMs, long bothMs)
{
if (bothMs > 0 || (controllerMs > 0 && keyboardMouseMs > 0))
{
return null;
}
if (controllerMs > 0)
{
return InputClass.Controller;
}
return keyboardMouseMs > 0 ? InputClass.KeyboardMouse : null;
}
/// <summary>The class a tick was mostly played with - what its point on the timeline shows - or null when the game was not in front at all.</summary>
public static InputClass? Dominant(long controllerMs, long keyboardMouseMs, long bothMs, long idleMs)
{
if (controllerMs + keyboardMouseMs + bothMs + idleMs <= 0)
{
return null;
}
InputClass best = InputClass.None;
long most = idleMs;
if (keyboardMouseMs > most)
{
(best, most) = (InputClass.KeyboardMouse, keyboardMouseMs);
}
if (controllerMs > most)
{
(best, most) = (InputClass.Controller, controllerMs);
}
return bothMs > most ? InputClass.Both : best;
}
}
@@ -0,0 +1,49 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>
/// The two things FrameLedger takes from the name Windows gives a controller's device interface, after which the name
/// is dropped (<c>21_INPUT_DEVICES</c> §What is never read): whether Windows presents the device through XInput, and
/// how it is connected.
/// </summary>
/// <remarks>
/// <para>
/// The name is a path such as <c>\\?\HID#VID_045E&amp;PID_0B12&amp;IG_00#…</c>. On Bluetooth it carries the service's
/// identifier - and, further along, an instance id that on some stacks is derived from the device's address. That is
/// why the name is never kept, logged or stored: this type returns two facts and holds no string.
/// </para>
/// <para>
/// <b><c>IG_</c></b> is Microsoft's documented mark of a device XInput presents ("XInput and DirectInput": a device id
/// that contains <c>IG_</c> is an XInput device). <b>The connection</b> is Bluetooth when the name carries the
/// identifier of the Bluetooth HID service, classic (<c>00001124-…</c>) or low energy (<c>00001812-…</c>), and USB
/// when it carries a USB vendor id written <c>VID_</c>; anything else is not known.
/// </para>
/// </remarks>
public static class RawDeviceName
{
private const string _xinputMark = "IG_";
private const string _bluetoothClassicService = "{00001124-0000-1000-8000-00805f9b34fb}";
private const string _bluetoothLowEnergyService = "{00001812-0000-1000-8000-00805f9b34fb}";
private const string _usbVendor = "VID_";
/// <summary>Whether Windows presents the device through XInput.</summary>
public static bool IsXInputClass(string? name) => name is not null && name.Contains(_xinputMark, StringComparison.OrdinalIgnoreCase);
/// <summary>How the device is connected, as far as its name says.</summary>
public static ControllerConnection ConnectionOf(string? name)
{
if (string.IsNullOrEmpty(name))
{
return ControllerConnection.Unknown;
}
if (name.Contains(_bluetoothClassicService, StringComparison.OrdinalIgnoreCase) || name.Contains(_bluetoothLowEnergyService, StringComparison.OrdinalIgnoreCase))
{
return ControllerConnection.Bluetooth;
}
return name.Contains(_usbVendor, StringComparison.OrdinalIgnoreCase) ? ControllerConnection.Usb : ControllerConnection.Unknown;
}
}
@@ -0,0 +1,67 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>
/// Whether two entries of a session's controller list are one pad seen twice (<c>03_METRICS</c> §Input). With Steam
/// Input between a controller and a game, Windows shows the controller the player holds and an Xbox pad Steam presents
/// for it; both move together. Counted as two, a session would have twice the controllers and a share for a maker
/// nobody held.
/// </summary>
public static class VirtualPad
{
/// <summary>How much of the busier entry's time the other must share for the two to be one pad.</summary>
public const double MergeAt = 0.9;
/// <summary>The least time in use the two must have: a few seconds moving together prove nothing.</summary>
public const long MinimumActiveMs = 10_000;
/// <summary>
/// How much two controllers were in use at the same moments: the time both were in use over the time the busier of
/// the two was, 0 to 1. Each array holds a controller's milliseconds in use for every tick of the session, tick for
/// tick.
/// </summary>
public static double Coincidence(ReadOnlySpan<int> a, ReadOnlySpan<int> b)
{
long together = 0;
long sumA = 0;
long sumB = 0;
int n = Math.Min(a.Length, b.Length);
for (int i = 0; i < n; i++)
{
together += Math.Min(a[i], b[i]);
}
foreach (int ms in a)
{
sumA += ms;
}
foreach (int ms in b)
{
sumB += ms;
}
long busier = Math.Max(sumA, sumB);
return busier <= 0 ? 0 : (double)together / busier;
}
/// <summary>Whether the two are one pad: they were in use for long enough, and at the same moments.</summary>
public static bool IsSamePad(ReadOnlySpan<int> a, ReadOnlySpan<int> b)
{
long sumA = 0;
long sumB = 0;
foreach (int ms in a)
{
sumA += ms;
}
foreach (int ms in b)
{
sumB += ms;
}
return Math.Min(sumA, sumB) >= MinimumActiveMs && Coincidence(a, b) >= MergeAt;
}
}
+50
View File
@@ -0,0 +1,50 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Input;
/// <summary>
/// What XInput's answers about one of its four pads mean to a session (<c>21_INPUT_DEVICES</c> §XInput): whether the
/// state it returned is a pad in use, and what its battery words are. The thresholds are the ones XInput's own header
/// recommends, so "in use" here is what a game written to that header would call input.
/// </summary>
public static class XInputPad
{
/// <summary><c>XINPUT_GAMEPAD_LEFT_THUMB_DEADZONE</c>.</summary>
public const int LeftThumbDeadzone = 7849;
/// <summary><c>XINPUT_GAMEPAD_RIGHT_THUMB_DEADZONE</c>.</summary>
public const int RightThumbDeadzone = 8689;
/// <summary><c>XINPUT_GAMEPAD_TRIGGER_THRESHOLD</c>.</summary>
public const int TriggerThreshold = 30;
private const int _typeWired = 0x01;
private const int _typeAlkaline = 0x02;
private const int _typeNimh = 0x03;
private const int _levelFull = 0x03;
/// <summary>Whether a state is a pad in use: a button down, a trigger past the threshold, or a stick outside its dead zone. A stick held counts; one that drifts inside the dead zone does not.</summary>
public static bool IsActive(int buttons, int leftTrigger, int rightTrigger, int thumbLx, int thumbLy, int thumbRx, int thumbRy) =>
buttons != 0
|| leftTrigger > TriggerThreshold
|| rightTrigger > TriggerThreshold
|| Outside(thumbLx, thumbLy, LeftThumbDeadzone)
|| Outside(thumbRx, thumbRy, RightThumbDeadzone);
/// <summary>
/// <c>XINPUT_BATTERY_INFORMATION</c> as a reading: null for "disconnected" and for a type this build does not know,
/// <see cref="BatteryReading.Wired"/> for a wired pad, and the four levels for a battery. XInput does not say whether
/// a battery charges, so one that is not wired is read as discharging.
/// </summary>
public static BatteryReading? Battery(int type, int level) => type switch
{
_typeWired => BatteryReading.Wired,
_typeAlkaline or _typeNimh => new BatteryReading(BatteryState.Discharging, BatteryScale.FourLevels, Math.Clamp(level, 0, _levelFull)),
// 0 is XInput's "disconnected" and 0xFF its "unknown": neither is a battery to show.
_ => null,
};
private static bool Outside(int x, int y, int deadzone) => ((long)x * x) + ((long)y * y) > (long)deadzone * deadzone;
}
@@ -0,0 +1,253 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;
using System.Globalization;
using FrameLedger.Application.Input;
using FrameLedger.Application.Telemetry;
namespace FrameLedger.Infrastructure.Input;
/// <summary>
/// The Agent's one input reader, on a thread of its own, running only while a session has a view of it (owner
/// decisions D155-D163, <c>21_INPUT_DEVICES</c> §The reader). With no session it has no thread, no window and no
/// registration: FrameLedger reads nothing about a controller, the keyboard or the mouse.
/// </summary>
/// <remarks>
/// <para>
/// <b>One reader, several sessions.</b> Sessions run side by side (the watcher keeps a table of them), and a
/// controller's reports arrive once. So the thread makes one <see cref="InputSlice"/> about ten times a second and
/// hands it to every view; each view counts it for its own session when a window of that session's game was in front
/// (<see cref="InputTickAccumulator"/>).
/// </para>
/// <para>
/// <b>A pause is a gap here too.</b> While recording is paused (FR-3.9) a slice is not observed by any session.
/// </para>
/// <para>
/// <b>A slice that throws is counted and skipped</b>; <see cref="MaxFaults"/> in a row end the run with one line in
/// the Agent's log, and the sessions go on without readings. Nothing the reader does may end a session.
/// </para>
/// </remarks>
public sealed class InputDeviceHub : IInputDevices, IDisposable
{
/// <summary>Slices that may throw in a row before the run ends.</summary>
public const int MaxFaults = 20;
/// <summary>How long a slice is.</summary>
public static readonly TimeSpan SliceInterval = TimeSpan.FromMilliseconds(100);
private readonly Lock _gate = new();
private readonly Func<IInputBackend> _backendFactory;
private readonly Func<bool> _paused;
private readonly TimeSpan _interval;
private readonly Action<string> _note;
private readonly ManualResetEventSlim _wake = new(initialState: false);
private readonly List<View> _views = [];
private Thread? _thread;
private bool _disposed;
/// <summary>A hub that reads nothing until a view of it is opened.</summary>
/// <param name="backendFactory">Makes the Windows side a run uses; called on the hub's thread, once per run.</param>
/// <param name="paused">Whether recording is paused now; null is never.</param>
/// <param name="interval">How long a slice is; null is <see cref="SliceInterval"/>.</param>
/// <param name="note">Told, in one line, when a run ends - the Agent's log. No line names a device.</param>
public InputDeviceHub(Func<IInputBackend> backendFactory, Func<bool>? paused = null, TimeSpan? interval = null, Action<string>? note = null)
{
ArgumentNullException.ThrowIfNull(backendFactory);
_backendFactory = backendFactory;
_paused = paused ?? (static () => false);
_interval = interval ?? SliceInterval;
ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(_interval, TimeSpan.Zero, nameof(interval));
_note = note ?? (static _ => { });
}
/// <summary>Whether a run is in progress.</summary>
public bool IsRunning
{
get
{
lock (_gate)
{
return _thread is not null;
}
}
}
public IInputActivitySource Open()
{
var view = new View(this);
lock (_gate)
{
ObjectDisposedException.ThrowIf(_disposed, this);
_views.Add(view);
if (_thread is null)
{
_thread = new Thread(Run) { IsBackground = true, Name = "fl-input" };
_thread.Start();
}
}
return view;
}
public void Dispose()
{
Thread? thread;
lock (_gate)
{
if (_disposed)
{
return;
}
_disposed = true;
thread = _thread;
}
_wake.Set();
if (thread is not null && thread != Thread.CurrentThread)
{
thread.Join(TimeSpan.FromSeconds(5));
}
_wake.Dispose();
}
private void Close(View view)
{
lock (_gate)
{
_views.Remove(view);
}
}
private void Run()
{
IInputBackend? backend = null;
InputHealth last = new();
try
{
backend = _backendFactory();
var reader = new InputReader(backend);
reader.Open();
long before = Stopwatch.GetTimestamp();
int faults = 0;
while (Wait())
{
long now = Stopwatch.GetTimestamp();
int elapsed = (int)Math.Min(Stopwatch.GetElapsedTime(before, now).TotalMilliseconds, int.MaxValue);
before = now;
try
{
InputSlice slice = reader.Slice(elapsed);
last = slice.Health;
faults = 0;
Hand(slice);
}
catch (Exception e) when (e is not OperationCanceledException)
{
reader.Fault();
if (++faults >= MaxFaults)
{
_note($"input: the reader's slice threw {MaxFaults} times running and the run ends ({e.GetType().Name}: {e.Message})");
break;
}
}
}
}
catch (Exception e) when (e is not OperationCanceledException)
{
_note($"input: the reader did not start ({e.GetType().Name}: {e.Message})");
}
finally
{
lock (_gate)
{
if (ReferenceEquals(_thread, Thread.CurrentThread))
{
_thread = null;
}
}
backend?.Dispose();
_note(Summary(last));
}
}
/// <summary>What a run did, as the Agent's log keeps it: counts and yes-or-no answers, nothing of any device.</summary>
private static string Summary(InputHealth h) => string.Create(CultureInfo.InvariantCulture,
$"input: run ended - slices {h.Slices}, raw input {(h.RawInputRegistered ? "registered" : "NOT registered")}, reports {h.RawReports} ({h.RawReportsUnread} not read), "
+ $"xinput {(h.XInputAvailable ? "there" : "absent")} with {h.XInputReads} reads and {h.XInputSilent} silent slices, last input {(h.LastInputAvailable ? "read" : "NOT read")}, "
+ $"thread cpu {h.ThreadCpuMs} ms, faults {h.Faults}");
/// <summary>Waits a slice; false when the run is over - the hub is disposed, or no view is open.</summary>
private bool Wait()
{
try
{
_wake.Wait(_interval);
}
catch (ObjectDisposedException)
{
// Dispose gave up waiting for this thread and released the event.
return false;
}
lock (_gate)
{
if (!_disposed && _views.Count > 0)
{
return true;
}
// Decided under the lock and the slot cleared in the same step, so an Open that arrives a moment later
// starts a run of its own rather than joining one that is closing.
if (ReferenceEquals(_thread, Thread.CurrentThread))
{
_thread = null;
}
return false;
}
}
private void Hand(InputSlice slice)
{
View[] views;
lock (_gate)
{
views = [.. _views];
}
bool paused = _paused();
foreach (View view in views)
{
view.Add(slice, paused);
}
}
/// <summary>One session's view.</summary>
private sealed class View(InputDeviceHub hub) : IInputActivitySource
{
private readonly InputTickAccumulator _sum = new();
private volatile int[] _pids = [];
public void Follow(GameProcess target)
{
ArgumentNullException.ThrowIfNull(target);
_pids = target.Pid is { } pinned ? [pinned] : [.. target.Processes.Select(static p => p.Pid)];
}
public bool TryRead([NotNullWhen(true)] out InputReading? reading)
{
reading = _sum.Take();
return reading is not null;
}
public void Add(InputSlice slice, bool paused) =>
_sum.Add(slice, inFront: slice.ForegroundProcessId != 0 && Array.IndexOf(_pids, (int)slice.ForegroundProcessId) >= 0, paused);
public void Dispose() => hub.Close(this);
}
}
@@ -0,0 +1,98 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Buffers.Binary;
using FrameLedger.Application.Input;
namespace FrameLedger.Infrastructure.Input;
/// <summary>
/// The bytes <c>GetRawInputBuffer</c> and <c>GetRawInputData</c> fill, walked without a pointer: a run of
/// <c>RAWINPUT</c> blocks, each a header and - for a HID device - a count of reports of one size
/// (<c>21_INPUT_DEVICES</c> §The reader).
/// </summary>
/// <remarks>
/// <para>
/// Layout on 64-bit Windows, which is all this project builds for: <c>RAWINPUTHEADER</c> is 24 bytes - <c>u32 type</c>,
/// <c>u32 size</c> of the whole block, the device's handle, a parameter - and a <c>RAWHID</c> follows it: <c>u32</c>
/// the size of one report, <c>u32</c> how many, then the reports. The next block starts at the next multiple of eight
/// (<c>NEXTRAWINPUTBLOCK</c>).
/// </para>
/// <para>
/// <b>It trusts no length it reads.</b> A block that claims more than the buffer holds, or less than its own header,
/// ends the walk: what was handed over before it stands, and nothing is read past the buffer. The bytes come from a
/// device by way of Windows, into an Agent that may run as administrator.
/// </para>
/// </remarks>
public static class RawInputBuffer
{
/// <summary><c>sizeof(RAWINPUTHEADER)</c> on 64-bit Windows.</summary>
public const int HeaderBytes = 24;
/// <summary><c>RIM_TYPEHID</c>: the block is a HID device's, the only kind the reader registers for.</summary>
public const uint TypeHid = 2;
private const int _hidHeaderBytes = 8;
/// <summary>Hands each report of each HID block to <paramref name="sink"/>; returns how many blocks were walked.</summary>
/// <param name="buffer">The bytes Windows filled.</param>
/// <param name="blocks">How many blocks Windows said it wrote.</param>
/// <param name="sink">Told each report with its device's handle.</param>
public static int Walk(ReadOnlySpan<byte> buffer, int blocks, IInputBackendSink sink)
{
ArgumentNullException.ThrowIfNull(sink);
int at = 0;
int walked = 0;
for (; walked < blocks; walked++)
{
if (buffer.Length - at < HeaderBytes)
{
break;
}
uint type = BinaryPrimitives.ReadUInt32LittleEndian(buffer[at..]);
uint size = BinaryPrimitives.ReadUInt32LittleEndian(buffer[(at + 4)..]);
if (size < HeaderBytes || size > buffer.Length - at)
{
break;
}
if (type == TypeHid)
{
Reports(buffer.Slice(at, (int)size), sink);
}
// Each block starts on a multiple of eight. The last one may end the buffer without the padding.
at += (int)((size + 7) & ~7u);
if (at > buffer.Length)
{
walked++;
break;
}
}
return walked;
}
private static void Reports(ReadOnlySpan<byte> block, IInputBackendSink sink)
{
if (block.Length < HeaderBytes + _hidHeaderBytes)
{
return;
}
nint device = (nint)BinaryPrimitives.ReadInt64LittleEndian(block[8..]);
uint reportBytes = BinaryPrimitives.ReadUInt32LittleEndian(block[HeaderBytes..]);
uint count = BinaryPrimitives.ReadUInt32LittleEndian(block[(HeaderBytes + 4)..]);
ReadOnlySpan<byte> reports = block[(HeaderBytes + _hidHeaderBytes)..];
if (reportBytes == 0 || count == 0 || (ulong)reportBytes * count > (ulong)reports.Length)
{
return;
}
for (int i = 0; i < count; i++)
{
sink.Report(device, reports.Slice(i * (int)reportBytes, (int)reportBytes));
}
}
}
@@ -0,0 +1,259 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.InteropServices;
namespace FrameLedger.Infrastructure.Input;
/// <summary>
/// Every Windows function the input reader calls, declared in one place so that the list can be held
/// (<c>tools/input-readonly-check.ps1</c>, <c>21_INPUT_DEVICES</c> §What is read): raw input for game controllers,
/// three of XInput's getters, the time of the last input, and the message-only window raw input is delivered to.
/// </summary>
/// <remarks>
/// <b>What is not here is not called.</b> No function that sends anything to a device (<c>XInputSetState</c>, a HID
/// output or feature report), none that reads a key or a button of the keyboard or mouse, no hook. The structures are
/// declared by hand, blittable, with the sizes the tests assert - the reader passes them to Windows by pointer.
/// </remarks>
internal static unsafe class Win32Input
{
public const uint WmInputDeviceChange = 0x00FE;
public const uint WmInput = 0x00FF;
/// <summary><c>GIDC_ARRIVAL</c> / <c>GIDC_REMOVAL</c>: <c>WM_INPUT_DEVICE_CHANGE</c>'s wParam.</summary>
public const nuint DeviceArrival = 1;
public const nuint DeviceRemoval = 2;
/// <summary><c>RIDEV_INPUTSINK</c>: reports are delivered while the caller is not in front.</summary>
public const uint RidevInputSink = 0x00000100;
/// <summary><c>RIDEV_DEVNOTIFY</c>: a device arriving or leaving is told.</summary>
public const uint RidevDevNotify = 0x00002000;
/// <summary><c>RIDEV_REMOVE</c>: ends a registration.</summary>
public const uint RidevRemove = 0x00000001;
public const uint RidiDeviceName = 0x20000007;
public const uint RidiDeviceInfo = 0x2000000B;
/// <summary><c>RID_INPUT</c>: <c>GetRawInputData</c> returns the whole block.</summary>
public const uint RidInput = 0x10000003;
public const uint PmRemove = 0x0001;
/// <summary><c>XINPUT_CAPS_WIRELESS</c>.</summary>
public const ushort XInputCapsWireless = 0x0002;
/// <summary><c>XINPUT_FLAG_GAMEPAD</c>.</summary>
public const uint XInputFlagGamepad = 0x00000001;
/// <summary><c>BATTERY_DEVTYPE_GAMEPAD</c>.</summary>
public const byte BatteryDevTypeGamepad = 0x00;
/// <summary><c>HWND_MESSAGE</c>: the parent of a window that is never shown and receives no broadcast.</summary>
public static readonly nint HwndMessage = -3;
private const string _user32 = "user32.dll";
private const string _kernel32 = "kernel32.dll";
private const string _xinput = "xinput1_4.dll";
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern ushort RegisterClassExW(WndClassEx* windowClass);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true)]
public static extern int UnregisterClassW(char* className, nint instance);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern nint CreateWindowExW(uint exStyle, char* className, char* windowName, uint style, int x, int y, int width, int height, nint parent, nint menu, nint instance, void* param);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true)]
public static extern int DestroyWindow(nint window);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true)]
public static extern nint DefWindowProcW(nint window, uint message, nuint wParam, nint lParam);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true)]
public static extern int PeekMessageW(Message* message, nint window, uint filterMin, uint filterMax, uint remove);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true)]
public static extern nint DispatchMessageW(Message* message);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern int RegisterRawInputDevices(RawInputDevice* devices, uint count, uint size);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern uint GetRawInputBuffer(void* data, uint* size, uint headerSize);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern uint GetRawInputData(nint rawInput, uint command, void* data, uint* size, uint headerSize);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern uint GetRawInputDeviceInfoW(nint device, uint command, void* data, uint* size);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true, SetLastError = true)]
public static extern uint GetRawInputDeviceList(RawInputDeviceListEntry* list, uint* count, uint size);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_user32, ExactSpelling = true)]
public static extern int GetLastInputInfo(LastInputInfo* info);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_kernel32, ExactSpelling = true)]
public static extern nint GetModuleHandleW(char* name);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_kernel32, ExactSpelling = true)]
public static extern nint GetCurrentThread();
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_kernel32, ExactSpelling = true)]
public static extern int GetThreadTimes(nint thread, long* creation, long* exit, long* kernel, long* user);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_xinput, ExactSpelling = true)]
public static extern uint XInputGetState(uint userIndex, XInputState* state);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_xinput, ExactSpelling = true)]
public static extern uint XInputGetCapabilities(uint userIndex, uint flags, XInputCapabilities* capabilities);
[DefaultDllImportSearchPaths(DllImportSearchPath.System32)]
[DllImport(_xinput, ExactSpelling = true)]
public static extern uint XInputGetBatteryInformation(uint userIndex, byte deviceType, XInputBatteryInformation* battery);
/// <summary><c>WNDCLASSEXW</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct WndClassEx
{
public uint Size;
public uint Style;
public delegate* unmanaged[Stdcall]<nint, uint, nuint, nint, nint> WndProc;
public int ClassExtra;
public int WindowExtra;
public nint Instance;
public nint Icon;
public nint Cursor;
public nint Background;
public char* MenuName;
public char* ClassName;
public nint SmallIcon;
}
/// <summary><c>MSG</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct Message
{
public nint Window;
public uint Id;
public nuint WParam;
public nint LParam;
public uint Time;
public int X;
public int Y;
}
/// <summary><c>RAWINPUTDEVICE</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct RawInputDevice
{
public ushort UsagePage;
public ushort Usage;
public uint Flags;
public nint Target;
}
/// <summary><c>RAWINPUTDEVICELIST</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct RawInputDeviceListEntry
{
public nint Device;
public uint Type;
}
/// <summary><c>RID_DEVICE_INFO</c>, with the HID member of its union - the only one the reader looks at.</summary>
[StructLayout(LayoutKind.Explicit, Size = 32)]
public struct RidDeviceInfo
{
[FieldOffset(0)]
public uint Size;
[FieldOffset(4)]
public uint Type;
[FieldOffset(8)]
public uint VendorId;
[FieldOffset(12)]
public uint ProductId;
[FieldOffset(16)]
public uint VersionNumber;
[FieldOffset(20)]
public ushort UsagePage;
[FieldOffset(22)]
public ushort Usage;
}
/// <summary><c>XINPUT_GAMEPAD</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct XInputGamepad
{
public ushort Buttons;
public byte LeftTrigger;
public byte RightTrigger;
public short ThumbLx;
public short ThumbLy;
public short ThumbRx;
public short ThumbRy;
}
/// <summary><c>XINPUT_STATE</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct XInputState
{
public uint PacketNumber;
public XInputGamepad Gamepad;
}
/// <summary><c>XINPUT_CAPABILITIES</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct XInputCapabilities
{
public byte Type;
public byte SubType;
public ushort Flags;
public XInputGamepad Gamepad;
public ushort LeftMotor;
public ushort RightMotor;
}
/// <summary><c>XINPUT_BATTERY_INFORMATION</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct XInputBatteryInformation
{
public byte Type;
public byte Level;
}
/// <summary><c>LASTINPUTINFO</c>.</summary>
[StructLayout(LayoutKind.Sequential)]
public struct LastInputInfo
{
public uint Size;
public uint Time;
}
}
@@ -0,0 +1,383 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
using FrameLedger.Application.Input;
using FrameLedger.Domain.Input;
using FrameLedger.Infrastructure.Io;
using Microsoft.Win32.SafeHandles;
namespace FrameLedger.Infrastructure.Input;
/// <summary>
/// The input reader's Windows side (<c>21_INPUT_DEVICES</c> §The reader): a window that is never shown, registered to
/// receive game controllers' reports while the Agent is in the background; three of XInput's getters; the time of the
/// last keyboard or mouse input; the window in front.
/// </summary>
/// <remarks>
/// <para>
/// <b>It opens no device.</b> Raw input hands the reports over; a handle of FrameLedger's on a controller could make a
/// game's own exclusive open of it fail. <b>It sends nothing to a device</b> and asks none for a feature report (owner
/// decision D159). <b>It registers for game controllers only</b> - <see cref="InputReader.RegisteredUsages"/> - never
/// for a keyboard or a mouse (D158).
/// </para>
/// <para>
/// <b>Reports are read in bulk, once a slice</b> (<c>GetRawInputBuffer</c>), not one message at a time: a DualSense
/// sends some hundreds a second, and the Agent's whole budget is 2.5 % of one core (NFR-2). A report that still comes
/// as a message is read too, so that neither path alone has to be the one that works on a given PC.
/// </para>
/// <para>
/// <b>A device's name is read and dropped.</b> It says whether Windows presents the device through XInput and how it
/// is connected (<see cref="RawDeviceName"/>); it can also carry an address, so it is never kept, logged or returned.
/// </para>
/// <para>
/// <b>No controller was at hand when this was written</b> (owner decision D157). What it does with none connected is
/// under test; what it does with one is owner-only item 48, read from the counts every session stores.
/// </para>
/// </remarks>
public sealed unsafe class Win32InputBackend : IInputBackend
{
/// <summary>The most messages one drain takes off the queue, and the most reads of the buffer: a slice is short.</summary>
private const int _maxMessages = 2048;
private const int _maxBufferReads = 64;
private const int _bufferBytes = 64 * 1024;
private const int _maxNameChars = 1024;
private const uint _success = 0;
private const uint _failed = unchecked((uint)-1);
private const string _className = "FrameLedger.InputReader";
private readonly List<(nint Device, RawController Controller)> _present = [];
private byte[]? _buffer;
private MessageWindow? _window;
private bool _classRegistered;
private bool _registered;
private bool _xinputAvailable = true;
private bool _disposed;
public bool XInputAvailable => _xinputAvailable;
public bool Open()
{
ObjectDisposedException.ThrowIf(_disposed, this);
AssertLayout();
// On the pinned heap and so at an address a multiple of eight, which GetRawInputBuffer requires of its buffer.
_buffer = GC.AllocateUninitializedArray<byte>(_bufferBytes, pinned: true);
nint instance = Win32Input.GetModuleHandleW(null);
nint window;
fixed (char* name = _className)
{
var windowClass = new Win32Input.WndClassEx
{
Size = (uint)sizeof(Win32Input.WndClassEx),
WndProc = &WindowProcedure,
Instance = instance,
ClassName = name,
};
// Zero with the class already there is fine: an earlier reader of this process registered it.
_classRegistered = Win32Input.RegisterClassExW(&windowClass) != 0;
window = Win32Input.CreateWindowExW(0, name, name, 0, 0, 0, 0, 0, Win32Input.HwndMessage, 0, instance, null);
}
if (window == 0)
{
return false;
}
_window = new MessageWindow(window);
_registered = Register(Win32Input.RidevInputSink | Win32Input.RidevDevNotify, window);
if (_registered)
{
ListPresent();
}
return _registered;
}
public void Drain(IInputBackendSink sink)
{
ArgumentNullException.ThrowIfNull(sink);
if (_window is null || _buffer is null)
{
return;
}
// The controllers that were there when the reader opened, once.
foreach ((nint device, RawController controller) in _present)
{
sink.Arrived(device, controller);
}
_present.Clear();
// First who came and went, so that a report is never of a device nobody has named yet.
Win32Input.Message message;
for (int i = 0; i < _maxMessages && Win32Input.PeekMessageW(&message, 0, Win32Input.WmInputDeviceChange, Win32Input.WmInputDeviceChange, Win32Input.PmRemove) != 0; i++)
{
DeviceChanged(message, sink);
}
ReadBuffered(sink);
// Then whatever is left on the queue. A report that came as a message is read as one; anything else is the
// window's to answer, which for this window is the default.
for (int i = 0; i < _maxMessages && Win32Input.PeekMessageW(&message, 0, 0, 0, Win32Input.PmRemove) != 0; i++)
{
if (message.Id == Win32Input.WmInputDeviceChange)
{
DeviceChanged(message, sink);
}
else if (message.Id == Win32Input.WmInput)
{
ReadMessage(message.LParam, sink);
}
Win32Input.DispatchMessageW(&message);
}
}
public bool TryReadPad(int slot, out XInputReading pad)
{
pad = default;
if (!_xinputAvailable)
{
return false;
}
Win32Input.XInputState state;
try
{
if (Win32Input.XInputGetState((uint)slot, &state) != _success)
{
return false;
}
}
catch (Exception e) when (e is DllNotFoundException or EntryPointNotFoundException)
{
_xinputAvailable = false;
return false;
}
Win32Input.XInputGamepad g = state.Gamepad;
pad = new XInputReading(state.PacketNumber, g.Buttons, g.LeftTrigger, g.RightTrigger, g.ThumbLx, g.ThumbLy, g.ThumbRx, g.ThumbRy);
return true;
}
public bool TryReadPadDetails(int slot, out XInputDetails details)
{
details = default;
if (!_xinputAvailable)
{
return false;
}
try
{
Win32Input.XInputCapabilities capabilities;
if (Win32Input.XInputGetCapabilities((uint)slot, Win32Input.XInputFlagGamepad, &capabilities) != _success)
{
return false;
}
// A pad whose battery XInput does not answer about - one on Bluetooth is reported not to - still has its
// wireless flag: type 0 is XInput's own "disconnected", which reads as no battery to show.
Win32Input.XInputBatteryInformation battery = default;
bool answered = Win32Input.XInputGetBatteryInformation((uint)slot, Win32Input.BatteryDevTypeGamepad, &battery) == _success;
details = new XInputDetails((capabilities.Flags & Win32Input.XInputCapsWireless) != 0, answered ? battery.Type : 0, answered ? battery.Level : 0);
return true;
}
catch (Exception e) when (e is DllNotFoundException or EntryPointNotFoundException)
{
_xinputAvailable = false;
return false;
}
}
public bool TryReadLastInputTick(out uint tick)
{
var info = new Win32Input.LastInputInfo { Size = (uint)sizeof(Win32Input.LastInputInfo) };
bool read = Win32Input.GetLastInputInfo(&info) != 0;
tick = read ? info.Time : 0;
return read;
}
public uint ForegroundProcessId() => ForegroundWindowProbe.ForegroundProcessId();
public long ThreadCpuMs()
{
long creation;
long exit;
long kernel;
long user;
return Win32Input.GetThreadTimes(Win32Input.GetCurrentThread(), &creation, &exit, &kernel, &user) != 0
? (kernel + user) / TimeSpan.TicksPerMillisecond
: 0;
}
/// <summary>
/// Ends the registration and destroys the window. Called on the thread that opened it: a window belongs to its
/// thread, and Windows refuses another's attempt to destroy it.
/// </summary>
public void Dispose()
{
if (_disposed)
{
return;
}
_disposed = true;
if (_registered)
{
// Ending a registration names no window (the API refuses one there).
Register(Win32Input.RidevRemove, target: 0);
_registered = false;
}
_window?.Dispose();
_window = null;
if (_classRegistered)
{
fixed (char* name = _className)
{
_ = Win32Input.UnregisterClassW(name, Win32Input.GetModuleHandleW(null));
}
_classRegistered = false;
}
_buffer = null;
}
[UnmanagedCallersOnly(CallConvs = [typeof(CallConvStdcall)])]
private static nint WindowProcedure(nint window, uint message, nuint wParam, nint lParam) => Win32Input.DefWindowProcW(window, message, wParam, lParam);
/// <summary>The structures are passed to Windows by pointer: a size that is not Windows' is a bug to stop on, not to read with.</summary>
private static void AssertLayout()
{
if (sizeof(Win32Input.WndClassEx) != 80 || sizeof(Win32Input.Message) != 48 || sizeof(Win32Input.RawInputDevice) != 16
|| sizeof(Win32Input.RawInputDeviceListEntry) != 16 || sizeof(Win32Input.RidDeviceInfo) != 32 || sizeof(Win32Input.XInputState) != 16
|| sizeof(Win32Input.XInputCapabilities) != 20 || sizeof(Win32Input.XInputBatteryInformation) != 2 || sizeof(Win32Input.LastInputInfo) != 8
|| nint.Size != 8)
{
throw new InvalidOperationException("the input reader's structures are not the size Windows expects of them");
}
}
private static bool Register(uint flags, nint target)
{
IReadOnlyList<(ushort UsagePage, ushort Usage)> usages = InputReader.RegisteredUsages;
Win32Input.RawInputDevice* devices = stackalloc Win32Input.RawInputDevice[usages.Count];
for (int i = 0; i < usages.Count; i++)
{
devices[i] = new Win32Input.RawInputDevice { UsagePage = usages[i].UsagePage, Usage = usages[i].Usage, Flags = flags, Target = target };
}
return Win32Input.RegisterRawInputDevices(devices, (uint)usages.Count, (uint)sizeof(Win32Input.RawInputDevice)) != 0;
}
private void ListPresent()
{
uint count = 0;
uint entry = (uint)sizeof(Win32Input.RawInputDeviceListEntry);
if (Win32Input.GetRawInputDeviceList(null, &count, entry) == _failed || count is 0 or > 4096)
{
return;
}
var list = new Win32Input.RawInputDeviceListEntry[count];
fixed (Win32Input.RawInputDeviceListEntry* p = list)
{
uint written = Win32Input.GetRawInputDeviceList(p, &count, entry);
if (written == _failed)
{
return;
}
for (int i = 0; i < written && i < list.Length; i++)
{
if (list[i].Type == RawInputBuffer.TypeHid && Describe(list[i].Device) is { } controller)
{
_present.Add((list[i].Device, controller));
}
}
}
}
private static void DeviceChanged(Win32Input.Message message, IInputBackendSink sink)
{
if (message.WParam == Win32Input.DeviceArrival)
{
if (Describe(message.LParam) is { } controller)
{
sink.Arrived(message.LParam, controller);
}
}
else if (message.WParam == Win32Input.DeviceRemoval)
{
sink.Removed(message.LParam);
}
}
/// <summary>What a device is, when it is a game controller; null for anything else, and for a device that left before it could be asked.</summary>
private static RawController? Describe(nint device)
{
var info = new Win32Input.RidDeviceInfo { Size = (uint)sizeof(Win32Input.RidDeviceInfo) };
uint size = info.Size;
uint written = Win32Input.GetRawInputDeviceInfoW(device, Win32Input.RidiDeviceInfo, &info, &size);
if (written is 0 or _failed || info.Type != RawInputBuffer.TypeHid
|| !InputReader.RegisteredUsages.Contains((info.UsagePage, info.Usage)))
{
return null;
}
// The name is used for the two facts below and goes no further than this method.
char* name = stackalloc char[_maxNameChars];
uint chars = _maxNameChars;
uint copied = Win32Input.GetRawInputDeviceInfoW(device, Win32Input.RidiDeviceName, name, &chars);
string? path = copied is 0 or _failed || copied > _maxNameChars ? null : new string(name, 0, (int)copied).TrimEnd('\0');
return new RawController((int)(info.VendorId & 0xFFFF), (int)(info.ProductId & 0xFFFF), RawDeviceName.IsXInputClass(path), RawDeviceName.ConnectionOf(path));
}
private void ReadBuffered(IInputBackendSink sink)
{
fixed (byte* buffer = _buffer)
{
for (int i = 0; i < _maxBufferReads; i++)
{
uint size = _bufferBytes;
uint blocks = Win32Input.GetRawInputBuffer(buffer, &size, RawInputBuffer.HeaderBytes);
if (blocks is 0 or _failed)
{
return;
}
RawInputBuffer.Walk(new ReadOnlySpan<byte>(buffer, _bufferBytes), (int)Math.Min(blocks, int.MaxValue), sink);
}
}
}
/// <summary>The message-only window, as a handle that is destroyed once.</summary>
private sealed class MessageWindow : SafeHandleZeroOrMinusOneIsInvalid
{
public MessageWindow(nint window)
: base(ownsHandle: true) => SetHandle(window);
protected override bool ReleaseHandle() => Win32Input.DestroyWindow(handle) != 0;
}
private void ReadMessage(nint rawInput, IInputBackendSink sink)
{
fixed (byte* buffer = _buffer)
{
uint size = _bufferBytes;
uint written = Win32Input.GetRawInputData(rawInput, Win32Input.RidInput, buffer, &size, RawInputBuffer.HeaderBytes);
if (written is not (0 or _failed) && written <= _bufferBytes)
{
RawInputBuffer.Walk(new ReadOnlySpan<byte>(buffer, (int)written), 1, sink);
}
}
}
}
@@ -0,0 +1,35 @@
-- 0024 (2026-11-14, 0.1.0-beta.50, owner decisions D155-D163): what a session was played with, and whether a game's
-- store lists controller support (03_METRICS §Input, 21_INPUT_DEVICES).
--
-- sessions: milliseconds, read by the Agent from outside the game - so both tiers have them. `input_observed_ms` is the
-- time the reader ran and the session was not paused; `input_foreground_ms` is the part of it a window of the game was
-- in front, and the four classes add up to it: a controller in use, the keyboard or mouse in use (one class - only the
-- time of the last input is read), both, neither. `input_method_switches` counts the changes between a controller and
-- the keyboard and mouse. `input_source` names the sources that answered (rawinput, xinput, lastinput, joined by +).
-- `input_devices` is InputDevicesRecord's JSON: each controller's maker, model and connection, its time connected and
-- in use, its connections and drops, its battery; each maker's share; what the reader's sources did. No serial number,
-- no address, no path. The series of the timeline are sensor_blobs rows named input.* (NaN where there is no value).
--
-- These are columns of sessions, not a table of their own, on purpose (D160): the trend and the comparison read a
-- session's row, and the CSV/JSON export and the bug bundle carry it - the Privacy Policy's section 3A says so.
--
-- games: `controller_support` is what the store's own file on the disk says - 'full', 'partial', or 'none' for a game
-- the store knows and lists no support for; `controller_support_source` names the file ('steam-appinfo');
-- `controller_support_at` is when it was read (unix ms). No network request is made for it.
--
-- NULL on every row written before; on a session recorded with the option off, or before the terms that describe the
-- reading were accepted (D156); on a game no store file describes. ADD COLUMN only.
ALTER TABLE sessions ADD COLUMN input_observed_ms INTEGER;
ALTER TABLE sessions ADD COLUMN input_foreground_ms INTEGER;
ALTER TABLE sessions ADD COLUMN input_controller_ms INTEGER;
ALTER TABLE sessions ADD COLUMN input_km_ms INTEGER;
ALTER TABLE sessions ADD COLUMN input_both_ms INTEGER;
ALTER TABLE sessions ADD COLUMN input_idle_ms INTEGER;
ALTER TABLE sessions ADD COLUMN input_method_switches INTEGER;
ALTER TABLE sessions ADD COLUMN input_source TEXT;
ALTER TABLE sessions ADD COLUMN input_devices TEXT;
ALTER TABLE games ADD COLUMN controller_support TEXT;
ALTER TABLE games ADD COLUMN controller_support_source TEXT;
ALTER TABLE games ADD COLUMN controller_support_at INTEGER;
@@ -19,10 +19,10 @@ namespace FrameLedger.Infrastructure.Persistence;
internal static class SessionRowColumns
{
public const string Insert =
"INSERT INTO sessions (session_guid, game_id, snapshot_id, started_at, ended_at, duration_s, qpc_epoch, qpc_frequency, capture_tier, capture_mode, capture_notes, ac_exception_family, late_attach, telemetry_source, overlay_build_id, exit_status, drain_ticks, foreground_ticks, records_before_attach, dxgi_presents_before_hook, gap_count, guard_ticks_published, launch_wait_ms, api, present_mode, swap_effect, hdr_flag, hdr_source, sync_interval_mode, upscaler, upscaler_quality, upscaler_sharpness, upscaler_driver_reported, render_w, render_h, output_w, output_h, upscale_ratio, settings_changed_midsession, fg_mode, fg_source, fg_factor, fg_driver_reported, fg_runtime_census, fg_none_withheld_reason, fg_refusal, fg_refusal_detail, fg_factor_scope, fg_steady_share, presented_fps, presented_qualifier, dxgi_unseen_total, dxgi_present_samples, displayed_counted_by, sl_tag_census, sl_interposer_version, runtime_modules, driver_profile, executable_markers, ngx_driver_words, rt_flag, rt_source, pt_flag, pt_source, pt_confidence, rr_flag, rr_source, rt_frame_pct, rays_per_pixel, rt_pso_count, rt_tier, hooks_installed_mask, raster_pso_count, frame_count, app_frame_count, displayed_frame_count, dropped_frames, native_fps, displayed_fps, median_fps, p1_low_fps, p01_low_fps, displayed_p1_low_fps, min_fps, max_fps, frametime_stddev_ms, stutter_count, stutter_time_pct, pso_stutter_pct, reflex_active, latency_avg_us, latency_p95_us, dropped_records, fault_count, data_quality_warnings, writer_status_at_end, early_stop_family, loader_signals, vram_proc_avg_mb, vram_proc_max_mb, vram_budget_exceeded_pct, vram_adapter_max_mb, avg_cpu_temp, max_cpu_temp, avg_gpu_temp, max_gpu_temp, max_gpu_hotspot, avg_gpu_load, avg_cpu_load, avg_ram_mb, avg_gpu_power_w, throttle_pct, display_exclusive_ms, display_borderless_ms, display_windowed_ms, display_covers_ms, display_minimized_ms, display_nowindow_ms, display_changes, display_source, display_window_w, display_window_h, display_buffer_w, display_buffer_h, display_monitor_w, display_monitor_h, display_monitor_hz, game_vram_dedicated_avg_mb, game_vram_dedicated_median_mb, game_vram_dedicated_max_mb, game_vram_shared_max_mb, game_ram_private_avg_mb, game_ram_private_median_mb, game_ram_private_max_mb, game_ram_ws_max_mb, game_commit_max_mb, game_memory_processes, game_memory_source, sensor_stats_json, time_below_30_pct, time_below_60_pct, time_below_refresh_pct, frametime_delta_mean_ms, vsync_present_pct, tearing_allowed_pct, avg_gpu_core_clock_mhz, avg_gpu_mem_clock_mhz, avg_gpu_fan_rpm, max_gpu_mem_temp, power_limit_pct, thermal_limit_pct, app_frames_per_joule, fg_mix, runtime_module_sources, dlss_nr_pct) "
+ "VALUES (@session_guid, @game_id, @snapshot_id, @started_at, @ended_at, @duration_s, @qpc_epoch, @qpc_frequency, @capture_tier, @capture_mode, @capture_notes, @ac_exception_family, @late_attach, @telemetry_source, @overlay_build_id, @exit_status, @drain_ticks, @foreground_ticks, @records_before_attach, @dxgi_presents_before_hook, @gap_count, @guard_ticks_published, @launch_wait_ms, @api, @present_mode, @swap_effect, @hdr_flag, @hdr_source, @sync_interval_mode, @upscaler, @upscaler_quality, @upscaler_sharpness, @upscaler_driver_reported, @render_w, @render_h, @output_w, @output_h, @upscale_ratio, @settings_changed_midsession, @fg_mode, @fg_source, @fg_factor, @fg_driver_reported, @fg_runtime_census, @fg_none_withheld_reason, @fg_refusal, @fg_refusal_detail, @fg_factor_scope, @fg_steady_share, @presented_fps, @presented_qualifier, @dxgi_unseen_total, @dxgi_present_samples, @displayed_counted_by, @sl_tag_census, @sl_interposer_version, @runtime_modules, @driver_profile, @executable_markers, @ngx_driver_words, @rt_flag, @rt_source, @pt_flag, @pt_source, @pt_confidence, @rr_flag, @rr_source, @rt_frame_pct, @rays_per_pixel, @rt_pso_count, @rt_tier, @hooks_installed_mask, @raster_pso_count, @frame_count, @app_frame_count, @displayed_frame_count, @dropped_frames, @native_fps, @displayed_fps, @median_fps, @p1_low_fps, @p01_low_fps, @displayed_p1_low_fps, @min_fps, @max_fps, @frametime_stddev_ms, @stutter_count, @stutter_time_pct, @pso_stutter_pct, @reflex_active, @latency_avg_us, @latency_p95_us, @dropped_records, @fault_count, @data_quality_warnings, @writer_status_at_end, @early_stop_family, @loader_signals, @vram_proc_avg_mb, @vram_proc_max_mb, @vram_budget_exceeded_pct, @vram_adapter_max_mb, @avg_cpu_temp, @max_cpu_temp, @avg_gpu_temp, @max_gpu_temp, @max_gpu_hotspot, @avg_gpu_load, @avg_cpu_load, @avg_ram_mb, @avg_gpu_power_w, @throttle_pct, @display_exclusive_ms, @display_borderless_ms, @display_windowed_ms, @display_covers_ms, @display_minimized_ms, @display_nowindow_ms, @display_changes, @display_source, @display_window_w, @display_window_h, @display_buffer_w, @display_buffer_h, @display_monitor_w, @display_monitor_h, @display_monitor_hz, @game_vram_dedicated_avg_mb, @game_vram_dedicated_median_mb, @game_vram_dedicated_max_mb, @game_vram_shared_max_mb, @game_ram_private_avg_mb, @game_ram_private_median_mb, @game_ram_private_max_mb, @game_ram_ws_max_mb, @game_commit_max_mb, @game_memory_processes, @game_memory_source, @sensor_stats_json, @time_below_30_pct, @time_below_60_pct, @time_below_refresh_pct, @frametime_delta_mean_ms, @vsync_present_pct, @tearing_allowed_pct, @avg_gpu_core_clock_mhz, @avg_gpu_mem_clock_mhz, @avg_gpu_fan_rpm, @max_gpu_mem_temp, @power_limit_pct, @thermal_limit_pct, @app_frames_per_joule, @fg_mix, @runtime_module_sources, @dlss_nr_pct) RETURNING id";
"INSERT INTO sessions (session_guid, game_id, snapshot_id, started_at, ended_at, duration_s, qpc_epoch, qpc_frequency, capture_tier, capture_mode, capture_notes, ac_exception_family, late_attach, telemetry_source, overlay_build_id, exit_status, drain_ticks, foreground_ticks, records_before_attach, dxgi_presents_before_hook, gap_count, guard_ticks_published, launch_wait_ms, api, present_mode, swap_effect, hdr_flag, hdr_source, sync_interval_mode, upscaler, upscaler_quality, upscaler_sharpness, upscaler_driver_reported, render_w, render_h, output_w, output_h, upscale_ratio, settings_changed_midsession, fg_mode, fg_source, fg_factor, fg_driver_reported, fg_runtime_census, fg_none_withheld_reason, fg_refusal, fg_refusal_detail, fg_factor_scope, fg_steady_share, presented_fps, presented_qualifier, dxgi_unseen_total, dxgi_present_samples, displayed_counted_by, sl_tag_census, sl_interposer_version, runtime_modules, driver_profile, executable_markers, ngx_driver_words, rt_flag, rt_source, pt_flag, pt_source, pt_confidence, rr_flag, rr_source, rt_frame_pct, rays_per_pixel, rt_pso_count, rt_tier, hooks_installed_mask, raster_pso_count, frame_count, app_frame_count, displayed_frame_count, dropped_frames, native_fps, displayed_fps, median_fps, p1_low_fps, p01_low_fps, displayed_p1_low_fps, min_fps, max_fps, frametime_stddev_ms, stutter_count, stutter_time_pct, pso_stutter_pct, reflex_active, latency_avg_us, latency_p95_us, dropped_records, fault_count, data_quality_warnings, writer_status_at_end, early_stop_family, loader_signals, vram_proc_avg_mb, vram_proc_max_mb, vram_budget_exceeded_pct, vram_adapter_max_mb, avg_cpu_temp, max_cpu_temp, avg_gpu_temp, max_gpu_temp, max_gpu_hotspot, avg_gpu_load, avg_cpu_load, avg_ram_mb, avg_gpu_power_w, throttle_pct, display_exclusive_ms, display_borderless_ms, display_windowed_ms, display_covers_ms, display_minimized_ms, display_nowindow_ms, display_changes, display_source, display_window_w, display_window_h, display_buffer_w, display_buffer_h, display_monitor_w, display_monitor_h, display_monitor_hz, game_vram_dedicated_avg_mb, game_vram_dedicated_median_mb, game_vram_dedicated_max_mb, game_vram_shared_max_mb, game_ram_private_avg_mb, game_ram_private_median_mb, game_ram_private_max_mb, game_ram_ws_max_mb, game_commit_max_mb, game_memory_processes, game_memory_source, sensor_stats_json, time_below_30_pct, time_below_60_pct, time_below_refresh_pct, frametime_delta_mean_ms, vsync_present_pct, tearing_allowed_pct, avg_gpu_core_clock_mhz, avg_gpu_mem_clock_mhz, avg_gpu_fan_rpm, max_gpu_mem_temp, power_limit_pct, thermal_limit_pct, app_frames_per_joule, fg_mix, runtime_module_sources, dlss_nr_pct, input_observed_ms, input_foreground_ms, input_controller_ms, input_km_ms, input_both_ms, input_idle_ms, input_method_switches, input_source, input_devices) "
+ "VALUES (@session_guid, @game_id, @snapshot_id, @started_at, @ended_at, @duration_s, @qpc_epoch, @qpc_frequency, @capture_tier, @capture_mode, @capture_notes, @ac_exception_family, @late_attach, @telemetry_source, @overlay_build_id, @exit_status, @drain_ticks, @foreground_ticks, @records_before_attach, @dxgi_presents_before_hook, @gap_count, @guard_ticks_published, @launch_wait_ms, @api, @present_mode, @swap_effect, @hdr_flag, @hdr_source, @sync_interval_mode, @upscaler, @upscaler_quality, @upscaler_sharpness, @upscaler_driver_reported, @render_w, @render_h, @output_w, @output_h, @upscale_ratio, @settings_changed_midsession, @fg_mode, @fg_source, @fg_factor, @fg_driver_reported, @fg_runtime_census, @fg_none_withheld_reason, @fg_refusal, @fg_refusal_detail, @fg_factor_scope, @fg_steady_share, @presented_fps, @presented_qualifier, @dxgi_unseen_total, @dxgi_present_samples, @displayed_counted_by, @sl_tag_census, @sl_interposer_version, @runtime_modules, @driver_profile, @executable_markers, @ngx_driver_words, @rt_flag, @rt_source, @pt_flag, @pt_source, @pt_confidence, @rr_flag, @rr_source, @rt_frame_pct, @rays_per_pixel, @rt_pso_count, @rt_tier, @hooks_installed_mask, @raster_pso_count, @frame_count, @app_frame_count, @displayed_frame_count, @dropped_frames, @native_fps, @displayed_fps, @median_fps, @p1_low_fps, @p01_low_fps, @displayed_p1_low_fps, @min_fps, @max_fps, @frametime_stddev_ms, @stutter_count, @stutter_time_pct, @pso_stutter_pct, @reflex_active, @latency_avg_us, @latency_p95_us, @dropped_records, @fault_count, @data_quality_warnings, @writer_status_at_end, @early_stop_family, @loader_signals, @vram_proc_avg_mb, @vram_proc_max_mb, @vram_budget_exceeded_pct, @vram_adapter_max_mb, @avg_cpu_temp, @max_cpu_temp, @avg_gpu_temp, @max_gpu_temp, @max_gpu_hotspot, @avg_gpu_load, @avg_cpu_load, @avg_ram_mb, @avg_gpu_power_w, @throttle_pct, @display_exclusive_ms, @display_borderless_ms, @display_windowed_ms, @display_covers_ms, @display_minimized_ms, @display_nowindow_ms, @display_changes, @display_source, @display_window_w, @display_window_h, @display_buffer_w, @display_buffer_h, @display_monitor_w, @display_monitor_h, @display_monitor_hz, @game_vram_dedicated_avg_mb, @game_vram_dedicated_median_mb, @game_vram_dedicated_max_mb, @game_vram_shared_max_mb, @game_ram_private_avg_mb, @game_ram_private_median_mb, @game_ram_private_max_mb, @game_ram_ws_max_mb, @game_commit_max_mb, @game_memory_processes, @game_memory_source, @sensor_stats_json, @time_below_30_pct, @time_below_60_pct, @time_below_refresh_pct, @frametime_delta_mean_ms, @vsync_present_pct, @tearing_allowed_pct, @avg_gpu_core_clock_mhz, @avg_gpu_mem_clock_mhz, @avg_gpu_fan_rpm, @max_gpu_mem_temp, @power_limit_pct, @thermal_limit_pct, @app_frames_per_joule, @fg_mix, @runtime_module_sources, @dlss_nr_pct, @input_observed_ms, @input_foreground_ms, @input_controller_ms, @input_km_ms, @input_both_ms, @input_idle_ms, @input_method_switches, @input_source, @input_devices) RETURNING id";
public const string Select = "SELECT id, session_guid, game_id, snapshot_id, started_at, ended_at, duration_s, qpc_epoch, qpc_frequency, capture_tier, capture_mode, capture_notes, ac_exception_family, late_attach, telemetry_source, overlay_build_id, exit_status, drain_ticks, foreground_ticks, records_before_attach, dxgi_presents_before_hook, gap_count, guard_ticks_published, launch_wait_ms, api, present_mode, swap_effect, hdr_flag, hdr_source, sync_interval_mode, upscaler, upscaler_quality, upscaler_sharpness, upscaler_driver_reported, render_w, render_h, output_w, output_h, upscale_ratio, settings_changed_midsession, fg_mode, fg_source, fg_factor, fg_driver_reported, fg_runtime_census, fg_none_withheld_reason, fg_refusal, fg_refusal_detail, fg_factor_scope, fg_steady_share, presented_fps, presented_qualifier, dxgi_unseen_total, dxgi_present_samples, displayed_counted_by, sl_tag_census, sl_interposer_version, runtime_modules, driver_profile, executable_markers, ngx_driver_words, rt_flag, rt_source, pt_flag, pt_source, pt_confidence, rr_flag, rr_source, rt_frame_pct, rays_per_pixel, rt_pso_count, rt_tier, hooks_installed_mask, raster_pso_count, frame_count, app_frame_count, displayed_frame_count, dropped_frames, native_fps, displayed_fps, median_fps, p1_low_fps, p01_low_fps, displayed_p1_low_fps, min_fps, max_fps, frametime_stddev_ms, stutter_count, stutter_time_pct, pso_stutter_pct, reflex_active, latency_avg_us, latency_p95_us, dropped_records, fault_count, data_quality_warnings, writer_status_at_end, early_stop_family, loader_signals, vram_proc_avg_mb, vram_proc_max_mb, vram_budget_exceeded_pct, vram_adapter_max_mb, avg_cpu_temp, max_cpu_temp, avg_gpu_temp, max_gpu_temp, max_gpu_hotspot, avg_gpu_load, avg_cpu_load, avg_ram_mb, avg_gpu_power_w, throttle_pct, display_exclusive_ms, display_borderless_ms, display_windowed_ms, display_covers_ms, display_minimized_ms, display_nowindow_ms, display_changes, display_source, display_window_w, display_window_h, display_buffer_w, display_buffer_h, display_monitor_w, display_monitor_h, display_monitor_hz, game_vram_dedicated_avg_mb, game_vram_dedicated_median_mb, game_vram_dedicated_max_mb, game_vram_shared_max_mb, game_ram_private_avg_mb, game_ram_private_median_mb, game_ram_private_max_mb, game_ram_ws_max_mb, game_commit_max_mb, game_memory_processes, game_memory_source, sensor_stats_json, time_below_30_pct, time_below_60_pct, time_below_refresh_pct, frametime_delta_mean_ms, vsync_present_pct, tearing_allowed_pct, avg_gpu_core_clock_mhz, avg_gpu_mem_clock_mhz, avg_gpu_fan_rpm, max_gpu_mem_temp, power_limit_pct, thermal_limit_pct, app_frames_per_joule, fg_mix, runtime_module_sources, dlss_nr_pct FROM sessions";
public const string Select = "SELECT id, session_guid, game_id, snapshot_id, started_at, ended_at, duration_s, qpc_epoch, qpc_frequency, capture_tier, capture_mode, capture_notes, ac_exception_family, late_attach, telemetry_source, overlay_build_id, exit_status, drain_ticks, foreground_ticks, records_before_attach, dxgi_presents_before_hook, gap_count, guard_ticks_published, launch_wait_ms, api, present_mode, swap_effect, hdr_flag, hdr_source, sync_interval_mode, upscaler, upscaler_quality, upscaler_sharpness, upscaler_driver_reported, render_w, render_h, output_w, output_h, upscale_ratio, settings_changed_midsession, fg_mode, fg_source, fg_factor, fg_driver_reported, fg_runtime_census, fg_none_withheld_reason, fg_refusal, fg_refusal_detail, fg_factor_scope, fg_steady_share, presented_fps, presented_qualifier, dxgi_unseen_total, dxgi_present_samples, displayed_counted_by, sl_tag_census, sl_interposer_version, runtime_modules, driver_profile, executable_markers, ngx_driver_words, rt_flag, rt_source, pt_flag, pt_source, pt_confidence, rr_flag, rr_source, rt_frame_pct, rays_per_pixel, rt_pso_count, rt_tier, hooks_installed_mask, raster_pso_count, frame_count, app_frame_count, displayed_frame_count, dropped_frames, native_fps, displayed_fps, median_fps, p1_low_fps, p01_low_fps, displayed_p1_low_fps, min_fps, max_fps, frametime_stddev_ms, stutter_count, stutter_time_pct, pso_stutter_pct, reflex_active, latency_avg_us, latency_p95_us, dropped_records, fault_count, data_quality_warnings, writer_status_at_end, early_stop_family, loader_signals, vram_proc_avg_mb, vram_proc_max_mb, vram_budget_exceeded_pct, vram_adapter_max_mb, avg_cpu_temp, max_cpu_temp, avg_gpu_temp, max_gpu_temp, max_gpu_hotspot, avg_gpu_load, avg_cpu_load, avg_ram_mb, avg_gpu_power_w, throttle_pct, display_exclusive_ms, display_borderless_ms, display_windowed_ms, display_covers_ms, display_minimized_ms, display_nowindow_ms, display_changes, display_source, display_window_w, display_window_h, display_buffer_w, display_buffer_h, display_monitor_w, display_monitor_h, display_monitor_hz, game_vram_dedicated_avg_mb, game_vram_dedicated_median_mb, game_vram_dedicated_max_mb, game_vram_shared_max_mb, game_ram_private_avg_mb, game_ram_private_median_mb, game_ram_private_max_mb, game_ram_ws_max_mb, game_commit_max_mb, game_memory_processes, game_memory_source, sensor_stats_json, time_below_30_pct, time_below_60_pct, time_below_refresh_pct, frametime_delta_mean_ms, vsync_present_pct, tearing_allowed_pct, avg_gpu_core_clock_mhz, avg_gpu_mem_clock_mhz, avg_gpu_fan_rpm, max_gpu_mem_temp, power_limit_pct, thermal_limit_pct, app_frames_per_joule, fg_mix, runtime_module_sources, dlss_nr_pct, input_observed_ms, input_foreground_ms, input_controller_ms, input_km_ms, input_both_ms, input_idle_ms, input_method_switches, input_source, input_devices FROM sessions";
public static Dictionary<string, object?> Parameters(SessionRow s)
{
@@ -35,10 +35,11 @@ internal static class SessionRowColumns
Parameters5(d, s);
Parameters6(d, s);
Parameters7(d, s);
Parameters8(d, s);
return d;
}
public static SessionRow Read(DbDataReader r) => Read7(Read6(Read5(Read4(Read3(Read2(Read1(Read0(r), r), r), r), r), r), r), r);
public static SessionRow Read(DbDataReader r) => Read8(Read7(Read6(Read5(Read4(Read3(Read2(Read1(Read0(r), r), r), r), r), r), r), r), r);
private static void Parameters0(Dictionary<string, object?> d, SessionRow s)
@@ -425,6 +426,33 @@ internal static class SessionRowColumns
DlssNrPct = D(r, "dlss_nr_pct"),
};
// Schema 0024 (beta.50, D155-D163): what the session was played with - read by the Agent from outside the game.
private static void Parameters8(Dictionary<string, object?> d, SessionRow s)
{
d["input_observed_ms"] = s.InputObservedMs;
d["input_foreground_ms"] = s.InputForegroundMs;
d["input_controller_ms"] = s.InputControllerMs;
d["input_km_ms"] = s.InputKeyboardMouseMs;
d["input_both_ms"] = s.InputBothMs;
d["input_idle_ms"] = s.InputIdleMs;
d["input_method_switches"] = s.InputMethodSwitches;
d["input_source"] = s.InputSource;
d["input_devices"] = s.InputDevicesJson;
}
private static SessionRow Read8(SessionRow row, DbDataReader r) => row with
{
InputObservedMs = L(r, "input_observed_ms"),
InputForegroundMs = L(r, "input_foreground_ms"),
InputControllerMs = L(r, "input_controller_ms"),
InputKeyboardMouseMs = L(r, "input_km_ms"),
InputBothMs = L(r, "input_both_ms"),
InputIdleMs = L(r, "input_idle_ms"),
InputMethodSwitches = I(r, "input_method_switches"),
InputSource = S(r, "input_source"),
InputDevicesJson = S(r, "input_devices"),
};
public static string ExitStatusText(ExitStatus status) => Vocabulary.ExitStatusText(status);
public static ExitStatus ParseExitStatus(string text) => text switch
@@ -33,7 +33,8 @@ public sealed class SqliteGameRepository : IGameRepository
+ "ac_exception_eligible, ac_exception_verdict, ac_exception_sessions, ac_exception_checked_rules_version, "
+ "ac_exception_checked_exe_size_bytes, ac_exception_checked_exe_mtime_ms, ac_exception_checked_block, ac_exception_at, "
+ "ac_exception_family, ac_exception_disclosure_version, ac_exception_exe_size_bytes, ac_exception_exe_mtime_ms, "
+ "ac_exception_lapsed_at, ac_exception_lapsed_reason, engine_version_source, ac_exception_trial_failed_at";
+ "ac_exception_lapsed_at, ac_exception_lapsed_reason, engine_version_source, ac_exception_trial_failed_at, "
+ "controller_support, controller_support_source, controller_support_at";
private const string _selectByPath = $"SELECT {_columns} FROM games WHERE exe_path = @path";
@@ -376,8 +377,11 @@ public sealed class SqliteGameRepository : IGameRepository
ExeFileVersion = SqliteReaders.String(r, 36),
ExeProductVersion = SqliteReaders.String(r, 37),
Libraries = LibraryVersionsJson.Parse(SqliteReaders.String(r, 38)),
AcException = ReadException(r) with { TrialFailedAt = At(SqliteReaders.Int64(r, 54)) }, // schema 0017, the last column
AcException = ReadException(r) with { TrialFailedAt = At(SqliteReaders.Int64(r, 54)) }, // schema 0017
EngineVersionSource = SqliteReaders.String(r, 53), // schema 0015
ControllerSupport = SqliteReaders.String(r, 55), // schema 0024, the last three columns
ControllerSupportSource = SqliteReaders.String(r, 56),
ControllerSupportAt = At(SqliteReaders.Int64(r, 57)),
};
/// <summary>Schema 0014's columns, 39 onwards in <see cref="_columns"/>' order.</summary>
@@ -53,8 +53,14 @@ public sealed class SqliteSessionRepository : ISessionRepository
// The fixed series; an advanced one (schema 0023) is a row of the same table under a name that starts with 'adv.'.
// In LIKE the dot is a literal and the only wildcard is the trailing %, so 'adv.%' is exactly that prefix.
// The input series (schema 0024) are rows of it too, under 'input.': a class's number and a controller's part are
// not sensor values, and they too mark a tick with nothing to say by NaN.
private const string _selectSensors =
"SELECT series, hz, codec, data FROM sensor_blobs WHERE session_id = @sessionId AND series NOT LIKE 'adv.%' ORDER BY series";
"SELECT series, hz, codec, data FROM sensor_blobs WHERE session_id = @sessionId AND series NOT LIKE 'adv.%' AND series NOT LIKE 'input.%' ORDER BY series";
private const string _selectInputSensors =
"SELECT series, hz, codec, data FROM sensor_blobs WHERE session_id = @sessionId AND (series = 't_ms' OR series LIKE 'input.%') "
+ "ORDER BY CASE WHEN series = 't_ms' THEN 0 ELSE 1 END, series";
private const string _selectAdvancedSensors =
"SELECT series, hz, codec, data FROM sensor_blobs WHERE session_id = @sessionId AND (series = 't_ms' OR series LIKE 'adv.%') "
@@ -217,6 +223,11 @@ public sealed class SqliteSessionRepository : ISessionRepository
c, new CommandDefinition(_selectAdvancedSensors, new { sessionId }, cancellationToken: token),
static r => new SensorBlob { Series = r.GetString(0), Hz = r.GetDouble(1), Codec = r.GetString(2), Data = (byte[])r.GetValue(3) }), ct);
public ValueTask<IReadOnlyList<SensorBlob>> FindInputSensorsAsync(long sessionId, CancellationToken ct = default) =>
_db.ReadAsync((c, token) => SqliteReaders.ReadAllAsync(
c, new CommandDefinition(_selectInputSensors, new { sessionId }, cancellationToken: token),
static r => new SensorBlob { Series = r.GetString(0), Hz = r.GetDouble(1), Codec = r.GetString(2), Data = (byte[])r.GetValue(3) }), ct);
public ValueTask<AdvancedSessionRow?> FindAdvancedAsync(long sessionId, CancellationToken ct = default) =>
_db.ReadAsync((c, token) => SqliteReaders.ReadOneAsync(
c, new CommandDefinition(_selectAdvanced, new { sessionId }, cancellationToken: token),
@@ -0,0 +1,286 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Buffers.Binary;
using FrameLedger.Application.Input;
using FrameLedger.Application.Telemetry;
using FrameLedger.Domain.Input;
namespace FrameLedger.Infrastructure.Recording;
/// <summary>
/// The input readings of a batch of telemetry samples, as one chunk of a <c>.partial</c> file (owner decisions
/// D155-D163, <c>06_DATA_MODEL</c> §<c>.partial</c>): so a session that is recovered after the Agent died has what it
/// was played with, as a finished one does.
/// </summary>
/// <remarks>
/// <para>
/// A chunk of its own, after the sensors' and the advanced one, for the reason <see cref="AdvancedSampleCodec"/> has
/// one: the sensor chunk's form is fixed, and a reading is attached to its sample by the QPC the sample already has. A
/// session recorded with the option off never writes one, and its file is byte for byte what it was.
/// </para>
/// <para>
/// <b>Each chunk stands alone</b>: every controller a sample counts is described in that sample - its maker, its two
/// USB ids, its connection - so a file cut anywhere still reads up to its last whole chunk.
/// </para>
/// <para>
/// Layout, little-endian: <c>u32 samples</c>, then per sample <c>i64 qpc</c>, seven <c>i32</c> (span, observed, in
/// front, controller, keyboard and mouse, both, no input), <c>u8 flags</c> (1 a virtual pad), the health (<c>u8</c>
/// answers: 1 raw input registered, 2 XInput there, 4 last input readable; six <c>i64</c> counts; <c>i32 faults</c>),
/// <c>u8 controllers</c> and per controller 23 bytes: <c>i32 id</c>, <c>u8 family</c>, <c>u16 vendor</c>,
/// <c>u16 product</c>, <c>u8 connection</c>, <c>u8 flags</c> (1 virtual, 2 one of XInput's pads, 4 connected, 8 a
/// battery), <c>u8 slot</c>, <c>i32 active ms</c>, <c>u8</c> battery state, scale and level, <c>u16 connects</c>,
/// <c>u16 disconnects</c>.
/// </para>
/// </remarks>
internal static class InputSampleCodec
{
private const int _sampleBytes = 8 + (7 * 4) + 1 + _healthBytes + 1;
private const int _healthBytes = 1 + (6 * 8) + 4;
private const int _deviceBytes = 23;
private const byte _virtualPad = 1;
private const byte _rawRegistered = 1;
private const byte _xinputAvailable = 2;
private const byte _lastInputAvailable = 4;
private const byte _deviceVirtual = 1;
private const byte _deviceXInput = 2;
private const byte _deviceConnected = 4;
private const byte _deviceBattery = 8;
/// <summary>The chunk for the samples of <paramref name="samples"/> that carry an input reading, or null when none does.</summary>
public static byte[]? Write(ReadOnlySpan<TelemetrySample> samples)
{
int carrying = 0;
int bytes = 4;
foreach (ref readonly TelemetrySample sample in samples)
{
if (sample.Input is { } reading)
{
carrying++;
bytes += _sampleBytes + (Devices(reading).Count * _deviceBytes);
}
}
if (carrying == 0)
{
return null;
}
byte[] payload = new byte[bytes];
BinaryPrimitives.WriteUInt32LittleEndian(payload, (uint)carrying);
int at = 4;
foreach (ref readonly TelemetrySample sample in samples)
{
if (sample.Input is { } reading)
{
at += WriteSample(payload.AsSpan(at), sample.QpcTicks, reading);
}
}
return payload;
}
/// <summary>The reading of each sample in a chunk, by the sample's QPC; false when the chunk is not well formed.</summary>
public static bool TryRead(ReadOnlySpan<byte> payload, List<(long Qpc, InputReading Reading)> into)
{
if (payload.Length < 4)
{
return false;
}
uint samples = BinaryPrimitives.ReadUInt32LittleEndian(payload);
int at = 4;
var read = new List<(long, InputReading)>();
for (uint s = 0; s < samples; s++)
{
if (payload.Length - at < _sampleBytes)
{
return false;
}
int devices = payload[at + _sampleBytes - 1];
if (payload.Length - at - _sampleBytes < devices * _deviceBytes)
{
return false;
}
read.Add(ReadSample(payload.Slice(at, _sampleBytes + (devices * _deviceBytes)), devices));
at += _sampleBytes + (devices * _deviceBytes);
}
if (at != payload.Length)
{
return false;
}
into.AddRange(read);
return true;
}
/// <summary>The controllers of a reading that can be written: each with its description, at most 255.</summary>
private static List<(InputDevice Device, InputDeviceReading Reading)> Devices(InputReading reading)
{
var devices = new List<(InputDevice, InputDeviceReading)>(reading.Devices.Count);
foreach (InputDeviceReading d in reading.Devices)
{
if (devices.Count < byte.MaxValue && reading.Table.FirstOrDefault(t => t.Id == d.DeviceId) is { } device)
{
devices.Add((device, d));
}
}
return devices;
}
private static int WriteSample(Span<byte> to, long qpc, InputReading reading)
{
BinaryPrimitives.WriteInt64LittleEndian(to, qpc);
int at = 8;
foreach (int ms in (ReadOnlySpan<int>)[reading.SpanMs, reading.ObservedMs, reading.ForegroundMs, reading.ControllerMs, reading.KeyboardMouseMs, reading.BothMs, reading.IdleMs])
{
BinaryPrimitives.WriteInt32LittleEndian(to[at..], ms);
at += 4;
}
to[at++] = reading.VirtualPad ? _virtualPad : (byte)0;
InputHealth h = reading.Health;
to[at++] = (byte)((h.RawInputRegistered ? _rawRegistered : 0) | (h.XInputAvailable ? _xinputAvailable : 0) | (h.LastInputAvailable ? _lastInputAvailable : 0));
foreach (long count in (ReadOnlySpan<long>)[h.RawReports, h.RawReportsUnread, h.XInputReads, h.XInputSilent, h.Slices, h.ThreadCpuMs])
{
BinaryPrimitives.WriteInt64LittleEndian(to[at..], count);
at += 8;
}
BinaryPrimitives.WriteInt32LittleEndian(to[at..], h.Faults);
at += 4;
List<(InputDevice Device, InputDeviceReading Reading)> devices = Devices(reading);
to[at++] = (byte)devices.Count;
foreach ((InputDevice device, InputDeviceReading d) in devices)
{
WriteDevice(to.Slice(at, _deviceBytes), device, d);
at += _deviceBytes;
}
return at;
}
private static void WriteDevice(Span<byte> to, InputDevice device, InputDeviceReading d)
{
BinaryPrimitives.WriteInt32LittleEndian(to, device.Id);
to[4] = (byte)device.Family;
BinaryPrimitives.WriteUInt16LittleEndian(to[5..], (ushort)Math.Clamp(device.VendorId, 0, ushort.MaxValue));
BinaryPrimitives.WriteUInt16LittleEndian(to[7..], (ushort)Math.Clamp(device.ProductId, 0, ushort.MaxValue));
to[9] = (byte)device.Connection;
to[10] = (byte)((device.IsVirtual ? _deviceVirtual : 0)
| (device.XInputSlot is not null ? _deviceXInput : 0)
| (d.Connected ? _deviceConnected : 0)
| (d.Battery is not null ? _deviceBattery : 0));
to[11] = (byte)Math.Clamp(device.XInputSlot ?? 0, 0, byte.MaxValue);
BinaryPrimitives.WriteInt32LittleEndian(to[12..], d.ActiveMs);
to[16] = (byte)(d.Battery?.State ?? BatteryState.Unknown);
to[17] = (byte)(d.Battery?.Scale ?? BatteryScale.None);
to[18] = (byte)Math.Clamp(d.Battery?.Level ?? 0, 0, byte.MaxValue);
BinaryPrimitives.WriteUInt16LittleEndian(to[19..], (ushort)Math.Clamp(d.Connects, 0, ushort.MaxValue));
BinaryPrimitives.WriteUInt16LittleEndian(to[21..], (ushort)Math.Clamp(d.Disconnects, 0, ushort.MaxValue));
}
private static (long Qpc, InputReading Reading) ReadSample(ReadOnlySpan<byte> from, int deviceCount)
{
long qpc = BinaryPrimitives.ReadInt64LittleEndian(from);
int at = 8;
Span<int> ms = stackalloc int[7];
for (int i = 0; i < ms.Length; i++)
{
ms[i] = BinaryPrimitives.ReadInt32LittleEndian(from[at..]);
at += 4;
}
bool virtualPad = (from[at++] & _virtualPad) != 0;
byte answers = from[at++];
Span<long> counts = stackalloc long[6];
for (int i = 0; i < counts.Length; i++)
{
counts[i] = BinaryPrimitives.ReadInt64LittleEndian(from[at..]);
at += 8;
}
int faults = BinaryPrimitives.ReadInt32LittleEndian(from[at..]);
at += 4 + 1;
var devices = new InputDeviceReading[deviceCount];
var table = new InputDevice[deviceCount];
for (int i = 0; i < deviceCount; i++)
{
(table[i], devices[i]) = ReadDevice(from.Slice(at, _deviceBytes));
at += _deviceBytes;
}
return (qpc, new InputReading
{
SpanMs = ms[0],
ObservedMs = ms[1],
ForegroundMs = ms[2],
ControllerMs = ms[3],
KeyboardMouseMs = ms[4],
BothMs = ms[5],
IdleMs = ms[6],
VirtualPad = virtualPad,
Devices = devices,
Table = table,
Health = new InputHealth
{
RawInputRegistered = (answers & _rawRegistered) != 0,
XInputAvailable = (answers & _xinputAvailable) != 0,
LastInputAvailable = (answers & _lastInputAvailable) != 0,
RawReports = counts[0],
RawReportsUnread = counts[1],
XInputReads = counts[2],
XInputSilent = counts[3],
Slices = counts[4],
ThreadCpuMs = counts[5],
Faults = faults,
},
});
}
private static (InputDevice Device, InputDeviceReading Reading) ReadDevice(ReadOnlySpan<byte> from)
{
byte flags = from[10];
int id = BinaryPrimitives.ReadInt32LittleEndian(from);
var device = new InputDevice
{
Id = id,
// A value this build has no name for was written by a later one: it reads as the word for "do not know".
Family = Known<ControllerFamily>(from[4]),
VendorId = BinaryPrimitives.ReadUInt16LittleEndian(from[5..]),
ProductId = BinaryPrimitives.ReadUInt16LittleEndian(from[7..]),
Connection = Known<ControllerConnection>(from[9]),
IsVirtual = (flags & _deviceVirtual) != 0,
XInputSlot = (flags & _deviceXInput) != 0 ? from[11] : null,
};
BatteryReading? battery = (flags & _deviceBattery) != 0
? new BatteryReading(Known<BatteryState>(from[16]), Known<BatteryScale>(from[17]), from[18])
: null;
return (device, new InputDeviceReading(
id,
Connected: (flags & _deviceConnected) != 0,
ActiveMs: BinaryPrimitives.ReadInt32LittleEndian(from[12..]),
battery,
Connects: BinaryPrimitives.ReadUInt16LittleEndian(from[19..]),
Disconnects: BinaryPrimitives.ReadUInt16LittleEndian(from[21..])));
}
private static T Known<T>(byte value)
where T : struct, Enum
{
T parsed = (T)Enum.ToObject(typeof(T), value);
return Enum.IsDefined(parsed) ? parsed : default;
}
}
@@ -49,4 +49,12 @@ internal enum PartialChunkType
/// last one wins.
/// </summary>
AdvancedContext = 10,
/// <summary>
/// The input readings of the samples of the <see cref="SensorsWide"/> chunk before it (owner decisions D155-D163):
/// <c>InputSampleCodec</c> - per sample its QPC, how its time in front divides between a controller, the keyboard
/// and mouse, both and neither, and each controller's part with what the controller is. Written only when a sample
/// of the batch carries one, so a session recorded with the option off has none.
/// </summary>
SensorsInput = 11,
}
@@ -6,6 +6,7 @@ using System.Runtime.InteropServices;
using System.Text;
using System.Text.Json;
using FrameLedger.Application.Advanced;
using FrameLedger.Application.Input;
using FrameLedger.Application.Recording;
using FrameLedger.Application.Telemetry;
using FrameLedger.Shared;
@@ -166,6 +167,7 @@ public static class PartialSessionFile
PartialChunkType.Touches => Int64s(payload, _touches),
PartialChunkType.SensorsAdvanced => AdvancedSensors(payload),
PartialChunkType.AdvancedContext => AdvancedContext(payload),
PartialChunkType.SensorsInput => InputSensors(payload),
// A type this build does not know, in a chunk whose length and checksum are right (TryReadChunk has
// verified both): a newer build wrote it, and it is passed over (owner decision D106, 2026-11-11).
@@ -302,6 +304,30 @@ public static class PartialSessionFile
return true;
}
/// <summary>The input readings of samples already read, attached as <see cref="AdvancedSensors"/> attaches its own: by QPC, to the last sample that has none yet.</summary>
private bool InputSensors(ReadOnlySpan<byte> payload)
{
var read = new List<(long Qpc, InputReading Reading)>();
if (!InputSampleCodec.TryRead(payload, read))
{
return false;
}
foreach ((long qpc, InputReading reading) in read)
{
for (int i = _sensors.Count - 1; i >= 0; i--)
{
if (_sensors[i].QpcTicks == qpc && _sensors[i].Input is null)
{
_sensors[i] = _sensors[i] with { Input = reading };
break;
}
}
}
return true;
}
private bool AdvancedContext(ReadOnlySpan<byte> payload)
{
_advancedContext = Encoding.UTF8.GetString(payload);
@@ -405,6 +431,12 @@ public static class PartialSessionFile
{
Append(PartialChunkType.SensorsAdvanced, advanced);
}
// And the input readings, the same way and for the same reason (D155-D163).
if (InputSampleCodec.Write(samples) is byte[] input)
{
Append(PartialChunkType.SensorsInput, input);
}
}
public void AppendAdvancedContext(string json)
@@ -1547,9 +1547,11 @@ bool MayObserve() noexcept {
// ---------------------------------------------------------------------------
// Which Streamline features were evaluated since the last present. Bits, not a
// last-writer-wins value: DLSS super-resolution and Ray Reconstruction run in
// the SAME frame (fl_shm.h retired FL_UPSCALER_RETIRED_RAY_RECONSTRUCTION for
// exactly that reason), so a single slot would drop one of them.
// last-writer-wins value: a game may evaluate more than one feature between two
// presents (several viewports, NIS after DLSS), so a single slot would drop one
// of them. NOT because DLSS super-resolution and Ray Reconstruction run in the
// same frame, as this said until 2026-11-14: RR runs INSTEAD of super-resolution
// (Streamline's guide; the measurement at the RR arm of the present detour).
// FRAME GENERATION NEEDS A COUNT, NOT A BIT, so the word is now split: features in
// the low byte, a saturating count of kFeatureDLSS_G evaluations above them
// (fl_sl_seen.h owns the encoding and is unit-tested without a hook). A bit
+6 -3
View File
@@ -176,9 +176,12 @@ enum FlUpscaler : uint8_t {
FL_UPSCALER_DLSS = 1,
// RETIRED, and the slot is reserved rather than reused. DLSS Ray
// Reconstruction was a value here, which made it MUTUALLY EXCLUSIVE with
// DLSS super-resolution -- but they run together, and 03_METRICS §RT/PT/RR
// makes RR an independent tri-state axis ("Yes / No if DLSS is active
// Reconstruction was a value here, which made it a technology BESIDE DLSS
// -- but it is DLSS: RR takes over the upscale, in DLSS's own quality mode
// (it does not run together with super-resolution, as this comment said
// until 2026-11-14: Streamline's guide has it "completely override" it, and
// Cyberpunk 2077 evaluated kFeatureDLSS_RR and never kFeatureDLSS). 03_METRICS
// §RT/PT/RR makes RR an independent tri-state axis ("Yes / No if DLSS is active
// without it"), which is also CLAUDE.md rule 7's trio. The record was the
// only place the two were conflated; 06_DATA_MODEL already stored them
// apart. RR is now FL_FEAT_RAY_RECONSTRUCTION in featureFlags.
@@ -455,13 +455,16 @@ public sealed class AdvancedPresenterTests
];
AdvancedPresenter.Metrics(series, []).Select(static m => m.Id).Should().BeEquivalentTo("nvapi.reflex.frame_report", "nvapi.reflex.gpu_times");
// The span between the driver's two GPU marks says what it includes, in every language (D143).
// The span between the driver's two GPU marks says what it is, in every language (D143) - and neither label says
// which of the two holds the other (D152): in Cyberpunk 2077 the driver's active time is the longer.
foreach (string culture in new[] { "", "vi", "ja" })
{
string render = Strings.ResourceManager.GetString(nameof(Strings.AdvToken_gpu_render), CultureInfo.GetCultureInfo(culture))!;
string active = Strings.ResourceManager.GetString(nameof(Strings.AdvToken_active_render), CultureInfo.GetCultureInfo(culture))!;
render.Should().Contain("(", "the label carries what the span includes");
render.Should().Contain("(", "the label carries what the span is");
render.Should().NotBe(active);
render.Should().NotContain("idle", "the span is not said to include the active time's idle time");
active.Should().NotContain("idle", "the active time is not said to be the span less its idle time");
}
}
@@ -143,6 +143,8 @@ public sealed class SeriesDigestTests
public ValueTask<IReadOnlyList<SensorBlob>> FindAdvancedSensorsAsync(long sessionId, CancellationToken ct = default) => inner.FindAdvancedSensorsAsync(sessionId, ct);
public ValueTask<IReadOnlyList<SensorBlob>> FindInputSensorsAsync(long sessionId, CancellationToken ct = default) => inner.FindInputSensorsAsync(sessionId, ct);
public ValueTask<AdvancedSessionRow?> FindAdvancedAsync(long sessionId, CancellationToken ct = default) => inner.FindAdvancedAsync(sessionId, ct);
public ValueTask<long> InsertFinalizedAsync(FinalizedSession session, CancellationToken ct = default) => inner.InsertFinalizedAsync(session, ct);
@@ -114,6 +114,20 @@ public sealed partial class AdvancedMetricCatalogTests
AdvancedMetricCatalog.Find("nvapi.reflex.mode")!.Reach.Should().Be(AdvancedReach.RefusedRoute);
AdvancedMetricCatalog.Find("sl.reflex.state")!.Reach.Should().Be(AdvancedReach.RefusedRoute);
_all.Where(static m => m.Reach == AdvancedReach.RefusedRoute).Should().OnlyContain(static m => !m.IsRead);
// Advanced metrics is closed (D154): what a game sets and asks through Streamline's feature functions is not
// read - seeing those calls would take handing the game a function of ours. Nothing is left "being studied".
string[] closed =
[
"sl.dlss.optimal_settings", "sl.dlss.vram_estimate", "sl.dlssg.options", "sl.dlssg.state", "sl.dlssg.frames_presented",
"sl.dlssg.vram_estimate", "sl.dlssd.options", "sl.nis.options", "sl.deepdvc.options", "sl.pcl.markers",
];
foreach (string id in closed)
{
AdvancedMetricCatalog.Find(id)!.Reach.Should().Be(AdvancedReach.RefusedRoute, id);
}
_all.Where(static m => m.Reach == AdvancedReach.Spike).Should().BeEmpty("no route is waiting for a spike");
}
[Fact]
@@ -29,4 +29,9 @@
<Using Include="Xunit" />
</ItemGroup>
<!-- Windows as the input reader asks it, with every answer written by the test (D157): shared with the other suites that drive the reader. -->
<ItemGroup>
<Compile Include="..\Shared\FakeInputBackend.cs" Link="Shared\FakeInputBackend.cs" />
</ItemGroup>
</Project>
@@ -0,0 +1,456 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FluentAssertions;
using FrameLedger.Application.Input;
using FrameLedger.Domain.Input;
using FrameLedger.Testing;
namespace FrameLedger.Application.Tests.Input;
/// <summary>
/// The input reader over a Windows whose every answer the test writes (<c>21_INPUT_DEVICES</c> §The reader): what a
/// controller is, when it is in use, what stands in for XInput where XInput says nothing, and what the reader says of
/// itself. <b>No device is behind any of it</b> - what a real controller answers is owner-only item 48.
/// </summary>
public sealed class InputReaderTests
{
private const nint _deviceA = 0x1001;
private const nint _deviceB = 0x1002;
private static readonly RawController _xboxBluetooth = new(ControllerCatalog.Microsoft, 0x0B13, XInputClass: true, ControllerConnection.Bluetooth);
private static readonly RawController _xboxUsb = new(ControllerCatalog.Microsoft, 0x0B12, XInputClass: true, ControllerConnection.Usb);
private static readonly RawController _steamPad = new(ControllerCatalog.Valve, ControllerCatalog.SteamVirtualGamepad, XInputClass: true, ControllerConnection.Usb);
private static readonly RawController _dualSenseUsb = new(ControllerCatalog.Sony, ControllerCatalog.DualSense, XInputClass: false, ControllerConnection.Usb);
private static readonly RawController _dualSenseBluetooth = _dualSenseUsb with { Connection = ControllerConnection.Bluetooth };
private static readonly RawController _dualShock = new(ControllerCatalog.Sony, 0x09CC, XInputClass: false, ControllerConnection.Usb);
private static readonly XInputReading _atRest = new(Packet: 7, 0, 0, 0, 0, 0, 0, 0);
private static readonly XInputReading _buttonDown = _atRest with { Packet = 8, Buttons = 0x1000 };
private static (InputReader Reader, FakeInputBackend Backend) Make()
{
var backend = new FakeInputBackend();
var reader = new InputReader(backend);
reader.Open();
return (reader, backend);
}
/// <summary>A USB report of a DualSense: at rest, or with a button down; the battery byte as given.</summary>
private static byte[] DualSenseUsb(bool pressed = false, byte status = 0x08)
{
byte[] report = new byte[DualSenseReport.UsbLength];
report[0] = 0x01;
report[1] = report[2] = report[3] = report[4] = 128;
report[8] = pressed ? (byte)0x28 : (byte)0x08;
report[53] = status;
return report;
}
[Fact]
public void WithNothingConnectedASliceHasNoControllerAndSaysWhatAnswered()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.CpuMs = 3;
InputSlice slice = reader.Slice(104);
backend.Opened.Should().BeTrue();
slice.ElapsedMs.Should().Be(104);
slice.ForegroundProcessId.Should().Be(42);
slice.Devices.Should().BeEmpty();
slice.KeyboardMouseActive.Should().BeFalse("the first slice has no time before it to compare with");
slice.VirtualPad.Should().BeFalse();
slice.Health.Should().Be(new InputHealth { RawInputRegistered = true, XInputAvailable = true, LastInputAvailable = true, Slices = 1, ThreadCpuMs = 3 });
}
[Fact]
public void TheOnlyDevicesRawInputIsRegisteredForAreJoysticksAndGamepads() =>
InputReader.RegisteredUsages.Should().Equal([(1, 4), (1, 5)], "usage 2 is a mouse and 6 a keyboard: neither is ever registered for (D158)");
/// <summary>XInput looks for a device each time it is asked about an empty slot, so an empty slot is asked about rarely.</summary>
[Fact]
public void AnEmptySlotIsAskedAboutOnceInTwentySlicesAndAConnectedOneEverySlice()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[1] = _atRest;
for (int i = 0; i < InputReader.ProbeEverySlices; i++)
{
reader.Slice(100);
}
backend.PadAsks.Should().Equal(1, InputReader.ProbeEverySlices, 1, 1);
reader.Slice(100);
backend.PadAsks.Should().Equal(2, InputReader.ProbeEverySlices + 1, 2, 2);
}
[Fact]
public void AnXInputPadIsAControllerOfTheXboxFamilyAndIsInUseWhenItsStateSaysSo()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[2] = _buttonDown;
InputSliceDevice pad = reader.Slice(100).Devices.Should().ContainSingle().Subject;
pad.Device.Should().Be(new InputDevice { Id = 3, Family = ControllerFamily.Xbox, XInputSlot = 2 });
pad.Device.Model.Should().BeNull("XInput does not say which device a pad is, and nothing else named it");
pad.Active.Should().BeTrue();
pad.Battery.Should().BeNull("XInput was not asked, or did not answer");
backend.Pads[2] = _atRest with { ThumbLx = 5000, ThumbLy = 5000 };
reader.Slice(100).Devices[0].Active.Should().BeFalse("a stick inside its dead zone is drift");
backend.Pads.Remove(2);
reader.Slice(100).Devices.Should().BeEmpty("XInput says it is not connected any more");
}
[Fact]
public void APadsBatteryAndWirelessFlagAreAskedForWhenItConnectsAndThenOnceInFiftySlices()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[0] = _atRest;
backend.Details[0] = new XInputDetails(Wireless: true, BatteryType: 3, BatteryLevel: 2);
InputSliceDevice pad = reader.Slice(100).Devices[0];
pad.Battery.Should().Be(new BatteryReading(BatteryState.Discharging, BatteryScale.FourLevels, 2));
pad.Device.Connection.Should().Be(ControllerConnection.Wireless);
backend.DetailAsks.Should().Be(1);
backend.Details[0] = new XInputDetails(Wireless: false, BatteryType: 1, BatteryLevel: 0);
for (int i = 0; i < InputReader.DetailsEverySlices - 1; i++)
{
reader.Slice(100);
}
backend.DetailAsks.Should().Be(1, "not yet");
pad = reader.Slice(100).Devices[0];
backend.DetailAsks.Should().Be(2);
pad.Battery.Should().Be(BatteryReading.Wired);
pad.Device.Connection.Should().Be(ControllerConnection.Usb, "the pad is wired now, and its description follows");
}
[Fact]
public void APadIsNamedWhenTheOnlyXInputClassDeviceThereCanBeIt()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[0] = _atRest;
backend.Details[0] = new XInputDetails(Wireless: true, BatteryType: 0, BatteryLevel: 0);
backend.Arrive(_deviceA, _xboxBluetooth);
InputSlice slice = reader.Slice(100);
InputSliceDevice pad = slice.Devices.Should().ContainSingle("the device raw input named IS the pad, not a second controller").Subject;
pad.Device.Should().Be(new InputDevice
{
Id = 1,
Family = ControllerFamily.Xbox,
VendorId = ControllerCatalog.Microsoft,
ProductId = 0x0B13,
Connection = ControllerConnection.Bluetooth,
XInputSlot = 0,
});
pad.Device.Model.Should().Be("Xbox Wireless Controller");
pad.Battery.Should().BeNull("type 0 is XInput's own word for nothing to show - a pad on Bluetooth is reported not to answer");
slice.VirtualPad.Should().BeFalse();
}
[Fact]
public void TwoDifferentXInputClassDevicesLeaveThePadsUnnamed()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[0] = _atRest;
backend.Pads[1] = _atRest;
backend.Arrive(_deviceA, _xboxBluetooth);
backend.Arrive(_deviceB, _xboxUsb);
IReadOnlyList<InputSliceDevice> pads = reader.Slice(100).Devices;
pads.Should().HaveCount(2);
pads.Should().OnlyContain(static p => p.Device.VendorId == 0 && p.Device.Family == ControllerFamily.Xbox, "which pad is which device cannot be told, and a wrong name is worse than none");
backend.Leave(_deviceB);
reader.Slice(100).Devices.Should().OnlyContain(static p => p.Device.ProductId == 0x0B13, "one device left: both pads can only be it");
}
[Fact]
public void SteamsVirtualGamepadMarksTheSliceAndNamesThePadsOnlyWhenNothingElseCan()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[0] = _atRest;
backend.Arrive(_deviceA, _steamPad);
InputSlice alone = reader.Slice(100);
alone.VirtualPad.Should().BeTrue();
alone.Devices.Should().ContainSingle().Which.Device.Should().BeEquivalentTo(new InputDevice
{
Id = 1,
Family = ControllerFamily.Xbox,
VendorId = ControllerCatalog.Valve,
ProductId = ControllerCatalog.SteamVirtualGamepad,
IsVirtual = true,
XInputSlot = 0,
});
backend.Arrive(_deviceB, _xboxUsb);
InputSlice beside = reader.Slice(100);
beside.VirtualPad.Should().BeTrue();
beside.Devices[0].Device.IsVirtual.Should().BeFalse("with a pad a player holds beside it, the pads take that pad's name");
beside.Devices[0].Device.ProductId.Should().Be(0x0B12);
}
[Fact]
public void ADualSenseIsReadFromItsOwnReports()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Arrive(_deviceA, _dualSenseUsb);
backend.Send(_deviceA, DualSenseUsb());
backend.Send(_deviceA, DualSenseUsb(pressed: true, status: 0x07));
backend.Send(_deviceA, DualSenseUsb(status: 0x06));
InputSlice slice = reader.Slice(100);
InputSliceDevice pad = slice.Devices.Should().ContainSingle().Subject;
pad.Device.Should().Be(new InputDevice { Id = 16, Family = ControllerFamily.PlayStation, VendorId = ControllerCatalog.Sony, ProductId = ControllerCatalog.DualSense, Connection = ControllerConnection.Usb });
pad.Active.Should().BeTrue("one of the slice's reports was a pad in use");
pad.Battery.Should().Be(new BatteryReading(BatteryState.Discharging, BatteryScale.Percent, 60), "the last report's");
slice.Health.RawReports.Should().Be(3);
slice.Health.RawReportsUnread.Should().Be(0);
InputSliceDevice later = reader.Slice(100).Devices[0];
later.Active.Should().BeFalse("no report in this slice said so");
later.Battery.Should().Be(pad.Battery, "the level a pad last reported is still its level");
}
[Fact]
public void ADualSenseOnBluetoothIsReadByItsShortReportUntilSomethingElseSwitchesIt()
{
(InputReader reader, FakeInputBackend backend) = Make();
byte[] shortReport = new byte[DualSenseReport.BluetoothLength];
shortReport[0] = 0x01;
shortReport[1] = shortReport[2] = shortReport[3] = shortReport[4] = 128;
shortReport[5] = 0x08;
shortReport[8] = 200;
backend.Arrive(_deviceA, _dualSenseBluetooth);
backend.Send(_deviceA, shortReport);
InputSliceDevice pad = reader.Slice(100).Devices[0];
pad.Active.Should().BeTrue();
pad.Battery.Should().BeNull("the short report has none, and the reader never asks the pad for the long one (D159)");
pad.Device.Connection.Should().Be(ControllerConnection.Bluetooth);
}
[Fact]
public void AReportTheParserCannotReadAndAReportOfADeviceNobodyNamedAreCountedAsNotRead()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Arrive(_deviceA, _dualSenseUsb);
backend.Send(_deviceA, 0x7F, 1, 2, 3);
backend.Send(_deviceB, DualSenseUsb(pressed: true));
InputSlice slice = reader.Slice(100);
slice.Health.RawReports.Should().Be(2);
slice.Health.RawReportsUnread.Should().Be(2);
slice.Devices.Should().ContainSingle().Which.Active.Should().BeFalse();
}
/// <summary>A controller whose layout this build does not know is listed, with its connections and drops, and is never "in use": a guess would be a made-up number.</summary>
[Fact]
public void AControllerWhoseReportsThisBuildCannotReadIsListedAndNeverInUse()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Arrive(_deviceA, _dualShock);
backend.Send(_deviceA, 1, 255, 255, 255, 255, 255, 255, 255);
InputSlice slice = reader.Slice(100);
InputSliceDevice pad = slice.Devices.Should().ContainSingle().Subject;
pad.Device.Family.Should().Be(ControllerFamily.PlayStation);
pad.Device.Model.Should().Be("DualShock 4");
pad.Active.Should().BeFalse();
pad.Battery.Should().BeNull();
slice.Health.RawReportsUnread.Should().Be(0, "it is not a report the reader set out to read");
}
[Fact]
public void AControllerKeepsItsNumberAcrossAReconnectAndASecondOfTheSameModelHasItsOwn()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Arrive(_deviceA, _dualSenseUsb);
backend.Arrive(_deviceA, _dualSenseUsb);
reader.Slice(100).Devices.Select(static d => d.Device.Id).Should().Equal([16], "Windows naming a device twice is one device");
backend.Leave(_deviceA);
reader.Slice(100).Devices.Should().BeEmpty();
backend.Arrive(_deviceB, _dualSenseUsb);
reader.Slice(100).Devices.Select(static d => d.Device.Id).Should().Equal([16], "the same model on the same connection, back under another handle");
backend.Arrive(_deviceA, _dualSenseUsb);
backend.Arrive(0x1003, _dualSenseBluetooth);
reader.Slice(100).Devices.Select(static d => d.Device.Id).Should().Equal(16, 17, 18);
backend.Leave(0x4242);
reader.Slice(100).Devices.Should().HaveCount(3, "a device nobody named leaving changes nothing");
}
[Fact]
public void TheKeyboardOrMouseWasInUseWhenWindowsTimeOfTheLastInputMoved()
{
(InputReader reader, FakeInputBackend backend) = Make();
reader.Slice(100).KeyboardMouseActive.Should().BeFalse();
reader.Slice(100).KeyboardMouseActive.Should().BeFalse("the time did not move");
backend.LastInputTick = 1090;
reader.Slice(100).KeyboardMouseActive.Should().BeTrue();
reader.Slice(100).KeyboardMouseActive.Should().BeFalse();
backend.LastInputTick = 900;
reader.Slice(100).KeyboardMouseActive.Should().BeTrue("Windows does not promise the time only goes forward; a different one is input all the same");
}
[Fact]
public void WhenWindowsDoesNotGiveTheTimeOfTheLastInputNothingIsSaidOfTheKeyboardAndTheHealthSaysSo()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.LastInputTick = null;
InputSlice slice = reader.Slice(100);
slice.KeyboardMouseActive.Should().BeFalse();
slice.Health.LastInputAvailable.Should().BeFalse();
slice.Health.Sources().Should().Be("rawinput+xinput");
}
[Fact]
public void WithoutXInputsLibraryNoPadIsAskedAbout()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.XInputAvailable = false;
backend.Pads[0] = _buttonDown;
InputSlice slice = reader.Slice(100);
slice.Devices.Should().BeEmpty();
slice.Health.XInputAvailable.Should().BeFalse();
backend.PadAsks.Should().Equal(0, 0, 0, 0);
}
/// <summary>
/// Microsoft's page for XInputEnable says the system switches a program's controller input by its window's focus.
/// Where that leaves the Agent with a pad that reads at rest for ever, the device's own reports stand in.
/// </summary>
[Fact]
public void WhereXInputSaysNothingWhileTheDevicesReportsChangeThePadCountsAsInUseAfterTenSuchSlices()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[1] = _atRest;
backend.Arrive(_deviceA, _xboxUsb);
backend.Send(_deviceA, 0, 1);
reader.Slice(100).Devices[0].Active.Should().BeFalse("the first report has nothing before it to differ from");
for (int i = 1; i < InputReader.SilentBeforeFallback; i++)
{
backend.Send(_deviceA, 0, (byte)(i + 1));
InputSlice early = reader.Slice(100);
early.Devices[0].Active.Should().BeFalse($"silent slice {i}: not enough of them yet");
early.Health.XInputSilent.Should().Be(i);
}
backend.Send(_deviceA, 0, 200);
InputSlice slice = reader.Slice(100);
slice.Health.XInputSilent.Should().Be(InputReader.SilentBeforeFallback);
slice.Devices.Should().ContainSingle().Which.Active.Should().BeTrue("XInput has never once been seen to move, and the device keeps saying something new");
backend.Send(_deviceA, 0, 200);
reader.Slice(100).Devices[0].Active.Should().BeFalse("the same report again is a pad at rest");
}
[Fact]
public void WhereXInputHasBeenSeenToMoveTheDevicesReportsNeverStandInForIt()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[0] = _atRest;
backend.Arrive(_deviceA, _xboxUsb);
backend.Send(_deviceA, 0, 1);
reader.Slice(100);
// XInput moves: it answers this program. The slice it moved in and the one after are not silent ones.
backend.Pads[0] = _atRest with { Packet = 9, ThumbLx = 3000 };
backend.Send(_deviceA, 0, 2);
reader.Slice(100).Health.XInputSilent.Should().Be(0);
backend.Send(_deviceA, 0, 3);
reader.Slice(100).Health.XInputSilent.Should().Be(0, "the report may be the one XInput already answered for");
// From here the device's reports change - a stick that drifts - and XInput's packet stays: counted, never used.
for (int i = 0; i < InputReader.SilentBeforeFallback + 5; i++)
{
backend.Send(_deviceA, 0, (byte)(10 + i));
reader.Slice(100).Devices[0].Active.Should().BeFalse("XInput is the one to say, and it says at rest");
}
reader.Slice(100).Health.XInputSilent.Should().Be(InputReader.SilentBeforeFallback + 5);
}
[Fact]
public void ASliceInWhichXInputSaysThePadIsInUseIsNotASilentOne()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.Pads[0] = _buttonDown;
backend.Arrive(_deviceA, _xboxUsb);
backend.Send(_deviceA, 0, 1);
reader.Slice(100);
backend.Send(_deviceA, 0, 2);
InputSlice slice = reader.Slice(100);
slice.Health.XInputSilent.Should().Be(0, "a button held gives the same packet number and a pad in use");
slice.Devices[0].Active.Should().BeTrue();
}
[Fact]
public void AFaultIsCountedAndANegativeElapsedTimeIsNone()
{
(InputReader reader, FakeInputBackend backend) = Make();
backend.ThrowOnDrain = true;
Action slice = () => reader.Slice(100);
slice.Should().Throw<InvalidOperationException>("the reader does not hide a failure; the hub counts it");
reader.Fault();
backend.ThrowOnDrain = false;
InputSlice after = reader.Slice(-5);
after.ElapsedMs.Should().Be(0);
after.Health.Faults.Should().Be(1);
after.Health.Slices.Should().Be(2);
}
[Fact]
public void ARegistrationWindowsRefusedIsSaidInEverySlice()
{
using var backend = new FakeInputBackend { Registers = false };
var reader = new InputReader(backend);
reader.Open();
InputHealth health = reader.Slice(100).Health;
health.RawInputRegistered.Should().BeFalse();
health.Sources().Should().Be("xinput+lastinput");
}
[Fact]
public void WhatADescriptionSaysOfADevice()
{
_steamPad.IsVirtual.Should().BeTrue();
_xboxUsb.IsVirtual.Should().BeFalse();
_dualSenseBluetooth.IsDualSense.Should().BeTrue();
_dualShock.IsDualSense.Should().BeFalse();
(_dualSenseUsb with { XInputClass = true }).IsDualSense.Should().BeFalse("presented through XInput, it is one of XInput's pads");
}
}
@@ -0,0 +1,267 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FluentAssertions;
using FrameLedger.Application.Input;
using FrameLedger.Domain.Input;
namespace FrameLedger.Application.Tests.Input;
/// <summary>
/// One session's slices added up into a reading a tick (<c>03_METRICS</c> §Input): only the time the game was in front
/// is classified, a pause is not observed, and a controller that was there at the start has not connected.
/// </summary>
public sealed class InputTickAccumulatorTests
{
private static readonly InputDevice _xbox = new() { Id = 1, Family = ControllerFamily.Xbox, XInputSlot = 0 };
private static readonly InputDevice _dualSense = new()
{
Id = 2,
Family = ControllerFamily.PlayStation,
VendorId = ControllerCatalog.Sony,
ProductId = ControllerCatalog.DualSense,
Connection = ControllerConnection.Usb,
};
private static InputSlice Slice(bool keyboardMouse = false, InputHealth? health = null, bool virtualPad = false, params InputSliceDevice[] devices) => new()
{
ElapsedMs = 100,
ForegroundProcessId = 42,
KeyboardMouseActive = keyboardMouse,
VirtualPad = virtualPad,
Devices = devices,
Health = health ?? new InputHealth(),
};
private static InputSliceDevice Pad(InputDevice device, bool active = false, BatteryReading? battery = null) => new(device, active, battery);
[Fact]
public void NothingAddedIsNothingToTake() =>
new InputTickAccumulator().Take().Should().BeNull();
[Fact]
public void EachSliceInFrontCountsForOneOfTheFourClasses()
{
var accumulator = new InputTickAccumulator();
accumulator.Add(Slice(devices: Pad(_xbox, active: true)), inFront: true, paused: false);
accumulator.Add(Slice(devices: Pad(_xbox, active: true)), inFront: true, paused: false);
accumulator.Add(Slice(keyboardMouse: true, devices: Pad(_xbox)), inFront: true, paused: false);
accumulator.Add(Slice(keyboardMouse: true, devices: Pad(_xbox, active: true)), inFront: true, paused: false);
accumulator.Add(Slice(devices: Pad(_xbox)), inFront: true, paused: false);
InputReading reading = accumulator.Take()!;
reading.SpanMs.Should().Be(500);
reading.ObservedMs.Should().Be(500);
reading.ForegroundMs.Should().Be(500);
reading.ControllerMs.Should().Be(200);
reading.KeyboardMouseMs.Should().Be(100);
reading.BothMs.Should().Be(100);
reading.IdleMs.Should().Be(100);
reading.Devices.Should().Equal(new InputDeviceReading(1, Connected: true, ActiveMs: 300, Battery: null, Connects: 0, Disconnects: 0));
reading.Table.Should().Equal(_xbox);
}
/// <summary>Typing in a browser beside the game is not the game played with the keyboard.</summary>
[Fact]
public void ASliceWithAnotherProgramInFrontIsNotClassified()
{
var accumulator = new InputTickAccumulator();
accumulator.Add(Slice(keyboardMouse: true, devices: Pad(_xbox, active: true)), inFront: false, paused: false);
accumulator.Add(Slice(devices: Pad(_xbox, active: true)), inFront: true, paused: false);
InputReading reading = accumulator.Take()!;
reading.SpanMs.Should().Be(200);
reading.ObservedMs.Should().Be(200);
reading.ForegroundMs.Should().Be(100);
reading.ControllerMs.Should().Be(100);
reading.KeyboardMouseMs.Should().Be(0);
reading.BothMs.Should().Be(0);
reading.Devices[0].ActiveMs.Should().Be(100, "a controller's time in use is time in the game");
}
[Fact]
public void APausedSliceIsNotObservedButItsTimeAndItsControllersAre()
{
var accumulator = new InputTickAccumulator();
accumulator.Add(Slice(devices: Pad(_xbox, active: true)), inFront: true, paused: true);
accumulator.Add(Slice(), inFront: true, paused: true);
InputReading reading = accumulator.Take()!;
reading.SpanMs.Should().Be(200, "a battery level is timed by the clock, paused or not");
reading.ObservedMs.Should().Be(0);
reading.ForegroundMs.Should().Be(0);
reading.ControllerMs.Should().Be(0);
reading.Devices.Should().Equal(new InputDeviceReading(1, Connected: false, ActiveMs: 0, Battery: null, Connects: 0, Disconnects: 1));
}
[Fact]
public void AControllerThereAtTheStartHasNotConnectedAndOneThatComesLaterHas()
{
var accumulator = new InputTickAccumulator();
accumulator.Add(Slice(devices: Pad(_xbox)), inFront: true, paused: false);
accumulator.Add(Slice(devices: [Pad(_xbox), Pad(_dualSense)]), inFront: true, paused: false);
InputReading reading = accumulator.Take()!;
reading.Devices.Should().Equal(
new InputDeviceReading(1, Connected: true, ActiveMs: 0, Battery: null, Connects: 0, Disconnects: 0),
new InputDeviceReading(2, Connected: true, ActiveMs: 0, Battery: null, Connects: 1, Disconnects: 0));
reading.Table.Should().Equal(_xbox, _dualSense);
}
[Fact]
public void ADropAndAReturnAreCountedEvenAcrossTicks()
{
var accumulator = new InputTickAccumulator();
accumulator.Add(Slice(devices: Pad(_dualSense)), inFront: true, paused: false);
accumulator.Add(Slice(), inFront: true, paused: false);
InputReading dropped = accumulator.Take()!;
accumulator.Add(Slice(), inFront: true, paused: false);
InputReading gone = accumulator.Take()!;
accumulator.Add(Slice(devices: Pad(_dualSense)), inFront: true, paused: false);
InputReading back = accumulator.Take()!;
dropped.Devices.Should().Equal(new InputDeviceReading(2, Connected: false, ActiveMs: 0, Battery: null, Connects: 0, Disconnects: 1));
gone.Devices.Should().BeEmpty("a controller that left is not carried into the next tick");
gone.Table.Should().BeEmpty();
back.Devices.Should().Equal(new InputDeviceReading(2, Connected: true, ActiveMs: 0, Battery: null, Connects: 1, Disconnects: 0));
}
[Fact]
public void ATakeStartsTheNextTickFromNothingButTheControllersStillConnected()
{
var accumulator = new InputTickAccumulator();
accumulator.Add(Slice(keyboardMouse: true, virtualPad: true, devices: Pad(_xbox, active: true)), inFront: true, paused: false);
accumulator.Take().Should().NotBeNull();
accumulator.Take().Should().BeNull("no slice since the last take");
accumulator.Add(Slice(devices: Pad(_xbox)), inFront: true, paused: false);
InputReading next = accumulator.Take()!;
next.SpanMs.Should().Be(100);
next.BothMs.Should().Be(0);
next.IdleMs.Should().Be(100);
next.VirtualPad.Should().BeFalse();
next.Devices.Should().Equal(new InputDeviceReading(1, Connected: true, ActiveMs: 0, Battery: null, Connects: 0, Disconnects: 0));
}
[Fact]
public void TheBatteryIsTheLastOneReportedAndASliceWithNoneKeepsIt()
{
var eighty = new BatteryReading(BatteryState.Discharging, BatteryScale.Percent, 80);
var seventy = new BatteryReading(BatteryState.Discharging, BatteryScale.Percent, 70);
var accumulator = new InputTickAccumulator();
accumulator.Add(Slice(devices: Pad(_dualSense, battery: eighty)), inFront: true, paused: false);
accumulator.Add(Slice(devices: Pad(_dualSense, battery: seventy)), inFront: true, paused: false);
accumulator.Add(Slice(devices: Pad(_dualSense)), inFront: true, paused: false);
accumulator.Take()!.Devices[0].Battery.Should().Be(seventy);
accumulator.Add(Slice(devices: Pad(_dualSense)), inFront: true, paused: false);
accumulator.Take()!.Devices[0].Battery.Should().Be(seventy, "the level a pad last reported is still its level");
}
[Fact]
public void AVirtualPadSeenInAnySliceMarksTheTick()
{
var accumulator = new InputTickAccumulator();
accumulator.Add(Slice(), inFront: true, paused: false);
accumulator.Add(Slice(virtualPad: true), inFront: false, paused: true);
accumulator.Take()!.VirtualPad.Should().BeTrue();
}
[Fact]
public void TheSameControllerNamedTwiceInASliceCountsOnce()
{
var accumulator = new InputTickAccumulator();
accumulator.Add(Slice(devices: [Pad(_xbox, active: true), Pad(_xbox, active: true)]), inFront: true, paused: false);
accumulator.Take()!.Devices.Should().Equal(new InputDeviceReading(1, Connected: true, ActiveMs: 100, Battery: null, Connects: 0, Disconnects: 0));
}
/// <summary>The reader runs before and after a session: a session's counts start where it began to read.</summary>
[Fact]
public void TheHealthIsWhatHappenedSinceTheSessionsFirstSlice()
{
var accumulator = new InputTickAccumulator();
accumulator.Add(Slice(health: new InputHealth { RawInputRegistered = true, RawReports = 1000, Slices = 50, ThreadCpuMs = 7, XInputReads = 40 }), inFront: true, paused: false);
accumulator.Add(Slice(health: new InputHealth { RawInputRegistered = true, XInputAvailable = true, RawReports = 1250, RawReportsUnread = 2, Slices = 51, ThreadCpuMs = 9, XInputReads = 44, XInputSilent = 1, Faults = 1 }), inFront: true, paused: false);
InputHealth health = accumulator.Take()!.Health;
health.Should().Be(new InputHealth
{
RawInputRegistered = true,
XInputAvailable = true,
RawReports = 250,
RawReportsUnread = 2,
Slices = 1,
ThreadCpuMs = 2,
XInputReads = 4,
XInputSilent = 1,
Faults = 1,
});
health.Sources().Should().Be("rawinput+xinput");
}
[Fact]
public void TheSourcesAreTheOnesThatAnswered()
{
new InputHealth().Sources().Should().BeEmpty();
new InputHealth { LastInputAvailable = true }.Sources().Should().Be("lastinput");
new InputHealth { RawInputRegistered = true, XInputAvailable = true, LastInputAvailable = true }.Sources().Should().Be("rawinput+xinput+lastinput");
}
[Fact]
public void ANegativeElapsedTimeCountsForNothing()
{
var accumulator = new InputTickAccumulator();
accumulator.Add(Slice(devices: Pad(_xbox, active: true)) with { ElapsedMs = -40 }, inFront: true, paused: false);
InputReading reading = accumulator.Take()!;
reading.SpanMs.Should().Be(0);
reading.ControllerMs.Should().Be(0);
}
[Fact]
public void TheStoredWordsReadBackAsWhatTheyWere()
{
foreach (ControllerFamily family in Enum.GetValues<ControllerFamily>())
{
InputNames.FamilyOf(InputNames.Of(family)).Should().Be(family);
}
foreach (ControllerConnection connection in Enum.GetValues<ControllerConnection>())
{
InputNames.ConnectionOf(InputNames.Of(connection)).Should().Be(connection);
}
foreach (BatteryState state in Enum.GetValues<BatteryState>())
{
InputNames.StateOf(InputNames.Of(state)).Should().Be(state);
}
foreach (BatteryScale scale in Enum.GetValues<BatteryScale>())
{
InputNames.ScaleOf(InputNames.Of(scale)).Should().Be(scale);
}
InputNames.FamilyOf("a word a later release wrote").Should().Be(ControllerFamily.Other);
InputNames.ConnectionOf(null).Should().Be(ControllerConnection.Unknown);
InputNames.StateOf(null).Should().Be(BatteryState.Unknown);
InputNames.ScaleOf(null).Should().Be(BatteryScale.None);
}
[Fact]
public void ADevicesModelIsItsCatalogName()
{
_dualSense.Model.Should().Be("DualSense");
_xbox.Model.Should().BeNull("one of XInput's pads that nothing named has no ids to look up");
}
}
@@ -130,7 +130,12 @@ internal sealed class FakeSessionRepository : ISessionRepository
public ValueTask<IReadOnlyList<SensorBlob>> FindSensorsAsync(long sessionId, CancellationToken ct = default) =>
ValueTask.FromResult<IReadOnlyList<SensorBlob>>(sessionId >= 1 && sessionId <= Stored.Count
? [.. Stored[(int)sessionId - 1].Sensors.Where(static s => !s.Series.StartsWith("adv.", StringComparison.Ordinal))]
? [.. Stored[(int)sessionId - 1].Sensors.Where(static s => !s.Series.StartsWith("adv.", StringComparison.Ordinal) && !s.Series.StartsWith("input.", StringComparison.Ordinal))]
: []);
public ValueTask<IReadOnlyList<SensorBlob>> FindInputSensorsAsync(long sessionId, CancellationToken ct = default) =>
ValueTask.FromResult<IReadOnlyList<SensorBlob>>(sessionId >= 1 && sessionId <= Stored.Count
? [.. Stored[(int)sessionId - 1].Sensors.Where(static s => string.Equals(s.Series, "t_ms", StringComparison.Ordinal) || s.Series.StartsWith("input.", StringComparison.Ordinal))]
: []);
public ValueTask<IReadOnlyList<SensorBlob>> FindAdvancedSensorsAsync(long sessionId, CancellationToken ct = default) =>
@@ -0,0 +1,319 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Text.Json;
using FluentAssertions;
using FrameLedger.Application.Input;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.Recording;
using FrameLedger.Application.Telemetry;
using FrameLedger.Domain.Input;
namespace FrameLedger.Application.Tests.Recording;
/// <summary>
/// What a session stores of its input readings (<c>03_METRICS</c> §Input): the totals, the controllers with their
/// batteries and makers, the series of the timeline - and nothing at all when no sample carries a reading. Every
/// reading here is made by hand: <b>none came from a controller</b>.
/// </summary>
public sealed class InputSessionBuilderTests
{
private static readonly InputDevice _xbox = new() { Id = 7, Family = ControllerFamily.Xbox, VendorId = ControllerCatalog.Microsoft, ProductId = 0x0B12, Connection = ControllerConnection.Usb, XInputSlot = 0 };
private static readonly InputDevice _steamPad = new() { Id = 8, Family = ControllerFamily.Xbox, VendorId = ControllerCatalog.Microsoft, ProductId = 0x0B12, Connection = ControllerConnection.Usb, XInputSlot = 1 };
private static readonly InputDevice _dualSense = new() { Id = 9, Family = ControllerFamily.PlayStation, VendorId = ControllerCatalog.Sony, ProductId = ControllerCatalog.DualSense, Connection = ControllerConnection.Bluetooth };
private static BatteryReading Percent(int level) => new(BatteryState.Discharging, BatteryScale.Percent, level);
/// <summary>A tick of one second with the game in front the whole time.</summary>
private static InputReading Tick(int controller = 0, int keyboardMouse = 0, int both = 0, bool virtualPad = false, InputHealth? health = null, params (InputDevice Device, InputDeviceReading Reading)[] devices) => new()
{
SpanMs = 1000,
ObservedMs = 1000,
ForegroundMs = 1000,
ControllerMs = controller,
KeyboardMouseMs = keyboardMouse,
BothMs = both,
IdleMs = 1000 - controller - keyboardMouse - both,
VirtualPad = virtualPad,
Devices = [.. devices.Select(static d => d.Reading)],
Table = [.. devices.Select(static d => d.Device)],
Health = health ?? new InputHealth { RawInputRegistered = true, XInputAvailable = true, LastInputAvailable = true },
};
private static (InputDevice, InputDeviceReading) Pad(InputDevice device, int activeMs = 0, bool connected = true, BatteryReading? battery = null, int connects = 0, int disconnects = 0) =>
(device, new InputDeviceReading(device.Id, connected, activeMs, battery, connects, disconnects));
private static List<TelemetrySample> Samples(params InputReading?[] readings)
{
List<TelemetrySample> samples = SessionFixtures.Sensors(readings.Length);
for (int i = 0; i < readings.Length; i++)
{
samples[i] = samples[i] with { Input = readings[i] };
}
return samples;
}
private static float[] Series(IReadOnlyList<SensorBlob> blobs, string name) => RawSeriesCodec.Floats(blobs.Single(b => string.Equals(b.Series, name, StringComparison.Ordinal)).Data);
[Fact]
public void WithNoReadingNothingIsStoredAtAll()
{
(IReadOnlyList<SensorBlob> blobs, InputSessionSummary? summary) = InputSessionBuilder.Build(SessionFixtures.Sensors(5), new RawSeriesCodec());
blobs.Should().BeEmpty();
summary.Should().BeNull("no summary is how a session says the option was off, or the terms not accepted yet");
}
[Fact]
public void TheTotalsAreTheTicksAddedUpAndTheSharesAreOfTheTimeInFront()
{
List<TelemetrySample> samples = Samples(
Tick(controller: 1000, devices: Pad(_xbox, 1000)),
Tick(controller: 600, keyboardMouse: 200, both: 100, devices: Pad(_xbox, 700)),
null,
Tick(keyboardMouse: 1000, devices: Pad(_xbox)),
Tick(devices: Pad(_xbox)) with { ObservedMs = 400, ForegroundMs = 0, IdleMs = 0 });
(_, InputSessionSummary? summary) = InputSessionBuilder.Build(samples, new RawSeriesCodec());
summary!.ObservedMs.Should().Be(3400);
summary.ForegroundMs.Should().Be(3000);
summary.ControllerMs.Should().Be(1600);
summary.KeyboardMouseMs.Should().Be(1200);
summary.BothMs.Should().Be(100);
summary.IdleMs.Should().Be(100);
(summary.ControllerMs + summary.KeyboardMouseMs + summary.BothMs + summary.IdleMs).Should().Be(summary.ForegroundMs);
summary.Source.Should().Be("rawinput+xinput+lastinput");
}
/// <summary>A tick played with both is no one thing; it does not end the run before it.</summary>
[Fact]
public void AMethodSwitchIsFromAControllerToTheKeyboardAndMouseOrBack()
{
List<TelemetrySample> samples = Samples(
Tick(controller: 1000),
Tick(),
Tick(controller: 900, both: 100),
Tick(controller: 1000),
Tick(keyboardMouse: 1000),
null,
Tick(keyboardMouse: 300),
Tick(controller: 400));
InputSessionBuilder.Build(samples, new RawSeriesCodec()).Summary!.MethodSwitches.Should().Be(2);
}
[Fact]
public void TheTimelineIsWhatEachTickWasMostlyPlayedWithAndNaNWhereThereIsNothingToSay()
{
List<TelemetrySample> samples = Samples(
Tick(controller: 800, keyboardMouse: 100),
Tick(keyboardMouse: 700),
Tick(both: 600),
Tick(),
null,
Tick() with { ForegroundMs = 0, IdleMs = 0 });
(IReadOnlyList<SensorBlob> blobs, _) = InputSessionBuilder.Build(samples, new RawSeriesCodec(), hz: 0.98);
float[] timeline = Series(blobs, InputSessionBuilder.ClassSeries);
timeline[..4].Should().Equal((float)InputClass.Controller, (float)InputClass.KeyboardMouse, (float)InputClass.Both, (float)InputClass.None);
float.IsNaN(timeline[4]).Should().BeTrue("a tick with no reading");
float.IsNaN(timeline[5]).Should().BeTrue("a tick with the game not in front");
blobs.Should().OnlyContain(static b => b.Hz == 0.98 && b.Series.StartsWith(InputSessionBuilder.SeriesPrefix, StringComparison.Ordinal));
}
[Fact]
public void AControllerHasItsTimesItsCountsAndItsSeries()
{
List<TelemetrySample> samples = Samples(
Tick(controller: 500, devices: Pad(_dualSense, 500, battery: Percent(80))),
Tick(controller: 1000, devices: Pad(_dualSense, 1000, battery: Percent(80))),
Tick(devices: Pad(_dualSense, connected: false, disconnects: 1)),
Tick(),
Tick(controller: 250, devices: Pad(_dualSense, 250, battery: Percent(70), connects: 1)) with { ForegroundMs = 500, IdleMs = 250 });
(IReadOnlyList<SensorBlob> blobs, InputSessionSummary? summary) = InputSessionBuilder.Build(samples, new RawSeriesCodec());
InputDevicesRecord record = InputDevicesRecord.Parse(summary!.DevicesJson)!;
InputDeviceRecord pad = record.Devices.Should().ContainSingle().Subject;
pad.Index.Should().Be(1);
pad.Family.Should().Be("playstation");
pad.Model.Should().Be("DualSense");
pad.Connection.Should().Be("bluetooth");
pad.XInputSlot.Should().BeNull();
pad.ConnectedMs.Should().Be(3000);
pad.ActiveMs.Should().Be(1750);
pad.Connects.Should().Be(1);
pad.Disconnects.Should().Be(1);
pad.Battery!.Scale.Should().Be("percent");
pad.Battery.States.Should().Equal(new InputBatteryStateRecord("discharging", 80, 2000), new InputBatteryStateRecord("discharging", 70, 1000));
pad.Battery.First.Should().Be(80);
pad.Battery.Last.Should().Be(70);
pad.Battery.DrainPercentPerHour.Should().BeNull("three seconds on battery say nothing about a rate");
float[] active = Series(blobs, InputSessionBuilder.ActiveSeries(1));
active[0].Should().Be(0.5f);
active[1].Should().Be(1f);
float.IsNaN(active[2]).Should().BeTrue("disconnected");
float.IsNaN(active[3]).Should().BeTrue("not there");
active[4].Should().Be(0.5f, "250 ms of the 500 the game was in front");
float[] battery = Series(blobs, InputSessionBuilder.BatterySeries(1));
battery[0].Should().Be(80f);
float.IsNaN(battery[2]).Should().BeTrue();
battery[4].Should().Be(70f);
}
[Fact]
public void AWiredPadHasABatteryStateAndNoBatterySeries()
{
List<TelemetrySample> samples = Samples(Tick(devices: Pad(_xbox, battery: BatteryReading.Wired)), Tick(devices: Pad(_xbox, battery: BatteryReading.Wired)));
(IReadOnlyList<SensorBlob> blobs, InputSessionSummary? summary) = InputSessionBuilder.Build(samples, new RawSeriesCodec());
InputBatteryRecord battery = InputDevicesRecord.Parse(summary!.DevicesJson)!.Devices[0].Battery!;
battery.Scale.Should().Be("none");
battery.States.Should().Equal(new InputBatteryStateRecord("wired", 0, 2000));
battery.First.Should().BeNull();
blobs.Select(static b => b.Series).Should().Equal(InputSessionBuilder.ClassSeries, InputSessionBuilder.ActiveSeries(1));
}
[Fact]
public void EachMakerHasItsShareAndAChangeOfMakerIsCounted()
{
var ticks = new List<InputReading?>();
for (int i = 0; i < 6; i++)
{
ticks.Add(Tick(controller: 1000, devices: [Pad(_xbox, 1000), Pad(_dualSense)]));
}
ticks.Add(Tick(controller: 1000, devices: [Pad(_xbox, 500), Pad(_dualSense, 500)]));
for (int i = 0; i < 2; i++)
{
ticks.Add(Tick(controller: 1000, devices: [Pad(_xbox), Pad(_dualSense, 1000)]));
}
ticks.Add(Tick(controller: 1000, devices: [Pad(_xbox, 1000), Pad(_dualSense)]));
InputDevicesRecord record = InputDevicesRecord.Parse(InputSessionBuilder.Build(Samples([.. ticks]), new RawSeriesCodec()).Summary!.DevicesJson)!;
record.Devices.Select(static d => d.Family).Should().Equal("xbox", "playstation");
record.Families.Should().Equal(new InputFamilyRecord("xbox", 7500, 0.75), new InputFamilyRecord("playstation", 2500, 0.25));
record.FamilySwitches.Should().Be(2, "to the DualSense and back; the tick with both in use is no one maker's");
record.VirtualPad.Should().BeFalse();
record.Devices.Should().OnlyContain(static d => !d.Remapped);
}
/// <summary>
/// Steam Input in front of a DualSense: Windows shows the DualSense and an Xbox pad that moves with it. The Xbox
/// pad is the DualSense, and the session has one controller - Sony's.
/// </summary>
[Fact]
public void AnXInputPadThatMovesWithAnotherControllerIsThatController()
{
var ticks = new List<InputReading?>();
for (int i = 0; i < 12; i++)
{
ticks.Add(Tick(controller: 1000, virtualPad: true, devices: [Pad(_dualSense, 1000), Pad(_xbox, 950)]));
}
InputDevicesRecord record = InputDevicesRecord.Parse(InputSessionBuilder.Build(Samples([.. ticks]), new RawSeriesCodec()).Summary!.DevicesJson)!;
InputDeviceRecord pad = record.Devices.Should().ContainSingle().Subject;
pad.Family.Should().Be("playstation");
pad.Remapped.Should().BeTrue();
record.Families.Should().Equal(new InputFamilyRecord("playstation", 12_000, 1));
record.FamilySwitches.Should().Be(0);
record.VirtualPad.Should().BeTrue();
}
/// <summary>Two of XInput's pads that move together are one only where Steam's virtual gamepad was seen: two players pressing in step are two players.</summary>
[Fact]
public void TwoXInputPadsThatMoveTogetherAreOneOnlyWhereSteamsPadWasSeen()
{
InputReading?[] Session(bool virtualPad) => [.. Enumerable.Range(0, 12).Select(_ => Tick(controller: 1000, virtualPad: virtualPad, devices: [Pad(_xbox, 1000), Pad(_steamPad, 1000)]))];
InputDevicesRecord with = InputDevicesRecord.Parse(InputSessionBuilder.Build(Samples(Session(virtualPad: true)), new RawSeriesCodec()).Summary!.DevicesJson)!;
InputDevicesRecord without = InputDevicesRecord.Parse(InputSessionBuilder.Build(Samples(Session(virtualPad: false)), new RawSeriesCodec()).Summary!.DevicesJson)!;
InputDeviceRecord kept = with.Devices.Should().ContainSingle().Subject;
kept.XInputSlot.Should().Be(0, "the higher of the two is the one folded");
kept.Remapped.Should().BeTrue();
without.Devices.Should().HaveCount(2);
without.Devices.Should().OnlyContain(static d => !d.Remapped);
}
[Fact]
public void OnlyTheFirstEightControllersHaveSeriesAndAllAreListed()
{
(InputDevice, InputDeviceReading)[] pads = [.. Enumerable.Range(0, InputSessionBuilder.MaxDevices + 2)
.Select(static i => Pad(new InputDevice { Id = 100 + i, Family = ControllerFamily.Other, VendorId = 0x1234, ProductId = i }))];
(IReadOnlyList<SensorBlob> blobs, InputSessionSummary? summary) = InputSessionBuilder.Build(Samples(Tick(devices: pads)), new RawSeriesCodec());
InputDevicesRecord.Parse(summary!.DevicesJson)!.Devices.Should().HaveCount(InputSessionBuilder.MaxDevices + 2);
blobs.Should().HaveCount(1 + InputSessionBuilder.MaxDevices);
}
[Fact]
public void TheHealthStoredIsTheLastReadingsAndTheSourceNamesWhatAnswered()
{
var early = new InputHealth { RawInputRegistered = true, RawReports = 10, Slices = 10 };
var late = new InputHealth { RawInputRegistered = true, LastInputAvailable = true, RawReports = 2500, Slices = 30, XInputSilent = 4, ThreadCpuMs = 12 };
InputSessionSummary summary = InputSessionBuilder.Build(Samples(Tick(health: early), null, Tick(health: late), null), new RawSeriesCodec()).Summary!;
summary.Source.Should().Be("rawinput+lastinput");
InputDevicesRecord.Parse(summary.DevicesJson)!.Health.Should().Be(late);
}
/// <summary>
/// Nothing that could name a person or a device is stored: the JSON has the keys listed here and no other, so a
/// serial number, an address or a path would need a key added to this test first.
/// </summary>
[Fact]
public void TheStoredJsonHasNoKeyThatCouldCarryASerialNumberAnAddressOrAPath()
{
string json = InputSessionBuilder.Build(Samples(Tick(controller: 1000, devices: Pad(_dualSense, 1000, battery: Percent(50)))), new RawSeriesCodec()).Summary!.DevicesJson;
var keys = new SortedSet<string>(StringComparer.Ordinal);
Collect(JsonElement.Parse(json), keys);
keys.Should().Equal(
"ActiveMs", "Battery", "ConnectedMs", "Connection", "Connects", "Devices", "Disconnects", "DrainPercentPerHour", "Families", "Family",
"FamilySwitches", "Faults", "First", "Health", "Index", "Last", "LastInputAvailable", "Level", "Model", "Ms", "ProductId", "RawInputRegistered",
"RawReports", "RawReportsUnread", "Remapped", "Scale", "Share", "Slices", "State", "States", "ThreadCpuMs", "V", "VendorId", "Virtual",
"VirtualPad", "XInputAvailable", "XInputReads", "XInputSilent", "XInputSlot");
json.Should().NotContainAny("\\\\", "HID#", "VID_", "serial", "Serial");
}
[Fact]
public void AColumnThatIsEmptyOrNotJsonReadsAsNothing()
{
InputDevicesRecord.Parse(null).Should().BeNull();
InputDevicesRecord.Parse(" ").Should().BeNull();
InputDevicesRecord.Parse("{ not json").Should().BeNull();
InputDevicesRecord.Parse("{}")!.Devices.Should().BeEmpty();
}
private static void Collect(JsonElement element, SortedSet<string> keys)
{
if (element.ValueKind == JsonValueKind.Object)
{
foreach (JsonProperty property in element.EnumerateObject())
{
keys.Add(property.Name);
Collect(property.Value, keys);
}
}
else if (element.ValueKind == JsonValueKind.Array)
{
foreach (JsonElement item in element.EnumerateArray())
{
Collect(item, keys);
}
}
}
}
@@ -3,8 +3,10 @@
using System.Reflection;
using FluentAssertions;
using FrameLedger.Application.Input;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.Recording;
using FrameLedger.Domain.Input;
using FrameLedger.Domain.Sessions;
using FrameLedger.Shared;
@@ -218,6 +220,71 @@ public sealed class SessionFinalizerTests
SensorSeriesStats.Parse("{not json").Should().BeEmpty("text this build cannot read is no statistics, never a throw into the UI");
}
/// <summary>
/// What a session was played with (D155-D163) is read by the Agent from outside the game, so a session that was not
/// hooked has it as a hooked one does: the totals on the row, the series beside the sensors'.
/// </summary>
[Theory]
[InlineData(false)]
[InlineData(true)]
public void BothTiersStoreWhatTheSessionWasPlayedWith(bool hooked)
{
(SessionFinalizer finalizer, _) = Make();
List<Application.Telemetry.TelemetrySample> sensors = SessionFixtures.Sensors(3);
var pad = new InputDevice { Id = 1, Family = ControllerFamily.Xbox, XInputSlot = 0 };
sensors[0] = sensors[0] with { Input = Played(controller: 1000, pad) };
sensors[2] = sensors[2] with { Input = Played(controller: 0, pad) with { KeyboardMouseMs = 700, IdleMs = 300 } };
FinalizedSession built = finalizer.Build(hooked
? new FinalizeInput { Skeleton = SessionFixtures.Skeleton(), Hooked = SessionFixtures.Hooked(SessionFixtures.Stream(600, FlMeasured.None)), Sensors = sensors }
: new FinalizeInput { Skeleton = SessionFixtures.Skeleton(tier: CaptureTier.NotHooked), Sensors = sensors });
built.Row.Tier.Should().Be(hooked ? CaptureTier.Hooked : CaptureTier.NotHooked);
built.Row.InputObservedMs.Should().Be(2000);
built.Row.InputForegroundMs.Should().Be(2000);
built.Row.InputControllerMs.Should().Be(1000);
built.Row.InputKeyboardMouseMs.Should().Be(700);
built.Row.InputBothMs.Should().Be(0);
built.Row.InputIdleMs.Should().Be(300);
built.Row.InputMethodSwitches.Should().Be(1);
built.Row.InputSource.Should().Be("rawinput+lastinput");
built.Row.InputSharePercent(built.Row.InputControllerMs).Should().Be(50);
InputDevicesRecord.Parse(built.Row.InputDevicesJson)!.Devices.Should().ContainSingle().Which.XInputSlot.Should().Be(0);
built.Sensors.Select(static s => s.Series).Should().Contain(["t_ms", "input.class", "input.dev.1.active"]);
float[] timeline = RawSeriesCodec.Floats(built.Sensors.Single(static s => string.Equals(s.Series, "input.class", StringComparison.Ordinal)).Data);
timeline[0].Should().Be((float)InputClass.Controller);
float.IsNaN(timeline[1]).Should().BeTrue("the tick the reader took no slice in");
timeline[2].Should().Be((float)InputClass.KeyboardMouse);
}
[Fact]
public void ASessionWithNoInputReadingKeepsEveryInputColumnNullAndStoresNoInputSeries()
{
(SessionFinalizer finalizer, _) = Make();
FinalizedSession built = finalizer.Build(new FinalizeInput { Skeleton = SessionFixtures.Skeleton(tier: CaptureTier.NotHooked), Sensors = SessionFixtures.Sensors(3) });
built.Row.InputObservedMs.Should().BeNull("the option was off, or the terms that describe the reading were not accepted yet: N/A, never a zero");
built.Row.InputForegroundMs.Should().BeNull();
built.Row.InputControllerMs.Should().BeNull();
built.Row.InputMethodSwitches.Should().BeNull();
built.Row.InputSource.Should().BeNull();
built.Row.InputDevicesJson.Should().BeNull();
built.Sensors.Should().NotContain(static s => s.Series.StartsWith("input.", StringComparison.Ordinal));
}
private static InputReading Played(int controller, InputDevice pad) => new()
{
SpanMs = 1000,
ObservedMs = 1000,
ForegroundMs = 1000,
ControllerMs = controller,
IdleMs = 1000 - controller,
Devices = [new InputDeviceReading(pad.Id, Connected: true, ActiveMs: controller, Battery: null, Connects: 0, Disconnects: 0)],
Table = [pad],
Health = new InputHealth { RawInputRegistered = true, LastInputAvailable = true },
};
[Fact]
public async Task TooShortIsDiscardedAndNothingIsWritten()
{
@@ -0,0 +1,170 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FluentAssertions;
using FrameLedger.Domain.Input;
namespace FrameLedger.Domain.Tests.Input;
/// <summary>
/// Who a controller is by its two USB ids, what XInput's words mean, and a battery's readings added up over a session
/// (<c>03_METRICS</c> §Input).
/// </summary>
public sealed class ControllerAndBatteryTests
{
private static BatteryReading Percent(int level, BatteryState state = BatteryState.Discharging) => new(state, BatteryScale.Percent, level);
[Theory]
[InlineData(ControllerCatalog.Microsoft, false, ControllerFamily.Xbox)]
[InlineData(ControllerCatalog.Sony, false, ControllerFamily.PlayStation)]
[InlineData(ControllerCatalog.Nintendo, false, ControllerFamily.Nintendo)]
[InlineData(0x2DC8, true, ControllerFamily.Xbox)] // another maker's pad that Windows presents through XInput
[InlineData(0x2DC8, false, ControllerFamily.Other)]
[InlineData(0, true, ControllerFamily.Xbox)] // one of XInput's pads that nothing named
public void AFamilyIsTheMakerOrWhatWindowsPresentsThePadAs(int vendor, bool xinput, ControllerFamily family) =>
ControllerCatalog.FamilyOf(vendor, xinput).Should().Be(family);
[Fact]
public void AModelHasANameOnlyWhereThisBuildListsIt()
{
ControllerCatalog.ModelOf(ControllerCatalog.Sony, ControllerCatalog.DualSense).Should().Be("DualSense");
ControllerCatalog.ModelOf(ControllerCatalog.Sony, ControllerCatalog.DualSenseEdge).Should().Be("DualSense Edge");
ControllerCatalog.ModelOf(ControllerCatalog.Microsoft, 0x0B12).Should().Be("Xbox Wireless Controller");
ControllerCatalog.ModelOf(ControllerCatalog.Microsoft, 0xFFFF).Should().BeNull("a wrong name would be worse than none");
ControllerCatalog.ModelOf(0, 0).Should().BeNull();
}
[Fact]
public void SteamsVirtualGamepadIsAPadAProgramPresents()
{
ControllerCatalog.IsVirtual(ControllerCatalog.Valve, ControllerCatalog.SteamVirtualGamepad).Should().BeTrue();
ControllerCatalog.IsVirtual(ControllerCatalog.Valve, 0x1142).Should().BeFalse("a Steam Controller is one a player holds");
ControllerCatalog.IsVirtual(ControllerCatalog.Microsoft, 0x028E).Should().BeFalse();
}
[Fact]
public void OnlySonysTwoDualSensesAreReadByTheDualSenseParser()
{
ControllerCatalog.IsDualSense(ControllerCatalog.Sony, ControllerCatalog.DualSense).Should().BeTrue();
ControllerCatalog.IsDualSense(ControllerCatalog.Sony, ControllerCatalog.DualSenseEdge).Should().BeTrue();
ControllerCatalog.IsDualSense(ControllerCatalog.Sony, 0x09CC).Should().BeFalse("a DualShock 4 has another layout");
ControllerCatalog.IsDualSense(ControllerCatalog.Microsoft, ControllerCatalog.DualSense).Should().BeFalse();
}
[Fact]
public void AnXInputPadAtRestIsNotInUse() =>
XInputPad.IsActive(0, 0, 0, 0, 0, 0, 0).Should().BeFalse();
[Theory]
[InlineData(0x1000, 0, 0, 0, 0, 0, 0)] // a button
[InlineData(0, 31, 0, 0, 0, 0, 0)] // the left trigger past the threshold
[InlineData(0, 0, 255, 0, 0, 0, 0)] // the right trigger
[InlineData(0, 0, 0, 7850, 0, 0, 0)] // the left stick just outside its dead zone
[InlineData(0, 0, 0, 0, -32768, 0, 0)] // held fully down
[InlineData(0, 0, 0, 0, 0, 6200, 6200)] // the right stick, diagonally outside
public void AButtonATriggerOrAStickOutsideItsDeadZoneIsAPadInUse(int buttons, int lt, int rt, int lx, int ly, int rx, int ry) =>
XInputPad.IsActive(buttons, lt, rt, lx, ly, rx, ry).Should().BeTrue();
[Theory]
[InlineData(0, 30, 30, 0, 0, 0, 0)] // triggers at the threshold
[InlineData(0, 0, 0, 7849, 0, 0, 0)] // on the edge of the left dead zone
[InlineData(0, 0, 0, 5000, 5000, 0, 0)] // drift
[InlineData(0, 0, 0, 0, 0, 8689, 0)] // on the edge of the right dead zone
public void DriftInsideADeadZoneIsNotUse(int buttons, int lt, int rt, int lx, int ly, int rx, int ry) =>
XInputPad.IsActive(buttons, lt, rt, lx, ly, rx, ry).Should().BeFalse();
[Fact]
public void XInputsBatteryWordsAreAWiredPadFourLevelsOrNothing()
{
XInputPad.Battery(type: 1, level: 0).Should().Be(BatteryReading.Wired);
XInputPad.Battery(type: 2, level: 0).Should().Be(new BatteryReading(BatteryState.Discharging, BatteryScale.FourLevels, 0));
XInputPad.Battery(type: 3, level: 3).Should().Be(new BatteryReading(BatteryState.Discharging, BatteryScale.FourLevels, 3));
XInputPad.Battery(type: 3, level: 9).Should().Be(new BatteryReading(BatteryState.Discharging, BatteryScale.FourLevels, 3), "a level past full is full");
XInputPad.Battery(type: 0, level: 0).Should().BeNull("disconnected");
XInputPad.Battery(type: 0xFF, level: 2).Should().BeNull("a type XInput itself calls unknown has nothing to show");
}
[Fact]
public void LowIsEmptyOrLowOrTenPerCentAndOnlyOnBattery()
{
new BatteryReading(BatteryState.Discharging, BatteryScale.FourLevels, 1).IsLow.Should().BeTrue();
new BatteryReading(BatteryState.Discharging, BatteryScale.FourLevels, 2).IsLow.Should().BeFalse();
Percent(10).IsLow.Should().BeTrue();
Percent(20).IsLow.Should().BeFalse();
Percent(10, BatteryState.Unknown).IsLow.Should().BeTrue("a level with no state is still a level");
Percent(10, BatteryState.Charging).IsLow.Should().BeFalse("it is on power");
BatteryReading.Wired.IsLow.Should().BeFalse();
}
[Fact]
public void TheLongestStateIsTheOneReadForTheMostTime()
{
var tally = new BatteryTally();
tally.Any.Should().BeFalse();
tally.Add(Percent(80), 600_000);
tally.Add(Percent(70), 1_500_000);
tally.Add(Percent(70), 300_000);
tally.Add(Percent(60), 200_000);
tally.Add(Percent(60), -5);
BatterySummary summary = tally.Summary();
tally.Any.Should().BeTrue();
summary.Longest.Should().Be(new BatteryStateTime(BatteryState.Discharging, BatteryScale.Percent, 70, 1_800_000));
summary.States.Select(static s => s.Level).Should().Equal(70, 80, 60);
summary.First.Should().Be(Percent(80));
summary.Last.Should().Be(Percent(60));
}
[Fact]
public void AnEmptyTallyHasNoLongestState()
{
BatterySummary summary = new BatteryTally().Summary();
summary.Longest.Should().BeNull();
summary.First.Should().BeNull();
summary.DrainPercentPerHour.Should().BeNull();
}
[Fact]
public void TheDrainIsTheFallOverTheTimeOnBattery()
{
var tally = new BatteryTally();
tally.Add(Percent(90), 1_800_000);
tally.Add(Percent(80), 1_800_000);
tally.Add(Percent(70), 1_800_000);
// Twenty points in an hour and a half.
tally.Summary().DrainPercentPerHour.Should().Be(13.3);
}
[Fact]
public void NoDrainIsWorkedOutFromTooLittleTimeARiseAChargeOrFourLevels()
{
var brief = new BatteryTally();
brief.Add(Percent(90), 200_000);
brief.Add(Percent(80), 200_000);
brief.Summary().DrainPercentPerHour.Should().BeNull("under ten minutes, a level that moves in tens says nothing");
var steady = new BatteryTally();
steady.Add(Percent(80), 3_600_000);
steady.Summary().DrainPercentPerHour.Should().BeNull("it did not fall");
var charged = new BatteryTally();
charged.Add(Percent(40), 1_200_000);
charged.Add(Percent(50, BatteryState.Charging), 1_200_000);
charged.Add(Percent(30), 1_200_000);
charged.Summary().DrainPercentPerHour.Should().BeNull("it was put on power in between: the fall is not one run");
var chargedFirst = new BatteryTally();
chargedFirst.Add(Percent(100, BatteryState.Full), 600_000);
chargedFirst.Add(Percent(100), 1_800_000);
chargedFirst.Add(Percent(80), 1_800_000);
chargedFirst.Summary().DrainPercentPerHour.Should().Be(20, "being on power before it began to run down breaks nothing");
var levels = new BatteryTally();
levels.Add(new BatteryReading(BatteryState.Discharging, BatteryScale.FourLevels, 3), 3_600_000);
levels.Add(new BatteryReading(BatteryState.Discharging, BatteryScale.FourLevels, 1), 3_600_000);
levels.Summary().DrainPercentPerHour.Should().BeNull("four words are not per cent");
}
}
@@ -0,0 +1,173 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FluentAssertions;
using FrameLedger.Domain.Input;
namespace FrameLedger.Domain.Tests.Input;
/// <summary>
/// The three input reports of a DualSense (<c>21_INPUT_DEVICES</c> §DualSense), as bytes written here from the layout:
/// <b>none of them came from a pad</b>. They hold what the reader takes from a report - in use or not, and the battery
/// where the report has one - and that a Bluetooth pad's short report is not read as a USB one.
/// </summary>
public sealed class DualSenseReportTests
{
private const int _hatNeutral = 0x08;
/// <summary>A USB report of a pad at rest: sticks centred, hat neutral, nothing down, the battery byte as given.</summary>
private static byte[] Usb(byte status = 0x08)
{
byte[] report = new byte[DualSenseReport.UsbLength];
report[0] = 0x01;
report[1] = report[2] = report[3] = report[4] = 128;
report[8] = _hatNeutral;
report[53] = status;
return report;
}
/// <summary>The same body behind a Bluetooth extended report's two leading bytes.</summary>
private static byte[] BluetoothFull(byte status = 0x08)
{
byte[] report = new byte[DualSenseReport.BluetoothLength];
report[0] = 0x31;
Usb(status).AsSpan(1).CopyTo(report.AsSpan(2));
return report;
}
/// <summary>The short Bluetooth report, padded to the device's longest report as Windows hands it over.</summary>
private static byte[] BluetoothShort()
{
byte[] report = new byte[DualSenseReport.BluetoothLength];
report[0] = 0x01;
report[1] = report[2] = report[3] = report[4] = 128;
report[5] = _hatNeutral;
return report;
}
[Fact]
public void APadAtRestIsNotInUse()
{
DualSenseReport.TryRead(Usb(), bluetooth: false, out bool active, out _).Should().BeTrue();
active.Should().BeFalse();
}
[Theory]
[InlineData(1, 200)] // left stick, x
[InlineData(2, 40)] // left stick, y
[InlineData(3, 255)] // right stick, x
[InlineData(4, 0)] // right stick, y
[InlineData(5, 200)] // left trigger
[InlineData(6, 31)] // right trigger, just past the threshold
[InlineData(8, 0x00)] // the hat, up
[InlineData(8, 0x28)] // a face button, the hat neutral
[InlineData(9, 0x01)] // a shoulder button
[InlineData(10, 0x01)] // the PS button
public void AnythingMovedOrHeldIsAPadInUse(int index, byte value)
{
byte[] report = Usb();
report[index] = value;
DualSenseReport.TryRead(report, bluetooth: false, out bool active, out _).Should().BeTrue();
active.Should().BeTrue();
}
[Theory]
[InlineData(1, 128 + DualSenseReport.StickDeadzone)] // a stick that drifts inside its dead zone
[InlineData(5, DualSenseReport.TriggerThreshold)] // a trigger at the threshold, not past it
[InlineData(7, 0xFF)] // the counter between the triggers and the buttons
[InlineData(16, 0xFF)] // the gyroscope: a pad lying on a desk still reports it
[InlineData(33, 0x7F)] // the touchpad
public void WhatIsNotAButtonAStickOrATriggerIsNotUse(int index, byte value)
{
byte[] report = Usb();
report[index] = value;
DualSenseReport.TryRead(report, bluetooth: false, out bool active, out _).Should().BeTrue();
active.Should().BeFalse("drift, the report counter, motion and the touchpad are not the pad being played with");
}
[Theory]
[InlineData(0x08, BatteryState.Discharging, 80)]
[InlineData(0x00, BatteryState.Discharging, 0)]
[InlineData(0x0A, BatteryState.Discharging, 100)]
[InlineData(0x0F, BatteryState.Discharging, 100)] // a level past ten is ten
[InlineData(0x15, BatteryState.Charging, 50)]
[InlineData(0x2A, BatteryState.Full, 100)]
[InlineData(0x20, BatteryState.Full, 100)] // full is 100 whatever the level bits say
[InlineData(0xA4, BatteryState.Unknown, 40)] // not charging: voltage or temperature
[InlineData(0xF3, BatteryState.Unknown, 30)] // a charging fault
public void TheBatteryByteIsALevelInTenthsAndWhatTheBatteryIsDoing(byte status, BatteryState state, int level)
{
DualSenseReport.TryRead(Usb(status), bluetooth: false, out _, out BatteryReading? battery).Should().BeTrue();
battery.Should().Be(new BatteryReading(state, BatteryScale.Percent, level));
}
[Fact]
public void TheExtendedBluetoothReportIsTheUsbBodyOneByteLater()
{
byte[] report = BluetoothFull(0x16);
report[2 + 4] = 255; // the left trigger, where the USB report has it at 5
DualSenseReport.TryRead(report, bluetooth: true, out bool active, out BatteryReading? battery).Should().BeTrue();
active.Should().BeTrue();
battery.Should().Be(new BatteryReading(BatteryState.Charging, BatteryScale.Percent, 60));
}
/// <summary>
/// Windows hands the short report over at the length of the device's longest, with the id the USB report has. Read
/// as a USB report it would be a pad with an empty battery and its buttons taken for triggers.
/// </summary>
[Fact]
public void TheShortBluetoothReportHasNoBatteryAndIsNotReadAsAUsbOne()
{
DualSenseReport.TryRead(BluetoothShort(), bluetooth: true, out bool active, out BatteryReading? battery).Should().BeTrue();
active.Should().BeFalse();
battery.Should().BeNull("the short report carries none: over Bluetooth the level is there only once something switched the pad");
}
[Theory]
[InlineData(1, 0)] // a stick
[InlineData(5, 0x00)] // the hat, up
[InlineData(6, 0x02)] // a shoulder button
[InlineData(7, 0x01)] // the PS button
[InlineData(8, 200)] // the left trigger
[InlineData(9, 200)] // the right trigger
public void TheShortBluetoothReportSaysWhenThePadIsInUse(int index, byte value)
{
byte[] report = BluetoothShort();
report[index] = value;
DualSenseReport.TryRead(report, bluetooth: true, out bool active, out _).Should().BeTrue();
active.Should().BeTrue();
}
[Fact]
public void TheCounterInTheShortReportsLastButtonByteIsNotAButton()
{
byte[] report = BluetoothShort();
report[7] = 0xFC; // the upper six bits count reports
DualSenseReport.TryRead(report, bluetooth: true, out bool active, out _).Should().BeTrue();
active.Should().BeFalse();
}
[Fact]
public void WhatIsNotOneOfTheThreeReportsIsRefused()
{
DualSenseReport.TryRead([], bluetooth: false, out _, out _).Should().BeFalse();
DualSenseReport.TryRead(new byte[20], bluetooth: false, out _, out _).Should().BeFalse("too short for a USB report");
DualSenseReport.TryRead(BluetoothFull(), bluetooth: false, out _, out _).Should().BeFalse("report 0x31 is not sent over USB");
DualSenseReport.TryRead([0x31, 0, 0], bluetooth: true, out _, out _).Should().BeFalse("a truncated extended report");
DualSenseReport.TryRead([0x01, 128, 128], bluetooth: true, out _, out _).Should().BeFalse("a truncated short report");
DualSenseReport.TryRead(new byte[78], bluetooth: true, out _, out _).Should().BeFalse("an unknown report id");
}
}
@@ -0,0 +1,112 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FluentAssertions;
using FrameLedger.Domain.Input;
namespace FrameLedger.Domain.Tests.Input;
/// <summary>
/// How a tick is named by what it was played with, how changes are counted, and when two entries of a session's
/// controller list are one pad (<c>03_METRICS</c> §Input).
/// </summary>
public sealed class InputSwitchesTests
{
[Fact]
public void AChangeIsCountedBetweenTwoDifferentValuesAndNothingInBetweenEndsARun()
{
InputClass?[] ticks =
[
null,
InputClass.Controller,
InputClass.Controller,
null, // the controller put down for a moment
InputClass.Controller,
InputClass.KeyboardMouse,
null,
null,
InputClass.Controller,
];
InputSwitches.Count(ticks).Should().Be(2);
}
[Fact]
public void NoTicksAndOneValueAreNoChange()
{
InputSwitches.Count(Array.Empty<InputClass?>()).Should().Be(0);
InputSwitches.Count(new InputClass?[] { null, null }).Should().Be(0);
InputSwitches.Count(new ControllerFamily?[] { ControllerFamily.Xbox, ControllerFamily.Xbox }).Should().Be(0);
InputSwitches.Count(new ControllerFamily?[] { ControllerFamily.Xbox, ControllerFamily.PlayStation, ControllerFamily.Xbox }).Should().Be(2);
}
[Theory]
[InlineData(900, 0, 0, InputClass.Controller)]
[InlineData(0, 400, 0, InputClass.KeyboardMouse)]
public void ATickPlayedWithOneThingIsThatThing(long controller, long keyboardMouse, long both, InputClass expected) =>
InputSwitches.Exclusive(controller, keyboardMouse, both).Should().Be(expected);
[Theory]
[InlineData(0, 0, 0)] // neither
[InlineData(500, 500, 0)] // one then the other within the tick
[InlineData(900, 0, 100)] // both at once for a moment
public void ATickPlayedWithBothOrWithNeitherIsNoOneThing(long controller, long keyboardMouse, long both) =>
InputSwitches.Exclusive(controller, keyboardMouse, both).Should().BeNull();
[Theory]
[InlineData(600, 300, 0, 100, InputClass.Controller)]
[InlineData(100, 700, 0, 200, InputClass.KeyboardMouse)]
[InlineData(100, 100, 500, 300, InputClass.Both)]
[InlineData(100, 100, 100, 700, InputClass.None)]
[InlineData(0, 0, 0, 1000, InputClass.None)]
[InlineData(500, 500, 0, 0, InputClass.KeyboardMouse)] // a tie goes to the one named first: none, keyboard, controller, both
public void TheDominantClassIsTheOneWithTheMostTime(long controller, long keyboardMouse, long both, long idle, InputClass expected) =>
InputSwitches.Dominant(controller, keyboardMouse, both, idle).Should().Be(expected);
[Fact]
public void ATickWithTheGameNotInFrontHasNoDominantClass() =>
InputSwitches.Dominant(0, 0, 0, 0).Should().BeNull();
[Fact]
public void TwoPadsThatMoveTogetherAreOnePad()
{
int[] held = [1000, 1000, 0, 1000, 900, 1000, 1000, 1000, 1000, 1000, 1000, 1000];
int[] presented = [1000, 900, 0, 1000, 1000, 1000, 1000, 1000, 1000, 1000, 1000, 1000];
VirtualPad.Coincidence(held, presented).Should().BeGreaterThan(0.95);
VirtualPad.IsSamePad(held, presented).Should().BeTrue();
}
[Fact]
public void TwoPadsUsedAtDifferentMomentsAreTwoPads()
{
int[] first = [1000, 1000, 1000, 1000, 1000, 1000, 0, 0, 0, 0, 0, 0];
int[] second = [0, 0, 0, 0, 0, 0, 1000, 1000, 1000, 1000, 1000, 1000];
VirtualPad.Coincidence(first, second).Should().Be(0);
VirtualPad.IsSamePad(first, second).Should().BeFalse();
}
[Fact]
public void APadThatSharesOnlyPartOfTheBusierOnesTimeIsNotIt()
{
// Two players: the second joins for a third of the time the first plays.
int[] first = [1000, 1000, 1000, 1000, 1000, 1000, 1000, 1000, 1000, 1000, 1000, 1000];
int[] second = [1000, 1000, 1000, 1000, 0, 0, 0, 0, 0, 0, 0, 0];
VirtualPad.Coincidence(first, second).Should().BeApproximately(1 / 3d, 1e-9);
VirtualPad.IsSamePad(first, second).Should().BeFalse();
}
[Fact]
public void AFewSecondsTogetherProveNothing()
{
int[] a = [1000, 1000, 1000];
int[] b = [1000, 1000, 1000];
VirtualPad.Coincidence(a, b).Should().Be(1);
VirtualPad.IsSamePad(a, b).Should().BeFalse("under ten seconds in use");
VirtualPad.Coincidence([], []).Should().Be(0);
VirtualPad.Coincidence([0, 0], [0, 0]).Should().Be(0);
}
}
@@ -0,0 +1,41 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FluentAssertions;
using FrameLedger.Domain.Input;
namespace FrameLedger.Domain.Tests.Input;
/// <summary>
/// The two facts taken from the name Windows gives a controller's device interface (<c>21_INPUT_DEVICES</c> §What is
/// never read). The names here have the shape Windows writes; their instance parts are made up.
/// </summary>
public sealed class RawDeviceNameTests
{
private const string _xboxUsb = @"\\?\HID#VID_045E&PID_0B12&IG_00#8&1a2b3c4d&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}";
private const string _xboxBluetooth = @"\\?\HID#{00001812-0000-1000-8000-00805f9b34fb}&Dev&VID_045e&PID_0b13&REV_0520&IG_00#9&2b3c4d5e&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}";
private const string _dualSenseUsb = @"\\?\HID#VID_054C&PID_0CE6&MI_03#8&3c4d5e6f&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}";
private const string _dualSenseBluetooth = @"\\?\HID#{00001124-0000-1000-8000-00805F9B34FB}_VID&0002054c_PID&0ce6#8&4d5e6f70&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}";
[Theory]
[InlineData(_xboxUsb, true)]
[InlineData(_xboxBluetooth, true)]
[InlineData(@"\\?\hid#vid_28de&pid_11ff&ig_00#7&5e6f7081&0&0000#{4d1e55b2-f16f-11cf-88cb-001111000030}", true)]
[InlineData(_dualSenseUsb, false)]
[InlineData(_dualSenseBluetooth, false)]
[InlineData("", false)]
[InlineData(null, false)]
public void ADeviceWindowsPresentsThroughXInputCarriesMicrosoftsMarkInItsName(string? name, bool xinput) =>
RawDeviceName.IsXInputClass(name).Should().Be(xinput);
[Theory]
[InlineData(_xboxUsb, ControllerConnection.Usb)]
[InlineData(_dualSenseUsb, ControllerConnection.Usb)]
[InlineData(_dualSenseBluetooth, ControllerConnection.Bluetooth)] // classic Bluetooth's HID service
[InlineData(_xboxBluetooth, ControllerConnection.Bluetooth)] // low energy's, which also carries VID_
[InlineData(@"\\?\HID#SOMETHING_ELSE#1&2&3#{4d1e55b2-f16f-11cf-88cb-001111000030}", ControllerConnection.Unknown)]
[InlineData("", ControllerConnection.Unknown)]
[InlineData(null, ControllerConnection.Unknown)]
public void TheConnectionIsBluetoothByTheServicesIdentifierAndUsbByAUsbVendorId(string? name, ControllerConnection connection) =>
RawDeviceName.ConnectionOf(name).Should().Be(connection);
}
@@ -28,6 +28,11 @@
<Using Include="Xunit" />
</ItemGroup>
<!-- Windows as the input reader asks it, with every answer written by the test (D157): shared with the other suites that drive the reader. -->
<ItemGroup>
<Compile Include="..\Shared\FakeInputBackend.cs" Link="Shared\FakeInputBackend.cs" />
</ItemGroup>
<!--
GuardMirrorTests and RulesPathAgreementTests P/Invoke into the real
FrameLedger.Guard.dll, which NativeAntiCheatGuard loads by absolute path from
@@ -0,0 +1,276 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Diagnostics;
using FluentAssertions;
using FrameLedger.Application.Capture;
using FrameLedger.Application.Input;
using FrameLedger.Application.Telemetry;
using FrameLedger.Infrastructure.Input;
using FrameLedger.Testing;
namespace FrameLedger.Infrastructure.Tests.Input;
/// <summary>
/// The Agent's one input reader and the sessions' views of it (<c>21_INPUT_DEVICES</c> §The reader): it runs only
/// while a view is open, each view counts the slices in which its own game was in front, a pause is not observed, and
/// a reader that keeps failing ends its run with one line and takes no session with it. The Windows behind it is the
/// tests' own.
/// </summary>
public sealed class InputDeviceHubTests
{
private static readonly TimeSpan _slice = TimeSpan.FromMilliseconds(5);
private static readonly TimeSpan _patience = TimeSpan.FromSeconds(10);
private static GameProcess Pids(params int[] pids) => GameProcess.Unpinned([.. pids.Select(static p => new GameProcessId(p, DateTimeOffset.UnixEpoch))]);
/// <summary>Reads the view until <paramref name="enough"/> says so, adding up what it returned.</summary>
private static (int Span, int Observed, int Foreground, int Controller, long Slices) ReadUntil(IInputActivitySource view, Func<(int Span, int Observed, int Foreground, int Controller, long Slices), bool> enough)
{
(int Span, int Observed, int Foreground, int Controller, long Slices) sum = default;
var clock = Stopwatch.StartNew();
while (!enough(sum) && clock.Elapsed < _patience)
{
if (view.TryRead(out InputReading? reading))
{
sum = (sum.Span + reading.SpanMs, sum.Observed + reading.ObservedMs, sum.Foreground + reading.ForegroundMs, sum.Controller + reading.ControllerMs, reading.Health.Slices);
}
else
{
Thread.Sleep(2);
}
}
return sum;
}
private static int Count(List<string> notes)
{
lock (notes)
{
return notes.Count;
}
}
private static void WaitUntil(Func<bool> condition)
{
var clock = Stopwatch.StartNew();
while (!condition() && clock.Elapsed < _patience)
{
Thread.Sleep(2);
}
condition().Should().BeTrue("it should have happened within the patience of the test");
}
[Fact]
public void WithNoViewTheHubHasNoThreadAndMakesNoBackend()
{
int made = 0;
using var hub = new InputDeviceHub(
() =>
{
made++;
return new FakeInputBackend();
},
interval: _slice);
hub.IsRunning.Should().BeFalse("with no session nothing is read: no thread, no window, no registration");
made.Should().Be(0);
}
[Fact]
public void AViewCountsTheSlicesItsOwnGameWasInFrontOfAndAnotherViewItsOwn()
{
using var backend = new FakeInputBackend { Foreground = 500 };
backend.Pads[0] = new XInputReading(1, Buttons: 0x1000, 0, 0, 0, 0, 0, 0);
backend.Details[0] = new XInputDetails(Wireless: false, BatteryType: 1, BatteryLevel: 0);
using var hub = new InputDeviceHub(() => backend, interval: _slice);
using IInputActivitySource mine = hub.Open();
using IInputActivitySource other = hub.Open();
mine.Follow(Pids(400, 500));
other.Follow(Pids(600));
(int span, int observed, int foreground, int controller, long slices) = ReadUntil(mine, static s => s.Controller > 0 && s.Slices >= 3);
(int otherSpan, int otherObserved, int otherForeground, int otherController, _) = ReadUntil(other, static s => s.Slices >= 3);
hub.IsRunning.Should().BeTrue();
backend.Opened.Should().BeTrue();
slices.Should().BeGreaterThanOrEqualTo(3);
foreground.Should().BeGreaterThan(0).And.BeLessThanOrEqualTo(observed);
controller.Should().BeGreaterThan(0).And.BeLessThanOrEqualTo(foreground);
observed.Should().BeLessThanOrEqualTo(span);
otherObserved.Should().BeGreaterThan(0, "the other session is observed too");
otherSpan.Should().BeGreaterThan(0);
otherForeground.Should().Be(0, "its game was never in front");
otherController.Should().Be(0, "a controller in use while another program is in front is not that session's");
}
[Fact]
public void APinnedProcessIsTheSessionsGame()
{
using var backend = new FakeInputBackend { Foreground = 77 };
using var hub = new InputDeviceHub(() => backend, interval: _slice);
using IInputActivitySource view = hub.Open();
view.Follow(GameProcess.Pinned(77, NSubstitute.Substitute.For<ITargetLiveness>()));
ReadUntil(view, static s => s.Foreground > 0).Foreground.Should().BeGreaterThan(0);
}
[Fact]
public void WithNoWindowInFrontNoSessionIsInFront()
{
using var backend = new FakeInputBackend { Foreground = 0 };
using var hub = new InputDeviceHub(() => backend, interval: _slice);
using IInputActivitySource view = hub.Open();
view.Follow(Pids(0));
(_, int observed, int foreground, _, _) = ReadUntil(view, static s => s.Slices >= 3);
observed.Should().BeGreaterThan(0);
foreground.Should().Be(0, "pid 0 is Windows' word for no window in front, never a game");
}
[Fact]
public void WhileRecordingIsPausedASliceIsNotObserved()
{
bool paused = true;
using var backend = new FakeInputBackend { Foreground = 500 };
using var hub = new InputDeviceHub(() => backend, () => Volatile.Read(ref paused), _slice);
using IInputActivitySource view = hub.Open();
view.Follow(Pids(500));
(int span, int observed, _, _, _) = ReadUntil(view, static s => s.Slices >= 3);
observed.Should().Be(0, "a pause is a gap");
span.Should().BeGreaterThan(0, "the clock does not stop for a pause: a battery level is timed by it");
Volatile.Write(ref paused, false);
ReadUntil(view, static s => s.Observed > 0).Observed.Should().BeGreaterThan(0);
}
[Fact]
public void TheRunEndsWithItsLastViewAndANewViewStartsANewOne()
{
var made = new List<FakeInputBackend>();
var notes = new List<string>();
using var hub = new InputDeviceHub(
() =>
{
var backend = new FakeInputBackend();
lock (made)
{
made.Add(backend);
}
return backend;
},
interval: _slice,
note: line =>
{
lock (notes)
{
notes.Add(line);
}
});
IInputActivitySource first = hub.Open();
ReadUntil(first, static s => s.Slices >= 2);
first.Dispose();
// The run's last act is its line in the log: by then the backend is disposed and the thread's slot is free.
WaitUntil(() => Count(notes) == 1);
hub.IsRunning.Should().BeFalse();
lock (made)
{
made.Should().ContainSingle().Which.Disposed.Should().BeTrue("the window and the registration go with the last session");
}
lock (notes)
{
notes.Should().ContainSingle().Which.Should().StartWith("input: run ended - slices ").And.Contain("raw input registered").And.Contain("xinput there").And.Contain("last input read");
}
using IInputActivitySource second = hub.Open();
ReadUntil(second, static s => s.Slices >= 1).Slices.Should().BeGreaterThanOrEqualTo(1);
lock (made)
{
made.Should().HaveCount(2, "a new session opens a new run, with a backend of its own");
}
}
[Fact]
public void AReaderThatKeepsFailingEndsItsRunWithOneLineAndTheViewSimplyHasNothingMore()
{
var notes = new List<string>();
using var backend = new FakeInputBackend { ThrowOnDrain = true };
using var hub = new InputDeviceHub(() => backend, interval: _slice, note: line =>
{
lock (notes)
{
notes.Add(line);
}
});
using IInputActivitySource view = hub.Open();
WaitUntil(() => Count(notes) == 2);
hub.IsRunning.Should().BeFalse();
view.TryRead(out _).Should().BeFalse("no slice was ever made");
lock (notes)
{
notes.Should().HaveCount(2);
notes[0].Should().StartWith($"input: the reader's slice threw {InputDeviceHub.MaxFaults} times running and the run ends (InvalidOperationException");
notes[1].Should().StartWith("input: run ended");
}
}
[Fact]
public void ABackendThatCannotBeMadeEndsTheRunWithOneLine()
{
var notes = new List<string>();
using var hub = new InputDeviceHub(() => throw new InvalidOperationException("no window station"), interval: _slice, note: line =>
{
lock (notes)
{
notes.Add(line);
}
});
using IInputActivitySource view = hub.Open();
WaitUntil(() => Count(notes) == 2);
hub.IsRunning.Should().BeFalse();
lock (notes)
{
notes[0].Should().Be("input: the reader did not start (InvalidOperationException: no window station)");
}
}
[Fact]
public void ADisposedHubOpensNoViewAndDisposingTwiceIsNothing()
{
using var backend = new FakeInputBackend();
var hub = new InputDeviceHub(() => backend, interval: _slice);
IInputActivitySource view = hub.Open();
ReadUntil(view, static s => s.Slices >= 1);
hub.Dispose();
hub.Dispose();
hub.IsRunning.Should().BeFalse();
Action open = () => hub.Open();
open.Should().Throw<ObjectDisposedException>();
view.Dispose();
}
[Fact]
public void ASliceMustBeLongerThanNothing()
{
Action zero = () => _ = new InputDeviceHub(static () => new FakeInputBackend(), interval: TimeSpan.Zero);
Action none = () => _ = new InputDeviceHub(null!);
zero.Should().Throw<ArgumentOutOfRangeException>();
none.Should().Throw<ArgumentNullException>();
}
}
@@ -0,0 +1,178 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Buffers.Binary;
using FluentAssertions;
using FrameLedger.Application.Input;
using FrameLedger.Infrastructure.Input;
namespace FrameLedger.Infrastructure.Tests.Input;
/// <summary>
/// The bytes <c>GetRawInputBuffer</c> fills, walked (<c>21_INPUT_DEVICES</c> §The reader): each report of each HID block
/// reaches the sink with its device, and a block that claims more than the buffer holds ends the walk without a byte
/// read past it. The buffers are built here to the documented layout - <b>none was filled by Windows</b>.
/// </summary>
public sealed class RawInputBufferTests
{
/// <summary>One block: the header, then for a HID device the size and count of its reports and the reports themselves.</summary>
private static byte[] Block(nint device, int reportBytes, params byte[][] reports)
{
byte[] block = new byte[RawInputBuffer.HeaderBytes + 8 + reports.Sum(static r => r.Length)];
BinaryPrimitives.WriteUInt32LittleEndian(block, RawInputBuffer.TypeHid);
BinaryPrimitives.WriteUInt32LittleEndian(block.AsSpan(4), (uint)block.Length);
BinaryPrimitives.WriteInt64LittleEndian(block.AsSpan(8), device);
BinaryPrimitives.WriteUInt32LittleEndian(block.AsSpan(RawInputBuffer.HeaderBytes), (uint)reportBytes);
BinaryPrimitives.WriteUInt32LittleEndian(block.AsSpan(RawInputBuffer.HeaderBytes + 4), (uint)reports.Length);
int at = RawInputBuffer.HeaderBytes + 8;
foreach (byte[] report in reports)
{
report.CopyTo(block, at);
at += report.Length;
}
return block;
}
/// <summary>Blocks one after another, each starting on a multiple of eight as Windows lays them out.</summary>
private static byte[] Buffer(params byte[][] blocks)
{
var bytes = new List<byte>();
foreach (byte[] block in blocks)
{
bytes.AddRange(block);
while (bytes.Count % 8 != 0)
{
bytes.Add(0xEE);
}
}
return [.. bytes];
}
[Fact]
public void EachReportOfEachBlockReachesTheSinkWithItsDevice()
{
var sink = new Recorder();
byte[] buffer = Buffer(
Block(0x10, 3, [1, 2, 3], [4, 5, 6]),
Block(0x20, 5, [9, 9, 9, 9, 9]));
RawInputBuffer.Walk(buffer, 2, sink).Should().Be(2);
sink.Reports.Should().HaveCount(3);
sink.Reports[0].Should().Be((0x10, "010203"));
sink.Reports[1].Should().Be((0x10, "040506"));
sink.Reports[2].Should().Be((0x20, "0909090909"));
}
[Fact]
public void OnlyAsManyBlocksAsWindowsSaidItWroteAreWalked()
{
var sink = new Recorder();
byte[] buffer = Buffer(Block(0x10, 1, [1]), Block(0x20, 1, [2]));
RawInputBuffer.Walk(buffer, 1, sink).Should().Be(1);
sink.Reports.Should().ContainSingle().Which.Device.Should().Be(0x10);
RawInputBuffer.Walk(buffer, 0, sink).Should().Be(0);
RawInputBuffer.Walk([], 3, sink).Should().Be(0);
}
[Fact]
public void ABlockThatIsNotAHidDevicesIsPassedOver()
{
var sink = new Recorder();
byte[] keyboard = new byte[RawInputBuffer.HeaderBytes + 16];
BinaryPrimitives.WriteUInt32LittleEndian(keyboard, 1);
BinaryPrimitives.WriteUInt32LittleEndian(keyboard.AsSpan(4), (uint)keyboard.Length);
RawInputBuffer.Walk(Buffer(keyboard, Block(0x20, 1, [7])), 2, sink).Should().Be(2);
sink.Reports.Should().ContainSingle("the reader registers for controllers only; a block of another kind is never read").Which.Device.Should().Be(0x20);
}
[Fact]
public void TheLastBlockMayEndTheBufferWithoutItsPadding()
{
var sink = new Recorder();
byte[] block = Block(0x10, 3, [1, 2, 3]);
block.Length.Should().Be(35, "not a multiple of eight: the walk must not want the five bytes after it");
RawInputBuffer.Walk(block, 1, sink).Should().Be(1);
sink.Reports.Should().ContainSingle();
}
/// <summary>The bytes come from a device by way of Windows: no length in them is trusted.</summary>
[Fact]
public void ABlockThatClaimsMoreThanTheBufferHoldsEndsTheWalkAndWhatCameBeforeStands()
{
var sink = new Recorder();
byte[] good = Block(0x10, 2, [1, 2]);
byte[] lying = Block(0x20, 2, [3, 4]);
BinaryPrimitives.WriteUInt32LittleEndian(lying.AsSpan(4), 4096);
RawInputBuffer.Walk(Buffer(good, lying), 2, sink).Should().Be(1);
sink.Reports.Should().ContainSingle().Which.Device.Should().Be(0x10);
}
[Fact]
public void ABlockSmallerThanItsOwnHeaderEndsTheWalk()
{
var sink = new Recorder();
byte[] tiny = Block(0x10, 1, [1]);
BinaryPrimitives.WriteUInt32LittleEndian(tiny.AsSpan(4), 8);
RawInputBuffer.Walk(Buffer(tiny, Block(0x20, 1, [2])), 2, sink).Should().Be(0);
sink.Reports.Should().BeEmpty();
RawInputBuffer.Walk(new byte[10], 1, sink).Should().Be(0, "not even a header");
}
[Theory]
[InlineData(0u, 4u)] // reports of no size
[InlineData(4u, 0u)] // no reports
[InlineData(4u, 3u)] // three reports of four bytes where eight bytes follow
[InlineData(0xFFFFFFFFu, 0xFFFFFFFFu)] // a product that would not fit in 32 bits
public void ReportsThatDoNotFitTheirBlockAreNotHandedOver(uint reportBytes, uint count)
{
var sink = new Recorder();
byte[] block = Block(0x10, 4, [1, 2, 3, 4], [5, 6, 7, 8]);
BinaryPrimitives.WriteUInt32LittleEndian(block.AsSpan(RawInputBuffer.HeaderBytes), reportBytes);
BinaryPrimitives.WriteUInt32LittleEndian(block.AsSpan(RawInputBuffer.HeaderBytes + 4), count);
RawInputBuffer.Walk(Buffer(block, Block(0x20, 1, [9])), 2, sink).Should().Be(2, "the block is walked over by its own size, which is sound");
sink.Reports.Should().ContainSingle("only the block after it").Which.Device.Should().Be(0x20);
}
[Fact]
public void AHidBlockWithNoRoomForItsCountsHasNoReports()
{
var sink = new Recorder();
byte[] header = new byte[RawInputBuffer.HeaderBytes + 4];
BinaryPrimitives.WriteUInt32LittleEndian(header, RawInputBuffer.TypeHid);
BinaryPrimitives.WriteUInt32LittleEndian(header.AsSpan(4), (uint)header.Length);
RawInputBuffer.Walk(header, 1, sink).Should().Be(1);
sink.Reports.Should().BeEmpty();
}
private sealed class Recorder : IInputBackendSink
{
public List<(nint Device, string Hex)> Reports { get; } = [];
public void Arrived(nint device, RawController controller)
{
}
public void Removed(nint device)
{
}
public void Report(nint device, ReadOnlySpan<byte> report) => Reports.Add((device, Convert.ToHexString(report)));
}
}
@@ -0,0 +1,153 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Diagnostics;
using FluentAssertions;
using FrameLedger.Application.Input;
using FrameLedger.Infrastructure.Input;
namespace FrameLedger.Infrastructure.Tests.Input;
/// <summary>
/// The reader's Windows side against the real Windows of whatever machine runs this - a developer's PC with or without
/// a controller, CI's runner with none. It asserts the CONTRACT, never the hardware: it opens, answers every question
/// without throwing, says honestly what it could register, and leaves nothing behind. <b>What it reads from a real
/// controller is not established by this</b>; that is owner-only item 48.
/// </summary>
[Trait("Category", "Integration")]
public sealed class Win32InputBackendTests
{
[Fact]
public void ItOpensAnswersEveryQuestionAndClosesWithOrWithoutAController()
{
using var backend = new Win32InputBackend();
var sink = new Recorder();
// Refused is a valid answer - a session with no interactive desktop gives none - and is said, not hidden.
bool registered = backend.Open();
backend.Drain(sink);
backend.Drain(sink);
for (int slot = 0; slot < InputReader.Slots; slot++)
{
if (backend.TryReadPad(slot, out XInputReading pad))
{
pad.LeftTrigger.Should().BeInRange(0, 255);
backend.TryReadPadDetails(slot, out XInputDetails details).Should().BeTrue("a pad XInput has a state for has capabilities");
details.BatteryType.Should().BeOneOf(0, 1, 2, 3, 0xFF);
}
}
if (backend.TryReadLastInputTick(out uint tick))
{
// The same clock as Environment.TickCount, and never ahead of it by more than a moment.
unchecked((int)((uint)Environment.TickCount - tick)).Should().BeGreaterThan(-60_000);
}
uint front = backend.ForegroundProcessId();
if (front != 0)
{
Action named = () => Process.GetProcessById((int)front).Dispose();
named.Should().NotThrow("what is in front is a live process");
}
backend.ThreadCpuMs().Should().BeGreaterThanOrEqualTo(0);
sink.Reports.Should().BeGreaterThanOrEqualTo(0);
if (!registered)
{
sink.Arrived.Should().Be(0, "nothing is listed for a registration Windows refused");
}
}
[Fact]
public void AReaderOverItTakesSlicesAndSaysWhatAnswered()
{
using var backend = new Win32InputBackend();
var reader = new InputReader(backend);
reader.Open();
InputSlice first = reader.Slice(100);
InputSlice second = reader.Slice(100);
second.Health.Slices.Should().Be(2);
second.Health.Faults.Should().Be(0);
second.Health.ThreadCpuMs.Should().BeGreaterThanOrEqualTo(first.Health.ThreadCpuMs);
second.Health.XInputAvailable.Should().Be(backend.XInputAvailable);
// All(), not OnlyContain: with no controller connected the list is empty, and that is a valid answer.
second.Devices.All(static d => d.Device.Id > 0).Should().BeTrue("every controller it lists has a number");
}
[Fact]
public void TheHubRunsOverItAndEndsCleanly()
{
var notes = new List<string>();
using var hub = new InputDeviceHub(static () => new Win32InputBackend(), interval: TimeSpan.FromMilliseconds(10), note: line =>
{
lock (notes)
{
notes.Add(line);
}
});
IInputActivitySource view = hub.Open();
var clock = Stopwatch.StartNew();
InputReading? reading = null;
while (reading is null && clock.Elapsed < TimeSpan.FromSeconds(10))
{
if (!view.TryRead(out reading))
{
Thread.Sleep(5);
}
}
view.Dispose();
reading.Should().NotBeNull("the reader's thread made a slice");
reading.SpanMs.Should().BeGreaterThanOrEqualTo(0);
reading.ForegroundMs.Should().Be(0, "this view followed no process");
lock (notes)
{
notes.Should().NotContain(static n => n.Contains("did not start", StringComparison.Ordinal) || n.Contains("threw", StringComparison.Ordinal));
}
}
[Fact]
public void ItCanBeOpenedAgainAfterItWasClosedAndClosedTwice()
{
var first = new Win32InputBackend();
bool registered = first.Open();
first.Dispose();
first.Dispose();
using var second = new Win32InputBackend();
second.Open().Should().Be(registered, "the window's class and the registration were given back");
Action reopen = () => first.Open();
reopen.Should().Throw<ObjectDisposedException>();
}
[Fact]
public void BeforeItIsOpenedItHandsOverNothing()
{
using var backend = new Win32InputBackend();
var sink = new Recorder();
backend.Drain(sink);
sink.Arrived.Should().Be(0);
sink.Reports.Should().Be(0);
}
private sealed class Recorder : IInputBackendSink
{
public int Arrived { get; private set; }
public int Reports { get; private set; }
void IInputBackendSink.Arrived(nint device, RawController controller) => Arrived++;
public void Removed(nint device)
{
}
public void Report(nint device, ReadOnlySpan<byte> report) => Reports++;
}
}
@@ -962,6 +962,79 @@ public sealed class LedgerDatabaseTests
}
}
/// <summary>
/// Schema 0024 (2026-11-14, owner decisions D155-D163): what a session was played with, nine columns of
/// <c>sessions</c>, and what a game's store lists of controller support, three of <c>games</c> - ADD COLUMN only. A
/// session and a game written before have none of them: N/A, never a zero.
/// </summary>
[Fact]
public async Task ScriptTwentyFourAddsTheInputColumnsAndAnEarlierSessionAndGameHaveNone()
{
await using LedgerFixture f = await LedgerFixture.OpenAsync();
MigrationRunner.LatestVersion.Should().BeGreaterThanOrEqualTo(24);
long gameId = (await new SqliteGameRepository(f.Db).EnsureAsync(
new() { ExePath = @"C:\Games\A\a.exe", SizeBytes = 1, MtimeUnixMs = 2 }, "A", Ct).ConfigureAwait(true)).Id;
long snapshotId = await new SqliteHardwareSnapshotRepository(f.Db).EnsureAsync(new HardwareSnapshot { GpuName = "g" }, DateTimeOffset.UnixEpoch, Ct)
.ConfigureAwait(true);
string path = f.Path;
await f.Db.DisposeAsync().ConfigureAwait(true);
var c23 = new SqliteConnection(new SqliteConnectionStringBuilder { DataSource = path, Pooling = false }.ToString());
await using (c23.ConfigureAwait(true))
{
await c23.OpenAsync(Ct).ConfigureAwait(true);
await RewindToAsync(c23, 23).ConfigureAwait(true);
(await c23.ExecuteScalarAsync<long>(new CommandDefinition(
"SELECT COUNT(*) FROM pragma_table_info('sessions') WHERE name LIKE 'input!_%' ESCAPE '!'", cancellationToken: Ct)).ConfigureAwait(true))
.Should().Be(0, "a ledger at schema 23 has no input column");
await c23.ExecuteAsync(new CommandDefinition(
"INSERT INTO sessions (session_guid, game_id, snapshot_id, started_at, ended_at, duration_s, qpc_epoch, qpc_frequency, capture_tier, capture_mode, exit_status, frame_count, app_frame_count, displayed_frame_count, dropped_frames) "
+ "VALUES ('00000000-0000-0000-0000-000000000024', @gameId, @snapshotId, 0, 60000, 60, 0, 10000000, 2, 'attach', 'normal', 0, 0, 0, 0)",
new { gameId, snapshotId }, cancellationToken: Ct)).ConfigureAwait(true);
}
LedgerDatabase migrated = await LedgerDatabase.OpenAsync(path, ct: Ct).ConfigureAwait(true);
await using (migrated.ConfigureAwait(true))
{
migrated.SchemaVersion.Should().Be(MigrationRunner.LatestVersion);
IReadOnlyList<string> sessionColumns = await migrated.ReadAsync(async (c, ct) => (IReadOnlyList<string>)[.. await c.QueryAsync<string>(new CommandDefinition(
"SELECT name FROM pragma_table_info('sessions') WHERE name LIKE 'input!_%' ESCAPE '!' ORDER BY cid", cancellationToken: ct)).ConfigureAwait(false)], Ct).ConfigureAwait(true);
IReadOnlyList<string> gameColumns = await migrated.ReadAsync(async (c, ct) => (IReadOnlyList<string>)[.. await c.QueryAsync<string>(new CommandDefinition(
"SELECT name FROM pragma_table_info('games') WHERE name LIKE 'controller!_%' ESCAPE '!' ORDER BY cid", cancellationToken: ct)).ConfigureAwait(false)], Ct).ConfigureAwait(true);
sessionColumns.Should().Equal(
"input_observed_ms", "input_foreground_ms", "input_controller_ms", "input_km_ms", "input_both_ms", "input_idle_ms", "input_method_switches", "input_source", "input_devices");
gameColumns.Should().Equal("controller_support", "controller_support_source", "controller_support_at");
var sessions = new SqliteSessionRepository(migrated);
SessionRow before = (await sessions.FindAsync(Guid.Parse("00000000-0000-0000-0000-000000000024"), Ct).ConfigureAwait(true))!;
before.InputObservedMs.Should().BeNull("a session recorded before the reading existed has none - N/A, never a zero");
before.InputForegroundMs.Should().BeNull();
before.InputMethodSwitches.Should().BeNull();
before.InputSource.Should().BeNull();
before.InputDevicesJson.Should().BeNull();
before.InputSharePercent(before.InputControllerMs).Should().BeNull();
(await sessions.FindInputSensorsAsync(before.Id, Ct).ConfigureAwait(true)).Should().BeEmpty();
GameRow game = (await new SqliteGameRepository(migrated).FindByIdAsync(gameId, Ct).ConfigureAwait(true))!;
game.ControllerSupport.Should().BeNull();
game.ControllerSupportSource.Should().BeNull();
game.ControllerSupportAt.Should().BeNull();
}
}
[Fact]
public void ScriptTwentyFourOnlyAddsColumnsAndNamesNoIdentifier()
{
// D160: the numbers are columns of sessions on purpose - the trend, the comparison, the export and the bug bundle
// read a session's row. What may never be a column: a controller's serial number, its address, its path.
string sql = MigrationRunner.Scripts()[24];
string statements = string.Join('\n', sql.Split('\n').Where(static l => !l.TrimStart().StartsWith("--", StringComparison.Ordinal)).Select(static l => l.Split("--")[0]));
statements.Should().NotContainAny("CREATE", "DROP", "UPDATE", "DELETE");
statements.Should().NotContainAny("serial", "address", "path", "mac", "uuid");
Regex.Matches(statements, @"ALTER\s+TABLE\s+(?<table>\w+)\s+ADD\s+COLUMN", RegexOptions.ExplicitCapture, TimeSpan.FromSeconds(1)).Select(static m => m.Groups["table"].Value)
.Distinct(StringComparer.Ordinal).Should().Equal("sessions", "games");
}
[Fact]
public void ScriptTwentyThreeAddsNoColumnToSessionsAndNamesNoIdentifier()
{
@@ -111,6 +111,15 @@ public sealed class SqliteSessionRepositoryTests
AppFramesPerJoule = 0.3125,
RuntimeModuleSourcesJson = "{\"nvngx_dlss.dll\":\"graphics_driver\"}",
DlssNrPct = 97.25,
InputObservedMs = 5_400_000,
InputForegroundMs = 5_000_000,
InputControllerMs = 3_500_000,
InputKeyboardMouseMs = 900_000,
InputBothMs = 100_000,
InputIdleMs = 500_000,
InputMethodSwitches = 4,
InputSource = "rawinput+xinput+lastinput",
InputDevicesJson = "{\"V\":1,\"Devices\":[{\"Index\":1,\"Family\":\"playstation\",\"Model\":\"DualSense\"}]}",
FgMixJson = "{\"Rows\":[{\"Kind\":\"generated\",\"Factor\":3.99,\"NativeFps\":70.5,\"DisplayedFps\":281.3,\"Seconds\":120,\"Share\":0.75,\"Windows\":24}]}",
};
@@ -547,6 +556,34 @@ public sealed class SqliteSessionRepositoryTests
float.IsNaN(rail[1]).Should().BeTrue("a tick with no reading is NaN");
}
[Fact]
public async Task TheInputSeriesAreReadOnTheirOwnAndTheFixedReadNeverSeesThem()
{
// Schema 0024 (D155-D163). The input series are rows of sensor_blobs too, and the read every summary and chart
// uses leaves them out: a class's number is not a sensor's value, and NaN marks a tick with nothing to say.
await using LedgerFixture f = await LedgerFixture.OpenAsync();
(long gameId, long snapshotId) = await SeedAsync(f);
var repo = new SqliteSessionRepository(f.Db);
SensorBlob[] sensors =
[
.. SensorsWithAdvanced(),
new() { Series = "input.class", Hz = 1, Codec = SeriesCodec.Tag, Data = SeriesCodec.EncodeSparseFloat32([1f, float.NaN, 2f]) },
new() { Series = "input.dev.1.active", Hz = 1, Codec = SeriesCodec.Tag, Data = SeriesCodec.EncodeSparseFloat32([1f, float.NaN, 0f]) },
];
long id = await repo.InsertFinalizedAsync(new FinalizedSession { Row = Row(gameId, snapshotId), Sensors = sensors, Advanced = Advanced() }, Ct);
long without = await repo.InsertFinalizedAsync(new FinalizedSession { Row = Row(gameId, snapshotId, started: DateTimeOffset.FromUnixTimeMilliseconds(1_700_000_000_000)), Sensors = [.. SensorsWithAdvanced().Take(2)] }, Ct);
(await repo.FindSensorsAsync(id, Ct)).Select(static s => s.Series).Should().Equal("gpu_temp", "t_ms");
(await repo.FindAdvancedSensorsAsync(id, Ct)).Select(static s => s.Series).Should().NotContain(static s => s.StartsWith("input.", StringComparison.Ordinal));
IReadOnlyList<SensorBlob> series = await repo.FindInputSensorsAsync(id, Ct);
series.Select(static s => s.Series).Should().Equal("t_ms", "input.class", "input.dev.1.active");
float[] timeline = SeriesCodec.DecodeFloat32(series[1].Data.ToArray());
timeline[0].Should().Be(1f);
float.IsNaN(timeline[1]).Should().BeTrue("a tick with the game not in front has no class");
(await repo.FindInputSensorsAsync(without, Ct)).Select(static s => s.Series).Should().Equal("t_ms");
}
[Fact]
public async Task TheAdvancedListNamesOnlySessionsRecordedWithTheOptionOnNewestFirst()
{
@@ -269,7 +269,7 @@ public sealed class PartialSessionFileAdvancedTests : IDisposable
}
/// <summary>One chunk as the format frames it: type, length, payload, then the IEEE CRC-32 of the first three.</summary>
private static byte[] Chunk(uint type, byte[] payload)
internal static byte[] Chunk(uint type, byte[] payload)
{
byte[] chunk = new byte[12 + payload.Length];
BinaryPrimitives.WriteUInt32LittleEndian(chunk, type);
@@ -289,7 +289,7 @@ public sealed class PartialSessionFileAdvancedTests : IDisposable
return chunk;
}
private static List<int> ChunkOffsets(byte[] file)
internal static List<int> ChunkOffsets(byte[] file)
{
var offsets = new List<int>();
for (int at = 0; at < file.Length; at += 12 + BitConverter.ToInt32(file, at + 4))
@@ -300,5 +300,5 @@ public sealed class PartialSessionFileAdvancedTests : IDisposable
return offsets;
}
private static uint[] ChunkTypes(byte[] file) => [.. ChunkOffsets(file).Select(at => BitConverter.ToUInt32(file, at))];
internal static uint[] ChunkTypes(byte[] file) => [.. ChunkOffsets(file).Select(at => BitConverter.ToUInt32(file, at))];
}
@@ -0,0 +1,287 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FluentAssertions;
using FrameLedger.Application.Input;
using FrameLedger.Application.Recording;
using FrameLedger.Application.Telemetry;
using FrameLedger.Domain.Input;
using FrameLedger.Domain.Sessions;
using FrameLedger.Infrastructure.Recording;
namespace FrameLedger.Infrastructure.Tests.Recording;
/// <summary>
/// The <c>.partial</c> and the input readings (owner decisions D155-D163): a sample's reading survives the round trip
/// with every controller it counts; with the option off the file is byte for byte what it was; a file cut at every byte
/// still reads up to its last whole chunk; and a chunk that is not well formed ends the read.
/// </summary>
public sealed class PartialSessionFileInputTests : IDisposable
{
private static readonly DateTimeOffset _t0 = new(2026, 11, 14, 9, 0, 0, TimeSpan.Zero);
private static readonly InputDevice _xbox = new() { Id = 3, Family = ControllerFamily.Xbox, VendorId = ControllerCatalog.Microsoft, ProductId = 0x0B12, Connection = ControllerConnection.Wireless, XInputSlot = 2 };
private static readonly InputDevice _dualSense = new() { Id = 70_000, Family = ControllerFamily.PlayStation, VendorId = ControllerCatalog.Sony, ProductId = ControllerCatalog.DualSense, Connection = ControllerConnection.Bluetooth };
private static readonly InputDevice _steam = new() { Id = 5, Family = ControllerFamily.Xbox, VendorId = ControllerCatalog.Valve, ProductId = ControllerCatalog.SteamVirtualGamepad, IsVirtual = true, XInputSlot = 0 };
private readonly string _dir = Path.Combine(Path.GetTempPath(), "fl-partial-input-" + Guid.NewGuid().ToString("N"));
public PartialSessionFileInputTests() => Directory.CreateDirectory(_dir);
public void Dispose()
{
try
{
Directory.Delete(_dir, recursive: true);
}
catch (IOException)
{
}
}
private static PartialHeader Header() => new()
{
SessionGuid = Guid.Parse("00000000-0000-0000-0000-0000000000b1"),
StartedAt = _t0,
QpcEpoch = 1_000_000,
QpcFrequency = 10_000_000,
GameId = 7,
SnapshotId = 3,
ExePath = @"C:\Games\Title\game.exe",
Pid = 4242,
Tier = CaptureTier.NotHooked,
Mode = CaptureMode.Attach,
TelemetryDescriptor = "l1+lhm",
};
private static TelemetrySample Sample(long qpc, InputReading? input = null) => new(
qpc,
new GpuSample { TakenAt = _t0.AddSeconds(qpc / 10_000_000.0), Layer = TelemetryLayer.Lhm, TempCoreC = 60 },
Input: input);
/// <summary>A reading with every field set to something a default would not be.</summary>
private static InputReading Full() => new()
{
SpanMs = 1004,
ObservedMs = 903,
ForegroundMs = 802,
ControllerMs = 401,
KeyboardMouseMs = 200,
BothMs = 101,
IdleMs = 100,
VirtualPad = true,
Devices =
[
new InputDeviceReading(_xbox.Id, Connected: true, ActiveMs: 502, new BatteryReading(BatteryState.Discharging, BatteryScale.FourLevels, 2), Connects: 1, Disconnects: 0),
new InputDeviceReading(_dualSense.Id, Connected: false, ActiveMs: 0, new BatteryReading(BatteryState.Charging, BatteryScale.Percent, 100), Connects: 2, Disconnects: 3),
new InputDeviceReading(_steam.Id, Connected: true, ActiveMs: 490, Battery: null, Connects: 0, Disconnects: 0),
],
Table = [_xbox, _dualSense, _steam],
Health = new InputHealth
{
RawInputRegistered = true,
XInputAvailable = true,
LastInputAvailable = true,
RawReports = 5_000_000_000,
RawReportsUnread = 7,
XInputReads = 1234,
XInputSilent = 5,
Slices = 10,
ThreadCpuMs = 3,
Faults = 1,
},
};
private static InputReading Quiet() => new() { SpanMs = 1000, ObservedMs = 1000, ForegroundMs = 1000, IdleMs = 1000, Health = new InputHealth { LastInputAvailable = true, Slices = 20 } };
[Fact]
public void ASamplesReadingRoundTripsWithEveryControllerAndASampleWithoutOneHasNone()
{
string path = Path.Combine(_dir, "input.partial");
using (IPartialSessionWriter w = PartialSessionFile.Create(path, Header()))
{
w.AppendSensors([Sample(1_100_000, Full()), Sample(1_200_000), Sample(1_300_000, Quiet())]);
w.AppendSensors([Sample(1_400_000, Full() with { VirtualPad = false })]);
}
PartialSession p = PartialSessionFile.Read(path)!;
p.Truncated.Should().BeFalse();
p.Sensors.Should().HaveCount(4);
p.Sensors[0].Input.Should().BeEquivalentTo(Full(), static o => o.WithStrictOrdering());
p.Sensors[0].Input!.Table[1].Model.Should().Be("DualSense", "a controller is what its two ids say, and they travel with the reading");
p.Sensors[1].Input.Should().BeNull("a tick the reader took no slice in carries none, and is not given the last one's");
p.Sensors[2].Input.Should().BeEquivalentTo(Quiet());
p.Sensors[3].Input!.VirtualPad.Should().BeFalse();
PartialSessionFileAdvancedTests.ChunkTypes(File.ReadAllBytes(path)).Should().Equal(1u, 8u, 11u, 8u, 11u);
}
[Fact]
public void WithTheOptionOffTheFileIsByteForByteWhatItWasBeforeTheReadingExisted()
{
string off = Path.Combine(_dir, "off.partial");
string on = Path.Combine(_dir, "on.partial");
using (IPartialSessionWriter w = PartialSessionFile.Create(off, Header()))
{
w.AppendSensors([Sample(1_100_000), Sample(1_200_000)]);
w.AppendNote(_t0, "end");
}
using (IPartialSessionWriter w = PartialSessionFile.Create(on, Header()))
{
w.AppendSensors([Sample(1_100_000, Quiet()), Sample(1_200_000)]);
w.AppendNote(_t0, "end");
}
byte[] offBytes = File.ReadAllBytes(off);
byte[] onBytes = File.ReadAllBytes(on);
PartialSessionFileAdvancedTests.ChunkTypes(offBytes).Should().Equal(1u, 8u, 6u);
PartialSessionFileAdvancedTests.ChunkTypes(onBytes).Should().Equal(1u, 8u, 11u, 6u);
int inputChunk = PartialSessionFileAdvancedTests.ChunkOffsets(onBytes)[2];
int inputLength = 12 + BitConverter.ToInt32(onBytes, inputChunk + 4);
onBytes.AsSpan(0, inputChunk).ToArray().Should().Equal(offBytes.AsSpan(0, inputChunk).ToArray(), "the sensor chunk does not change when a reading rides beside it");
onBytes.AsSpan(inputChunk + inputLength).ToArray().Should().Equal(offBytes.AsSpan(inputChunk).ToArray());
}
[Fact]
public void AKillAtEveryByteOffsetYieldsExactlyTheReadingsWhoseChunkWasComplete()
{
string path = Path.Combine(_dir, "cut.partial");
using (IPartialSessionWriter w = PartialSessionFile.Create(path, Header()))
{
w.AppendSensors([Sample(1_100_000, Full()), Sample(1_200_000, Quiet())]);
w.AppendSensors([Sample(1_300_000, Full())]);
}
byte[] whole = File.ReadAllBytes(path);
List<int> starts = PartialSessionFileAdvancedTests.ChunkOffsets(whole);
PartialSessionFileAdvancedTests.ChunkTypes(whole).Should().Equal(1u, 8u, 11u, 8u, 11u);
int[] ends = [.. starts.Skip(1), whole.Length];
for (int cut = ends[0]; cut <= whole.Length; cut++)
{
PartialSession p = PartialSessionFile.Parse(whole.AsSpan(0, cut))!;
int complete = ends.Count(e => e <= cut);
p.Sensors.Should().HaveCount(complete >= 4 ? 3 : complete >= 2 ? 2 : 0, $"cut at {cut}, {complete} complete chunk(s)");
p.Sensors.Count(static s => s.Input is not null).Should().Be(complete >= 5 ? 3 : complete >= 3 ? 2 : 0, $"cut at {cut}: a reading arrives with its own chunk and never before it");
p.Truncated.Should().Be(cut != whole.Length && !ends.Contains(cut), $"cut at {cut}");
}
}
[Fact]
public void AnInputChunkThatIsNotWellFormedEndsTheReadLikeAnyKnownChunkThatIsNot()
{
string path = Path.Combine(_dir, "bad.partial");
using (IPartialSessionWriter w = PartialSessionFile.Create(path, Header()))
{
w.AppendSensors([Sample(1_100_000, Quiet())]);
}
byte[] file = File.ReadAllBytes(path);
int at = PartialSessionFileAdvancedTests.ChunkOffsets(file)[2];
byte[] good = file.AsSpan(at + 8, BitConverter.ToInt32(file, at + 4)).ToArray();
byte[] head = file[..at];
byte[][] bad =
[
[],
[1, 0],
good[..^1], // a sample cut short
[.. good, 0], // a byte too many
[2, 0, 0, 0, .. good[4..]], // two samples declared, one there
[.. good[..^1], 1], // a controller declared and not there
];
foreach (byte[] payload in bad)
{
PartialSession p = PartialSessionFile.Parse([.. head, .. PartialSessionFileAdvancedTests.Chunk(type: 11, payload)])!;
p.Truncated.Should().BeTrue($"a payload of {payload.Length} byte(s)");
p.Sensors.Should().ContainSingle().Which.Input.Should().BeNull();
}
PartialSessionFile.Parse([.. head, .. PartialSessionFileAdvancedTests.Chunk(type: 11, good)])!.Sensors[0].Input.Should().BeEquivalentTo(Quiet(), "the same chunk, whole");
}
[Fact]
public void AReadingWhoseSampleIsNotInTheFileBelongsToNoTickAndIsLeftOut()
{
string source = Path.Combine(_dir, "source.partial");
using (IPartialSessionWriter w = PartialSessionFile.Create(source, Header()))
{
w.AppendSensors([Sample(9_999_999, Quiet())]);
}
string path = Path.Combine(_dir, "orphan.partial");
using (IPartialSessionWriter w = PartialSessionFile.Create(path, Header()))
{
w.AppendSensors([Sample(1_100_000)]);
}
byte[] other = File.ReadAllBytes(source);
byte[] orphan = other[PartialSessionFileAdvancedTests.ChunkOffsets(other)[2]..];
PartialSession p = PartialSessionFile.Parse([.. File.ReadAllBytes(path), .. orphan])!;
p.Truncated.Should().BeFalse();
p.Sensors.Should().ContainSingle().Which.Input.Should().BeNull();
}
/// <summary>A later build may know a maker, a connection or a battery state this one has no name for: it reads as "do not know", and the rest of the reading is kept.</summary>
[Fact]
public void AValueThisBuildHasNoNameForReadsAsUnknownAndTheRestIsKept()
{
string path = Path.Combine(_dir, "later.partial");
using (IPartialSessionWriter w = PartialSessionFile.Create(path, Header()))
{
w.AppendSensors([Sample(1_100_000, Full() with { Devices = [Full().Devices[0]], Table = [_xbox] })]);
}
byte[] file = File.ReadAllBytes(path);
int at = PartialSessionFileAdvancedTests.ChunkOffsets(file)[2];
byte[] payload = file.AsSpan(at + 8, BitConverter.ToInt32(file, at + 4)).ToArray();
int device = payload.Length - 23;
payload[device + 4] = 200; // the family
payload[device + 9] = 201; // the connection
payload[device + 16] = 202; // the battery's state
payload[device + 17] = 203; // and its scale
InputReading reading = PartialSessionFile.Parse([.. file[..at], .. PartialSessionFileAdvancedTests.Chunk(type: 11, payload)])!.Sensors[0].Input!;
reading.Table[0].Family.Should().Be(ControllerFamily.Other);
reading.Table[0].Connection.Should().Be(ControllerConnection.Unknown);
reading.Devices[0].Battery.Should().Be(new BatteryReading(BatteryState.Unknown, BatteryScale.None, 2));
reading.Devices[0].ActiveMs.Should().Be(502);
reading.Table[0].XInputSlot.Should().Be(2);
}
/// <summary>A controller the reading counts and does not describe cannot be written whole, and is left out; ids past sixteen bits are held to them.</summary>
[Fact]
public void AControllerWithNoDescriptionIsLeftOutAndOutOfRangeValuesAreHeld()
{
var wide = new InputDevice { Id = 9, VendorId = 0x12345, ProductId = -4, XInputSlot = 300 };
var reading = new InputReading
{
Devices =
[
new InputDeviceReading(404, Connected: true, ActiveMs: 10, Battery: null, Connects: 0, Disconnects: 0),
new InputDeviceReading(9, Connected: true, ActiveMs: 20, new BatteryReading(BatteryState.Discharging, BatteryScale.Percent, 900), Connects: 70_000, Disconnects: -1),
],
Table = [wide],
};
string path = Path.Combine(_dir, "held.partial");
using (IPartialSessionWriter w = PartialSessionFile.Create(path, Header()))
{
w.AppendSensors([Sample(1_100_000, reading)]);
}
InputReading back = PartialSessionFile.Read(path)!.Sensors[0].Input!;
back.Devices.Should().ContainSingle().Which.Should().Be(
new InputDeviceReading(9, Connected: true, ActiveMs: 20, new BatteryReading(BatteryState.Discharging, BatteryScale.Percent, 255), Connects: 65_535, Disconnects: 0));
back.Table.Should().ContainSingle().Which.Should().BeEquivalentTo(wide with { VendorId = 65_535, ProductId = 0, XInputSlot = 255 });
}
}
+90
View File
@@ -0,0 +1,90 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FrameLedger.Application.Input;
namespace FrameLedger.Testing;
/// <summary>Windows, as the input reader asks it, with every answer written by the test: <b>no device is behind it</b>.</summary>
internal sealed class FakeInputBackend : IInputBackend
{
private readonly List<Action<IInputBackendSink>> _pending = [];
public bool Registers { get; set; } = true;
public bool XInputAvailable { get; set; } = true;
/// <summary>The pads XInput has, by slot.</summary>
public Dictionary<int, XInputReading> Pads { get; } = [];
public Dictionary<int, XInputDetails> Details { get; } = [];
/// <summary>Windows' time of the last keyboard or mouse input; null is "Windows did not give it".</summary>
public uint? LastInputTick { get; set; } = 1000;
public uint Foreground { get; set; } = 42;
public long CpuMs { get; set; }
public bool ThrowOnDrain { get; set; }
/// <summary>How many times each slot was asked for its state.</summary>
public int[] PadAsks { get; } = new int[InputReader.Slots];
public int DetailAsks { get; private set; }
public bool Opened { get; private set; }
public bool Disposed { get; private set; }
public void Arrive(nint device, RawController controller) => _pending.Add(sink => sink.Arrived(device, controller));
public void Leave(nint device) => _pending.Add(sink => sink.Removed(device));
public void Send(nint device, params byte[] report) => _pending.Add(sink => sink.Report(device, report));
public bool Open()
{
Opened = true;
return Registers;
}
public void Drain(IInputBackendSink sink)
{
if (ThrowOnDrain)
{
throw new InvalidOperationException("the drain failed");
}
foreach (Action<IInputBackendSink> step in _pending)
{
step(sink);
}
_pending.Clear();
}
public bool TryReadPad(int slot, out XInputReading pad)
{
PadAsks[slot]++;
return Pads.TryGetValue(slot, out pad);
}
public bool TryReadPadDetails(int slot, out XInputDetails details)
{
DetailAsks++;
return Details.TryGetValue(slot, out details);
}
public bool TryReadLastInputTick(out uint tick)
{
tick = LastInputTick ?? 0;
return LastInputTick is not null;
}
public uint ForegroundProcessId() => Foreground;
public long ThreadCpuMs() => CpuMs;
public void Dispose() => Disposed = true;
}
Loaded 100 of 102 files, more files were not shown because too many files have changed in this diff. Show more