# gggz114514-oss/re8-b580-nr-xess architecture

> Architecture diagram of the GitHub repository gggz114514-oss/re8-b580-nr-xess, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gggz114514-oss/re8-b580-nr-xess
- Repository: https://github.com/gggz114514-oss/re8-b580-nr-xess

## Overview

This repository adds a RE8-specific neural-residual stage before XeSS: the game’s render inputs are bridged from D3D12 into the Python/XPU runtime, processed under loopback-web controls, and returned for XeSS upscaling. The documented user workflow is to open the local control page during gameplay, select NR options, and confirm active processing and timing. Major branches include input-format bridging, configurable model modes and history, and presentation integration. The README and sampled files support the high-level wiring; unsampled host and OptiScaler code limit finer call-level detail.

Main entry points: [`game/nr_game_pre_xess_host.py`](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_pre_xess_host.py) (Pre-XeSS host), [`game/fullsize_session_v1.py`](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/fullsize_session_v1.py) (NR session), [`optiscaler/added/nr_live_present.cpp`](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/optiscaler/added/nr_live_present.cpp) (OptiScaler hook), [`game/nr_game_fullsize.py`](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_fullsize.py) (Mode selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Game integration"]
  node_game["RE8 renderer"]
  node_optiscaler["OptiScaler hook"]
  node_host["Pre-XeSS host"]
  node_residual["Residual output"]
  node_present["Present bridge<br/>[nr_live_present.h]"]
end

subgraph group_controls["Web controls"]
  node_panel["Control panel"]
  node_controls_model["Validated settings"]
  node_telemetry["Processing status"]
end

subgraph group_inference["NR processing"]
  node_mode_select["Mode selection"]
  node_session["NR session"]
  node_geometry["Geometry contracts<br/>[re4_session_v1.py]"]
  node_history["History and replay"]
  node_model["NR model runtime"]
  node_weights[("Model weights")]
end

subgraph group_bridge["GPU texture bridge"]
  node_texture_api["Texture bridge API"]
  node_texture_impl["D3D12 texture bridge"]
  node_texture_wrapper["Python bridge wrapper"]
end

node_player(("Player"))
node_browser(("Local browser"))
node_xess["XeSS upscaler"]

node_player -->|"renders"| node_game
node_game -->|"presents frames"| node_optiscaler
node_optiscaler -->|"dispatches input"| node_host
node_host -->|"prepares textures"| node_texture_wrapper
node_texture_wrapper -->|"calls API"| node_texture_api
node_texture_api -->|"dispatches GPU work"| node_texture_impl
node_browser -->|"sets options"| node_panel
node_panel -->|"validates settings"| node_controls_model
node_host -->|"reads settings"| node_controls_model
node_host -->|"selects mode"| node_mode_select
node_mode_select -->|"sets geometry"| node_geometry
node_mode_select -->|"opens session"| node_session
node_host -->|"processes frame"| node_session
node_session -->|"uses history"| node_history
node_session -->|"runs inference"| node_model
node_weights -.->|"provides weights"| node_model
node_host -->|"exports output"| node_texture_wrapper
node_host -->|"forms residual"| node_residual
node_residual -->|"returns input"| node_xess
node_host -->|"updates status"| node_telemetry
node_telemetry -->|"reports timing"| node_panel
node_optiscaler -.->|"hooks presentation"| node_present

click node_optiscaler "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/optiscaler/added/nr_live_present.cpp"
click node_panel "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_controls.py"
click node_host "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_pre_xess_host.py"
click node_texture_api "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/native/nr_texture_bridge_v1.h"
click node_texture_impl "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/native/nr_texture_bridge_re8_v1.cpp"
click node_texture_wrapper "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_texture_bridge_v1.py"
click node_controls_model "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_controls.py"
click node_mode_select "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_fullsize.py"
click node_session "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/fullsize_session_v1.py"
click node_geometry "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/re4_session_v1.py"
click node_history "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_history_fused.py"
click node_residual "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_pre_xess_host.py"
click node_telemetry "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_controls.py"
click node_present "https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/optiscaler/added/nr_live_present.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_game,node_optiscaler,node_host,node_residual,node_present,node_browser toneBlue
class node_panel,node_controls_model,node_telemetry toneAmber
class node_mode_select,node_session,node_geometry,node_history,node_model,node_weights toneMint
class node_texture_api,node_texture_impl,node_texture_wrapper toneRose
class node_player,node_xess toneIndigo
```

## Components

### Game integration

- **RE8 renderer**
- [OptiScaler hook](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/optiscaler/added/nr_live_present.cpp): `optiscaler/added/nr_live_present.cpp`
- [Pre-XeSS host](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_pre_xess_host.py): `game/nr_game_pre_xess_host.py`
- [Residual output](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_pre_xess_host.py): `game/nr_game_pre_xess_host.py`
- [Present bridge](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/optiscaler/added/nr_live_present.h): `optiscaler/added/nr_live_present.h`

### Web controls

- [Control panel](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_controls.py): `game/nr_game_controls.py`
- [Validated settings](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_controls.py): `game/nr_game_controls.py`
- [Processing status](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_controls.py): `game/nr_game_controls.py`

### NR processing

- [Mode selection](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_fullsize.py): `game/nr_game_fullsize.py`
- [NR session](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/fullsize_session_v1.py): `game/fullsize_session_v1.py`
- [Geometry contracts](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/re4_session_v1.py): `game/re4_session_v1.py`
- [History and replay](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_game_history_fused.py): `game/nr_game_history_fused.py`
- **NR model runtime**
- **Model weights**

### GPU texture bridge

- [Texture bridge API](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/native/nr_texture_bridge_v1.h): `native/nr_texture_bridge_v1.h`
- [D3D12 texture bridge](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/native/nr_texture_bridge_re8_v1.cpp): `native/nr_texture_bridge_re8_v1.cpp`
- [Python bridge wrapper](https://github.com/gggz114514-oss/re8-b580-nr-xess/blob/main/game/nr_texture_bridge_v1.py): `game/nr_texture_bridge_v1.py`

### Other components

- **Player**
- **Local browser**
- **XeSS upscaler**

## Connections

- Player → RE8 renderer: renders
- RE8 renderer → OptiScaler hook: presents frames
- OptiScaler hook → Pre-XeSS host: dispatches input
- Pre-XeSS host → Python bridge wrapper: prepares textures
- Python bridge wrapper → Texture bridge API: calls API
- Texture bridge API → D3D12 texture bridge: dispatches GPU work
- Local browser → Control panel: sets options
- Control panel → Validated settings: validates settings
- Pre-XeSS host → Validated settings: reads settings
- Pre-XeSS host → Mode selection: selects mode
- Mode selection → Geometry contracts: sets geometry
- Mode selection → NR session: opens session
- Pre-XeSS host → NR session: processes frame
- NR session → History and replay: uses history
- NR session → NR model runtime: runs inference
- Model weights → NR model runtime: provides weights
- Pre-XeSS host → Python bridge wrapper: exports output
- Pre-XeSS host → Residual output: forms residual
- Residual output → XeSS upscaler: returns input
- Pre-XeSS host → Processing status: updates status
- Processing status → Control panel: reports timing
- OptiScaler hook → Present bridge: hooks presentation