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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines