1urxvt-background(1) RXVT-UNICODE urxvt-background(1)
2
6 background - manage terminal background
7
9 urxvt --background-expr 'background expression'
10 --background-border
11 --background-interval seconds
12
14 Load a random jpeg image and tile the background with it without
15 scaling or anything else:
16 load "/path/to/img.jpg"
18 The same, but use mirroring/reflection instead of tiling:
20 mirror load "/path/to/img.jpg"
22 Load an image and scale it to exactly fill the terminal window:
24 scale keep { load "/path/to/img.jpg" }
26 Implement pseudo-transparency by using a suitably-aligned root pixmap
28 as window background:
29 rootalign root
31 Likewise, but keep a blurred copy:
33 rootalign keep { blur 10, root }
35
37 This extension manages the terminal background by creating a picture
38 that is behind the text, replacing the normal background colour.
39 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 While the full power of Perl is available, the operators have been
45 designed to be as simple as possible.
46 For example, to load an image and scale it to the window size, you
48 would use:
49 urxvt --background-expr 'scale keep { load "/path/to/mybg.png" }'
51 Or specified as a X resource:
53 URxvt.background.expr: scale keep { load "/path/to/mybg.png" }
55
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 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 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 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 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 EXPRESSIONS
83 Expressions are normal Perl expressions, in fact, they are Perl blocks
84 - which means you could use multiple lines and statements:
85 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 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 Fortunately, we expect that most expressions will be much simpler, with
100 little Perl knowledge needed.
101 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 load "$HOME/mypic.png"
107 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 Then you prepend one or more modifiers or filtering expressions, such
113 as "scale":
114 scale load "$HOME/mypic.png"
116 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 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 scale 2, load "$HOME/mypic.png"
128 This enlarges the image by a factor of 2 (200%). As you can see,
130 "scale" has now two arguments, the 2 and the "load" expression, while
131 "load" only has one argument. Arguments are separated from each other
132 by commas.
133 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 scale 0.5, 2, load "$HOME/mypic.png"
139 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 scale 0.5, 2, keep { load "$HOME/mypic.png" }
147 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 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 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 tile keep { load "$HOME/mypic.png" }
162 In fact, images returned by "load" are in "tile" mode by default, so
164 the "tile" operator is kind of superfluous.
165 Another common effect is to mirror the image, so that the same edges
167 touch:
168 mirror keep { load "$HOME/mypic.png" }
170 Another common background expression is:
172 rootalign root
174 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 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 "red" # named colour
187 "#f00" # simple rgb
188 "[50]red" # red with 50% alpha
189 "TekHVC:300/50/50" # anything goes
190 OR as an array reference with one, three or four components:
192 [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 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 "keep { ... }" caching
205 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 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 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 "keep" is most useful for expensive operations, such as "blur":
223 rootalign keep { blur 20, root }
225 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 "load" caching
233 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 That means that this expression:
239 keep { load "$HOME/path..." }
241 Not only caches the image in memory, other terminal instances that try
243 to "load" it can reuse that in-memory copy.
244
246 COMMAND LINE SWITCHES
247 --background-expr perl-expression
248 Specifies the Perl expression to evaluate.
249 --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 Specifying this flag changes the behaviour, so that the image only
256 replaces the background of the character area.
257 --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 If you want to do updates more often, you can decrease this safety
265 interval with this switch.
266 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 load $path
273 Loads the image at the given $path. The image is set to plane
274 tiling mode.
275 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 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 root
285 Returns the root window pixmap, that is, hopefully, the background
286 image of your screen.
287 This function makes your expression root sensitive, that means it
289 will be reevaluated when the bg image changes.
290 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 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 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 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 This function is called automatically when an expression returns
310 multiple images.
311 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 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 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 tile load "mybg.png"
327 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 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 mirror load "mybg.png"
339 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 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 pad load "mybg.png"
351 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 Example: just for curiosity, how does this pixel extension stuff
359 work?
360 extend move 50, 50, load "mybg.png"
362 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 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 Using these functions makes your expression sensitive to window
376 moves.
377 These functions are mainly useful to align images to the root
379 window.
380 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 move -TX, -TY, keep { load "mybg.png" }
385 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 Using these functions makes your expression sensitive to window
392 resizes.
393 These functions are mainly useful to scale images, or to clip
395 images to the window size to conserve memory.
396 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 clip move -TX, -TY, keep { blur 5, root }
402 FOCUS
404 Returns a boolean indicating whether the terminal window has
405 keyboard focus, in which case it returns true.
406 Using this function makes your expression sensitive to focus
408 changes.
409 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 Example: use two entirely different background images, depending on
416 whether the window has focus.
417 FOCUS ? keep { load "has_focus.jpg" } : keep { load "no_focus.jpg" }
419 now Returns the current time as (fractional) seconds since the epoch.
421 Using this expression does not make your expression sensitive to
423 time, but the next two functions do.
424 again $seconds
426 When this function is used the expression will be reevaluated again
427 in $seconds seconds.
428 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 again 60;
434 rotate 50, 50, (now % 86400) * -72 / 8640, scale keep { load "myclock.png" }
435 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 SHAPE CHANGING OPERATORS
442 The following operators modify the shape, size or position of the
443 image.
444 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 If $x and $y are missing, then 0 is assumed for both.
454 If $width and $height are missing, then the window size will be
456 assumed.
457 Example: load an image, blur it, and clip it to the window size to
459 save memory.
460 clip keep { blur 10, load "mybg.png" }
462 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 If only one factor is given, it is used for both directions.
470 If no factors are given, scales the image to the window size
472 without keeping aspect.
473 resize $width, $height, $img
475 Resizes the image to exactly $width times $height pixels.
476 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 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 move $dx, $dy, $img
491 Moves the image by $dx pixels in the horizontal, and $dy pixels in
492 the vertical.
493 Example: move the image right by 20 pixels and down by 30.
495 move 20, 30, ...
497 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 Example: remove any visible border around an image, center it
504 vertically but move it to the right hand side.
505 align 1, 0.5, pad $img
507 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 Example: load an image and center it.
515 center keep { pad load "mybg.png" }
517 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 Example: load a background image, put it in mirror mode and root
525 align it.
526 rootalign keep { mirror load "mybg.png" }
528 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 rootalign root
534 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 Example: rotate the image by 90 degrees around its center.
541 rotate 0.5, 0.5, 90, keep { load "$HOME/mybg.png" }
543 COLOUR MODIFICATIONS
545 The following operators change the pixels of the image.
546 tint $color, $img
548 Tints the image in the given colour.
549 Example: tint the image red.
551 tint "red", load "rgb.png"
553 Example: the same, but specify the colour by component.
555 tint [1, 0, 0], load "rgb.png"
557 shade $factor, $img
559 Shade the image by the given factor.
560 contrast $factor, $img
562 contrast $r, $g, $b, $img
563 contrast $r, $g, $b, $a, $img
564 Adjusts the contrast of an image.
565 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 Values from 0 to 1 lower the contrast, values higher than 1
571 increase the contrast.
572 Due to limitations in the underlying XRender extension, lowering
574 contrast also reduces brightness, while increasing contrast
575 currently also increases brightness.
576 brightness $bias, $img
578 brightness $r, $g, $b, $img
579 brightness $r, $g, $b, $a, $img
580 Adjusts the brightness of an image.
581 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 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 Due to idiosyncrasies in the underlying XRender extension, biases
591 less than zero can be very slow.
592 You can also try the experimental(!) "muladd" operator.
594 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 Due to numerous bugs in XRender implementations, it can also
601 introduce a number of visual artifacts.
602 Example: increase contrast by a factor of $c without changing image
604 brightness too much.
605 muladd $c, (1 - $c) * 0.5, $img
607 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 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 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 Example: do the right thing when focus fading is requested.
628 focus_fade load "mybg.jpg";
630 OTHER STUFF
632 Anything that didn't fit any of the other categories, even after
633 applying force and closing our eyes.
634 keep { ... }
636 This operator takes a code block as argument, that is, one or more
637 statements enclosed by braces.
638 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 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 Another example is "load", which can be quite slow.
651 In fact, urxvt itself encloses the whole expression in some kind of
653 "keep" block so it only is reevaluated as required.
654 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 rootalign keep { blur 10, root }
660 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
668 This extension also provides support for the old options/resources and
669 OSC sequences for setting a background image. These settings are
670 deprecated and will be removed in future versions.
671 OPTIONS AND RESOURCES
673 -pixmap file[;oplist]
674 backgroundPixmap: file[;oplist]
675 Use the specified image file as the window's background and also
676 optionally specify a colon separated list of operations to modify
677 it. Note that you may need to quote the ";" character when using
678 the command line option, as ";" is usually a metacharacter in
679 shells. Supported operations are:
680 WxH+X+Y
682 sets scale and position. "W" / "H" specify the
683 horizontal/vertical scale (percent), and "X" / "Y" locate the
684 image centre (percent). A scale of 0 disables scaling.
685 op=tile
687 enables tiling
688 op=keep-aspect
690 maintain the image aspect ratio when scaling
691 op=root-align
693 use the position of the terminal window relative to the root
694 window as the image offset, simulating a root window background
695 The default scale and position setting is "100x100+50+50".
697 Alternatively, a predefined set of templates can be used to achieve
698 the most common setups:
699 style=tiled
701 the image is tiled with no scaling. Equivalent to
702 0x0+0+0:op=tile
703 style=aspect-stretched
705 the image is scaled to fill the whole window maintaining the
706 aspect ratio and centered. Equivalent to
707 100x100+50+50:op=keep-aspect
708 style=stretched
710 the image is scaled to fill the whole window. Equivalent to
711 100x100
712 style=centered
714 the image is centered with no scaling. Equivalent to 0x0+50+50
715 style=root-tiled
717 the image is tiled with no scaling and using 'root'
718 positioning. Equivalent to 0x0:op=tile:op=root-align
719 If multiple templates are specified the last one wins. Note that a
721 template overrides all the scale, position and operations settings.
722 If used in conjunction with pseudo-transparency, the specified
724 image will be blended over the transparent background using alpha-
725 blending.
726 -tr|+tr
728 transparent: boolean
729 Turn on/off pseudo-transparency by using the root pixmap as
730 background.
731 -tint colour
733 tintColor: colour
734 Tint the transparent background with the given colour. Note that a
735 black tint yields a completely black image while a white tint
736 yields the image unchanged.
737 -sh number
739 shading: number
740 Darken (0 .. 99) or lighten (101 .. 200) the transparent
741 background. A value of 100 means no shading.
742 -blr HxV
744 blurRadius: HxV
745 Apply gaussian blur with the specified radius to the transparent
746 background. If a single number is specified, the vertical and
747 horizontal radii are considered to be the same. Setting one of the
748 radii to 1 and the other to a large number creates interesting
749 effects on some backgrounds. The maximum radius value is 128. An
750 horizontal or vertical radius of 0 disables blurring.
751 OSC sequences
753 This extension will react to the following OSC sequences. Note that
754 this extension will not be autoloaded when these are used currently, so
755 to make urxvt recognize them, you have to enable the "background"
756 extension. One way to achieve that is to use the "--background-expr ''"
757 command line argument or by specifying an empty
758 "URxvt.background.expr:"> resource.
759 "ESC ] 705 ; Pt ST" Change transparent background tint colour to "Pt".
761 "ESC ] 20 ; Pt ST" Change/Query background image parameters: the value
762 of "Pt" can be one of the following commands:
763 "?" display scale and position in the title
764 ";WxH+X+Y"
766 change scale and/or position
767 "FILE;WxH+X+Y"
769 change background image
7709.31 2023-01-21 urxvt-background(1)