338. Incrementar la dirección vram horizontal

Incrementa la componente horizontal de la dirección de renderizado actual v.

Lección 338 de 356 · tests/chapter_13_scrolling/test_338_increment_horizontal_vram_addr.py

Archivo a actualizar

emulator/ppu/ppu.py

Referencias

https://www.nesdev.org/wiki/PPU_scrolling#Coarse_X_increment
https://www.nesdev.org/wiki/PPU_scrolling#During_rendering

Por qué existe este paso

Durante las obtenciones de fondo, la PPU avanza de una columna de tiles de 8 píxeles cada vez. La dirección de renderizado actual v almacena tanto la columna de tiles de coarse X como la selección horizontal de nametable:

v: yyy NN YYYYY XXXXX
                   |
                   +-- coarse X, bits 0-4

horizontal nametable selection: bit 10

Comportamiento normal

coarse X 0  -> 1
coarse X 30 -> 31

Comportamiento en la frontera

coarse X 31, horizontal nametable 0
    -> coarse X 0, horizontal nametable 1

coarse X 31, horizontal nametable 1
    -> coarse X 0, horizontal nametable 0

El conmutador de frontera mueve el renderizado a través de la frontera lógica izquierda/derecha entre nametables. PpuBus aplica después el mirroring del cartucho cuando se leen esas direcciones lógicas.

Invariantes importantes

solo pueden cambiar coarse X y, al hacer wrap, el nametable horizontal
coarse Y, fine Y y el nametable vertical permanecen sin cambios
fine X es independiente y no es un argumento de esta operación
la función auxiliar devuelve un valor y no muta la PPU

Error común

Esto no mueve un píxel. Avanza una columna de tiles, que representa 8 píxeles. Fine X proporciona el desfase independiente de 0-7 píxeles dentro del primer tile.

Fuera del alcance

llamar a la función auxiliar desde PPU.step()
elegir los dots de obtención de fondo
copiar los bits horizontales de t en v
incrementos verticales
renderizado de framebuffer

Implementación de ejemplo completa

# emulator/ppu/ppu.py

# --- NEW BLOCK: PURE HORIZONTAL v INCREMENT ---
def increment_horizontal_vram_addr(vram_addr: int) -> int:
    # Advance v by one background tile column.
    coarse_x = vram_addr & 0b1_1111

    if coarse_x == 31:
        vram_addr &= ~0b1_1111
        vram_addr ^= 0b100_0000_0000
        return vram_addr

    return vram_addr + 1

Ejecutar esta lección

uv run pytest tests/chapter_13_scrolling/test_338_increment_horizontal_vram_addr.py -v

Implementación de ejemplo

Implementación de ejemplo completa

# emulator/ppu/ppu.py

# --- NEW BLOCK: PURE HORIZONTAL v INCREMENT ---
def increment_horizontal_vram_addr(vram_addr: int) -> int:
    # Advance v by one background tile column.
    coarse_x = vram_addr & 0b1_1111

    if coarse_x == 31:
        vram_addr &= ~0b1_1111
        vram_addr ^= 0b100_0000_0000
        return vram_addr

    return vram_addr + 1

Ver código del testtest_338_increment_horizontal_vram_addr.py

import pytest

from emulator.ppu.ppu import PPU, increment_horizontal_vram_addr


COARSE_X_MASK = 0x001F
HORIZONTAL_NAMETABLE_BIT = 0x0400
HORIZONTAL_FIELDS_MASK = COARSE_X_MASK | HORIZONTAL_NAMETABLE_BIT


@pytest.mark.parametrize("coarse_x", range(31))
def test_normal_increment_advances_only_coarse_x(coarse_x):
    """
    Objective:
    Coarse X values 0-30 increment without changing the selected nametable.
    """
    preserved_fields = 0x7BE0 | 0x8000
    original = preserved_fields | HORIZONTAL_NAMETABLE_BIT | coarse_x

    result = increment_horizontal_vram_addr(original)

    assert result & COARSE_X_MASK == coarse_x + 1
    assert result & HORIZONTAL_NAMETABLE_BIT
    assert result & ~HORIZONTAL_FIELDS_MASK == original & ~HORIZONTAL_FIELDS_MASK


def test_coarse_x_31_wraps_to_zero_and_selects_right_nametable():
    """
    Objective:
    Crossing the right edge of logical nametable X=0 continues at logical nametable
    X=1.
    """
    original = 31

    result = increment_horizontal_vram_addr(original)

    assert result & COARSE_X_MASK == 0
    assert result & HORIZONTAL_NAMETABLE_BIT


def test_coarse_x_31_wraps_to_zero_and_selects_left_nametable():
    """
    Objective:
    Crossing the right edge of logical nametable X=1 wraps around to logical
    nametable X=0.
    """
    original = HORIZONTAL_NAMETABLE_BIT | 31

    result = increment_horizontal_vram_addr(original)

    assert result & COARSE_X_MASK == 0
    assert (result & HORIZONTAL_NAMETABLE_BIT) == 0


def test_wrapping_preserves_every_non_horizontal_field():
    """
    Objective:
    Horizontal wrapping must not silently damage vertical scrolling or unrelated
    internal address bits.
    """
    preserved_fields = 0x7BE0 | 0x8000
    original = preserved_fields | HORIZONTAL_NAMETABLE_BIT | 31

    result = increment_horizontal_vram_addr(original)

    assert result & ~HORIZONTAL_FIELDS_MASK == original & ~HORIZONTAL_FIELDS_MASK


def test_helper_is_pure_and_does_not_mutate_ppu_vram_addr():
    """
    Objective:
    Keep address arithmetic independently testable before timing integration.
    """
    ppu = PPU()
    ppu.vram_addr = 14

    result = increment_horizontal_vram_addr(ppu.vram_addr)

    assert result == 15
    assert ppu.vram_addr == 14

Funciones de test (5)

test_normal_increment_advances_only_coarse_x
test_coarse_x_31_wraps_to_zero_and_selects_right_nametable
test_coarse_x_31_wraps_to_zero_and_selects_left_nametable
test_wrapping_preserves_every_non_horizontal_field
test_helper_is_pure_and_does_not_mutate_ppu_vram_addr