307. 合成背景与精灵

把背景和精灵合成到一个帧缓冲中。

第 307 / 356 · tests/chapter_09_sprite_rendering/test_307_composite_background_and_sprites.py

需要创建的文件

emulator/rendering/frame_compositor.py

为什么需要这一步

模拟器现在既能渲染背景帧缓冲数据,又能把 OAM 精灵渲染进帧缓冲。这一步把这两条路径结合起来:

background framebuffer + OAM sprites -> final framebuffer

重要的设计选择

合成器应该返回一个新的 Framebuffer,不应修改原始的背景帧缓冲。这样这个函数更易于推理,也更易于测试。

建议的实现示例

from emulator.rendering.framebuffer import Framebuffer
from emulator.rendering.palette_ram import SpritePalettes
from emulator.rendering.sprite_renderer import render_oam_sprites_to_framebuffer


def composite_background_and_sprites(
    background: Framebuffer,
    oam: bytes | bytearray,
    pattern_table: bytes,
    sprite_palettes: SpritePalettes,
) -> Framebuffer:
    framebuffer = Framebuffer(
        width=background.width,
        height=background.height,
        pixels=list(background.pixels),
    )

    render_oam_sprites_to_framebuffer(
        framebuffer,
        oam,
        pattern_table,
        sprite_palettes,
    )

    return framebuffer

本步骤不涉及的内容

精灵在背景后面的优先级
sprite 0 hit
sprite overflow
8x16 精灵
Console 集成
pygame

运行本课

uv run pytest tests/chapter_09_sprite_rendering/test_307_composite_background_and_sprites.py -v

示例实现

建议的实现示例

from emulator.rendering.framebuffer import Framebuffer
from emulator.rendering.palette_ram import SpritePalettes
from emulator.rendering.sprite_renderer import render_oam_sprites_to_framebuffer


def composite_background_and_sprites(
    background: Framebuffer,
    oam: bytes | bytearray,
    pattern_table: bytes,
    sprite_palettes: SpritePalettes,
) -> Framebuffer:
    framebuffer = Framebuffer(
        width=background.width,
        height=background.height,
        pixels=list(background.pixels),
    )

    render_oam_sprites_to_framebuffer(
        framebuffer,
        oam,
        pattern_table,
        sprite_palettes,
    )

    return framebuffer

查看测试代码test_307_composite_background_and_sprites.py

from pathlib import Path

from emulator.rendering.frame_compositor import composite_background_and_sprites
from emulator.rendering.framebuffer import Framebuffer
from tests.chapter_09_sprite_rendering.test_304_render_one_sprite_8x8 import (
    encode_chr_tile,
    make_sprite_palettes,
)
from tests.chapter_09_sprite_rendering.test_306_render_all_oam_sprites import (
    OAM_SIZE,
    make_offscreen_oam,
    write_oam_sprite,
)


def make_single_pixel_tile(color_index: int) -> bytes:
    """Create one CHR tile with a single visible pixel at tile coordinate (0, 0)."""
    return encode_chr_tile(
        [[color_index if x == 0 and y == 0 else 0 for x in range(8)] for y in range(8)]
    )


def test_frame_compositor_file_exists():
    """
    Objective:
    Composition lives in its own rendering module instead of being hidden in
    main.py or Console.
    """
    assert Path("emulator/rendering/frame_compositor.py").exists()


def test_composite_background_and_sprites_returns_new_framebuffer():
    """
    Objective:
    The compositor returns a new framebuffer object rather than mutating and
    returning the original background input.
    """
    background = Framebuffer(width=8, height=8)
    oam = make_offscreen_oam()

    result = composite_background_and_sprites(
        background,
        oam,
        make_single_pixel_tile(1),
        make_sprite_palettes(),
    )

    assert isinstance(result, Framebuffer)
    assert result is not background
    assert result.width == background.width
    assert result.height == background.height


def test_composite_background_and_sprites_does_not_mutate_background():
    """
    Objective:
    The input background framebuffer remains unchanged after sprite overlay.
    """
    background = Framebuffer(width=8, height=8)
    background.set_pixel(0, 0, (1, 2, 3))
    before = list(background.pixels)

    oam = make_offscreen_oam()
    write_oam_sprite(oam, 0, y=0, tile_index=0, attributes=0, x=0)

    result = composite_background_and_sprites(
        background,
        oam,
        make_single_pixel_tile(1),
        make_sprite_palettes(),
    )

    assert background.pixels == before
    assert result.get_pixel(0, 0) == (10, 0, 0)


def test_composite_preserves_background_where_no_sprite_draws():
    """
    Objective:
    Pixels not covered by non-transparent sprite pixels keep their background color.
    """
    background = Framebuffer(width=8, height=8)
    background.set_pixel(5, 5, (44, 55, 66))

    oam = make_offscreen_oam()
    write_oam_sprite(oam, 0, y=0, tile_index=0, attributes=0, x=0)

    result = composite_background_and_sprites(
        background,
        oam,
        make_single_pixel_tile(1),
        make_sprite_palettes(),
    )

    assert result.get_pixel(5, 5) == (44, 55, 66)


def test_composite_overlays_sprite_pixels_on_background_copy():
    """
    Objective:
    Non-transparent sprite pixels appear in the returned framebuffer.
    """
    background = Framebuffer(width=8, height=8)
    background.set_pixel(2, 3, (1, 2, 3))

    oam = make_offscreen_oam()
    write_oam_sprite(oam, 0, y=3, tile_index=0, attributes=0, x=2)

    result = composite_background_and_sprites(
        background,
        oam,
        make_single_pixel_tile(2),
        make_sprite_palettes(),
    )

    assert result.get_pixel(2, 3) == (20, 0, 0)


def test_composite_preserves_background_under_transparent_sprite_pixels():
    """
    Objective:
    Sprite color index 0 is transparent, so background pixels remain visible.
    """
    background = Framebuffer(width=8, height=8)
    background.set_pixel(0, 0, (99, 88, 77))

    oam = make_offscreen_oam()
    write_oam_sprite(oam, 0, y=0, tile_index=0, attributes=0, x=0)

    transparent_tile = encode_chr_tile([[0 for _ in range(8)] for _ in range(8)])

    result = composite_background_and_sprites(
        background,
        oam,
        transparent_tile,
        make_sprite_palettes(),
    )

    assert result.get_pixel(0, 0) == (99, 88, 77)


def test_composite_uses_all_sprite_renderer_priority_behavior():
    """
    Objective:
    Composition should preserve all-sprite OAM priority behavior: lower OAM index
    appears in front when sprites overlap.
    """
    background = Framebuffer(width=8, height=8)
    oam = make_offscreen_oam()
    write_oam_sprite(oam, 0, y=0, tile_index=0, attributes=0, x=0)
    write_oam_sprite(oam, 1, y=0, tile_index=1, attributes=0, x=0)

    pattern_table = make_single_pixel_tile(1) + make_single_pixel_tile(2)

    result = composite_background_and_sprites(
        background,
        oam,
        pattern_table,
        make_sprite_palettes(),
    )

    assert result.get_pixel(0, 0) == (10, 0, 0)


def test_compositor_accepts_bytes_or_bytearray_oam():
    """
    Objective:
    The compositor can use either mutable PPU.oam data or immutable OAM snapshots.
    """
    background = Framebuffer(width=8, height=8)
    oam = make_offscreen_oam()
    write_oam_sprite(oam, 0, y=0, tile_index=0, attributes=0, x=0)

    result_from_bytearray = composite_background_and_sprites(
        background,
        oam,
        make_single_pixel_tile(1),
        make_sprite_palettes(),
    )
    result_from_bytes = composite_background_and_sprites(
        background,
        bytes(oam),
        make_single_pixel_tile(1),
        make_sprite_palettes(),
    )

    assert result_from_bytearray.get_pixel(0, 0) == (10, 0, 0)
    assert result_from_bytes.get_pixel(0, 0) == (10, 0, 0)


def test_compositor_does_not_import_pygame_or_console():
    """
    Objective:
    Composition is pure rendering data logic. Console and pygame integration come
    later.
    """
    source = Path("emulator/rendering/frame_compositor.py").read_text()

    assert "import pygame" not in source
    assert "Console" not in source

测试函数 (9)

test_frame_compositor_file_exists
test_composite_background_and_sprites_returns_new_framebuffer
test_composite_background_and_sprites_does_not_mutate_background
test_composite_preserves_background_where_no_sprite_draws
test_composite_overlays_sprite_pixels_on_background_copy
test_composite_preserves_background_under_transparent_sprite_pixels
test_composite_uses_all_sprite_renderer_priority_behavior
test_compositor_accepts_bytes_or_bytearray_oam
test_compositor_does_not_import_pygame_or_console