1. Theme metadata
-----------------

It is advised that all fbsplash themes be shipped with a metadata.xml
file providing additional information about the author, license and origin
of the theme.  The XML schema for this file is available in
thememeta.xsd.  A sample metadata file is provided in metadata_sample.xml.
The metadata.xml file should be located in the main directory of the
fbsplash theme (e.g. /etc/splash/<themename>/metadata.xml).



2. Config file directives
-------------------------

NOTE: Unless otherwise stated, all coordinates are specified in the screen
coordinate system (i.e. the top left pixel is at (0,0)).

There are two types of directives that can be used in fbsplash config
files: object/setting and grouping directives.  The first kind is used
to specify that an object is to be displayed on the screen or that
a setting should take a specific value.  The grouping directives on the
other hand are used add a context to the set of object/setting directives
that they enclose.


2.1 Grouping directives
------------------------

* <type type-spec [type-spec]>..</type>
  type-spec can be any of the following: 'bootup', 'reboot', 'shutdown',
  'suspend', 'resume' and 'other'.

  All directives enclosed in a <type> section will be effective only if
  one of the processes specified in 'type-spec' is taking place.  If a
  directive is not contained in a <type> section, it is effective regardless
  of which process is taking place.

  Example:

  # Progress bar for boot-up.
  <type bootup>
     box silent inter 0    262  0    337  #22222c #191920 #383849 #2e2e3d
  	 box silent       0    262  799  337  #22222c #191920 #383849 #2e2e3d
  </type>

  # Progress bar for reboot/shutdown.
  <type reboot shutdown>
     box silent inter 0    262  799  337  #22222c #191920 #383849 #2e2e3d
     box silent       0    262  0    337  #22222c #191920 #383849 #2e2e3d
  </type>

* <textbox>..</textbox>

  Directives enclosed in this section will be assumed to form an integral
  part of a textbox that is only to be displayed on an explicit request
  by the user (by a config file setting or by pressing F3 when fbsplash is
  active).

  The textbox usually contains the fbsplash message log.

  Example:
  <textbox>
     text silent dejavu.ttf 12 100 100 #ffffff "System messages:"
	 text silent courier.ttf 10 100 120 #eeeeee msglog
  </textbox>


2.2 Silent mode directives
--------------------------

* silentpic=<path>
  Relative path to the JPG/PNG background image for silent mode.

* silentpic256=<path>
  Relative path to the PNG background image for silent splash mode and 8 bpp
  video modes.

  NOTES:
  - The image can have a maximum of 256 colors.

* log_lines=<n>
  Number of lines to display from the fbsplash message log.

* log_cols=<n>
  Number of columns to display from the fbsplash message log.

* text_x=<n>
  The x coordinate of the main system message.

* text_y=<n>
  The y coordinate of the main system message.

* text_size=<n>
  The size of the font used to render the main system message.

