Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ jobs:
python3 tools/lower/test_lower.py
python3 tools/xbox/test_vp_encoder.py
python3 tools/xbox/test_tex_convert.py
python3 tools/xbox/test_fog.py

- uses: actions/upload-artifact@v4
with:
Expand Down
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ tools/xbox/docker/build.sh # -> build-xbox/xbe/default.xb
XBOX_CFLAGS="-DXHW_PROF=1" tools/xbox/docker/build.sh # extra platform flags (switch table: docs/testing.md)
python3 tools/xbox/test_tex_convert.py # host tests (tests/xbox/*.c)
python3 tools/xbox/test_vp_encoder.py
python3 tools/xbox/test_fog.py # GX fog math (nv2a_fog.c) vs GX's fog factor
python3 tools/lower/test_lower.py
```

Expand Down
21 changes: 18 additions & 3 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,20 @@ another homebrew's icon and name cached under that ID
(`E:\UDATA\ffff0002\TitleImage.xbx`, `TitleMeta.xbx`). The script writes
both files for 4D580001 next to `default.tbn`.

**GX fog per vertex, from GX's own registers** (`nv2a_fog.c`,
`docs/renderer.md`). The NV2A has no per-pixel depth fog: its fog unit
interpolates a factor the vertex program writes. The vertex program
computes GX's fog amount from each vertex's depth with the registers
`GXSetFog` would write (A and C cut to 11 mantissa bits, b_mag and
b_shift), and the fog unit passes it through (LINEAR, parameters 1, 1, 0);
the final combiner mixes that much fog colour into the colour. Rebuilding
the registers, not the textbook formula, matters for Melee: with its
0.1..16384 camera GX's b_mag rounding makes the fog depth ze up to 1.57
times smaller at the far plane (thinner fog). The cost: GX evaluates fog per pixel, so a polygon spanning a long
depth range gets less fog mid-span than on the GameCube (up to ~23/255 on
long edges), and the EXP curves are linear between vertices.
`GXSetFogRangeAdj` is not applied.

**Vanilla gameplay.** melee-pc's UCF, free camera, frozen stadium,
unlock-all, netplay, Slippi and launcher are off or not built.

Expand Down Expand Up @@ -206,9 +220,10 @@ To sync a newer melee-pc:
rendering on the console with BACK screenshots, not only in xemu.
- **Performance.** Matches draw 13-30 fps on the console while the
simulation keeps 60 ticks (`docs/roadmap.md`).
- **Rendering gaps**: no indirect texturing (water and reflections), no
fog, TEV swap tables only for the alpha broadcast; non-power-of-two
textures are resampled; the texture pool is short on busy stages.
- **Rendering gaps**: no indirect texturing (water and reflections), fog
per vertex (long polygons get less fog mid-span; no range adjustment),
TEV swap tables only for the alpha broadcast; non-power-of-two textures
are resampled; the texture pool is short on busy stages.
- **Netplay** is not built; the online/LAN lobby returns to the menu.
- **The demand-commit fault handler** relies on the Xbox kernel sending
kernel-mode access violations on reserved memory to the thread's SEH
Expand Down
83 changes: 82 additions & 1 deletion docs/renderer.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ game -> GX calls -> gx_state.c (XgxState, dirty bits)
nv2a.c (state diff, pushbuffer, texture pool, vertex ring)
nv2a_vp.c (vertex programs generated from the transform state)
nv2a_rc.c (TEV -> register combiners)
nv2a_fog.c (GX fog -> vertex-program fog, final combiner)
```

Per draw, the back end rebuilds only what the front end's dirty groups
Expand Down Expand Up @@ -160,6 +161,7 @@ Constant rows:
| 70-109 `VPC_LIGHT` | 8 lights x 5 rows: position, direction, colour, angle attenuation, distance attenuation |
| 110-121 `VPC_TEXGEN` | 4 units x 3 rows (s, t, q), post matrix folded in when there is no normalize |
| 122-133 `VPC_POSTMTX` | 4 units x 3 rows, the post-transform matrix after normalize |
| 134-136 `VPC_FOG` | fog numerator, denominator and curve (see Fog) |

Inputs: v0 position, v1 matrix index, v2 normal, v3/v4 colours 0/1, GX
TEX0..6 -> v9..v15, TEX7 -> v8. The front end writes canonical vertices
Expand Down Expand Up @@ -224,10 +226,89 @@ Current limits:
work only in the movie recipe;
- TEV swap tables: only the alpha broadcast (`AAAA`) is supported;
- indirect texturing is ignored (some stage effects);
- fog is off;
- destination alpha is missing at 720p (R5G6B5 has no alpha);
- texture-matrix index attributes (TEXnMTXIDX) are ignored.

## Fog (`nv2a_fog.c`)

GX applies fog after the last TEV stage, to the colour only:
`rgb = (rgb * (256 - F256) + fog * F256) >> 8` with F256 = F * 256. The
fog amount F comes from the pixel's 24-bit EFB depth Zs and the registers
`GXSetFog` writes: A and C cut to 11 mantissa bits, and for perspective fog
B as a 24-bit magnitude and a shift (libogc `GX_SetFog`, Dolphin's
`PixelShaderGen`):

| fog | per pixel |
|---|---|
| perspective (`GX_FOG_PERSP_*`) | `ze = A * 2^24 / (b_mag - (Zs >> b_shift))`: eye depth / (end - start) when the fog's near and far are the projection's |
| orthographic (`GX_FOG_ORTHO_*`) | `ze = A * Zs / 2^24` |
| all | `x = clamp(ze - C, 0, 1)`; LIN `F = x`, EXP `1 - 2^(-8x)`, EXP2 `1 - 2^(-8x^2)`, REVEXP `2^(-8(1-x))`, REVEXP2 `2^(-8(1-x)^2)`; `GX_FOG_NONE`: off |

The NV2A has no per-pixel depth fog. Its fog unit takes oFog.x from the
vertex program per vertex and interpolates the factor (xemu evaluates it
per vertex; `FOG_PARAMS` also goes to the transform engine). So:

