305. Soporte de volteo en el renderizado de sprites

Añadir soporte de volteo horizontal y vertical al renderizado de un sprite.

Lección 305 de 356 · tests/chapter_09_sprite_rendering/test_305_sprite_render_flip_support.py

Archivo a actualizar

emulator/rendering/sprite_renderer.py

Por qué existe este paso

Los atributos de sprite ya decodifican los bits de volteo horizontal y vertical. El renderizador de un sprite ahora debería usar esos bits al elegir qué píxel CHR dibujar.

Bits de volteo en los atributos de sprite

bit 6: horizontal flip
bit 7: vertical flip

Modelo importante

El volteo refleja la imagen dentro de la caja 8x8 del sprite. No mueve la posición del sprite en pantalla.

Ejemplo de implementación sugerido dentro de render_sprite_8x8_to_framebuffer():

for tile_y in range(8):
    for tile_x in range(8):
        source_x = 7 - tile_x if attributes.flip_horizontal else tile_x
        source_y = 7 - tile_y if attributes.flip_vertical else tile_y

        color_index = color_indexes[source_y][source_x]

        if color_index == 0:
            continue

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

        ...

Ejemplo mínimo

original row:          1 2 3 . . . . .
horizontal flip row:   . . . . . 3 2 1

Concepto erróneo frecuente

"Horizontal flip should change sprite.x."

No. La caja de destino permanece en sprite.x/sprite.y. Solo se refleja la búsqueda del píxel de origen.

Fuera del alcance

renderizado de los 64 sprites
prioridad de sprite detrás del fondo
sprite 0 hit
sprite overflow
pygame

Ejecutar esta lección

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

Implementación de ejemplo

Modelo importante

for tile_y in range(8):
    for tile_x in range(8):
        source_x = 7 - tile_x if attributes.flip_horizontal else tile_x
        source_y = 7 - tile_y if attributes.flip_vertical else tile_y

        color_index = color_indexes[source_y][source_x]

        if color_index == 0:
            continue

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

        ...

Ver código del testtest_305_sprite_render_flip_support.py

from pathlib import Path

from emulator.rendering.framebuffer import BLACK, Framebuffer
from emulator.rendering.sprite_renderer import (
    SPRITE_FLIP_HORIZONTAL,
    SPRITE_FLIP_VERTICAL,
    SpriteEntry,
    render_sprite_8x8_to_framebuffer,
)
from tests.chapter_09_sprite_rendering.test_304_render_one_sprite_8x8 import (
    encode_chr_tile,
    make_sprite_palettes,
)


def make_corner_marker_tile() -> bytes:
    """
    Build a tile with visible pixels in distinct corners.

    Color index placement:
        top-left     = 1
        top-right    = 2
        bottom-left  = 3
        bottom-right = 1
    """
    grid = [[0 for _ in range(8)] for _ in range(8)]
    grid[0][0] = 1
    grid[0][7] = 2
    grid[7][0] = 3
    grid[7][7] = 1
    return encode_chr_tile(grid)


def test_horizontal_flip_mirrors_sprite_pixels_left_to_right():
    """
    Objective:
    Horizontal flip mirrors source pixels along the X axis inside the 8x8 sprite box.
    """
    framebuffer = Framebuffer(width=8, height=8)
    sprite = SpriteEntry(
        y=0,
        tile_index=0,
        attributes=SPRITE_FLIP_HORIZONTAL,
        x=0,
    )

    render_sprite_8x8_to_framebuffer(
        framebuffer,
        sprite,
        make_corner_marker_tile(),
        make_sprite_palettes(),
    )

    assert framebuffer.get_pixel(7, 0) == (10, 0, 0)  # original top-left moved right
    assert framebuffer.get_pixel(0, 0) == (20, 0, 0)  # original top-right moved left
    assert framebuffer.get_pixel(7, 7) == (30, 0, 0)  # original bottom-left moved right
    assert framebuffer.get_pixel(0, 7) == (10, 0, 0)  # original bottom-right moved left


def test_vertical_flip_mirrors_sprite_pixels_top_to_bottom():
    """
    Objective:
    Vertical flip mirrors source pixels along the Y axis inside the 8x8 sprite box.
    """
    framebuffer = Framebuffer(width=8, height=8)
    sprite = SpriteEntry(
        y=0,
        tile_index=0,
        attributes=SPRITE_FLIP_VERTICAL,
        x=0,
    )

    render_sprite_8x8_to_framebuffer(
        framebuffer,
        sprite,
        make_corner_marker_tile(),
        make_sprite_palettes(),
    )

    assert framebuffer.get_pixel(0, 7) == (10, 0, 0)  # original top-left moved down
    assert framebuffer.get_pixel(7, 7) == (20, 0, 0)  # original top-right moved down
    assert framebuffer.get_pixel(0, 0) == (30, 0, 0)  # original bottom-left moved up
    assert framebuffer.get_pixel(7, 0) == (10, 0, 0)  # original bottom-right moved up


def test_horizontal_and_vertical_flip_work_together():
    """
    Objective:
    When both flip bits are set, pixels are mirrored on both axes.
    """
    framebuffer = Framebuffer(width=8, height=8)
    sprite = SpriteEntry(
        y=0,
        tile_index=0,
        attributes=SPRITE_FLIP_HORIZONTAL | SPRITE_FLIP_VERTICAL,
        x=0,
    )

    render_sprite_8x8_to_framebuffer(
        framebuffer,
        sprite,
        make_corner_marker_tile(),
        make_sprite_palettes(),
    )

    assert framebuffer.get_pixel(7, 7) == (10, 0, 0)  # original top-left
    assert framebuffer.get_pixel(0, 7) == (20, 0, 0)  # original top-right
    assert framebuffer.get_pixel(7, 0) == (30, 0, 0)  # original bottom-left
    assert framebuffer.get_pixel(0, 0) == (10, 0, 0)  # original bottom-right


def test_flip_does_not_change_sprite_screen_position():
    """
    Objective:
    Flipping mirrors pixels inside the 8x8 box but keeps the destination box at
    sprite.x and sprite.y.
    """
    tile = encode_chr_tile(
        [[1 if x == 7 and y == 7 else 0 for x in range(8)] for y in range(8)]
    )
    framebuffer = Framebuffer(width=16, height=16)
    sprite = SpriteEntry(
        y=4,
        tile_index=0,
        attributes=SPRITE_FLIP_HORIZONTAL | SPRITE_FLIP_VERTICAL,
        x=5,
    )

    render_sprite_8x8_to_framebuffer(framebuffer, sprite, tile, make_sprite_palettes())

    assert framebuffer.get_pixel(5, 4) == (10, 0, 0)
    assert framebuffer.get_pixel(4, 4) == BLACK
    assert framebuffer.get_pixel(13, 12) == BLACK


def test_transparency_still_applies_after_flip():
    """
    Objective:
    Color index 0 remains transparent even when the source pixel is selected through
    flipped coordinates.
    """
    tile = encode_chr_tile(
        [[1 if x == 7 and y == 0 else 0 for x in range(8)] for y in range(8)]
    )
    framebuffer = Framebuffer(width=8, height=8)
    framebuffer.set_pixel(7, 0, (99, 88, 77))
    sprite = SpriteEntry(y=0, tile_index=0, attributes=SPRITE_FLIP_HORIZONTAL, x=0)

    render_sprite_8x8_to_framebuffer(framebuffer, sprite, tile, make_sprite_palettes())

    assert framebuffer.get_pixel(0, 0) == (10, 0, 0)
    assert framebuffer.get_pixel(7, 0) == (99, 88, 77)


def test_flip_support_does_not_import_pygame_or_render_all_sprites():
    """
    Objective:
    Flip support belongs to pure one-sprite framebuffer rendering. It should not add
    frontend dependencies or all-sprite logic yet.
    """
    source = Path("emulator/rendering/sprite_renderer.py").read_text()

    assert "import pygame" not in source
    assert "render_all" not in source

Funciones de test (6)

test_horizontal_flip_mirrors_sprite_pixels_left_to_right
test_vertical_flip_mirrors_sprite_pixels_top_to_bottom
test_horizontal_and_vertical_flip_work_together
test_flip_does_not_change_sprite_screen_position
test_transparency_still_applies_after_flip
test_flip_support_does_not_import_pygame_or_render_all_sprites