312. 精灵优先级使用背景不透明掩码

使用背景不透明度掩码来应用精灵优先级第 5 位。

第 312 / 356 · tests/chapter_09_sprite_rendering/test_312_sprite_priority_uses_background_opaque_mask.py

需要更新的文件

emulator/rendering/sprite_renderer.py

为什么需要这一步

步骤 310 构建了逐像素的背景不透明度掩码。步骤 311 将该掩码传递到了精灵渲染流水线中。这一步最终在单精灵渲染器中使用该掩码。

规则

If a sprite pixel is non-transparent,
and the sprite has priority bit 5 set,
and the background mask says that screen pixel is opaque,
then keep the background pixel and skip drawing the sprite pixel.

重要的顺序要求

1. sprite CHR color index 0 -> skip
2. offscreen pixel -> skip
3. behind-background sprite over opaque background -> skip
4. otherwise draw sprite pixel

示例实现片段

def render_sprite_8x8_to_framebuffer (...) -> ...

...
... 

screen_x = sprite.x + tile_x
screen_y = sprite.y + tile_y

if not (0 <= screen_x < framebuffer.width):
    continue
if not (0 <= screen_y < framebuffer.height):
    continue

# --- ADD THIS NEW BLOCK ---
if (
    background_opaque_mask is not None
    and attributes.is_behind_background
    and background_opaque_mask[screen_y * framebuffer.width + screen_x]
):
    continue
# --- END NEW BLOCK ---

framebuffer.set_pixel(...)

为什么要在裁剪之后？掩码索引使用的是屏幕坐标。如果在检查像素是否在屏幕内之前就对掩码进行索引，屏幕外的精灵可能会读取到错误的掩码项，或引发 IndexError。

本步骤范围之外

在 Console.render_framebuffer() 内部构建掩码
根据 PPUCTRL 第 4 位选择背景图案表
精灵 0 命中
精灵溢出
pygame

运行本课

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

示例实现

示例实现片段

...
... 

screen_x = sprite.x + tile_x
screen_y = sprite.y + tile_y

if not (0 <= screen_x < framebuffer.width):
    continue
if not (0 <= screen_y < framebuffer.height):
    continue

# --- ADD THIS NEW BLOCK ---
if (
    background_opaque_mask is not None
    and attributes.is_behind_background
    and background_opaque_mask[screen_y * framebuffer.width + screen_x]
):
    continue
# --- END NEW BLOCK ---

framebuffer.set_pixel(...)

查看测试代码test_312_sprite_priority_uses_background_opaque_mask.py

from emulator.rendering.framebuffer import Framebuffer
from emulator.rendering.nametable_renderer import BackgroundOpaqueMask
from emulator.rendering.sprite_renderer import (
    SPRITE_IS_BEHIND_BACKGROUND,
    SpriteEntry,
    render_sprite_8x8_to_framebuffer,
)
from tests.chapter_09_sprite_rendering.test_304_render_one_sprite_8x8 import encode_chr_tile


BACKGROUND_COLOR = (1, 1, 1)
SPRITE_COLOR = (200, 20, 20)


def make_pattern_table_with_one_tile(tile: bytes) -> bytes:
    pattern_table = bytearray(0x1000)
    pattern_table[0:16] = tile
    return bytes(pattern_table)


def make_tile_with_single_pixel(x: int, y: int, color_index: int) -> bytes:
    grid = [[0 for _ in range(8)] for _ in range(8)]
    grid[y][x] = color_index
    return encode_chr_tile(grid)


def make_sprite_palettes():
    return [
        [(0, 0, 0), SPRITE_COLOR, (0, 200, 0), (0, 0, 200)],
        [(0, 0, 0)] * 4,
        [(0, 0, 0)] * 4,
        [(0, 0, 0)] * 4,
    ]


def make_background_framebuffer() -> Framebuffer:
    return Framebuffer(
        width=8,
        height=8,
        pixels=[BACKGROUND_COLOR] * 64,
    )


def test_behind_background_sprite_is_hidden_when_background_mask_is_opaque():
    """
    Objective:
    Priority bit 5 should prevent a sprite pixel from replacing an opaque
    background pixel.
    """
    framebuffer = make_background_framebuffer()
    pattern_table = make_pattern_table_with_one_tile(
        make_tile_with_single_pixel(x=0, y=0, color_index=1)
    )
    sprite = SpriteEntry(
        y=0,
        tile_index=0,
        attributes=SPRITE_IS_BEHIND_BACKGROUND,
        x=0,
    )
    mask: BackgroundOpaqueMask = [True] * 64

    render_sprite_8x8_to_framebuffer(
        framebuffer=framebuffer,
        sprite=sprite,
        pattern_table=pattern_table,
        sprite_palettes=make_sprite_palettes(),
        background_opaque_mask=mask,
    )

    assert framebuffer.get_pixel(0, 0) == BACKGROUND_COLOR


def test_behind_background_sprite_draws_when_background_mask_is_transparent():
    """
    Objective:
    A behind-background sprite is still visible where the background CHR color index
    was zero.
    """
    framebuffer = make_background_framebuffer()
    pattern_table = make_pattern_table_with_one_tile(
        make_tile_with_single_pixel(x=0, y=0, color_index=1)
    )
    sprite = SpriteEntry(
        y=0,
        tile_index=0,
        attributes=SPRITE_IS_BEHIND_BACKGROUND,
        x=0,
    )
    mask: BackgroundOpaqueMask = [False] * 64

    render_sprite_8x8_to_framebuffer(
        framebuffer=framebuffer,
        sprite=sprite,
        pattern_table=pattern_table,
        sprite_palettes=make_sprite_palettes(),
        background_opaque_mask=mask,
    )

    assert framebuffer.get_pixel(0, 0) == SPRITE_COLOR


def test_front_priority_sprite_draws_even_when_background_mask_is_opaque():
    """
    Objective:
    The mask only hides sprites whose priority bit says they are behind the
    background.
    """
    framebuffer = make_background_framebuffer()
    pattern_table = make_pattern_table_with_one_tile(
        make_tile_with_single_pixel(x=0, y=0, color_index=1)
    )
    sprite = SpriteEntry(
        y=0,
        tile_index=0,
        attributes=0,
        x=0,
    )
    mask: BackgroundOpaqueMask = [True] * 64

    render_sprite_8x8_to_framebuffer(
        framebuffer=framebuffer,
        sprite=sprite,
        pattern_table=pattern_table,
        sprite_palettes=make_sprite_palettes(),
        background_opaque_mask=mask,
    )

    assert framebuffer.get_pixel(0, 0) == SPRITE_COLOR


def test_transparent_sprite_pixel_still_draws_nothing_even_with_transparent_background_mask():
    """
    Objective:
    Sprite CHR color index 0 remains transparent. The background mask does not make
    transparent sprite pixels visible.
    """
    framebuffer = make_background_framebuffer()
    pattern_table = make_pattern_table_with_one_tile(
        make_tile_with_single_pixel(x=0, y=0, color_index=0)
    )
    sprite = SpriteEntry(
        y=0,
        tile_index=0,
        attributes=SPRITE_IS_BEHIND_BACKGROUND,
        x=0,
    )
    mask: BackgroundOpaqueMask = [False] * 64

    render_sprite_8x8_to_framebuffer(
        framebuffer=framebuffer,
        sprite=sprite,
        pattern_table=pattern_table,
        sprite_palettes=make_sprite_palettes(),
        background_opaque_mask=mask,
    )

    assert framebuffer.get_pixel(0, 0) == BACKGROUND_COLOR


def test_priority_mask_is_not_required_for_old_front_sprite_behavior():
    """
    Objective:
    The optional mask keeps old callers working. Without a mask, non-transparent
    sprite pixels still draw as before.
    """
    framebuffer = make_background_framebuffer()
    pattern_table = make_pattern_table_with_one_tile(
        make_tile_with_single_pixel(x=0, y=0, color_index=1)
    )
    sprite = SpriteEntry(
        y=0,
        tile_index=0,
        attributes=SPRITE_IS_BEHIND_BACKGROUND,
        x=0,
    )

    render_sprite_8x8_to_framebuffer(
        framebuffer=framebuffer,
        sprite=sprite,
        pattern_table=pattern_table,
        sprite_palettes=make_sprite_palettes(),
    )

    assert framebuffer.get_pixel(0, 0) == SPRITE_COLOR

测试函数 (5)

test_behind_background_sprite_is_hidden_when_background_mask_is_opaque
test_behind_background_sprite_draws_when_background_mask_is_transparent
test_front_priority_sprite_draws_even_when_background_mask_is_opaque
test_transparent_sprite_pixel_still_draws_nothing_even_with_transparent_background_mask
test_priority_mask_is_not_required_for_old_front_sprite_behavior