--- rxvt-unicode/src/perl/background	2012/06/07 10:22:55	1.23
+++ rxvt-unicode/src/perl/background	2012/06/07 13:56:27	1.32
@@ -4,7 +4,9 @@
 #:META:X_RESOURCE:%.enable:boolean:some boolean
 #:META:X_RESOURCE:%.extra.:value:extra config
 
-our $EXPR = 'clip move -X, -Y, load "MagnoliaAlpha.png"';
+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,
@@ -18,7 +20,7 @@
 use Safe;
 
 our ($bgdsl_self, $old, $new);
-our ($l, $t, $w, $h);
+our ($x, $y, $w, $h);
 
 # enforce at least this interval between updates
 our $MIN_INTERVAL = 1/100;
@@ -26,17 +28,21 @@
 {
    package urxvt::bgdsl; # background language
 
-#   *repeat_empty  = \&urxvt::RepeatNone;
-#   *repeat_tile   = \&urxvt::RepeatNormal;
-#   *repeat_pad    = \&urxvt::RepeatPad;
-#   *repeat_mirror = \&urxvt::RepeatReflect;
-
 =head2 PROVIDERS/GENERATORS
 
+These functions provide an image, by loading it from disk, grabbing it
+from the root screen or by simply generating it. They are used as starting
+points to get an image you can play with.
+
 =over 4
 
 =item load $path
 
+Loads the image at the given C<$path>. The image is set to plane tiling
+mode.
+
+Loaded images will be cached for one cycle.
+
 =cut
 
    sub load($) {
@@ -45,14 +51,38 @@
       $new->{load}{$path} = $old->{load}{$path} || $bgdsl_self->new_img_from_file ($path);
    }
 
+=item root
+
+Returns the root window pixmap, that is, hopefully, the background image
+of your screen. The image is set to extend mode.
+
+This function makes your expression root sensitive, that means it will be
+reevaluated when the bg image changes.
+
+=cut
+
    sub root() {
       $new->{rootpmap_sensitive} = 1;
       die "root op not supported, exg, we need you";
    }
 
-   sub solid($;$$) {
-      my $img = $bgdsl_self->new_img (urxvt::PictStandardARGB32, $_[1] || 1, $_[2] || 1);
-      $img->fill ($_[0]);
+=item solid $colour
+
+=item solid $width, $height, $colour
+
+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
+useful for solid backgrounds or for use in filtering effects.
+
+=cut
+
+   sub solid($$;$) {
+      my $colour = pop;
+
+      my $img = $bgdsl_self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1);
+      $img->fill ($colour);
       $img
    }
 
@@ -60,14 +90,52 @@
 
 =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 X() { $new->{position_sensitive} = 1; $l }
-   sub Y() { $new->{position_sensitive} = 1; $t }
-   sub W() { $new->{size_sensitive}     = 1; $w }
-   sub H() { $new->{size_sensitive}     = 1; $h }
+   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 }
 
    sub now() { urxvt::NOW }
 
@@ -82,39 +150,152 @@
 
 =back
 
-=head2 OPERATORS
+=head2 TILING MODES
+
+The following operators modify the tiling mode of an image, that is, the
+way that pixels outside the image area are painted when the image is used.
 
 =over 4
 
+=item tile $img
+
+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.
+
+=item mirror $img
+
+Similar to tile, but reflects the image each time it uses a new copy, so
+that top edges always touch top edges, right edges always touch right
+edges and so on (with normal tiling, left edges always touch right edges
+and top always touch bottom edges).
+
+=item pad $img
+
+Takes an image and modifies it so that all pixels outside the image area
+become transparent. This mode is most useful when you want to place an
+image over another image or the background colour while leaving all
+background pixels outside the image unchanged.
+
+=item extend $img
+
+Extends the image over the whole plane, using the closest pixel in the
+area outside the image. This mode is mostly useful when you more complex
+filtering operations and want the pixels outside the image to have the
+same values as the pixels near the edge.
+
 =cut
 
-#   sub clone($) {
-#      $_[0]->clone
-#   }
+   sub pad($) {
+      my $img = $_[0]->clone;
+      $img->repeat_mode (urxvt::RepeatNone);
+      $img
+   }
+
+   sub tile($) {
+      my $img = $_[0]->clone;
+      $img->repeat_mode (urxvt::RepeatNormal);
+      $img
+   }
+
+   sub mirror($) {
+      my $img = $_[0]->clone;
+      $img->repeat_mode (urxvt::RepeatReflect);
+      $img
+   }
+
+   sub extend($) {
+      my $img = $_[0]->clone;
+      $img->repeat_mode (urxvt::RepeatPad);
+      $img
+   }
+
+=back
+
+=head2 PIXEL OPERATORS
+
+The following operators modify the image pixels in various ways.
+
+=over 4
+
+=item clone $img
+
+Returns an exact copy of the image.
+
+=cut
+
+   sub clone($) {
+      $_[0]->clone
+   }
+
+=item clip $img
+
+=item clip $width, $height, $img
+
+=item clip $x, $y, $width, $height, $img
+
+Clips an image to the given rectangle. If the rectangle is outside the
+image area (e.g. when C<$x> or C<$y> are negative) or the rectangle is
+larger than the image, then the tiling mode defines how the extra pixels
+will be filled.
+
+If C<$x> an C<$y> are missing, then C<0> is assumed for both.
+
+If C<$width> and C<$height> are missing, then the window size will be
+assumed.
+
+Example: load an image, blur it, and clip it to the window size to save
+memory.
+
+   clip blur 10, load "mybg.png"
+
+=cut
 
    sub clip($;$$;$$) {
       my $img = pop;
-      my $h = pop || H;
-      my $w = pop || W;
+      my $h = pop || TH;
+      my $w = pop || TW;
       $img->sub_rect ($_[0], $_[1], $w, $h)
    }
 
+=item scale $img
+
+=item scale $size_percent, $img
+
+=item scale $width_percent, $height_percent, $img
+
+Scales the image by the given percentages in horizontal
+(C<$width_percent>) and vertical (C<$height_percent>) direction.
+
+If only one percentage is give, it is used for both directions.
+
+If no percentages 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
+
+#TODO: maximise, maximise_fill?
+
+   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)
+              : $img->scale (TW, TH)
+   }
+
    sub resize($$$) {
       my $img = pop;
       $img->scale ($_[0], $_[1])
    }
 
-   # TODO: ugly
    sub move($$;$) {
       my $img = pop->clone;
       $img->move ($_[0], $_[1]);
       $img
-#      my $img = pop;
-#      $img->sub_rect (
-#         $_[0], $_[1],
-#         $img->w, $img->h,
-#         $_[2],
-#      )
    }
 
    sub rotate($$$$$$) {
@@ -128,10 +309,9 @@
       )
    }
 
-   sub blur($$$) {
-      my ($rh, $rv, $img) = @_;
-
-      $img->blur ($rh, $rv);
+   sub blur($$;$) {
+      my $img = pop;
+      $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
    }
 
    sub contrast($$;$$;$) {
@@ -200,10 +380,10 @@
    local $old = $self->{state};
    local $new = my $state = $self->{state} = {};
 
-   ($l, $t, $w, $h) =
-      $self->get_geometry;
+   my $border = 0; #d#
 
-      warn "$l,$t,$w,$h\n";#d#
+   ($x, $y, $w, $h) =
+      $self->background_geometry ($border);
 
    # evaluate user expression
 
@@ -260,7 +440,7 @@
    $img = $img->sub_rect (0, 0, $w, $h)
       if $img->w != $w || $img->h != $h;
 
-   $self->set_background ($img);
+   $self->set_background ($img, $border);
    $self->scr_recolour (0);
    $self->want_refresh;
 }