⚠️ Clean-Room / Educational

This project is educational and Open Source. No code is copied from other emulators. Implementation based solely on technical documentation and permitted tests.

Extended Verification and Framebuffer Monitor

Date:2025-12-25 StepID:0304 State: DRAFT

Summary

Implementing framebuffer monitors with trigger flags to track what indexes the framebuffer has in each frame and detect when it changes from having only indices 0 to having indices 1 or 2. The monitors are ready but disabled by default, and will only be activated if the extended visual check (10-15 minutes) confirms that the green streaks persist after Step 0303 corrections.

Aim: Verify that palette corrections removed green streaks during a session extended. If the streaks appear, the monitors will allow you to identify when and why the framebuffer changes.

Hardware Concept

Framebuffer and Color Indices

The framebuffer containscolor indices(0-3), not RGB colors directly. These indices are mapped to colors using a palette. If the framebuffer changes from having only indices 0 to having indices 1 or 2, it means that the PPU is writing different values to the framebuffer.

Under normal conditions, the framebuffer should mainly have 0 (blank) indices when there are no graphics, or a mix of indices 0-3 when there are rendered graphics. If green streaks appear after a few minutes, it means that the framebuffer is receiving values 1 or 2 that are incorrectly being mapped to green (instead of gray).

Framebuffer trace

Monitoring the contents of the framebuffer allows you to identify when and where specific values ​​are written. The monitors They must be efficient so as not to affect performance, so they only trace when there are changes or at regular intervals (every 1000 frames).

Fountain: Pan Docs - "Framebuffer", "Background Palette (BGP)"

Implementation

Two framebuffer monitors with activation flags were implemented:

Monitor in Python (renderer.py)

Monitor[FRAMEBUFFER-INDEX-TRACE]which tracks what indices the framebuffer has in each frame:

  • Counts how many pixels each index has (0, 1, 2, 3)
  • Detects if there are non-zero values ​​(1, 2 or 3)
  • Records information only when there are changes or every 1000 frames
  • Limit to 100 records to avoid saturating the logs

Activation flag: self._framebuffer_trace_enabled = False(change totrueif logs are needed)

Monitor in C++ (PPU.cpp)

Monitor[FRAMEBUFFER-DETAILED]which monitors the framebuffer from the C++ side:

  • Tracks the center line (LY=72) every 1000 frames
  • Counts non-zero pixels on the center line
  • Shows a sample of the first 32 pixels
  • Limit to 100 records to avoid saturating the logs

Activation flag: ENABLE_FRAMEBUFFER_DETAILED_TRACE = false(change totrueif logs are needed)

Design Decisions

  • Activation flags: Monitors are disabled by default so as not to affect performance. They are only activated if visual verification confirms that the stripes appear.
  • Registration limits: They are limited to 100 records to avoid saturating the context and the logs.
  • Trace intervals: They only track every 1000 frames or when there are changes, to minimize overhead.
  • Center line: The C++ monitor tracks the center line (LY=72) as a representative sample of the framebuffer.

Affected Files

  • src/gpu/renderer.py- Implementation of the [FRAMEBUFFER-INDEX-TRACE] monitor with activation flag
  • src/core/cpp/PPU.cpp- Implementation of the [FRAMEBUFFER-DETAILED] monitor with activation flag
  • INSTRUCTIONS_VERIFICATION_STEP_0304.md- Instructions for extended visual verification

Tests and Verification

Extended Visual Verification: Pending execution. The user must run the emulator for 10-15 minutes to check if the green streaks appear after the corrections in Step 0303.

Instructions: View fileINSTRUCTIONS_VERIFICATION_STEP_0304.mdfor detailed steps verification.

Monitors: Monitors are implemented but disabled by default. They will only be activated if the Visual verification confirms that the stripes appear.

Sources consulted

  • Pan Docs: "Framebuffer", "Background Palette (BGP)"
  • Step 0303: Correction of Debug Palette Indexes 1 and 2

Educational Integrity

What I Understand Now

  • Framebuffer and indexes: The framebuffer contains color indices (0-3), not RGB colors. These indices are mapped to colors using a palette.
  • Efficient monitoring: Monitors must be efficient so as not to affect performance. They only track when there are changes or at regular intervals.
  • Activation flags: Monitors are disabled by default and are only activated if needed, to avoid unnecessary overhead.

What remains to be confirmed

  • Visual verification: Did the fixes in Step 0303 remove the green stripes? Extended verification pending (10-15 minutes).
  • Source of values ​​1 and 2: If streaks appear, the monitors will help identify when and why the framebuffer changes from having only indices 0 to having indices 1 or 2.

Hypotheses and Assumptions

Hypothesis: The fixes in Step 0303 should remove the green stripes, since all palettes debug now use true grays instead of green for indices 1 and 2. If the stripes persist, it means that There is another source of the problem (possibly in the C++ PPU or in how values are written to the framebuffer).

Next Steps

  • [ ] Run extended visual check (10-15 minutes) with Pokémon Red
  • [ ] Record observations: Do green streaks appear? When? How do they look?
  • [ ] If NO streaks appear: Document success and continue with other features
  • [ ] If stripes DO appear: Activate monitors and run with captured logs
  • [ ] Analyze logs (if captured) to identify when and why the framebuffer changes
  • [ ] Generate executive summary with findings and conclusions
  • [ ] Step 0305 (if needed): Investigate PPU C++ code to identify where values ​​1 or 2 are written