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.8 by root, Tue Jun 5 14:07:47 2012 UTC vs.
Revision 1.38 by root, Fri Jun 8 21:48:07 2012 UTC

1#! perl 1#! perl
2 2
3our $EXPR = 'move load "/root/pix/das_fette_schwein.jpg", repeat_wrap, X, Y'; 3#:META:X_RESOURCE:%.expr:string:background expression
4#:META:X_RESOURCE:%.border.:boolean:respect the terminal border
5
6#TODO: once, rootalign
7
8=head1 background - manage terminal background
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
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
126=head2 REFERENCE
127
128=head3 COMMAND LINE SWITCHES
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
148our $EXPR;#d#
149#$EXPR = 'move W * 0.1, -H * 0.1, resize W * 0.5, H * 0.5, repeat_none load "opensource.png"';
150$EXPR = 'move -TX, -TY, load "argb.png"';
4$EXPR = ' 151#$EXPR = '
5 blur 10, 10,
6 rotate W, H, 50, 50, counter 1/60, repeat_mirror, 152# rotate W, H, 50, 50, counter 1/59.95, repeat_mirror,
7 clip X, Y, W, H, repeat_mirror, 153# clip X, Y, W, H, repeat_mirror,
8 load "/root/pix/das_fette_schwein.jpg" 154# load "/root/pix/das_fette_schwein.jpg"
9'; 155#';
156#$EXPR = 'solid "red"';
10#$EXPR = 'blur root, 10, 10' 157#$EXPR = 'blur root, 10, 10'
11#$EXPR = 'blur move (root, -x, -y), 5, 5' 158#$EXPR = 'blur move (root, -x, -y), 5, 5'
12#resize load "/root/pix/das_fette_schwein.jpg", w, h 159#resize load "/root/pix/das_fette_schwein.jpg", w, h
13 160
14use Safe; 161our $HOME;
15
16our ($bgdsl_self, $old, $new); 162our ($self, $old, $new);
17our ($l, $t, $w, $h); 163our ($x, $y, $w, $h);
164
165# enforce at least this interval between updates
166our $MIN_INTERVAL = 1/100;
18 167
19{ 168{
20 package urxvt::bgdsl; # background language 169 package urxvt::bgdsl; # background language
21 170
22 *repeat_black = \&urxvt::RepeatNone; #TODO wtf 171=head2 PROVIDERS/GENERATORS
23 *repeat_wrap = \&urxvt::RepeatNormal; 172
24 *repeat_pad = \&urxvt::RepeatPad; 173These functions provide an image, by loading it from disk, grabbing it
25 *repeat_mirror = \&urxvt::RepeatReflect; 174from the root screen or by simply generating it. They are used as starting
175points to get an image you can play with.
176
177=over 4
178
179=item load $path
180
181Loads the image at the given C<$path>. The image is set to plane tiling
182mode.
183
184Loaded images will be cached for one cycle.
185
186=cut
26 187
27 sub load($) { 188 sub load($) {
28 my ($path) = @_; 189 my ($path) = @_;
29 190
30 $new->{load}{$path} = $old->{load}{$path} || $bgdsl_self->new_img_from_file ($path); 191 $new->{load}{$path} = $old->{load}{$path} || $self->new_img_from_file ($path);
31 } 192 }
193
194=item root
195
196Returns the root window pixmap, that is, hopefully, the background image
197of your screen. The image is set to extend mode.
198
199This function makes your expression root sensitive, that means it will be
200reevaluated when the bg image changes.
201
202=cut
32 203
33 sub root() { 204 sub root() {
205 $new->{rootpmap_sensitive} = 1;
34 die "root op not supported, exg, we need you"; 206 die "root op not supported, exg, we need you";
35 } 207 }
36 208
209=item solid $colour
210
211=item solid $width, $height, $colour
212
213Creates a new image and completely fills it with the given colour. The
214image is set to tiling mode.
215
216If <$width> and C<$height> are omitted, it creates a 1x1 image, which is
217useful for solid backgrounds or for use in filtering effects.
218
219=cut
220
221 sub solid($$;$) {
222 my $colour = pop;
223
224 my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1);
225 $img->fill ($colour);
226 $img
227 }
228
229=back
230
231=head2 VARIABLES
232
233The following functions provide variable data such as the terminal
234window dimensions. Most of them make your expression sensitive to some
235events, for example using C<TW> (terminal width) means your expression is
236evaluated again when the terminal is resized.
237
238=over 4
239
240=item TX
241
242=item TY
243
244Return the X and Y coordinates of the terminal window (the terminal
245window is the full window by default, and the character area only when in
246border-respect mode).
247
248Using these functions make your expression sensitive to window moves.
249
250These functions are mainly useful to align images to the root window.
251
252Example: load an image and align it so it looks as if anchored to the
253background.
254
255 move -TX, -TY, load "mybg.png"
256
257=item TW
258
259Return the width (C<TW>) and height (C<TH>) of the terminal window (the
260terminal window is the full window by default, and the character area only
261when in border-respect mode).
262
263Using these functions make your expression sensitive to window resizes.
264
265These functions are mainly useful to scale images, or to clip images to
266the window size to conserve memory.
267
268Example: take the screen background, clip it to the window size, blur it a
269bit, align it to the window position and use it as background.
270
271 clip move -TX, -TY, blur 5, root
272
273=cut
274
275 sub TX() { $new->{position_sensitive} = 1; $x }
276 sub TY() { $new->{position_sensitive} = 1; $y }
277 sub TW() { $new->{size_sensitive} = 1; $w }
278 sub TH() { $new->{size_sensitive} = 1; $h }
279
280=item now
281
282Returns the current time as (fractional) seconds since the epoch.
283
284Using this expression does I<not> make your expression sensitive to time,
285but the next two functions do.
286
287=item again $seconds
288
289When this function is used the expression will be reevaluated again in
290C<$seconds> seconds.
291
292Example: load some image and rotate it according to the time of day (as if it were
293the hour pointer of a clock). Update this image every minute.
294
295 again 60; rotate TW, TH, 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png"
296
297=item counter $seconds
298
299Like C<again>, but also returns an increasing counter value, starting at
3000, which might be useful for some simple animation effects.
301
302=cut
303
304 sub now() { urxvt::NOW }
305
306 sub again($) {
307 $new->{again} = $_[0];
308 }
309
310 sub counter($) {
311 $new->{again} = $_[0];
312 $self->{counter} + 0
313 }
314
315=back
316
317=head2 TILING MODES
318
319The following operators modify the tiling mode of an image, that is, the
320way that pixels outside the image area are painted when the image is used.
321
322=over 4
323
324=item tile $img
325
326Tiles the whole plane with the image and returns this new image - or in
327other words, it returns a copy of the image in plane tiling mode.
328
329Example: load an image and tile it over the background, without
330resizing. The C<tile> call is superfluous because C<load> already defaults
331to tiling mode.
332
333 tile load "mybg.png"
334
335=item mirror $img
336
337Similar to tile, but reflects the image each time it uses a new copy, so
338that top edges always touch top edges, right edges always touch right
339edges and so on (with normal tiling, left edges always touch right edges
340and top always touch bottom edges).
341
342Example: load an image and mirror it over the background, avoiding sharp
343edges at the image borders at the expense of mirroring the image itself
344
345 mirror load "mybg.png"
346
347=item pad $img
348
349Takes an image and modifies it so that all pixels outside the image area
350become transparent. This mode is most useful when you want to place an
351image over another image or the background colour while leaving all
352background pixels outside the image unchanged.
353
354Example: load an image and display it in the upper left corner. The rest
355of the space is left "empty" (transparent or wahtever your compisotr does
356in alpha mode, else background colour).
357
358 pad load "mybg.png"
359
360=item extend $img
361
362Extends the image over the whole plane, using the closest pixel in the
363area outside the image. This mode is mostly useful when you more complex
364filtering operations and want the pixels outside the image to have the
365same values as the pixels near the edge.
366
367Example: just for curiosity, how does this pixel extension stuff work?
368
369 extend move 50, 50, load "mybg.png"
370
371=cut
372
373 sub pad($) {
374 my $img = $_[0]->clone;
375 $img->repeat_mode (urxvt::RepeatNone);
376 $img
377 }
378
379 sub tile($) {
380 my $img = $_[0]->clone;
381 $img->repeat_mode (urxvt::RepeatNormal);
382 $img
383 }
384
385 sub mirror($) {
386 my $img = $_[0]->clone;
387 $img->repeat_mode (urxvt::RepeatReflect);
388 $img
389 }
390
391 sub extend($) {
392 my $img = $_[0]->clone;
393 $img->repeat_mode (urxvt::RepeatPad);
394 $img
395 }
396
397=back
398
399=head2 PIXEL OPERATORS
400
401The following operators modify the image pixels in various ways.
402
403=over 4
404
405=item clone $img
406
407Returns an exact copy of the image.
408
409=cut
410
37# sub clone($) { 411 sub clone($) {
38# $_[0]->clone 412 $_[0]->clone
39# } 413 }
40 414
415=item clip $img
416
417=item clip $width, $height, $img
418
419=item clip $x, $y, $width, $height, $img
420
421Clips an image to the given rectangle. If the rectangle is outside the
422image area (e.g. when C<$x> or C<$y> are negative) or the rectangle is
423larger than the image, then the tiling mode defines how the extra pixels
424will be filled.
425
426If C<$x> an C<$y> are missing, then C<0> is assumed for both.
427
428If C<$width> and C<$height> are missing, then the window size will be
429assumed.
430
431Example: load an image, blur it, and clip it to the window size to save
432memory.
433
434 clip blur 10, load "mybg.png"
435
436=cut
437
41 sub clip($$$$$;$) { 438 sub clip($;$$;$$) {
42 my $img = pop; 439 my $img = pop;
440 my $h = pop || TH;
441 my $w = pop || TW;
43 $img->sub_rect ($_[0], $_[1], $_[2], $_[3], $_[4]) 442 $img->sub_rect ($_[0], $_[1], $w, $h)
443 }
444
445=item scale $img
446
447=item scale $size_percent, $img
448
449=item scale $width_percent, $height_percent, $img
450
451Scales the image by the given percentages in horizontal
452(C<$width_percent>) and vertical (C<$height_percent>) direction.
453
454If only one percentage is give, it is used for both directions.
455
456If no percentages are given, scales the image to the window size without
457keeping aspect.
458
459=item resize $width, $height, $img
460
461Resizes the image to exactly C<$width> times C<$height> pixels.
462
463=cut
464
465#TODO: maximise, maximise_fill?
466
467 sub scale($;$;$) {
468 my $img = pop;
469
470 @_ == 2 ? $img->scale ($_[0] * $img->w * 0.01, $_[1] * $img->h * 0.01)
471 : @_ ? $img->scale ($_[0] * $img->w * 0.01, $_[0] * $img->h * 0.01)
472 : $img->scale (TW, TH)
44 } 473 }
45 474
46 sub resize($$$) { 475 sub resize($$$) {
47 my $img = pop; 476 my $img = pop;
48 $img->scale ($_[0], $_[1]) 477 $img->scale ($_[0], $_[1])
49 } 478 }
50 479
51 # TODO: ugly 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
52 sub move($$;$) { 507 sub move($$;$) {
508 my $img = pop->clone;
509 $img->move ($_[0], $_[1]);
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#TODO#
526
527=item brightness $factor, $img
528
529=item brightness $r, $g, $b, $img
530
531=item brightness $r, $g, $b, $a, $img
532
533Adjusts the brightness of an image.
534
535=cut
536
537 sub contrast($$;$$;$) {
53 my $img = pop; 538 my $img = pop;
54 $img->sub_rect ( 539 my ($r, $g, $b, $a) = @_;
55 $_[0], $_[1],
56 $img->w, $img->h,
57 $_[2],
58 )
59 }
60 540
541 ($g, $b) = ($r, $r) if @_ < 4;
542 $a = 1 if @_ < 5;
543
544 $img = $img->clone;
545 $img->contrast ($r, $g, $b, $a);
546 $img
547 }
548
549 sub brightness($$;$$;$) {
550 my $img = pop;
551 my ($r, $g, $b, $a) = @_;
552
553 ($g, $b) = ($r, $r) if @_ < 4;
554 $a = 1 if @_ < 5;
555
556 $img = $img->clone;
557 $img->brightness ($r, $g, $b, $a);
558 $img
559 }
560
561=item blur $radius, $img
562
563=item blur $radius_horz, $radius_vert, $img
564
565Gaussian-blurs the image with (roughly) C<$radius> pixel radius. The radii
566can also be specified separately.
567
568=cut
569
570 sub blur($$;$) {
571 my $img = pop;
572 $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
573 }
574
575=item rotate $new_width, $new_height, $center_x, $center_y, $degrees
576
577Rotates the image by C<$degrees> degrees, counter-clockwise, around the
578pointer at C<$center_x> and C<$center_y> (specified as percentage of image
579width/height), generating a new image with width C<$new_width> and height
580C<$new_height>.
581
582#TODO# new width, height, maybe more operators?
583
584Example: rotate the image by 90 degrees
585
586=cut
587
61 sub rotate($$$$$$;$) { 588 sub rotate($$$$$$) {
62 my $img = pop; 589 my $img = pop;
63 $img->rotate ( 590 $img->rotate (
64 $_[0], 591 $_[0],
65 $_[1], 592 $_[1],
66 $_[2] * $img->w * .01, 593 $_[2] * $img->w * .01,
67 $_[3] * $img->h * .01, 594 $_[3] * $img->h * .01,
68 $_[4] * (3.14159265 / 180), 595 $_[4] * (3.14159265 / 180),
69 $_[5],
70 ) 596 )
71 } 597 }
72 598
73 sub blur($$$) { 599=back
74 my ($rh, $rv, $img) = @_;
75 600
76 $img = $img->clone; 601=cut
77 $img->blur ($rh, $rv);
78 $img
79 }
80 602
81 sub contrast($$;$$;$) {
82 my $img = pop;
83 my ($r, $g, $b, $a) = @_;
84
85 ($g, $b) = ($r, $r) if @_ < 4;
86 $a = 1 if @_ < 5;
87
88 $img = $img->clone;
89 $img->contrast ($r, $g, $b, $a);
90 $img
91 }
92
93 sub brightness($$;$$;$) {
94 my $img = pop;
95 my ($r, $g, $b, $a) = @_;
96
97 ($g, $b) = ($r, $r) if @_ < 4;
98 $a = 1 if @_ < 5;
99
100 $img = $img->clone;
101 $img->brightness ($r, $g, $b, $a);
102 $img
103 }
104
105 sub X() { $new->{position_sensitive} = 1; $l }
106 sub Y() { $new->{position_sensitive} = 1; $t }
107 sub W() { $new->{size_sensitive} = 1; $w }
108 sub H() { $new->{size_sensitive} = 1; $h }
109
110 sub now() { urxvt::NOW }
111
112 sub again($) {
113 $new->{again} = $_[0];
114 }
115
116 sub counter($) {
117 $new->{again} = $_[0];
118 $bgdsl_self->{counter} + 0
119 }
120} 603}
121 604
122sub parse_expr { 605sub parse_expr {
123 my $expr = eval "sub {\npackage urxvt::bgdsl;\n#line 0 'background expression'\n$_[0]\n}"; 606 my $expr = eval "sub {\npackage urxvt::bgdsl;\n#line 0 'background expression'\n$_[0]\n}";
124 die if $@; 607 die if $@;
133 $self->recalculate; 616 $self->recalculate;
134} 617}
135 618
136# evaluate the current bg expression 619# evaluate the current bg expression
137sub recalculate { 620sub recalculate {
138 my ($self) = @_; 621 my ($arg_self) = @_;
139 622
140 #TODO: rate limit calls 623 # rate limit evaluation
141 624
142 local $bgdsl_self = $self; 625 if ($arg_self->{next_refresh} > urxvt::NOW) {
626 $arg_self->{next_refresh_timer} = urxvt::timer->new->after ($arg_self->{next_refresh} - urxvt::NOW)->cb (sub {
627 $arg_self->recalculate;
628 });
629 return;
630 }
143 631
632 $arg_self->{next_refresh} = urxvt::NOW + $MIN_INTERVAL;
633
634 # set environment to evaluate user expression
635
636 local $self = $arg_self;
637
638 local $HOME = $ENV{HOME};
144 local $old = $self->{state}; 639 local $old = $self->{state};
145 local $new = my $state = $self->{state} = {}; 640 local $new = my $state = $self->{state} = {};
146 641
147 ($l, $t, $w, $h) = 642 ($x, $y, $w, $h) =
148 $self->get_geometry; 643 $self->background_geometry ($self->{border});
644
645 # evaluate user expression
149 646
150 my $img = eval { $self->{expr}->() }; 647 my $img = eval { $self->{expr}->() };
151 warn $@ if $@;#d# 648 warn $@ if $@;#d#
649 die if !UNIVERSAL::isa $img, "urxvt::img";
650
651 $state->{size_sensitive} = 1
652 if $img->repeat_mode != urxvt::RepeatNormal;
653
654 # if the expression is sensitive to external events, prepare reevaluation then
152 655
153 my $repeat; 656 my $repeat;
154 657
155 if (my $again = $state->{again}) { 658 if (my $again = $state->{again}) {
156 $repeat = 1; 659 $repeat = 1;
660 my $self = $self;
157 $state->{timer} = $again == $old->{again} 661 $state->{timer} = $again == $old->{again}
158 ? $old->{timer} 662 ? $old->{timer}
159 : urxvt::timer->new->after ($again)->interval ($again)->cb (sub { 663 : urxvt::timer->new->after ($again)->interval ($again)->cb (sub {
160 ++$self->{counter}; 664 ++$self->{counter};
161 $self->recalculate 665 $self->recalculate
174 $self->enable (size_change => sub { $_[0]->recalculate }); 678 $self->enable (size_change => sub { $_[0]->recalculate });
175 } else { 679 } else {
176 $self->disable ("size_change"); 680 $self->disable ("size_change");
177 } 681 }
178 682
683 if (delete $state->{rootpmap_sensitive}) {
684 $repeat = 1;
685 $self->enable (rootpmap_change => sub { $_[0]->recalculate });
686 } else {
687 $self->disable ("rootpmap_change");
688 }
689
690 # clear stuff we no longer need
691
179 %$old = (); 692 %$old = ();
180 693
181 unless ($repeat) { 694 unless ($repeat) {
182 delete $self->{state}; 695 delete $self->{state};
183 delete $self->{expr}; 696 delete $self->{expr};
184 } 697 }
185 698
186 $img = $img->sub_rect (0, 0, $w, $h) 699 # set background pixmap
187 if $img->w != $w || $img->h != $h;
188 700
189 $self->set_background ($img); 701 $self->set_background ($img, $self->{border});
190 $self->scr_recolour (0); 702 $self->scr_recolour (0);
191 $self->want_refresh; 703 $self->want_refresh;
192} 704}
193 705
194sub on_start { 706sub on_start {
195 my ($self) = @_; 707 my ($self) = @_;
196 708
709 my $expr = $self->x_resource ("background.expr")
710 or return;
711
197 $self->set_expr (parse_expr $EXPR); 712 $self->set_expr (parse_expr $expr);
713 $self->{border} = $self->x_resource_boolean ("background.border");
198 714
199 () 715 ()
200} 716}
201 717

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines