344. Decrementar la dirección horizontal de vram

Revertir un incremento de fetch de fondo horizontal sobre una dirección copiada.

Lección 344 de 356 · tests/chapter_13_scrolling/test_344_decrement_horizontal_vram_addr.py

Archivo a actualizar

emulator/ppu/ppu.py

Referencias

https://www.nesdev.org/wiki/PPU_scrolling#Details

Por qué existe este paso

Los dots 321-336 precargan los dos primeros tiles de fondo para el siguiente scanline. Cada fetch de tile avanza la v horizontal, así que en el dot 1 la dirección ya está dos columnas de tiles por delante de los píxeles almacenados en los registros de desplazamiento de fondo:

intended visible coarse X = 5
prefetch tile 5 -> v advances to 6
prefetch tile 6 -> v advances to 7

dot 1:
    shifters begin displaying tile 5
    v already contains coarse X 7

El registro de scanline posterior copiará v y rebobinará esa copia dos veces

7 -> 6 -> 5

Este auxiliar revierte un incremento. No es una operación de la PPU temporizada, y nunca debe mover hacia atrás el PPU.vram_addr real.

Comportamiento normal

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

Comportamiento en el límite

coarse X 0 -> 31 and toggle horizontal nametable

Invariantes importantes

solo pueden cambiar la X gruesa y, al desbordarse, la nametable horizontal
cualquier campo vertical o no relacionado permanece sin cambios
el decremento es el inverso del incremento horizontal probado
la función es pura y no modifica la PPU

Concepto erróneo común

La PPU de la NES no realiza este decremento durante el renderizado. Existe solo para traducir la dirección de fetch adelantada respecto a la visualización en una dirección de viewport visible para el renderizador de alto nivel existente.

Fuera de alcance

invocar el auxiliar desde PPU.step()
registrar 240 posiciones de scanline
cambios en el framebuffer o en la máscara de opacidad

Implementación de ejemplo completa

# emulator/ppu/ppu.py

# --- NEW BLOCK: REVERSE ONE HORIZONTAL FETCH INCREMENT ---
def decrement_horizontal_vram_addr(vram_addr: int) -> int:
    coarse_x = vram_addr & 0b1_1111

    if coarse_x == 0:
        vram_addr = (
            (vram_addr & ~0b1_1111)
            | 0b1_1111
        )
        vram_addr ^= 0b000_01_00000_00000
        return vram_addr

    return vram_addr - 1

Ejecutar esta lección

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

Implementación de ejemplo

Implementación de ejemplo completa

# emulator/ppu/ppu.py

# --- NEW BLOCK: REVERSE ONE HORIZONTAL FETCH INCREMENT ---
def decrement_horizontal_vram_addr(vram_addr: int) -> int:
    coarse_x = vram_addr & 0b1_1111

    if coarse_x == 0:
        vram_addr = (
            (vram_addr & ~0b1_1111)
            | 0b1_1111
        )
        vram_addr ^= 0b000_01_00000_00000
        return vram_addr

    return vram_addr - 1

Ver código del testtest_344_decrement_horizontal_vram_addr.py

import pytest

from emulator.ppu.ppu import (
    HORIZONTAL_SCROLL_BITS,
    PPU,
    decrement_horizontal_vram_addr,
    increment_horizontal_vram_addr,
)


COARSE_X_MASK = 0x001F
HORIZONTAL_NAMETABLE_BIT = 0x0400


@pytest.mark.parametrize("coarse_x", range(1, 32))
@pytest.mark.parametrize("nametable_x", [0, 1])
def test_nonzero_coarse_x_decrements_without_changing_nametable(
    coarse_x,
    nametable_x,
):
    """
    Objective:
    Reverse ordinary horizontal fetch increments without borrowing into other fields.
    """
    vertical_fields = 0x7BE0
    original = vertical_fields | (nametable_x << 10) | coarse_x

    result = decrement_horizontal_vram_addr(original)

    assert result & COARSE_X_MASK == coarse_x - 1
    assert result & HORIZONTAL_NAMETABLE_BIT == nametable_x << 10
    assert result & ~HORIZONTAL_SCROLL_BITS == original & ~HORIZONTAL_SCROLL_BITS


@pytest.mark.parametrize("nametable_x", [0, 1])
def test_coarse_x_zero_wraps_to_31_and_toggles_horizontal_nametable(
    nametable_x,
):
    """
    Objective:
    Reverse a fetch increment that crossed a logical horizontal nametable boundary.
    """
    vertical_fields = 0x7BE0
    original = vertical_fields | (nametable_x << 10)

    result = decrement_horizontal_vram_addr(original)

    assert result & COARSE_X_MASK == 31
    assert result & HORIZONTAL_NAMETABLE_BIT == (nametable_x ^ 1) << 10
    assert result & ~HORIZONTAL_SCROLL_BITS == original & ~HORIZONTAL_SCROLL_BITS


@pytest.mark.parametrize("coarse_x", range(32))
@pytest.mark.parametrize("nametable_x", [0, 1])
def test_decrement_reverses_horizontal_increment(coarse_x, nametable_x):
    """
    Objective:
    Prove the rewind operation is the inverse of one previously tested fetch increment.
    """
    original = 0x7BE0 | (nametable_x << 10) | coarse_x

    incremented = increment_horizontal_vram_addr(original)
    restored = decrement_horizontal_vram_addr(incremented)

    assert restored == original


@pytest.mark.parametrize("coarse_x", range(32))
@pytest.mark.parametrize("nametable_x", [0, 1])
def test_increment_reverses_horizontal_decrement(coarse_x, nametable_x):
    """
    Objective:
    Check the inverse relationship in the opposite operation order as well.
    """
    original = 0x7BE0 | (nametable_x << 10) | coarse_x

    decremented = decrement_horizontal_vram_addr(original)
    restored = increment_horizontal_vram_addr(decremented)

    assert restored == original


def test_rewind_preserves_unrelated_high_bit():
    """
    Objective:
    Preserve internal fields outside coarse X and horizontal nametable selection.
    """
    original = 0x8000 | 0x7BE0

    result = decrement_horizontal_vram_addr(original)

    assert result & 0x8000
    assert result & 0x7BE0 == original & 0x7BE0


def test_helper_is_pure_and_does_not_mutate_ppu_vram_addr():
    """
    Objective:
    Rewind only a copied value rather than the PPU's active rendering address.
    """
    ppu = PPU()
    ppu.vram_addr = HORIZONTAL_NAMETABLE_BIT | 7

    result = decrement_horizontal_vram_addr(ppu.vram_addr)

    assert result & COARSE_X_MASK == 6
    assert ppu.vram_addr == HORIZONTAL_NAMETABLE_BIT | 7

Funciones de test (6)

test_nonzero_coarse_x_decrements_without_changing_nametable
test_coarse_x_zero_wraps_to_31_and_toggles_horizontal_nametable
test_decrement_reverses_horizontal_increment
test_increment_reverses_horizontal_decrement
test_rewind_preserves_unrelated_high_bit
test_helper_is_pure_and_does_not_mutate_ppu_vram_addr