Add externs to avoid multiple definitions, and then add missing definitions.

[rrq/maintain_lilo.git] / readme / README.bitmaps

        Notes on the use of Bitmap boot screens
                LILO 22.3 -- 11-Apr-2002


SUMMARY OF CHANGES (LILO 22.3)
==============================

LILO 22.3 no longer requires placement parameters in the configuration
file (/etc/lilo.conf).  Instead, text menu size, placement, and colors
may be edited into the bitmap file header using "lilo -E file.bmp".  The
parameters may also be saved from the bitmap file header to a companion
configuration file, "file.dat", as an option to the edit command. Param-
eters may be transferred from the companion '.dat' file to the bitmap
file header using the command "lilo -E file.dat".  LILO 22.3 still rec-
ognizes bitmap file formating commands in '/etc/lilo.conf'.

This change allows bitmap graphics to be exchanged among users without the
tedious need to exchange the color/positioning information separately.



MOTIVATION
==========

The makers of several Linux distributions which include LILO as the boot
loader have issued patched versions which support graphical screens for
kernel selection.  However, each distribution seems to have chosen a
different screen resolution, and different file-type to implement the
graphical (bitmapped) background.  In order to try to bring some order
to this array of different implementations, and to support common code
across all Linux distributions, I submit the following implementation of
a graphical background and menu driven interface (cursor keys only) for
kernel selection.

The choice then was to have the implementation run on the widest array
of graphics hardware in use today.  VGA is the common standard, and this
dictates a choice of two color modes:  320x200x256 and 640x480x16.  The
VGA/VESA standard extends the modes to add 640x400x256, 640x480x256, and
800x600x256 as possible choices.  However, most high-end graphics cards
provide graphics acceleration through other means than the VESA standard;
and, in actual fact, are moving away from supporting the full spectrum of
VESA modes.  Older VGA systems often do not have VESA extensions in ROM
BIOS, so the choice narrows to the two modes in the original IBM VGA BIOS.

Character generation in the 320x200x256 mode is generally limited to an
8x8 character cell, and is not visually appealing.  The 640x480x16 mode
uses an 8x16 character cell, and is acceptable.  The question was the
limitations to 16 colors.  This is less of a restriction than one might
think it is.  There are the 16 EGA-compatible colors, which are the BIOS
defaults on all systems; but the VGA palette is programmable with 6 bits
alloted to each primary color.  Some experimentation with graphics images
convinced me that very appealing logos could easily be generated, as long
as the graphics editor in use would allow ANY 16 colors to be chosen from
among the 256K available.  Good dithering algorithms exist, and the screens
that I produced with dithered 16-color images, in my opinion, were more
acceptable than 256-color images.  In these latter cases, as a color area
transitions from one shade to another, the stepping effect is more notice-
able, and more objectionable, than a good dither.

With this said, the choice of VGA 640x480x16 (mode 0x12) was settled upon.

Then the choice of a graphics screen file format had to be settled.  It
had to be universally supported, be well documented, allow for image
compression, and allow for easy decompression.  File formats considered
included PCX, GIF, and BMP.  The last was chosen because it is understand-
able, and the run-length compression is very easy to expand.


USAGE
=====

Update (22.3):  The three keywords 'bmp-table', 'bmp-colors', and 'bmp-timer'
are now primarily to be used in the configuration file used as a companion
to a bitmap file.  The bitmap file must have the filename extension ".bmp",
and the companion configuration file must have the filename extension
".dat".

Four keywords are added to 'lilo.conf' to allow the usage of bitmap screens:

        bitmap     =            #specifies the bitmap file to be used as
                                #a background

        bmp-table  =            #specifies the location of the table of
                                #image/other names, and its layout

        bmp-colors =            #specifies the color attributes of the table
                                #entries, normal & highlighted

        bmp-timer  =            #specifies the position and color attributes
                                #of the timeout timer

        install = bmp           #specify the boot loader with bitmap
                                #graphics capability

'bitmap=' specifies the graphic file to be used as a background screen.  It
must be 640 x 480 x 16 colors, and may be saved as an uncompressed bitmap
file (153718 bytes), run-length encoded (compressed) bitmap file, or an OS2
bitmap file (153674 bytes).  It is suggested that you use the smallest,
which will probably be the RLE (compressed) file.  When a 'bitmap=' file is
in use, 'message=' may not be used, and vice versa.

'bmp-table=<list>' specifies the position and table layout of the boot 
selection menu.  The list is a series of up to 5 decimal values, separated
by commas, and containing no spaces.  Values may be omitted in order to use
default values, but the comma separators are required as placeholders.  In
designing the bmp-table layout, consideration must be given to the upper
limit on kernel image/other names.  LILO guarantees that up to 16 may be
specified, and the current implementation allows up to 19.  It is suggested
that the table layout design allow for 18 entries.

  bmp-table = [x],[y],[ncol],[nrow],[xspc],[spill]

        [x]     specifies the column position [1..80] of the first column
                of the table.  Character addressing is assumed, unless the
                coordinate is suffixed with 'p', in which case pixel ad-
                dressing will be used [0p..632p].

        [y]     specifies the row position [1..30] of the top row of the
                table.  All screen text is placed on a 30 row grid.  Pixel
                addressing [0p..464p] is allowed.

        [ncol]  specifies the number of columns used for the display of the
                kernel image/other entries.  The current implementation
                requires the number of columns to be in the range [1..4].

        [nrow]  specifies the number of rows in each column; i.e., the
                height of each column in the table.

        [xspc]  specifies the column spacing from the beginning of one
                column to the beginning of the next column.  Since names in
                the table are up to 15 characters, plus 2 spacers, 17 is an
                absolute minimum for this value.  The column spacing
                increases as this value is increased.  Too large a value may
                spill characters beyond the edge of the screen.  Pixel
                addressing is allowed, if the value is suffixed with a 'p'.

        [spill] specifies the number of entries which may fill a column
                before the column spills to the next column.  The default
                value for this is 4 entries.  (LILO 22.3)


'bmp-colors=<list>' specifies a list of six color numbers, each in the range
[0..15].  The first three specify the color attributes of normal text in the
boot selection table, and the second three specify the color attributes of
the highlighted text in the menu.  The list is comma or semicolon separated,
with no spaces.  However, default values may be indicated by omitting a
numerical value altogether.  Each of the two triples consists of a fore-
ground color, background color, and a shadow color.  The foreground color is
the color used to display the letter or numeral.  The background color is
the fill-color of the 8x16 box which encloses the character.  If the back-
ground color value is omitted from the list, then "transparent" is assumed.
The shadow color is the color used to display a character shadow displaced
one pixel in both X & Y toward the lower right.  If shadows are used, they
generally specify a color of low luminance.

  bmp-colors = [fg],[bg],[sh];[h-fg],[h-bg],[h-sh]

        [fg]    specifies the foreground color for normal text.

        [bg]    specifies the background color for normal text.  If omitted,
                the background is taken to be transparent, and the
                underlying bitmap color shows through.

        [sh]    specifies the shadow color for the character.  If omitted,
                no shadow is displayed.

        [h-fg]  specifies the foreground color for the line of highlighted
                text.

        [h-bg]  specifies the background color for highlighted text.  If
                omitted, the highlighted background is taken to be
                transparent.

        [h-sh]  specifies the shadow color for highlighted text.  If
                omitted, no shadow is displayed.

                Note:  in the list specification above, the semicolon has
                no special significance; it could have been a comma.  Its
                use is suggested merely for distinguishing the two triples,
                as spaces (blanks) are not allowed in the list.


'bmp-timer=<list>' specifies the position at which the 'timeout=' timer will
be displayed, as well as the color attributes of the characters in the
display.  If the line 'bmp-timer=' is not used, then no timer will be
displayed.  If the <list> is specified as "none", then no timer (as speci-
fied in the bitmap file header) will be displayed.

  bmp-timer = [tx],[ty];[t-fg],[t-bg],[t-sh]

        [tx]    specifies the column at which the first of five characters
                in the timer display will be positioned.  It must be in the
                range [1..80], or [0p..632p] if pixel addresses are used.

        [ty]    specifies the character row position of the timer display. 
                It must be in the range [1..30], or [0p..464p] if pixel
                addresses are used.

        [t-fg]  specifies the foreground color of the timer characters.  If
                omitted, the normal foreground text color will be used.

        [t-bg]  specifies the background color of the timer character
                display.  If omitted, color '0' will be used.  It is not
                possible to have a transparent timer background.

        [t-sh]  specifies the shadow color for timer display characters.  If
                omitted, no shadow is displayed.

                Note:  the semicolon in the list specification is for
                readability only; a comma could have been used as well.



EXAMPLE
=======

The following is excerpted from 'bmp.conf', a LILO configuration file which
has been used during the development of the bitmap-capable boot loader.

File:  bmp.conf (substitute for 'lilo.conf'):

        ...
        #
        #  The following parameters select appropriate colors
        #  and proper screen positions for the 'logo64a.bmp' graphic.
        #
        bitmap=logo64a.bmp
        bmp-colors=6,9,0;15,9,0
        bmp-table=59,5,1,19,
        bmp-timer=66,28,6,8,0
        ...

Update (22.3):  If the color information and screen positions specified on
the last three lines above have been transferred to the LILO sub-header in
the bitmap file "logo64a.bmp", then the entry in 'lilo.conf' can be
shortened to:

        ...
        #
        #  Select the bitmap file to display.  Text positioning information
        #  is in the LILO subheader in the bitmap file.
        #
        bitmap=logo64a.bmp
        ...


        ...
        #
        #  The following parameters select appropriate colors
        #  and proper screen positions for the 'ins64a.bmp' graphic.
        #
        bitmap=ins64a.bmp
        bmp-colors=14,11,;15,9,0        # omit this line for lilo 22.3
        bmp-table=21,287p,2,4,175p      #  ditto
        bmp-timer=73,29,12,8,0          #  ditto
        ...

Both bitmap files are available in the source code tarball at:

        http://lilo.go.dyndns.org/pub/linux/lilo

They are located in the 'sample' subdirectory, along with companion
'.dat' configuration files.


USAGE COMMAND
=============

With version 22.3, '/sbin/lilo' becomes, in addition to the boot installer,
the bitmap file header editor.  A single switch, '-E' is added to accomplish
this new task.  It has two uses:

        lilo -E filename.bmp
                or
        lilo -E filename.dat

In the first case, if the bitmap file is fresh out of a graphics editor, it
will have no LILO sub-header.  The first edit command is used to alter the
default values for color and positioning information, and to save the new
values to the LILO sub-header in the bitmap file.  The editor is
interactive, and allows you to change one parameter at a time.  When you
write out the updated bitmap file, you are given the chance to create a
companion text configuration file, 'filename.dat', which contains a readable
copy of all of the text color and positioning information in the header.

In the second case, the abbreviated configuration file, 'filename.dat',
contains only the commands:  "bitmap=", "bmp-table=", "bmp-colors=", or
"bmp-timer="; all are optional.  If "bitmap=" is omitted, then
'filename.dat' is taken to correspond to the bitmap file 'filename.bmp';
i.e., same name, diffenent file extension.  Otherwise, the configuartion
file corresponds to the bitmap file specified by the "bitmap=" option.  The
color, positioning, and timer information in the configuration file is
transferred to the LILO header in the bitmap file.  If no such header
exists, one is created.

The primary use for the '.dat' file is to save the LILO header information,
so that the bitmap graphic may be edited with a graphics editor.  No
graphichs editor recognizes the LILO header, so an updated bitmap graphic
file will be without the LILO header.  The second form of the edit command
allows the header to be recreated very quickly, exacltly as it was before.


TRADEMARKS
==========

Windows is a trademark of Microsoft Corporation.
OS/2 and OS2 are trademarks of IBM Corporation.

(end)
written 05/07/2001 -- John Coffman <johninsd@san.rr.com>
updated 05/10/2001 -- John Coffman
updated 11/25/2001 -- John Coffman (typos corrected)
updated 04/11/2002 -- John Coffman (update to LILO 22.3)