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.45 by root, Sun Jun 10 11:53:32 2012 UTC vs.
Revision 1.56 by root, Thu Jun 14 17:06:57 2012 UTC

1#! perl 1#! perl
2 2
3#:META:X_RESOURCE:%.expr:string:background expression 3#:META:X_RESOURCE:%.expr:string:background expression
4#:META:X_RESOURCE:%.border.:boolean:respect the terminal border 4#:META:X_RESOURCE:%.border:boolean:respect the terminal border
5 5#:META:X_RESOURCE:%.interval:seconds:minimum time between updates
6#TODO: once, rootalign
7 6
8=head1 NAME 7=head1 NAME
9 8
10 background - manage terminal background 9 background - manage terminal background
11 10
12=head1 SYNOPSIS 11=head1 SYNOPSIS
13 12
14 urxvt --background-expr 'background expression' 13 urxvt --background-expr 'background expression'
15 --background-border 14 --background-border
15 --background-interval seconds
16 16
17=head1 DESCRIPTION 17=head1 DESCRIPTION
18 18
19This extension manages the terminal background by creating a picture that 19This extension manages the terminal background by creating a picture that
20is behind the text, replacing the normal background colour. 20is behind the text, replacing the normal background colour.
57 57
58For example, an expression such as C<scale load "$HOME/mybg.png"> scales the 58For example, an expression such as C<scale load "$HOME/mybg.png"> scales the
59image to the window size, so it relies on the window size and will 59image to the window size, so it relies on the window size and will
60be reevaluated each time it is changed, but not when it moves for 60be reevaluated each time it is changed, but not when it moves for
61example. That ensures that the picture always fills the terminal, even 61example. That ensures that the picture always fills the terminal, even
62after it's size changes. 62after its size changes.
63 63
64=head2 EXPRESSIONS 64=head2 EXPRESSIONS
65 65
66Expressions are normal Perl expressions, in fact, they are Perl blocks - 66Expressions are normal Perl expressions, in fact, they are Perl blocks -
67which means you could use multiple lines and statements: 67which means you could use multiple lines and statements:
71 return scale load "$HOME/weekday.png"; 71 return scale load "$HOME/weekday.png";
72 } else { 72 } else {
73 return scale load "$HOME/sunday.png"; 73 return scale load "$HOME/sunday.png";
74 } 74 }
75 75
76This expression gets evaluated once per hour. It will set F<sunday.png> as 76This expression is evaluated once per hour. It will set F<sunday.png> as
77background on Sundays, and F<weekday.png> on all other days. 77background on Sundays, and F<weekday.png> on all other days.
78 78
79Fortunately, we expect that most expressions will be much simpler, with 79Fortunately, we expect that most expressions will be much simpler, with
80little Perl knowledge needed. 80little Perl knowledge needed.
81 81
115horizontal and vertical dimensions. For example, this halves the image 115horizontal and vertical dimensions. For example, this halves the image
116width and doubles the image height: 116width and doubles the image height:
117 117
118 scale 0.5, 2, load "$HOME/mypic.png" 118 scale 0.5, 2, load "$HOME/mypic.png"
119 119
120Other effects than scalign are also readily available, for exmaple, you can 120Other effects than scaling are also readily available, for example, you can
121tile the image to fill the whole window, instead of resizing it: 121tile the image to fill the whole window, instead of resizing it:
122 122
123 tile load "$HOME/mypic.png" 123 tile load "$HOME/mypic.png"
124 124
125In fact, images returned by C<load> are in C<tile> mode by default, so the C<tile> operator 125In fact, images returned by C<load> are in C<tile> mode by default, so the C<tile> operator
151This only works for one cycle though, so as long as you load the same 151This only works for one cycle though, so as long as you load the same
152image every time, it will always be cached, but when you load a different 152image every time, it will always be cached, but when you load a different
153image, it will forget about the first one. 153image, it will forget about the first one.
154 154
155This allows you to either speed things up by keeping multiple images in 155This allows you to either speed things up by keeping multiple images in
156memory, or comserve memory by loading images more often. 156memory, or conserve memory by loading images more often.
157 157
158For example, you can keep two images in memory and use a random one like 158For example, you can keep two images in memory and use a random one like
159this: 159this:
160 160
161 my $img1 = load "img1.png"; 161 my $img1 = load "img1.png";
189overwriting borders and any other areas, such as the scrollbar. 189overwriting borders and any other areas, such as the scrollbar.
190 190
191Specifying this flag changes the behaviour, so that the image only 191Specifying this flag changes the behaviour, so that the image only
192replaces the background of the character area. 192replaces the background of the character area.
193 193
194=item --background-interval seconds
195
196Since some operations in the underlying XRender extension can effectively
197freeze your X-server for prolonged time, this extension enforces a minimum
198time between updates, which is normally about 0.1 seconds.
199
200If you want to do updates more often, you can decrease this safety
201interval with this switch.
202
194=back 203=back
195 204
196=cut 205=cut
197 206
207our %_IMG_CACHE;
198our $HOME; 208our $HOME;
199our ($self, $old, $new); 209our ($self, $old, $new);
200our ($x, $y, $w, $h); 210our ($x, $y, $w, $h);
201 211
202# enforce at least this interval between updates 212# enforce at least this interval between updates
203our $MIN_INTERVAL = 1/100; 213our $MIN_INTERVAL = 6/59.951;
204 214
205{ 215{
206 package urxvt::bgdsl; # background language 216 package urxvt::bgdsl; # background language
207 217
208 use List::Util qw(min max sum shuffle); 218 use List::Util qw(min max sum shuffle);
218=item load $path 228=item load $path
219 229
220Loads the image at the given C<$path>. The image is set to plane tiling 230Loads the image at the given C<$path>. The image is set to plane tiling
221mode. 231mode.
222 232
223Loaded images will be cached for one cycle. 233Loaded images will be cached for one cycle, and shared between temrinals
234running in the same process (e.g. in C<urxvtd>).
224 235
236=item load_uc $path
237
238Load uncached - same as load, but does not cache the image. This function
239is most useufl if you want to optimise a background expression in some
240way.
241
225=cut 242=cut
243
244 sub load_uc($) {
245 my ($path) = @_;
246
247 $_IMG_CACHE{$path} || do {
248 my $img = $self->new_img_from_file ($path);
249 Scalar::Util::weaken ($_IMG_CACHE{$path} = $img);
250 $img
251 }
252 }
226 253
227 sub load($) { 254 sub load($) {
228 my ($path) = @_; 255 my ($path) = @_;
229 256
230 $new->{load}{$path} = $old->{load}{$path} || $self->new_img_from_file ($path); 257 $new->{load}{$path} = $old->{load}{$path} || load_uc $path;
231 } 258 }
232 259
233=item root 260=item root
234 261
235Returns the root window pixmap, that is, hopefully, the background image 262Returns the root window pixmap, that is, hopefully, the background image
239reevaluated when the bg image changes. 266reevaluated when the bg image changes.
240 267
241=cut 268=cut
242 269
243 sub root() { 270 sub root() {
244 $new->{rootpmap_sensitive} = 1; 271 $new->{again}{rootpmap} = 1;
245 die "root op not supported, exg, we need you"; 272 $self->new_img_from_root
246 } 273 }
247 274
248=item solid $colour 275=item solid $colour
249 276
250=item solid $width, $height, $colour 277=item solid $width, $height, $colour
274 301
275 sub clone($) { 302 sub clone($) {
276 $_[0]->clone 303 $_[0]->clone
277 } 304 }
278 305
279=back 306=item merge $img ...
307
308Takes any number of images and merges them together, creating a single image containing them all.
309
310=cut
311
312 sub merge(@) {
313 #TODO
314 }
280 315
281=head2 TILING MODES 316=head2 TILING MODES
282 317
283The following operators modify the tiling mode of an image, that is, the 318The following operators modify the tiling mode of an image, that is, the
284way that pixels outside the image area are painted when the image is used. 319way that pixels outside the image area are painted when the image is used.
314become transparent. This mode is most useful when you want to place an 349become transparent. This mode is most useful when you want to place an
315image over another image or the background colour while leaving all 350image over another image or the background colour while leaving all
316background pixels outside the image unchanged. 351background pixels outside the image unchanged.
317 352
318Example: load an image and display it in the upper left corner. The rest 353Example: load an image and display it in the upper left corner. The rest
319of the space is left "empty" (transparent or wahtever your compisotr does 354of the space is left "empty" (transparent or whatever your compositor does
320in alpha mode, else background colour). 355in alpha mode, else background colour).
321 356
322 pad load "mybg.png" 357 pad load "mybg.png"
323 358
324=item extend $img 359=item extend $img
325 360
326Extends the image over the whole plane, using the closest pixel in the 361Extends the image over the whole plane, using the closest pixel in the
327area outside the image. This mode is mostly useful when you more complex 362area outside the image. This mode is mostly useful when you use more complex
328filtering operations and want the pixels outside the image to have the 363filtering operations and want the pixels outside the image to have the
329same values as the pixels near the edge. 364same values as the pixels near the edge.
330 365
331Example: just for curiosity, how does this pixel extension stuff work? 366Example: just for curiosity, how does this pixel extension stuff work?
332 367
399the window size to conserve memory. 434the window size to conserve memory.
400 435
401Example: take the screen background, clip it to the window size, blur it a 436Example: take the screen background, clip it to the window size, blur it a
402bit, align it to the window position and use it as background. 437bit, align it to the window position and use it as background.
403 438
404 clip move -TX, -TY, blur 5, root 439 clip move -TX, -TY, once { blur 5, root }
405 440
406=cut 441=cut
407 442
408 sub TX() { $new->{position_sensitive} = 1; $x } 443 sub TX() { $new->{again}{position} = 1; $x }
409 sub TY() { $new->{position_sensitive} = 1; $y } 444 sub TY() { $new->{again}{position} = 1; $y }
410 sub TW() { $new->{size_sensitive} = 1; $w } 445 sub TW() { $new->{again}{size} = 1; $w }
411 sub TH() { $new->{size_sensitive} = 1; $h } 446 sub TH() { $new->{again}{size} = 1; $h }
412 447
413=item now 448=item now
414 449
415Returns the current time as (fractional) seconds since the epoch. 450Returns the current time as (fractional) seconds since the epoch.
416 451
423C<$seconds> seconds. 458C<$seconds> seconds.
424 459
425Example: load some image and rotate it according to the time of day (as if it were 460Example: load some image and rotate it according to the time of day (as if it were
426the hour pointer of a clock). Update this image every minute. 461the hour pointer of a clock). Update this image every minute.
427 462
428 again 60; rotate TW, TH, 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png" 463 again 60; rotate 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png"
429 464
430=item counter $seconds 465=item counter $seconds
431 466
432Like C<again>, but also returns an increasing counter value, starting at 467Like C<again>, but also returns an increasing counter value, starting at
4330, which might be useful for some simple animation effects. 4680, which might be useful for some simple animation effects.
435=cut 470=cut
436 471
437 sub now() { urxvt::NOW } 472 sub now() { urxvt::NOW }
438 473
439 sub again($) { 474 sub again($) {
440 $new->{again} = $_[0]; 475 $new->{again}{time} = $_[0];
441 } 476 }
442 477
443 sub counter($) { 478 sub counter($) {
444 $new->{again} = $_[0]; 479 $new->{again}{time} = $_[0];
445 $self->{counter} + 0 480 $self->{counter} + 0
446 } 481 }
447 482
448=back 483=back
449 484
553 588
554Example: move the image right by 20 pixels and down by 30. 589Example: move the image right by 20 pixels and down by 30.
555 590
556 move 20, 30, ... 591 move 20, 30, ...
557 592
593=item align $xalign, $yalign, $img
594
595Aligns the image according to a factor - C<0> means the image is moved to
596the left or top edge (for C<$xalign> or C<$yalign>), C<0.5> means it is
597exactly centered and C<1> means it touches the right or bottom edge.
598
599Example: remove any visible border around an image, center it vertically but move
600it to the right hand side.
601
602 align 1, 0.5, pad $img
603
558=item center $img 604=item center $img
559 605
560=item center $width, $height, $img 606=item center $width, $height, $img
561 607
562Centers the image, i.e. the center of the image is moved to the center of 608Centers the image, i.e. the center of the image is moved to the center of
563the terminal window (or the box specified by C<$width> and C<$height> if 609the terminal window (or the box specified by C<$width> and C<$height> if
564given). 610given).
611
612Example: load an image and center it.
613
614 center pad load "mybg.png"
565 615
566=item rootalign $img 616=item rootalign $img
567 617
568Moves the image so that it appears glued to the screen as opposed to the 618Moves the image so that it appears glued to the screen as opposed to the
569window. This gives the illusion of a larger area behind the window. It is 619window. This gives the illusion of a larger area behind the window. It is
575 rootalign mirror load "mybg.png" 625 rootalign mirror load "mybg.png"
576 626
577Example: take the screen background and align it, giving the illusion of 627Example: take the screen background and align it, giving the illusion of
578transparency as long as the window isn't in front of other windows. 628transparency as long as the window isn't in front of other windows.
579 629
580 rootalign root 630 rootalign root
581 631
582=cut 632=cut
583 633
584 sub move($$;$) { 634 sub move($$;$) {
585 my $img = pop->clone; 635 my $img = pop->clone;
586 $img->move ($_[0], $_[1]); 636 $img->move ($_[0], $_[1]);
587 $img 637 $img
588 } 638 }
589 639
640 sub align($;$$) {
641 my $img = pop;
642
643 move $_[0] * (TW - $img->w),
644 $_[1] * (TH - $img->h),
645 $img
646 }
647
590 sub center($;$$) { 648 sub center($;$$) {
591 my $img = pop; 649 my $img = pop;
592 my $w = $_[0] || TW; 650 my $w = $_[0] || TW;
593 my $h = $_[0] || TH; 651 my $h = $_[1] || TH;
594 652
595 move 0.5 * ($w - $img->w), 0.5 * ($h - $img->h), $img 653 move 0.5 * ($w - $img->w), 0.5 * ($h - $img->h), $img
596 } 654 }
597 655
598 sub rootalign($) { 656 sub rootalign($) {
599 move -TX, -TY, $_[0] 657 move -TX, -TY, $_[0]
658 }
659
660=item rotate $center_x, $center_y, $degrees
661
662Rotates the image by C<$degrees> degrees, counter-clockwise, around the
663pointer at C<$center_x> and C<$center_y> (specified as factor of image
664width/height).
665
666#TODO# new width, height, maybe more operators?
667
668Example: rotate the image by 90 degrees
669
670=cut
671
672 sub rotate($$$$) {
673 my $img = pop;
674 $img->rotate (
675 $_[0] * $img->w,
676 $_[1] * $img->h,
677 $_[2] * (3.14159265 / 180),
678 )
600 } 679 }
601 680
602=back 681=back
603 682
604=head2 COLOUR MODIFICATIONS 683=head2 COLOUR MODIFICATIONS
640 719
641Values less than 0 reduce brightness, while values larger than 0 increase 720Values less than 0 reduce brightness, while values larger than 0 increase
642it. Useful range is from -1 to 1 - the former results in a black, the 721it. Useful range is from -1 to 1 - the former results in a black, the
643latter in a white picture. 722latter in a white picture.
644 723
645Due to idiosynchrasies in the underlying XRender extension, biases less 724Due to idiosyncrasies in the underlying XRender extension, biases less
646than zero can be I<very> slow. 725than zero can be I<very> slow.
647 726
648=cut 727=cut
649 728
650 sub contrast($$;$$;$) { 729 sub contrast($$;$$;$) {
651 my $img = pop; 730 my $img = pop;
652 my ($r, $g, $b, $a) = @_; 731 my ($r, $g, $b, $a) = @_;
653 732
654 ($g, $b) = ($r, $r) if @_ < 4; 733 ($g, $b) = ($r, $r) if @_ < 3;
655 $a = 1 if @_ < 5; 734 $a = 1 if @_ < 4;
656 735
657 $img = $img->clone; 736 $img = $img->clone;
658 $img->contrast ($r, $g, $b, $a); 737 $img->contrast ($r, $g, $b, $a);
659 $img 738 $img
660 } 739 }
661 740
662 sub brightness($$;$$;$) { 741 sub brightness($$;$$;$) {
663 my $img = pop; 742 my $img = pop;
664 my ($r, $g, $b, $a) = @_; 743 my ($r, $g, $b, $a) = @_;
665 744
666 ($g, $b) = ($r, $r) if @_ < 4; 745 ($g, $b) = ($r, $r) if @_ < 3;
667 $a = 1 if @_ < 5; 746 $a = 1 if @_ < 4;
668 747
669 $img = $img->clone; 748 $img = $img->clone;
670 $img->brightness ($r, $g, $b, $a); 749 $img->brightness ($r, $g, $b, $a);
671 $img 750 $img
672 } 751 }
688 sub blur($$;$) { 767 sub blur($$;$) {
689 my $img = pop; 768 my $img = pop;
690 $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0]) 769 $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
691 } 770 }
692 771
693=item rotate $new_width, $new_height, $center_x, $center_y, $degrees 772=back
694 773
695Rotates the image by C<$degrees> degrees, counter-clockwise, around the 774=head2 OTHER STUFF
696pointer at C<$center_x> and C<$center_y> (specified as factor of image
697width/height), generating a new image with width C<$new_width> and height
698C<$new_height>.
699 775
700#TODO# new width, height, maybe more operators? 776Anything that didn't fit any of the other categories, even after applying
777force and closing our eyes.
701 778
702Example: rotate the image by 90 degrees 779=over 4
703 780
704=cut 781=item once { ... }
705 782
706 sub rotate($$$$$$) { 783This function takes a code block as argument, that is, one or more
707 my $img = pop; 784statements enclosed by braces.
708 $img->rotate ( 785
709 $_[0], 786The trick is that this code block is only evaluated once - future calls
710 $_[1], 787will simply return the original image (yes, it should only be used with
711 $_[2] * $img->w, 788images).
712 $_[3] * $img->h, 789
713 $_[4] * (3.14159265 / 180), 790This can be extremely useful to avoid redoign the same slow operations
791again and again- for example, if your background expression takes the root
792background, blurs it and then root-aligns it it would have to blur the
793root background on every window move or resize.
794
795Putting the blur into a C<once> block will make sure the blur is only done
796once:
797
798 rootlign once { blur 10, root }
799
800This leaves the question of how to force reevaluation of the block, in
801case the root background changes: Right now, all once blocks forget that
802they ahve been executed before each time the root background changes (if
803the expression is sensitive to that) or when C<once_again> is called.
804
805=item once_again
806
807Resets all C<once> block as if they had never been called, i.e. on the
808next call they will be reevaluated again.
809
810=cut
811
812 sub once(&) {
813 my $once = $self->{once_cache}{$_[0]+0} ||= do {
814 local $new->{again};
815 my @res = $_[0]();
816 [$new->{again}, \@res]
714 ) 817 };
818
819 $new->{again} = {
820 %{ $new->{again} },
821 %{ $once->[0] }
822 };
823
824 # in scalar context we always return the first original result, which
825 # is not quite how perl works.
826 wantarray
827 ? @{ $once->[1] }
828 : $once->[1][0]
829 }
830
831 sub once_again() {
832 delete $self->{once_cache};
715 } 833 }
716 834
717=back 835=back
718 836
719=cut 837=cut
762 880
763 # evaluate user expression 881 # evaluate user expression
764 882
765 my $img = eval { $self->{expr}->() }; 883 my $img = eval { $self->{expr}->() };
766 warn $@ if $@;#d# 884 warn $@ if $@;#d#
767 die if !UNIVERSAL::isa $img, "urxvt::img"; 885 die "background-expr did not return an image.\n" if !UNIVERSAL::isa $img, "urxvt::img";
768 886
769 $state->{size_sensitive} = 1 887 # if the expression is sensitive to external events, prepare reevaluation then
888
889 my $again = delete $state->{again};
890
891 $again->{size} = 1
770 if $img->repeat_mode != urxvt::RepeatNormal; 892 if $img->repeat_mode != urxvt::RepeatNormal;
771 893
772 # if the expression is sensitive to external events, prepare reevaluation then
773
774 my $repeat;
775
776 if (my $again = $state->{again}) { 894 if (my $again = $again->{time}) {
777 $repeat = 1;
778 my $self = $self; 895 my $self = $self;
779 $state->{timer} = $again == $old->{again} 896 $state->{timer} = $again == $old->{again}
780 ? $old->{timer} 897 ? $old->{timer}
781 : urxvt::timer->new->after ($again)->interval ($again)->cb (sub { 898 : urxvt::timer->new->after ($again)->interval ($again)->cb (sub {
782 ++$self->{counter}; 899 ++$self->{counter};
783 $self->recalculate 900 $self->recalculate
784 }); 901 });
785 } 902 }
786 903
787 if (delete $state->{position_sensitive}) { 904 if ($again->{position}) {
788 $repeat = 1;
789 $self->enable (position_change => sub { $_[0]->recalculate }); 905 $self->enable (position_change => sub { $_[0]->recalculate });
790 } else { 906 } else {
791 $self->disable ("position_change"); 907 $self->disable ("position_change");
792 } 908 }
793 909
794 if (delete $state->{size_sensitive}) { 910 if ($again->{size}) {
795 $repeat = 1;
796 $self->enable (size_change => sub { $_[0]->recalculate }); 911 $self->enable (size_change => sub { $_[0]->recalculate });
797 } else { 912 } else {
798 $self->disable ("size_change"); 913 $self->disable ("size_change");
799 } 914 }
800 915
801 if (delete $state->{rootpmap_sensitive}) { 916 if ($again->{rootpmap}) {
802 $repeat = 1;
803 $self->enable (rootpmap_change => sub { $_[0]->recalculate }); 917 $self->enable (rootpmap_change => sub {
918 delete $_[0]{once_cache}; # this will override once-block values from
919 $_[0]->recalculate;
920 });
804 } else { 921 } else {
805 $self->disable ("rootpmap_change"); 922 $self->disable ("rootpmap_change");
806 } 923 }
807 924
808 # clear stuff we no longer need 925 # clear stuff we no longer need
809 926
810 %$old = (); 927 %$old = ();
811 928
812 unless ($repeat) { 929 unless (%$again) {
813 delete $self->{state}; 930 delete $self->{state};
814 delete $self->{expr}; 931 delete $self->{expr};
815 } 932 }
816 933
817 # set background pixmap 934 # set background pixmap
822} 939}
823 940
824sub on_start { 941sub on_start {
825 my ($self) = @_; 942 my ($self) = @_;
826 943
827 my $expr = $self->x_resource ("background.expr") 944 my $expr = $self->x_resource ("%.expr")
828 or return; 945 or return;
829 946
947 $self->has_render
948 or die "background extension needs RENDER extension 0.10 or higher, ignoring background-expr.\n";
949
830 $self->set_expr (parse_expr $expr); 950 $self->set_expr (parse_expr $expr);
831 $self->{border} = $self->x_resource_boolean ("background.border"); 951 $self->{border} = $self->x_resource_boolean ("%.border");
952
953 $MIN_INTERVAL = $self->x_resource ("%.interval");
832 954
833 () 955 ()
834} 956}
835 957

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines