Usage instructions:
These are based on research and experimentation, so may not be entirely accurate.
The converters accept PNG, GIF or JPEG images. JPEG images cannot be used to create masks for transparency, for use with the Spritesheet Converter.
The maximum size for a single image, sprite or tile is 128 x 64 pixels. They must be multiples of 8 pixels high. Any width can be used for images and sprites. Tiles must be square, with an equal width and height that is a multiple of 8 pixels.
For best results, images should contain only pixels that are fully black, fully white or fully transparent.
The Image Converter converts a file to a single sprite without a mask. Any filename can be used but anything after an underscore (including the underscore) will be removed from the resulting array name.
The Spritesheet Converter converts a file to arrays containing one or more sprites. A sprite array, mask array and a combined sprite+mask array are produced. The sprite+mask array contains sprite/mask byte pairs suitable for use with the Sprites drawPlusMask() function.
Note: The mask array produced includes width and height bytes at the beginning. If this array is to be used with the drawExternalMask() function, these bytes must be commented out or deleted.
The Tilesheet Converter converts a file to an array of one one or more square tiles. Tiles are assumed to be solid, with no transparency, so no masks are produced.
For the Spritesheet Converter and Tilesheet Converter, the filename can be any name but must have the dimensions of a single sprite or tile, in the form _WIDTHxHEIGHT, appended to it before the extension.
E.g. to create an array named mySprites with each sprite having a width of 8 and a height of 16 pixels, from a PNG image, the file should be named mySprites_8x16.png. The underscore and dimensions will be removed from the resulting array names.
The image file for multiple sprites or tiles must have them arranged vertically in a single column.
Here is an image that will produce arrays for 3 16x16 sprites. The image contains transparent pixels that will be used for the masks. Its original filename was sprites_16x16.png
Here is an image that will produce arrays for 3 16x16 tiles or sprites (or a single 16x48 image array with the Image Converter). There are no transparent pixels. Its original filename was tiles_16x16.png
In addition to using the produced arrays with the Sprites classes, they can also be used (except sprite+mask) with the Arduboy2Base class drawBitmap() function. For this, the length and width bytes at the start of the array need to be commented out or deleted. To draw a given sprite or tile from an array containing more than one, the proper index into the array would have to be calculated (SpriteNumber * SpriteWidth * SpriteHeight / 8) as a pointer and passed as the bitmap parameter. Masking can be done by first drawing the mask using colour BLACK and then the sprite, at the same position, using colour WHITE (or reverse the two colours to draw the sprite inverted).
