--- rxvt-unicode/src/perl/background	2012/07/01 21:47:07	1.68
+++ rxvt-unicode/src/perl/background	2012/09/04 11:21:11	1.77
@@ -14,6 +14,30 @@
          --background-border
          --background-interval seconds
 
+=head1 QUICK AND DIRTY CHEAT SHEET
+
+Just load a random jpeg image and tile the background with it without
+scaling or anything else:
+
+   load "/path/to/img.jpg"
+
+The same, but use mirroring/reflection instead of tiling:
+
+   mirror load "/path/to/img.jpg"
+
+Load an image and scale it to exactly fill the terminal window:
+
+   scale keep { load "/path/to/img.jpg" }
+
+Implement pseudo-transparency by using a suitably-aligned root pixmap
+as window background:
+
+   rootalign root
+
+Likewise, but keep a blurred copy:
+
+   rootalign keep { blur 10, root }
+
 =head1 DESCRIPTION
 
 This extension manages the terminal background by creating a picture that
@@ -76,7 +100,7 @@
    }
 
 This inner expression is evaluated once per hour (and whenever the
-temrinal window is resized). It sets F<sunday.png> as background on
+terminal window is resized). It sets 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
@@ -121,7 +145,7 @@
    scale 0.5, 2, load "$HOME/mypic.png"
 
 IF you try out these expressions, you might suffer from some sluggishness,
-because each time the terminal is resized, it loads the PNG image agin
+because each time the terminal is resized, it loads the PNG image again
 and scales it. Scaling is usually fast (and unavoidable), but loading the
 image can be quite time consuming. This is where C<keep> comes in handy:
 
@@ -159,6 +183,22 @@
 left corner of the terminal window)- the result is pseudo-transparency:
 the image seems to be static while the window is moved around.
 
+=head2 COLOUR SPECIFICATIONS
+
+Whenever an operator expects a "colour", then this can be specified in one
+of two ways: Either as string with an X11 colour specification, such as:
+
+   "red"               # named colour
+   "#f00"              # simple rgb
+   "[50]red"           # red with 50% alpha
+   "TekHVC:300/50/50"  # anything goes
+
+OR as an array reference with one, three or four components:
+
+   [0.5]               # 50% gray, 100% alpha
+   [0.5, 0, 0]         # dark red, no green or blur, 100% alpha
+   [0.5, 0, 0, 0.7]    # same with explicit 70% alpha
+
 =head2 CACHING AND SENSITIVITY
 
 Since some operations (such as C<load> and C<blur>) can take a long time,
@@ -275,12 +315,13 @@
 =item load_uc $path
 
 Load uncached - same as load, but does not cache the image, which means it
-is I<always> loaded from the filesystem again.
+is I<always> loaded from the filesystem again, even if another copy of it
+is in memory at the time.
 
 =cut
 
    sub load_uc($) {
-      $self->new_img_from_file ($path)
+      $self->new_img_from_file ($_[0])
    }
 
    sub load($) {
@@ -383,6 +424,8 @@
       $base
    }
 
+=back
+
 =head2 TILING MODES
 
 The following operators modify the tiling mode of an image, that is, the
@@ -494,6 +537,8 @@
 
 =item TW
 
+=item TH
+
 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).
@@ -756,6 +801,24 @@
 
 =over 4
 
+=item tint $color, $img
+
+Tints the image in the given colour.
+
+Example: tint the image red.
+
+   tint "red", load "rgb.png"
+
+Example: the same, but specify the colour by component.
+
+   tint [1, 0, 0], load "rgb.png"
+
+=cut
+
+   sub tint($$) {
+      $_[1]->tint ($_[0])
+   }
+
 =item contrast $factor, $img
 
 =item contrast $r, $g, $b, $img
@@ -794,6 +857,8 @@
 Due to idiosyncrasies in the underlying XRender extension, biases less
 than zero can be I<very> slow.
 
+You can also try the experimental(!) C<muladd> operator.
+
 =cut
 
    sub contrast($$;$$;$) {
@@ -820,6 +885,26 @@
       $img
    }
 
+=item muladd $mul, $add, $img # EXPERIMENTAL
+
+First multipliesthe pixels by C<$mul>, then adds C<$add>. This cna be used
+to implement brightness and contrast at the same time, with a wider value
+range than contrast and brightness operators.
+
+Due to numerous bugs in XRender implementations, it can also introduce a
+number of visual artifacts.
+
+Example: increase contrast by a factor of C<$c> without changing image
+brightness too much.
+
+   muladd $c, (1 - $c) * 0.5, $img
+
+=cut
+
+   sub muladd($$$) {
+      $_[2]->muladd ($_[0], $_[1])
+   }
+
 =item blur $radius, $img
 
 =item blur $radius_horz, $radius_vert, $img
@@ -872,7 +957,7 @@
 Putting the blur into a C<keep> block will make sure the blur is only done
 once, while the C<rootalign> is still done each time the window moves.
 
-   rootlign keep { blur 10, root }
+   rootalign keep { blur 10, root }
 
 This leaves the question of how to force reevaluation of the block,
 in case the root background changes: If expression inside the block
@@ -934,7 +1019,7 @@
 sub set_expr {
    my ($self, $expr) = @_;
 
-   $self->{root} = [];
+   $self->{root} = []; # the outermost frame
    $self->{expr} = $expr;
    $self->recalculate;
 }
@@ -1006,7 +1091,7 @@
 
    local $self  = $arg_self;
    local $HOME  = $ENV{HOME};
-   local $frame = [];
+   local $frame = $self->{root};
 
    ($x, $y, $w, $h) = $self->background_geometry ($self->{border});