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.31 by root, Thu Jun 7 13:48:15 2012 UTC vs.
Revision 1.39 by root, Fri Jun 8 22:19:03 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:%.enable:boolean:some boolean 4#:META:X_RESOURCE:%.border.:boolean:respect the terminal border
5#:META:X_RESOURCE:%.extra.:value:extra config
6 5
7our $EXPR; 6#TODO: once, rootalign
8#$EXPR = 'move W * 0.1, -H * 0.1, resize W * 0.5, H * 0.5, repeat_none load "opensource.png"';
9$EXPR = 'move -TX, -TY, load "argb.png"';
10#$EXPR = '
11# rotate W, H, 50, 50, counter 1/59.95, repeat_mirror,
12# clip X, Y, W, H, repeat_mirror,
13# load "/root/pix/das_fette_schwein.jpg"
14#';
15#$EXPR = 'solid "red"';
16#$EXPR = 'blur root, 10, 10'
17#$EXPR = 'blur move (root, -x, -y), 5, 5'
18#resize load "/root/pix/das_fette_schwein.jpg", w, h
19 7
20use Safe; 8=head1 background - manage terminal background
21 9
10=head2 SYNOPSIS
11
12 urxvt --background-expr 'background expression'
13 --background-border
14
15=head2 DESCRIPTION
16
17This extension manages the terminal background by creating a picture that
18is behind the text, replacing the normal background colour.
19
20It does so by evaluating a Perl expression that I<calculates> the image on
21the fly, for example, by grabbing the root background or loading a file.
22
23While the full power of Perl is available, the operators have been design
24to be as simple as possible.
25
26For example, to load an image and scale it to the window size, you would
27use:
28
29 urxvt --background-expr 'scale load "/path/to/mybg.png"'
30
31Or specified as a X resource:
32
33 URxvt.background-expr: scale load "/path/to/mybg.png"
34
35=head2 THEORY OF OPERATION
36
37At startup, just before the window is mapped for the first time, the
38expression is evaluated and must yield an image. The image is then
39extended as necessary to cover the whole terminal window, and is set as a
40background pixmap.
41
42If the image contains an alpha channel, then it will be used as-is in
43visuals that support alpha channels (for example, for a compositing
44manager). In other visuals, the terminal background colour will be used to
45replace any transparency.
46
47When the expression relies, directly or indirectly, on the window size,
48position, the root pixmap, or a timer, then it will be remembered. If not,
49then it will be removed.
50
51If any of the parameters that the expression relies on changes (when the
52window is moved or resized, its position or size changes; when the root
53pixmap is replaced by another one the root background changes; or when the
54timer elapses), then the expression will be evaluated again.
55
56For example, an expression such as C<scale load "$HOME/mybg.png"> scales the
57image to the window size, so it relies on the window size and will
58be reevaluated each time it is changed, but not when it moves for
59example. That ensures that the picture always fills the terminal, even
60after it's size changes.
61
62=head3 EXPRESSIONS
63
64Expressions are normal Perl expressions, in fact, they are Perl blocks -
65which means you could use multiple lines and statements:
66
67 again 3600;
68 if (localtime now)[6]) {
69 return scale load "$HOME/weekday.png";
70 } else {
71 return scale load "$HOME/sunday.png";
72 }
73
74This expression gets evaluated once per hour. It will set F<sunday.png> as
75background on Sundays, and F<weekday.png> on all other days.
76
77Fortunately, we expect that most expressions will be much simpler, with
78little Perl knowledge needed.
79
80Basically, you always start with a function that "generates" an image
81object, such as C<load>, which loads an image from disk, or C<root>, which
82returns the root window background image:
83
84 load "$HOME/mypic.png"
85
86The path is usually specified as a quoted string (the exact rules can be
87found in the L<perlop> manpage). The F<$HOME> at the beginning of the
88string is expanded to the home directory.
89
90Then you prepend one or more modifiers or filtering expressions, such as
91C<scale>:
92
93 scale load "$HOME/mypic.png"
94
95Just like a mathematical expression with functions, you should read these
96expressions from right to left, as the C<load> is evaluated first, and
97its result becomes the argument to the C<scale> function.
98
99Many operators also allow some parameters preceding the input image
100that modify its behaviour. For example, C<scale> without any additional
101arguments scales the image to size of the terminal window. If you specify
102an additional argument, it uses it as a percentage:
103
104 scale 200, load "$HOME/mypic.png"
105
106This enlarges the image by a factor of 2 (200%). As you can see, C<scale>
107has now two arguments, the C<200> and the C<load> expression, while
108C<load> only has one argument. Arguments are separated from each other by
109commas.
110
111Scale also accepts two arguments, which are then separate factors for both
112horizontal and vertical dimensions. For example, this halves the image
113width and doubles the image height:
114
115 scale 50, 200, load "$HOME/mypic.png"
116
117Other effects than scalign are also readily available, for exmaple, you can
118tile the image to fill the whole window, instead of resizing it:
119
120 tile load "$HOME/mypic.png"
121
122In fact, images returned by C<load> are in C<tile> mode by default, so the C<tile> operator
123is kind of superfluous.
124
125Another common effect is to mirror the image, so that the same edges touch:
126
127 mirror load "$HOME/mypic.png"
128
129This is also a typical background expression:
130
131 rootalign root
132
133It first takes a snapshot of the screen background image, and then
134moves it to the upper left corner of the screen - the result is
135pseudo-transparency, as the image seems to be static while the window is
136moved around.
137
138=head3 CYCLES AND CACHING
139
140As has been mentioned before, the expression might be evaluated multiple
141times. Each time the expression is reevaluated, a new cycle is said to
142have begun. Many operators cache their results till the next cycle.
143
144For example, the C<load> operator keeps a copy of the image. If it is
145asked to load the same image on the next cycle it will not load it again,
146but return the cached copy.
147
148This only works for one cycle though, so as long as you load the same
149image every time, it will always be cached, but when you load a different
150image, it will forget about the first one.
151
152This allows you to either speed things up by keeping multiple images in
153memory, or comserve memory by loading images more often.
154
155For example, you can keep two images in memory and use a random one like
156this:
157
158 my $img1 = load "img1.png";
159 my $img2 = load "img2.png";
160 (0.5 > rand) ? $img1 : $img2
161
162Since both images are "loaded" every time the expression is evaluated,
163they are always kept in memory. Contrast this version:
164
165 my $path1 = "img1.png";
166 my $path2 = "img2.png";
167 load ((0.5 > rand) ? $path1 : $path2)
168
169Here, a path is selected randomly, and load is only called for one image,
170so keeps only one image in memory. If, on the next evaluation, luck
171decides to use the other path, then it will have to load that image again.
172
173=head2 REFERENCE
174
175=head3 COMMAND LINE SWITCHES
176
177=over 4
178
179=item --background-expr perl-expression
180
181Specifies the Perl expression to evaluate.
182
183=item --background-border
184
185By default, the expression creates an image that fills the full window,
186overwriting borders and any other areas, such as the scrollbar.
187
188Specifying this flag changes the behaviour, so that the image only
189replaces the background of the character area.
190
191=back
192
193=cut
194
195our $HOME;
22our ($bgdsl_self, $old, $new); 196our ($self, $old, $new);
23our ($x, $y, $w, $h); 197our ($x, $y, $w, $h);
24 198
25# enforce at least this interval between updates 199# enforce at least this interval between updates
26our $MIN_INTERVAL = 1/100; 200our $MIN_INTERVAL = 1/100;
27 201
29 package urxvt::bgdsl; # background language 203 package urxvt::bgdsl; # background language
30 204
31=head2 PROVIDERS/GENERATORS 205=head2 PROVIDERS/GENERATORS
32 206
33These functions provide an image, by loading it from disk, grabbing it 207These functions provide an image, by loading it from disk, grabbing it
34from the root screen or by simply generating it. They are used as strating 208from the root screen or by simply generating it. They are used as starting
35points to get an image you can play with. 209points to get an image you can play with.
36 210
37=over 4 211=over 4
38 212
39=item load $path 213=item load $path
46=cut 220=cut
47 221
48 sub load($) { 222 sub load($) {
49 my ($path) = @_; 223 my ($path) = @_;
50 224
51 $new->{load}{$path} = $old->{load}{$path} || $bgdsl_self->new_img_from_file ($path); 225 $new->{load}{$path} = $old->{load}{$path} || $self->new_img_from_file ($path);
52 } 226 }
53 227
54=item root 228=item root
55 229
56Returns the root window pixmap, that is, hopefully, the background image 230Returns the root window pixmap, that is, hopefully, the background image
79=cut 253=cut
80 254
81 sub solid($$;$) { 255 sub solid($$;$) {
82 my $colour = pop; 256 my $colour = pop;
83 257
84 my $img = $bgdsl_self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1); 258 my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1);
85 $img->fill ($colour); 259 $img->fill ($colour);
86 $img 260 $img
87 } 261 }
88 262
89=back 263=back
90 264
91=head2 VARIABLES 265=head2 VARIABLES
92 266
93The following functions provide variable data such as the terminal 267The following functions provide variable data such as the terminal
94widnow dimensions. Most of them make your expression sensitive to some 268window dimensions. Most of them make your expression sensitive to some
95events, for example using C<TW> (terminal width) means your expression is 269events, for example using C<TW> (terminal width) means your expression is
96evaluated again when the terminal is resized. 270evaluated again when the terminal is resized.
97 271
98=over 4 272=over 4
99 273
135 sub TX() { $new->{position_sensitive} = 1; $x } 309 sub TX() { $new->{position_sensitive} = 1; $x }
136 sub TY() { $new->{position_sensitive} = 1; $y } 310 sub TY() { $new->{position_sensitive} = 1; $y }
137 sub TW() { $new->{size_sensitive} = 1; $w } 311 sub TW() { $new->{size_sensitive} = 1; $w }
138 sub TH() { $new->{size_sensitive} = 1; $h } 312 sub TH() { $new->{size_sensitive} = 1; $h }
139 313
314=item now
315
316Returns the current time as (fractional) seconds since the epoch.
317
318Using this expression does I<not> make your expression sensitive to time,
319but the next two functions do.
320
321=item again $seconds
322
323When this function is used the expression will be reevaluated again in
324C<$seconds> seconds.
325
326Example: load some image and rotate it according to the time of day (as if it were
327the hour pointer of a clock). Update this image every minute.
328
329 again 60; rotate TW, TH, 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png"
330
331=item counter $seconds
332
333Like C<again>, but also returns an increasing counter value, starting at
3340, which might be useful for some simple animation effects.
335
336=cut
337
140 sub now() { urxvt::NOW } 338 sub now() { urxvt::NOW }
141 339
142 sub again($) { 340 sub again($) {
143 $new->{again} = $_[0]; 341 $new->{again} = $_[0];
144 } 342 }
145 343
146 sub counter($) { 344 sub counter($) {
147 $new->{again} = $_[0]; 345 $new->{again} = $_[0];
148 $bgdsl_self->{counter} + 0 346 $self->{counter} + 0
149 } 347 }
150 348
151=back 349=back
152 350
153=head2 TILING MODES 351=head2 TILING MODES
159 357
160=item tile $img 358=item tile $img
161 359
162Tiles the whole plane with the image and returns this new image - or in 360Tiles the whole plane with the image and returns this new image - or in
163other words, it returns a copy of the image in plane tiling mode. 361other words, it returns a copy of the image in plane tiling mode.
362
363Example: load an image and tile it over the background, without
364resizing. The C<tile> call is superfluous because C<load> already defaults
365to tiling mode.
366
367 tile load "mybg.png"
164 368
165=item mirror $img 369=item mirror $img
166 370
167Similar to tile, but reflects the image each time it uses a new copy, so 371Similar to tile, but reflects the image each time it uses a new copy, so
168that top edges always touch top edges, right edges always touch right 372that top edges always touch top edges, right edges always touch right
169edges and so on (with normal tiling, left edges always touch right edges 373edges and so on (with normal tiling, left edges always touch right edges
170and top always touch bottom edges). 374and top always touch bottom edges).
171 375
376Example: load an image and mirror it over the background, avoiding sharp
377edges at the image borders at the expense of mirroring the image itself
378
379 mirror load "mybg.png"
380
172=item pad $img 381=item pad $img
173 382
174Takes an image and modifies it so that all pixels outside the image area 383Takes an image and modifies it so that all pixels outside the image area
175become transparent. This mode is most useful when you want to place an 384become transparent. This mode is most useful when you want to place an
176image over another image or the background colour while leaving all 385image over another image or the background colour while leaving all
177background pixels outside the image unchanged. 386background pixels outside the image unchanged.
178 387
388Example: load an image and display it in the upper left corner. The rest
389of the space is left "empty" (transparent or wahtever your compisotr does
390in alpha mode, else background colour).
391
392 pad load "mybg.png"
393
179=item extend $img 394=item extend $img
180 395
181Extends the image over the whole plane, using the closest pixel in the 396Extends the image over the whole plane, using the closest pixel in the
182area outside the image. This mode is mostly useful when you more complex 397area outside the image. This mode is mostly useful when you more complex
183filtering operations and want the pixels outside the image to have the 398filtering operations and want the pixels outside the image to have the
184same values as the pixels near the edge. 399same values as the pixels near the edge.
400
401Example: just for curiosity, how does this pixel extension stuff work?
402
403 extend move 50, 50, load "mybg.png"
185 404
186=cut 405=cut
187 406
188 sub pad($) { 407 sub pad($) {
189 my $img = $_[0]->clone; 408 my $img = $_[0]->clone;
277 496
278=cut 497=cut
279 498
280#TODO: maximise, maximise_fill? 499#TODO: maximise, maximise_fill?
281 500
282 sub scale($$$) { 501 sub scale($;$;$) {
283 my $img = pop; 502 my $img = pop;
284 503
285 @_ == 2 ? $img->scale ($_[0] * $img->w * 0.01, $_[1] * $img->h * 0.01) 504 @_ == 2 ? $img->scale ($_[0] * $img->w * 0.01, $_[1] * $img->h * 0.01)
286 : @_ ? $img->scale ($_[0] * $img->w * 0.01, $_[0] * $img->h * 0.01) 505 : @_ ? $img->scale ($_[0] * $img->w * 0.01, $_[0] * $img->h * 0.01)
287 : $img->scale (TW, TH) 506 : $img->scale (TW, TH)
289 508
290 sub resize($$$) { 509 sub resize($$$) {
291 my $img = pop; 510 my $img = pop;
292 $img->scale ($_[0], $_[1]) 511 $img->scale ($_[0], $_[1])
293 } 512 }
513
514=item move $dx, $dy, $img
515
516Moves the image by C<$dx> pixels in the horizontal, and C<$dy> pixels in
517the vertical.
518
519Example: move the image right by 20 pixels and down by 30.
520
521 move 20, 30, ...
522
523=item rootalign $img
524
525Moves the image so that it appears glued to the screen as opposed to the
526window. This gives the illusion of a larger area behind the window. It is
527exactly equivalent to C<move -TX, -TY>, that is, it moves the image to the
528top left of the screen.
529
530Example: load a background image, put it in mirror mode and root align it.
531
532 rootalign mirror load "mybg.png"
533
534Example: take the screen background and align it, giving the illusion of
535transparency as long as the window isn't in front of other windows.
536
537 rootalign root
538
539=cut
294 540
295 sub move($$;$) { 541 sub move($$;$) {
296 my $img = pop->clone; 542 my $img = pop->clone;
297 $img->move ($_[0], $_[1]); 543 $img->move ($_[0], $_[1]);
298 $img 544 $img
299 } 545 }
546
547 sub rootalign($) {
548 move -TX, -TY, $_[0]
549 }
550
551=item contrast $factor, $img
552
553=item contrast $r, $g, $b, $img
554
555=item contrast $r, $g, $b, $a, $img
556
557Adjusts the I<contrast> of an image.
558
559#TODO#
560
561=item brightness $factor, $img
562
563=item brightness $r, $g, $b, $img
564
565=item brightness $r, $g, $b, $a, $img
566
567Adjusts the brightness of an image.
568
569=cut
570
571 sub contrast($$;$$;$) {
572 my $img = pop;
573 my ($r, $g, $b, $a) = @_;
574
575 ($g, $b) = ($r, $r) if @_ < 4;
576 $a = 1 if @_ < 5;
577
578 $img = $img->clone;
579 $img->contrast ($r, $g, $b, $a);
580 $img
581 }
582
583 sub brightness($$;$$;$) {
584 my $img = pop;
585 my ($r, $g, $b, $a) = @_;
586
587 ($g, $b) = ($r, $r) if @_ < 4;
588 $a = 1 if @_ < 5;
589
590 $img = $img->clone;
591 $img->brightness ($r, $g, $b, $a);
592 $img
593 }
594
595=item blur $radius, $img
596
597=item blur $radius_horz, $radius_vert, $img
598
599Gaussian-blurs the image with (roughly) C<$radius> pixel radius. The radii
600can also be specified separately.
601
602Blurring is often I<very> slow, at least compared or other
603operators. Larger blur radii are slower than smaller ones, too, so if you
604don't want to freeze your screen for long times, start experimenting with
605low values for radius (<5).
606
607=cut
608
609 sub blur($$;$) {
610 my $img = pop;
611 $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
612 }
613
614=item rotate $new_width, $new_height, $center_x, $center_y, $degrees
615
616Rotates the image by C<$degrees> degrees, counter-clockwise, around the
617pointer at C<$center_x> and C<$center_y> (specified as percentage of image
618width/height), generating a new image with width C<$new_width> and height
619C<$new_height>.
620
621#TODO# new width, height, maybe more operators?
622
623Example: rotate the image by 90 degrees
624
625=cut
300 626
301 sub rotate($$$$$$) { 627 sub rotate($$$$$$) {
302 my $img = pop; 628 my $img = pop;
303 $img->rotate ( 629 $img->rotate (
304 $_[0], 630 $_[0],
307 $_[3] * $img->h * .01, 633 $_[3] * $img->h * .01,
308 $_[4] * (3.14159265 / 180), 634 $_[4] * (3.14159265 / 180),
309 ) 635 )
310 } 636 }
311 637
312 sub blur($$;$) {
313 my $img = pop;
314 $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
315 }
316
317 sub contrast($$;$$;$) {
318 my $img = pop;
319 my ($r, $g, $b, $a) = @_;
320
321 ($g, $b) = ($r, $r) if @_ < 4;
322 $a = 1 if @_ < 5;
323
324 $img = $img->clone;
325 $img->contrast ($r, $g, $b, $a);
326 $img
327 }
328
329 sub brightness($$;$$;$) {
330 my $img = pop;
331 my ($r, $g, $b, $a) = @_;
332
333 ($g, $b) = ($r, $r) if @_ < 4;
334 $a = 1 if @_ < 5;
335
336 $img = $img->clone;
337 $img->brightness ($r, $g, $b, $a);
338 $img
339 }
340
341=back 638=back
342 639
343=cut 640=cut
344 641
345} 642}
358 $self->recalculate; 655 $self->recalculate;
359} 656}
360 657
361# evaluate the current bg expression 658# evaluate the current bg expression
362sub recalculate { 659sub recalculate {
363 my ($self) = @_; 660 my ($arg_self) = @_;
364 661
365 # rate limit evaluation 662 # rate limit evaluation
366 663
367 if ($self->{next_refresh} > urxvt::NOW) { 664 if ($arg_self->{next_refresh} > urxvt::NOW) {
368 $self->{next_refresh_timer} = urxvt::timer->new->after ($self->{next_refresh} - urxvt::NOW)->cb (sub { 665 $arg_self->{next_refresh_timer} = urxvt::timer->new->after ($arg_self->{next_refresh} - urxvt::NOW)->cb (sub {
369 $self->recalculate; 666 $arg_self->recalculate;
370 }); 667 });
371 return; 668 return;
372 } 669 }
373 670
374 $self->{next_refresh} = urxvt::NOW + $MIN_INTERVAL; 671 $arg_self->{next_refresh} = urxvt::NOW + $MIN_INTERVAL;
375 672
376 # set environment to evaluate user expression 673 # set environment to evaluate user expression
377 674
378 local $bgdsl_self = $self; 675 local $self = $arg_self;
379 676
677 local $HOME = $ENV{HOME};
380 local $old = $self->{state}; 678 local $old = $self->{state};
381 local $new = my $state = $self->{state} = {}; 679 local $new = my $state = $self->{state} = {};
382 680
383 my $border = 0; #d#
384
385 ($x, $y, $w, $h) = 681 ($x, $y, $w, $h) =
386 $self->background_geometry ($border); 682 $self->background_geometry ($self->{border});
387 683
388 # evaluate user expression 684 # evaluate user expression
389 685
390 my $img = eval { $self->{expr}->() }; 686 my $img = eval { $self->{expr}->() };
391 warn $@ if $@;#d# 687 warn $@ if $@;#d#
392 die if !UNIVERSAL::isa $img, "urxvt::img"; 688 die if !UNIVERSAL::isa $img, "urxvt::img";
393 689
690 $state->{size_sensitive} = 1
691 if $img->repeat_mode != urxvt::RepeatNormal;
692
394 # if the expression is sensitive to external events, prepare reevaluation then 693 # if the expression is sensitive to external events, prepare reevaluation then
395 694
396 my $repeat; 695 my $repeat;
397 696
398 if (my $again = $state->{again}) { 697 if (my $again = $state->{again}) {
399 $repeat = 1; 698 $repeat = 1;
699 my $self = $self;
400 $state->{timer} = $again == $old->{again} 700 $state->{timer} = $again == $old->{again}
401 ? $old->{timer} 701 ? $old->{timer}
402 : urxvt::timer->new->after ($again)->interval ($again)->cb (sub { 702 : urxvt::timer->new->after ($again)->interval ($again)->cb (sub {
403 ++$self->{counter}; 703 ++$self->{counter};
404 $self->recalculate 704 $self->recalculate
433 unless ($repeat) { 733 unless ($repeat) {
434 delete $self->{state}; 734 delete $self->{state};
435 delete $self->{expr}; 735 delete $self->{expr};
436 } 736 }
437 737
438 # prepare and set background pixmap 738 # set background pixmap
439 739
440 $img = $img->sub_rect (0, 0, $w, $h)
441 if $img->w != $w || $img->h != $h;
442
443 $self->set_background ($img, $border); 740 $self->set_background ($img, $self->{border});
444 $self->scr_recolour (0); 741 $self->scr_recolour (0);
445 $self->want_refresh; 742 $self->want_refresh;
446} 743}
447 744
448sub on_start { 745sub on_start {
449 my ($self) = @_; 746 my ($self) = @_;
450 747
748 my $expr = $self->x_resource ("background.expr")
749 or return;
750
451 $self->set_expr (parse_expr $EXPR); 751 $self->set_expr (parse_expr $expr);
752 $self->{border} = $self->x_resource_boolean ("background.border");
452 753
453 () 754 ()
454} 755}
455 756

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines