Arduboy-homemade-package/board-package-source/libraries/ArdBitmap/README.md

ArdBitmap: Compress and draw bitmaps on the Arduboy

By @igvina

Features:

Bitmap library:

• Works with compressed & uncompressed bitmaps.
• Real-time image resize (downscale).
• Horizontal/Vertical mirroring (fast).
• Bitmap alignment.

Bitmap compressor:

• Compatible with PC/MAC/Linux (made with Java).
• Good compression (better than Cabi).
• Supports PNG, GIF (also animated gifs) & JPG.
• Autogenerate sketches from images or animated gifs (great for no-developers).

Video:

Usage:

Compressor (v2.0):

• Syntax: java -jar compressor2.0.jar image [-options]

  • options:

    • -gs SKETCH_FOLDER Generate sketch code
    • -fr VALUE Change frame rate (only animated gifs)
    • -v View compressed image
    • -anp PREFIX Array name prefix
    • -ver Show encoder version

  • examples:

      "java -jar compressor2.0.jar dog.gif -gs DOG -fr 15"
      "java -jar compressor2.0.jar dance.png -v"
    

  • Notes:

    • Supports PNG, GIF (also animated gifs) & JPG
    • Max image size = 128 x 64 pixels (resized if bigger)
    • Encoding ratio could be bigger than 1 (worse than original image)

Bitmap library (v2.0.x):

• Install the ArdBitmap library in the Arduino IDE. The library can be installed using the Arduino IDE library manager:

  • In the Arduino IDE select from the menus: Sketch > Include Library > Manage Libraries...
  • In the Library Manager Filter your search... field enter ardbitmap
  • Click somewhere within the ArdBitmap entry.
  • Click on the Install button.

  For more library installation information see:

  Installing Additional Arduino Libraries - Using the Library Manager

• In .ino file, add ArdBitmap library instance after main library instance:

// make an instance of the Arduboy2 class used for many functions
Arduboy2 arduboy;

// make an ArdBitmap instance that will use the given the screen buffer and dimensions
#define ARDBITMAP_SBUF arduboy.getBuffer()
#include <ArdBitmap.h>
ArdBitmap<WIDTH, HEIGHT> ardbitmap;

• See the Library instance details section below for more information on creating an ArdBitmap class instance.

• To draw, call function: ardbitmap.drawCompressed(...) , ardbitmap.drawCompressedResized(...) , ardbitmap.drawBitmap(...) , ardbitmap.drawBitmapResized(...)

Methods:

Compressed images:

• void drawCompressed(int16_t sx, int16_t sy, const uint8_t *compBitmap, uint8_t color, uint8_t align, uint8_t mirror);
• void drawCompressedResized(int16_t sx, int16_t sy, const uint8_t *compBitmap, uint8_t color,uint8_t align, uint8_t mirror, float resize);

Uncompressed images:

• void drawBitmap(int16_t sx, int16_t sy, const uint8_t *bitmap,uint8_t w, uint8_t h, uint8_t color, uint8_t align, uint8_t mirror);
• void drawBitmapResized(int16_t sx, int16_t sy, const uint8_t *bitmap, uint8_t w,uint8_t h, uint8_t color,uint8_t align, uint8_t mirror, float resize);

Defines:

• #define ALIGN_H_LEFT
• #define ALIGN_H_RIGHT
• #define ALIGN_H_CENTER
• #define ALIGN_V_TOP
• #define ALIGN_V_BOTTOM
• #define ALIGN_V_CENTER
• #define ALIGN_CENTER
• #define ALIGN_NONE
• #define MIRROR_NONE
• #define MIRROR_HORIZONTAL
• #define MIRROR_VERTICAL
• #define MIRROR_HOR_VER

Library instance details:

• The library is implemented as a class template named ArdBitmap. It requires 3 pieces of information in order to create an instance of the ArdBitmap class:

  • An expression that will evaluate to a pointer to the first location in the screen buffer array, such that it can be used to index a screen buffer location like expression[i] = 5. The expression is provided by defining the macro ARDBITMAP_SBUF. It must be defined before including ArdBitmap.h
  • The width of the screen, in pixels. This is provided as the first of the two template arguments.
  • the height of the screen in pixels. This is provided as the second of the two template arguments.

• It's probably best to group the #define ARDBITMAP_SBUF, the #include ArdBitmap.h and the instantiation of an ArdBitmap class object as one block of code. For an Arduboy sketch this might be:

// make an instance of the Arduboy2 class used for many functions
// (this has to be done before creating an ArdBitmap object so we can define
//  the ARDBITMAP_SBUF macro and use the defined WIDTH and HEIGHT)
Arduboy2 arduboy;
// use the following instead, for the older Arduboy library:
//Arduboy arduboy;

// define the screen buffer pointer expression
#define ARDBITMAP_SBUF arduboy.getBuffer()
// Arduboy2 library verson 3.1.0 and higher exposes the screen buffer as public,
// so the following could be used instead and may reduce code size:
//#define ARDBITMAP_SBUF arduboy.sBuffer

// we can now include the ArdBitmap header file, which will use the
// ARDBITMAP_SBUF macro when creating the template
#include <ArdBitmap.h>

// make an ArdBitmap instance, providing screen width and height arguments that
// were defined by the Arduboy2 (or Arduboy) library
ArdBitmap<WIDTH, HEIGHT> ardbitmap;