341. Incrementar la dirección vertical de vram

Incrementar el componente vertical de la dirección de renderizado actual v.

Lección 341 de 356 · tests/chapter_13_scrolling/test_341_increment_vertical_vram_addr.py

Archivo a actualizar

emulator/ppu/ppu.py

Referencias

https://www.nesdev.org/wiki/PPU_scrolling#Y_increment
https://www.nesdev.org/wiki/PPU_scrolling#Wrapping_around

Por qué existe este paso

En el dot 256, la PPU avanza la dirección de renderizado en una fila de píxeles. A diferencia del incremento horizontal, el movimiento vertical primero avanza la Y fina dentro del tile actual de 8 píxeles:

yyy NN YYYYY XXXXX
+++    +++++
 |       +---- coarse Y: bits 5-9
 +------------ fine Y: bits 12-14

vertical nametable: bit 11

Comportamiento de Y fina

0 -> 1 -> 2 -> ... -> 7

Cuando la Y fina ya vale 7, vuelve a 0 y la Y gruesa avanza.

Comportamiento de la Y gruesa tras el desbordamiento de la Y fina

coarse Y 0-28 -> increment by one
coarse Y 29   -> 0 and toggle vertical nametable
coarse Y 30   -> 31 through the normal increment branch
coarse Y 31   -> 0 without toggling vertical nametable

Las filas 0-29 son las 30 filas de tiles visibles de una nametable. Los valores 30 y 31 no son filas visibles normales, pero pueden existir porque la Y gruesa es un campo de cinco bits y las operaciones de dirección de la CPU pueden cargar esos valores.

¿Por qué sumar $1000 para un incremento normal de Y fina? La Y fina comienza en el bit 12, así que sumar 1 << 12 incrementa ese campo empaquetado en uno. Esto no significa conceptualmente desplazarse 4096 bytes por la memoria de la PPU.

Invariantes importantes

la X gruesa horizontal y la selección de nametable permanecen sin cambios
los bits internos de dirección no relacionados permanecen sin cambios
la nametable vertical solo se alterna cuando la fila 29 se desborda
el auxiliar es puro y no modifica la PPU

Concepto erróneo común

El incremento vertical no es simplemente simétrico al incremento horizontal. El movimiento horizontal avanza una columna de tiles; el movimiento vertical avanza una fila de píxeles fina y solo a veces avanza la fila de tiles gruesa.

Fuera de alcance

invocar este auxiliar en el dot 256
la copia vertical de t a v
la temporización del pre-render
el registro del viewport por scanline
el renderizado del framebuffer

Implementación de ejemplo completa

# emulator/ppu/ppu.py

# --- NEW BLOCK: PURE VERTICAL v INCREMENT ---
def increment_vertical_vram_addr(vram_addr: int) -> int:
    fine_y = (vram_addr >> 12) & 0b111

    if fine_y < 7:
        return vram_addr + (1 << 12)

    vram_addr &= ~0b111_00_00000_00000
    coarse_y = (vram_addr >> 5) & 0b1_1111

    if coarse_y == 29:
        coarse_y = 0
        vram_addr ^= 0b000_10_00000_00000
    elif coarse_y == 31:
        coarse_y = 0
    else:
        coarse_y += 1

    return (
        (vram_addr & ~0b000_00_11111_00000)
        | (coarse_y << 5)
    )

Ejecutar esta lección

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

Implementación de ejemplo

Implementación de ejemplo completa

# emulator/ppu/ppu.py

# --- NEW BLOCK: PURE VERTICAL v INCREMENT ---
def increment_vertical_vram_addr(vram_addr: int) -> int:
    fine_y = (vram_addr >> 12) & 0b111

    if fine_y < 7:
        return vram_addr + (1 << 12)

    vram_addr &= ~0b111_00_00000_00000
    coarse_y = (vram_addr >> 5) & 0b1_1111

    if coarse_y == 29:
        coarse_y = 0
        vram_addr ^= 0b000_10_00000_00000
    elif coarse_y == 31:
        coarse_y = 0
    else:
        coarse_y += 1

    return (
        (vram_addr & ~0b000_00_11111_00000)
        | (coarse_y << 5)
    )

Ver código del testtest_341_increment_vertical_vram_addr.py

import pytest

from emulator.ppu.ppu import PPU, increment_vertical_vram_addr


FINE_Y_MASK = 0x7000
COARSE_Y_MASK = 0x03E0
VERTICAL_NAMETABLE_BIT = 0x0800
VERTICAL_FIELDS_MASK = FINE_Y_MASK | COARSE_Y_MASK | VERTICAL_NAMETABLE_BIT
HORIZONTAL_FIELDS_MASK = 0x041F


def make_vram_addr(
    *,
    coarse_y: int,
    fine_y: int,
    nametable_y: int = 0,
    horizontal_fields: int = 0,
    unrelated_fields: int = 0,
) -> int:
    """Pack the fields needed for focused vertical-address tests."""
    return (
        ((fine_y & 0b111) << 12)
        | ((nametable_y & 1) << 11)
        | ((coarse_y & 0b1_1111) << 5)
        | (horizontal_fields & HORIZONTAL_FIELDS_MASK)
        | unrelated_fields
    )


@pytest.mark.parametrize("fine_y", range(7))
def test_fine_y_zero_through_six_increments_without_changing_coarse_y(fine_y):
    """
    Objective:
    Advance one pixel row inside the current tile before touching coarse Y.
    """
    original = make_vram_addr(
        coarse_y=12,
        fine_y=fine_y,
        nametable_y=1,
        horizontal_fields=0x0415,
        unrelated_fields=0x8000,
    )

    result = increment_vertical_vram_addr(original)

    assert (result & FINE_Y_MASK) >> 12 == fine_y + 1
    assert result & ~FINE_Y_MASK == original & ~FINE_Y_MASK


@pytest.mark.parametrize(
    ("coarse_y", "expected_coarse_y"),
    [
        (0, 1),
        (1, 2),
        (28, 29),
        (30, 31),
    ],
)
def test_fine_y_seven_wraps_and_normally_increments_coarse_y(
    coarse_y,
    expected_coarse_y,
):
    """
    Objective:
    Use the normal coarse-Y increment for every value except hardware-special rows 29
    and 31. This includes the representable out-of-range value 30.
    """
    original = make_vram_addr(
        coarse_y=coarse_y,
        fine_y=7,
        nametable_y=0,
        horizontal_fields=0x0412,
    )

    result = increment_vertical_vram_addr(original)

    assert (result & FINE_Y_MASK) == 0
    assert (result & COARSE_Y_MASK) >> 5 == expected_coarse_y
    assert (result & VERTICAL_NAMETABLE_BIT) == 0
    assert result & HORIZONTAL_FIELDS_MASK == original & HORIZONTAL_FIELDS_MASK


@pytest.mark.parametrize("starting_nametable_y", [0, 1])
def test_row_29_wraps_to_zero_and_toggles_vertical_nametable(
    starting_nametable_y,
):
    """
    Objective:
    Cross the normal 240-pixel nametable boundary after visible row 29.
    """
    original = make_vram_addr(
        coarse_y=29,
        fine_y=7,
        nametable_y=starting_nametable_y,
        horizontal_fields=0x0407,
    )

    result = increment_vertical_vram_addr(original)

    assert (result & FINE_Y_MASK) == 0
    assert (result & COARSE_Y_MASK) == 0
    assert (result & VERTICAL_NAMETABLE_BIT) == (
        (starting_nametable_y ^ 1) << 11
    )
    assert result & HORIZONTAL_FIELDS_MASK == original & HORIZONTAL_FIELDS_MASK


@pytest.mark.parametrize("starting_nametable_y", [0, 1])
def test_row_31_wraps_to_zero_without_toggling_vertical_nametable(
    starting_nametable_y,
):
    """
    Objective:
    Preserve the documented row-31 hardware rule independently of normal visible
    row-29 wrapping.
    """
    original = make_vram_addr(
        coarse_y=31,
        fine_y=7,
        nametable_y=starting_nametable_y,
        horizontal_fields=0x001F,
    )

    result = increment_vertical_vram_addr(original)

    assert (result & FINE_Y_MASK) == 0
    assert (result & COARSE_Y_MASK) == 0
    assert (result & VERTICAL_NAMETABLE_BIT) == (
        starting_nametable_y << 11
    )
    assert result & HORIZONTAL_FIELDS_MASK == original & HORIZONTAL_FIELDS_MASK


def test_vertical_increment_preserves_unrelated_high_bit():
    """
    Objective:
    Keep internal address bits outside the named vertical fields unchanged.
    """
    original = make_vram_addr(
        coarse_y=5,
        fine_y=7,
        unrelated_fields=0x8000,
    )

    result = increment_vertical_vram_addr(original)

    assert result & 0x8000


def test_helper_is_pure_and_does_not_mutate_ppu_vram_addr():
    """
    Objective:
    Keep vertical arithmetic independently testable before timing integration.
    """
    ppu = PPU()
    ppu.vram_addr = make_vram_addr(coarse_y=8, fine_y=3)

    result = increment_vertical_vram_addr(ppu.vram_addr)

    assert (result & FINE_Y_MASK) >> 12 == 4
    assert ppu.vram_addr == make_vram_addr(coarse_y=8, fine_y=3)

Funciones de test (6)

test_fine_y_zero_through_six_increments_without_changing_coarse_y
test_fine_y_seven_wraps_and_normally_increments_coarse_y
test_row_29_wraps_to_zero_and_toggles_vertical_nametable
test_row_31_wraps_to_zero_without_toggling_vertical_nametable
test_vertical_increment_preserves_unrelated_high_bit
test_helper_is_pure_and_does_not_mutate_ppu_vram_addr