# Bitmap manipulation tools

## Contents

- Overview
- Changes to `bmconv` in EPOC Release 5
- Examples

- Constructing and using a file containing two EPOC format bitmaps
- Viewing the contents of a multi-bitmap file
- Creating Windows bitmaps from a multi-bitmap file

## Overview

Bitmaps provide the pixel patterns used by pictures, icons and masks, sprites and brush styles for filling areas of the display. To optimise bitmap handling performance, EPOC uses files containing multiple bitmaps in its own EPOC bitmap format. These files are of two types:

- ROM image bitmap files
- file store bitmap files

The `bmconv` tool is used to convert bitmaps designed on a PC to EPOC bitmap format. The tool is also used to perform the reverse conversion process, so bitmaps can be created on either platform.

Note that the tools are used for converting bitmaps files prior to bundling in EPOC installation files — see Preparing applications for installation. Microsoft Windows bitmap files are automatically converted to EPOC Sketch files, and visa versa, when files are moved between EPOC and a PC using EPOC Connect.

## Changes to `bmconv` in EPOC Release 5

The `bmconv` bitmap conversion tool has increased functionality, primarily to support enhancements, such as colour, to EPOC.

The new arguments available to `bmconv` in this release are: `/n`, `/q`, `/`bpp, and `/v`. Pre EPOC release 5, `bmconv` was limited to creating 1, 2 or 4 bits per pixel bitmaps. It can now create bitmaps for all the new display EPOC modes.

## Examples

Section Contents

- Constructing and using a file containing two EPOC format bitmaps

- Designing the original Windows bitmaps
- Combining the bitmaps into a multi-bitmap file

- Viewing the contents of a multi-bitmap file
- Creating Windows bitmaps from a multi-bitmap file

### Constructing and using a file containing two EPOC format bitmaps

Making a file of bitmaps for use by EPOC consists of two stages:

- designing the original Windows bitmaps, in `.bmp` format.
- converting the Windows bitmaps to EPOC bitmap format and combining the EPOC format bitmaps into a multi-bitmap file

The following example shows the creation of an EPOC multi-bitmap file from three Windows bitmaps, created using Microsoft Paintbrush. They can be found in `\epoc32ex\adk\`.

#### Designing the original Windows bitmaps

The most important feature to consider when designing a bitmap is the capacity of the target system. While `bmconv` can convert 24-bit colour bitmaps to `.mbm` format, there is little point in doing so if the EPOC platform can only display 4-bit images. In addition, increased colour depth comes at the cost of increased file size, and should be used sparingly.

The smallest memory/least colour diagrams are those produced in monochrome, e.g. black and white. The diagram `\epoc32ex\adk\hangman.bmp` was produced in Microsoft Paintbrush, and then saved as monochrome bitmap using:

`File|Save As...|Monochrome bitmap (*.BMP)`

The second examples are the 16 colour bitmaps `smiley.bmp` and `abstract.bmp`. These were drawn in various colours and shades of grey, and then saved using:

`File|Save As...|16 Color bitmap (*.BMP)`

#### Combining the bitmaps into a multi-bitmap file

The `.bmp` files must be converted into EPOC format bitmaps and combined into a multi-bitmap file. A possible command line to use is:

        bmconv /hbmexmpl.h bmexmpl.mbm /4smiley.bmp /1hangman.bmp /c16abstract.bmp

The screen output should be:

        BMCONV version 48.
        Compiling...
        Multiple bitmap store type: File store
        Epoc file: bmexmpl.mbm

        Bitmap file 1   : Smiley.bmp
        Bitmap file 2   : Hangman.bmp
        Bitmap file 3   : Abstract.bmp
        Success.

The header file generated is as follows:

        // bmexmpl.h
        // Generated by BitmapCompiler
        // Copyright (c) 1998 Symbian Ltd
        //

        enum TMbmBmexmpl
              {
              EMbmBmexmplSmiley,
              EMbmBmexmplHangman,
              EMbmBmexmplAbstract
              };

### Viewing the contents of a multi-bitmap file

The contents of a file can be viewed using the summary switch `/v` , as shown below:

        bmconv /v bmexmpl.mbm

This results in a screen output:

        BMCONV version 48.

        Bitmap 1 information:
        Pixel size 48 x 48
        Twips size 0 x 0
        4 Bpp Monochrome
        Bytewise RLE compression 45%

        Bitmap 2 information:
        Pixel size 33 x 33
        Twips size 49 x 49
        1 Bpp Monochrome
        Bytewise RLE compression 59%

        Bitmap 3 information:
        Pixel size 216 x 158
        Twips size 323 x 236
        16 Bpp Colour
        16 bit RLE compression 5%

        bmexmpl.mbm contains 3 bitmaps

##### Note

- Files resolution is defined by the `/`bpp switch used during the conversion from Windows `.bmp` format. This is independent of the resolution of the original bitmap.

### Creating Windows bitmaps from a multi-bitmap file

Windows bitmap files can be extracted from a multi-bitmap file using the `/u` switch, as shown below:

        bmconv /u bmexmpl.mbm smiley-out.bmp hangman-out.bmp abstract-out.bmp

This results in a screen output:

        BMCONV version 48.
        Decompiling...
        Epoc file: bmexmpl.mbm

        Bitmap file 1   : smiley-out.bmp
        Bitmap file 2   : hangman-out.bmp
        Bitmap file 3   : abstract-out.bmp
        Success.

##### Note

- A name must be defined for each bitmap in the `.mbm`. Any name can be used, however a `.bmp` extension should be declared so that Windows will associate the bitmap with a viewer.
- The output file resolution is 24 bits per pixel (colour).
- The output file may not be a precise duplicate of the original bitmap, due to loss of information during bitmap resolution changes.