--- rxvt-unicode/src/perl/background	2012/06/08 20:35:43	1.37
+++ rxvt-unicode/src/perl/background	2012/06/10 13:58:05	1.47
@@ -1,18 +1,22 @@
 #! perl
 
 #:META:X_RESOURCE:%.expr:string:background expression
-#:META:X_RESOURCE:%.border.:boolean:respect the terminal border
+#:META:X_RESOURCE:%.border:boolean:respect the terminal border
+#:META:X_RESOURCE:%.interval:seconds:minimum time between updates
 
 #TODO: once, rootalign
 
-=head1 background - manage terminal background
+=head1 NAME
 
-=head2 SYNOPSIS
+   background - manage terminal background
+
+=head1 SYNOPSIS
 
    urxvt --background-expr 'background expression'
          --background-border
+         --background-interval seconds
 
-=head2 DESCRIPTION
+=head1 DESCRIPTION
 
 This extension manages the terminal background by creating a picture that
 is behind the text, replacing the normal background colour.
@@ -32,7 +36,7 @@
 
    URxvt.background-expr: scale load "/path/to/mybg.png"
 
-=head2 THEORY OF OPERATION
+=head1 THEORY OF OPERATION
 
 At startup, just before the window is mapped for the first time, the
 expression is evaluated and must yield an image. The image is then
@@ -59,7 +63,7 @@
 example. That ensures that the picture always fills the terminal, even
 after it's size changes.
 
-=head3 EXPRESSIONS
+=head2 EXPRESSIONS
 
 Expressions are normal Perl expressions, in fact, they are Perl blocks -
 which means you could use multiple lines and statements:
@@ -72,7 +76,7 @@
    }
 
 This expression gets evaluated once per hour. It will set F<sunday.png> as
-background on sundays, and F<weekday.png> on all other days.
+background on Sundays, and F<weekday.png> on all other days.
 
 Fortunately, we expect that most expressions will be much simpler, with
 little Perl knowledge needed.
@@ -99,9 +103,10 @@
 Many operators also allow some parameters preceding the input image
 that modify its behaviour. For example, C<scale> without any additional
 arguments scales the image to size of the terminal window. If you specify
-an additional argument, it uses it as a percentage:
+an additional argument, it uses it as a scale factor (multiply by 100 to
+get a percentage):
 
-   scale 200, load "$HOME/mypic.png"
+   scale 2, load "$HOME/mypic.png"
 
 This enlarges the image by a factor of 2 (200%). As you can see, C<scale>
 has now two arguments, the C<200> and the C<load> expression, while
@@ -112,20 +117,67 @@
 horizontal and vertical dimensions. For example, this halves the image
 width and doubles the image height:
 
-   scale 50, 200, load "$HOME/mypic.png"
+   scale 0.5, 2, load "$HOME/mypic.png"
+
+Other effects than scalign are also readily available, for exmaple, you can
+tile the image to fill the whole window, instead of resizing it:
+
+   tile load "$HOME/mypic.png"
+
+In fact, images returned by C<load> are in C<tile> mode by default, so the C<tile> operator
+is kind of superfluous.
+
+Another common effect is to mirror the image, so that the same edges touch:
+
+   mirror load "$HOME/mypic.png"
+
+This is also a typical background expression:
+
+   rootalign root
+
+It first takes a snapshot of the screen background image, and then
+moves it to the upper left corner of the screen - the result is
+pseudo-transparency, as the image seems to be static while the window is
+moved around.
+
+=head2 CYCLES AND CACHING
+
+As has been mentioned before, the expression might be evaluated multiple
+times. Each time the expression is reevaluated, a new cycle is said to
+have begun. Many operators cache their results till the next cycle.
+
+For example, the C<load> operator keeps a copy of the image. If it is
+asked to load the same image on the next cycle it will not load it again,
+but return the cached copy.
+
+This only works for one cycle though, so as long as you load the same
+image every time, it will always be cached, but when you load a different
+image, it will forget about the first one.
+
+This allows you to either speed things up by keeping multiple images in
+memory, or comserve memory by loading images more often.
+
+For example, you can keep two images in memory and use a random one like
+this:
 
