Fix: Frame_ready communication C++ -> Python

Summary

After unlocking the main loop (Step 0122), the emulator was running correctly in the console ("Heartbeat" logs visible), but the Pygame window remained blank or did not appear. Diagnostics revealed that although the PPU in C++ was advancing correctly and reaching V-Blank, there was no way to tell Python that a frame was ready to render.

The problem was that the render loop in `viboy.py` depended on `self.ppu.is_frame_ready()`, but the existing method was not being called correctly or was not properly exposed from C++ to Python. Renamed the method to `get_frame_ready_and_reset()` for clarity and verified that the communication signal works correctly throughout the C++ → Cython → Python chain.

Hardware Concept

On the real Game Boy, when the PPU completes the 144 visible lines and enters V-Blank (line 144), a V-Blank interrupt is fired notifying the CPU that a full frame is ready. The game software can then update sprites, tilemaps, and other graphical resources during the V-Blank period (lines 144-153, approximately 1.1ms).

The problem in the emulator:In a hybrid Python/C++ architecture, we need a synchronization mechanism that allows the C++ core (PPU) to communicate to the Python frontend (renderer) that a frame is ready. This communication must be:

• Thread-safe:Although in this case there are no threads, the pattern must be safe
• Non-blocking:The main loop should not wait
• Single use:Each frame must be rendered exactly once
• Efficient:No significant overhead in the critical loop

The solution:Implement a "one-time state machine" pattern using a boolean flag (`frame_ready_`) in C++ that is raised when `LY == 144` and automatically lowered when Python queries the state. This ensures that:

• C++ raises the flag once per frame (when it reaches V-Blank)
• Python queries flag on each loop iteration
• The flag is automatically reset after being read (avoids duplicate renderings)
• If Python doesn't query in time, the next frame just overwrites the flag (correct behavior)

Implementation

The `is_frame_ready()` method already existed in the C++ implementation, but was renamed to `get_frame_ready_and_reset()` for clarity on its behavior. It was verified that the entire communication chain works correctly:

1. C++ (PPU.cpp) - Raise the Flag

In the `step()` method, when the PPU reaches V-Blank (line 144), the flag is raised:

// If we reach V-Blank (line 144), request interruption and mark frame ready
if (ly_ == VBLANK_START) {
    //...V-Blank interrupt code...
    
    // CRITICAL: Mark frame as ready to render
    frame_ready_ = true;
}

2. C++ (PPU.cpp) - Query and Reset the Flag

The `get_frame_ready_and_reset()` method implements the "one-time state machine" pattern:

bool PPU::get_frame_ready_and_reset() {
    if (frame_ready_) {
        frame_ready_ = false;
        return true;
    }
    return false;
}

3. Cython (ppu.pxd) - Declaration

Updated the declaration in the `.pxd` file to expose the method to Cython:

cdef cppclass PPU:
    #...other methods...
    bool get_frame_ready_and_reset()

4. Cython (ppu.pyx) - Python Wrapper

Updated the Cython wrapper to expose the method to Python:

def get_frame_ready_and_reset(self):
    """
    Checks if there is a frame ready to render and resets the flag.
    
    Implements a "one-time state machine" pattern: if the flag
    is up, returns it as true and immediately lowers it to false.
    
    Returns:
        True if there is a frame ready to render, False otherwise
    """
    return self._ppu.get_frame_ready_and_reset()

5. Python (viboy.py) - Render Loop

Updated the main loop to use the new method:

#3. Rendering if V-Blank
if self._ppu is not None:
    # Check if frame is ready (different method depending on core)
    frame_ready = False
    if self._use_cpp:
        frame_ready = self._ppu.get_frame_ready_and_reset()
    else:
        frame_ready = self._ppu.is_frame_ready() # PPU Python keeps old name
    
    if frame_ready:
        if self._renderer is not None:
            self._renderer.render_frame()
            pygame.display.flip()

Design Decisions

• Method renaming:Changed from `is_frame_ready()` to `get_frame_ready_and_reset()` to make it explicit that the method has side effects (resets the flag). This improves readability and avoids confusion.
• PPU Python support:Kept the old name `is_frame_ready()` for the Python PPU (fallback) so as not to break existing code.
• "Single-use state machine" pattern:This pattern ensures that each frame is rendered exactly once, avoiding duplicate renders or loss of synchronization.

Affected Files

• src/core/cpp/PPU.hpp- Renamed `is_frame_ready()` method to `get_frame_ready_and_reset()`
• src/core/cpp/PPU.cpp- Renamed method implementation
• src/core/cython/ppu.pxd- Updated Cython declaration
• src/core/cython/ppu.pyx- Updated Python wrapper
• src/viboy.py- Updated rendering loop to use new method

Tests and Verification

Verification was performed by manually running the emulator:

• Command executed: python main.py tu_rom.gbc
• Expected result:The Pygame window should appear and display the game content
• Validation:The "Heartbeat" logs should show `LY` going from 0 to 153, and the window should update to 60 FPS

Compiled C++ module validation:Verified that the `.pyd` binary recompiles correctly after the changes by running:

python setup.py build_ext --inplace

Diagnosis:If the log `[PPU C++] STEP LIVE` appears in the console, it confirms that the C++ code is running. If the window appears and refreshes, it confirms that the C++ → Python communication is working correctly.

Sources consulted

• Bread Docs:LCD Timing, V-Blank
• Cython documentation:C++/Python interface

Educational Integrity

Next Steps

• [ ] Verify that rendering works correctly with real ROMs
• [ ] Optimize the render loop if necessary
• [ ] Implement Audio Sync (APU) where applicable
• [ ] Consider implementing threading for audio if performance requires it