- **Vertex program.** F is computed per vertex from the vertex's own depth
with the same registers. Zs / 2^24 is `(a . P) / (w . P)` for the
view-space position P and the projection's depth and w rows (`VPC_PROJ`
+ 2 and + 3), so `ze - C` is a ratio of two linear functions of P: rows
`VPC_FOG` and `VPC_FOG + 1`, built by `fog_setup` when the fog or the
projection changes. EXP and EXP2 clamp x and evaluate `2^(-8u)` with
`expp` (the REV types use 1 - x; the curve's constants are in
`VPC_FOG + 2`). `VpKey.fog` selects the variant (off, linear, exp,
exp2); fog makes a program 4 (LIN) to 10 (EXP2) instructions longer, so
a program already near the NV2A's 136 drops lights sooner.
- **Fog unit.** LINEAR, `FOG_PARAMS` (1, 1, 0): the linear mode computes
`p0 + p1 * oFog - 1` (nxdk's NV10 notes, xemu's `fogFactor -= 1.0`), so
the factor is F, clamped to 0..1 per pixel. nxdk_pgraph_tests' vertex
shader fog tests use the same setup; they also found that the gen mode
doesn't matter with a vertex program. The NV2A's EXP modes aren't used:
they are evaluated per vertex as well, and EXP's zero point measures
~1.51 on hardware where the formula says 1.5.
- **Final combiner.** CW0 becomes A = FOG.a (the factor), B = FOG.rgb (the
fog colour, `SET_FOG_COLOR` is ABGR), C = PREV, D = 0; alpha (CW1's G)
is untouched. Without fog CW0 is what `nv2a_rc.c` compiled, and
unfogged vertex programs are the same as before (checked on 200000
random keys).
- **State.** Fog is sent only when `GXSetFog` changed something
(`XGX_DIRTY_FOG`; `GXSetFog` returns early on equal values like the other
setters, as HSD calls it for every camera pass and particle kind) or the
projection changed while fog is on.

Accuracy (`tools/xbox/test_fog.py`, against libogc's registers and
Dolphin's formula): at every vertex F is within 1/255 of what GX gives
within one of its own depth steps. With Melee's 0.1..16384 game camera GX
resolves fog coarsely: `b_mag - (Zs >> 2)` is 99 steps at depth 5000 and 41
at the far plane, and b_mag rounds B up (8388638 / 2^23), which makes GX's
ze up to 1.57 times smaller at depth than the textbook formula (thinner
fog). The port reproduces both at the vertices. Between vertices the NV2A
interpolates F linearly in view space, which is exact for LIN fog while
b_mag's rounding is negligible (the test checks edges for most cameras).
With Melee's camera GX's denominator grows by ~57% from near to far, so a
polygon that spans a long depth range gets less fog mid-span than on the
GameCube: up to ~23/255 on an edge from depth 2000 to 14000 through a
narrow fog range. The EXP curves are also linear between vertices.

`GXSetFogRangeAdj` (a horizontal correction toward radial distance, which
HSD sets when a fog has a FogAdj descriptor) is not applied.

Melee sets fog in these places (`HSD_FogSet`), all compared best against
Dolphin:

- stages: `Ground_801C1E94` loads the stage's fog descriptor (scaled by the
stage's `param->y`; its colour is also the clear colour) and
`Ground_801C1E2C` applies it for the stage's camera passes while
`stage_info.unk8C.b2` holds (set at stage load; Final Destination's
`grlast.c` clears it). The camera turns it off for its later passes
(`camera.c`);
- particles whose kind has `DispFog` (`psdisp.c`);
- the title screen (`ScTitle_fog`), the Classic and All-Star intros
(`gm_1832.c`, `gm_186E.c`), Tournament mode (`gmtou_*.c`), the 1P ending
(`gmregenddisp.c`), the staff roll, Adventure cutscenes (`vi0102`,
`vi0401`, `vi0501`, `vi0502`, `vi0801`, `vi1201v1`, `vi1201v2`) and the
trophy display (`ScMenDisplay_fog`, `tydisplay.c`; `toy.c`'s own white
fog is a debug-ROM feature).

## Textures (`gx_tex.c`, `nv2a.c`)

- GX textures are converted once and cached, keyed by data pointer, size,
Expand Down
8 changes: 6 additions & 2 deletions docs/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,9 @@
- [x] memory fit measured on hardware (boot.log `[MEM]`); disc-backed ARAM pages
- [x] 4-CPU VS matches stable on hardware (Pokémon Stadium with transformations,
Fountain of Dreams, Green Greens), audio, saves, 100% save file loads
- [ ] fog, indirect texturing, TEV swap tables beyond alpha broadcast
- [x] fog: every GX fog type, per vertex from GX's registers (`nv2a_fog.c`); not yet
compared with Dolphin on the console; no range adjustment
- [ ] indirect texturing, TEV swap tables beyond alpha broadcast
- [ ] VS mode with 4 players on hardware at 60 fps
- [x] movie frames decoded (`thp.c`)
- [x] dashboard icon (`$$XTIMAGE` + `default.tbn`, own title ID 4D580001)
Expand Down Expand Up @@ -63,7 +65,9 @@ Fixed on the console this round (details in `renderer.md`,

1. **Texture accuracy.** Fountain of Dreams' water and other reflections
need indirect texturing (the NV2A's texture-shader bump modes may do
it); fog and TEV swap tables beyond the alpha broadcast. Item crates
it); TEV swap tables beyond the alpha broadcast. Fog is new: compare
stage backgrounds, the title screen and the Classic/All-Star intros
with Dolphin (`docs/renderer.md` lists where Melee uses it). Item crates
still show the background through their dark gaps. Short black flashes
remain on Stadium's floor. For each, take a console screenshot (BACK)
and compare with xemu at the same scene (`docs/testing.md`).
Expand Down
5 changes: 3 additions & 2 deletions docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,10 @@
tools/lower/test_lower.py # disc_lower vs GCC scalar_storage_order (needs GCC 12+)
tools/xbox/test_vp_encoder.py # vertex-program encoder vs nv2a-vsh (pip install nv2a-vsh)
tools/xbox/test_tex_convert.py # native texture formats vs the GX decoder
tools/xbox/test_fog.py # GX fog on the NV2A vs GX's fog factor (libogc registers, Dolphin's formula)
```

CI (`.github/workflows/build.yml`) runs all three after building
CI (`.github/workflows/build.yml`) runs all four after building
`default.xbe`, and uploads the XBE with its link map.

## Running it
Expand Down Expand Up @@ -246,7 +247,7 @@ report.
| `-DXGX_EFB_GPU_COPY=0` | EFB copies read back on the CPU instead of drawn by the GPU |
| `-DXGX_DEPTH_CULL=1` | cull pixels whose depth falls outside the clip range instead of clamping it (the pre-v15 behaviour) |
| `-DXGX_DEBUG_EFBLOG` | log the first 200 EFB copies (source rect, size, format) as `[EFB]` lines |
| `-DXGX_DEBUG_TRACE` | log every draw (TEV stages, textures, texgens, blend) of the frame an autopad `SHOT` dumps, as `[DRAW]` lines |
| `-DXGX_DEBUG_TRACE` | log every draw (TEV stages, textures, texgens, blend, fog) of the frame an autopad `SHOT` dumps, as `[DRAW]` lines |
| `-DXGX_DEBUG_NOMIP` | bind only the base level of every texture |
| `-DXHW_FBDUMP_EVERY=<n>` | screenshot every n presented frames |
| `-DXGX_STATS_EVERY=<n>` | `[NV2A]` / `[TEX]` stats period, in frames (default 600) |
Expand Down
Loading
Loading