330. Композиция горизонтальной области просмотра фреймбуфера

Составить область просмотра 256x240 из двух соседних фреймбуферов nametable по горизонтали.

Урок 330 из 356 · tests/chapter_13_scrolling/test_330_compose_horizontal_framebuffer_viewport.py

Файл для обновления

emulator/rendering/background_viewport.py

Справочная документация

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

Зачем нужен этот шаг

Каждый отрисованный nametable имеет ширину 256 пикселей, но горизонтальная прокрутка может привести к тому, что один экран будет содержать пиксели из двух соседних nametable. Этот шаг рассматривает их как один логический фон 512x240 и выбирает из него область просмотра 256x240.

Модель координат

left framebuffer:  logical X   0-255
right framebuffer: logical X 256-511

Для каждого целевого X экрана

logical X = (viewport X + screen X) modulo 512

Операция по модулю оборачивает правый край логической пары обратно к её левому краю.

Пример стыка

viewport X = 200

screen X   0-55  <- left X 200-255
screen X  56-255 <- right X   0-199

Инварианты

оба исходных фреймбуфера имеют размер ровно 256x240
возвращаемый фреймбуфер имеет размер ровно 256x240
ни один из исходных фреймбуферов не изменяется
каждый выходной пиксель берётся из одной и той же строки Y одного исходного фреймбуфера

Распространённое заблуждение

Эта функция не реализует зеркалирование nametable картриджа. PpuBus владеет зеркалированием адресов; эта функция лишь составляет уже отрисованных логических соседей.

Вне рамок

вертикальная прокрутка
композиция маски непрозрачности фона
чтения PPU или PpuBus
рендеринг тайлов nametable
интеграция с Console
pygame
точные переносы v/t по тактам

Полный пример реализации

# emulator/rendering/background_viewport.py

from emulator.rendering.framebuffer import Framebuffer


def compose_horizontal_framebuffer_viewport(
    left: Framebuffer,
    right: Framebuffer,
    viewport_x: int,
) -> Framebuffer:
    expected_size = (
        NAMETABLE_PIXEL_WIDTH,
        NAMETABLE_PIXEL_HEIGHT,
    )

    if (left.width, left.height) != expected_size:
        raise ValueError("Left nametable framebuffer must be 256x240")

    if (right.width, right.height) != expected_size:
        raise ValueError("Right nametable framebuffer must be 256x240")

    logical_width = NAMETABLE_PIXEL_WIDTH * 2
    result = Framebuffer(
        width=NAMETABLE_PIXEL_WIDTH,
        height=NAMETABLE_PIXEL_HEIGHT,
    )

    for screen_y in range(NAMETABLE_PIXEL_HEIGHT):
        for screen_x in range(NAMETABLE_PIXEL_WIDTH):
            logical_x = (viewport_x + screen_x) % logical_width

            if logical_x < NAMETABLE_PIXEL_WIDTH:
                source = left
                source_x = logical_x
            else:
                source = right
                source_x = logical_x - NAMETABLE_PIXEL_WIDTH

            color = source.get_pixel(source_x, screen_y)
            result.set_pixel(screen_x, screen_y, color)

    return result

Запустить этот урок

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

Пример реализации

Полный пример реализации

# emulator/rendering/background_viewport.py

from emulator.rendering.framebuffer import Framebuffer


def compose_horizontal_framebuffer_viewport(
    left: Framebuffer,
    right: Framebuffer,
    viewport_x: int,
) -> Framebuffer:
    expected_size = (
        NAMETABLE_PIXEL_WIDTH,
        NAMETABLE_PIXEL_HEIGHT,
    )

    if (left.width, left.height) != expected_size:
        raise ValueError("Left nametable framebuffer must be 256x240")

    if (right.width, right.height) != expected_size:
        raise ValueError("Right nametable framebuffer must be 256x240")

    logical_width = NAMETABLE_PIXEL_WIDTH * 2
    result = Framebuffer(
        width=NAMETABLE_PIXEL_WIDTH,
        height=NAMETABLE_PIXEL_HEIGHT,
    )

    for screen_y in range(NAMETABLE_PIXEL_HEIGHT):
        for screen_x in range(NAMETABLE_PIXEL_WIDTH):
            logical_x = (viewport_x + screen_x) % logical_width

            if logical_x < NAMETABLE_PIXEL_WIDTH:
                source = left
                source_x = logical_x
            else:
                source = right
                source_x = logical_x - NAMETABLE_PIXEL_WIDTH

            color = source.get_pixel(source_x, screen_y)
            result.set_pixel(screen_x, screen_y, color)

    return result

Показать код тестаtest_330_compose_horizontal_framebuffer_viewport.py

import pytest

from emulator.rendering.background_viewport import (
    NAMETABLE_PIXEL_HEIGHT,
    NAMETABLE_PIXEL_WIDTH,
    compose_horizontal_framebuffer_viewport,
)
from emulator.rendering.framebuffer import Framebuffer, RGBColor


LEFT_COLOR: RGBColor = (10, 20, 30)
RIGHT_COLOR: RGBColor = (40, 50, 60)


