The Framebuffer Life Cycle: Frame Cleanup

Summary

Diagnosing Step 0198 has revealed a critical architectural flaw: the C++ framebuffer is never cleared. After the first frame, when the game turns off background rendering (LCDC=0x80), our PPU obeys correctly and stops drawing, but the framebuffer retains the "ghost" data from the previous frame, which is displayed indefinitely creating visual artifacts.

This Step implements the professional solution: a methodclear_framebuffer()in the C++ PPU that is called from the Python orchestrator at the start of each frame, ensuring that each render starts from a clean state. This is a standard computer graphics practice known as "Back Buffer Clearing."

Hardware Concept: The Back Buffer and the Framebuffer Life Cycle

In computer graphics, it is standard practice to clear the "back buffer" (our framebuffer) to a predetermined background color before drawing a new frame. Although the actual Game Boy hardware does this implicitly by redrawing each pixel based on the current VRAM in each screen cycle, our simplified emulation model, which does not redraw if the background is off, must perform this cleanup explicitly.

The "Ghost" Problem:

• In Step 0198, we restore hardware precision: the PPU only renders if theBit 0of theLCDCis active.
• When the Tetris game displays the Nintendo logo, activate the background (LCDC=0x91) and the PPU correctly renders the first frame.
• The game then turns off the background (LCDC=0x80) to prepare the next screen (probably copying new graphics to VRAM).
• Our PPU, now precise, sees that the background is off and immediately returns fromrender_scanline()without drawing anything.
• The problem:The framebuffer is never cleared. Maintains the data of the first frame (the logo) indefinitely.
• When the game modifies VRAM to prepare for the next screen, these changes are partially reflected in the framebuffer, creating a "ghost" mix of old and new data.

The Solution:Implement an explicit framebuffer lifecycle. At the start of each frame, before the CPU starts executing cycles, we clear the framebuffer by setting all pixels to index 0 (white in the default palette). This ensures that each render starts from a clean canvas, just like on real hardware.

Implementation

This Step implements the methodclear_framebuffer()in three layers: C++, Cython and Python.

1. Method in C++ PPU

The public declaration is added inPPU.hpp:

/**
 * Clear the framebuffer, setting all pixels to index 0 (white by default).
 * 
 * This method must be called at the start of each frame to ensure that the
 * rendering starts from a clean state. On real hardware, this occurs
 * implicitly because each pixel is redrawn in each cycle, but in our
 * emulation model, when the background is off (LCDC bit 0 = 0), no
 * renders nothing and the framebuffer retains the data from the previous frame.
 * 
 * Source: Computer Graphics Standard Practice (Back Buffer Clearing).
 */
void clear_framebuffer();

And its implementation inPPU.cpp:

void PPU::clear_framebuffer() {
    // Fill the framebuffer with color index 0 (white in the default palette)
    std::fill(framebuffer_.begin(), framebuffer_.end(), 0);
}

It is required to include<algorithm>to usestd::fill, which is highly optimized for this type of operations.

2. Exposure via Cython

The declaration is added inppu.pxd:

void clear_framebuffer()

And the wrapper inppu.pyx:

def clear_framebuffer(self):
    """
    Clears the framebuffer, setting all pixels to index 0 (white by default).
    
    This method must be called at the start of each frame to ensure that the
    rendering starts from a clean state.
    """
    if self._ppu == NULL:
        return
    self._ppu.clear_framebuffer()

3. Integration into Python Orchestrator

Inviboy.py, inside the methodrun(), the call is added to the start of the frame loop:

while self.running:
    # --- Step 0199: Clear the framebuffer at the start of each frame ---
    # This ensures that each render starts from a clean state.
    # When the game turns off the background (LCDC bit 0 = 0), the PPU does not draw anything
    # but the framebuffer must be clean to avoid "ghost" artifacts.
    if self._use_cpp and self._ppu is not None:
        self._ppu.clear_framebuffer()
    
    # --- Full Frame Loop (154 scanlines) ---
    for line in range(SCANLINES_PER_FRAME):
        #...rest of the loop...

Design Decisions

Why clean at the beginning of the frame and not at the end?Clearing on startup ensures that even if an error occurs or the game does not render anything in a frame, the screen will show a clean (white) state instead of artifacts from the previous frame. It is the standard pattern in graphics rendering.

Why usestd::fillinstead of a manual loop? std::fillis highly optimized by the compiler and can generate vectorized (SIMD) code that is much faster than a manual loop, especially for a 23040 byte buffer.

Why index 0 (white) and not another value?Index 0 corresponds to the lightest color in the standard Game Boy palette. This is the "neutral" value that ensures that if nothing is rendered, we will see a clean, smooth background instead of visual noise.

Affected Files

• src/core/cpp/PPU.hpp- Added method declarationclear_framebuffer()
• src/core/cpp/PPU.cpp- Added implementation ofclear_framebuffer()and include<algorithm>
• src/core/cython/ppu.pxd- Added method declaration for Cython
• src/core/cython/ppu.pyx- Added Python wrapper forclear_framebuffer()
• src/viboy.py- Added call toclear_framebuffer()at the start of the frame loop
• docs/logbook/entries/2025-12-21__0199__cycle-life-framebuffer-cleaning-frames.html- New log entry
• docs/bitacora/index.html- Updated with new entry
• REPORT_PHASE_2.md- Updated with Step 0199

Tests and Verification

The validation of this change is visual and functional:

1. Recompiling C++ module:

   python setup.py build_ext --inplace
   # Or using the PowerShell script:
   .\rebuild_cpp.ps1

   Successful compilation without errors or warnings.
2. Running the emulator:

   python main.py roms/tetris.gb

3. Expected Result:
   • Frame 1: LCDC=0x91. The PPU renders the Nintendo logo. Python shows it correctly.
   • Frame 2 (and following):
     • clear_framebuffer()sets all buffer to0(white).
     • The game putsLCDC=0x80(turns off the background).
     • Our PPU, now precise, sees that the background is off and does not draw anything.
     • Python reads the framebuffer, which is full of zeros (blank).
   • The CORRECT result is a BLANK SCREEN.

Important Note:A blank screen may seem like a step back, but it's a leap forward in accuracy! Confirm that:

• Our framebuffer lifecycle is correct: each frame starts with a clean canvas.
• Our PPU obeys the hardware: when the game turns off the background, it doesn't render anything.
• Once the game progresses and activates the background for the title screen, we'll see it appear on this clean white canvas, with no "ghost" artifacts.

Sources consulted

• Bread Docs:LCD Control Register (LCDC)- LCD control bits, including Bit 0 (BG Display Enable)
• Computer Graphics Standard Practice: "Back Buffer Clearing" - Common pattern in graphics rendering to avoid visual artifacts between frames

Educational Integrity

Next Steps

• [ ] Check the behavior of the emulator when the game activates the background again to show the Tetris title screen
• [ ] Confirm that blank screen is the correct behavior when LCDC Bit 0 is off
• [ ] Investigate if there are any additional registers or bits that control what is displayed when the background is disabled
• [ ] Continue to implement additional PPU features (Window, Sprites, etc.)