core/docs/theme_format

   1 Theme metadata
   2 --------------
   3
   4 It is advised that all fbsplash themes are shipped with a metadata.xml
   5 file providing additional information about the author, license and origin
   6 of the theme.  The XML schema for this file is available in
   7 thememeta.xsd.  A sample metadata file is provided in metadata_sample.xml.
   8 The metadata.xml file should be located in the main directory of the
   9 fbsplash theme (e.g. it should be /etc/splash/<themename>/metadata.xml).
  10
  11
  12 Config file directives
  13 ----------------------
  14
  15 fbsplash recognizes the following directives in the config files in
  16 /etc/splash:
  17
  18 NOTE: Unless otherwise stated, all coordinates are specified in the screen
  19 coordinate system (ie. the top left pixel is at (0,0)) and are given in
  20 pixels.
  21
  22 Verbose mode settings (for fbcondecor)
  23 --------------------------------------
  24
  25 * pic=<path>
  26   Relative path to the JPG/PNG background image for verbose mode.
  27
  28 * pic256=<path>
  29   Relative path to the PNG background image for verbose splash mode and 8 bpp
  30   video modes.
  31
  32   NOTES:
  33   - The image can have a maximum of 240 colors. 16 colors are taken by fbcon
  34     and cannot be used in the picture.
  35
  36 * bgcolor=<n>
  37   Background color which is to be treated as transparent by fbcon. Usually 0.
  38
  39 * tx=<n>
  40   The x coordinate of the upper left corner of the text window.
  41
  42 * ty=<n>
  43   The y coordinate of the upper left corner of the text window.
  44
  45 * tw=<n>
  46   The width of the text window. n cannot be greater than horizontal resolution.
  47
  48 * th=<n>
  49   The height of the text window. n cannot be greater than vertical resolution.
  50
  51 Silent mode settings
  52 --------------------
  53
  54 You put any number of the following directives inside the <type>..</type>
  55 section to make them effective e.g. only during bootup, reboot or shutdown.
  56 This way you can effectively have completely different configs for each
  57 of the five supported processes.  If a directive is not inside a
  58 <type>..</type> section, it is effective regardless of which process
  59 is taking place.
  60
  61 The format for the <type> tag is:
  62   <type type-spec [type-spec]>
  63
  64 where type-spec is any of the following: 'bootup', 'reboot', 'shutdown',
  65 'suspend', 'resume' and 'other'.
  66
  67 Example:
  68  # Progress bar for boot-up.
  69  <type bootup>
  70          box silent inter 0    262  0    337  #22222c #191920 #383849 #2e2e3d
  71          box silent       0    262  799  337  #22222c #191920 #383849 #2e2e3d
  72  </type>
  73
  74  # Progress bar for reboot/shutdown.
  75  <type reboot shutdown>
  76          box silent inter 0    262  799  337  #22222c #191920 #383849 #2e2e3d
  77          box silent       0    262  0    337  #22222c #191920 #383849 #2e2e3d
  78  </type>
  79
  80 Silent mode directives
  81 ----------------------
  82
  83 * silentpic=<path>
  84   Relative path to the JPG/PNG background image for silent mode.
  85
  86 * silentpic256=<path>
  87   Relative path to the PNG background image for silent splash mode and 8 bpp
  88   video modes.
  89
  90   NOTES:
  91   - The image can have a maximum of 256 colors.
  92
  93 * log_lines=<n>
  94   Number of lines to display from the fbsplash message log.
  95
  96 * log_cols=<n>
  97   Number of columns to display from the fbsplash message log.
  98
  99 * text_x=<n>
 100   The x coordinate of the main system message.
 101
 102 * text_y=<n>
 103   The y coordinate of the main system message.
 104
 105 * text_size=<n>
 106   The size of the font used to render the main system message.
 107
 108 * text_color=<color>
 109   The color of the main system message either in [0x|#]rrggbb or in
 110   [0x|#]rrggbbaa format.
 111
 112 * text_font=<file>
 113   A path to the TTF font with which the main system message will be rendered.
 114   The path can be either:
 115    - an absolute path, starting with '/',
 116    - a path relative to THEME_DIR (eg. /etc/splash),
 117    - a path relative to THEME_DIR/<theme_name> (eg. /etc/splash/default),
 118
 119 * text [flags] <font> [style] <size> <x> [left|middle|right]
 120   <y> [top|middle|bottom] <color> ([exec] [eval] "text" | msglog)
 121
 122   Draws an UTF8-encoded text string somewhere on the screen.
 123
 124   Flags:
 125   silent  - The text is rendered only in silent mode.
 126   verbose - The text is rendered only in verbose mode.
 127
 128   If no flags are specified, the text is rendered in both modes.
 129
 130   'font' is the name of the file with a TTF font. The path is interpreted in
 131   the same way as in the case of the 'text_font' configuration directive.
 132
 133   'style' can be used to select a bold/italic/underlined form. The style
 134   selector is formed with the following characters:
 135
 136    'b' - bold
 137    'i' - italic
 138    'u' - underlined
 139
 140   Example:
 141    A style selector for a bold italic font: bi
 142
 143   The color can be specified either as #rrggbb or as #rrggbbaa.
 144
 145   The x and y coordinates specify the position of the hot spot of the text
 146   string. The position of the hot spot within the bounding rectangle of the
 147   text string can be chosen with the 'left', 'middle' and 'right', 'top'
 148   and 'bottom' flags.
 149
 150   The different positions of the hot spot are shown below:
 151
 152  (lt)-------------------------(mt)----------------------------(rt)
 153   | TTTTTT EEEEE  SSSS TTTTTT      TTTTTT EEEEE XX  XX TTTTTT   |
 154   |   TT   EE    SS      TT          TT   EE     XXXX    TT     |
 155  (lm) TT   EEEE   SSS    TT   (mm)   TT   EEEE    XX     TT   (rm)
 156   |   TT   EE       SS   TT          TT   EE     XXXX    TT     |
 157   |   TT   EEEEE SSSS    TT          TT   EEEEE XX  XX   TT     |
 158  (lb)-------------------------(mb)----------------------------(rb)
 159
 160   lt = left/top
 161   mt = middle/top
 162   rt = right/top
 163   lm = left/middle
 164   ...
 165
 166   The default position of the hot spot is (lt) (left - top).
 167
 168   Before the text is rendered/evaluated, all expressions of the form:
 169   '\x', where 'x' is any character, are replaced by 'x'.
 170
 171   If the 'exec' flag is set, sh -c 'text' is executed, and the value
 172   read from stdout is rendered on the screen.
 173
 174   If the 'eval' flag is set, evaluation is performed on the 'text'
 175   argument. Variables of the form $variablename are replaced by their
 176   values. Recognized variables:
 177    - $progress - progress indicator (in percents)
 178
 179   If the 'msglog' flag is set, the text object will display the
 180   contents of the fbsplash message log.
 181
 182   The 'text' argument has to be enclosed in double quotes.
 183
 184 * box [flags] <x0> <y0> <x1> <y1> <color1> [color2 color3 color4]
 185   Draws a box on the screen.
 186
 187   Flags:
 188   silent - The box is drawn only in silent mode. If a box doesn't have
 189            this flag set, it's drawn only in verbose mode.
 190   noover - This stands for no-overpaint. Boxes with this flag set are
 191            painted only when progress == 0 or the repaint command is used.
 192   inter  - The box will be interpolated with the following one, based
 193            on the value of the progress variable.
 194
 195   x0, y0 - coordinates of the upper left corner of the box
 196   x1, y1 - coordinates of the lower right corner of the box
 197
 198   Colors are specified in one of the following formats:
 199   - #rrggbb
 200   - #rrggbbaa
 201   aa = alpha, 00 - translucent, ff - solid
 202
 203   If only color1 is specified, the box is filled with the color.
 204   If all four colors are specified, then:
 205
 206   color1   is the color of the   upper left    corner of the box,
 207   color2   is the color of the   upper right   corner of the box,
 208   color3   is the color of the   lower left    corner of the box,
 209   color4   is the color of the   lower right   corner of the box,
 210
 211   and the box is filled with a gradient formed by these colors.
 212
 213 * icon <path> <x> <y> [crop from to] [state service]
 214   Draws an icon (a PNG image) at coordinates x, y, based on
 215   the current state of a service.
 216
 217   If the 'crop' keyword is used, the icon will be cropped by a
 218   rectangle interpolated between 'from' and 'to', based on the
 219   value of the progress variable. 'from' and 'to' are both
 220   rectangles described in the icon coordinate system using the
 221   following format:
 222
 223     <x0, y0, x1, y1>
 224
 225   In the icon coordinate system, the icon's top left corner
 226   is at (0,0).
 227
 228   'state' can be one of the following:
 229   svc_inactive_start,   svc_inactive_stop,
 230   svc_started,          svc_stopped,
 231   svc_start_failed,     svc_stop_failed,
 232   svc_start,            svc_stop,
 233
 234   'service' is the name of the system service.
 235
 236   An icon will be rendered on the screen only if its state has
 237   been set through an appropriate splash daemon command.
 238
 239   Examples:
 240
 241    1) icon img/logo.png 100 100 crop <0,0,49,0> <0,0,49,199>
 242       The image from img/logo.png will be painted at (100,100)
 243       (ie. at the 101-th pixel from the left and from the top).
 244
 245       The image will be cropped. When progress == 0, no part of
 246       it will be displayed on the screen (height of the first
 247       rectangle is equal to 0). As the progress increases, the
 248       image will be extended downward, until it reaches the
 249       full size of 50 x 200 pixels.
 250
 251 * anim <once|loop|proportional> <path> <x> <y> [state service]
 252
 253   Displays a MNG animation on the silent splash screen at (x,y).
 254
 255   'once' -- the animation is displayed only once. After it reaches its
 256             last frame, it is displayed just like an icon.
 257
 258   'loop' -- the animation is displayed in an infinite loop.
 259
 260   'proportional' -- the animation progress is coupled with the progress
 261                     variable. Note that in this case, the animation
 262                     isn't smooth and only single frames are displayed.
 263
 264   Depending on how the mng file is constructed 'once' and 'proportional'
 265   might not work as aspected. When the file is internally looped, the
 266   animation will always be displayed in an infinite loop (even when
 267   the 'once' flag is used). When the file doesn't contain a frame
 268   counter, 'proportional' will not work and only the first frame will
 269   be displayed.
 270
 271   The animations are displayed only when the screen is painted by the
 272   splash daemon, they won't work with the kernel helper (i.e. the animations
 273   won't work from an initrd).
 274
 275 Deprecated settings
 276 -------------------
 277 * jpeg=<path>
 278   Relative path to the JPG background image for verbose mode.
 279   (Use pic=<path> instead.)
 280
 281 * silentjpeg=<path>
 282   Relative path to the JPG background image for silent mode.
 283   (Use silentpic=<path> instead.)
 284
 285