This project is educational and Open Source. No code is copied from other emulators. Implementation based solely on technical documentation and permitted tests.
Graphic Architecture: Framebuffer Synchronization with V-Blank
Summary
Diagnosing Step 0199 confirmed a race condition: the framebuffer is cleared from Python before the PPU has time to draw, resulting in a white screen. Although the first frame (the Nintendo logo) is rendered correctly, subsequent frames are displayed blank because the cleanup occurs asynchronously to the emulated hardware.
This Step solves the problem architecturally: the responsibility for clearing the framebuffer is moved from Python to C++, being activated precisely when the PPU starts rendering a new frame (whenL.Y.resets to 0). This synchronization eliminates the race condition and ensures that the framebuffer is always clear just before the first pixel of the new frame is drawn.
Hardware Concept: Vertical Scan Synchronization (V-Sync)
The Game Boy's rendering cycle is immutable. The PPU draws 144 visible lines (LY 0-143) and then enters the V-Blank period (LY 144-153). When the cycle ends,L.Y.resets to0to start the next frame. This moment, thechange LY to 0, is the hardware vertical sync (V-Sync) "pulse." It is the guaranteed starting point for any new frame rendering operation.
By anchoring our logicclear_framebuffer()to this event, we remove the race condition. Cleaning will occur within the same hardware "tick" that initiates drawing, ensuring that the canvas is always clean just before the first pixel of the new frame is drawn, but never before.
The Race Condition of Step 0199:
- Frame 0:Python calls
clear_framebuffer()→ C++ buffer fills with zeros → CPU executes ~17,556 instructions → ROM setsLCDC=0x91→ PPU renders the Nintendo logo → Python displays the logo (visible for 1/60s). - Frame 1:Python calls
clear_framebuffer()→ The C++ buffer is cleared immediately → The CPU executes instructions → The game setsLCDC=0x80(background off) → PPU draws nothing → Python reads framebuffer (full of zeros) → White screen.
The Architectural Solution:The responsibility for clearing the framebuffer should not be on the main Python loop (which is asynchronous to the hardware), but on the emulated hardware itself. The PPU must clear its own canvas just as it is about to start drawing a new frame. And when does that happen? Exactly when the scan line (L.Y.) is again0.
Implementation
This Step moves the framebuffer clearing logic from the Python orchestrator to the C++ PPU, synchronizing it with the reset ofL.Y.to 0.
1. Modification in PPU::step() (C++)
Insrc/core/cpp/PPU.cpp, inside the methodstep(), we add the call toclear_framebuffer()just whenly_resets to 0:
// If we pass the last line (153), reset to 0 (new frame)
if (ly_ > 153) {
ly_ = 0;
// Reset STAT interrupt flag when changing frame
stat_interrupt_line_ = 0;
// --- Step 0200: Synchronous Framebuffer Cleanup ---
// Clear the framebuffer just when the new frame starts (LY=0).
// This eliminates the race condition: cleanup occurs within the same
// hardware "tick" that starts drawing, ensuring the canvas is
// always clear just before the first pixel of the new frame is drawn.
clear_framebuffer();
}This modification ensures that:
- Cleaning happenswithin the same hardware cyclewhich starts the new frame.
- There is no race condition: the PPU controls its own framebuffer.
- The framebuffer is cleanjust beforefor the first visible line (LY=0) to start rendering.
2. Removing Asynchronous Cleanup in Python
Insrc/viboy.py, we eliminate the call toclear_framebuffer()from the main loop:
# Main emulator loop
while self.running:
# --- Step 0200: Cleaning the framebuffer is now the responsibility of the PPU ---
# The PPU clears the framebuffer synchronously when LY is reset to 0,
# eliminating the race condition between Python and C++.
# --- Full Frame Loop (154 scanlines) ---
for line in range(SCANLINES_PER_FRAME):
#...rest of the loop...The Python orchestrator is no longer responsible for cleanup. This responsibility belongs exclusively to the PPU, which knows the exact timing of the hardware.
3. Integration of the Custom Logo "VIBOY COLOR"
As part of this Step, we also integrated the custom "VIBOY COLOR" logo instead of the standard Nintendo logo. To facilitate this task, we created an automatic conversion script that transforms a PNG image into the 48-byte array required by the cartridge header format.
3.1. Logo Conversion Script
The script was createdtools/logo_converter/convert_logo_to_header.pyto automatically convert PNG images to Game Boy cartridge header format. The script is documented intools/logo_converter/README.mdand is available on GitHub so other developers can use it.
Complete script code:
#!/usr/bin/env python3
"""
Script to convert a PNG image to Game Boy cartridge header format.
The Nintendo logo in the cartridge header (0x0104-0x0133) is 48 bytes
which represent 48x8 pixels in 1-bit format (1 bit per pixel).
Format:
- 48 bytes = 48 columns x 8 rows
- Each byte represents 8 vertical pixels (1 bit per pixel)
- Bit 7 = top pixel, Bit 0 = bottom pixel
- 0 = white/transparent, 1 = black/visible
Source: Pan Docs - "Nintendo Logo", Cart Header (0x0104-0x0133)
"""
from PIL import Image
import sys
from pathlib import Path
def image_to_gb_logo_header(image_path: str, output_cpp: bool = True) -> str:
"""
Converts a PNG image to a 48-byte array for the cartridge header.
Args:
image_path: Path to the PNG image
output_cpp: If True, generates C++ code. If False, only shows the bytes.
Returns:
String with C++ code or bytes in hexadecimal format
"""
try:
# Open the image
img = Image.open(image_path)
print(f"Original image loaded: {img.size} pixels, mode: {img.mode}")
# Resize to 48x8 (width x height)
# We use LANCZOS for better downscale quality
img_resized = img.resize((48, 8), Image.Resampling.LANCZOS)
print(f"Resized image: {img_resized.size} pixels")
# Convert to grayscale if not
if img_resized.mode != 'L':
img_gray = img_resized.convert('L')
else:
img_gray = img_resized
# Convert to 1-bit (black and white) using threshold
# Threshold: pixels darker than 128 are converted to black (1),
# pixels lighter to white (0)
img_1bit = img_gray.point(lambda x: 0 if x > 128 else 255, mode='1')
# Save reference version (optional, for debugging)
debug_path = Path(image_path).parent / "viboy_logo_48x8_debug.png"
img_1bit.save(debug_path)
print(f"48x8 version saved in: {debug_path}")
# Get the pixels as list
pixels = list(img_1bit.getdata())
# The header format is:
# - 48 bytes = 48 columns
# - Each byte represents 8 vertical pixels (1 bit per pixel)
# - Bit 7 = top pixel (row 0), Bit 0 = bottom pixel (row 7)
# - 0 in PIL '1' mode = black (255), 1 = white (0)
# - On Game Boy: 1 = visible/black, 0 = transparent/white
header_data = bytearray(48)
# For each column (0-47)
for col in range(48):
byte_value = 0
# For each row (0-7), from top to bottom
for row in range(8):
# Calculate pixel index in flat list
pixel_index = row * 48 + col
if pixel_index< len(pixels):
# En modo '1' de PIL: 0 = negro, 255 = blanco
# Pero en realidad, getdata() devuelve 0 para negro y 255 para blanco
# Necesitamos invertir: si el píxel es negro (0), poner el bit a 1
pixel_value = pixels[pixel_index]
if pixel_value == 0: # Negro en PIL
# Bit 7-row: bit más significativo para la fila superior
byte_value |= (1 << (7 - row))
header_data[col] = byte_value
# Formatear para C++
if output_cpp:
cpp_array = "// --- Logo Personalizado 'Viboy Color' (48x8 píxeles, formato 1bpp) ---\n"
cpp_array += "// Convertido desde: " + str(Path(image_path).name) + "\n"
cpp_array += "// Formato: 48 bytes = 48 columnas x 8 filas (1 bit por píxel)\n"
cpp_array += "// Bit 7 = píxel superior, Bit 0 = píxel inferior\n"
cpp_array += "// 1 = visible/negro, 0 = transparente/blanco\n"
cpp_array += "static const uint8_t VIBOY_LOGO_HEADER_DATA[48] = {\n "
for i, byte in enumerate(header_data):
cpp_array += f"0x{byte:02X}, "
if (i + 1) % 12 == 0:
cpp_array += "\n "
cpp_array = cpp_array.rstrip(", \n ") + "\n};"
return cpp_array
else:
# Solo mostrar los bytes en formato hexadecimal
hex_string = " ".join(f"{b:02X}" for b in header_data)
return hex_string
except FileNotFoundError:
return f"Error: No se encontró el archivo en la ruta: {image_path}"
except Exception as e:
return f"Error al procesar la imagen: {e}"
if __name__ == "__main__":
# Ruta por defecto
default_path = "assets/svg viboycolor logo.png"
# Permitir pasar la ruta como argumento
if len(sys.argv) >1:
image_path = sys.argv[1]
else:
image_path = default_path
# Verify that the file exists
if not Path(image_path).exists():
print(f"Error: File not found: {image_path}")
print(f"Searching in: {Path(image_path).absolute()}")
sys.exit(1)
# Convert
print(f"Converting: {image_path}")
print("-" * 60)
result = image_to_gb_logo_header(image_path, output_cpp=True)
print("\n" + "=" * 60)
print("GENERATED C++ ARRAY:")
print("=" * 60)
print(result)
print("=" * 60)
# Also save to a file
output_file = Path("tools") / "viboy_logo_header.txt"
with open(output_file, "w", encoding="utf-8") as f:
f.write(result)
print(f"\nArray also saved in: {output_file}")3.2. Use of the Script
The script is run from the command line:
# Use the default path (assets/svg viboycolor logo.png)
python tools/logo_converter/convert_logo_to_header.py
# Or specify a custom image
python tools/logo_converter/convert_logo_to_header.py path/to/your/image.pngThe script generates:
- A ready-to-use C++ array
MMU.cpp - A text file with the array in
tools/viboy_logo_header.txt - A debug image in
assets/viboy_logo_48x8_debug.pngfor visual verification
3.3. Generated Array
The final array generated from the imageassets/svg viboycolor logo.pngis:
// --- Step 0200: Custom Logo Data "Viboy Color" (Post-BIOS) ---
// Boot ROM copies logo data from cartridge header (0x0104-0x0133)
// to VRAM. These are the 48 bytes of the personalized logo "VIBOY COLOR" converted
// from a 48x8 pixel image to cartridge header format (1bpp).
//
// Converted from: assets/svg viboycolor logo.png
// Format: 48 bytes = 48 columns x 8 rows (1 bit per pixel)
// Bit 7 = top pixel, Bit 0 = bottom pixel
// 1 = visible/black, 0 = transparent/white
//
// Source: Pan Docs - "Nintendo Logo", Cart Header (0x0104-0x0133)
// The original Nintendo logo is used as an anti-piracy mechanism: the Boot ROM
// compares these bytes with those in the cartridge header. If they do not match, the
// system freezes. In our case, we use a custom logo.
//
// NOTE: This array was generated automatically using tools/convert_logo_to_header.py
static const uint8_t VIBOY_LOGO_HEADER_DATA[48] = {
0xF7, 0xC3, 0x9D, 0xBD, 0xBE, 0x7E, 0x6E, 0x76, 0x66, 0x7E, 0x66, 0x7E,
0x66, 0x66, 0x7E, 0x66, 0x7E, 0x6E, 0x66, 0x6E, 0x66, 0x6E, 0x7E, 0x7E,
0x66, 0x6E, 0x7E, 0x7E, 0x66, 0x7E, 0x66, 0x7E, 0x66, 0x7E, 0x7E, 0x66,
0x7E, 0x6E, 0x76, 0x66, 0x66, 0x66, 0x7E, 0xBE, 0xBD, 0x9D, 0xC3, 0xE7
};Note on Nintendo's Anti-Piracy Mechanism:The Nintendo logo on the cartridge header (0x0104-0x0133) is not just decorative. The official Boot ROM compares these 48 bytes with the data it copies to VRAM. If they don't match, the system freezes, preventing unauthorized games from running. This is one of the first anti-piracy mechanisms in the video game industry.
Availability on GitHub:The script is available in the directorytools/logo_converter/from the repository, along with complete documentation inREADME.md, so that other developers can use it to customize their own emulators or Game Boy-related projects.
Affected Files
src/core/cpp/PPU.cpp- Added call toclear_framebuffer()whenly_resets to 0src/viboy.py- Removed asynchronous call toclear_framebuffer()from the main loopsrc/core/cpp/MMU.cpp- ReplacedNINTENDO_LOGO_DATAwithVIBOY_LOGO_HEADER_DATAgenerated from imagetools/logo_converter/convert_logo_to_header.py- Script to convert PNG images to cartridge header format (NEW)tools/logo_converter/README.md- Complete script documentation (NEW)README.md- Added tools and utilities section with mention of Logo Converter (NEW)docs/bitacora/entries/2025-12-21__0200__arquitectura-grafica-synchronizacion-framebuffer-vblank.html- New log entrydocs/bitacora/index.html- Updated with new entryREPORT_PHASE_2.md- Updated with Step 0200
Tests and Verification
The validation of this change is visual and functional:
-
Recompiling C++ module:
python setup.py build_ext --inplace # Or using the PowerShell script: .\rebuild_cpp.ps1 -
Running the emulator:
python main.py roms/tetris.gb -
Expected Result:
- The Nintendo logo (or the custom "VIBOY COLOR" logo) is displayed steadily for approximately one second.
- When the game sets
LCDC=0x80(background off), the screen turns white cleanly, without "ghosting" artifacts. - There is no race condition: the framebuffer is cleared synchronously with the start of each frame.
Compiled C++ module validation:This change modifies the behavior of the emulation loop in C++, so it is critical to verify that the build completes without errors and that the emulator is working correctly.
Conclusion
This Step definitively resolves the framebuffer race condition by moving the cleanup responsibility from the Python orchestrator (asynchronous) to the C++ PPU (hardware-synchronous). By pinning the cleanup to the reset eventL.Y.to 0, we guarantee that the framebuffer is always clear just before the first pixel of the new frame is drawn, but never before.
This architectural solution is more robust and precise than the previous one, since it respects the exact timing of the emulated hardware. The result is a stable and accurate rendering cycle, without visual artifacts or race conditions.