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.41 by root, Fri Jun 8 22:21:48 2012 UTC vs.
Revision 1.51 by sf-exg, Sun Jun 10 19:01: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:%.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:
99its result becomes the argument to the C<scale> function. 99its result becomes the argument to the C<scale> function.
100 100
101Many operators also allow some parameters preceding the input image 101Many operators also allow some parameters preceding the input image
102that modify its behaviour. For example, C<scale> without any additional 102that modify its behaviour. For example, C<scale> without any additional
103arguments scales the image to size of the terminal window. If you specify 103arguments scales the image to size of the terminal window. If you specify
104an additional argument, it uses it as a percentage: 104an additional argument, it uses it as a scale factor (multiply by 100 to
105get a percentage):
105 106
106 scale 200, load "$HOME/mypic.png" 107 scale 2, load "$HOME/mypic.png"
107 108
108This enlarges the image by a factor of 2 (200%). As you can see, C<scale> 109This 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 110has 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 111C<load> only has one argument. Arguments are separated from each other by
111commas. 112commas.
112 113
113Scale also accepts two arguments, which are then separate factors for both 114Scale also accepts two arguments, which are then separate factors for both
114horizontal and vertical dimensions. For example, this halves the image 115horizontal and vertical dimensions. For example, this halves the image
115width and doubles the image height: 116width and doubles the image height:
116 117
117 scale 50, 200, load "$HOME/mypic.png" 118 scale 0.5, 2, load "$HOME/mypic.png"
118 119
119Other effects than scalign are also readily available, for exmaple, you can 120Other effects than scaling are also readily available, for example, you can
120tile the image to fill the whole window, instead of resizing it: 121tile the image to fill the whole window, instead of resizing it:
121 122
122 tile load "$HOME/mypic.png" 123 tile load "$HOME/mypic.png"
123 124
124In 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
150This 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
151image 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
152image, it will forget about the first one. 153image, it will forget about the first one.
153 154
154This 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
155memory, or comserve memory by loading images more often. 156memory, or conserve memory by loading images more often.
156 157
157For 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
158this: 159this:
159 160
160 my $img1 = load "img1.png"; 161 my $img1 = load "img1.png";
188overwriting borders and any other areas, such as the scrollbar. 189overwriting borders and any other areas, such as the scrollbar.
189 190
190Specifying this flag changes the behaviour, so that the image only 191Specifying this flag changes the behaviour, so that the image only
191replaces the background of the character area. 192replaces the background of the character area.
192 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
193=back 203=back
194 204
195=cut 205=cut
196 206
207our %_IMGCACHE;
197our $HOME; 208our $HOME;
198our ($self, $old, $new); 209our ($self, $old, $new);
199our ($x, $y, $w, $h); 210our ($x, $y, $w, $h);
200 211
201# enforce at least this interval between updates 212# enforce at least this interval between updates
202our $MIN_INTERVAL = 1/100; 213our $MIN_INTERVAL = 6/59.951;
203 214
204{ 215{
205 package urxvt::bgdsl; # background language 216 package urxvt::bgdsl; # background language
217
218 use List::Util qw(min max sum shuffle);
206 219
207=head2 PROVIDERS/GENERATORS 220=head2 PROVIDERS/GENERATORS
208 221
209These functions provide an image, by loading it from disk, grabbing it 222These functions provide an image, by loading it from disk, grabbing it
210from the root screen or by simply generating it. They are used as starting 223from the root screen or by simply generating it. They are used as starting
252If C<$width> and C<$height> are omitted, it creates a 1x1 image, which is 265If C<$width> and C<$height> are omitted, it creates a 1x1 image, which is
253useful for solid backgrounds or for use in filtering effects. 266useful for solid backgrounds or for use in filtering effects.
254 267
255=cut 268=cut
256 269
257 sub solid($$;$) { 270 sub solid($;$$) {
258 my $colour = pop; 271 my $colour = pop;
259 272
260 my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1); 273 my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1);
261 $img->fill ($colour); 274 $img->fill ($colour);
262 $img 275 $img
263 } 276 }
264 277
278=item clone $img
279
280Returns an exact copy of the image. This is useful if you want to have
281multiple copies of the same image to apply different effects to.
282
283=cut
284
285 sub clone($) {
286 $_[0]->clone
287 }
288
265=back 289=back
266 290
291=head2 TILING MODES
292
293The following operators modify the tiling mode of an image, that is, the
294way that pixels outside the image area are painted when the image is used.
295
296=over 4
297
298=item tile $img
299
300Tiles the whole plane with the image and returns this new image - or in
301other words, it returns a copy of the image in plane tiling mode.
302
303Example: load an image and tile it over the background, without
304resizing. The C<tile> call is superfluous because C<load> already defaults
305to tiling mode.
306
307 tile load "mybg.png"
308
309=item mirror $img
310
311Similar to tile, but reflects the image each time it uses a new copy, so
312that top edges always touch top edges, right edges always touch right
313edges and so on (with normal tiling, left edges always touch right edges
314and top always touch bottom edges).
315
316Example: load an image and mirror it over the background, avoiding sharp
317edges at the image borders at the expense of mirroring the image itself
318
319 mirror load "mybg.png"
320
321=item pad $img
322
323Takes an image and modifies it so that all pixels outside the image area
324become transparent. This mode is most useful when you want to place an
325image over another image or the background colour while leaving all
326background pixels outside the image unchanged.
327
328Example: load an image and display it in the upper left corner. The rest
329of the space is left "empty" (transparent or whatever your compositor does
330in alpha mode, else background colour).
331
332 pad load "mybg.png"
333
334=item extend $img
335
336Extends the image over the whole plane, using the closest pixel in the
337area outside the image. This mode is mostly useful when you use more complex
338filtering operations and want the pixels outside the image to have the
339same values as the pixels near the edge.
340
341Example: just for curiosity, how does this pixel extension stuff work?
342
343 extend move 50, 50, load "mybg.png"
344
345=cut
346
347 sub pad($) {
348 my $img = $_[0]->clone;
349 $img->repeat_mode (urxvt::RepeatNone);
350 $img
351 }
352
353 sub tile($) {
354 my $img = $_[0]->clone;
355 $img->repeat_mode (urxvt::RepeatNormal);
356 $img
357 }
358
359 sub mirror($) {
360 my $img = $_[0]->clone;
361 $img->repeat_mode (urxvt::RepeatReflect);
362 $img
363 }
364
365 sub extend($) {
366 my $img = $_[0]->clone;
367 $img->repeat_mode (urxvt::RepeatPad);
368 $img
369 }
370
371=back
372
267=head2 VARIABLES 373=head2 VARIABLE VALUES
268 374
269The following functions provide variable data such as the terminal window 375The following functions provide variable data such as the terminal window
270dimensions. They are not (Perl-) variables, they jsut return stuff that 376dimensions. They are not (Perl-) variables, they just return stuff that
271varies. Most of them make your expression sensitive to some events, for 377varies. Most of them make your expression sensitive to some events, for
272example using C<TW> (terminal width) means your expression is evaluated 378example using C<TW> (terminal width) means your expression is evaluated
273again when the terminal is resized. 379again when the terminal is resized.
274 380
275=over 4 381=over 4
349 $self->{counter} + 0 455 $self->{counter} + 0
350 } 456 }
351 457
352=back 458=back
353 459
354=head2 TILING MODES 460=head2 SHAPE CHANGING OPERATORS
355 461
356The following operators modify the tiling mode of an image, that is, the 462The following operators modify the shape, size or position of the image.
357way that pixels outside the image area are painted when the image is used.
358 463
359=over 4 464=over 4
360
361=item tile $img
362
363Tiles the whole plane with the image and returns this new image - or in
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"
371
372=item mirror $img
373
374Similar to tile, but reflects the image each time it uses a new copy, so
375that top edges always touch top edges, right edges always touch right
376edges and so on (with normal tiling, left edges always touch right edges
377and top always touch bottom edges).
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
384=item pad $img
385
386Takes an image and modifies it so that all pixels outside the image area
387become transparent. This mode is most useful when you want to place an
388image over another image or the background colour while leaving all
389background pixels outside the image unchanged.
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
397=item extend $img
398
399Extends the image over the whole plane, using the closest pixel in the
400area outside the image. This mode is mostly useful when you more complex
401filtering operations and want the pixels outside the image to have the
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"
407
408=cut
409
410 sub pad($) {
411 my $img = $_[0]->clone;
412 $img->repeat_mode (urxvt::RepeatNone);
413 $img
414 }
415
416 sub tile($) {
417 my $img = $_[0]->clone;
418 $img->repeat_mode (urxvt::RepeatNormal);
419 $img
420 }
421
422 sub mirror($) {
423 my $img = $_[0]->clone;
424 $img->repeat_mode (urxvt::RepeatReflect);
425 $img
426 }
427
428 sub extend($) {
429 my $img = $_[0]->clone;
430 $img->repeat_mode (urxvt::RepeatPad);
431 $img
432 }
433
434=back
435
436=head2 PIXEL OPERATORS
437
438The following operators modify the image pixels in various ways.
439
440=over 4
441
442=item clone $img
443
444Returns an exact copy of the image.
445
446=cut
447
448 sub clone($) {
449 $_[0]->clone
450 }
451 465
452=item clip $img 466=item clip $img
453 467
454=item clip $width, $height, $img 468=item clip $width, $height, $img
455 469
479 $img->sub_rect ($_[0], $_[1], $w, $h) 493 $img->sub_rect ($_[0], $_[1], $w, $h)
480 } 494 }
481 495
482=item scale $img 496=item scale $img
483 497
484=item scale $size_percent, $img 498=item scale $size_factor, $img
485 499
486=item scale $width_percent, $height_percent, $img 500=item scale $width_factor, $height_factor, $img
487 501
488Scales the image by the given percentages in horizontal 502Scales the image by the given factors in horizontal
489(C<$width_percent>) and vertical (C<$height_percent>) direction. 503(C<$width>) and vertical (C<$height>) direction.
490 504
491If only one percentage is give, it is used for both directions. 505If only one factor is give, it is used for both directions.
492 506
493If no percentages are given, scales the image to the window size without 507If no factors are given, scales the image to the window size without
494keeping aspect. 508keeping aspect.
495 509
496=item resize $width, $height, $img 510=item resize $width, $height, $img
497 511
498Resizes the image to exactly C<$width> times C<$height> pixels. 512Resizes the image to exactly C<$width> times C<$height> pixels.
499 513
500=cut 514=item fit $img
501 515
502#TODO: maximise, maximise_fill? 516=item fit $width, $height, $img
517
518Fits the image into the given C<$width> and C<$height> without changing
519aspect, or the terminal size. That means it will be shrunk or grown until
520the whole image fits into the given area, possibly leaving borders.
521
522=item cover $img
523
524=item cover $width, $height, $img
525
526Similar to C<fit>, but shrinks or grows until all of the area is covered
527by the image, so instead of potentially leaving borders, it will cut off
528image data that doesn't fit.
529
530=cut
503 531
504 sub scale($;$;$) { 532 sub scale($;$;$) {
505 my $img = pop; 533 my $img = pop;
506 534
507 @_ == 2 ? $img->scale ($_[0] * $img->w * 0.01, $_[1] * $img->h * 0.01) 535 @_ == 2 ? $img->scale ($_[0] * $img->w, $_[1] * $img->h)
508 : @_ ? $img->scale ($_[0] * $img->w * 0.01, $_[0] * $img->h * 0.01) 536 : @_ ? $img->scale ($_[0] * $img->w, $_[0] * $img->h)
509 : $img->scale (TW, TH) 537 : $img->scale (TW, TH)
510 } 538 }
511 539
512 sub resize($$$) { 540 sub resize($$$) {
513 my $img = pop; 541 my $img = pop;
514 $img->scale ($_[0], $_[1]) 542 $img->scale ($_[0], $_[1])
543 }
544
545 sub fit($;$$) {
546 my $img = pop;
547 my $w = ($_[0] || TW) / $img->w;
548 my $h = ($_[1] || TH) / $img->h;
549 scale +(min $w, $h), $img
550 }
551
552 sub cover($;$$) {
553 my $img = pop;
554 my $w = ($_[0] || TW) / $img->w;
555 my $h = ($_[1] || TH) / $img->h;
556 scale +(max $w, $h), $img
515 } 557 }
516 558
517=item move $dx, $dy, $img 559=item move $dx, $dy, $img
518 560
519Moves the image by C<$dx> pixels in the horizontal, and C<$dy> pixels in 561Moves the image by C<$dx> pixels in the horizontal, and C<$dy> pixels in
520the vertical. 562the vertical.
521 563
522Example: move the image right by 20 pixels and down by 30. 564Example: move the image right by 20 pixels and down by 30.
523 565
524 move 20, 30, ... 566 move 20, 30, ...
567
568=item align $xalign, $yalign, $img
569
570Aligns the image according to a factor - C<0> means the image is moved to
571the left or top edge (for C<$xalign> or C<$yalign>), C<0.5> means it is
572exactly centered and C<1> means it touches the right or bottom edge.
573
574Example: remove any visible border around an image, center it vertically but move
575it to the right hand side.
576
577 align 1, 0.5, pad $img
578
579=item center $img
580
581=item center $width, $height, $img
582
583Centers the image, i.e. the center of the image is moved to the center of
584the terminal window (or the box specified by C<$width> and C<$height> if
585given).
586
587Example: load an image and center it.
588
589 center pad load "mybg.png"
525 590
526=item rootalign $img 591=item rootalign $img
527 592
528Moves the image so that it appears glued to the screen as opposed to the 593Moves 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 594window. This gives the illusion of a larger area behind the window. It is
535 rootalign mirror load "mybg.png" 600 rootalign mirror load "mybg.png"
536 601
537Example: take the screen background and align it, giving the illusion of 602Example: take the screen background and align it, giving the illusion of
538transparency as long as the window isn't in front of other windows. 603transparency as long as the window isn't in front of other windows.
539 604
540 rootalign root 605 rootalign root
541 606
542=cut 607=cut
543 608
544 sub move($$;$) { 609 sub move($$;$) {
545 my $img = pop->clone; 610 my $img = pop->clone;
546 $img->move ($_[0], $_[1]); 611 $img->move ($_[0], $_[1]);
547 $img 612 $img
548 } 613 }
549 614
615 sub align($;$$) {
616 my $img = pop;
617
618 move $_[0] * (TW - $img->w),
619 $_[1] * (TH - $img->h),
620 $img
621 }
622
623 sub center($;$$) {
624 my $img = pop;
625 my $w = $_[0] || TW;
626 my $h = $_[1] || TH;
627
628 move 0.5 * ($w - $img->w), 0.5 * ($h - $img->h), $img
629 }
630
550 sub rootalign($) { 631 sub rootalign($) {
551 move -TX, -TY, $_[0] 632 move -TX, -TY, $_[0]
552 } 633 }
553 634
635=back
636
637=head2 COLOUR MODIFICATIONS
638
639The following operators change the pixels of the image.
640
641=over 4
642
554=item contrast $factor, $img 643=item contrast $factor, $img
555 644
556=item contrast $r, $g, $b, $img 645=item contrast $r, $g, $b, $img
557 646
558=item contrast $r, $g, $b, $a, $img 647=item contrast $r, $g, $b, $a, $img
559 648
560Adjusts the I<contrast> of an image. 649Adjusts the I<contrast> of an image.
561 650
562#TODO# 651The first form applies a single C<$factor> to red, green and blue, the
652second form applies separate factors to each colour channel, and the last
653form includes the alpha channel.
563 654
655Values from 0 to 1 lower the contrast, values higher than 1 increase the
656contrast.
657
658Due to limitations in the underlying XRender extension, lowering contrast
659also reduces brightness, while increasing contrast currently also
660increases brightness.
661
564=item brightness $factor, $img 662=item brightness $bias, $img
565 663
566=item brightness $r, $g, $b, $img 664=item brightness $r, $g, $b, $img
567 665
568=item brightness $r, $g, $b, $a, $img 666=item brightness $r, $g, $b, $a, $img
569 667
570Adjusts the brightness of an image. 668Adjusts the brightness of an image.
571 669
670The first form applies a single C<$bias> to red, green and blue, the
671second form applies separate biases to each colour channel, and the last
672form includes the alpha channel.
673
674Values less than 0 reduce brightness, while values larger than 0 increase
675it. Useful range is from -1 to 1 - the former results in a black, the
676latter in a white picture.
677
678Due to idiosyncrasies in the underlying XRender extension, biases less
679than zero can be I<very> slow.
680
572=cut 681=cut
573 682
574 sub contrast($$;$$;$) { 683 sub contrast($$;$$;$) {
575 my $img = pop; 684 my $img = pop;
576 my ($r, $g, $b, $a) = @_; 685 my ($r, $g, $b, $a) = @_;
577 686
578 ($g, $b) = ($r, $r) if @_ < 4; 687 ($g, $b) = ($r, $r) if @_ < 3;
579 $a = 1 if @_ < 5; 688 $a = 1 if @_ < 4;
580 689
581 $img = $img->clone; 690 $img = $img->clone;
582 $img->contrast ($r, $g, $b, $a); 691 $img->contrast ($r, $g, $b, $a);
583 $img 692 $img
584 } 693 }
585 694
586 sub brightness($$;$$;$) { 695 sub brightness($$;$$;$) {
587 my $img = pop; 696 my $img = pop;
588 my ($r, $g, $b, $a) = @_; 697 my ($r, $g, $b, $a) = @_;
589 698
590 ($g, $b) = ($r, $r) if @_ < 4; 699 ($g, $b) = ($r, $r) if @_ < 3;
591 $a = 1 if @_ < 5; 700 $a = 1 if @_ < 4;
592 701
593 $img = $img->clone; 702 $img = $img->clone;
594 $img->brightness ($r, $g, $b, $a); 703 $img->brightness ($r, $g, $b, $a);
595 $img 704 $img
596 } 705 }
615 } 724 }
616 725
617=item rotate $new_width, $new_height, $center_x, $center_y, $degrees 726=item rotate $new_width, $new_height, $center_x, $center_y, $degrees
618 727
619Rotates the image by C<$degrees> degrees, counter-clockwise, around the 728Rotates the image by C<$degrees> degrees, counter-clockwise, around the
620pointer at C<$center_x> and C<$center_y> (specified as percentage of image 729pointer at C<$center_x> and C<$center_y> (specified as factor of image
621width/height), generating a new image with width C<$new_width> and height 730width/height), generating a new image with width C<$new_width> and height
622C<$new_height>. 731C<$new_height>.
623 732
624#TODO# new width, height, maybe more operators? 733#TODO# new width, height, maybe more operators?
625 734
630 sub rotate($$$$$$) { 739 sub rotate($$$$$$) {
631 my $img = pop; 740 my $img = pop;
632 $img->rotate ( 741 $img->rotate (
633 $_[0], 742 $_[0],
634 $_[1], 743 $_[1],
635 $_[2] * $img->w * .01, 744 $_[2] * $img->w,
636 $_[3] * $img->h * .01, 745 $_[3] * $img->h,
637 $_[4] * (3.14159265 / 180), 746 $_[4] * (3.14159265 / 180),
638 ) 747 )
639 } 748 }
640 749
641=back 750=back
686 795
687 # evaluate user expression 796 # evaluate user expression
688 797
689 my $img = eval { $self->{expr}->() }; 798 my $img = eval { $self->{expr}->() };
690 warn $@ if $@;#d# 799 warn $@ if $@;#d#
691 die if !UNIVERSAL::isa $img, "urxvt::img"; 800 die "background-expr did not return an image.\n" if !UNIVERSAL::isa $img, "urxvt::img";
692 801
693 $state->{size_sensitive} = 1 802 $state->{size_sensitive} = 1
694 if $img->repeat_mode != urxvt::RepeatNormal; 803 if $img->repeat_mode != urxvt::RepeatNormal;
695 804
696 # if the expression is sensitive to external events, prepare reevaluation then 805 # if the expression is sensitive to external events, prepare reevaluation then
746} 855}
747 856
748sub on_start { 857sub on_start {
749 my ($self) = @_; 858 my ($self) = @_;
750 859
751 my $expr = $self->x_resource ("background.expr") 860 my $expr = $self->x_resource ("%.expr")
752 or return; 861 or return;
753 862
863 $self->has_render
864 or die "background extension needs RENDER extension 0.10 or higher, ignoring background-expr.\n";
865
754 $self->set_expr (parse_expr $expr); 866 $self->set_expr (parse_expr $expr);
755 $self->{border} = $self->x_resource_boolean ("background.border"); 867 $self->{border} = $self->x_resource_boolean ("%.border");
868
869 $MIN_INTERVAL = $self->x_resource ("%.interval");
756 870
757 () 871 ()
758} 872}
759 873

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines