--- rxvt-unicode/src/perl/background	2012/06/07 16:30:58	1.33
+++ rxvt-unicode/src/perl/background	2012/06/08 22:19:03	1.39
@@ -3,32 +3,196 @@
 #:META:X_RESOURCE:%.expr:string:background expression
 #:META:X_RESOURCE:%.border.:boolean:respect the terminal border
 
+#TODO: once, rootalign
+
 =head1 background - manage terminal background
 
 =head2 SYNOPSIS
 
-   rxvt -background-expr 'background expression'
-        -background-border
+   urxvt --background-expr 'background expression'
+         --background-border
 
 =head2 DESCRIPTION
 
+This extension manages the terminal background by creating a picture that
+is behind the text, replacing the normal background colour.
+
+It does so by evaluating a Perl expression that I<calculates> the image on
+the fly, for example, by grabbing the root background or loading a file.
+
+While the full power of Perl is available, the operators have been design
+to be as simple as possible.
+
+For example, to load an image and scale it to the window size, you would
+use:
+
+   urxvt --background-expr 'scale load "/path/to/mybg.png"'
+
+Or specified as a X resource:
+
+   URxvt.background-expr: scale load "/path/to/mybg.png"
+
+=head2 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
+extended as necessary to cover the whole terminal window, and is set as a
+background pixmap.
+
+If the image contains an alpha channel, then it will be used as-is in
+visuals that support alpha channels (for example, for a compositing
+manager). In other visuals, the terminal background colour will be used to
+replace any transparency.
+
+When the expression relies, directly or indirectly, on the window size,
+position, the root pixmap, or a timer, then it will be remembered. If not,
+then it will be removed.
+
+If any of the parameters that the expression relies on changes (when the
+window is moved or resized, its position or size changes; when the root
+pixmap is replaced by another one the root background changes; or when the
+timer elapses), then the expression will be evaluated again.
+
+For example, an expression such as C<scale load "$HOME/mybg.png"> scales the
+image to the window size, so it relies on the window size and will
+be reevaluated each time it is changed, but not when it moves for
+example. That ensures that the picture always fills the terminal, even
+after it's size changes.
+
+=head3 EXPRESSIONS
+
+Expressions are normal Perl expressions, in fact, they are Perl blocks -
+which means you could use multiple lines and statements:
+
+   again 3600;
+   if (localtime now)[6]) {
+      return scale load "$HOME/weekday.png";
+   } else {
+      return scale load "$HOME/sunday.png";
+   }
+
+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.
+
+Fortunately, we expect that most expressions will be much simpler, with
+little Perl knowledge needed.
+
+Basically, you always start with a function that "generates" an image
+object, such as C<load>, which loads an image from disk, or C<root>, which
+returns the root window background image:
+
+   load "$HOME/mypic.png"
+
+The path is usually specified as a quoted string (the exact rules can be
+found in the L<perlop> manpage). The F<$HOME> at the beginning of the
+string is expanded to the home directory.
+
+Then you prepend one or more modifiers or filtering expressions, such as
+C<scale>:
+
+   scale load "$HOME/mypic.png"
+
+Just like a mathematical expression with functions, you should read these
+expressions from right to left, as the C<load> is evaluated first, and
+its result becomes the argument to the C<scale> function.
+
+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:
+
+   scale 200, 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
+C<load> only has one argument. Arguments are separated from each other by
+commas.
+
+Scale also accepts two arguments, which are then separate factors for both
+horizontal and vertical dimensions. For example, this halves the image
+width and doubles the image height:
+
+   scale 50, 200, 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.
+
+=head3 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:
+
+   my $img1 = load "img1.png";
+   my $img2 = load "img2.png";
+   (0.5 > rand) ? $img1 : $img2
+
+Since both images are "loaded" every time the expression is evaluated,
+they are always kept in memory. Contrast this version:
+
+   my $path1 = "img1.png";
+   my $path2 = "img2.png";
+   load ((0.5 > rand) ? $path1 : $path2)
+
+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
 
-=cut
+=head3 COMMAND LINE SWITCHES
 
-our $EXPR;
-#$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
+=over 4
+
+=item --background-expr perl-expression
+
+Specifies the Perl expression to evaluate.
+
+=item --background-border
+
+By default, the expression creates an image that fills the full window,
+overwriting borders and any other areas, such as the scrollbar.
+
+Specifying this flag changes the behaviour, so that the image only
+replaces the background of the character area.
+
+=back
 
+=cut
+
+our $HOME;
 our ($self, $old, $new);
 our ($x, $y, $w, $h);
 
@@ -160,7 +324,7 @@
 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.
+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"
 
@@ -196,6 +360,12 @@
 Tiles the whole plane with the image and returns this new image - or in
 other words, it returns a copy of the image in plane tiling mode.
 
+Example: load an image and tile it over the background, without
+resizing. The C<tile> call is superfluous because C<load> already defaults
+to tiling mode.
+
+   tile load "mybg.png"
+
 =item mirror $img
 
 Similar to tile, but reflects the image each time it uses a new copy, so
@@ -203,6 +373,11 @@
 edges and so on (with normal tiling, left edges always touch right edges
 and top always touch bottom edges).
 
+Example: load an image and mirror it over the background, avoiding sharp
+edges at the image borders at the expense of mirroring the image itself
+
+   mirror load "mybg.png"
+
 =item pad $img
 
 Takes an image and modifies it so that all pixels outside the image area
@@ -210,6 +385,12 @@
 image over another image or the background colour while leaving all
 background pixels outside the image unchanged.
 
+Example: load an image and display it in the upper left corner. The rest
+of the space is left "empty" (transparent or wahtever your compisotr does
+in alpha mode, else background colour).
+
+   pad load "mybg.png"
+
 =item extend $img
 
 Extends the image over the whole plane, using the closest pixel in the
@@ -217,6 +398,10 @@
 filtering operations and want the pixels outside the image to have the
 same values as the pixels near the edge.
 
+Example: just for curiosity, how does this pixel extension stuff work?
+
+   extend move 50, 50, load "mybg.png"
+
 =cut
 
    sub pad($) {
@@ -326,27 +511,62 @@
       $img->scale ($_[0], $_[1])
    }
 
+=item move $dx, $dy, $img
+
+Moves the image by C<$dx> pixels in the horizontal, and C<$dy> pixels in
+the vertical.
+
+Example: move the image right by 20 pixels and down by 30.
+
+   move 20, 30, ...
+
+=item rootalign $img
+
+Moves the image so that it appears glued to the screen as opposed to the
+window. This gives the illusion of a larger area behind the window. It is
+exactly equivalent to C<move -TX, -TY>, that is, it moves the image to the
+top left of the screen.
+
+Example: load a background image, put it in mirror mode and root align it.
+
+   rootalign mirror load "mybg.png"
+
+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
+
+=cut
+
    sub move($$;$) {
       my $img = pop->clone;
       $img->move ($_[0], $_[1]);
       $img
    }
 
-   sub rotate($$$$$$) {
-      my $img = pop;
-      $img->rotate (
-         $_[0],
-         $_[1],
-         $_[2] * $img->w * .01,
-         $_[3] * $img->h * .01,
-         $_[4] * (3.14159265 / 180),
-      )
+   sub rootalign($) {
+      move -TX, -TY, $_[0]
    }
 
-   sub blur($$;$) {
-      my $img = pop;
-      $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
-   }
+=item contrast $factor, $img
+
+=item contrast $r, $g, $b, $img
+
+=item contrast $r, $g, $b, $a, $img
+
+Adjusts the I<contrast> of an image.
+
+#TODO#
+
+=item brightness $factor, $img
+
+=item brightness $r, $g, $b, $img
+
+=item brightness $r, $g, $b, $a, $img
+
+Adjusts the brightness of an image.
+
+=cut
 
    sub contrast($$;$$;$) {
       my $img = pop;
@@ -372,6 +592,49 @@
       $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 percentage 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,
+         $_[4] * (3.14159265 / 180),
+      )
+   }
+
 =back
 
 =cut
@@ -411,6 +674,7 @@
 
    local $self = $arg_self;
 
+   local $HOME = $ENV{HOME};
    local $old = $self->{state};
    local $new = my $state = $self->{state} = {};
 
@@ -423,12 +687,16 @@
    warn $@ if $@;#d#
    die if !UNIVERSAL::isa $img, "urxvt::img";
 
+   $state->{size_sensitive} = 1
+      if $img->repeat_mode != urxvt::RepeatNormal;
+
    # if the expression is sensitive to external events, prepare reevaluation then
 
    my $repeat;
 
    if (my $again = $state->{again}) {
       $repeat = 1;
+      my $self = $self;
       $state->{timer} = $again == $old->{again}
                         ? $old->{timer}
                         : urxvt::timer->new->after ($again)->interval ($again)->cb (sub {
@@ -467,10 +735,7 @@
       delete $self->{expr};
    }
 
-   # prepare and set background pixmap
-
-   $img = $img->sub_rect (0, 0, $w, $h)
-      if $img->w != $w || $img->h != $h;
+   # set background pixmap
 
    $self->set_background ($img, $self->{border});
    $self->scr_recolour (0);