ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/rxvt-unicode/src/perl/background
(Generate patch)

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.71 by root, Mon Jul 2 01:40:41 2012 UTC vs.
Revision 1.108 by root, Tue Nov 29 05:45:43 2022 UTC

1#! perl 1#! perl
2 2
3#:META:X_RESOURCE:%.expr:string:background expression 3#:META:RESOURCE:%.expr:string:background expression
4#:META:X_RESOURCE:%.border:boolean:respect the terminal border 4#:META:RESOURCE:%.border:boolean:respect the terminal border
5#:META:X_RESOURCE:%.interval:seconds:minimum time between updates 5#:META:RESOURCE:%.interval:seconds:minimum time between updates
6#:META:RESOURCE:pixmap:file[;geom]:set image as background
7#:META:RESOURCE:backgroundPixmap:file[;geom]:set image as background
8#:META:RESOURCE:tr:boolean:set root pixmap as background
9#:META:RESOURCE:transparent:boolean:set root pixmap as background
10#:META:RESOURCE:tint:color:tint background with color
11#:META:RESOURCE:tintColor:color:tint background with color
12#:META:RESOURCE:sh:number:shade background by number %
13#:META:RESOURCE:shading:number:shade background by number %
14#:META:RESOURCE:blr:HxV:gaussian-blur background with radii
15#:META:RESOURCE:blurRadius:HxV:gaussian-blur background with radii
16#:META:OSC:20:change/query background image
17#:META:OSC:705:change transparent background tint colour
6 18
7=head1 NAME 19=head1 NAME
8 20
9 background - manage terminal background 21background - manage terminal background
10 22
11=head1 SYNOPSIS 23=head1 SYNOPSIS
12 24
13 urxvt --background-expr 'background expression' 25 urxvt --background-expr 'background expression'
14 --background-border 26 --background-border
15 --background-interval seconds 27 --background-interval seconds
16 28
29=head1 QUICK AND DIRTY CHEAT SHEET
30
31Load a random jpeg image and tile the background with it without scaling
32or anything else:
33
34 load "/path/to/img.jpg"
35
36The same, but use mirroring/reflection instead of tiling:
37
38 mirror load "/path/to/img.jpg"
39
40Load an image and scale it to exactly fill the terminal window:
41
42 scale keep { load "/path/to/img.jpg" }
43
44Implement pseudo-transparency by using a suitably-aligned root pixmap
45as window background:
46
47 rootalign root
48
49Likewise, but keep a blurred copy:
50
51 rootalign keep { blur 10, root }
52
17=head1 DESCRIPTION 53=head1 DESCRIPTION
18 54
19This extension manages the terminal background by creating a picture that 55This extension manages the terminal background by creating a picture that
20is behind the text, replacing the normal background colour. 56is behind the text, replacing the normal background colour.
21 57
22It does so by evaluating a Perl expression that I<calculates> the image on 58It does so by evaluating a Perl expression that I<calculates> the image on
23the fly, for example, by grabbing the root background or loading a file. 59the fly, for example, by grabbing the root background or loading a file.
24 60
25While the full power of Perl is available, the operators have been design 61While the full power of Perl is available, the operators have been
26to be as simple as possible. 62designed to be as simple as possible.
27 63
28For example, to load an image and scale it to the window size, you would 64For example, to load an image and scale it to the window size, you would
29use: 65use:
30 66
31 urxvt --background-expr 'scale keep { load "/path/to/mybg.png" }' 67 urxvt --background-expr 'scale keep { load "/path/to/mybg.png" }'
32 68
33Or specified as a X resource: 69Or specified as a X resource:
34 70
35 URxvt.background-expr: scale keep { load "/path/to/mybg.png" } 71 URxvt.background.expr: scale keep { load "/path/to/mybg.png" }
36 72
37=head1 THEORY OF OPERATION 73=head1 THEORY OF OPERATION
38 74
39At startup, just before the window is mapped for the first time, the 75At startup, just before the window is mapped for the first time, the
40expression is evaluated and must yield an image. The image is then 76expression is evaluated and must yield an image. The image is then
74 return load "$HOME/sunday.png"; 110 return load "$HOME/sunday.png";
75 } 111 }
76 } 112 }
77 113
78This inner expression is evaluated once per hour (and whenever the 114This inner expression is evaluated once per hour (and whenever the
79temrinal window is resized). It sets F<sunday.png> as background on 115terminal window is resized). It sets F<sunday.png> as background on
80Sundays, and F<weekday.png> on all other days. 116Sundays, and F<weekday.png> on all other days.
81 117
82Fortunately, we expect that most expressions will be much simpler, with 118Fortunately, we expect that most expressions will be much simpler, with
83little Perl knowledge needed. 119little Perl knowledge needed.
84 120
108get a percentage): 144get a percentage):
109 145
110 scale 2, load "$HOME/mypic.png" 146 scale 2, load "$HOME/mypic.png"
111 147
112This enlarges the image by a factor of 2 (200%). As you can see, C<scale> 148This enlarges the image by a factor of 2 (200%). As you can see, C<scale>
113has now two arguments, the C<200> and the C<load> expression, while 149has now two arguments, the C<2> and the C<load> expression, while
114C<load> only has one argument. Arguments are separated from each other by 150C<load> only has one argument. Arguments are separated from each other by
115commas. 151commas.
116 152
117Scale also accepts two arguments, which are then separate factors for both 153Scale also accepts two arguments, which are then separate factors for both
118horizontal and vertical dimensions. For example, this halves the image 154horizontal and vertical dimensions. For example, this halves the image
119width and doubles the image height: 155width and doubles the image height:
120 156
121 scale 0.5, 2, load "$HOME/mypic.png" 157 scale 0.5, 2, load "$HOME/mypic.png"
122 158
123IF you try out these expressions, you might suffer from some sluggishness, 159IF you try out these expressions, you might suffer from some sluggishness,
124because each time the terminal is resized, it loads the PNG image agin 160because each time the terminal is resized, it loads the PNG image again
125and scales it. Scaling is usually fast (and unavoidable), but loading the 161and scales it. Scaling is usually fast (and unavoidable), but loading the
126image can be quite time consuming. This is where C<keep> comes in handy: 162image can be quite time consuming. This is where C<keep> comes in handy:
127 163
128 scale 0.5, 2, keep { load "$HOME/mypic.png" } 164 scale 0.5, 2, keep { load "$HOME/mypic.png" }
129 165
159left corner of the terminal window)- the result is pseudo-transparency: 195left corner of the terminal window)- the result is pseudo-transparency:
160the image seems to be static while the window is moved around. 196the image seems to be static while the window is moved around.
161 197
162=head2 COLOUR SPECIFICATIONS 198=head2 COLOUR SPECIFICATIONS
163 199
164Whenever an oprator expects a "colour", then this can be specified in one 200Whenever an operator expects a "colour", then this can be specified in one
165of two ways: Either as string with an X11 colour specification, such as: 201of two ways: Either as string with an X11 colour specification, such as:
166 202
167 "red" # named colour 203 "red" # named colour
168 "#f00" # simple rgb 204 "#f00" # simple rgb
169 "[50]red" # red with 50% alpha 205 "[50]red" # red with 50% alpha
225 261
226=head1 REFERENCE 262=head1 REFERENCE
227 263
228=head2 COMMAND LINE SWITCHES 264=head2 COMMAND LINE SWITCHES
229 265
230=over 4 266=over
231 267
232=item --background-expr perl-expression 268=item --background-expr perl-expression
233 269
234Specifies the Perl expression to evaluate. 270Specifies the Perl expression to evaluate.
235 271
255=cut 291=cut
256 292
257our %_IMG_CACHE; 293our %_IMG_CACHE;
258our $HOME; 294our $HOME;
259our ($self, $frame); 295our ($self, $frame);
260our ($x, $y, $w, $h); 296our ($x, $y, $w, $h, $focus);
261 297
262# enforce at least this interval between updates 298# enforce at least this interval between updates
263our $MIN_INTERVAL = 6/59.951; 299our $MIN_INTERVAL = 6/59.951;
264 300
265{ 301{
276 312
277These functions provide an image, by loading it from disk, grabbing it 313These functions provide an image, by loading it from disk, grabbing it
278from the root screen or by simply generating it. They are used as starting 314from the root screen or by simply generating it. They are used as starting
279points to get an image you can play with. 315points to get an image you can play with.
280 316
281=over 4 317=over
282 318
283=item load $path 319=item load $path
284 320
285Loads the image at the given C<$path>. The image is set to plane tiling 321Loads the image at the given C<$path>. The image is set to plane tiling
286mode. 322mode.
287 323
288If the image is already in memory (e.g. because another terminal instance 324If the image is already in memory (e.g. because another terminal instance
289uses it), then the in-memory copy us returned instead. 325uses it), then the in-memory copy is returned instead.
290 326
291=item load_uc $path 327=item load_uc $path
292 328
293Load uncached - same as load, but does not cache the image, which means it 329Load uncached - same as load, but does not cache the image, which means it
294is I<always> loaded from the filesystem again. 330is I<always> loaded from the filesystem again, even if another copy of it
331is in memory at the time.
295 332
296=cut 333=cut
334
335 sub load_uc($) {
336 $self->new_img_from_file ($_[0])
337 }
297 338
298 sub load($) { 339 sub load($) {
299 my ($path) = @_; 340 my ($path) = @_;
300 341
301 $_IMG_CACHE{$path} || do { 342 $_IMG_CACHE{$path} || do {
302 my $img = $self->new_img_from_file ($path); 343 my $img = load_uc $path;
303 Scalar::Util::weaken ($_IMG_CACHE{$path} = $img); 344 Scalar::Util::weaken ($_IMG_CACHE{$path} = $img);
304 $img 345 $img
305 } 346 }
306 } 347 }
307 348
393 for @_; 434 for @_;
394 435
395 $base 436 $base
396 } 437 }
397 438
439=back
440
398=head2 TILING MODES 441=head2 TILING MODES
399 442
400The following operators modify the tiling mode of an image, that is, the 443The following operators modify the tiling mode of an image, that is, the
401way that pixels outside the image area are painted when the image is used. 444way that pixels outside the image area are painted when the image is used.
402 445
403=over 4 446=over
404 447
405=item tile $img 448=item tile $img
406 449
407Tiles the whole plane with the image and returns this new image - or in 450Tiles the whole plane with the image and returns this new image - or in
408other words, it returns a copy of the image in plane tiling mode. 451other words, it returns a copy of the image in plane tiling mode.
483dimensions. They are not (Perl-) variables, they just return stuff that 526dimensions. They are not (Perl-) variables, they just return stuff that
484varies. Most of them make your expression sensitive to some events, for 527varies. Most of them make your expression sensitive to some events, for
485example using C<TW> (terminal width) means your expression is evaluated 528example using C<TW> (terminal width) means your expression is evaluated
486again when the terminal is resized. 529again when the terminal is resized.
487 530
488=over 4 531=over
489 532
490=item TX 533=item TX
491 534
492=item TY 535=item TY
493 536
494Return the X and Y coordinates of the terminal window (the terminal 537Return the X and Y coordinates of the terminal window (the terminal
495window is the full window by default, and the character area only when in 538window is the full window by default, and the character area only when in
496border-respect mode). 539border-respect mode).
497 540
498Using these functions make your expression sensitive to window moves. 541Using these functions makes your expression sensitive to window moves.
499 542
500These functions are mainly useful to align images to the root window. 543These functions are mainly useful to align images to the root window.
501 544
502Example: load an image and align it so it looks as if anchored to the 545Example: load an image and align it so it looks as if anchored to the
503background (that's exactly what C<rootalign> does btw.): 546background (that's exactly what C<rootalign> does btw.):
504 547
505 move -TX, -TY, keep { load "mybg.png" } 548 move -TX, -TY, keep { load "mybg.png" }
506 549
507=item TW 550=item TW
551
552=item TH
508 553
509Return the width (C<TW>) and height (C<TH>) of the terminal window (the 554Return the width (C<TW>) and height (C<TH>) of the terminal window (the
510terminal window is the full window by default, and the character area only 555terminal window is the full window by default, and the character area only
511when in border-respect mode). 556when in border-respect mode).
512 557
513Using these functions make your expression sensitive to window resizes. 558Using these functions makes your expression sensitive to window resizes.
514 559
515These functions are mainly useful to scale images, or to clip images to 560These functions are mainly useful to scale images, or to clip images to
516the window size to conserve memory. 561the window size to conserve memory.
517 562
518Example: take the screen background, clip it to the window size, blur it a 563Example: take the screen background, clip it to the window size, blur it a
519bit, align it to the window position and use it as background. 564bit, align it to the window position and use it as background.
520 565
521 clip move -TX, -TY, keep { blur 5, root } 566 clip move -TX, -TY, keep { blur 5, root }
522 567
523=cut 568=item FOCUS
524 569
570Returns a boolean indicating whether the terminal window has keyboard
571focus, in which case it returns true.
572
573Using this function makes your expression sensitive to focus changes.
574
575A common use case is to fade the background image when the terminal loses
576focus, often together with the C<-fade> command line option. In fact,
577there is a special function for just that use case: C<focus_fade>.
578
579Example: use two entirely different background images, depending on
580whether the window has focus.
581
582 FOCUS ? keep { load "has_focus.jpg" } : keep { load "no_focus.jpg" }
583
584=cut
585
525 sub TX() { $frame->[FR_AGAIN]{position} = 1; $x } 586 sub TX () { $frame->[FR_AGAIN]{position} = 1; $x }
526 sub TY() { $frame->[FR_AGAIN]{position} = 1; $y } 587 sub TY () { $frame->[FR_AGAIN]{position} = 1; $y }
527 sub TW() { $frame->[FR_AGAIN]{size} = 1; $w } 588 sub TW () { $frame->[FR_AGAIN]{size} = 1; $w }
528 sub TH() { $frame->[FR_AGAIN]{size} = 1; $h } 589 sub TH () { $frame->[FR_AGAIN]{size} = 1; $h }
590 sub FOCUS() { $frame->[FR_AGAIN]{focus} = 1; $focus }
529 591
530=item now 592=item now
531 593
532Returns the current time as (fractional) seconds since the epoch. 594Returns the current time as (fractional) seconds since the epoch.
533 595
567 629
568=head2 SHAPE CHANGING OPERATORS 630=head2 SHAPE CHANGING OPERATORS
569 631
570The following operators modify the shape, size or position of the image. 632The following operators modify the shape, size or position of the image.
571 633
572=over 4 634=over
573 635
574=item clip $img 636=item clip $img
575 637
576=item clip $width, $height, $img 638=item clip $width, $height, $img
577 639
580Clips an image to the given rectangle. If the rectangle is outside the 642Clips an image to the given rectangle. If the rectangle is outside the
581image area (e.g. when C<$x> or C<$y> are negative) or the rectangle is 643image area (e.g. when C<$x> or C<$y> are negative) or the rectangle is
582larger than the image, then the tiling mode defines how the extra pixels 644larger than the image, then the tiling mode defines how the extra pixels
583will be filled. 645will be filled.
584 646
585If C<$x> an C<$y> are missing, then C<0> is assumed for both. 647If C<$x> and C<$y> are missing, then C<0> is assumed for both.
586 648
587If C<$width> and C<$height> are missing, then the window size will be 649If C<$width> and C<$height> are missing, then the window size will be
588assumed. 650assumed.
589 651
590Example: load an image, blur it, and clip it to the window size to save 652Example: load an image, blur it, and clip it to the window size to save
608=item scale $width_factor, $height_factor, $img 670=item scale $width_factor, $height_factor, $img
609 671
610Scales the image by the given factors in horizontal 672Scales the image by the given factors in horizontal
611(C<$width>) and vertical (C<$height>) direction. 673(C<$width>) and vertical (C<$height>) direction.
612 674
613If only one factor is give, it is used for both directions. 675If only one factor is given, it is used for both directions.
614 676
615If no factors are given, scales the image to the window size without 677If no factors are given, scales the image to the window size without
616keeping aspect. 678keeping aspect.
617 679
618=item resize $width, $height, $img 680=item resize $width, $height, $img
743=item rotate $center_x, $center_y, $degrees, $img 805=item rotate $center_x, $center_y, $degrees, $img
744 806
745Rotates the image clockwise by C<$degrees> degrees, around the point at 807Rotates the image clockwise by C<$degrees> degrees, around the point at
746C<$center_x> and C<$center_y> (specified as factor of image width/height). 808C<$center_x> and C<$center_y> (specified as factor of image width/height).
747 809
748Example: rotate the image by 90 degrees around it's center. 810Example: rotate the image by 90 degrees around its center.
749 811
750 rotate 0.5, 0.5, 90, keep { load "$HOME/mybg.png" } 812 rotate 0.5, 0.5, 90, keep { load "$HOME/mybg.png" }
751 813
752=cut 814=cut
753 815
764 826
765=head2 COLOUR MODIFICATIONS 827=head2 COLOUR MODIFICATIONS
766 828
767The following operators change the pixels of the image. 829The following operators change the pixels of the image.
768 830
769=over 4 831=over
770 832
771=item tint $color, $img 833=item tint $color, $img
772 834
773Tints the image in the given colour. 835Tints the image in the given colour.
774 836
782 844
783=cut 845=cut
784 846
785 sub tint($$) { 847 sub tint($$) {
786 $_[1]->tint ($_[0]) 848 $_[1]->tint ($_[0])
849 }
850
851=item shade $factor, $img
852
853Shade the image by the given factor.
854
855=cut
856
857 sub shade($$) {
858 $_[1]->shade ($_[0])
787 } 859 }
788 860
789=item contrast $factor, $img 861=item contrast $factor, $img
790 862
791=item contrast $r, $g, $b, $img 863=item contrast $r, $g, $b, $img
822latter in a white picture. 894latter in a white picture.
823 895
824Due to idiosyncrasies in the underlying XRender extension, biases less 896Due to idiosyncrasies in the underlying XRender extension, biases less
825than zero can be I<very> slow. 897than zero can be I<very> slow.
826 898
899You can also try the experimental(!) C<muladd> operator.
900
827=cut 901=cut
828 902
829 sub contrast($$;$$;$) { 903 sub contrast($$;$$;$) {
830 my $img = pop; 904 my $img = pop;
831 my ($r, $g, $b, $a) = @_; 905 my ($r, $g, $b, $a) = @_;
846 $a = 1 if @_ < 4; 920 $a = 1 if @_ < 4;
847 921
848 $img = $img->clone; 922 $img = $img->clone;
849 $img->brightness ($r, $g, $b, $a); 923 $img->brightness ($r, $g, $b, $a);
850 $img 924 $img
925 }
926
927=item muladd $mul, $add, $img # EXPERIMENTAL
928
929First multiplies the pixels by C<$mul>, then adds C<$add>. This can be used
930to implement brightness and contrast at the same time, with a wider value
931range than contrast and brightness operators.
932
933Due to numerous bugs in XRender implementations, it can also introduce a
934number of visual artifacts.
935
936Example: increase contrast by a factor of C<$c> without changing image
937brightness too much.
938
939 muladd $c, (1 - $c) * 0.5, $img
940
941=cut
942
943 sub muladd($$$) {
944 $_[2]->muladd ($_[0], $_[1])
851 } 945 }
852 946
853=item blur $radius, $img 947=item blur $radius, $img
854 948
855=item blur $radius_horz, $radius_vert, $img 949=item blur $radius_horz, $radius_vert, $img
867 sub blur($$;$) { 961 sub blur($$;$) {
868 my $img = pop; 962 my $img = pop;
869 $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0]) 963 $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
870 } 964 }
871 965
966=item focus_fade $img
967
968=item focus_fade $factor, $img
969
970=item focus_fade $factor, $color, $img
971
972Fades the image by the given factor (and colour) when focus is lost (the
973same as the C<-fade>/C<-fadecolor> command line options, which also supply
974the default values for C<factor> and C<$color>. Unlike with C<-fade>, the
975C<$factor> is a real value, not a percentage value (that is, 0..1, not
9760..100).
977
978Example: do the right thing when focus fading is requested.
979
980 focus_fade load "mybg.jpg";
981
982=cut
983
984 sub focus_fade($;$$) {
985 my $img = pop;
986
987 return $img
988 if FOCUS;
989
990 my $fade = @_ >= 1 ? $_[0] : defined $self->resource ("fade") ? $self->resource ("fade") * 0.01 : 0;
991 my $color = @_ >= 2 ? $_[1] : $self->resource ("color+" . &urxvt::Color_fade ()); # Color_fade not always available
992
993 $img = $img->tint ($color) if $color ne "rgb:00/00/00";
994 $img = $img->muladd (1 - $fade, 0) if $fade;
995
996 $img
997 }
998
872=back 999=back
873 1000
874=head2 OTHER STUFF 1001=head2 OTHER STUFF
875 1002
876Anything that didn't fit any of the other categories, even after applying 1003Anything that didn't fit any of the other categories, even after applying
877force and closing our eyes. 1004force and closing our eyes.
878 1005
879=over 4 1006=over
880 1007
881=item keep { ... } 1008=item keep { ... }
882 1009
883This operator takes a code block as argument, that is, one or more 1010This operator takes a code block as argument, that is, one or more
884statements enclosed by braces. 1011statements enclosed by braces.
900C<keep> block so it only is reevaluated as required. 1027C<keep> block so it only is reevaluated as required.
901 1028
902Putting the blur into a C<keep> block will make sure the blur is only done 1029Putting the blur into a C<keep> block will make sure the blur is only done
903once, while the C<rootalign> is still done each time the window moves. 1030once, while the C<rootalign> is still done each time the window moves.
904 1031
905 rootlign keep { blur 10, root } 1032 rootalign keep { blur 10, root }
906 1033
907This leaves the question of how to force reevaluation of the block, 1034This leaves the question of how to force reevaluation of the block,
908in case the root background changes: If expression inside the block 1035in case the root background changes: If expression inside the block
909is sensitive to some event (root background changes, window geometry 1036is sensitive to some event (root background changes, window geometry
910changes), then it will be reevaluated automatically as needed. 1037changes), then it will be reevaluated automatically as needed.
1038
1039=back
1040
1041=head1 OLD BACKGROUND IMAGE SETTINGS
1042
1043This extension also provides support for the old options/resources and
1044OSC sequences for setting a background image. These settings are
1045B<deprecated> and will be removed in future versions.
1046
1047=head2 OPTIONS AND RESOURCES
1048
1049=over
1050
1051=item B<-pixmap> I<file[;oplist]>
1052
1053=item B<backgroundPixmap:> I<file[;oplist]>
1054
1055Use the specified image file as the window's background and also
1056optionally specify a colon separated list of operations to modify it.
1057Note that you may need to quote the C<;> character when using the
1058command line option, as C<;> is usually a metacharacter in shells.
1059Supported operations are:
1060
1061=over
1062
1063=item B<WxH+X+Y>
1064
1065sets scale and position. B<"W" / "H"> specify the horizontal/vertical
1066scale (percent), and B<"X" / "Y"> locate the image centre (percent). A
1067scale of 0 disables scaling.
1068
1069=item B<op=tile>
1070
1071enables tiling
1072
1073=item B<op=keep-aspect>
1074
1075maintain the image aspect ratio when scaling
1076
1077=item B<op=root-align>
1078
1079use the position of the terminal window relative to the root window as
1080the image offset, simulating a root window background
1081
1082=back
1083
1084The default scale and position setting is C<100x100+50+50>.
1085Alternatively, a predefined set of templates can be used to achieve
1086the most common setups:
1087
1088=over
1089
1090=item B<style=tiled>
1091
1092the image is tiled with no scaling. Equivalent to 0x0+0+0:op=tile
1093
1094=item B<style=aspect-stretched>
1095
1096the image is scaled to fill the whole window maintaining the aspect
1097ratio and centered. Equivalent to 100x100+50+50:op=keep-aspect
1098
1099=item B<style=stretched>
1100
1101the image is scaled to fill the whole window. Equivalent to 100x100
1102
1103=item B<style=centered>
1104
1105the image is centered with no scaling. Equivalent to 0x0+50+50
1106
1107=item B<style=root-tiled>
1108
1109the image is tiled with no scaling and using 'root' positioning.
1110Equivalent to 0x0:op=tile:op=root-align
1111
1112=back
1113
1114If multiple templates are specified the last one wins. Note that a
1115template overrides all the scale, position and operations settings.
1116
1117If used in conjunction with pseudo-transparency, the specified image
1118will be blended over the transparent background using alpha-blending.
1119
1120=item B<-tr>|B<+tr>
1121
1122=item B<transparent:> I<boolean>
1123
1124Turn on/off pseudo-transparency by using the root pixmap as background.
1125
1126=item B<-tint> I<colour>
1127
1128=item B<tintColor:> I<colour>
1129
1130Tint the transparent background with the given colour. Note that a
1131black tint yields a completely black image while a white tint yields
1132the image unchanged.
1133
1134=item B<-sh> I<number>
1135
1136=item B<shading:> I<number>
1137
1138Darken (0 .. 99) or lighten (101 .. 200) the transparent background.
1139A value of 100 means no shading.
1140
1141=item B<-blr> I<HxV>
1142
1143=item B<blurRadius:> I<HxV>
1144
1145Apply gaussian blur with the specified radius to the transparent
1146background. If a single number is specified, the vertical and
1147horizontal radii are considered to be the same. Setting one of the
1148radii to 1 and the other to a large number creates interesting effects
1149on some backgrounds. The maximum radius value is 128. An horizontal or
1150vertical radius of 0 disables blurring.
1151
1152=back
1153
1154=head2 OSC sequences
1155
1156This extension will react to the following OSC sequences. Note that
1157this extension will not be autoloaded when these are used currently,
1158so to make urxvt recognize them, you have to enable the C<background>
1159extension. One way to achieve that is to use the C<--background-expr ''>
1160command line argument or by specifying an empty C<URxvt.background.expr:>>
1161resource.
1162
1163=over
1164
1165=item B<< C<ESC ] 705 ; Pt ST> >> Change transparent background tint colour to B<< C<Pt> >>.
1166
1167=item B<< C<ESC ] 20 ; Pt ST> >> Change/Query background image
1168parameters: the value of B<< C<Pt> >> can be one of the following
1169commands:
1170
1171=over
1172
1173=item B<< C<?> >>
1174
1175display scale and position in the title
1176
1177=item B<< C<;WxH+X+Y> >>
1178
1179change scale and/or position
1180
1181=item B<< C<FILE;WxH+X+Y> >>
1182
1183change background image
1184
1185=back
911 1186
912=cut 1187=cut
913 1188
914 sub keep(&) { 1189 sub keep(&) {
915 my $id = $_[0]+0; 1190 my $id = $_[0]+0;
948=cut 1223=cut
949 1224
950} 1225}
951 1226
952sub parse_expr { 1227sub parse_expr {
1228 my ($expr) = @_;
1229
1230 # an empty expression is valid and represents the default background
1231 if ($expr !~ /\S/) {
1232 $expr = sub {
1233 undef
1234 };
1235 } else {
953 my $expr = eval 1236 $expr = eval
954 "sub {\n" 1237 "sub {\n"
955 . "package urxvt::bgdsl;\n" 1238 . "package urxvt::bgdsl;\n"
956 . "#line 0 'background expression'\n" 1239 . "#line 0 'background expression'\n"
957 . "$_[0]\n" 1240 . "$expr\n"
958 . "}"; 1241 . "}";
959 die if $@; 1242 die if $@;
1243 }
1244
960 $expr 1245 $expr
961} 1246}
962 1247
963# compiles a parsed expression 1248# compiles a parsed expression
964sub set_expr { 1249sub set_expr {
965 my ($self, $expr) = @_; 1250 my ($self, $expr) = @_;
966 1251
967 $self->{root} = []; 1252 $self->{root} = []; # the outermost frame
968 $self->{expr} = $expr; 1253 $self->{expr} = $expr;
969 $self->recalculate; 1254 $self->recalculate;
970} 1255}
971 1256
972# takes a hash of sensitivity indicators and installs watchers 1257# takes a hash of sensitivity indicators and installs watchers
1013 if ($again->{rootpmap}) { 1298 if ($again->{rootpmap}) {
1014 $state->{rootpmap} = $self->on (rootpmap_change => $cb); 1299 $state->{rootpmap} = $self->on (rootpmap_change => $cb);
1015 } else { 1300 } else {
1016 delete $state->{rootpmap}; 1301 delete $state->{rootpmap};
1017 } 1302 }
1303
1304 if ($again->{focus}) {
1305 $state->{focus} = $self->on (focus_in => $cb, focus_out => $cb);
1306 } else {
1307 delete $state->{focus};
1308 }
1018} 1309}
1019 1310
1020# evaluate the current bg expression 1311# evaluate the current bg expression
1021sub recalculate { 1312sub recalculate {
1022 my ($arg_self) = @_; 1313 my ($arg_self) = @_;
1030 return; 1321 return;
1031 } 1322 }
1032 1323
1033 $arg_self->{next_refresh} = urxvt::NOW + $MIN_INTERVAL; 1324 $arg_self->{next_refresh} = urxvt::NOW + $MIN_INTERVAL;
1034 1325
1326 unless ($arg_self->has_render) {
1327 warn "background extension needs RENDER extension 0.11 or higher, ignoring background-expr.\n";
1328 return;
1329 }
1330
1035 # set environment to evaluate user expression 1331 # set environment to evaluate user expression
1036 1332
1037 local $self = $arg_self; 1333 local $self = $arg_self;
1038 local $HOME = $ENV{HOME}; 1334 local $HOME = $ENV{HOME};
1039 local $frame = []; 1335 local $frame = $self->{root};
1040 1336
1041 ($x, $y, $w, $h) = $self->background_geometry ($self->{border}); 1337 ($x, $y, $w, $h) = $self->background_geometry ($self->{border});
1338 $focus = $self->focus;
1042 1339
1043 # evaluate user expression 1340 # evaluate user expression
1044 1341
1045 my @img = eval { $self->{expr}->() }; 1342 my @img = eval { $self->{expr}->() };
1046 die $@ if $@; 1343 die $@ if $@;
1047 die "background-expr did not return anything.\n" unless @img; 1344 die "background-expr did not return anything.\n" unless @img;
1345
1346 if ($img[0]) {
1048 die "background-expr: expected image(s), got something else.\n" 1347 die "background-expr: expected image(s), got something else.\n"
1049 if grep { !UNIVERSAL::isa $_, "urxvt::img" } @img; 1348 if grep { !UNIVERSAL::isa $_, "urxvt::img" } @img;
1050 1349
1051 my $img = urxvt::bgdsl::merge @img; 1350 my $img = urxvt::bgdsl::merge @img;
1052 1351
1053 $frame->[FR_AGAIN]{size} = 1 1352 $frame->[urxvt::bgdsl::FR_AGAIN]{size} = 1
1054 if $img->repeat_mode != urxvt::RepeatNormal; 1353 if $img->repeat_mode != urxvt::RepeatNormal;
1055 1354
1056 # if the expression is sensitive to external events, prepare reevaluation then 1355 # if the expression is sensitive to external events, prepare reevaluation then
1057 $self->compile_frame ($frame, sub { $arg_self->recalculate }); 1356 $self->compile_frame ($frame, sub { $arg_self->recalculate });
1058 1357
1059 # clear stuff we no longer need 1358 # clear stuff we no longer need
1060 1359
1061# unless (%{ $frame->[FR_STATE] }) { 1360# unless (%{ $frame->[FR_STATE] }) {
1062# delete $self->{state}; 1361# delete $self->{state};
1063# delete $self->{expr}; 1362# delete $self->{expr};
1064# } 1363# }
1065 1364
1066 # set background pixmap 1365 # set background pixmap
1067 1366
1068 $self->set_background ($img, $self->{border}); 1367 $self->set_background ($img, $self->{border});
1368 } else {
1369 $self->clr_background;
1370 }
1371
1069 $self->scr_recolour (0); 1372 $self->scr_recolor (0);
1070 $self->want_refresh; 1373 $self->want_refresh;
1071} 1374}
1072 1375
1376sub old_bg_opts {
1377 my ($self, $arg) = @_;
1378
1379 $arg or return;
1380
1381 my @str = split /;/, $arg;
1382
1383 return unless $str[0] or $self->{bg_opts}->{path};
1384
1385 my $bg_opts = $self->{bg_opts};
1386
1387 if ($str[0]) {
1388 $bg_opts->{tile} = 0;
1389 $bg_opts->{keep_aspect} = 0;
1390 $bg_opts->{root_align} = 0;
1391 $bg_opts->{h_scale} = $bg_opts->{v_scale} = 100;
1392 $bg_opts->{h_align} = $bg_opts->{v_align} = 50;
1393 $bg_opts->{path} = $str[0];
1394 }
1395
1396 my @oplist = split /:/, $str[1];
1397
1398 for (@oplist) {
1399 if (/style=tiled/i) {
1400 $bg_opts->{tile} = 1;
1401 $bg_opts->{keep_aspect} = 0;
1402 $bg_opts->{root_align} = 0;
1403 $bg_opts->{h_scale} = $bg_opts->{v_scale} = 0;
1404 $bg_opts->{h_align} = $bg_opts->{v_align} = 0;
1405 } elsif (/style=aspect-stretched/i) {
1406 $bg_opts->{tile} = 0;
1407 $bg_opts->{keep_aspect} = 1;
1408 $bg_opts->{root_align} = 0;
1409 $bg_opts->{h_scale} = $bg_opts->{v_scale} = 100;
1410 $bg_opts->{h_align} = $bg_opts->{v_align} = 50;
1411 } elsif (/style=stretched/i) {
1412 $bg_opts->{tile} = 0;
1413 $bg_opts->{keep_aspect} = 0;
1414 $bg_opts->{root_align} = 0;
1415 $bg_opts->{h_scale} = $bg_opts->{v_scale} = 100;
1416 $bg_opts->{h_align} = $bg_opts->{v_align} = 50;
1417 } elsif (/style=centered/i) {
1418 $bg_opts->{tile} = 0;
1419 $bg_opts->{keep_aspect} = 0;
1420 $bg_opts->{root_align} = 0;
1421 $bg_opts->{h_scale} = $bg_opts->{v_scale} = 0;
1422 $bg_opts->{h_align} = $bg_opts->{v_align} = 50;
1423 } elsif (/style=root-tiled/i) {
1424 $bg_opts->{tile} = 1;
1425 $bg_opts->{keep_aspect} = 0;
1426 $bg_opts->{root_align} = 1;
1427 $bg_opts->{h_scale} = $bg_opts->{v_scale} = 0;
1428 $bg_opts->{h_align} = $bg_opts->{v_align} = 0;
1429 } elsif (/op=tile/i) {
1430 $bg_opts->{tile} = 1;
1431 } elsif (/op=keep-aspect/i) {
1432 $bg_opts->{keep_aspect} = 1;
1433 } elsif (/op=root-align/i) {
1434 $bg_opts->{root_align} = 1;
1435 } elsif (/^ =? ([0-9]+)? (?:[xX] ([0-9]+))? ([+-][0-9]+)? ([+-][0-9]+)? $/x) {
1436 my ($w, $h, $x, $y) = ($1, $2, $3, $4);
1437
1438 if ($str[0]) {
1439 $w = $h unless defined $w;
1440 $h = $w unless defined $h;
1441 $y = $x unless defined $y;
1442 }
1443
1444 $bg_opts->{h_scale} = $w if defined $w;
1445 $bg_opts->{v_scale} = $h if defined $h;
1446 $bg_opts->{h_align} = $x if defined $x;
1447 $bg_opts->{v_align} = $y if defined $y;
1448 }
1449 }
1450}
1451
1452# helper function, quote string as perl without allowing
1453# any code execution or other shenanigans.
1454sub q0 {
1455 "qq\x00\Q$_\E\x00"
1456}
1457
1458sub old_bg_expr {
1459 my ($self) = @_;
1460
1461 my $expr;
1462
1463 my $bg_opts = $self->{bg_opts};
1464
1465 if ($bg_opts->{root} =~ /^\s*(?:true|yes|on|1)\s*$/i) {
1466 $expr .= "tile (";
1467
1468 my $shade = $bg_opts->{shade};
1469
1470 if ($shade) {
1471 $shade = List::Util::min $shade, 200;
1472 $shade = List::Util::max $shade, -100;
1473 $shade = 200 - (100 + $shade) if $shade < 0;
1474
1475 $shade = $shade * 0.01 - 1;
1476 $expr .= "shade $shade, ";
1477 }
1478
1479 my $tint = $bg_opts->{tint};
1480
1481 if ($tint) {
1482 $tint = q0 $tint;
1483 $expr .= "tint $tint,";
1484 }
1485
1486 my $blur = $bg_opts->{blur};
1487
1488 if ($blur and $blur =~ /^ =? ([0-9]+)? (?:[xX] ([0-9]+))? $/x) {
1489 my $hr = defined $1 ? $1 : 1;
1490 my $vr = defined $2 ? $2 : $hr;
1491
1492 if ($hr != 0 and $vr != 0) {
1493 $expr .= "blur $hr, $vr, ";
1494 }
1495 }
1496
1497 $expr .= "rootalign root)";
1498 }
1499
1500 if ($bg_opts->{path}) {
1501 my $file_expr;
1502 my $h_scale = $bg_opts->{h_scale} * 0.01;
1503 my $v_scale = $bg_opts->{v_scale} * 0.01;
1504 my $h_align = $bg_opts->{h_align} * 0.01;
1505 my $v_align = $bg_opts->{v_align} * 0.01;
1506
1507 if (!$bg_opts->{tile}) {
1508 $file_expr .= "pad (";
1509 } else {
1510 $file_expr .= "tile (";
1511 }
1512
1513 if ($bg_opts->{root_align}) {
1514 $file_expr .= "rootalign ";
1515 } else {
1516 $file_expr .= "align $h_align, $v_align, ";
1517 }
1518
1519 if ($h_scale != 0 and $v_scale != 0) {
1520 my $op = $bg_opts->{keep_aspect} ? "fit" : "resize";
1521 $file_expr .= "$op TW * $h_scale, TH * $v_scale, ";
1522 }
1523
1524 my $path = q0 $bg_opts->{path};
1525
1526 $file_expr .= "keep { load $path })";
1527
1528 if ($expr) {
1529 $expr .= ", tint (\"[50]white\", $file_expr)";
1530 } else {
1531 $expr = $file_expr;
1532 }
1533 }
1534
1535 $expr
1536}
1537
1538sub find_resource {
1539 my ($self, $res, $opt) = @_;
1540
1541 my $v = $self->x_resource ($opt);
1542 $v = $self->x_resource ($res) unless defined $v;
1543
1544 $v
1545}
1546
1547sub parse_bgopts {
1548 my ($self) = @_;
1549
1550 my $expr = $self->x_resource ("%.expr");
1551
1552 if (!$expr) {
1553 $self->{bg_opts} = { h_scale => 100, v_scale => 100,
1554 h_align => 50, v_align => 50 };
1555
1556 $self->{bg_opts}{shade} = $self->find_resource ("shading", "sh");
1557 $self->{bg_opts}{tint} = $self->find_resource ("tintColor", "tint");
1558 $self->{bg_opts}{blur} = $self->find_resource ("blurRadius", "blr");
1559 $self->{bg_opts}{root} = $self->find_resource ("transparent", "tr");
1560
1561 $self->old_bg_opts ($self->find_resource ("backgroundPixmap", "pixmap"));
1562 $expr = $self->old_bg_expr;
1563 }
1564
1565 $self->set_expr (parse_expr $expr);
1566 $self->{border} = $self->x_resource_boolean ("%.border");
1567
1568 $MIN_INTERVAL = $self->x_resource ("%.interval");
1569}
1570
1073sub on_start { 1571sub on_start {
1074 my ($self) = @_; 1572 my ($self) = @_;
1075 1573
1076 my $expr = $self->x_resource ("%.expr") 1574 $self->parse_bgopts;
1077 or return;
1078
1079 $self->has_render
1080 or die "background extension needs RENDER extension 0.10 or higher, ignoring background-expr.\n";
1081
1082 $self->set_expr (parse_expr $expr);
1083 $self->{border} = $self->x_resource_boolean ("%.border");
1084
1085 $MIN_INTERVAL = $self->x_resource ("%.interval");
1086 1575
1087 () 1576 ()
1088} 1577}
1089 1578
1579sub on_osc_seq {
1580 my ($self, $op, $arg) = @_;
1581
1582 $op eq "20" or $op eq "706"
1583 or return;
1584
1585 $self->{bg_opts}
1586 or $self->parse_bgopts;
1587
1588 if ($op eq "20") {
1589 if ($arg eq "?") {
1590 my $h_scale = $self->{bg_opts}{h_scale};
1591 my $v_scale = $self->{bg_opts}{v_scale};
1592 my $h_align = $self->{bg_opts}{h_align};
1593 my $v_align = $self->{bg_opts}{v_align};
1594 $self->cmd_parse ("\033]2;[${h_scale}x${v_scale}+${h_align}+${v_align}]\007");
1595 } else {
1596 $self->old_bg_opts ($arg);
1597 my $expr = $self->old_bg_expr;
1598 $self->set_expr (parse_expr $expr) if $expr;
1599 }
1600 } elsif ($op eq "705") {
1601 $self->{bg_opts}{tint} = $arg;
1602 my $expr = $self->old_bg_expr;
1603 $self->set_expr (parse_expr $expr) if $expr;
1604 }
1605
1606 1
1607}
1608

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines