--- rxvt-unicode/src/perl/background	2012/06/08 22:19:03	1.39
+++ rxvt-unicode/src/perl/background	2012/06/10 11:31:22	1.44
@@ -5,14 +5,16 @@
 
 #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
 
-=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 +34,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 +61,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:
@@ -99,9 +101,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,7 +115,7 @@
 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:
@@ -135,7 +138,7 @@
 pseudo-transparency, as the image seems to be static while the window is
 moved around.
 
-=head3 CYCLES AND CACHING
+=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
@@ -170,9 +173,9 @@
 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
 
@@ -202,6 +205,8 @@
 {
    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
@@ -247,12 +252,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);
@@ -264,10 +269,11 @@
 
 =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.
+The following functions provide variable data such as the terminal window
+dimensions. They are not (Perl-) variables, they jsut 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
 
@@ -478,31 +484,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)
    }
 
@@ -511,6 +531,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
@@ -520,6 +554,14 @@
 
    move 20, 30, ...
 
+=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).
+
 =item rootalign $img
 
 Moves the image so that it appears glued to the screen as opposed to the
@@ -544,6 +586,14 @@
       $img
    }
 
+   sub center($;$$) {
+      my $img = pop;
+      my $w = $_[0] || TW;
+      my $h = $_[0] || TH;
+
+      move 0.5 * ($w - $img->w), 0.5 * ($h - $img->h), $img
+   }
+
    sub rootalign($) {
       move -TX, -TY, $_[0]
    }
@@ -614,7 +664,7 @@
 =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
+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>.
 
@@ -629,8 +679,8 @@
       $img->rotate (
          $_[0],
          $_[1],
-         $_[2] * $img->w * .01,
-         $_[3] * $img->h * .01,
+         $_[2] * $img->w,
+         $_[3] * $img->h,
          $_[4] * (3.14159265 / 180),
       )
    }