Black Marker Test: Direct Writing

Summary

The Step 0211 probe confirmed that VRAM address validation is successful (VALID CHECK: PASS) and that the address math is perfect. However, the screen is still white because we are rendering Tile 0 (empty). To visually confirm that we have control over the framebuffer within the validated render loop, we implement a direct write of color index 3 (Black) into a vertical stripe pattern.

Aim:Generate black vertical bars by forcingframebuffer_[i] = 3within the validated block. If this works, we will see black and white vertical stripes, confirming that the actual rendering pipeline is traversing the screen and passing validation.

Hardware Concept: Visual Pipeline Validation

Step 0211 confirmed that VRAM address validation works correctly. The log showedVALID CHECK: PASSandCalcTileAddr: 0x8000withTileID: 0x00, which means the math is perfect. However, the screen is still white.

The "where are we looking" problem:Tile 0 (located in0x8000) is empty/white by default. Our probe looked at the pixel (0,0), which corresponds to Tile 0. Although we forcedbyte1=0xFFin Step 0209, it's possible that the bit decoding or palette in Python is making that "3" look white, or we simply need to be more aggressive in confirming full control.

The "Black Marker" solution:Instead of relying on VRAM reading and bit decoding, we are going to directly write color index 3 (Black) to the framebuffer within the validated block. If this turns the screen black (or striped), we have confirmed that the actual rendering pipeline (VRAM → Validation → Framebuffer) works, and that the previous problem was purely data (empty Tile 0).

Vertical stripes pattern:To make the test more visible, we implement an alternating pattern: every 8 pixels, we force color 3 (Black). On the alternating stripes, we leave the normal behavior (which probably reads 0/white of Tile 0). This will generate black and white vertical bars, visually confirming that:

• The rendering loop is looping through all the pixels on the screen.
• VRAM validation is working correctly.
• The framebuffer is being written correctly.
• The C++ → Cython → Python pipeline works end-to-end.

Fountain:Pan Docs - "PPU Rendering", "Framebuffer", "Color Indexing"

Implementation

Function changedPPU::render_scanline()in the filesrc/core/cpp/PPU.cppto implement the black vertical stripe pattern within the validated block of VRAM.

Modifying the Render Block

Replaced code that forcedbyte1 = 0xFFandbyte2 = 0xFF(Step 0209) with a conditional pattern that writes directly to the framebuffer:

// --- Step 0212: THE BLACK MARKER TEST ---
// We ignore VRAM reading and decoding for a moment.
// We write directly to the framebuffer.
// If this works, we will see black vertical bars.

// Stripe pattern: 8 black pixels, 8 normal pixels (white for now)
if ((x / 8) % 2 == 0) {
    framebuffer_[line_start_index + x] = 3; // FORCE BLACK (Index 3)
} else {
    // For the other stripes, we leave the "normal" behavior (which probably reads 0/white of Tile 0)
    uint8_t byte1 = mmu_->read(tile_line_addr);
    uint8_t byte2 = mmu_->read(tile_line_addr + 1);
    uint8_t bit_index = 7 - (map_x % 8);
    uint8_t bit_low = (byte1 >> bit_index) & 1;
    uint8_t bit_high = (byte2 >> bit_index) & 1;
    uint8_t color_index = (bit_high<< 1) | bit_low;
    framebuffer_[line_start_index + x] = color_index;
}
// ----------------------------------------------

Pattern Logic

The pattern works as follows:

• Condition(x / 8) % 2 == 0:Divide the X coordinate by 8 (each tile is 8 pixels wide) and check if the result is even. This creates 8 pixel wide stripes.
• Even stripes:It is forced directlyframebuffer_[line_start_index + x] = 3(Black), completely ignoring VRAM reading and bit decoding.
• Odd stripes:Normal behavior is maintained: reading VRAM, decoding bits, and writing the calculated color index. Since Tile 0 is empty, these stripes will probably be white (color_index = 0).

Expected result:If the code works correctly, we should see a screen with alternating vertical stripes: black (where we force color 3) and white (where we read empty Tile 0).

Affected Files

• src/core/cpp/PPU.cpp- Modified the rendering block inrender_scanline()(lines 385-402) to implement the black vertical stripe pattern

Tests and Verification

Compilation:The code should compile successfully withpython setup.py build_ext --inplaceeither.\rebuild_cpp.ps1. No compilation errors were introduced.

Compiled C++ module validation:The Cython extension will be generated successfully and ready for runtime testing.

Expected test:When running the emulator withpython main.py roms/tetris.gb, we should see a screen with alternating black and white vertical stripes:

• Black stripes:Where our "felt pen" forced color 3 (every 8 pixels, starting from X=0).
• White stripes:Where the PPU read Tile 0 (empty) from the VRAM (every 8 pixels, starting from X=8).

Success validation:If we see this pattern, we will have confirmed that:

• The render loop is working correctly.
• VRAM validation is allowing access (the blockifis running).
• The framebuffer is being written correctly.
• The C++ → Cython → Python pipeline works end-to-end.
• The previous problem was purely data (empty Tile 0), not logic.

Next step if it works:Once confirmed that we have full control over the framebuffer, the next step will be to load real data into VRAM or look at the correct tile in the tilemap.

Sources consulted

• Pan Docs: "PPU Rendering" - Scan Line Rendering Process
• Pan Docs: "Framebuffer" - Pixel Buffer Structure
• Pan Docs: "Color Indexing" - Color indexes (0-3) and palettes

Educational Integrity

Next Steps

• [ ] Recompile the C++ module with.\rebuild_cpp.ps1eitherpython setup.py build_ext --inplace
• [ ] Run the emulator:python main.py roms/tetris.gb
• [ ] Check visual result: Look for alternating black and white vertical stripes
• [ ] If it works: Confirm that we have full control of the framebuffer and that the problem was with data, not logic
• [ ] If it works: Load real data into VRAM or look at the correct tile in the tilemap