Step 0406: CGB RGB Pipeline and Palettes by Tile

💡 Hardware Concept

HeGame Boy Colorintroduces a sophisticated palette system that allows up to 32 simultaneous colors on screen:

• 8 BG palettes× 4 colors = 32 colors for Background
• BG Map Attributes(VRAM Bank 1) define which palette to use for each tile
• Bits 0-2 of the attribute byte = palette number (0-7)

BG Map Attributes (VRAM Bank 1)

Bit 0-2: Palette number (0-7)
Bit 3: Tile VRAM bank (0=Bank 0, 1=Bank 1)
Bit 5: X-Flip
Bit 6: Y-Flip
Bit 7: BG-to-OAM Priority

CGB Pallet Format (BGR555)

Each color uses 2 bytes (BGR555):
  GGGRRRRR XBBBBBGG (Little Endian, X = unused)

BGR555 → RGB888 conversion:
  R5 = (color >> 0) & 0x1F
  G5 = (color >> 5) & 0x1F
  B5 = (color >> 10) & 0x1F
  R8 = (R5 * 255) / 31 # Scale to 0-255
  G8 = (G5 * 255) / 31
  B8 = (B5 * 255) / 31

Fountain:Pan Docs - CGB Registers, BG Map Attributes, Color Palettes

⚙️ Implementation

Task 1: Apply BG Attributes (Palette per Tile)

ModifiedPPU::convert_framebuffer_to_rgb()to read attributes of VRAM bank 1:

// For each pixel (x,y):
uint8_t world_x = (x + scx) & 0xFF;  // Apply scroll with wrap
uint8_t world_y = (y + scy) & 0xFF;
uint8_t tile_x = world_x / 8;
uint8_t tile_y = world_y / 8;

// Read attribute from VRAM bank 1
uint16_t tilemap_offset = tile_y * 32 + tile_x;
uint8_t attributes = mmu_->read_vram_bank(1, tilemap_base + tilemap_offset);

// Extract palette_id (bits 0-2)
uint8_t palette_id = attributes & 0x07;

// Use correct palette for this tile
uint16_t bgr555 = cgb_palettes[palette_id][color_index];

Task 2: Execute Conversion at the End of Frame

Added call toconvert_framebuffer_to_rgb()inswap_framebuffers()for perfect synchronization:

void PPU::swap_framebuffers() {
    std::swap(framebuffer_front_, framebuffer_back_);
    framebuffer_swap_pending_ = false;
    std::fill(framebuffer_back_.begin(), framebuffer_back_.end(), 0);
    
    // Step 0406: Convert indices to RGB after swap
    convert_framebuffer_to_rgb();
}

Task 3: Integrate RGB Render in Python

Modifiedviboy.pyto detect CGB mode and use RGB buffer:

hardware_mode = self._mmu.get_hardware_mode()

if hardware_mode == "CGB":
    rgb_view = self._ppu.get_framebuffer_rgb()
    self._renderer.render_frame(rgb_view=rgb_view)
else:
    # DMG mode: use indexes + BGP
    self._renderer.render_frame(framebuffer_data=framebuffer_to_render)

Added support inRenderer.render_frame()for RGB buffer:

if rgb_view is not None:
    rgb_array = np.frombuffer(rgb_view, dtype=np.uint8)
    rgb_reshaped = rgb_array.reshape((GB_HEIGHT, GB_WIDTH, 3))
    rgb_transposed = np.transpose(rgb_reshaped, (1, 0, 2))
    pygame.surfarray.blit_array(self.screen, rgb_transposed)
    pygame.display.flip()

🧪 Tests and Verification

Compilation

$python3 setup.py build_ext --inplace
✅ Successful build
⚠️ Format warnings (non-critical)

Test: Tetris DX (CGB ROM)

$ timeout 30s python3 main.py roms/tetris_dx.gbc

Results:
✅ CGB mode detected correctly
✅ BG attributes being read from VRAM bank 1
✅ RGB Pipeline working without errors
✅ [CGB-BG-ATTR] logs show attribute reading

Evidence:
[MMU] CGB ROM detected (flag=0x80). Hardware mode: CGB
[MMU] I/O registers initialized for CGB mode
[CGB-BG-ATTR] LY:0 X:0 | TileMapAddr:0x9800 | TileID:0x00 | Attr:0x00
[Renderer-RGB-CGB] Frame rendered correctly from RGB888

Other Games Status

• Tetris DX:✅ Works, progresses (GameplayState=YES)
• Zelda DX / Pokémon Red:⚠️ Require Boot ROM for correct initialization

📄 Affected Files

• src/core/cpp/PPU.cpp- Implementation of palettes per tile inconvert_framebuffer_to_rgb()
• src/core/cpp/PPU.cpp- Call to RGB conversion inswap_framebuffers()
• src/viboy.py- CGB mode detection and RGB buffer usage
• src/gpu/renderer.py- Support forrgb_viewinrender_frame()

📊 Conclusions