This tutorial will attempt to explain how Images are working for the Gamebuino META.

General Idea

The general Idea of images is to have one standard way of drawing graphics onto the screen, on the lights, or on other images.

In Image can have multiple different resources (such as, SD card BMP file, flash array, or ram array). An Image can also have either the color mode RGB565 or be indexed.

On an Image itself you can draw lines, shape, text, and more importantly: other images! The gb.display itself is an image, meaning you can do all those actions with gb.display

Now, let's just pretend we'd already have an image...

#include <Gamebuino-Meta.h>

Image myImg; // let's just pretend this was a correctly initialized image (which it is not)

void setup() {
  gb.begin();
}

void loop() {
  while(!gb.update());
  gb.display.clear();
  // now we can draw the image to the display, at x=10 and y=0
  gb.display.drawImage(10, 0, myImg);
}

As you can see, drawing an image is pretty straight-forward.

Image Sources

As already mentioned, there are different kind of image sources, which result in different constructors for the Image object.

RAM Image

Image( uint16_t width , uint16_t height [, ColorMode col = (RGB565|Index) ] , [ uint16_t frames = 1 [, uint8_t fl = 1 ]])

A RAM image is simply an image with a blank buffer in RAM. They are only two parameters needed to initialize it: the width and the height. Both are of type uint16_t.

The optional other parameters are explained below.

For example, gb.display is such a RAM image, and is, by default, initialized with

Image(80, 64)

Flash Image

Now, if you want to save some assets, like sprites, in your game, you typically don't want to have them in RAM, so, you can save Images in Flash, too!

You don't have to code the images yourself, use the Image to code converter !

They are either a uint8_t array, or a uint16_t array. The first one is recommended to use for an indexed image, the second one for an rgb565 image. In the indexed case there is two pixels per byte. In the rgb565 case one pixel per two bytes, so one pixel per array entry.

Both have a header, which are slightly different:

For uint8_t data

<width>, <height>,
<frames-lower-8-bit>, <frames-upper-8-bit>,
<frame_loop>,
<transparent_color>,
<color_mode>,

For uint16_t data:

<width>, <height>,
<frames>,
<frame_loop>,
<transparent_color>,
<color_mode>,

For an rgb565 image the color mode is 0, for an indexed image it is 1.

The transparent color is which color should be interpreted as transparent. In rgb565 mode 0 is interpreted as no transparency, in indexed mode anything greater than 0x0F is interpreted as no transparency.

Frames and Frame Loop are explained below.

So, for an indexed checkered-board you'd do

const uint8_t myImgBuf[] = {
  8, 8, // width, heigth
  1, 0, // frames
  0, // frame loop
  0xFF, // transparent color
  1, // color mode

  0x07, 0x07, 0x07, 0x07,
  0x70, 0x70, 0x70, 0x70,
  0x07, 0x07, 0x07, 0x07,
  0x70, 0x70, 0x70, 0x70,
  0x07, 0x07, 0x07, 0x07,
  0x70, 0x70, 0x70, 0x70,
  0x07, 0x07, 0x07, 0x07,
  0x70, 0x70, 0x70, 0x70,
};

Image myImg(myImgBuf);

Or for a small RGB565 image you'd do

const uint16_t myImgBuf[] = {
  2, 2, // width, height
  1, // frames
  0, // frame loop
  0, // transparent color
  0, // color mode

  0x1234, 0x2345,
  0x3456, 0x4567,
};

Image myImg(myImgBuf);

SD Card Image

Lastly, you can also load assets right from the SD card, from BMP files! Please keep in mind that every SD-card image has to keep track of an internal 

Supported are BMP files with 4-bit, 24-bit and 32-bit bitdepth.

4-bit-depth BMPs are converted to indexed images, according how the current palette of the gamebuino meta is. If exact matches aren't present, closest matches are being used.

24-bit-depth BMPs are converted to rgb565 images.

32-bit-depth BMPs are also converted to rgb565 images. The alpha channel is partly ignored: If a pixel is more than 50% transparent it will appear as a transparent pixel in the final image, else as a solid pixel.

You can create a BMP image like this:

Image myImg("PATH/TO/IMAGE.BMP");

It will automatically detect what kind of BMP is present and adapt accordingly

Image Animations

Now that we discussed different image sources, let's talk about some other features these images have: Animations!

The idea is basically that you have, in your flash/RAM buffer, just multiple frames stacked. Or, with BMP image, have frames stacked.

As explained above, you have different ways to specify the number of frames you have.

Frame Loop hereby is the animation speed, we'll just use 1 for now.

#include <Gamebuino-Meta.h>

const uint8_t myAnimBuf[] = {
  8, 8, // width, height
  0x2A, 0x00, // let's just say the animation has 42 frames
  1, // frame loop
  0xFF, // no transparency
  1, // indexed image

  /* all the frames go here */
};

Image myAnim(myAnimBuf);

void setup() {
  gb.begin();
}

void loop() {
  while(!gb.update());
  gb.display.clear();

  // let's just draw the image
  gb.display.drawImage(0, 0, myAnim);
}

Aaaaand, there you go, it automatically progresses to the next frame and loops the animation! As simple as that!

Now, let's say the animation is a tad to fast to you, and you only want to progress one animation frame every two gamebuino frames...that is what the fl (Frame Loop) parameter is there for! In the buffer you just set a different Frame Loop parameter, e.g. a value of 2 would only progress the animation every two frames.

Spritesheet & Tilemapper

Now, we can also use one image as an entire spritesheet, and thus make a tilemapper! The idea exactly the same as with animations: when setting fl (Frame Loop) parameter to zero the animation doesn't automatically progress anymore. So, creating a spritesheet would look like this:

const uint8_t spritesheetBuf[] = {
  8, 8,
  0x2A, 0x00, // if we have 42 sprites
  0, // no frame looping
  0xFF,
  1,
  
  /* all the sprites */
};

Image spritesheet(spritesheetBuf);

And, with setFrame() we can set the current frame, so if we have our tilemap in an array called tilemap we could do something like this to render it all:

for (uint8_t y = 0; y < height; y++) {
  for (uint8_t x = 0; x < width; x++) {
    spritesheet.setFrame(tilemap[y*width + x]);
    gb.display.drawImage(x*8, y*8, spritesheet);
  }
}

Please note, while that does work with BMP spritesheets, that setFrame is slow with BMP images, and thus it is recommended to use a flash array.

Image Cropping

You can also directly crop an image while drawing it, for that you just need to specify the x, y, width and height of the cropped image. Example, assuming that myImage is an image:

gb.display.drawImage(0, 0, myImage, 4, 4, 8, 8);

Questions? Unclarity?

Leave a comment below and help improve this tutorial!

Last comments

JulienGio

NEW 3 days ago

This is super useful :D

DFX2KX

NEW 1 day ago

A bit more complicated then the Classic, but not too bad at all.

Sorunome

1 day ago

Well, if you don't use any of the extra features i'd dare to say it isn't really more complex (except of index vs rgb565, which is a burden of color graphics).

Sorunome

NEW 1 day ago

DFX2KX DFX2KX

Well, if you don't use any of the extra features i'd dare to say it isn't really more complex (except of index vs rgb565, which is a burden of color graphics).

You must be logged in in order to post a message on the forum

Log in