Readme
******

Thank you for trying Splashy!

Features
========

What makes Splashy special over other boot-splash systems is:
  * There is NO need to patch the kernel
  * It supports millions of colors as well as alpha channels (transparency)
  * All resolutions are supported
  * It supports all the formats provided by directfb: jpg, png, gif, mpg, swf...
  * It run in user-space as any other application. So, it can be run at any time
    by simply typing "splashy" at the command prompt
  * initramfs support, which allows Splashy to run early at boot [See Initram File System below]
  * XML configuration
  * Multiple and easy to create themes
  * Lots of effects (animations, fade in/out, smooth progress, etc)
  * TrueType2 fonts support
  * And many other features, too numerous to list here...

Requirements
============

In order to start using Splashy you will need to have the following:
  * A video card
  * A kernel that supports framebuffers (default for the mayority of Linux
    distributors)
  * On Linux, a 2.6 kernel or later is requiered (because directfb requires it)
  * Splashy itself

In order to compile Splashy you will also need to have the following:
  * glib2
  * directfb 0.9.22 or later
  * libjpeg and/or libpng (optional)

Installation (Quick)
====================

1. Unpack Splashy's sources and run as super-user in the extracted directory:
  ./configure --prefix=/ && make && make install 

2. Add "vga=791 quiet" to the append= line on your bootloader configuration

  NOTE: For Grub, this is /boot/grub/menu.lst
  For lilo you need "vga=791" in its own line before the kernel stanzas, and add
  only "quiet" to append=
  Other bootloaders will use the same options, but they need to be passed
  differently. Check your bootloader's manual

3. Make sure "splashy-init" is in /etc/init.d/splashy-init and that there is an
  /etc/rcS.d/S02splashy-init symlink that points there (see scripts/README)

4. Reboot and have fun!

Installation (Detailed)
=======================

1. Compile Splashy following the usual "./configure && make && make install"
   procedure (check "./configure --help" to see the available options)

2. Edit your bootloader's configuration file to set up the framebuffer mode:
  * In Grub, edit /boot/grub/menu.lst
    HINT: In Debian, look for "#kopt" and append vga=0x317 to it.  Then run
    update-grub. Other distros edit the kernel root= line appropriately
  * In lilo, edit /etc/lilo.conf
    HINT: Look for the default image= and edit append= by appending vga=0x317
    to it
  * In Quik, edit /etc/quik.conf and append vga=0x317 to the kernel argument
    line

If you use a different framebuffer driver, then you would need to tell the
kernel, through the kernel's parameters, to use that other driver. For example,
to use the radeonfb framebuffer driver:
  * Grub: #kopt: quiet video=radeonfb:1024x768-32@100
  * Lilo: append="quiet video=radeonfb:1024x768-32@100"
For intel i810 internal cards the lilo line would look like:
  append="video=i810fb:vram:2,xres:1024,yres:768,bpp:8,hsync1:30,hsync2:55, \
    vsync1:50,vsync2:85,accel,mtrr"

Splashy will support any video mode the framebuffer supports
The following is a table for the vide modes and their corresponding codes

                  640x480    800x600    1024x768       1280x1024       1600x1200
 256 colors (8b)    769        771         773            775             796
 32K colors (15b)   784        787         790            793             797
 64K colors (16b)   785        788         791            794             798
 16M colors (24b)   786        789         792            795             799

For example, for 1024x768 at 16bit (64K colors or "thousands of colors"), you
could pass an argument to the kernel like:
  vga=791
These values could be used in base16 (hexadecimal) also, like:
  vga=0x317

3. Link /etc/init.d/splashy-init to start at boot, shutdown or whenever you plan
   to start Splashy (see scripts/README)

4. Reboot and have fun!

Configuration
=============

Splashy's configuration file is /etc/splashy/config.xml

To know about it read it's man page: man splashy-config.xml

Initram File System
===================

In order to enable Splashy running early at the initramfs level, you need to
ensure the following:

1. Make sure that you edit /etc/default/splashy and set ENABLE_INITRAMFS= to 1
like:
  ENABLE_INITRAMFS=1
2. After that, run:
  update-initramfs -u -t -k `uname -r`

Lastly, you will need to find which /etc/init.d scripts use the commands
/usr/bin/unicode_start and /usr/bin/unicode_stop

These are used to set the font for all consoles as well as the keyboard
mapping. If this is done while Splashy is running from initramfs, the boot
process will stall. To avoid this do the following:

  cd /etc/init.d/
  grep -i unicode_ /etc/init.d/* -m1 | cut -f1 -d:

This will let you see which initrc scripts use the unicode_* commands. You will
need to then edit these scripts so that they do not execute the unicode_* command
if Splashy is running. If the script contains a function called
"unicode_start_stop()", patch it in the following way:

  unicode_start_stop()
  {
    # check if splashy is runing and skip this, we'll get run again later
    pidof splashy > /dev/null && return
    ...

If your scripts do not use unicode_start_stop() function (console-screen.sh doesn't), 
you might want to edit it like:

  #!/bin/sh
  # ...
  # check if splashy is runing and skip this, we'll get run again later
  pidof splashy > /dev/null && exit 0
  ...

In other words, check if there is a splashy process running as early as possible and
before running unicode_start/unicode_stop commands. If it is, skip unicode_*

Finally, edit /etc/default/splashy again and set POST_EXEC_SERVICES to contain the
names of the scripts you modified in the same order they are executed at boot time
For example:

  POST_EXEC_SERVICES="keymap.sh console-screen.sh"

Themes
======

To install a new theme, download it and install it with splashy_config:

  splashy_config -i <theme>

To use some theme as the default theme, run:

  splashy_config -s <theme_name>

You can get a list of available themes with:

  splashy_config --info

To create a theme, run "splashy_config -c" and answer all the questions

Uninstallation
==============

From within the extracted sources directory just run as super-user:

  make uninstall

Other (Links)
=============

Project page: http://alioth.debian.org/projects/splashy

Documentation/Wiki: http://splashy.alioth.debian.org

IRC: Channel #splashy on irc.freenode.net

Mail list: splashy-users@lists.alioth.debian.org

Development sources: svn://svn.debian.org/svn/splashy
