⚠️ 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.

The Missing Link: Fixing render_frame

Date:2025-12-22 StepID:0217 State: draft

Summary

The Step 0216 diagnostic confirmed that the entire pipeline is working correctly: C++ writes the value `3` (Red in our debug palette), Python receives it correctly, and the palette has the `3` mapped to `(255, 0, 0)` (Red). However, the screen looksLIGHT GREEN(Color 0), indicating that the `render_frame` method is ignoring framebuffer data or silently failing to draw it.

This step implements a robust and explicit version of `render_frame` that iterates pixel by pixel over the 1D linear buffer to ensure that each value is processed correctly. The implementation uses `pygame.PixelArray` with explicit closure instead of the context manager for greater control and debugging.

Hardware Concept

The PPU C++ framebuffer is a 1D linear array of 23040 bytes (160 × 144 pixels), where each byte represents a color index (0-3). The organization is:

pixel (y, x) is at index [y * 160 + x]

The Python renderer should convert these indices to RGB colors using the palette BGP (Background Palette Register, 0xFF47) and draw them on a Pygame surface of 160x144 pixels, which is then scaled to the main window.

If the render method fails silently or does not process the buffer correctly, the screen will show the default background color (light green, index 0) instead of the actual framebuffer data.

Implementation

Replaced the section of the `render_frame` method that renders the C++ framebuffer with an explicit implementation that uses a double (y, x) loop to iterate over each pixel of the linear buffer.

Modified components

  • src/gpu/renderer.py: Methodrender_frame()- Replacing C++ framebuffer rendering logic with explicit loop

Technical changes

Before:A context manager was used (`with pygame.PixelArray()`) that it could be failing silently or not applying changes correctly.

After:`pygame.PixelArray` is used with explicit closure via `px_array.close()`, ensuring that changes are applied to the surface before to scale it and show it.

The loop explicitly iterates over each pixel (y, x), calculates the linear index, gets the color index from the framebuffer, maps it to RGB using the palette, and writes the pixel on the surface. This is slower than using vectorized operations of NumPy, but ensures that each pixel is rendered correctly.

Affected Files

  • src/gpu/renderer.py- Replaced C++ framebuffer rendering logic (lines 508-530)

Tests and Verification

Visual Validation:Executepython main.py roms/tetris.gband verify that the screen showsSOLID RED(or red stripes if keeps the debug code from Step 0216).

If you see the red screen, confirm that:

  • C++ framebuffer reads correctly
  • Color indices map correctly to RGB
  • Pixels are written correctly to the Pygame surface
  • The surface is scaled and displayed correctly

Next step:Once confirmed that the red screen is displayed, remove debug hacks (force red, force byte=0xFF in PPU.cpp) and restore normal rendering logic to see the actual game graphics.

Sources consulted

  • Pygame Documentation:PixelArray
  • Pan Docs: LCD Control Register, Background Rendering

Educational Integrity

What I Understand Now

  • Linear Framebuffer:The C++ framebuffer is a 1D array where the pixel (y, x) is at index [y * 160 + x]. This organization is standard for video buffers.
  • PixelArray and Explicit Closure:`pygame.PixelArray` requires an explicit close (`close()`) to apply changes to the surface. The context manager should do this automatically, but explicit closure guarantees the behavior.
  • Visual Debugging:When the data pipeline works but the display fails, the problem is with the renderer. An explicit loop helps isolate the problem.

What remains to be confirmed

  • Performance:Explicit looping is slow in pure Python. Once confirmed that it works, it can be optimized with NumPy/Surfarray for better performance.
  • Buffer format:Verify that the C++ framebuffer is in the expected format (uint8_t, indices 0-3, linear organization).

Hypotheses and Assumptions

Main Hypothesis:The context manager `with pygame.PixelArray()` It wasn't applying the changes correctly, or there was a sync issue between surface blocking and pixel writing. The explicit closure ensures that changes are applied before scaling and displaying the surface.

Next Steps

  • [ ] Visually confirm that the red screen is displayed correctly
  • [ ] Remove debug hacks (force red in renderer.py, force byte=0xFF in PPU.cpp)
  • [ ] Restore normal VRAM rendering logic in PPU.cpp
  • [ ] Verify that the actual game graphics are displayed correctly
  • [ ] Optimize render loop with NumPy/Surfarray for better performance