sites

public wiki contents of suckless.org
git clone git://git.suckless.org/sites
Log | Files | Refs

index.md (3023B)

      1 background image
      2 ================
      3 
      4 Description
      5 -----------
      6 
      7 Draws a background image in place of the `defaultbg` color. Instead of
      8 loading an image file itself, st uses the pixmap published by the
      9 companion program `stbg` in the `_ST_BACKGROUND_IMAGE` root window
     10 property. Every st instance tiles the same server-side pixmap, so the
     11 image data is held in memory only once and all instances stay in sync.
     12 
     13 Download
     14 --------
     15 
     16 * [st-background-image-0.9.3.diff](st-background-image-0.9.3.diff)
     17 
     18 Usage
     19 -----
     20 
     21 The background image is set by the separate `stbg` tool, which reads a
     22 [farbfeld](//tools.suckless.org/farbfeld) image and publishes it on the
     23 root window:
     24 
     25 	cc -o stbg stbg.c -lX11
     26 	stbg wallpaper.ff
     27 	stbg - < wallpaper.ff
     28 
     29 Once the image is published, every st started afterwards tiles it across
     30 its window. Re-running `stbg` with a new image updates all running st
     31 instances immediately; there is no need to restart or reload them.
     32 
     33 Pseudo Transparency
     34 -------------------
     35 
     36 The variable `pseudotransparency` in `config.def.h` fixes the
     37 coordinates of the background image to the screen origin. This emulates
     38 the effect of transparency without the need for an *X composite
     39 manager*.
     40 
     41 *Hint*: Because image processing is done outside of st, effects can be
     42 applied to the desktop background in an automated fashion with external
     43 tools. Pictured below is an example of the result of a darken and blur
     44 operation using [farbfeld utilities](https://web.archive.org/web/20211205013032/http://zzo38computer.org/fossil/farbfeld.ui/index):
     45 
     46 	jpg2ff < wallpaper.jpg | ff-border e 50 | ff-bright rgba 0 0.5 1 | ff-blur 50 15 | stbg -
     47 
     48 ![Screenshot](pseudo-transparency.png)
     49 
     50 Legacy versions
     51 ---------------
     52 
     53 Older versions of this patch loaded the farbfeld image directly inside
     54 st. They still work but have several shortcomings that are fixed by the
     55 0.9.3 version above:
     56 
     57 * **Per-instance decoding.** Each st instance read and decoded the
     58   image file from disk and created its own copy of the pixmap. With
     59   several terminals open the same image was held in memory multiple
     60   times.
     61 * **No live updates.** The background was only loaded at startup.
     62   Updating it required the *signal reload* hack: sending a `USR1`
     63   signal to every st process (`pidof st | xargs kill -s USR1`) after
     64   regenerating the image file, assuming the extra
     65   `st-background-image-signal-reload-0.8.5.diff` patch had been
     66   applied on top.
     67 * **Recompilation to change the image.** The image path was baked in
     68   at build time via the `bgfile` variable in `config.h`.
     69 * **File format parsing inside the terminal.** The farbfeld loading
     70   code, including `arpa/inet` byte-swapping, lived in `x.c`, tying the
     71   terminal to a single image format.
     72 
     73 Legacy downloads:
     74 
     75 * [st-background-image-0.8.4.diff](st-background-image-0.8.4.diff)
     76 * [st-background-image-0.8.5.diff](st-background-image-0.8.5.diff)
     77 * [st-background-image-signal-reload-0.8.5.diff](st-background-image-signal-reload-0.8.5.diff)
     78 
     79 Authors
     80 -------
     81 
     82 * Matthias Schoth - <mschoth@gmail.com>