# Sprites

Sprites are two-dimensional images that you can draw on a framebuffer. In computer graphics, the term "sprite" is often used to refer to fixed images, like a spaceship or character that is moved around the screen while the games is played. The Ready Set STEM API provides a `Sprite()` function to create sprites that can be then be placed at different locations on the screen — we also provide functions to allow you to flip, crop and rotate your sprite on the display.

To create a sprite, you can use the the `Sprite()` function with a string representing the sprite:

    Sprite(string_sprite)

The `string_sprite` is a multiple line string, with each character in the string representing the color of one point of the sprite. Each row of the sprite much have the same number of points.

Multiline Strings

Sometimes, you'll want to create a string that has multiple lines. For example, to `print()` a your grocery list, you might do the following:

    print("Cheeze Whiz")
    print("Snickers")
    print("Mangoes")

However, it is sometimes useful to be able to put several lines all together in one string. Python provides a way to do this with multiline strings. Multiline strings start and end with 3 quotes. For example, to print the above grocery list with only one print statement, you could use:

    print("""Cheeze Whiz
    Snickers
    Mangoes""")

Just like single-line strings, multiline strings can be enclosed with double quotes or single-quotes, but remember, you'll need 3 of them.

The sprite colors range from 0 through 15, as discussed previously in . To represent the colors in the `string_sprite`, we need to use only one digit for each character. So, we use the digits 0 through 9 followed by A through F (where A=10, B=11, and so forth). Plus, sprites add a new color: transparent. To use it, you can put a dash ('-') in the sprite string.

The full list of colors for sprites is:

LED COLOR
0
1
2
3
4
5
6
7
8
9
A
B
C
D
E
F
-

For example, a up-arrow sprite could be created with:

from rstem.led_matrix import Sprite up_arrow = Sprite(""" 00F00 0FFF0 F0F0F 00F00 00F00 00F00 """)

The `Sprite()` function doesn't care if you add extra spaces at the beginning or end of a line, or if you add extra blank lines. Once you have created a sprite, you can draw it on your framebuffer with the framebuffer's `draw()` function:

from rstem.led_matrix import Sprite from rstem.led_matrix import FrameBuffer fb = FrameBuffer() up_arrow = Sprite(""" 00F00 0FFF0 F0F0F 00F00 00F00 00F00 """) fb.erase() fb.draw(up_arrow) fb.show()

Similar to framebuffers, sprites can also tell you how high and wide they are, for example, to print the height and width of our arrow:

print(up_arrow.height) print(up_arrow.width)

Finally, sprites have several function that allow you to modify the sprite:

- The `crop()` function will clip out a rectangular portion of the sprite. It takes two parameters: `origin`, which is the lower left corner of the rectangle, and the `dimensions` of the rectangle. Once cropped, the sprite will generally be smaller than the original.

- The `rotate()` function will rotate the sprite in multiples of 90 degrees. It takes one parameter, which is the `angle` to rotate.

- The `flip()` function will flip the sprite horizontally or vertically. It takes one parameter, `vertical`, which is should be `True` to flip vertically, or `False` to flip horizontally.

- The `reset()` function will undo any previous changes to the sprite, restoring it to its original state.

Like sound chains described in , sprite functions can be chained. This means that you can do multiple operations (crop, flip, rotate), together in one brief statement.

# Examples

Here's a set of examples that all use the same sprite, a flag, as defined below:

from rstem.led_matrix import Sprite from rstem.led_matrix import FrameBuffer fb = FrameBuffer() flag = Sprite(""" ---FF --F4F -F44F FFFFF ----F ----F ----F ----F """) fb.erase() fb.draw(flag) fb.show()

Before drawing the flag (just before the `fb.draw()` function above), there's a number of operation we could do to modify it. The following table shows what the flag would look like for various operations:

Functions | LED Matrix
--- | ---
`fb.draw(flag)` |
    000FF000
    00F4F000
    0F44F000
    FFFFF000
    0000F000
    0000F000
    0000F000
    0000F000
`# Shift right and up` `fb.draw(flag, (2,3))` |
    00FFFFF0
    000000F0
    000000F0
    000000F0
    000000F0
    00000000
    00000000
    00000000
`# Crop the trianglar part` `flag.crop((0,4), (4,4))` `fb.draw(flag)` |
    00000000
    00000000
    00000000
    00000000
    000F0000
    00F40000
    0F440000
    FFFF0000
`# Draw the triangular part shifted right and up` `flag.crop((0,4), (4,4))` `fb.draw(flag, (3,2))` |
    00000000
    00000000
    000000F0
    00000F40
    0000F440
    000FFFF0
    00000000
    00000000
`# Rotate 90 degrees` `flag.rotate(90)` `fb.draw(flag)` |
    00000000
    00000000
    00000000
    FFFFFFFF
    F44F0000
    0F4F0000
    00FF0000
    000F0000
`# Rotate 180 degrees` `flag.rotate(180)` `fb.draw(flag)` |
    F0000000
    F0000000
    F0000000
    F0000000
    FFFFF000
    F44F0000
    F4F00000
    FF000000
`# Rotate 270 degrees` `flag.rotate(270)` `fb.draw(flag)` |
    00000000
    00000000
    00000000
    0000F000
    0000FF00
    0000F4F0
    0000F44F
    FFFFFFFF
`# Flip horizontally` `flag.flip(vertical=False)` `fb.draw(flag)` |
    FF000000
    F4F00000
    F44F0000
    FFFFF000
    F0000000
    F0000000
    F0000000
    F0000000
`# Flip veritcally` `flag.flip(vertical=True)` `fb.draw(flag)` |
    0000F000
    0000F000
    0000F000
    0000F000
    FFFFF000
    0F44F000
    00F4F000
    000FF000
`# Crop the trianglar part, then rotate` `flag.crop((0,4), (4,4)).rotate(90)` `fb.draw(flag)` |
    00000000
    00000000
    00000000
    00000000
    F44F0000
    0F4F0000
    00FF0000
    000F0000
`# Crop, rotate, then reset` `# Original image will be restored!` `flag.crop((0,4), (4,4)).rotate(90).reset()` `fb.draw(flag)` |
    000FF000
    00F4F000
    0F44F000
    FFFFF000
    0000F000
    0000F000
    0000F000
    0000F000