Bitmaps which can be used with emWin are normally defined as GUI_BITMAP structures in C. The structures -- or rather the picture data which is referenced by these structures -- can be quite large. It is time-consuming and inefficient to generate these bitmaps manually, especially if you are dealing with images of considerable size and with multiple shades of gray or colors. We therefore recommend using the bitmap converter, which automatically generates C files from bitmaps.
The bitmap converter is a Windows program which is easy to use. Simply load a bitmap (in the form of a .bmp file) into the application. Convert the color format if you want or have to, and convert it into a C file by saving it in the appropriate format. The C file may then be compiled, allowing the image to be shown on your display with emWin.

What it does

The bitmap converter is intended as a tool to convert bitmaps from a PC format to a C file. It also features color conversion, so that the resulting C code is not unnecessarily large. You would typically reduce the number of bits per pixel in order to reduce memory consumption. The bitmap converter displays the converted image.
A number of simple functions can be performed with the bitmap converter, including flipping the bitmap horizontally or vertically, rotating it, and inverting the bitmap indices or colors (these features can be found under the Image menu). Any further modifications to an image must be made in a bitmap manipulation program such as Adobe Photoshop or Corel Photopaint. It usually makes the most sense to perform any image modifications in such a program, using the bitmap converter for converting purposes only.

Loading a bitmap

Loading from a file

A bitmap image in .bmp format may be opened directly in the bitmap converter by selecting File/Open . The following .bmp files may be loaded:

• 1,4,8,16 or 32 bits per pixel (bpp) with palette;
• 24 bpp without palette (RGB/full-color mode);
• RLE4 and RLE8.

Using the clipboard

Any other type of bitmap (i.e. .gif , .jpg , .jpeg , .png , .tif ) may be opened with another program, copied to the clipboard, and pasted into the bitmap converter. This process will achieve the same effect as loading directly from a file.

Generating C files from bitmaps

The main function of the bitmap converter is to convert PC-formatted bitmaps into C files which can be used by emWin. Before doing so, however, it is often desirable to modify the color palette of an image so that the generated C file is not excessively large. When using full-color bitmaps, it will be necessary to convert the image into a palette format, as the bitmap converter cannot generate C files from bitmaps in full-color mode.
The bitmap may be saved as a .bmp file (which can be reloaded and used or loaded into other bitmap manipulation programs) or as a C file. A C file will serve as an input file for your C compiler. It may contain a palette (device-independent bitmap, or DIB) or be saved without (device-dependent bitmap, or DDB). DIBs are recommended, as they will display correctly on any LCD; a DDB will only display correctly on an LCD which uses the same palette as the bitmap.
"C"-files may be generated as "emWin C with palette", "emWin C without palette", "emWin C with palette, compressed" or "emWin C without palette, compressed".
The basic procedure for using the bitmap converter is illustrated below:

The basic procedure for using the bitmap converter is illustrated step by step in the table below:

Step 1: Start the application. The bitmap converter is opened as an empty window
Step 2: Load a bitmap into the bitmap converter. Choose File/Open . Locate the document you want to open and click Open (must be a .bmp file). In this example, the file SeggerLogo200.bmp is chosen. The bitmap converter displays the loaded bitmap.	In this example, the loaded bitmap is in full-color mode. It must be converted to a palette format before a C file can be generated.
Step 3: Convert the image if necessary. Choose Image/Convert Into . Select the desired palette. In this example, the option Best palette is chosen. The bitmap converter displays the converted bitmap.	The image is unchanged in terms of appearance, but uses less memory since a palette of only 15 colors is used instead of the full-color mode. These 15 colors are the only ones actually required to display this particular image.
Step 4: Save the bitmap as a C file. Choose File/Save. Select a destination and a name for the C file. Select the file type. In this example, the file is saved as "emWin C with palette." Click Save. The bitmap converter will create a separate file in the specified destination, containing the C source code for the bitmap.

Color conversion

The primary reason for converting the color format of a bitmap is to reduce memory consumption. The most common way of doing this is by using the option Best palette as in the above example, which customizes the palette of a particular bitmap to include only the colors which are used in the image. It is especially useful with full-color bitmaps in order to make the palette as small as possible while still fully supporting the image. Once a bitmap file has been opened in the bitmap converter, simply select Image/Convert Into/Best palette from the menu.
For certain applications, it may be more efficient to use a fixed color palette, chosen from the menu under Image/Convert Into . For example, suppose a bitmap in full-color mode is to be shown on a display which supports only four gray scales. It would be a waste of memory to keep the image in the original format, since it would only appear as four gray scales on the display. The full-color bitmap can be converted into a four-grayscale, 2bpp bitmap for maximum efficiency.
The procedure for conversion would be as follows:

The bitmap converter is opened and the same file is loaded as in steps 1 and 2 of the previous example. The bitmap converter displays the loaded bitmap.
Choose Image/Convert Into/Gray4.
The bitmap converter displays the converted bitmap. In this example, the image uses less memory since a palette of only 4 gray scales is used instead of the full-color mode. If the target display supports only 4 gray scales, there is no use in having a higher pixel depth as it would only waste memory.

Compressed bitmaps

The bitmap converter and emWin support run-length encoding (RLE) compression of bitmaps in the resulting source code files. The RLE compression method works most efficiently if your bitmap contains many horizontal sequences of equal-colored pixels. An efficiently compressed bitmap will save a significant amount of space. However, compression is not recommended for photographic images since they do not normally have sequences of identical pixels. It should also be noted that a compressed image may take slightly longer to display.
If you want to save a bitmap using RLE compression, you can do so by selecting one of the compressed output formats when saving as a C file: "emWin C with palette, compressed" or "emWin C without palette, compressed". There are no special functions needed for displaying compressed bitmaps; it works in the same way as displaying uncompressed bitmaps.

Compression ratios

The ratio of compression achieved will vary depending on the bitmap used. The more horizontal uniformity in the image, the better the ratio will be. A higher number of bits per pixel will also result in a higher degree of compression.
In the bitmap used in the previous examples, the total number of pixels in the image is (200*94) = 18,800.
Since 2 pixels are stored in 1 byte, the total uncompressed size of the image is 18,800/2 = 9,400 bytes.
The total compressed size for this particular bitmap is 3,803 bytes for 18,800 pixels (see the example at the end of the chapter).
The ratio of compression can therefore be calculated as 9,400/3,803 = 2.47.

Using a custom palette

Under certain circumstances it may be desirable to use a custom palette for conversions. In these cases (usually only if you have a color display using a special custom palette and you would like to use the same palette for bitmaps) a custom palette may be used. In the menu, you would select Image/Convert Into/Custom palette.

File format for custom palette

Custom palette files are simple files defining the available colors for conversion. They contain the following:

• Header (8 bytes).
• NumColors (U32, 4 bytes).
• 0 (4 bytes).
• U32 Colors[NumColors] (NumColors*4 bytes, type GUI_COLOR).

Total file size is therefore: 16+(NumColors*4) bytes. A custom palette file with 8 colors would be 16+(8*4) = 48 bytes. At this point, a binary editor must be used in order to create such a file.
The maximum number of colors supported is 256; the minimum is 2.

Custom palette sample file

This sample file would define a palette containing 2 colors -- red and white:
0000: 65 6d 57 69 6e 50 61 6c 02 00 00 00 00 00 00 00
0010: ff 00 00 00 ff ff ff 00
The 8 headers make up the first eight bytes of the first line. The U32 is stored lsb first (big endian) and represents the next four bytes, followed by the four 0 bytes. Colors are stored 1 byte per color, where the 4th byte is 0 as follows: RRGGBB00. The second line of code therefore defines the two colors used in this sample.

BmpCvt.exe: Command line usage

It is also possible to work with the bitmap converter using the command prompt . All conversion functions available in the bitmap converter menu are available as commands, and any number of functions may be performed on a bitmap in one command line. Commands are entered using the following format:

BmpCvt .bmp <-command>
(If more than one command is used, one space is typed between each.)
For example, a bitmap with the name logo.bmp is converted into Best palette format and saved as a C file named logo.bmp all at once by entering the following at the command prompt:
BmpCvt logo.bmp -convertintobestpalette -saveaslogo,1 -exit

Note that while the file to be loaded into the bitmap converter always includes its .bmp extension, no file extension is written in the -saveas command. An integer is used instead to specify the desired file type. The number 1 in the -saveas command above designates "emWin C with palette". The -exit command automatically closes the program upon completion. See the table below for more information.

Valid command line options

The following table lists all permitted bitmap converter commands. It can also be viewed at any time by entering BmpCvt /? at the command prompt.

Example of a converted bitmap

A typical example for the use of the bitmap converter would be the conversion of your company logo into a C bitmap. Take a look at the sample bitmap pictured:

The bitmap is loaded into the bitmap converter, converted to Best palette , and saved as "emWin C with palette". The resulting C source code is displayed below (some data is not shown to conserve space).

/*
C-file generated by Bitmap converter for emWin V2.20a, compiled Apr 15 2002, 15:28:45

Copyright (C) 1998-2002

SEGGER Microcontroller GmbH & Co.KG

www.segger.com


Solutions for real time microcontroller applications

Source file: Logo

Dimensions: 200 * 94

NumColors: 15
*/


#include "stdlib.h"
#include "GUI.H"

/* Palette
The following are the entries of the palette table.
Every entry is a 32-bit value (of which 24 bits are actually used)
the lower 8 bits represent the Red component,
the middle 8 bits represent the Green component,
the highest 8 bits (of the 24 bits used) represent the Blue component
as follows: 0xBBGGRR
*/


const GUI_COLOR ColorsLogo[] = {
  0xFFFFFF,0xFF0000,0x000000,0x0F0F0F,
  0x1C1F23,0xC3C3C3,0x020202,0xFBEFEF,
  0xFF3B3B,0x5A5B5E,0x909294,0xFFC1C1,
  0xD0D1D1,0xFF6868,0xFF9393
};

const GUI_LOGPALETTE PalLogo = {
  15, /* number of entries */
   0, /* No transparency */
  &ColorsLogo[0]
};

const unsigned char acLogo[] = {
  0x00, 0x00, 0xC9, 0x43, ... , 0x00, /* Not all data is shown */
  0x00, 0x0A, 0x32, 0x22, ... , 0x00,/* in this example */
  0x00, 0x92, 0x22, 0x22, ... , 0x00,
  0x0A, 0x22, 0x22, 0x22, ... , 0xA0,
  0xC6, 0x22, 0x23, 0x95, ... , 0x6C,
  .
  .
  .
  0xC6, 0x22, 0x23, 0xA5, ... , 0x6C,
  0x0A, 0x22, 0x22, 0x22, ... , 0x90,
  0x07, 0x92, 0x22, 0x22, ... , 0x70,
  0x00, 0x7A, 0x32, 0x22, ... , 0x00,
  0x00, 0x00, 0xCA, 0x44, ... , 0x00
};

const GUI_BITMAP bmLogo = {
  200, /* XSize */
  94, /* YSize */
  100, /* BytesPerLine */
  4, /* BitsPerPixel */
  acLogo, /* Pointer to picture data (indices) */
  &PalLogo /* Pointer to palette */
};

/* *** End of file *** */

Compressing the file

We can use the same bitmap image to create a compressed C file, which is done simply by loading and converting the bitmap as before, and saving it as "emWin C with palette, compressed". The source code is displayed below (some data is not shown to conserve space).
The compressed image size can be seen towards the end of the file as 3,803 bytes for 18,800 pixels.

/*
C-file generated by Bitmap converter for emWin V2.20a, compiled Apr 15 2002, 15:28:45
 

Copyright (C) 1998-2002

SEGGER Microcontroller GmbH & Co.KG

www.segger.com


Solutions for real time microcontroller applications

 
Source file: LogoCompressed

Dimensions: 200 * 94

NumColors: 15
*/

#include "stdlib.h"
#include "GUI.H"

/* Palette
The following are the entries of the palette table.
Every entry is a 32-bit value (of which 24 bits are actually used)
the lower 8 bits represent the Red component,
the middle 8 bits represent the Green component,
the highest 8 bits (of the 24 bits used) represent the Blue component
as follows: 0xBBGGRR
*/

const GUI_COLOR ColorsLogoCompressed[] = {
  0xFFFFFF,0xFF0000,0x000000,0x0F0F0F,
  0x1C1F23,0xC3C3C3,0x020202,0xFBEFEF,
  0xFF3B3B,0x5A5B5E,0x909294,0xFFC1C1,
  0xD0D1D1,0xFF6868,0xFF9393
};

 
const GUI_LOGPALETTE PalLogoCompressed = {
  15, /* number of entries */
  0, /* No transparency */
  &ColorsLogoCompressed[0]
};

 
const unsigned char acLogoCompressed[] = {
  /* RLE: 004 Pixels @ 000,000*/ 4, 0x00, 
  /* ABS: 003 Pixels @ 004,000*/ 0, 3, 0xC9, 0x40, 
  /* RLE: 186 Pixels @ 007,000*/ 186, 0x03, 
  /* ABS: 003 Pixels @ 193,000*/ 0, 3, 0x49, 0xC0, 
  /* RLE: 007 Pixels @ 196,000*/ 7, 0x00, 
  .
  .
  .
  /* RLE: 006 Pixels @ 198,092*/ 6, 0x00, 
  /* ABS: 004 Pixels @ 004,093*/ 0, 4, 0xCA, 0x44, 
  /* RLE: 184 Pixels @ 008,093*/ 184, 0x03, 
  /* ABS: 004 Pixels @ 192,093*/ 0, 4, 0x44, 0xA5, 
  /* RLE: 004 Pixels @ 196,093*/ 4, 0x00, 
  0}; /* 3803 for 18800 pixels */
 
const GUI_BITMAP bmLogoCompressed = {
  200, /* XSize */
  94, /* YSize */
  100, /* BytesPerLine */
  GUI_COMPRESS_RLE4, /* BitsPerPixel */
  acLogoCompressed, /* Pointer to picture data (indices) */
  &PalLogoCompressed /* Pointer to palette */
  ,GUI_DRAW_RLE4
};
 
/* *** End of file *** */