335. Viewport de fondo de la PPU a máscara de opacidad

Compone el viewport de la máscara de opacidad horizontal a partir del estado de desplazamiento actual de la PPU.

Lección 335 de 356 · tests/chapter_13_scrolling/test_335_ppu_background_viewport_to_opaque_mask.py

Archivo a actualizar

emulator/rendering/ppu_background_renderer.py

Referencias

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

Por qué esto se parece al paso 334

El adaptador de la máscara de opacidad copia deliberadamente la estructura de direccionamiento del adaptador del framebuffer:

decode the same viewport X
select the same horizontal logical pair
process the same left and right bases
compose using the same viewport X

La diferencia importante es que cada operación que produce datos debe usar la ruta de la máscara de opacidad:

ppu_background_to_opaque_mask()
compose_horizontal_opaque_mask_viewport()

No debe llamar accidentalmente a

ppu_background_to_framebuffer()
compose_horizontal_framebuffer_viewport()

Esta copia deliberada mantiene ambas rutas fáciles de leer. Sus pruebas de paridad evitan que el pequeño mecanismo de direccionamiento duplicado diverja.

La máscara resultante se compartirá más tarde entre la prioridad de sprites y la detección de sprite-zero-hit. Este paso solo la construye; no integra ninguno de los dos consumidores.

Fuera del alcance

composición del framebuffer
integración en Console
integración del sprite-zero-hit
desplazamiento vertical por píxeles
pygame

Implementación de ejemplo completa

# emulator/rendering/ppu_background_renderer.py

# --- NEW BLOCK: COPY FRAMEBUFFER ADDRESSING FOR THE OPACITY-MASK PATH ---
def ppu_background_viewport_to_opaque_mask(
    ppu: PPU,
) -> BackgroundOpaqueMask:
    viewport_x, _ = decode_background_viewport_position(
        temp_vram_addr=ppu.temp_vram_addr,
        fine_x=ppu.fine_x,
    )

    nametable_y = (ppu.temp_vram_addr >> 11) & 1
    left_base = BASE_NAMETABLE_ADDR + nametable_y * 0x0800
    right_base = left_base + 0x0400

    # Same addresses, but call the opacity-mask producer.
    left = ppu_background_to_opaque_mask(
        ppu,
        base_nametable_addr=left_base,
    )
    right = ppu_background_to_opaque_mask(
        ppu,
        base_nametable_addr=right_base,
    )

    # Use the opacity-mask compositor, not the framebuffer compositor.
    return compose_horizontal_opaque_mask_viewport(
        left=left,
        right=right,
        viewport_x=viewport_x,
    )

Ejecutar esta lección

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

Implementación de ejemplo

Implementación de ejemplo completa

# emulator/rendering/ppu_background_renderer.py

# --- NEW BLOCK: COPY FRAMEBUFFER ADDRESSING FOR THE OPACITY-MASK PATH ---
def ppu_background_viewport_to_opaque_mask(
    ppu: PPU,
) -> BackgroundOpaqueMask:
    viewport_x, _ = decode_background_viewport_position(
        temp_vram_addr=ppu.temp_vram_addr,
        fine_x=ppu.fine_x,
    )

    nametable_y = (ppu.temp_vram_addr >> 11) & 1
    left_base = BASE_NAMETABLE_ADDR + nametable_y * 0x0800
    right_base = left_base + 0x0400

    # Same addresses, but call the opacity-mask producer.
    left = ppu_background_to_opaque_mask(
        ppu,
        base_nametable_addr=left_base,
    )
    right = ppu_background_to_opaque_mask(
        ppu,
        base_nametable_addr=right_base,
    )

    # Use the opacity-mask compositor, not the framebuffer compositor.
    return compose_horizontal_opaque_mask_viewport(
        left=left,
        right=right,
        viewport_x=viewport_x,
    )

Ver código del testtest_335_ppu_background_viewport_to_opaque_mask.py

import pytest

from emulator.ppu.ppu import PPU
from emulator.rendering.framebuffer import Framebuffer
from emulator.rendering.nametable_renderer import BackgroundOpaqueMask
import emulator.rendering.ppu_background_renderer as background_renderer
from emulator.rendering.ppu_background_renderer import (
    ppu_background_viewport_to_opaque_mask,
)


@pytest.mark.parametrize(
    ("nametable_y", "expected_left_base", "expected_right_base"),
    [
        (0, 0x2000, 0x2400),
        (1, 0x2800, 0x2C00),
    ],
)
def test_opaque_mask_viewport_copies_framebuffer_addressing_with_mask_functions(
    monkeypatch,
    nametable_y,
    expected_left_base,
    expected_right_base,
):
    """
    Objective:
    Use the same PPU coordinate and logical-pair mapping as framebuffer composition,
    while calling only opacity-mask production and composition functions.
    """
    ppu = PPU()
    ppu.temp_vram_addr = (
        (1 << 10)          # nametable X = 1
        | (nametable_y << 11)
        | 5                # coarse X = 5
    )
    ppu.fine_x = 3

    left: BackgroundOpaqueMask = [False, True]
    right: BackgroundOpaqueMask = [True, False]
    expected_result: BackgroundOpaqueMask = [True, True]
    sources = {
        expected_left_base: left,
        expected_right_base: right,
    }
    rendered_bases: list[int] = []
    captured = {}

    def fake_build_one(ppu_argument, base_nametable_addr):
        assert ppu_argument is ppu
        rendered_bases.append(base_nametable_addr)
        return sources[base_nametable_addr]

    def fake_compose(*, left, right, viewport_x):
        captured["left"] = left
        captured["right"] = right
        captured["viewport_x"] = viewport_x
        return expected_result

    def forbidden_framebuffer_call(*args, **kwargs):
        raise AssertionError("Opacity viewport must not render framebuffers")

    monkeypatch.setattr(
        background_renderer,
        "ppu_background_to_opaque_mask",
        fake_build_one,
    )
    monkeypatch.setattr(
        background_renderer,
        "compose_horizontal_opaque_mask_viewport",
        fake_compose,
    )
    monkeypatch.setattr(
        background_renderer,
        "ppu_background_to_framebuffer",
        forbidden_framebuffer_call,
    )
    monkeypatch.setattr(
        background_renderer,
        "compose_horizontal_framebuffer_viewport",
        forbidden_framebuffer_call,
    )

    result = ppu_background_viewport_to_opaque_mask(ppu)

    assert rendered_bases == [expected_left_base, expected_right_base]
    assert captured["left"] is left
    assert captured["right"] is right
    assert captured["viewport_x"] == 299
    assert result is expected_result


def test_framebuffer_and_mask_adapters_decode_the_same_viewport_x(monkeypatch):
    """
    Objective:
    Protect the duplicated coordinate path from drifting between framebuffer and
    opacity-mask behavior.
    """
    ppu = PPU()
    ppu.temp_vram_addr = (1 << 10) | 5
    ppu.fine_x = 3
    captured = {}

    monkeypatch.setattr(
        background_renderer,
        "ppu_background_to_framebuffer",
        lambda ppu_argument, base_nametable_addr: object(),
    )
    monkeypatch.setattr(
        background_renderer,
        "ppu_background_to_opaque_mask",
        lambda ppu_argument, base_nametable_addr: [False],
    )

    def capture_framebuffer_x(*, left, right, viewport_x):
        captured["framebuffer_x"] = viewport_x
        return Framebuffer()

    def capture_mask_x(*, left, right, viewport_x):
        captured["mask_x"] = viewport_x
        return [False]

    monkeypatch.setattr(
        background_renderer,
        "compose_horizontal_framebuffer_viewport",
        capture_framebuffer_x,
    )
    monkeypatch.setattr(
        background_renderer,
        "compose_horizontal_opaque_mask_viewport",
        capture_mask_x,
    )

    background_renderer.ppu_background_viewport_to_framebuffer(ppu)
    ppu_background_viewport_to_opaque_mask(ppu)

    assert captured["framebuffer_x"] == 299
    assert captured["mask_x"] == 299

Funciones de test (2)

test_opaque_mask_viewport_copies_framebuffer_addressing_with_mask_functions
test_framebuffer_and_mask_adapters_decode_the_same_viewport_x