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.39 by root, Fri Jun 8 22:19:03 2012 UTC vs.
Revision 1.45 by root, Sun Jun 10 11:53:32 2012 UTC

… …
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
6#TODO: once, rootalign 6#TODO: once, rootalign
7 7
8=head1 NAME
9
8=head1 background - manage terminal background 10 background - manage terminal background
9 11
10=head2 SYNOPSIS 12=head1 SYNOPSIS
11 13
12 urxvt --background-expr 'background expression' 14 urxvt --background-expr 'background expression'
13 --background-border 15 --background-border
14 16
15=head2 DESCRIPTION 17=head1 DESCRIPTION
16 18
17This extension manages the terminal background by creating a picture that 19This extension manages the terminal background by creating a picture that
18is behind the text, replacing the normal background colour. 20is behind the text, replacing the normal background colour.
19 21
20It does so by evaluating a Perl expression that I<calculates> the image on 22It does so by evaluating a Perl expression that I<calculates> the image on
… …
30 32
31Or specified as a X resource: 33Or specified as a X resource:
32 34
33 URxvt.background-expr: scale load "/path/to/mybg.png" 35 URxvt.background-expr: scale load "/path/to/mybg.png"
34 36
35=head2 THEORY OF OPERATION 37=head1 THEORY OF OPERATION
36 38
37At startup, just before the window is mapped for the first time, the 39At startup, just before the window is mapped for the first time, the
38expression is evaluated and must yield an image. The image is then 40expression 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 41extended as necessary to cover the whole terminal window, and is set as a
40background pixmap. 42background pixmap.
… …
57image 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
58be 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
59example. That ensures that the picture always fills the terminal, even 61example. That ensures that the picture always fills the terminal, even
60after it's size changes. 62after it's size changes.
61 63
62=head3 EXPRESSIONS 64=head2 EXPRESSIONS
63 65
64Expressions are normal Perl expressions, in fact, they are Perl blocks - 66Expressions are normal Perl expressions, in fact, they are Perl blocks -
65which means you could use multiple lines and statements: 67which means you could use multiple lines and statements:
66 68
67 again 3600; 69 again 3600;
… …
97its result becomes the argument to the C<scale> function. 99its result becomes the argument to the C<scale> function.
98 100
99Many operators also allow some parameters preceding the input image 101Many operators also allow some parameters preceding the input image
100that modify its behaviour. For example, C<scale> without any additional 102that modify its behaviour. For example, C<scale> without any additional
101arguments 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
102an 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):
103 106
104 scale 200, load "$HOME/mypic.png" 107 scale 2, load "$HOME/mypic.png"
105 108
106This 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>
107has 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
108C<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
109commas. 112commas.
110 113
111Scale also accepts two arguments, which are then separate factors for both 114Scale also accepts two arguments, which are then separate factors for both
112horizontal and vertical dimensions. For example, this halves the image 115horizontal and vertical dimensions. For example, this halves the image
113width and doubles the image height: 116width and doubles the image height:
114 117
115 scale 50, 200, load "$HOME/mypic.png" 118 scale 0.5, 2, load "$HOME/mypic.png"
116 119
117Other effects than scalign are also readily available, for exmaple, you can 120Other effects than scalign are also readily available, for exmaple, you can
118tile the image to fill the whole window, instead of resizing it: 121tile the image to fill the whole window, instead of resizing it:
119 122
120 tile load "$HOME/mypic.png" 123 tile load "$HOME/mypic.png"
… …
133It first takes a snapshot of the screen background image, and then 136It first takes a snapshot of the screen background image, and then
134moves it to the upper left corner of the screen - the result is 137moves 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 138pseudo-transparency, as the image seems to be static while the window is
136moved around. 139moved around.
137 140
138=head3 CYCLES AND CACHING 141=head2 CYCLES AND CACHING
139 142
140As has been mentioned before, the expression might be evaluated multiple 143As has been mentioned before, the expression might be evaluated multiple
141times. Each time the expression is reevaluated, a new cycle is said to 144times. Each time the expression is reevaluated, a new cycle is said to
142have begun. Many operators cache their results till the next cycle. 145have begun. Many operators cache their results till the next cycle.
143 146
… …
168 171
169Here, a path is selected randomly, and load is only called for one image, 172Here, 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 173so 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. 174decides to use the other path, then it will have to load that image again.
172 175
173=head2 REFERENCE 176=head1 REFERENCE
174 177
175=head3 COMMAND LINE SWITCHES 178=head2 COMMAND LINE SWITCHES
176 179
177=over 4 180=over 4
178 181
179=item --background-expr perl-expression 182=item --background-expr perl-expression
180 183
… …
200our $MIN_INTERVAL = 1/100; 203our $MIN_INTERVAL = 1/100;
201 204
202{ 205{
203 package urxvt::bgdsl; # background language 206 package urxvt::bgdsl; # background language
204 207
208 use List::Util qw(min max sum shuffle);
209
205=head2 PROVIDERS/GENERATORS 210=head2 PROVIDERS/GENERATORS
206 211
207These functions provide an image, by loading it from disk, grabbing it 212These functions provide an image, by loading it from disk, grabbing it
208from the root screen or by simply generating it. They are used as starting 213from the root screen or by simply generating it. They are used as starting
209points to get an image you can play with. 214points to get an image you can play with.
… …
245=item solid $width, $height, $colour 250=item solid $width, $height, $colour
246 251
247Creates a new image and completely fills it with the given colour. The 252Creates a new image and completely fills it with the given colour. The
248image is set to tiling mode. 253image is set to tiling mode.
249 254
250If <$width> and C<$height> are omitted, it creates a 1x1 image, which is 255If C<$width> and C<$height> are omitted, it creates a 1x1 image, which is
251useful for solid backgrounds or for use in filtering effects. 256useful for solid backgrounds or for use in filtering effects.
252 257
253=cut 258=cut
254 259
255 sub solid($$;$) { 260 sub solid($;$$) {
256 my $colour = pop; 261 my $colour = pop;
257 262
258 my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1); 263 my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1);
259 $img->fill ($colour); 264 $img->fill ($colour);
260 $img 265 $img
261 } 266 }
262 267
268=item clone $img
269
270Returns an exact copy of the image. This is useful if you want to have
271multiple copies of the same image to apply different effects to.
272
273=cut
274
275 sub clone($) {
276 $_[0]->clone
277 }
278
263=back 279=back
264 280
281=head2 TILING MODES
282
283The following operators modify the tiling mode of an image, that is, the
284way that pixels outside the image area are painted when the image is used.
285
286=over 4
287
288=item tile $img
289
290Tiles the whole plane with the image and returns this new image - or in
291other words, it returns a copy of the image in plane tiling mode.
292
293Example: load an image and tile it over the background, without
294resizing. The C<tile> call is superfluous because C<load> already defaults
295to tiling mode.
296
297 tile load "mybg.png"
298
299=item mirror $img
300
301Similar to tile, but reflects the image each time it uses a new copy, so
302that top edges always touch top edges, right edges always touch right
303edges and so on (with normal tiling, left edges always touch right edges
304and top always touch bottom edges).
305
306Example: load an image and mirror it over the background, avoiding sharp
307edges at the image borders at the expense of mirroring the image itself
308
309 mirror load "mybg.png"
310
311=item pad $img
312
313Takes an image and modifies it so that all pixels outside the image area
314become transparent. This mode is most useful when you want to place an
315image over another image or the background colour while leaving all
316background pixels outside the image unchanged.
317
318Example: load an image and display it in the upper left corner. The rest
319of the space is left "empty" (transparent or wahtever your compisotr does
320in alpha mode, else background colour).
321
322 pad load "mybg.png"
323
324=item extend $img
325
326Extends the image over the whole plane, using the closest pixel in the
327area outside the image. This mode is mostly useful when you more complex
328filtering operations and want the pixels outside the image to have the
329same values as the pixels near the edge.
330
331Example: just for curiosity, how does this pixel extension stuff work?
332
333 extend move 50, 50, load "mybg.png"
334
335=cut
336
337 sub pad($) {
338 my $img = $_[0]->clone;
339 $img->repeat_mode (urxvt::RepeatNone);
340 $img
341 }
342
343 sub tile($) {
344 my $img = $_[0]->clone;
345 $img->repeat_mode (urxvt::RepeatNormal);
346 $img
347 }
348
349 sub mirror($) {
350 my $img = $_[0]->clone;
351 $img->repeat_mode (urxvt::RepeatReflect);
352 $img
353 }
354
355 sub extend($) {
356 my $img = $_[0]->clone;
357 $img->repeat_mode (urxvt::RepeatPad);
358 $img
359 }
360
361=back
362
265=head2 VARIABLES 363=head2 VARIABLE VALUES
266 364
267The following functions provide variable data such as the terminal 365The following functions provide variable data such as the terminal window
366dimensions. They are not (Perl-) variables, they just return stuff that
268window dimensions. Most of them make your expression sensitive to some 367varies. Most of them make your expression sensitive to some events, for
269events, for example using C<TW> (terminal width) means your expression is 368example using C<TW> (terminal width) means your expression is evaluated
270evaluated again when the terminal is resized. 369again when the terminal is resized.
271 370
272=over 4 371=over 4
273 372
274=item TX 373=item TX
275 374
… …
346 $self->{counter} + 0 445 $self->{counter} + 0
347 } 446 }
348 447
349=back 448=back
350 449
351=head2 TILING MODES 450=head2 SHAPE CHANGING OPERATORS
352 451
353The following operators modify the tiling mode of an image, that is, the 452The following operators modify the shape, size or position of the image.
354way that pixels outside the image area are painted when the image is used.
355 453
356=over 4 454=over 4
357
358=item tile $img
359
360Tiles the whole plane with the image and returns this new image - or in
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"
368
369=item mirror $img
370
371Similar to tile, but reflects the image each time it uses a new copy, so
372that top edges always touch top edges, right edges always touch right
373edges and so on (with normal tiling, left edges always touch right edges
374and top always touch bottom edges).
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
381=item pad $img
382
383Takes an image and modifies it so that all pixels outside the image area
384become transparent. This mode is most useful when you want to place an
385image over another image or the background colour while leaving all
386background pixels outside the image unchanged.
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
394=item extend $img
395
396Extends the image over the whole plane, using the closest pixel in the
397area outside the image. This mode is mostly useful when you more complex
398filtering operations and want the pixels outside the image to have the
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"
404
405=cut
406
407 sub pad($) {
408 my $img = $_[0]->clone;
409 $img->repeat_mode (urxvt::RepeatNone);
410 $img
411 }
412
413 sub tile($) {
414 my $img = $_[0]->clone;
415 $img->repeat_mode (urxvt::RepeatNormal);
416 $img
417 }
418
419 sub mirror($) {
420 my $img = $_[0]->clone;
421 $img->repeat_mode (urxvt::RepeatReflect);
422 $img
423 }
424
425 sub extend($) {
426 my $img = $_[0]->clone;
427 $img->repeat_mode (urxvt::RepeatPad);
428 $img
429 }
430
431=back
432
433=head2 PIXEL OPERATORS
434
435The following operators modify the image pixels in various ways.
436
437=over 4
438
439=item clone $img
440
441Returns an exact copy of the image.
442
443=cut
444
445 sub clone($) {
446 $_[0]->clone
447 }
448 455
449=item clip $img 456=item clip $img
450 457
451=item clip $width, $height, $img 458=item clip $width, $height, $img
452 459
… …
476 $img->sub_rect ($_[0], $_[1], $w, $h) 483 $img->sub_rect ($_[0], $_[1], $w, $h)
477 } 484 }
478 485
479=item scale $img 486=item scale $img
480 487
481=item scale $size_percent, $img 488=item scale $size_factor, $img
482 489
483=item scale $width_percent, $height_percent, $img 490=item scale $width_factor, $height_factor, $img
484 491
485Scales the image by the given percentages in horizontal 492Scales the image by the given factors in horizontal
486(C<$width_percent>) and vertical (C<$height_percent>) direction. 493(C<$width>) and vertical (C<$height>) direction.
487 494
488If only one percentage is give, it is used for both directions. 495If only one factor is give, it is used for both directions.
489 496
490If no percentages are given, scales the image to the window size without 497If no factors are given, scales the image to the window size without
491keeping aspect. 498keeping aspect.
492 499
493=item resize $width, $height, $img 500=item resize $width, $height, $img
494 501
495Resizes the image to exactly C<$width> times C<$height> pixels. 502Resizes the image to exactly C<$width> times C<$height> pixels.
496 503
497=cut 504=item fit $img
498 505
499#TODO: maximise, maximise_fill? 506=item fit $width, $height, $img
507
508Fits the image into the given C<$width> and C<$height> without changing
509aspect, or the terminal size. That means it will be shrunk or grown until
510the whole image fits into the given area, possibly leaving borders.
511
512=item cover $img
513
514=item cover $width, $height, $img
515
516Similar to C<fit>, but shrinks or grows until all of the area is covered
517by the image, so instead of potentially leaving borders, it will cut off
518image data that doesn't fit.
519
520=cut
500 521
501 sub scale($;$;$) { 522 sub scale($;$;$) {
502 my $img = pop; 523 my $img = pop;
503 524
504 @_ == 2 ? $img->scale ($_[0] * $img->w * 0.01, $_[1] * $img->h * 0.01) 525 @_ == 2 ? $img->scale ($_[0] * $img->w, $_[1] * $img->h)
505 : @_ ? $img->scale ($_[0] * $img->w * 0.01, $_[0] * $img->h * 0.01) 526 : @_ ? $img->scale ($_[0] * $img->w, $_[0] * $img->h)
506 : $img->scale (TW, TH) 527 : $img->scale (TW, TH)
507 } 528 }
508 529
509 sub resize($$$) { 530 sub resize($$$) {
510 my $img = pop; 531 my $img = pop;
511 $img->scale ($_[0], $_[1]) 532 $img->scale ($_[0], $_[1])
533 }
534
535 sub fit($;$$) {
536 my $img = pop;
537 my $w = ($_[0] || TW) / $img->w;
538 my $h = ($_[1] || TH) / $img->h;
539 scale +(min $w, $h), $img
540 }
541
542 sub cover($;$$) {
543 my $img = pop;
544 my $w = ($_[0] || TW) / $img->w;
545 my $h = ($_[1] || TH) / $img->h;
546 scale +(max $w, $h), $img
512 } 547 }
513 548
514=item move $dx, $dy, $img 549=item move $dx, $dy, $img
515 550
516Moves the image by C<$dx> pixels in the horizontal, and C<$dy> pixels in 551Moves the image by C<$dx> pixels in the horizontal, and C<$dy> pixels in
517the vertical. 552the vertical.
518 553
519Example: move the image right by 20 pixels and down by 30. 554Example: move the image right by 20 pixels and down by 30.
520 555
521 move 20, 30, ... 556 move 20, 30, ...
557
558=item center $img
559
560=item center $width, $height, $img
561
562Centers the image, i.e. the center of the image is moved to the center of
563the terminal window (or the box specified by C<$width> and C<$height> if
564given).
522 565
523=item rootalign $img 566=item rootalign $img
524 567
525Moves the image so that it appears glued to the screen as opposed to the 568Moves 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 569window. This gives the illusion of a larger area behind the window. It is
… …
542 my $img = pop->clone; 585 my $img = pop->clone;
543 $img->move ($_[0], $_[1]); 586 $img->move ($_[0], $_[1]);
544 $img 587 $img
545 } 588 }
546 589
590 sub center($;$$) {
591 my $img = pop;
592 my $w = $_[0] || TW;
593 my $h = $_[0] || TH;
594
595 move 0.5 * ($w - $img->w), 0.5 * ($h - $img->h), $img
596 }
597
547 sub rootalign($) { 598 sub rootalign($) {
548 move -TX, -TY, $_[0] 599 move -TX, -TY, $_[0]
549 } 600 }
550 601
602=back
603
604=head2 COLOUR MODIFICATIONS
605
606The following operators change the pixels of the image.
607
608=over 4
609
551=item contrast $factor, $img 610=item contrast $factor, $img
552 611
553=item contrast $r, $g, $b, $img 612=item contrast $r, $g, $b, $img
554 613
555=item contrast $r, $g, $b, $a, $img 614=item contrast $r, $g, $b, $a, $img
556 615
557Adjusts the I<contrast> of an image. 616Adjusts the I<contrast> of an image.
558 617
559#TODO# 618The first form applies a single C<$factor> to red, green and blue, the
619second form applies separate factors to each colour channel, and the last
620form includes the alpha channel.
560 621
622Values from 0 to 1 lower the contrast, values higher than 1 increase the
623contrast.
624
625Due to limitations in the underlying XRender extension, lowering contrast
626also reduces brightness, while increasing contrast currently also
627increases brightness.
628
561=item brightness $factor, $img 629=item brightness $bias, $img
562 630
563=item brightness $r, $g, $b, $img 631=item brightness $r, $g, $b, $img
564 632
565=item brightness $r, $g, $b, $a, $img 633=item brightness $r, $g, $b, $a, $img
566 634
567Adjusts the brightness of an image. 635Adjusts the brightness of an image.
636
637The first form applies a single C<$bias> to red, green and blue, the
638second form applies separate biases to each colour channel, and the last
639form includes the alpha channel.
640
641Values less than 0 reduce brightness, while values larger than 0 increase
642it. Useful range is from -1 to 1 - the former results in a black, the
643latter in a white picture.
644
645Due to idiosynchrasies in the underlying XRender extension, biases less
646than zero can be I<very> slow.
568 647
569=cut 648=cut
570 649
571 sub contrast($$;$$;$) { 650 sub contrast($$;$$;$) {
572 my $img = pop; 651 my $img = pop;
… …
612 } 691 }
613 692
614=item rotate $new_width, $new_height, $center_x, $center_y, $degrees 693=item rotate $new_width, $new_height, $center_x, $center_y, $degrees
615 694
616Rotates the image by C<$degrees> degrees, counter-clockwise, around the 695Rotates the image by C<$degrees> degrees, counter-clockwise, around the
617pointer at C<$center_x> and C<$center_y> (specified as percentage of image 696pointer at C<$center_x> and C<$center_y> (specified as factor of image
618width/height), generating a new image with width C<$new_width> and height 697width/height), generating a new image with width C<$new_width> and height
619C<$new_height>. 698C<$new_height>.
620 699
621#TODO# new width, height, maybe more operators? 700#TODO# new width, height, maybe more operators?
622 701
… …
627 sub rotate($$$$$$) { 706 sub rotate($$$$$$) {
628 my $img = pop; 707 my $img = pop;
629 $img->rotate ( 708 $img->rotate (
630 $_[0], 709 $_[0],
631 $_[1], 710 $_[1],
632 $_[2] * $img->w * .01, 711 $_[2] * $img->w,
633 $_[3] * $img->h * .01, 712 $_[3] * $img->h,
634 $_[4] * (3.14159265 / 180), 713 $_[4] * (3.14159265 / 180),
635 ) 714 )
636 } 715 }
637 716
638=back 717=back

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines