Palix: sprites

The video system can display up to 64 sprites at one time. Also called a "movable object block," a sprite is a rectangular bitmap that may include transparent pixels. The sprite width and height can be any combination of 8, 16, 32, or 48 pixel dimensions. For example, an 8 × 8 sprite might be used to display a mouse pointer, whereas a 16 × 48 sprite might show a tall person walking.

Note: The Hybrix designer lets you design resources that are also called "sprites" with features such as animation clips and board placement. That concept is a bit different from IO_SPRITE, which is the primitive hardware interface. For example, the Hybrix framework's ACTOR class animates sprite clips by periodically updating IO_SPRITE::PIXELS_ADDRESS to point to the next animation frame.

Basics

The IO_SPRITE::X and IO_SPRITE::Y fields position the sprite on the screen. The coordinate origin is in the upper-left corner of the screen, with the Y axis pointing downwards and the X axis pointing to the right.

The IO_SPRITE::PIXELS field stores the memory address of the pixels, one byte per pixel. The number of pixels is IO_SPRITE::WIDTH∗IO_SPRITE::HEIGHT, and the first byte is the upper-left pixel of the sprite. The bytes are interpreted according to the color palette of the IO_SPRITE::THEME. A zero byte is typically transparent.

Note: If IO_SPRITE::PIXELS points to a Hybrix language array, it should be the address of the first array element, not the address of the memory block (which starts with an array size TRIO).

Display priority

There are four sprite layers. Layer 0 appears in front of Tilemap A. Layer 1 appears between Tilemap A and Tilemap B, Layer 2 between Tilemap C and Tilemap D, and Layer 3 appears behind all the tilemaps. The layer assignment is controlled by IO_SPRITE::FLAGS, or ACTOR::LAYER when using the framework engine.

Level	Notes
Sprite Layer #0	🡅 (displayed in the front)
Tile Layer A	shows the framework CONSOLE
Sprite Layer #1	ACTOR.LAYER default for the framework actors
Tile Layer B	used for the framework scene tilemap
Sprite Layer #2
Tile Layer C
Sprite Layer #3	🡇 (displayed in the back)

Within a layer, the IO::SPRITES array is rendered from front to back. For example, IO::SPRITES[0] will appear in front of IO::SPRITES[1] if both sprites belong to the same layer.

IO_SPRITE::FLAGS can "flip" sprites horizontally (X) or vertically (Y) or both. This is a bitmap reflection transform that does not alter the sprite's visual position. For example, flipping horizontally can be used to make a game character face to the left instead of to the right. Flipping vertically would make them appear upside down.

For square sprites (whose width and height are equal), IO_SPRITE::FLAGS can also rotate the sprite 90° clockwise. The 180° and 270° rotations can be obtained by combining rotation and flipping.

Code sample

This code sample animates an 8 × 8 sprite by directly writing to I/O memory.

MODULE MAIN
  FUNC START()
    VAR SPRITE: IO_SPRITE
    VAR PIXELS: BYTE[SIZE 64]
    VAR I: INT

    NEW BYTE[SIZE 64]() -> PIXELS
    0 -> I
    LOOP
      IF I = 64
      DO DROP
      TO_BYTE(I % 7) -> PIXELS[I]
      I + 1 -> I
    END LOOP

    IO::SPRITES[0] -> SPRITE
    8 -> SPRITE.WIDTH
    8 -> SPRITE.HEIGHT
    TO_ADDRESS(PIXELS) -> SPRITE.PIXELS_ADDRESS

    LOOP
      (IO::FRAME_COUNTER % 320) -> SPRITE.X
      1 -> SPRITE.Y
    END LOOP
  END FUNC
END MODULE

I/O definitions

CLASS IO_SPRITE # SIZE 16
  # SCREEN COORDINATES
  VAR X: PAIR, Y: PAIR

  # POSSIBLE VALUES: 8, 16, 32, 48
  VAR WIDTH: BYTE, HEIGHT: BYTE

  # LAYER:
  # 0   = IN FRONT OF ALL TILEMAPS
  # 1   = BEHIND TILEMAP A, IN FRONT OF B
  # 2   = BEHIND TILEMAP B, IN FRONT OF C
  # 3   = BEHIND ALL TILEMAPS
  #
  # TRANSFORM:
  # +4  = FLIP X (HORIZONTAL)
  # +8  = FLIP Y (VERTICAL)
  # +16 = ROTATE CLOCKWISE 90 DEGREES, ONLY IF SPRITE IS SQUARE
  VAR FLAGS: BYTE

  # THE THEME IS AN INDEX (0..31) INTO IO::THEMES
  VAR THEME: BYTE

  # THE ADDRESS OF THE PIXEL BUFFER.  TO HIDE THE SPRITE, SET PIXELS_ADDRESS=0
  VAR PIXELS_ADDRESS: INT

  VAR RESERVED: INT
END CLASS

MODULE IO
  . . .
  INSET SPRITES: IO_SPRITE[INSET 64]          LOCATED AT $D0_0400 # ..$D0_07FF
  . . .
END MODULE