def solid_nametable_framebuffer(color: RGBColor) -> Framebuffer:
    """Create one rendered nametable whose source is easy to identify."""
    return Framebuffer(
        width=NAMETABLE_PIXEL_WIDTH,
        height=NAMETABLE_PIXEL_HEIGHT,
        pixels=[color] * (NAMETABLE_PIXEL_WIDTH * NAMETABLE_PIXEL_HEIGHT),
    )


def coordinate_nametable_framebuffer(source_id: int) -> Framebuffer:
    """Encode source identity and coordinates into each RGB pixel."""
    return Framebuffer(
        width=NAMETABLE_PIXEL_WIDTH,
        height=NAMETABLE_PIXEL_HEIGHT,
        pixels=[
            (source_id, x, y)
            for y in range(NAMETABLE_PIXEL_HEIGHT)
            for x in range(NAMETABLE_PIXEL_WIDTH)
        ],
    )


def test_viewport_at_zero_uses_the_entire_left_nametable():
    """
    Objective:
    With no horizontal offset, the visible screen is the left logical nametable.
    """
    left = solid_nametable_framebuffer(LEFT_COLOR)
    right = solid_nametable_framebuffer(RIGHT_COLOR)

    result = compose_horizontal_framebuffer_viewport(left, right, viewport_x=0)

    assert result.width == NAMETABLE_PIXEL_WIDTH
    assert result.height == NAMETABLE_PIXEL_HEIGHT
    assert result.pixels == left.pixels
    assert result is not left


def test_viewport_at_256_uses_the_entire_right_nametable():
    """
    Objective:
    Logical X 256 is the first pixel column of the right nametable.
    """
    left = solid_nametable_framebuffer(LEFT_COLOR)
    right = solid_nametable_framebuffer(RIGHT_COLOR)

    result = compose_horizontal_framebuffer_viewport(left, right, viewport_x=256)

    assert result.pixels == right.pixels
    assert result is not right


def test_viewport_at_200_crosses_the_nametable_seam_on_every_row():
    """
    Objective:
    Compose 56 columns from the end of the left nametable and 200 columns from the
    beginning of the right nametable without changing Y rows.
    """
    left = coordinate_nametable_framebuffer(source_id=1)
    right = coordinate_nametable_framebuffer(source_id=2)

    result = compose_horizontal_framebuffer_viewport(left, right, viewport_x=200)

    expected_pixels: list[RGBColor] = []
    for y in range(NAMETABLE_PIXEL_HEIGHT):
        row_start = y * NAMETABLE_PIXEL_WIDTH
        row_end = row_start + NAMETABLE_PIXEL_WIDTH
        expected_pixels.extend(left.pixels[row_start + 200:row_end])
        expected_pixels.extend(right.pixels[row_start:row_start + 200])

    assert result.pixels == expected_pixels


def test_viewport_wraps_from_right_nametable_back_to_left():
    """
    Objective:
    A viewport beginning at logical X 300 consumes 212 right-hand columns before
    wrapping to 44 columns from the left nametable.
    """
    left = coordinate_nametable_framebuffer(source_id=1)
    right = coordinate_nametable_framebuffer(source_id=2)

    result = compose_horizontal_framebuffer_viewport(left, right, viewport_x=300)

    assert result.get_pixel(0, 0) == right.get_pixel(44, 0)
    assert result.get_pixel(211, 0) == right.get_pixel(255, 0)
    assert result.get_pixel(212, 0) == left.get_pixel(0, 0)
    assert result.get_pixel(255, 239) == left.get_pixel(43, 239)


def test_composition_does_not_mutate_either_source_framebuffer():
    """
    Objective:
    Keep viewport composition pure so source nametables can be reused and failures
    remain local to the returned framebuffer.
    """
    left = coordinate_nametable_framebuffer(source_id=1)
    right = coordinate_nametable_framebuffer(source_id=2)
    left_before = list(left.pixels)
    right_before = list(right.pixels)

    result = compose_horizontal_framebuffer_viewport(left, right, viewport_x=200)

    assert left.pixels == left_before
    assert right.pixels == right_before
    assert result is not left
    assert result is not right


def test_rejects_left_framebuffer_with_wrong_dimensions():
    """
    Objective:
    Reject an invalid left source at the function boundary instead of failing during
    pixel indexing.
    """
    left = Framebuffer(width=255, height=240)
    right = solid_nametable_framebuffer(RIGHT_COLOR)

    with pytest.raises(ValueError, match="Left nametable framebuffer"):
        compose_horizontal_framebuffer_viewport(left, right, viewport_x=0)


def test_rejects_right_framebuffer_with_wrong_dimensions():
    """
    Objective:
    Apply the same explicit dimension invariant to the right source.
    """
    left = solid_nametable_framebuffer(LEFT_COLOR)
    right = Framebuffer(width=256, height=239)

    with pytest.raises(ValueError, match="Right nametable framebuffer"):
        compose_horizontal_framebuffer_viewport(left, right, viewport_x=0)

Тестовые функции (7)

test_viewport_at_zero_uses_the_entire_left_nametable
test_viewport_at_256_uses_the_entire_right_nametable
test_viewport_at_200_crosses_the_nametable_seam_on_every_row
test_viewport_wraps_from_right_nametable_back_to_left
test_composition_does_not_mutate_either_source_framebuffer
test_rejects_left_framebuffer_with_wrong_dimensions
test_rejects_right_framebuffer_with_wrong_dimensions