* text_color=<color>
  The color of the main system message either in [0x|#]rrggbb or in
  [0x|#]rrggbbaa format.

* text_font=<file>
  A path to the TTF font with which the main system message will be rendered.
  The path can be either:
   - an absolute path, starting with '/',
   - a path relative to THEME_DIR (eg. /etc/splash),
   - a path relative to THEME_DIR/<theme_name> (eg. /etc/splash/default),

* text [flags] <font> [style] <size> <x> [left|middle|right]
  <y> [top|middle|bottom] <color> ([exec] [eval] "text" | msglog)

  Draws an UTF8-encoded text string somewhere on the screen.

  Flags:
  silent  - The text is rendered only in silent mode.
  verbose - The text is rendered only in verbose mode.

  If no flags are specified, the text is rendered in both modes.

  'font' is the name of the file with a TTF font. The path is interpreted in
  the same way as in the case of the 'text_font' configuration directive.

  'style' can be used to select a bold/italic/underlined form. The style
  selector is formed with the following characters:

   'b' - bold
   'i' - italic
   'u' - underlined

  Example:
   A style selector for a bold italic font: bi

  The color can be specified either as #rrggbb or as #rrggbbaa.

  The x and y coordinates specify the position of the hot spot of the text
  string. The position of the hot spot within the bounding rectangle of the
  text string can be chosen with the 'left', 'middle' and 'right', 'top'
  and 'bottom' flags.

  The different positions of the hot spot are shown below:

 (lt)-------------------------(mt)----------------------------(rt)
  | TTTTTT EEEEE  SSSS TTTTTT      TTTTTT EEEEE XX  XX TTTTTT   |
  |   TT   EE    SS      TT          TT   EE     XXXX    TT     |
 (lm) TT   EEEE   SSS    TT   (mm)   TT   EEEE    XX     TT   (rm)
  |   TT   EE       SS   TT          TT   EE     XXXX    TT     |
  |   TT   EEEEE SSSS    TT          TT   EEEEE XX  XX   TT     |
 (lb)-------------------------(mb)----------------------------(rb)

  lt = left/top
  mt = middle/top
  rt = right/top
  lm = left/middle
  ...

  The default position of the hot spot is (lt) (left - top).

  Before the text is rendered/evaluated, all expressions of the form:
  '\x', where 'x' is any character, are replaced by 'x'.

  If the 'exec' flag is set, sh -c 'text' is executed, and the value
  read from stdout is rendered on the screen.

  If the 'eval' flag is set, evaluation is performed on the 'text'
  argument. Variables of the form $variablename are replaced by their
  values. Recognized variables:
   - $progress - progress indicator (in percents)

  If the 'msglog' flag is set, the text object will display the
  contents of the fbsplash message log.

  The 'text' argument has to be enclosed in double quotes.

* box [flags] <x0> <y0> <x1> <y1> <color1> [color2 color3 color4]
  Draws a box on the screen.

  Flags:
  silent - The box is drawn only in silent mode. If a box doesn't have
           this flag set, it's drawn only in verbose mode.
  noover - This stands for no-overpaint. Boxes with this flag set are
           painted only when progress == 0 or the repaint command is used.
  inter  - The box will be interpolated with the following one, based
           on the value of the progress variable.

  x0, y0 - coordinates of the upper left corner of the box
  x1, y1 - coordinates of the lower right corner of the box

  Colors are specified in one of the following formats:
  - #rrggbb
  - #rrggbbaa
  aa = alpha, 00 - translucent, ff - solid

  If only color1 is specified, the box is filled with the color.
  If all four colors are specified, then:

  color1   is the color of the   upper left    corner of the box,
  color2   is the color of the   upper right   corner of the box,
  color3   is the color of the   lower left    corner of the box,
  color4   is the color of the   lower right   corner of the box,

  and the box is filled with a gradient formed by these colors.

* icon <path> <x> <y> [crop from to] [state service]
  Draws an icon (a PNG image) at coordinates x, y, based on
  the current state of a service.

  If the 'crop' keyword is used, the icon will be cropped by a
  rectangle interpolated between 'from' and 'to', based on the
  value of the progress variable. 'from' and 'to' are both
  rectangles described in the icon coordinate system using the
  following format:

    <x0, y0, x1, y1>

  In the icon coordinate system, the icon's top left corner
  is at (0,0).

  'state' can be one of the following:
  svc_inactive_start,   svc_inactive_stop,
  svc_started,          svc_stopped,
  svc_start_failed,     svc_stop_failed,
  svc_start,            svc_stop,

  'service' is the name of the system service.

  An icon will be rendered on the screen only if its state has
  been set through an appropriate splash daemon command.

  Examples:

   1) icon img/logo.png 100 100 crop <0,0,49,0> <0,0,49,199>
      The image from img/logo.png will be painted at (100,100)
      (ie. at the 101-th pixel from the left and from the top).

      The image will be cropped. When progress == 0, no part of
      it will be displayed on the screen (height of the first
      rectangle is equal to 0). As the progress increases, the
      image will be extended downward, until it reaches the
      full size of 50 x 200 pixels.

* anim <once|loop|proportional> <path> <x> <y> [state service]

  Displays a MNG animation on the silent splash screen at (x,y).

  'once' -- the animation is displayed only once. After it reaches its
            last frame, it is displayed just like an icon.

  'loop' -- the animation is displayed in an infinite loop.

  'proportional' -- the animation progress is coupled with the progress
                    variable. Note that in this case, the animation
                    isn't smooth and only single frames are displayed.

  Depending on how the mng file is constructed 'once' and 'proportional'
  might not work as aspected. When the file is internally looped, the
  animation will always be displayed in an infinite loop (even when
  the 'once' flag is used). When the file doesn't contain a frame
  counter, 'proportional' will not work and only the first frame will
  be displayed.

  The animations are displayed only when the screen is painted by the
  splash daemon, they won't work with the kernel helper (i.e. the animations
  won't work from an initrd).


2.3 Special effects modifiers
-----------------------------

Each of the following object directives: box, text, icon, anim can be
directly followed by a whitespace-separated set of special effect
modifiers:

* blendin(time)
  When the object becomes visible, its alpha is smoothly changed from
  0% (transparent) to 100% (full opacity).  Time is specified in
  miliseconds.

* blendout(time)
  When the object becomes invisible, its alpha is smoothly changed from
  100% (full opacity) to 0% (invisible).  Time is specified in
  miliseconds.

The notion of changing the visibility of an object refers to one of the
following:
- the first time the object is displayed,
- a change of the status of a service causing the object to be shown/hidden.


2.4 Verbose mode settings (for fbcondecor)
------------------------------------------

* pic=<path>
  Relative path to the JPG/PNG background image for verbose mode.

* pic256=<path>
  Relative path to the PNG background image for verbose splash mode and 8 bpp
  video modes.

  NOTES:
  - The image can have a maximum of 240 colors. 16 colors are taken by fbcon
    and cannot be used in the picture.

* bgcolor=<n>
  Background color which is to be treated as transparent by fbcon. Usually 0.

* tx=<n>
  The x coordinate of the upper left corner of the text window.

* ty=<n>
  The y coordinate of the upper left corner of the text window.

* tw=<n>
  The width of the text window. n cannot be greater than horizontal resolution.

* th=<n>
  The height of the text window. n cannot be greater than vertical resolution.


2.5 Deprecated settings
------------------------
* jpeg=<path>
  Relative path to the JPG background image for verbose mode.
  (Use pic=<path> instead.)

* silentjpeg=<path>
  Relative path to the JPG background image for silent mode.
  (Use silentpic=<path> instead.)


