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.44 by root, Sun Jun 10 11:31:22 2012 UTC vs.
Revision 1.54 by root, Thu Jun 14 16:22:20 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;
208our %_ONCE_CACHE;
198our $HOME; 209our $HOME;
199our ($self, $old, $new); 210our ($self, $old, $new);
200our ($x, $y, $w, $h); 211our ($x, $y, $w, $h);
201 212
202# enforce at least this interval between updates 213# enforce at least this interval between updates
203our $MIN_INTERVAL = 1/100; 214our $MIN_INTERVAL = 6/59.951;
204 215
205{ 216{
206 package urxvt::bgdsl; # background language 217 package urxvt::bgdsl; # background language
207 218
208 use List::Util qw(min max sum shuffle); 219 use List::Util qw(min max sum shuffle);
218=item load $path 229=item load $path
219 230
220Loads the image at the given C<$path>. The image is set to plane tiling 231Loads the image at the given C<$path>. The image is set to plane tiling
221mode. 232mode.
222 233
223Loaded images will be cached for one cycle. 234Loaded images will be cached for one cycle, and shared between temrinals
235running in the same process (e.g. in C<urxvtd>).
224 236
237=item load_uc $path
238
239Load uncached - same as load, but does not cache the image. This function
240is most useufl if you want to optimise a background expression in some
241way.
242
225=cut 243=cut
244
245 sub load_uc($) {
246 my ($path) = @_;
247
248 $_IMG_CACHE{$path} || do {
249 my $img = $self->new_img_from_file ($path);
250 Scalar::Util::weaken ($_IMG_CACHE{$path} = $img);
251 $img
252 }
253 }
226 254
227 sub load($) { 255 sub load($) {
228 my ($path) = @_; 256 my ($path) = @_;
229 257
230 $new->{load}{$path} = $old->{load}{$path} || $self->new_img_from_file ($path); 258 $new->{load}{$path} = $old->{load}{$path} || load_uc $path;
231 } 259 }
232 260
233=item root 261=item root
234 262
235Returns the root window pixmap, that is, hopefully, the background image 263Returns the root window pixmap, that is, hopefully, the background image
240 268
241=cut 269=cut
242 270
243 sub root() { 271 sub root() {
244 $new->{rootpmap_sensitive} = 1; 272 $new->{rootpmap_sensitive} = 1;
245 die "root op not supported, exg, we need you"; 273 $self->new_img_from_root
246 } 274 }
247 275
248=item solid $colour 276=item solid $colour
249 277
250=item solid $width, $height, $colour 278=item solid $width, $height, $colour
263 my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1); 291 my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1);
264 $img->fill ($colour); 292 $img->fill ($colour);
265 $img 293 $img
266 } 294 }
267 295
296=item clone $img
297
298Returns an exact copy of the image. This is useful if you want to have
299multiple copies of the same image to apply different effects to.
300
301=cut
302
303 sub clone($) {
304 $_[0]->clone
305 }
306
307=head2 TILING MODES
308
309The following operators modify the tiling mode of an image, that is, the
310way that pixels outside the image area are painted when the image is used.
311
312=over 4
313
314=item tile $img
315
316Tiles the whole plane with the image and returns this new image - or in
317other words, it returns a copy of the image in plane tiling mode.
318
319Example: load an image and tile it over the background, without
320resizing. The C<tile> call is superfluous because C<load> already defaults
321to tiling mode.
322
323 tile load "mybg.png"
324
325=item mirror $img
326
327Similar to tile, but reflects the image each time it uses a new copy, so
328that top edges always touch top edges, right edges always touch right
329edges and so on (with normal tiling, left edges always touch right edges
330and top always touch bottom edges).
331
332Example: load an image and mirror it over the background, avoiding sharp
333edges at the image borders at the expense of mirroring the image itself
334
335 mirror load "mybg.png"
336
337=item pad $img
338
339Takes an image and modifies it so that all pixels outside the image area
340become transparent. This mode is most useful when you want to place an
341image over another image or the background colour while leaving all
342background pixels outside the image unchanged.
343
344Example: load an image and display it in the upper left corner. The rest
345of the space is left "empty" (transparent or whatever your compositor does
346in alpha mode, else background colour).
347
348 pad load "mybg.png"
349
350=item extend $img
351
352Extends the image over the whole plane, using the closest pixel in the
353area outside the image. This mode is mostly useful when you use more complex
354filtering operations and want the pixels outside the image to have the
355same values as the pixels near the edge.
356
357Example: just for curiosity, how does this pixel extension stuff work?
358
359 extend move 50, 50, load "mybg.png"
360
361=cut
362
363 sub pad($) {
364 my $img = $_[0]->clone;
365 $img->repeat_mode (urxvt::RepeatNone);
366 $img
367 }
368
369 sub tile($) {
370 my $img = $_[0]->clone;
371 $img->repeat_mode (urxvt::RepeatNormal);
372 $img
373 }
374
375 sub mirror($) {
376 my $img = $_[0]->clone;
377 $img->repeat_mode (urxvt::RepeatReflect);
378 $img
379 }
380
381 sub extend($) {
382 my $img = $_[0]->clone;
383 $img->repeat_mode (urxvt::RepeatPad);
384 $img
385 }
386
268=back 387=back
269 388
270=head2 VARIABLES 389=head2 VARIABLE VALUES
271 390
272The following functions provide variable data such as the terminal window 391The following functions provide variable data such as the terminal window
273dimensions. They are not (Perl-) variables, they jsut return stuff that 392dimensions. They are not (Perl-) variables, they just return stuff that
274varies. Most of them make your expression sensitive to some events, for 393varies. Most of them make your expression sensitive to some events, for
275example using C<TW> (terminal width) means your expression is evaluated 394example using C<TW> (terminal width) means your expression is evaluated
276again when the terminal is resized. 395again when the terminal is resized.
277 396
278=over 4 397=over 4
330C<$seconds> seconds. 449C<$seconds> seconds.
331 450
332Example: load some image and rotate it according to the time of day (as if it were 451Example: load some image and rotate it according to the time of day (as if it were
333the hour pointer of a clock). Update this image every minute. 452the hour pointer of a clock). Update this image every minute.
334 453
335 again 60; rotate TW, TH, 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png" 454 again 60; rotate 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png"
336 455
337=item counter $seconds 456=item counter $seconds
338 457
339Like C<again>, but also returns an increasing counter value, starting at 458Like C<again>, but also returns an increasing counter value, starting at
3400, which might be useful for some simple animation effects. 4590, which might be useful for some simple animation effects.
352 $self->{counter} + 0 471 $self->{counter} + 0
353 } 472 }
354 473
355=back 474=back
356 475
357=head2 TILING MODES 476=head2 SHAPE CHANGING OPERATORS
358 477
359The following operators modify the tiling mode of an image, that is, the 478The following operators modify the shape, size or position of the image.
360way that pixels outside the image area are painted when the image is used.
361 479
362=over 4 480=over 4
363
364=item tile $img
365
366Tiles the whole plane with the image and returns this new image - or in
367other words, it returns a copy of the image in plane tiling mode.
368
369Example: load an image and tile it over the background, without
370resizing. The C<tile> call is superfluous because C<load> already defaults
371to tiling mode.
372
373 tile load "mybg.png"
374
375=item mirror $img
376
377Similar to tile, but reflects the image each time it uses a new copy, so
378that top edges always touch top edges, right edges always touch right
379edges and so on (with normal tiling, left edges always touch right edges
380and top always touch bottom edges).
381
382Example: load an image and mirror it over the background, avoiding sharp
383edges at the image borders at the expense of mirroring the image itself
384
385 mirror load "mybg.png"
386
387=item pad $img
388
389Takes an image and modifies it so that all pixels outside the image area
390become transparent. This mode is most useful when you want to place an
391image over another image or the background colour while leaving all
392background pixels outside the image unchanged.
393
394Example: load an image and display it in the upper left corner. The rest
395of the space is left "empty" (transparent or wahtever your compisotr does
396in alpha mode, else background colour).
397
398 pad load "mybg.png"
399
400=item extend $img
401
402Extends the image over the whole plane, using the closest pixel in the
403area outside the image. This mode is mostly useful when you more complex
404filtering operations and want the pixels outside the image to have the
405same values as the pixels near the edge.
406
407Example: just for curiosity, how does this pixel extension stuff work?
408
409 extend move 50, 50, load "mybg.png"
410
411=cut
412
413 sub pad($) {
414 my $img = $_[0]->clone;
415 $img->repeat_mode (urxvt::RepeatNone);
416 $img
417 }
418
419 sub tile($) {
420 my $img = $_[0]->clone;
421 $img->repeat_mode (urxvt::RepeatNormal);
422 $img
423 }
424
425 sub mirror($) {
426 my $img = $_[0]->clone;
427 $img->repeat_mode (urxvt::RepeatReflect);
428 $img
429 }
430
431 sub extend($) {
432 my $img = $_[0]->clone;
433 $img->repeat_mode (urxvt::RepeatPad);
434 $img
435 }
436
437=back
438
439=head2 PIXEL OPERATORS
440
441The following operators modify the image pixels in various ways.
442
443=over 4
444
445=item clone $img
446
447Returns an exact copy of the image.
448
449=cut
450
451 sub clone($) {
452 $_[0]->clone
453 }
454 481
455=item clip $img 482=item clip $img
456 483
457=item clip $width, $height, $img 484=item clip $width, $height, $img
458 485
552 579
553Example: move the image right by 20 pixels and down by 30. 580Example: move the image right by 20 pixels and down by 30.
554 581
555 move 20, 30, ... 582 move 20, 30, ...
556 583
584=item align $xalign, $yalign, $img
585
586Aligns the image according to a factor - C<0> means the image is moved to
587the left or top edge (for C<$xalign> or C<$yalign>), C<0.5> means it is
588exactly centered and C<1> means it touches the right or bottom edge.
589
590Example: remove any visible border around an image, center it vertically but move
591it to the right hand side.
592
593 align 1, 0.5, pad $img
594
557=item center $img 595=item center $img
558 596
559=item center $width, $height, $img 597=item center $width, $height, $img
560 598
561Centers the image, i.e. the center of the image is moved to the center of 599Centers the image, i.e. the center of the image is moved to the center of
562the terminal window (or the box specified by C<$width> and C<$height> if 600the terminal window (or the box specified by C<$width> and C<$height> if
563given). 601given).
602
603Example: load an image and center it.
604
605 center pad load "mybg.png"
564 606
565=item rootalign $img 607=item rootalign $img
566 608
567Moves the image so that it appears glued to the screen as opposed to the 609Moves the image so that it appears glued to the screen as opposed to the
568window. This gives the illusion of a larger area behind the window. It is 610window. This gives the illusion of a larger area behind the window. It is
574 rootalign mirror load "mybg.png" 616 rootalign mirror load "mybg.png"
575 617
576Example: take the screen background and align it, giving the illusion of 618Example: take the screen background and align it, giving the illusion of
577transparency as long as the window isn't in front of other windows. 619transparency as long as the window isn't in front of other windows.
578 620
579 rootalign root 621 rootalign root
580 622
581=cut 623=cut
582 624
583 sub move($$;$) { 625 sub move($$;$) {
584 my $img = pop->clone; 626 my $img = pop->clone;
585 $img->move ($_[0], $_[1]); 627 $img->move ($_[0], $_[1]);
586 $img 628 $img
587 } 629 }
588 630
631 sub align($;$$) {
632 my $img = pop;
633
634 move $_[0] * (TW - $img->w),
635 $_[1] * (TH - $img->h),
636 $img
637 }
638
589 sub center($;$$) { 639 sub center($;$$) {
590 my $img = pop; 640 my $img = pop;
591 my $w = $_[0] || TW; 641 my $w = $_[0] || TW;
592 my $h = $_[0] || TH; 642 my $h = $_[1] || TH;
593 643
594 move 0.5 * ($w - $img->w), 0.5 * ($h - $img->h), $img 644 move 0.5 * ($w - $img->w), 0.5 * ($h - $img->h), $img
595 } 645 }
596 646
597 sub rootalign($) { 647 sub rootalign($) {
598 move -TX, -TY, $_[0] 648 move -TX, -TY, $_[0]
599 } 649 }
600 650
651=item rotate $center_x, $center_y, $degrees
652
653Rotates the image by C<$degrees> degrees, counter-clockwise, around the
654pointer at C<$center_x> and C<$center_y> (specified as factor of image
655width/height).
656
657#TODO# new width, height, maybe more operators?
658
659Example: rotate the image by 90 degrees
660
661=cut
662
663 sub rotate($$$$) {
664 my $img = pop;
665 $img->rotate (
666 $_[0] * $img->w,
667 $_[1] * $img->h,
668 $_[2] * (3.14159265 / 180),
669 )
670 }
671
672=back
673
674=head2 COLOUR MODIFICATIONS
675
676The following operators change the pixels of the image.
677
678=over 4
679
601=item contrast $factor, $img 680=item contrast $factor, $img
602 681
603=item contrast $r, $g, $b, $img 682=item contrast $r, $g, $b, $img
604 683
605=item contrast $r, $g, $b, $a, $img 684=item contrast $r, $g, $b, $a, $img
606 685
607Adjusts the I<contrast> of an image. 686Adjusts the I<contrast> of an image.
608 687
609#TODO# 688The first form applies a single C<$factor> to red, green and blue, the
689second form applies separate factors to each colour channel, and the last
690form includes the alpha channel.
610 691
692Values from 0 to 1 lower the contrast, values higher than 1 increase the
693contrast.
694
695Due to limitations in the underlying XRender extension, lowering contrast
696also reduces brightness, while increasing contrast currently also
697increases brightness.
698
611=item brightness $factor, $img 699=item brightness $bias, $img
612 700
613=item brightness $r, $g, $b, $img 701=item brightness $r, $g, $b, $img
614 702
615=item brightness $r, $g, $b, $a, $img 703=item brightness $r, $g, $b, $a, $img
616 704
617Adjusts the brightness of an image. 705Adjusts the brightness of an image.
618 706
707The first form applies a single C<$bias> to red, green and blue, the
708second form applies separate biases to each colour channel, and the last
709form includes the alpha channel.
710
711Values less than 0 reduce brightness, while values larger than 0 increase
712it. Useful range is from -1 to 1 - the former results in a black, the
713latter in a white picture.
714
715Due to idiosyncrasies in the underlying XRender extension, biases less
716than zero can be I<very> slow.
717
619=cut 718=cut
620 719
621 sub contrast($$;$$;$) { 720 sub contrast($$;$$;$) {
622 my $img = pop; 721 my $img = pop;
623 my ($r, $g, $b, $a) = @_; 722 my ($r, $g, $b, $a) = @_;
624 723
625 ($g, $b) = ($r, $r) if @_ < 4; 724 ($g, $b) = ($r, $r) if @_ < 3;
626 $a = 1 if @_ < 5; 725 $a = 1 if @_ < 4;
627 726
628 $img = $img->clone; 727 $img = $img->clone;
629 $img->contrast ($r, $g, $b, $a); 728 $img->contrast ($r, $g, $b, $a);
630 $img 729 $img
631 } 730 }
632 731
633 sub brightness($$;$$;$) { 732 sub brightness($$;$$;$) {
634 my $img = pop; 733 my $img = pop;
635 my ($r, $g, $b, $a) = @_; 734 my ($r, $g, $b, $a) = @_;
636 735
637 ($g, $b) = ($r, $r) if @_ < 4; 736 ($g, $b) = ($r, $r) if @_ < 3;
638 $a = 1 if @_ < 5; 737 $a = 1 if @_ < 4;
639 738
640 $img = $img->clone; 739 $img = $img->clone;
641 $img->brightness ($r, $g, $b, $a); 740 $img->brightness ($r, $g, $b, $a);
642 $img 741 $img
643 } 742 }
659 sub blur($$;$) { 758 sub blur($$;$) {
660 my $img = pop; 759 my $img = pop;
661 $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0]) 760 $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
662 } 761 }
663 762
664=item rotate $new_width, $new_height, $center_x, $center_y, $degrees 763=back
665 764
666Rotates the image by C<$degrees> degrees, counter-clockwise, around the 765=head2 OTHER STUFF
667pointer at C<$center_x> and C<$center_y> (specified as factor of image
668width/height), generating a new image with width C<$new_width> and height
669C<$new_height>.
670 766
671#TODO# new width, height, maybe more operators? 767Anything that didn't fit any of the other categories, even after appliyng
768force and closing our eyes.
672 769
673Example: rotate the image by 90 degrees 770=over 4
674 771
675=cut 772=item once { ... }
676 773
677 sub rotate($$$$$$) { 774This function takes a code block as argument, that is, one or more
678 my $img = pop; 775statements enclosed by braces.
679 $img->rotate ( 776
680 $_[0], 777The trick is that this code block is only evaluated once - future calls
681 $_[1], 778will simply return the original image (yes, it should only be used with
682 $_[2] * $img->w, 779images).
683 $_[3] * $img->h, 780
684 $_[4] * (3.14159265 / 180), 781This can be extremely useful to avoid redoign the same slow operations
685 ) 782again and again- for example, if your background expression takes the root
783background, blurs it and then root-aligns it it would have to blur the
784root background on every window move or resize.
785
786Putting the blur into a C<once> block will make sure the blur is only done
787once:
788
789 rootlign once { blur 10, root }
790
791This leaves the question of how to force reevaluation of the block, in
792case the root background changes: Right now, all once blocks forget that
793they ahve been executed before each time the root background changes (if
794the expression is sensitive to that) or when C<once_again> is called.
795
796=item once_again
797
798Resets all C<once> block as if they had never been called, i.e. on the
799next call they will be reevaluated again.
800
801=cut
802
803 sub once(&) {
804 $_ONCE_CACHE{$_[0]+0} ||= $_[0]()
805 }
806
807 sub once_again() {
808 %_ONCE_CACHE = ();
686 } 809 }
687 810
688=back 811=back
689 812
690=cut 813=cut
733 856
734 # evaluate user expression 857 # evaluate user expression
735 858
736 my $img = eval { $self->{expr}->() }; 859 my $img = eval { $self->{expr}->() };
737 warn $@ if $@;#d# 860 warn $@ if $@;#d#
738 die if !UNIVERSAL::isa $img, "urxvt::img"; 861 die "background-expr did not return an image.\n" if !UNIVERSAL::isa $img, "urxvt::img";
739 862
740 $state->{size_sensitive} = 1 863 $state->{size_sensitive} = 1
741 if $img->repeat_mode != urxvt::RepeatNormal; 864 if $img->repeat_mode != urxvt::RepeatNormal;
742 865
743 # if the expression is sensitive to external events, prepare reevaluation then 866 # if the expression is sensitive to external events, prepare reevaluation then
793} 916}
794 917
795sub on_start { 918sub on_start {
796 my ($self) = @_; 919 my ($self) = @_;
797 920
798 my $expr = $self->x_resource ("background.expr") 921 my $expr = $self->x_resource ("%.expr")
799 or return; 922 or return;
800 923
924 $self->has_render
925 or die "background extension needs RENDER extension 0.10 or higher, ignoring background-expr.\n";
926
801 $self->set_expr (parse_expr $expr); 927 $self->set_expr (parse_expr $expr);
802 $self->{border} = $self->x_resource_boolean ("background.border"); 928 $self->{border} = $self->x_resource_boolean ("%.border");
929
930 $MIN_INTERVAL = $self->x_resource ("%.interval");
803 931
804 () 932 ()
805} 933}
806 934

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines