1urxvt-background(1)              RXVT-UNICODE              urxvt-background(1)
2
3
4

NAME

6       background - manage terminal background
7

SYNOPSIS

9          urxvt --background-expr 'background expression'
10                --background-border
11                --background-interval seconds
12

QUICK AND DIRTY CHEAT SHEET

14       Just load a random jpeg image and tile the background with it without
15       scaling or anything else:
16
17          load "/path/to/img.jpg"
18
19       The same, but use mirroring/reflection instead of tiling:
20
21          mirror load "/path/to/img.jpg"
22
23       Load an image and scale it to exactly fill the terminal window:
24
25          scale keep { load "/path/to/img.jpg" }
26
27       Implement pseudo-transparency by using a suitably-aligned root pixmap
28       as window background:
29
30          rootalign root
31
32       Likewise, but keep a blurred copy:
33
34          rootalign keep { blur 10, root }
35

DESCRIPTION

37       This extension manages the terminal background by creating a picture
38       that is behind the text, replacing the normal background colour.
39
40       It does so by evaluating a Perl expression that calculates the image on
41       the fly, for example, by grabbing the root background or loading a
42       file.
43
44       While the full power of Perl is available, the operators have been
45       design to be as simple as possible.
46
47       For example, to load an image and scale it to the window size, you
48       would use:
49
50          urxvt --background-expr 'scale keep { load "/path/to/mybg.png" }'
51
52       Or specified as a X resource:
53
54          URxvt.background.expr: scale keep { load "/path/to/mybg.png" }
55

THEORY OF OPERATION

57       At startup, just before the window is mapped for the first time, the
58       expression is evaluated and must yield an image. The image is then
59       extended as necessary to cover the whole terminal window, and is set as
60       a background pixmap.
61
62       If the image contains an alpha channel, then it will be used as-is in
63       visuals that support alpha channels (for example, for a compositing
64       manager). In other visuals, the terminal background colour will be used
65       to replace any transparency.
66
67       When the expression relies, directly or indirectly, on the window size,
68       position, the root pixmap, or a timer, then it will be remembered. If
69       not, then it will be removed.
70
71       If any of the parameters that the expression relies on changes (when
72       the window is moved or resized, its position or size changes; when the
73       root pixmap is replaced by another one the root background changes; or
74       when the timer elapses), then the expression will be evaluated again.
75
76       For example, an expression such as "scale keep { load "$HOME/mybg.png"
77       }" scales the image to the window size, so it relies on the window size
78       and will be reevaluated each time it is changed, but not when it moves
79       for example. That ensures that the picture always fills the terminal,
80       even after its size changes.
81
82   EXPRESSIONS
83       Expressions are normal Perl expressions, in fact, they are Perl blocks
84       - which means you could use multiple lines and statements:
85
86          scale keep {
87             again 3600;
88             if (localtime now)[6]) {
89                return load "$HOME/weekday.png";
90             } else {
91                return load "$HOME/sunday.png";
92             }
93          }
94
95       This inner expression is evaluated once per hour (and whenever the
96       terminal window is resized). It sets sunday.png as background on
97       Sundays, and weekday.png on all other days.
98
99       Fortunately, we expect that most expressions will be much simpler, with
100       little Perl knowledge needed.
101
102       Basically, you always start with a function that "generates" an image
103       object, such as "load", which loads an image from disk, or "root",
104       which returns the root window background image:
105
106          load "$HOME/mypic.png"
107
108       The path is usually specified as a quoted string (the exact rules can
109       be found in the perlop manpage). The $HOME at the beginning of the
110       string is expanded to the home directory.
111
112       Then you prepend one or more modifiers or filtering expressions, such
113       as "scale":
114
115          scale load "$HOME/mypic.png"
116
117       Just like a mathematical expression with functions, you should read
118       these expressions from right to left, as the "load" is evaluated first,
119       and its result becomes the argument to the "scale" function.
120
121       Many operators also allow some parameters preceding the input image
122       that modify its behaviour. For example, "scale" without any additional
123       arguments scales the image to size of the terminal window. If you
124       specify an additional argument, it uses it as a scale factor (multiply
125       by 100 to get a percentage):
126
127          scale 2, load "$HOME/mypic.png"
128
129       This enlarges the image by a factor of 2 (200%). As you can see,
130       "scale" has now two arguments, the 200 and the "load" expression, while
131       "load" only has one argument. Arguments are separated from each other
132       by commas.
133
134       Scale also accepts two arguments, which are then separate factors for
135       both horizontal and vertical dimensions. For example, this halves the
136       image width and doubles the image height:
137
138          scale 0.5, 2, load "$HOME/mypic.png"
139
140       IF you try out these expressions, you might suffer from some
141       sluggishness, because each time the terminal is resized, it loads the
142       PNG image again and scales it. Scaling is usually fast (and
143       unavoidable), but loading the image can be quite time consuming. This
144       is where "keep" comes in handy:
145
146          scale 0.5, 2, keep { load "$HOME/mypic.png" }
147
148       The "keep" operator executes all the statements inside the braces only
149       once, or when it thinks the outcome might change. In other cases it
150       returns the last value computed by the brace block.
151
152       This means that the "load" is only executed once, which makes it much
153       faster, but also means that more memory is being used, because the
154       loaded image must be kept in memory at all times. In this expression,
155       the trade-off is likely worth it.
156
157       But back to effects: Other effects than scaling are also readily
158       available, for example, you can tile the image to fill the whole
159       window, instead of resizing it:
160
161          tile keep { load "$HOME/mypic.png" }
162
163       In fact, images returned by "load" are in "tile" mode by default, so
164       the "tile" operator is kind of superfluous.
165
166       Another common effect is to mirror the image, so that the same edges
167       touch:
168
169          mirror keep { load "$HOME/mypic.png" }
170
171       Another common background expression is:
172
173          rootalign root
174
175       This one first takes a snapshot of the screen background image, and
176       then moves it to the upper left corner of the screen (as opposed to the
177       upper left corner of the terminal window)- the result is pseudo-
178       transparency: the image seems to be static while the window is moved
179       around.
180
181   COLOUR SPECIFICATIONS
182       Whenever an operator expects a "colour", then this can be specified in
183       one of two ways: Either as string with an X11 colour specification,
184       such as:
185
186          "red"               # named colour
187          "#f00"              # simple rgb
188          "[50]red"           # red with 50% alpha
189          "TekHVC:300/50/50"  # anything goes
190
191       OR as an array reference with one, three or four components:
192
193          [0.5]               # 50% gray, 100% alpha
194          [0.5, 0, 0]         # dark red, no green or blur, 100% alpha
195          [0.5, 0, 0, 0.7]    # same with explicit 70% alpha
196
197   CACHING AND SENSITIVITY
198       Since some operations (such as "load" and "blur") can take a long time,
199       caching results can be very important for a smooth operation. Caching
200       can also be useful to reduce memory usage, though, for example, when an
201       image is cached by "load", it could be shared by multiple terminal
202       windows running inside urxvtd.
203
204       "keep { ... }" caching
205
206       The most important way to cache expensive operations is to use "keep {
207       ... }". The "keep" operator takes a block of multiple statements
208       enclosed by "{}" and keeps the return value in memory.
209
210       An expression can be "sensitive" to various external events, such as
211       scaling or moving the window, root background changes and timers.
212       Simply using an expression (such as "scale" without parameters) that
213       depends on certain changing values (called "variables"), or using those
214       variables directly, will make an expression sensitive to these events -
215       for example, using "scale" or "TW" will make the expression sensitive
216       to the terminal size, and thus to resizing events.
217
218       When such an event happens, "keep" will automatically trigger a
219       reevaluation of the whole expression with the new value of the
220       expression.
221
222       "keep" is most useful for expensive operations, such as "blur":
223
224          rootalign keep { blur 20, root }
225
226       This makes a blurred copy of the root background once, and on
227       subsequent calls, just root-aligns it. Since "blur" is usually quite
228       slow and "rootalign" is quite fast, this trades extra memory (for the
229       cached blurred pixmap) with speed (blur only needs to be redone when
230       root changes).
231
232       "load" caching
233
234       The "load" operator itself does not keep images in memory, but as long
235       as the image is still in memory, "load" will use the in-memory image
236       instead of loading it freshly from disk.
237
238       That means that this expression:
239
240          keep { load "$HOME/path..." }
241
242       Not only caches the image in memory, other terminal instances that try
243       to "load" it can reuse that in-memory copy.
244

REFERENCE

246   COMMAND LINE SWITCHES
247       --background-expr perl-expression
248           Specifies the Perl expression to evaluate.
249
250       --background-border
251           By default, the expression creates an image that fills the full
252           window, overwriting borders and any other areas, such as the
253           scrollbar.
254
255           Specifying this flag changes the behaviour, so that the image only
256           replaces the background of the character area.
257
258       --background-interval seconds
259           Since some operations in the underlying XRender extension can
260           effectively freeze your X-server for prolonged time, this extension
261           enforces a minimum time between updates, which is normally about
262           0.1 seconds.
263
264           If you want to do updates more often, you can decrease this safety
265           interval with this switch.
266
267   PROVIDERS/GENERATORS
268       These functions provide an image, by loading it from disk, grabbing it
269       from the root screen or by simply generating it. They are used as
270       starting points to get an image you can play with.
271
272       load $path
273           Loads the image at the given $path. The image is set to plane
274           tiling mode.
275
276           If the image is already in memory (e.g. because another terminal
277           instance uses it), then the in-memory copy is returned instead.
278
279       load_uc $path
280           Load uncached - same as load, but does not cache the image, which
281           means it is always loaded from the filesystem again, even if
282           another copy of it is in memory at the time.
283
284       root
285           Returns the root window pixmap, that is, hopefully, the background
286           image of your screen.
287
288           This function makes your expression root sensitive, that means it
289           will be reevaluated when the bg image changes.
290
291       solid $colour
292       solid $width, $height, $colour
293           Creates a new image and completely fills it with the given colour.
294           The image is set to tiling mode.
295
296           If $width and $height are omitted, it creates a 1x1 image, which is
297           useful for solid backgrounds or for use in filtering effects.
298
299       clone $img
300           Returns an exact copy of the image. This is useful if you want to
301           have multiple copies of the same image to apply different effects
302           to.
303
304       merge $img ...
305           Takes any number of images and merges them together, creating a
306           single image containing them all. The tiling mode of the first
307           image is used as the tiling mode of the resulting image.
308
309           This function is called automatically when an expression returns
310           multiple images.
311
312   TILING MODES
313       The following operators modify the tiling mode of an image, that is,
314       the way that pixels outside the image area are painted when the image
315       is used.
316
317       tile $img
318           Tiles the whole plane with the image and returns this new image -
319           or in other words, it returns a copy of the image in plane tiling
320           mode.
321
322           Example: load an image and tile it over the background, without
323           resizing. The "tile" call is superfluous because "load" already
324           defaults to tiling mode.
325
326              tile load "mybg.png"
327
328       mirror $img
329           Similar to tile, but reflects the image each time it uses a new
330           copy, so that top edges always touch top edges, right edges always
331           touch right edges and so on (with normal tiling, left edges always
332           touch right edges and top always touch bottom edges).
333
334           Example: load an image and mirror it over the background, avoiding
335           sharp edges at the image borders at the expense of mirroring the
336           image itself
337
338              mirror load "mybg.png"
339
340       pad $img
341           Takes an image and modifies it so that all pixels outside the image
342           area become transparent. This mode is most useful when you want to
343           place an image over another image or the background colour while
344           leaving all background pixels outside the image unchanged.
345
346           Example: load an image and display it in the upper left corner. The
347           rest of the space is left "empty" (transparent or whatever your
348           compositor does in alpha mode, else background colour).
349
350              pad load "mybg.png"
351
352       extend $img
353           Extends the image over the whole plane, using the closest pixel in
354           the area outside the image. This mode is mostly useful when you use
355           more complex filtering operations and want the pixels outside the
356           image to have the same values as the pixels near the edge.
357
358           Example: just for curiosity, how does this pixel extension stuff
359           work?
360
361              extend move 50, 50, load "mybg.png"
362
363   VARIABLE VALUES
364       The following functions provide variable data such as the terminal
365       window dimensions. They are not (Perl-) variables, they just return
366       stuff that varies. Most of them make your expression sensitive to some
367       events, for example using "TW" (terminal width) means your expression
368       is evaluated again when the terminal is resized.
369
370       TX
371       TY  Return the X and Y coordinates of the terminal window (the terminal
372           window is the full window by default, and the character area only
373           when in border-respect mode).
374
375           Using these functions makes your expression sensitive to window
376           moves.
377
378           These functions are mainly useful to align images to the root
379           window.
380
381           Example: load an image and align it so it looks as if anchored to
382           the background (that's exactly what "rootalign" does btw.):
383
384              move -TX, -TY, keep { load "mybg.png" }
385
386       TW
387       TH  Return the width ("TW") and height ("TH") of the terminal window
388           (the terminal window is the full window by default, and the
389           character area only when in border-respect mode).
390
391           Using these functions makes your expression sensitive to window
392           resizes.
393
394           These functions are mainly useful to scale images, or to clip
395           images to the window size to conserve memory.
396
397           Example: take the screen background, clip it to the window size,
398           blur it a bit, align it to the window position and use it as
399           background.
400
401              clip move -TX, -TY, keep { blur 5, root }
402
403       FOCUS
404           Returns a boolean indicating whether the terminal window has
405           keyboard focus, in which case it returns true.
406
407           Using this function makes your expression sensitive to focus
408           changes.
409
410           A common use case is to fade the background image when the terminal
411           loses focus, often together with the "-fade" command line option.
412           In fact, there is a special function for just that use case:
413           "focus_fade".
414
415           Example: use two entirely different background images, depending on
416           whether the window has focus.
417
418              FOCUS ? keep { load "has_focus.jpg" } : keep { load "no_focus.jpg" }
419
420       now Returns the current time as (fractional) seconds since the epoch.
421
422           Using this expression does not make your expression sensitive to
423           time, but the next two functions do.
424
425       again $seconds
426           When this function is used the expression will be reevaluated again
427           in $seconds seconds.
428
429           Example: load some image and rotate it according to the time of day
430           (as if it were the hour pointer of a clock). Update this image
431           every minute.
432
433              again 60;
434              rotate 50, 50, (now % 86400) * -72 / 8640, scale keep { load "myclock.png" }
435
436       counter $seconds
437           Like "again", but also returns an increasing counter value,
438           starting at 0, which might be useful for some simple animation
439           effects.
440
441   SHAPE CHANGING OPERATORS
442       The following operators modify the shape, size or position of the
443       image.
444
445       clip $img
446       clip $width, $height, $img
447       clip $x, $y, $width, $height, $img
448           Clips an image to the given rectangle. If the rectangle is outside
449           the image area (e.g. when $x or $y are negative) or the rectangle
450           is larger than the image, then the tiling mode defines how the
451           extra pixels will be filled.
452
453           If $x and $y are missing, then 0 is assumed for both.
454
455           If $width and $height are missing, then the window size will be
456           assumed.
457
458           Example: load an image, blur it, and clip it to the window size to
459           save memory.
460
461              clip keep { blur 10, load "mybg.png" }
462
463       scale $img
464       scale $size_factor, $img
465       scale $width_factor, $height_factor, $img
466           Scales the image by the given factors in horizontal ($width) and
467           vertical ($height) direction.
468
469           If only one factor is given, it is used for both directions.
470
471           If no factors are given, scales the image to the window size
472           without keeping aspect.
473
474       resize $width, $height, $img
475           Resizes the image to exactly $width times $height pixels.
476
477       fit $img
478       fit $width, $height, $img
479           Fits the image into the given $width and $height without changing
480           aspect, or the terminal size. That means it will be shrunk or grown
481           until the whole image fits into the given area, possibly leaving
482           borders.
483
484       cover $img
485       cover $width, $height, $img
486           Similar to "fit", but shrinks or grows until all of the area is
487           covered by the image, so instead of potentially leaving borders, it
488           will cut off image data that doesn't fit.
489
490       move $dx, $dy, $img
491           Moves the image by $dx pixels in the horizontal, and $dy pixels in
492           the vertical.
493
494           Example: move the image right by 20 pixels and down by 30.
495
496              move 20, 30, ...
497
498       align $xalign, $yalign, $img
499           Aligns the image according to a factor - 0 means the image is moved
500           to the left or top edge (for $xalign or $yalign), 0.5 means it is
501           exactly centered and 1 means it touches the right or bottom edge.
502
503           Example: remove any visible border around an image, center it
504           vertically but move it to the right hand side.
505
506              align 1, 0.5, pad $img
507
508       center $img
509       center $width, $height, $img
510           Centers the image, i.e. the center of the image is moved to the
511           center of the terminal window (or the box specified by $width and
512           $height if given).
513
514           Example: load an image and center it.
515
516             center keep { pad load "mybg.png" }
517
518       rootalign $img
519           Moves the image so that it appears glued to the screen as opposed
520           to the window. This gives the illusion of a larger area behind the
521           window. It is exactly equivalent to "move -TX, -TY", that is, it
522           moves the image to the top left of the screen.
523
524           Example: load a background image, put it in mirror mode and root
525           align it.
526
527              rootalign keep { mirror load "mybg.png" }
528
529           Example: take the screen background and align it, giving the
530           illusion of transparency as long as the window isn't in front of
531           other windows.
532
533              rootalign root
534
535       rotate $center_x, $center_y, $degrees, $img
536           Rotates the image clockwise by $degrees degrees, around the point
537           at $center_x and $center_y (specified as factor of image
538           width/height).
539
540           Example: rotate the image by 90 degrees around its center.
541
542              rotate 0.5, 0.5, 90, keep { load "$HOME/mybg.png" }
543
544   COLOUR MODIFICATIONS
545       The following operators change the pixels of the image.
546
547       tint $color, $img
548           Tints the image in the given colour.
549
550           Example: tint the image red.
551
552              tint "red", load "rgb.png"
553
554           Example: the same, but specify the colour by component.
555
556              tint [1, 0, 0], load "rgb.png"
557
558       shade $factor, $img
559           Shade the image by the given factor.
560
561       contrast $factor, $img
562       contrast $r, $g, $b, $img
563       contrast $r, $g, $b, $a, $img
564           Adjusts the contrast of an image.
565
566           The first form applies a single $factor to red, green and blue, the
567           second form applies separate factors to each colour channel, and
568           the last form includes the alpha channel.
569
570           Values from 0 to 1 lower the contrast, values higher than 1
571           increase the contrast.
572
573           Due to limitations in the underlying XRender extension, lowering
574           contrast also reduces brightness, while increasing contrast
575           currently also increases brightness.
576
577       brightness $bias, $img
578       brightness $r, $g, $b, $img
579       brightness $r, $g, $b, $a, $img
580           Adjusts the brightness of an image.
581
582           The first form applies a single $bias to red, green and blue, the
583           second form applies separate biases to each colour channel, and the
584           last form includes the alpha channel.
585
586           Values less than 0 reduce brightness, while values larger than 0
587           increase it. Useful range is from -1 to 1 - the former results in a
588           black, the latter in a white picture.
589
590           Due to idiosyncrasies in the underlying XRender extension, biases
591           less than zero can be very slow.
592
593           You can also try the experimental(!) "muladd" operator.
594
595       muladd $mul, $add, $img # EXPERIMENTAL
596           First multiplies the pixels by $mul, then adds $add. This can be
597           used to implement brightness and contrast at the same time, with a
598           wider value range than contrast and brightness operators.
599
600           Due to numerous bugs in XRender implementations, it can also
601           introduce a number of visual artifacts.
602
603           Example: increase contrast by a factor of $c without changing image
604           brightness too much.
605
606              muladd $c, (1 - $c) * 0.5, $img
607
608       blur $radius, $img
609       blur $radius_horz, $radius_vert, $img
610           Gaussian-blurs the image with (roughly) $radius pixel radius. The
611           radii can also be specified separately.
612
613           Blurring is often very slow, at least compared or other operators.
614           Larger blur radii are slower than smaller ones, too, so if you
615           don't want to freeze your screen for long times, start
616           experimenting with low values for radius (<5).
617
618       focus_fade $img
619       focus_fade $factor, $img
620       focus_fade $factor, $color, $img
621           Fades the image by the given factor (and colour) when focus is lost
622           (the same as the "-fade"/"-fadecolor" command line options, which
623           also supply the default values for "factor" and $color. Unlike with
624           "-fade", the $factor is a real value, not a percentage value (that
625           is, 0..1, not 0..100).
626
627           Example: do the right thing when focus fading is requested.
628
629              focus_fade load "mybg.jpg";
630
631   OTHER STUFF
632       Anything that didn't fit any of the other categories, even after
633       applying force and closing our eyes.
634
635       keep { ... }
636           This operator takes a code block as argument, that is, one or more
637           statements enclosed by braces.
638
639           The trick is that this code block is only evaluated when the
640           outcome changes - on other calls the "keep" simply returns the
641           image it computed previously (yes, it should only be used with
642           images). Or in other words, "keep" caches the result of the code
643           block so it doesn't need to be computed again.
644
645           This can be extremely useful to avoid redoing slow operations - for
646           example, if your background expression takes the root background,
647           blurs it and then root-aligns it it would have to blur the root
648           background on every window move or resize.
649
650           Another example is "load", which can be quite slow.
651
652           In fact, urxvt itself encloses the whole expression in some kind of
653           "keep" block so it only is reevaluated as required.
654
655           Putting the blur into a "keep" block will make sure the blur is
656           only done once, while the "rootalign" is still done each time the
657           window moves.
658
659              rootalign keep { blur 10, root }
660
661           This leaves the question of how to force reevaluation of the block,
662           in case the root background changes: If expression inside the block
663           is sensitive to some event (root background changes, window
664           geometry changes), then it will be reevaluated automatically as
665           needed.
666
667
668
6699.22                              2019-02-02               urxvt-background(1)
Impressum