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.35 by root, Fri Jun 8 08:06:38 2012 UTC vs.
Revision 1.36 by root, Fri Jun 8 20:23:09 2012 UTC

7 7
8=head1 background - manage terminal background 8=head1 background - manage terminal background
9 9
10=head2 SYNOPSIS 10=head2 SYNOPSIS
11 11
12 rxvt -background-expr 'background expression' 12 urxvt --background-expr 'background expression'
13 -background-border 13 --background-border
14 14
15=head2 DESCRIPTION 15=head2 DESCRIPTION
16 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
117TODO
118
119=head3 CYCLES AND CACHING
120
121TODO
122
123Each time the expression is reevaluated, a new cycle is said to have begun. Many operators
124cache their results till the next cycle. For example
125
17=head2 REFERENCE 126=head2 REFERENCE
18 127
19=cut 128=head3 COMMAND LINE SWITCHES
20 129
130=over 4
131
132=item --background-expr perl-expression
133
134Specifies the Perl expression to evaluate.
135
136=item --background-border
137
138By default, the expression creates an image that fills the full window,
139overwriting borders and any other areas, such as the scrollbar.
140
141Specifying this flag changes the behaviour, so that the image only
142replaces the background of the character area.
143
144=back
145
146=cut
147
21our $EXPR; 148our $EXPR;#d#
22#$EXPR = 'move W * 0.1, -H * 0.1, resize W * 0.5, H * 0.5, repeat_none load "opensource.png"'; 149#$EXPR = 'move W * 0.1, -H * 0.1, resize W * 0.5, H * 0.5, repeat_none load "opensource.png"';
23$EXPR = 'move -TX, -TY, load "argb.png"'; 150$EXPR = 'move -TX, -TY, load "argb.png"';
24#$EXPR = ' 151#$EXPR = '
25# rotate W, H, 50, 50, counter 1/59.95, repeat_mirror, 152# rotate W, H, 50, 50, counter 1/59.95, repeat_mirror,
26# clip X, Y, W, H, repeat_mirror, 153# clip X, Y, W, H, repeat_mirror,
29#$EXPR = 'solid "red"'; 156#$EXPR = 'solid "red"';
30#$EXPR = 'blur root, 10, 10' 157#$EXPR = 'blur root, 10, 10'
31#$EXPR = 'blur move (root, -x, -y), 5, 5' 158#$EXPR = 'blur move (root, -x, -y), 5, 5'
32#resize load "/root/pix/das_fette_schwein.jpg", w, h 159#resize load "/root/pix/das_fette_schwein.jpg", w, h
33 160
161our $HOME;
34our ($self, $old, $new); 162our ($self, $old, $new);
35our ($x, $y, $w, $h); 163our ($x, $y, $w, $h);
36 164
37# enforce at least this interval between updates 165# enforce at least this interval between updates
38our $MIN_INTERVAL = 1/100; 166our $MIN_INTERVAL = 1/100;
160 288
161When this function is used the expression will be reevaluated again in 289When this function is used the expression will be reevaluated again in
162C<$seconds> seconds. 290C<$seconds> seconds.
163 291
164Example: load some image and rotate it according to the time of day (as if it were 292Example: load some image and rotate it according to the time of day (as if it were
165the hour pointer of a clock). update this image every minute. 293the hour pointer of a clock). Update this image every minute.
166 294
167 again 60; rotate TW, TH, 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png" 295 again 60; rotate TW, TH, 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png"
168 296
169=item counter $seconds 297=item counter $seconds
170 298
209Similar to tile, but reflects the image each time it uses a new copy, so 337Similar to tile, but reflects the image each time it uses a new copy, so
210that top edges always touch top edges, right edges always touch right 338that top edges always touch top edges, right edges always touch right
211edges and so on (with normal tiling, left edges always touch right edges 339edges and so on (with normal tiling, left edges always touch right edges
212and top always touch bottom edges). 340and top always touch bottom edges).
213 341
214Exmaple: load an image and mirror it over the background, avoiding sharp 342Example: load an image and mirror it over the background, avoiding sharp
215edges at the image borders at the expense of mirroring the image itself 343edges at the image borders at the expense of mirroring the image itself
216 344
217 mirror load "mybg.png" 345 mirror load "mybg.png"
218 346
219=item pad $img 347=item pad $img
221Takes an image and modifies it so that all pixels outside the image area 349Takes an image and modifies it so that all pixels outside the image area
222become transparent. This mode is most useful when you want to place an 350become transparent. This mode is most useful when you want to place an
223image over another image or the background colour while leaving all 351image over another image or the background colour while leaving all
224background pixels outside the image unchanged. 352background pixels outside the image unchanged.
225 353
226Example: load an image and display it in the upper left corner. The rets 354Example: load an image and display it in the upper left corner. The rest
227of the space is left "empty" (transparent or wahtever your compisotr does 355of the space is left "empty" (transparent or wahtever your compisotr does
228in alpha mode, else background colour). 356in alpha mode, else background colour).
229 357
230 pad load "mybg.png" 358 pad load "mybg.png"
231 359
347 sub resize($$$) { 475 sub resize($$$) {
348 my $img = pop; 476 my $img = pop;
349 $img->scale ($_[0], $_[1]) 477 $img->scale ($_[0], $_[1])
350 } 478 }
351 479
480=item move $dx, $dy, $img
481
482Moves the image by C<$dx> pixels in the horizontal, and C<$dy> pixels in
483the vertical.
484
485Example: move the image right by 20 pixels and down by 30.
486
487 move 20, 30, ...
488
489=item rootalign $img
490
491Moves the image so that it appears glued to the screen as opposed to the
492window. This gives the illusion of a larger area behind the window. It is
493exactly equivalent to C<move -TX, -TY>, that is, it moves the image to the
494top left of the screen.
495
496Example: load a background image, put it in mirror mode and root align it.
497
498 rootalign mirror load "mybg.png"
499
500Example: take the screen background and align it, giving the illusion of
501transparency as long as the window isn't in front of other windows.
502
503 rootalign root
504
505=cut
506
352 sub move($$;$) { 507 sub move($$;$) {
353 my $img = pop->clone; 508 my $img = pop->clone;
354 $img->move ($_[0], $_[1]); 509 $img->move ($_[0], $_[1]);
355 $img 510 $img
511 }
512
513 sub rootalign($) {
514 move -TX, -TY, $_[0]
515 }
516
517=item contrast $factor, $img
518
519=item contrast $r, $g, $b, $img
520
521=item contrast $r, $g, $b, $a, $img
522
523Adjusts the I<contrast> of an image.
524
525=item brightness $factor, $img
526
527=item brightness $r, $g, $b, $img
528
529=item brightness $r, $g, $b, $a, $img
530
531=cut
532
533 sub contrast($$;$$;$) {
534 my $img = pop;
535 my ($r, $g, $b, $a) = @_;
536
537 ($g, $b) = ($r, $r) if @_ < 4;
538 $a = 1 if @_ < 5;
539
540 $img = $img->clone;
541# $img->contrast ($r, $g, $b, $a);
542 $img
543 }
544
545 sub brightness($$;$$;$) {
546 my $img = pop;
547 my ($r, $g, $b, $a) = @_;
548
549 ($g, $b) = ($r, $r) if @_ < 4;
550 $a = 1 if @_ < 5;
551
552 $img = $img->clone;
553 $img->brightness ($r, $g, $b, $a);
554 $img
555 }
556
557 sub blur($$;$) {
558 my $img = pop;
559 $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
356 } 560 }
357 561
358 sub rotate($$$$$$) { 562 sub rotate($$$$$$) {
359 my $img = pop; 563 my $img = pop;
360 $img->rotate ( 564 $img->rotate (
364 $_[3] * $img->h * .01, 568 $_[3] * $img->h * .01,
365 $_[4] * (3.14159265 / 180), 569 $_[4] * (3.14159265 / 180),
366 ) 570 )
367 } 571 }
368 572
369 sub blur($$;$) {
370 my $img = pop;
371 $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
372 }
373
374 sub contrast($$;$$;$) {
375 my $img = pop;
376 my ($r, $g, $b, $a) = @_;
377
378 ($g, $b) = ($r, $r) if @_ < 4;
379 $a = 1 if @_ < 5;
380
381 $img = $img->clone;
382 $img->contrast ($r, $g, $b, $a);
383 $img
384 }
385
386 sub brightness($$;$$;$) {
387 my $img = pop;
388 my ($r, $g, $b, $a) = @_;
389
390 ($g, $b) = ($r, $r) if @_ < 4;
391 $a = 1 if @_ < 5;
392
393 $img = $img->clone;
394 $img->brightness ($r, $g, $b, $a);
395 $img
396 }
397
398=back 573=back
399 574
400=cut 575=cut
401 576
402} 577}
432 607
433 # set environment to evaluate user expression 608 # set environment to evaluate user expression
434 609
435 local $self = $arg_self; 610 local $self = $arg_self;
436 611
612 local $HOME = $ENV{HOME};
437 local $old = $self->{state}; 613 local $old = $self->{state};
438 local $new = my $state = $self->{state} = {}; 614 local $new = my $state = $self->{state} = {};
439 615
440 ($x, $y, $w, $h) = 616 ($x, $y, $w, $h) =
441 $self->background_geometry ($self->{border}); 617 $self->background_geometry ($self->{border});

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines