# gfxboot reference

## Overview

To make a graphical boot screen you'll have to write a small script. Optionally you might want font files, graphics files and sound files.

The script is written in a Postscript-like language. You must program everything related to graphics output in it. That does include e.g. drawing the background picture and in particular handling all kind of user input.

Font files have a special format. Create them using `gfxboot-font`. Maximum font file size is 512kB.

If you have written a script, convert it into byte code using `gfxboot-compile`.

Debugging this script is rather tedious. For this, `gfxboot-compile -l` will give you debug information that is useful together with the `dtrace` command.

## Utilities

Tools needed to build a boot graphics file.

- gfxboot-compile

  Compile source into byte code. The result (together with any other files you might need) has to be put into a cpio archive. If you are using `isolinux` or `syslinux`, this is not required, as you can read files directly from the filesystem. The compiled byte code, however, always has to be put into the cpio archive.

        # compile 'foo.ps' to 'foo', writing log to foo.log
        # Note: '-O' turns on the optimizer. You'll always want to do this.
        gfxboot-compile -O -v -l foo.log -c foo.ps foo

        # put it into a cpio archive
        # we'll assume you need a picture 'foo.jpg' and are using font 'foo.fnt'
        echo -e "foo\nfoo.jpg\nfoo.fnt" | cpio -o >bootlogo

        # 'bootlogo' is ready to use, e.g.
        # as 'gfxboot bootlogo' in isolinux.cfg

- gfxboot-font

  Build font file using the freetype rendering engine.

- help2txt

  Convert html files into the internal online-help format.

## syslinux Submenus

gfxboot allows you to have submenus with syslinux (without the menu module) by extending the syslinux config file syntax a bit.

Submenu entries have a label stating with `'->FOO '` (note the space) where `FOO` is an arbitrary string identifying the submenu.

Menu (or submenu) entries that have an `append` entry `'->BAR'` link to submenu `BAR`. The maximum submenu nesting depth is 16.

As there are spaces in labels required to make this work, use the `menu label` statement in syslinux.

Note that this way you can still use the `label` statement to reach any menu item (even if it's in a submenu) directly, which keeps the config file also usable in text mode.

      # normal entry
      label linux
        kernel linux
        append initrd=initrd

      # link to submenu
      label submenu
        menu label My Submenu
        append ->1

      # 1st submenu entry
      label item1
        menu label ->1 Submenu Item #1
        kernel linux
        append initrd=initrd sub=1

      # 2nd submenu entry
      label item2
        menu label ->1 Submenu Item #2
        kernel linux
        append initrd=initrd sub=2

## Reference

Comments start with '%' and extend to the end of line.

To include some other source file, do:

    %% include file

Numbers are always 32 bit signed integer. Numerical and string constants are given in a C-like way (not as in Postscript).

        123, -456
        0x4567
        "Hi there\n"
        '\033', '\x1b', '\u20ac'

But: chars have values in the range 0 .. 0x1fffff.

Strings are interpreted as utf8-sequences. Alternatively you can use '\uXXXX' or '\UXXXXXXXX' to include Unicode characters.

         "1 Euro = 1 €\n"
         "1 Euro = 1 \u20ac\n"
         "1 Euro = 1 \xe2\x82\xac\n"

Logical operations return values of type 'bool'. They are not identical with integers. There are no pre-defined constants 'true' and 'false'. But you can define them yourself if you need them, e.g.:

    /true 0 0 eq def

Strings and arrays are effectively pointers. So duplicating them on the stack does duplicate the pointer, not the object.

In addition, there is a unspecific pointer data type. You can use it to construct arbitrary memory references.

Variable/constants/function names can consist of everything except whitespace.

### Initialisation

During initialization the config file in run. It must leave either an empty stack or a boolean 'true' value at the TOS (top of stack) to indicate the boot loader that everything worked fine. Otherwise the boot loader will assume that some error occured and not continue in graphics mode.

If you want to handle input (as you probably do) you must define at least the callback function KeyEvent.

### Callbacks

Communication with the boot loader is done via callback functions. You are responsible to assign useful actions to them. See config file examples for more documentation.

- `KeyEvent`

  Called if a key is pressed.

- `MenuInit`

  Should draw boot menu.

- `InfoBoxInit`

  Show message box (e.g. error messages).

- `InfoBoxDone`

  Hide message box.

- `ProgressInit`

  Initialize kernel load progress bar (syslinux/isolinux only).

- `ProgressDone`

  Hide progress bar.

- `ProgressUpdate`

  Advance progress bar.

- `PasswordInit`

  Show password dialog.

- `PasswordDone`

  Hide password dialog.

- `Timeout`

  Timeout counter; called every 18.3th second until timeout occurs.

- `Timer`

  Called every 18.3th second regardless of timeout.

### Primary words

&reference.xml;