workspace/ksplash/ksplashx/README

   1 This is a splashscreen which basically depends only on libX11 and libpng.
   2 It includes few sources from Qt which have been modified to work without
   3 QApplication. Due to almost no link dependencies and no QApplication
   4 initialization this splashscreen has a very fast startup.
   5
   6 Please see file LICENSE for the licensing terms.
   7
   8
   9 LIMITATIONS:
  10 This implementation can only draw images and animations. This means that
  11 e.g. texts need to be pre-rendered into images. i18n support is however
  12 provided by mimicking KLocale's mechanism for localizing non-text resources.
  13
  14
  15 USAGE:
  16 ksplashx <theme> [--test]
  17
  18
  19 NOTES:
  20 Add a comment in description.txt and update it everytime you change anything.
  21 Caching of the splash is done and the timestamp of description.txt is used.
  22
  23 New images are alphablended (if needed) with what's in the splash window
  24 and then they replace what's at their position. Animations have all frames
  25 alphablended (if needed) with what's in the splash window but they do not
  26 replace window contents permanently.
  27
  28 In a theme directory there can be a subdirectory for each screen resolution
  29 named the same like the resolution (e.g. "1600x1200"). A best match is searched
  30 for the active screen resolution. It should be usually enough to have just
  31 one set, e.g. 1600x1200; especially with SCALE OFF.
  32
  33 Low color screen depths are supported, with bpp <= 8 a directory called with
  34 "-locolor" (e.g. "1600x1200-locolor") appended is always searched first.
  35
  36
  37 FORMAT:
  38
  39 # comments start with #
  40 # commands are case-sensitive
  41
  42 # whether to enable scaling (SCALE ON) or not (SCALE OFF) to fit current screen resolution
  43 # if enabled, all positions and sizes are scaled by ratio between their primary resolution size
  44 # and current resolution size (e.g. a 80x80 image at 100,0 in 1600x1200
  45 # is scaled to 40x40 at 50,0 for 800x600)
  46 # defaults to ON, it's suggested to always explicitly specify
  47 # it is possible to toggle scaling also several times (e.g. scale background image, not scale the rest)
  48 SCALE ON/OFF
  49
  50 # like SCALE, for only one dimension
  51 SCALEX ON/OFF
  52 SCALEY ON/OFF
  53
  54 # x y w h - geometry of the splash window (screen size by default)
  55 # if x or y are negative, they're relative to the right/bottom side
  56 GEOMETRY x y w h
  57
  58 # geometry of the splash window relatively to the screen
  59 # relative position is specified as x_rel,y_rel offset of reference point of the window
  60 # to reference point of the screen
  61 # reference point is specified as two letters, first being X, second being Y:
  62 #   L - left, R - right, C - center, T - top, B - bottom
  63 # e.g. GEOMETRY_REL LC 100 0 CC places window's center 100 pixels to the right of middle of left screen edge
  64 GEOMETRY_REL screen_ref x_rel y_rel window_ref w h
  65
  66 # color to fill the window with (this command also clears the whole window)
  67 # not necessary if image(s) will fill the area entirely
  68 BACKGROUND color
  69
  70 # place an image called name (no path, include extension) at position x,y
  71 IMAGE x y name
  72
  73 # Same as image but this image is painted on every screen in xinerama setups
  74 BACKGROUND_IMAGE x y name
  75
  76 # place an image called name (no path, include extension) at relative position
  77 # see description of GEOMETRY_REL for screen_ref, x_rel, y_rel and image_ref (=window_ref)
  78 IMAGE_REL screen_ref x_rel y_xrel image_ref name
  79
  80 # place animation from file 'name' at position x,y, id is 'number'
  81 # animation is specified in a non-animated file as a sequence of images in rows,
  82 # images wrap at 10 columns
  83 # image contains 'frames' frames and there's 'delay' pause between each frame
  84 # the animation repeats 'repeat' times, with 0 for infinite (optional field defaulting to 0)
  85 ANIM number x y frames name delay [repeat]
  86
  87 # place animation
  88 # see description of ANIM for number, frames, name, delay and repeat
  89 # see description of GEOMETRY_REL for screen_ref, x_rel, y_rel and image_ref (=window_ref)
  90 ANIM_REL number screen_ref x_rel y_rel image_ref frames name delay [repeat]
  91
  92 # stop animation with the given id
  93 # this also clears the animation from the window
  94 STOP_ANIM number
  95
  96 # wait until the specified ksplash state
  97 # see the splash toplevel README file (one directory up)
  98 # specifying "ready" means waiting until whole startup is complete (should be used at the very end)
  99 WAIT_STATE state
 100
 101
 102 HOW TO CREATE ANIM PNG FILE:
 103
 104 Since there's only PNG support, animation have to be prepared as separate frames.
 105 In order to improve performance, all frames are put together in one big PNG file.
 106
 107 Steps:
 108 1. Animation must be prepared as a list of images.
 109 2. In the utils/ directory there's prepareanim utility. Run it as
 110    ./prepareanim <frame images>
 111    where
 112    frame images - list of images for animation in their order
 113 3. File result.png will be created.
 114
 115 It is also possible to create the resulting PNG manually - frames are added
 116 in rows, rows wrap at 10th frame.