-TODO
+   my $img1 = load "img1.png";
+   my $img2 = load "img2.png";
+   (0.5 > rand) ? $img1 : $img2
 
-=head3 CYCLES AND CACHING
+Since both images are "loaded" every time the expression is evaluated,
+they are always kept in memory. Contrast this version:
 
-TODO
+   my $path1 = "img1.png";
+   my $path2 = "img2.png";
+   load ((0.5 > rand) ? $path1 : $path2)
 
-Each time the expression is reevaluated, a new cycle is said to have begun. Many operators
-cache their results till the next cycle. For example
+Here, a path is selected randomly, and load is only called for one image,
+so keeps only one image in memory. If, on the next evaluation, luck
+decides to use the other path, then it will have to load that image again.
 
-=head2 REFERENCE
+=head1 REFERENCE
 
-=head3 COMMAND LINE SWITCHES
+=head2 COMMAND LINE SWITCHES
 
 =over 4
 
@@ -141,33 +193,31 @@
 Specifying this flag changes the behaviour, so that the image only
 replaces the background of the character area.
 
+=item --background-interval seconds
+
+Since some operations in the underlying XRender extension can effetively
+freeze your X-server for prolonged time, this extension enforces a minimum
+time between updates, which is normally about 0.1 seconds.
+
+If you want to do updates more often, you can decrease this safety
+interval with this switch.
+
 =back
 
 =cut
 
-our $EXPR;#d#
-#$EXPR = 'move W * 0.1, -H * 0.1, resize W * 0.5, H * 0.5, repeat_none load "opensource.png"';
-$EXPR = 'move -TX, -TY, load "argb.png"';
-#$EXPR = '
-#   rotate W, H, 50, 50, counter 1/59.95, repeat_mirror,
-#   clip X, Y, W, H, repeat_mirror,
-#   load "/root/pix/das_fette_schwein.jpg"
-#';
-#$EXPR = 'solid "red"';
-#$EXPR = 'blur root, 10, 10'
-#$EXPR = 'blur move (root, -x, -y), 5, 5'
-#resize load "/root/pix/das_fette_schwein.jpg", w, h
-
 our $HOME;
 our ($self, $old, $new);
 our ($x, $y, $w, $h);
 
 # enforce at least this interval between updates
