This page does not want to replace img2tile user manual (for that there is the README) but to provide some indications on its operation, as well as to explain some of the algorithms used. It give, also, an example using the midres library primitives.

Images can be prepared with any photo editing program, such as GIMP. The images must be the size of a tile (8×8 pixels) or a multiple of a single tile (i.e. 32×24 pixel, 64×64 pixel, and so on). Although the program can read many graphic formats, the most accurate results are obtained by using two highly contrasted colors (black / white) and saving using the PNG format at RGB (24 bit)

The main function of this program is to convert bitmap images (from various formats) into a “charset file”, suitable for loading into the font memory of the most popular 8-bit computers.

The simplest way to explain this is to give an example. Below you see an 8×8 pixel image of a “bomb” (bomb.png).

Each white pixel drawn on the image is a pixel that must be represented on the character to be drawn on the screen. To convert this image into a character, simply call the program with the following options:

 img2tile -i bomb.png -o tiles.bin 

At the moment this software only handles 8×8 pixel fonts. For this reason, it is unable to work with images that are not multiples of this size. On the other hand, the system is capable of converting images that are multiples of this size. The conversion mechanism is simple: the original image is divided into “tiles”. Each tile is then represented in sequence. So, if you have an image of N x M pixels, img2tile will generate (N/8)x(M/8) tiles.

For example, the image of an airplane (32×16 pixel, airplane.png) occupy a space of 3×2 tiles, so 6 tiles will be generated, in the following order:

The command line follows:

 img2tile -i airplane.png -o tiles.bin 

This program allows you to convert a set of images, one after the other. It is sufficient to give a set of options -i. The generated tiles will then be written to the file indicated by the -o option. For example, if you pass the images of the plane and of the bomb on the same command line, the result is the following:

From release 1.14 of the program it is possible to generate multicolor tiles with the -m option. In this case, what matters is no longer the brightness of each single pixel but the color, intended as RGB. In particular, the option allows you to manage images that have up to 4 colors.

More information are available in this tutorial, in the section on how to generate multicolor tiles.

The program is able to generate an include file for the C language with the symbols necessary to identify the tile within the tileset (as an “offset”). The name of the symbol will have the prefix TILE_ and it derives from the file name, according to a very simple logic:

• if the name contains an underscore character (_), the right part of the underscore (minus the extension) will be used as the symbol name;
• otherwise, the name will coincide with that of the file (always after removing the extension).

For example, in the previous case the following symbols will be created:

  #define TILE_AIRPLANE         0
  #define TILE_BOMB             8

Also, for each tile, two additional symbols will be generated:

1. TILE_xxx_WIDTH, which will contain the width of the image (in terms of tiles);
2. TILE_xxx_HEIGHT, which will contain the height of the image (in terms of tiles).

For example, in the previous case the following symbols will be created:

  #define TILE_AIRPLANE_WIDTH   4
  #define TILE_AIRPLANE_HEIGHT  2
  #define TILE_BOMB_WIDTH       1
  #define TILE_BOMB_HEIGHT      1

Finally, two more symbols will be generates:

1. TILE_START, which will contain the first tale index (0);
2. TILE_COUNT, which will contain the total count of tiles.

The command line follows:

 img2tile -i airplane.png -i bomb.png -g header_tiles.h -o tiles.bin 
 

This simple program loads all tiles prepared with the last img2tile command, and it draws a yellow bomb at the center of the default screen:

 #include "midres.h"
 #include "header_tiles.h"
 
 mr_tileset_load("tiles.bin", MR_TILESET_0, TILE_START, TILE_COUNT);
 mr_tileset_visible(MR_TILESET_0);
 mr_puttile(MR_SCREEN_DEFAULT, MR_SCREEN_WIDTH >> 1, MR_SCREEN_HEIGHT >> 1, TILE_BOMB, MR_COLOR_YELLOW);