                   V2I - .VBM to .ICO file converter
                   =================================

Warranty
--------
This program is provided on an "as is" basis, without warranty of any
kind. The entire risk as to the quality and performance of the program
is borne by you.

Icon-Resource File Format
-------------------------
An icon-resource file contains image data for icons used by Windows
applications. The file consists of an icon directory identifying the
number and types of icon images in the file, plus one or more icon
images. The default filename extension for an icon-resource file is
.ICO.

Windows Icon Selection
----------------------
Windows detects the resolution of the current display and matches it
against the width and height specified for each version of the icon
image. If Windows determines that there is an exact match between an
icon image and the current device, it uses the matching image.
Otherwise, it selects the closest match and stretches the image to the
proper size.
If an icon-resource file contains more than one image for a particular
resolution, Windows uses the icon image that most closely matches the
color capabilities of the current display. If no image matches the
device capabilities exactly, Windows selects the image that has the
greatest number of colors without exceeding the number of display
colors. If all images exceed the color capabilities of the current
display, Windows uses the icon image with the least number of colors.

Icon Sizes
------------
Acceptable values for icons width and height are 16, 32, and 64 pixels.
Windows uses four icon sizes: system small, system large, shell small,
and shell large.
The system small icon is displayed in the window caption.
The system large icon is mainly used by applications, but it is also
displayed in the Alt+Tab dialog.
The shell small icon is used in the Windows Explorer and the common
dialogs. Currently, this defaults to the system small size.
The shell large icon is used on the desktop.

Icon Colors
-----------
Acceptable values for the icon number of colors are 2, 8, and 16.
Your application should supply icon resources in the following sizes: 

-       48x48, 256 color (*)
-       32x32, 16 color
-       16x16 pixels, 16 color

(*) According to SDK documentation :o(

The Windows Way of Doing Things
-------------------------------
Starting with a MS Plu+s! for Win95, Microsoft were added a support for
a 256 color icons, thus confusing all of the programmer understandings
for the format of the icon-resources. Documentation says that the field
named bColorCount in the ICONDIRENTRY structure is just an eight-bit
wide field (!?). Meanwhile, SDK help files were modified not to contain
information about the format of the resource files. New API functions
were added with ability for automatically replacing specified colors with
a background. Naming of the function parameters also became confusing
(width parameter named `cxDesired' for example) and so on. Most of the
icon editors does not recognize 256 color icons and when you try to open
.ICO file that contains 256-color icon then their behavior becomes
unpredictable.

V2I Approach
------------
Taking in mind that two color icons are anachronism (for Windows) and
256 color icons are still somehow `classified', there is not much
possibilities left for an icon images:

-       64x64, 16 color
-       48x48, 16 color
-       32x32, 16 color
-       16x16 pixels, 16 color

The .VBM files may have three different color depths: 1, 8, and 24 bit.
V2I works only with .VBMs with color depth of 8 bits. All colors from
the .VBM palette are mapped to the commonly used Windows palette for
icon images, specified as follows (along with color names):

rgbquad stdtable[] =
{  /* Blue, Green, Red */
    { 0, 0, 0, 0 },            /*  0: black */
    { 0, 0, 0x80, 0 },         /*  1: maroon */
    { 0, 0x80, 0, 0 },         /*  2: green */
    { 0, 0x80, 0x80, 0 },      /*  3: olive */
    { 0x80, 0, 0, 0 },         /*  4: navy */
    { 0x80, 0, 0x80, 0 },      /*  5: purple */
    { 0x80, 0x80, 0, 0 },      /*  6: teal */
    { 0xc0, 0xc0, 0xc0, 0 },   /*  7: silver */
    { 0x80, 0x80, 0x80, 0 },   /*  8: gray */
    { 0, 0, 0xff, 0 },         /*  9: red */
    { 0, 0xff, 0, 0 },         /* 10: lime */
    { 0, 0xff, 0xff, 0 },      /* 11: yellow */
    { 0xff, 0, 0, 0 },         /* 12: blue */
    { 0xff, 0, 0xff, 0 },      /* 13: fuchsia */
    { 0xff, 0xff, 0, 0 },      /* 14: aqua */
    { 0xff, 0xff, 0xff, 0 }    /* 15: white */
};

V2I accomplishes the mapping with the help of the function `nearest'
which finds the nearest standard color located in the 3D color Cartesian
co-ordinate space. All colors involved in the translation (including
colors given as a command line parameters) stands for this mapping.

Transparent Areas
-----------------
Transparent areas in the icon image may be defined. These areas must be
filled with identical color. There is three ways to define the color for
the transparent areas:

-       Giving the name of the color (cyan, maroon, etc.)
-       Giving the value of the color as RGB value (0xFF00C0)
-       Specifying the location of some pixel used as a color reference

If the first way is used for specifying the transparent color,
acceptable color names are:

        black, maroon, green, olive, navy, purple, teal, silver,
        gray, red, lime, yellow, blue, fuchsia, aqua, white

When the second way is used, take in mind that the color stands for the
standard color mapping.

If the third way is used, acceptable values for the location are:

-       Upper-left hand pixel
-       Upper-right hand pixel
-       Lower-left hand pixel (default)
-       Lower-right hand pixel

Command-Line Options
-------------------
Usage:
        v2i.exe vbmfile [options] vbmfile [options] ...

Options:

-h
--help                  Show this message and exit

-o
--output ICOFILE        Name the icon-resource file output ICOFILE

-c
--color CNAME           Use color CNAME for transparent areas

-r
--rgb VALUE             Use RGB value VALUE for the transparent areas

-ul
--upper-left            Use the color of the upper-left hand pixel for
                        the transparent areas

-ur
--upper-right           Use the color of the upper-right hand pixel for
                        the transparent areas

-ll
--lower-left            Use the color of the lower-left hand pixel for
                        the transparent areas

-lr
--lower-right           Use the color of the lower-right hand pixel for
                        transparent areas (default)

Up to five .VBM files may be placed in single .ICO file. All options,
except the -o option, stands for the next .VBM file. You may use
the same option more than once. For example, if you want to specify the
black areas to be transparent in the file SMALL.VBM and the red areas to be
transparent in the second file, BIG.VBM, use the following statement:

        v2i -c black small.vbm -c red big.vbm -o app.ico

Feedback
--------
Send your feedback to:

Youlian Ivanov
v2i@alpinist.fsn.net    or
july@cblink.net

>>> END-OF-FILE <<<