-our $MIN_INTERVAL = 1/100;
+our $MIN_INTERVAL = 6/59.951;
 
 {
    package urxvt::bgdsl; # background language
 
+   use List::Util qw(min max sum shuffle);
+
 =head2 PROVIDERS/GENERATORS
 
 These functions provide an image, by loading it from disk, grabbing it
@@ -213,12 +263,12 @@
 Creates a new image and completely fills it with the given colour. The
 image is set to tiling mode.
 
-If <$width> and C<$height> are omitted, it creates a 1x1 image, which is
+If C<$width> and C<$height> are omitted, it creates a 1x1 image, which is
 useful for solid backgrounds or for use in filtering effects.
 
 =cut
 
-   sub solid($$;$) {
+   sub solid($;$$) {
       my $colour = pop;
 
       my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1);
@@ -226,90 +276,15 @@
       $img
    }
 
-=back
-
-=head2 VARIABLES
-
-The following functions provide variable data such as the terminal
-window dimensions. Most of them make your expression sensitive to some
-events, for example using C<TW> (terminal width) means your expression is
-evaluated again when the terminal is resized.
-
-=over 4
-
-=item TX
-
-=item TY
-
-Return the X and Y coordinates of the terminal window (the terminal
-window is the full window by default, and the character area only when in
-border-respect mode).
-
-Using these functions make your expression sensitive to window moves.
-
-These functions are mainly useful to align images to the root window.
-
-Example: load an image and align it so it looks as if anchored to the
-background.
-
-   move -TX, -TY, load "mybg.png"
-
-=item TW
-
-Return the width (C<TW>) and height (C<TH>) of the terminal window (the
-terminal window is the full window by default, and the character area only
-when in border-respect mode).
-
-Using these functions make your expression sensitive to window resizes.
-
-These functions are mainly useful to scale images, or to clip images to
-the window size to conserve memory.
-
-Example: take the screen background, clip it to the window size, blur it a
-bit, align it to the window position and use it as background.
-
-   clip move -TX, -TY, blur 5, root
-
-=cut
-
-   sub TX() { $new->{position_sensitive} = 1; $x }
-   sub TY() { $new->{position_sensitive} = 1; $y }
-   sub TW() { $new->{size_sensitive}     = 1; $w }
-   sub TH() { $new->{size_sensitive}     = 1; $h }
-
-=item now
-
-Returns the current time as (fractional) seconds since the epoch.
-
-Using this expression does I<not> make your expression sensitive to time,
-but the next two functions do.
-
-=item again $seconds
-
-When this function is used the expression will be reevaluated again in
-C<$seconds> seconds.
-
-Example: load some image and rotate it according to the time of day (as if it were
-the hour pointer of a clock). Update this image every minute.
-
-   again 60; rotate TW, TH, 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png"
-
-=item counter $seconds
+=item clone $img
 
-Like C<again>, but also returns an increasing counter value, starting at
-0, which might be useful for some simple animation effects.
+Returns an exact copy of the image. This is useful if you want to have
+multiple copies of the same image to apply different effects to.
 
 =cut
 
-   sub now() { urxvt::NOW }
-
-   sub again($) {
-      $new->{again} = $_[0];
-   }
-
-   sub counter($) {
-      $new->{again} = $_[0];
-      $self->{counter} + 0
+   sub clone($) {
+      $_[0]->clone
    }
 
 =back
@@ -396,22 +371,99 @@
 
 =back
 
-=head2 PIXEL OPERATORS
+=head2 VARIABLE VALUES
 
-The following operators modify the image pixels in various ways.
+The following functions provide variable data such as the terminal window
+dimensions. They are not (Perl-) variables, they just return stuff that
+varies. Most of them make your expression sensitive to some events, for
+example using C<TW> (terminal width) means your expression is evaluated
+again when the terminal is resized.
 
 =over 4
 
-=item clone $img
+=item TX
+
+=item TY
+
+Return the X and Y coordinates of the terminal window (the terminal
+window is the full window by default, and the character area only when in
+border-respect mode).
+
+Using these functions make your expression sensitive to window moves.
 
-Returns an exact copy of the image.
+These functions are mainly useful to align images to the root window.
+
+Example: load an image and align it so it looks as if anchored to the
+background.
+
+   move -TX, -TY, load "mybg.png"
+
+=item TW
+
+Return the width (C<TW>) and height (C<TH>) of the terminal window (the
+terminal window is the full window by default, and the character area only
+when in border-respect mode).
+
+Using these functions make your expression sensitive to window resizes.
+
+These functions are mainly useful to scale images, or to clip images to
+the window size to conserve memory.
+
+Example: take the screen background, clip it to the window size, blur it a
+bit, align it to the window position and use it as background.
+
+   clip move -TX, -TY, blur 5, root
 
 =cut
 
-   sub clone($) {
-      $_[0]->clone
+   sub TX() { $new->{position_sensitive} = 1; $x }
+   sub TY() { $new->{position_sensitive} = 1; $y }
+   sub TW() { $new->{size_sensitive}     = 1; $w }
+   sub TH() { $new->{size_sensitive}     = 1; $h }
+
+=item now
+
+Returns the current time as (fractional) seconds since the epoch.
+
+Using this expression does I<not> make your expression sensitive to time,
+but the next two functions do.
+
+=item again $seconds
+
+When this function is used the expression will be reevaluated again in
+C<$seconds> seconds.
+
+Example: load some image and rotate it according to the time of day (as if it were
+the hour pointer of a clock). Update this image every minute.
+
+   again 60; rotate TW, TH, 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png"
+
+=item counter $seconds
+
+Like C<again>, but also returns an increasing counter value, starting at
+0, which might be useful for some simple animation effects.
+
+=cut
+
+   sub now() { urxvt::NOW }
+
+   sub again($) {
+      $new->{again} = $_[0];
    }
 
+   sub counter($) {
+      $new->{again} = $_[0];
+      $self->{counter} + 0
+   }
+
+=back
+
+=head2 SHAPE CHANGING OPERATORS
+
+The following operators modify the shape, size or position of the image.
+
+=over 4
+
 =item clip $img
 
 =item clip $width, $height, $img
@@ -444,31 +496,45 @@
 
 =item scale $img
 
-=item scale $size_percent, $img
+=item scale $size_factor, $img
 
-=item scale $width_percent, $height_percent, $img
+=item scale $width_factor, $height_factor, $img
 
-Scales the image by the given percentages in horizontal
-(C<$width_percent>) and vertical (C<$height_percent>) direction.
+Scales the image by the given factors in horizontal
+(C<$width>) and vertical (C<$height>) direction.
 
-If only one percentage is give, it is used for both directions.
+If only one factor is give, it is used for both directions.
 
-If no percentages are given, scales the image to the window size without
+If no factors are given, scales the image to the window size without
 keeping aspect.
 
 =item resize $width, $height, $img
 
 Resizes the image to exactly C<$width> times C<$height> pixels.
 
-=cut
+=item fit $img
+
+=item fit $width, $height, $img
+
+Fits the image into the given C<$width> and C<$height> without changing
+aspect, or the terminal size. That means it will be shrunk or grown until
+the whole image fits into the given area, possibly leaving borders.
+
+=item cover $img
 
-#TODO: maximise, maximise_fill?
+=item cover $width, $height, $img
+
+Similar to C<fit>, but shrinks or grows until all of the area is covered
+by the image, so instead of potentially leaving borders, it will cut off
+image data that doesn't fit.
+
+=cut
 
    sub scale($;$;$) {
       my $img = pop;
 
-      @_ == 2 ? $img->scale ($_[0] * $img->w * 0.01, $_[1] * $img->h * 0.01)
-      : @_    ? $img->scale ($_[0] * $img->w * 0.01, $_[0] * $img->h * 0.01)
+      @_ == 2 ? $img->scale ($_[0] * $img->w, $_[1] * $img->h)
+      : @_    ? $img->scale ($_[0] * $img->w, $_[0] * $img->h)
               : $img->scale (TW, TH)
    }
 
@@ -477,6 +543,20 @@
       $img->scale ($_[0], $_[1])
    }
 
+   sub fit($;$$) {
+      my $img = pop;
+      my $w = ($_[0] || TW) / $img->w;
+      my $h = ($_[1] || TH) / $img->h;
+      scale +(min $w, $h), $img
+   }
+
+   sub cover($;$$) {
+      my $img = pop;
+      my $w = ($_[0] || TW) / $img->w;
+      my $h = ($_[1] || TH) / $img->h;
+      scale +(max $w, $h), $img
+   }
+
 =item move $dx, $dy, $img
 
 Moves the image by C<$dx> pixels in the horizontal, and C<$dy> pixels in
@@ -486,6 +566,29 @@
 
    move 20, 30, ...
 
+=item align $xalign, $yalign, $img
+
+Aligns the image according to a factor - C<0> means the image is moved to
+the left or top edge (for C<$xalign> or C<$yalign>), C<0.5> means it is
+exactly centered and C<1> means it touches the right or bottom edge.
+
+Example: remove any visible border around an image, center it vertically but move
+it to the right hand side.
+
+   align 1, 0.5, pad $img
+
+=item center $img
+
+=item center $width, $height, $img
+
+Centers the image, i.e. the center of the image is moved to the center of
+the terminal window (or the box specified by C<$width> and C<$height> if
+given).
+
+Example: load an image and center it.
+
+  center pad load "mybg.png"
+
 =item rootalign $img
 
 Moves the image so that it appears glued to the screen as opposed to the
@@ -500,7 +603,7 @@
 Example: take the screen background and align it, giving the illusion of
 transparency as long as the window isn't in front of other windows.
 
-  rootalign root
+   rootalign root
 
 =cut
 
@@ -510,10 +613,34 @@
       $img
    }
 
+   sub align($;$$) {
+      my $img = pop;
+
+      move $_[0] * (TW - $img->w),
+           $_[1] * (TH - $img->h),
+           $img
+   }
+
+   sub center($;$$) {
+      my $img = pop;
+      my $w = $_[0] || TW;
+      my $h = $_[1] || TH;
+
+      move 0.5 * ($w - $img->w), 0.5 * ($h - $img->h), $img
+   }
+
    sub rootalign($) {
       move -TX, -TY, $_[0]
    }
 
+=back
+
+=head2 COLOUR MODIFICATIONS
+
+The following operators change the pixels of the image.
+
+=over 4
+
 =item contrast $factor, $img
 
 =item contrast $r, $g, $b, $img
@@ -522,12 +649,36 @@
 
 Adjusts the I<contrast> of an image.
 
-=item brightness $factor, $img
+The first form applies a single C<$factor> to red, green and blue, the
+second form applies separate factors to each colour channel, and the last
+form includes the alpha channel.
+
+Values from 0 to 1 lower the contrast, values higher than 1 increase the
+contrast.
+
+Due to limitations in the underlying XRender extension, lowering contrast
+also reduces brightness, while increasing contrast currently also
+increases brightness.
+
+=item brightness $bias, $img
 
 =item brightness $r, $g, $b, $img
 
 =item brightness $r, $g, $b, $a, $img
 
+Adjusts the brightness of an image.
+
+The first form applies a single C<$bias> to red, green and blue, the
+second form applies separate biases to each colour channel, and the last
+form includes the alpha channel.
+
+Values less than 0 reduce brightness, while values larger than 0 increase
+it. Useful range is from -1 to 1 - the former results in a black, the
+latter in a white picture.
+
+Due to idiosynchrasies in the underlying XRender extension, biases less
+than zero can be I<very> slow.
+
 =cut
 
    sub contrast($$;$$;$) {
@@ -554,18 +705,45 @@
       $img
    }
 
+=item blur $radius, $img
+
+=item blur $radius_horz, $radius_vert, $img
+
+Gaussian-blurs the image with (roughly) C<$radius> pixel radius. The radii
+can also be specified separately.
+
+Blurring is often I<very> slow, at least compared or other
+operators. Larger blur radii are slower than smaller ones, too, so if you
+don't want to freeze your screen for long times, start experimenting with
+low values for radius (<5).
+
+=cut
+
    sub blur($$;$) {
       my $img = pop;
       $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
    }
 
+=item rotate $new_width, $new_height, $center_x, $center_y, $degrees
+
+Rotates the image by C<$degrees> degrees, counter-clockwise, around the
+pointer at C<$center_x> and C<$center_y> (specified as factor of image
+width/height), generating a new image with width C<$new_width> and height
+C<$new_height>.
+
+#TODO# new width, height, maybe more operators?
+
+Example: rotate the image by 90 degrees
+
+=cut
+
    sub rotate($$$$$$) {
       my $img = pop;
       $img->rotate (
          $_[0],
          $_[1],
-         $_[2] * $img->w * .01,
-         $_[3] * $img->h * .01,
+         $_[2] * $img->w,
+         $_[3] * $img->h,
          $_[4] * (3.14159265 / 180),
       )
    }
@@ -680,11 +858,13 @@
 sub on_start {
    my ($self) = @_;
 
-   my $expr = $self->x_resource ("background.expr")
+   my $expr = $self->x_resource ("%.expr")
       or return;
 
    $self->set_expr (parse_expr $expr);
-   $self->{border} = $self->x_resource_boolean ("background.border");
+   $self->{border} = $self->x_resource_boolean ("%.border");
+
+   $MIN_INTERVAL = $self->x_resource ("%.interval");
 
    ()
 }