-
Notifications
You must be signed in to change notification settings - Fork 13
Blitter library
The blitter library allows one to handle a graphical scene made of objects (sprites, tilemaps) on screen and load graphical assets from files instead of coding everything from scratch (which is preferrable for certain kind of games).
The blitter API defines a scene to which you can add and remove objects. It will provide its own callbacks to the kernel.
The base graphical object of the kernel is an object structure.
It contains (See header file for full details over the types) :
| attribute | description |
|---|---|
| x,y | the position of the element on screen. |
| z | the graphical distance from screen. Higher Z objects are rendered further from screen and will thus be overwritten by closer objects. |
| w,h | the visible width/height of the object |
| frame, line | drawing callbacks. frame it called once per frame, and line draws on the buffer. |
| object *next | internal state for handling lists. It will be managed by the library. |
Objects are generally initialized using specific "init" functions, but you will need to insert them into the yourself You can provide / subclass you own types as long as you can cast to this object interface (using OOP in C).
The engine will call the callbacks of the different objects in order when your object need to paint on screen.
void blt_insert(struct object*o, int x, int y, iny z);Adds the object on screen. Setting an object Y after the visible screen will hide it and not consume any CPU rendering it.
void blt_remove(struct object *o);Remove an object from screen.
Important : Many objects don't support changing their y-position while they're blitting. Also, removing objects while they're blitting is not supported. It is safe to do so when vsync is happening, though.
Having a way to render sprites and tilemaps is nice but you often want to load them from graphical assets. Several scripts have been defined to transform graphical assets directly to file formats, loadable from their type-specific functions.
You then have to embedding the objects in flash, or load them from the microSD, or uncompress them from flash to ram ...
Several object types with extra data with specific callbacks can be used directly.
You can by example embed the object struct into your object definition and reference them as is, or just use the macro OBJECT_HEADER first in your own object struct (which just defines the preceding members) which will provide the adequate memebers.
This is the simplest object. It only defines a color, and the blitter will just fill between x,y and x+w, y+h with the full color.
| attribute | description |
|---|---|
| pixel_t color | color with which to blit. |
A Sprite is a compressed bitmap image, generally read-only. It is made of several frames, which are all of the same size. There are several formats for images:
- 16bit non palettized
- 8bit with kernel palette (bitbox micro hardware palette or bitbox user palette), shared with all elements on screen.
- 8bit per couple, with a specific couple palette.
The sprite must have a format which is compatible with your display, i.e. you cannot use a 16-bit sprite on a 8-bit display.
User-accessible attributes :
| attribute | description |
|---|---|
| frame | id of the currently displayed frame. |
| palette | palette of couples for the 256-couples paletted sprites. This format saves place, and allow dynamic setting of a palette to allow fade-outs. |
| zoom_v | vertical scaling factor. Value is the zoom factor *16, i.e. for 1.125 zoom factor, or 18:16, set it to 18. Can be negative, in that case the sprite is mirrored vertically. |
Special methods :
palette_fade_black (int nb, const pixel_t *src, pixel_t *dst, uint8_t ratio);| Method | Description |
|---|---|
| load | parses header of a spr file, and set up the referenced object |
| toggle_2X | Call this to scale the sprite by 2 in X and Y |
| set_solid(pixel_t color) | replace the colors of the sprite with a uniform color. Set to zero to draw normally. |
Sprites can be loaded from sprite files, generated from images (through a specific format), Sprites objects can be saved to disk with header metadata so that the library has a way to load them directly.
The script (in python) is named mk_sprite and the specific file format is documented by calling the script with --format.
The input of this script can be :
- a png file, where the frames size can be given either as an option or in the filename itself.
- a tsx (tiled map editor tilesheet) file. Here one
.sprfile will be exported for each tile with aTypeinformation. Animations defined in the tsx file will be exported.
Tilemaps can represent big objects in few characters by tiling small elements.
A tilemap is typically made of :
- 4 tilesets, which is a collection of 8x8 little squares
- a tilemap, which represents indices of tiles in a tileset. A reference is a u16 : tilset:2<<12 | tile_index.
Tilemaps use tilesets on screen, which are stored uncompressed with a small header in files. To save a tileset, just use
The tilemaps will be saved from a tmx file (tiled map editor format). The complete file format for exporting
(tbc, either a file or a .c file) Objects referenced (using external tilesheets) in the will be exported after the tilemaps. The format used for exporting those is defined in the tilemap.
An X-macro header is generated as part of the export on stdout for each object. The object is a .ref file with the same name as the
The surface type is a 4bpp/16 color, palette-enabled, opaque, (potentially) writeable data. Pixels are not compressed, so a 320x200 buffer will take 32k of memory (but it can be smaller).
It can be displayed with specific zooms / distortions.
Drawing (on R/W surfaces)
- draw_pixel : paint a pixel on screen
- draw_text : draws text with a given font on surface
- draw_bmp () : draws a bmp file to surface /!\ updating the surface palette
- draw_line : draw a line
- draw_rect : draw a rectangle
- draw_poly : draws a polygon
This surface is a btc-compressed surface, mostly used for compressing photos and movies.
scale_2X
Sometimes you will have to specify your own objects.
Here, we will re-implement the Solid color object.