348. X del viewport de scanline

Decodificar la X del viewport horizontal a partir de un estado de scanline registrado.

Lección 348 de 356 · tests/chapter_13_scrolling/test_348_scanline_viewport_x.py

Archivo a actualizar

emulator/rendering/ppu_background_renderer.py

Referencia

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

Por qué existe este paso

El paso 347 seleccionó las dos nametables lógicas que forman un par de origen horizontal. Un compositor de filas posterior también necesita el píxel exacto en el que comienza este scanline dentro de ese par de 512 píxeles de ancho.

La dirección registrada usa el mismo formato empaquetado de scroll que t

yyy NN YYYYY XXXXX

La X del viewport horizontal usa

XXXXX          coarse X tile column
low N bit      horizontal nametable selection, vram_addr bit 10
state.fine_x   pixel offset inside the first tile

Conversión de píxeles

viewport_x = nametable_x * 256 + coarse_x * 8 + fine_x

Ejemplo

nametable X = 1
coarse X    = 5
fine X      = 3

viewport X = 1 * 256 + 5 * 8 + 3 = 299

¿Por qué reutilizar decode_background_viewport_position? El decodificador puro existente ya posee la conversión del campo de scroll empaquetado. Tanto t como la v registrada tienen el mismo formato de bits, así que repetir máscaras y dimensiones en este renderizador crearía dos implementaciones que podrían divergir.

Invariantes importantes

el bit 10 de la nametable horizontal aporta 256 píxeles
la X gruesa aporta ocho píxeles por tile
la X fina aporta el desplazamiento final de 0-7 píxeles
la nametable vertical, la Y gruesa y la Y fina no afectan a la X del viewport
el resultado permanece dentro del rango lógico horizontal 0-511
la dirección registrada no se rebobina de nuevo
el auxiliar no realiza renderizado ni acceso a memoria

Concepto erróneo común

La dirección registrada no necesita otra corrección de dos tiles. El paso 345 ya rebobinó dos veces una copia de v antes de construir BackgroundScanlineState. Repetir el rebobinado aquí desplazaría incorrectamente cada fila renderizada dieciséis píxeles a la izquierda.

Fuera de alcance

seleccionar direcciones lógicas de nametable
componer filas del framebuffer
aplicar el desbordamiento horizontal a los píxeles de destino
la composición de la máscara de opacidad
elegir entre los datos temporizados y el mecanismo de respaldo a nivel de frame antiguo

Implementación de ejemplo completa

# emulator/rendering/ppu_background_renderer.py

# --- NEW BLOCK: DECODE ONE SCANLINE'S HORIZONTAL VIEWPORT ---
def _scanline_viewport_x(state: BackgroundScanlineState) -> int:
    viewport_x, _ = decode_background_viewport_position(
        temp_vram_addr=state.vram_addr,
        fine_x=state.fine_x,
    )

    return viewport_x

Ejecutar esta lección

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

Implementación de ejemplo

Implementación de ejemplo completa

# emulator/rendering/ppu_background_renderer.py

# --- NEW BLOCK: DECODE ONE SCANLINE'S HORIZONTAL VIEWPORT ---
def _scanline_viewport_x(state: BackgroundScanlineState) -> int:
    viewport_x, _ = decode_background_viewport_position(
        temp_vram_addr=state.vram_addr,
        fine_x=state.fine_x,
    )

    return viewport_x

Ver código del testtest_348_scanline_viewport_x.py

import pytest

from emulator.ppu.ppu import BackgroundScanlineState
from emulator.rendering.ppu_background_renderer import _scanline_viewport_x


def make_scanline_state(
    *,
    coarse_x: int = 0,
    coarse_y: int = 0,
    nametable_x: int = 0,
    nametable_y: int = 0,
    fine_y: int = 0,
    fine_x: int = 0,
) -> BackgroundScanlineState:
    """Pack scrolling fields into one immutable recorded scanline value."""
    vram_addr = (
        (coarse_x & 0b1_1111)
        | ((coarse_y & 0b1_1111) << 5)
        | ((nametable_x & 1) << 10)
        | ((nametable_y & 1) << 11)
        | ((fine_y & 0b111) << 12)
    )
    return BackgroundScanlineState(vram_addr=vram_addr, fine_x=fine_x)


def test_zero_recorded_scroll_starts_at_left_edge():
    """
    Objective:
    Establish the origin of the 512-pixel horizontal logical pair.
    """
    state = make_scanline_state()

    assert _scanline_viewport_x(state) == 0


@pytest.mark.parametrize("coarse_x", [0, 1, 5, 17, 31])
def test_coarse_x_converts_tile_columns_to_pixels(coarse_x):
    """
    Objective:
    Convert each selected tile column into its eight-pixel horizontal position.
    """
    state = make_scanline_state(coarse_x=coarse_x)

    assert _scanline_viewport_x(state) == coarse_x * 8


@pytest.mark.parametrize("fine_x", range(8))
def test_fine_x_adds_offset_inside_the_first_tile(fine_x):
    """
    Objective:
    Preserve pixel-level scrolling after coarse tile selection.
    """
    state = make_scanline_state(coarse_x=5, fine_x=fine_x)

    assert _scanline_viewport_x(state) == 40 + fine_x


def test_horizontal_nametable_bit_selects_right_half_of_logical_pair():
    """
    Objective:
    Include bit 10 as a 256-pixel offset rather than treating it as pair selection.
    """
    state = make_scanline_state(
        nametable_x=1,
        coarse_x=5,
        fine_x=3,
    )

    assert _scanline_viewport_x(state) == 299


def test_maximum_horizontal_fields_reach_last_logical_pixel():
    """
    Objective:
    Prove the complete horizontal state covers exactly pixel positions 0 through 511.
    """
    state = make_scanline_state(
        nametable_x=1,
        coarse_x=31,
        fine_x=7,
    )

    assert _scanline_viewport_x(state) == 511


def test_vertical_fields_do_not_change_horizontal_viewport_x():
    """
    Objective:
    Keep horizontal row positioning independent from vertical scrolling fields.
    """
    horizontal_only = make_scanline_state(
        nametable_x=1,
        coarse_x=9,
        fine_x=6,
    )
    with_vertical_fields = make_scanline_state(
        nametable_x=1,
        coarse_x=9,
        fine_x=6,
        nametable_y=1,
        coarse_y=29,
        fine_y=7,
    )

    assert _scanline_viewport_x(horizontal_only) == 334
    assert _scanline_viewport_x(with_vertical_fields) == 334

Funciones de test (6)

test_zero_recorded_scroll_starts_at_left_edge
test_coarse_x_converts_tile_columns_to_pixels
test_fine_x_adds_offset_inside_the_first_tile
test_horizontal_nametable_bit_selects_right_half_of_logical_pair
test_maximum_horizontal_fields_reach_last_logical_pixel
test_vertical_fields_do_not_change_horizontal_viewport_x