fast3d: clamp MSAA to GL_MAX_SAMPLES and bind the default framebuffer as GL name 0 (PR #106, italoarruda; security-reviewed 2026-09-28, D405)

Port-layer only: resolve_msaa_color_buffer clamps msaa_level to the driver's
GL_MAX_SAMPLES (pre-fix: unallocated multisample renderbuffers -> black
screen when MSAA is set beyond driver support); the resolve/copy paths now
bind current_framebuffer ? framebuffers[i].fbo : 0 (the default framebuffer
is GL name 0, not framebuffers[0]). Affects both Windows (opengl32) and
Linux builds. Code file from the PR head (fc092d99); docs in house style,
label rebased D323 -> D405 (collision with our G_TL_LOD finding).

docs/dev/findings-index.csv

@@ -281,3 +281,4 @@ D401,CLOSED,Rumble Pak → real gamepad haptics (re-promotes D224/M-87):,CLOSED
 D402,RESOLVED,First clean Linux (glibc / SteamOS) build of release/v0.4.0 broke in two port-layer include-resolution spots MinGW tolerated (bondconstants.h first-include cyc…,RESOLVED (Linux/Ubuntu-24.04 build → glibc-2.41-compatible binary for the Steam Deck):
 D403,RESOLVED,Deck v0.4.0-pre test:,"RESOLVED (2026-09-27, user-confirmed on the Deck:"
 D404,RESOLVED,"""Aim style: Centred (PC)"" (Input.AimMode=1, D333/D337) has no effect when aiming with a gamepad; the row's own doc comment over-promises (""applies to every aim…","RESOLVED (2026-09-28, port-layer only):"
+D405,?,"fast3d/OpenGL: MSAA above the driver max black-screens; two glBindFramebuffer calls pass an index where a GL name is required (PR #106, italoarruda, 2026-09-25…",full ## D405 entry at file tail

docs/dev/findings.md

@@ -689,6 +689,7 @@ covers D24–D69; the log continues in §H (D32 procedure, D70–D121).
 | D402 | **First clean Linux (glibc / SteamOS) build of `release/v0.4.0` broke in two port-layer include-resolution spots MinGW tolerated (`bondconstants.h` first-include cycle; `video.c` `_SHIFTL`); fixed in `port/shim/` only, no `src/` edits, no rule-2 (2026-09-27).** Full `## D402` entry at file tail. | RESOLVED (Linux/Ubuntu-24.04 build → glibc-2.41-compatible binary for the Steam Deck): three `port/shim/` fixes — `PR/ucode.h` + `bondconstants.h` defer `pc_protos.h`/`bondtypes.h` during `bondconstants.h`'s own `ultra64.h` pass (breaks the `bondconstants.h`→`ultra64.h`→`pc_protos.h`→`bondtypes.h`→`bondconstants.h` re-entry); `PR/gbi.h` defines `_SHIFTL`/`_SHIFTR` when absent (the `gbi.h` macros in `video.c` lost their `mbi.h` definitions on Linux). Builds + links clean on Ubuntu-24.04; bundled `libSDL2` with `rpath=$ORIGIN`; pushed to the Deck. Shim files uncommitted at log time. |
 | D403 | **Deck v0.4.0-pre test: Nintendo logo + copyright/legal page render broken, broader graphics "not reflecting new updates" — stale 0.3.0-era sidecars seeded into the bundle (2026-09-27).** Full `## D403` entry at file tail. | RESOLVED (2026-09-27, user-confirmed on the Deck: a stale-sidecar **test artifact**, never a code regression): the Deck bundle was seeded with `pcmodels`/`pccg` sidecars from the `0.3.0-local` install (data dated 2026-09-15), which predate the D75/M-197 embedded-blob raw-pixel fix (commit `425237f9`, 2026-09-21) and the D303 muzzle-vertex converter fix (2026-09-26) → the `P*` front-end logo/legal textures come out broken while the in-exe fast3d fixes (D397 gun-barrel/file-select) render correctly. Disambiguation performed (2026-09-27): `data/pcmodels-ntsc-final` + `data/pccg-ntsc-final` regenerated from the Python-source converter (`prepare-assets.py` + the current `d43/d69/d88_emit.py`, `ALL CHECKS PASSED`) on the NTSC ROM and pushed to the Deck (sha256-verified), preserving the user's `ge007.eep`/`ge007.ini`. **RESOLVED (user-confirmed on the Deck, 2026-09-27): the front-end logo / copyright / legal page now render correctly — confirming this was the stale-sidecar test artifact, not a code regression.** |
 | D404 | **"Aim style: Centred (PC)" (`Input.AimMode=1`, D333/D337) has no effect when aiming with a gamepad; the row's own doc comment over-promises ("applies to every aim input … pad trigger") but the centred path is mouse-only (Steam Deck, 2026-09-27).** Full `## D404` entry at file tail. | RESOLVED (2026-09-28, port-layer only): the toggle now genuinely works on a pad. First logged as a communication bug and closed by relabel ("Aim style (mouse)"), then reopened on user challenge the same day: the pad path emits stick *deflection* into the game's crosshair integrator, so the pad was actually always in the **N64** model (a flick travels the crosshair; edge-scroll + spring-back only made a hold *feel* direct), and the "stick has no crosshair to travel" rationale was wrong. Fix: new `padDirectCompute()` in `input.c` (the pad twin of `hipDirectCompute`'s CENTRED branch -- same dead/watch/pause/cutscene gates, minus the mouse-grab gate; revised same day to the N64 path's verbatim quadratic curve -- `sign(v)\u00b7clamp(defl/70,\u00b11)\u00b2 \u00b7 (fov/60) \u00b7 3.5 deg/poll` (bondview2.c canNaturalTurn/canNaturalPitch), full-stick parity with the N64 path, pending retest on the refreshed build); the natural-pitch pad branch routes CENTRED through it and keeps N64's classic deflection behaviour (also the default, so no pad default changes). Labels reverted to device-neutral ("Aim style" / "Aim range"). **Steam Deck (2026-09-27/28): "centered aim is broken on deck too" -- fixed for real; the first-pass linear gain was measured as a dramatic sensitivity loss (2026-09-28) and replaced with the N64 path's verbatim quadratic curve (fov/60 base, 3.5 deg/poll top rate); retest on the refreshed build: user "good". RESOLVED.** |
+| D405 | **fast3d/OpenGL: MSAA above the driver max black-screens; two `glBindFramebuffer` calls pass an index where a GL name is required** (PR #106, italoarruda, 2026-09-25; label rebased from the PR's D323, which collides with our D323 LOD finding) | full `## D405` entry at file tail | **CLOSED (2026-09-28).** Merged from PR #106 (code file only; security-reviewed clean - port-layer GL state fixes, no external input, no allocations). `resolve_msaa_color_buffer` clamps `msaa_level` to `GL_MAX_SAMPLES`; the resolve/copy paths bind `current_framebuffer ? framebuffers[i].fbo : 0` (the default framebuffer is GL name 0). Both Windows (opengl32) and Linux use this backend. Post-merge sweep + MSAA>max boot check: see entry. |
 
 
 Phase 2 replaced the Phase-1 demo loop with the real `mainproc()` on real OS
@@ -15452,6 +15453,19 @@ So the broken logo + copyright page + "a lot of graphics not updated" are **stal
 
 **Cross-refs:** D333 (#104 centred aim origin), D337 (device-aware aim integration; the "mouse-active only" gate), D338 (`Input.AimRange` hidden-in-Centred), D403 (same Deck session's other observations), `input.c:1783` / `optionsoverlay.c` Aim-style row.
 
+
+## D405 — fast3d/OpenGL MSAA clamp + default-framebuffer bind (PR #106, italoarruda, security-reviewed and merged 2026-09-28; label rebased from the PR's D323)
+
+**PR #106 (merged into v0.4.0).** Two `port/fast3d/gfx_opengl.cpp` fixes, both latent in the shipped renderer (Windows *and* Linux use the OpenGL backend):
+
+1. `resolve_msaa_color_buffer`: `glRenderbufferStorageMultisample` with a `msaa_level` above the driver's `GL_MAX_SAMPLES` silently leaves the renderbuffers unallocated -> black screen when the user sets MSAA beyond what the GPU/driver offers (common on integrated GPUs and old IGP drivers). Fix: clamp `msaa_level` to `GL_MAX_SAMPLES` (queried once) before allocating.
+2. Two `glBindFramebuffer(GL_FRAMEBUFFER, ...)` calls passed the *index* `current_framebuffer` (or `framebuffers[current_framebuffer]` while `current_framebuffer == 0`) where a GL *name* is required: when `current_framebuffer == 0` the call must bind `0` (the default framebuffer), not `framebuffers[0].fbo`. Binding index 1-3 as a raw name hits whatever unrelated GL object (or an invalid name -> GL error) that number holds.
+
+**Security review (2026-09-28, per the unvetted-contributor policy):** port-layer only, three hunks, no external input, no allocations, no control-flow changes beyond the clamp; N64 build untouched; no game-code edits. Clean. Integrated by cherry-pick of the PR head's code file (`fc092d99`); the PR's docs hunks were superseded by our canonical findings log, and its D323 label rebased to D405 (our D323 is the G_TL_LOD finding).
+
+**Verification (2026-09-28):** post-merge 21-level sweep PASS; boot check with MSAA set above `GL_MAX_SAMPLES` renders (pre-fix: black screen on affected drivers).
+
+**Status:** CLOSED (merged to v0.4.0, 2026-09-28).
 ## v0.4.0 campaign playtest sign-off (2026-09-28, user -- full campaign, Steam Deck + physical pad)
 
 The user walked the v0.4.0 release checklist end-to-end and reported (item = user verdict):

port/fast3d/gfx_opengl.cpp

@@ -1230,6 +1230,20 @@ static void gfx_opengl_update_framebuffer_parameters(int fb_id, uint32_t width,
     width = max(width, 1U);
     height = max(height, 1U);
 
+    /* macOS GL 4.1 core: asking for more samples than GL_MAX_SAMPLES (e.g. 8x)
+     * makes the multisample renderbuffers incomplete and the screen goes dark
+     * (glReadPixels 0x506). Clamp to what the driver reports. */
+    if (msaa_level > 1) {
+        static GLint maxSamples = -1;
+        if (maxSamples < 0) {
+            glGetIntegerv(GL_MAX_SAMPLES, &maxSamples);
+            if (maxSamples < 1) maxSamples = 1;
+        }
+        if ((GLint)msaa_level > maxSamples) {
+            msaa_level = (uint32_t)maxSamples;
+        }
+    }
+
     if (gfx_framebuffers_enabled) {
         glBindFramebuffer(GL_FRAMEBUFFER, fb.fbo);
 
@@ -1326,7 +1340,8 @@ void gfx_opengl_resolve_msaa_color_buffer(int fb_id_target, int fb_id_source) {
     glBindFramebuffer(GL_READ_FRAMEBUFFER, fb_src.fbo);
     glBlitFramebuffer(0, 0, fb_src.width, fb_src.height, 0, 0, fb_dst.width, fb_dst.height, GL_COLOR_BUFFER_BIT,
                       GL_NEAREST);
-    glBindFramebuffer(GL_FRAMEBUFFER, current_framebuffer);
+    /* current_framebuffer is an INDEX into framebuffers[], not a GL name; fb 0 is the window's default framebuffer (name 0). */
+    glBindFramebuffer(GL_FRAMEBUFFER, current_framebuffer == 0 ? 0 : framebuffers[current_framebuffer].fbo);
     glEnable(GL_SCISSOR_TEST);
 }
 
@@ -1390,7 +1405,7 @@ void gfx_opengl_copy_framebuffer(int fb_dst, int fb_src, int left, int top, bool
 
     glBlitFramebuffer(srcX0, srcY0, srcX1, srcY1, dstX0, dstY0, dstX1, dstY1, GL_COLOR_BUFFER_BIT, GL_NEAREST);
 
-    glBindFramebuffer(GL_FRAMEBUFFER, framebuffers[current_framebuffer].fbo);
+    glBindFramebuffer(GL_FRAMEBUFFER, current_framebuffer == 0 ? 0 : framebuffers[current_framebuffer].fbo);
 
     glReadBuffer(GL_BACK);