"Sacred temple gone foul. Dark whispering in the night. She comes to save us."
- 17th century Haiku, Soul Edge

Color Images The Waba Beta 7 release had support for drawing lines, rectangles, text, etc. in full color on devices that support drawing in color. However, even on color/greyscale devices, the Beta 7 release only supported loading monochrome (black and white) BMP images. The Beta 8 release of Waba contains more support for color images. Specifically, the Virtual Machine has built-in support for loading 2, 16 and 256 color BMP images. In addition, we have developed a 4 color greyscale VM for PalmOS for developers who are looking for more than just black and white on a Palm device. This page provides an overview of color image support and also explains how to create color/greyscale images that look good on various small devices. Loading Images In the next release, if you want to display a 256 color image on a Windows CE device that supports 256 colors, you can simply load the color image as you normally would:
    Image image = new Image("pinball.bmp");
and draw it using a Graphic object's drawImage() method:
    g.drawImage(image, 10, 10);
This is the same way things work in the Beta 7 for drawing monochrome images. The API has not changed but the loadImage() call supports loading 2, 16 and 256 color uncompressed BMP format images from a warp file. The BMP image format is fairly standard and is supported by almost all paint programs, including the "Paint" program that comes with Windows 98 and NT. Color Mapping One downside of using color images is that they take up more storage memory on small devices. A second downside is that most small devices still only have a black and white or greyscale display and if you want to create images that look good on all the various devices or target a specific device, you're going to have to do a bit of work playing with the colors. For example, although a 16 or 256 color image can be loaded by any Waba Virtual Machine, it probably won't look great on a black and white display. By knowing how color mapping works, however, you can work to get more visually pleasing results. Color Mapping under Windows CE Most Windows CE devices support either 4 shades of grey or 256 colors. Under a 256 color display, images of any supported depth should pretty much look the same as they do on a desktop machine that supports full color. This of course depends on what else is running on the device and using the colormap but if other applications aren't using many colors, you should get pretty much the same you do on the desktop. However, if you create a 16 or 256 color image and display it on a 4 greyscale device (like a Cassiopeia E-10), the way colors get mapped will have a dramatic effect on the results you get. The color mapping Waba uses under Windows CE devices is the default that comes with Windows. That is, Waba lets Windows CE map colors from 16 or 256 colors to the 4 shades of grey. Waba doesn't do the color mapping itself. So, what does Windows do to map colors? The image below gives a glimpse of how Windows CE does it color mapping. Below we show a 256 color image and how it looks on a 4 greyscale Cassiopeia E-10 Windows CE device:
256 color | 4 greyshades
Notice that Windows CE isn't dithering the image and that the image is really too dark to make out. The 4 greyscale Windows CE for the E-10 performs "closest-color" mapping. That is, a really dark color will get mapped to black. A really bright color will get mapped to white. Intermediate colors will get mapped to grey. To make the image appear better, we can simply lighten it up. Most image processing programs support brightening an image. In PaintShop Pro, for example, you can increase the gamma correction of the image to make it brighter. Below is the same 256 color image as before but brightened up a bit and then displayed on a 4 color device.
256 color | 4 greyshades
Notice that this one looks quite a bit better when converted to greyscale than the previous example. Remember that 256 color images use quite a bit more storage space than 16 color images (more than twice as much). If you are going to be using color images, it may be best to stick with 16 color images to save space on the device, especially since most users can't realize the benefit of a 256 color image on a small device. Color Mapping Under Monochrome PalmOS By default, most PalmOS devices are still black and white (monochrome) devices. With some tweaking, the devices can display in 4 shades of grey but PalmOS itself doesn't have any support on most Palm devices for more than black and white. So, if you are developing a program for Palm devices, it should probably be designed to run under plain old black and white. When using Waba under PalmOS, color images are converted to black and white by the Waba Virtual Machine itself. The most important thing to know about how the conversion occurs is that the WabaVM does not use the colormap of the image when converting it to black and white. The VM assumes that the colormap ranges from darkest color first to brightest color last. So, if you have a 2 color image, its colormap entries should be black and then white in that order. For a 4 color image, it should range from dark colors to light colors. When the WabaVM converts an image from color to black and white, it looks at each pixel and determines if its value (its index into the colormap) is more than half the number of entries in the colormap. If the image is 16 color and a pixel has a value 15, then it will appear in white. If the pixel has a value 1, it will be mapped to the color black. Here are the results of this process when displaying a 256 color image on a black and white PalmOS display.
256 color | black and white
Notice that the image didn't turn out great. There are a few things we could do to make the image appear better in black and white. One is lighten up the image, as we did for Windows CE images. Another is to convert it to greyscale using something like PaintShop Pro, which gives it a nice colormap that goes from black to white. Below is the image converted to a 16 greyscale image using PaintShop Pro and then displayed on a monochrome Palm device:
16 greyshades | black and white
But the best way to make a nice looking black and white image is to convert it to black and white using a paint program that dithers the image and converts it to monochrome. The image below was converted to black and white with dithering using PaintShop Pro. black and white Color Mapping Under Greyscale PalmOS Although PalmOS itself doesn't normally support more than black and white (2 colors), the processor that Palm devices use supports processing 4 shades of grey with a bitmap display. Wabasoft has a greyscale WabaVM for PalmOS in development that subverts PalmOS and allocates a screen buffer itself and performs all drawing in that screen buffer. The VM doesn't use any PalmOS routines to draw lines, characters, etc. it does all the drawing itself. The VM also supports loading 2, 16 and 256 color BMP images. The important thing to know about how the VM deals with BMP images is that, like the monochrome WabaVM, it expects the colormap to range from black to white. Darkest colors should come first in the colormap and brightest colors last. If you have a color image, you can get very nice results by converting the image to 16 color greyscale using something like PaintShop Pro that, by default, converts color images into a greyscale image with a colormap that ranges from darkest color first to brightest color last. The image on the left below is a 256 color image converted to greyscale in PaintShop Pro and then converted to 16 colors. The image on the right is the image displayed on the greyscale WabaVM for PalmOS.
16 greyshades | 4 greyshades
If you want a perfect mapping, that is if you want to see the exact same image in a paint program as you do on a greyscale WabaVM, you can create a 16 color image and use the following colormap: 16 color palette for 4 greyshades This is the colormap the WabaVM uses internally for 16 color images for the 4 greyscale WabaVM. There are 4 colors in this colormap: black, dark grey, light grey and white, in that order. The WabaVM does not support 4 color BMP images since 4 color BMP images can't be loaded or saved by most paint programs. Microsoft added support for 4 color BMP images to Visual C++ specifically for Windows CE, however, a 4 color image isn't really part of the BMP "standard". So, to create a 4 color image, you need to create a 16 color BMP with a colormap as above. Final Thoughts Since you're normally using Waba to develop programs for small devices, its probably best to stick with 2 or 16 color BMP images to save storage space. If you're just targeting monochrome PalmOS devices, its best to stick with 2 color BMP images with a colormap of black and white (in that order). If you're targeting WinCE and/or greyscale PalmOS devices, you probably want to use 16 color BMP images with colormaps that are arranged with darkest colors first and brightest colors last.