--- rxvt-unicode/src/perl/background	2012/06/10 19:01:03	1.51
+++ rxvt-unicode/src/perl/background	2012/06/14 16:22:20	1.54
@@ -73,7 +73,7 @@
       return scale load "$HOME/sunday.png";
    }
 
-This expression gets evaluated once per hour. It will set F<sunday.png> as
+This expression is 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
@@ -204,7 +204,8 @@
 
 =cut
 
-our %_IMGCACHE;
+our %_IMG_CACHE;
+our %_ONCE_CACHE;
 our $HOME;
 our ($self, $old, $new);
 our ($x, $y, $w, $h);
@@ -230,14 +231,31 @@
 Loads the image at the given C<$path>. The image is set to plane tiling
 mode.
 
-Loaded images will be cached for one cycle.
+Loaded images will be cached for one cycle, and shared between temrinals
+running in the same process (e.g. in C<urxvtd>).
+
+=item load_uc $path
+
+Load uncached - same as load, but does not cache the image. This function
+is most useufl if you want to optimise a background expression in some
+way.
 
 =cut
 
+   sub load_uc($) {
+      my ($path) = @_;
+
+      $_IMG_CACHE{$path} || do {
+         my $img = $self->new_img_from_file ($path);
+         Scalar::Util::weaken ($_IMG_CACHE{$path} = $img);
+         $img
+      }
+   }
+
    sub load($) {
       my ($path) = @_;
 
-      $new->{load}{$path} = $old->{load}{$path} || $self->new_img_from_file ($path);
+      $new->{load}{$path} = $old->{load}{$path} || load_uc $path;
    }
 
 =item root
@@ -252,7 +270,7 @@
 
    sub root() {
       $new->{rootpmap_sensitive} = 1;
-      die "root op not supported, exg, we need you";
+      $self->new_img_from_root
    }
 
 =item solid $colour
@@ -286,8 +304,6 @@
       $_[0]->clone
    }
 
-=back
-
 =head2 TILING MODES
 
 The following operators modify the tiling mode of an image, that is, the
@@ -435,7 +451,7 @@
 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"
+   again 60; rotate 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png"
 
 =item counter $seconds
 
@@ -632,6 +648,27 @@
       move -TX, -TY, $_[0]
    }
 
+=item rotate $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).
+
+#TODO# new width, height, maybe more operators?
+
+Example: rotate the image by 90 degrees
+
+=cut
+
+   sub rotate($$$$) {
+      my $img = pop;
+      $img->rotate (
+         $_[0] * $img->w,
+         $_[1] * $img->h,
+         $_[2] * (3.14159265 / 180),
+      )
+   }
+
 =back
 
 =head2 COLOUR MODIFICATIONS
@@ -723,28 +760,52 @@
       $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
    }
 
-=item rotate $new_width, $new_height, $center_x, $center_y, $degrees
+=back
 
-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>.
+=head2 OTHER STUFF
 
-#TODO# new width, height, maybe more operators?
+Anything that didn't fit any of the other categories, even after appliyng
+force and closing our eyes.
 
-Example: rotate the image by 90 degrees
+=over 4
+
+=item once { ... }
+
+This function takes a code block as argument, that is, one or more
+statements enclosed by braces.
+
+The trick is that this code block is only evaluated once - future calls
+will simply return the original image (yes, it should only be used with
+images).
+
+This can be extremely useful to avoid redoign the same slow operations
+again and again- for example, if your background expression takes the root
+background, blurs it and then root-aligns it it would have to blur the
+root background on every window move or resize.
+
+Putting the blur into a C<once> block will make sure the blur is only done
+once:
+
+   rootlign once { blur 10, root }
+
+This leaves the question of how to force reevaluation of the block, in
+case the root background changes: Right now, all once blocks forget that
+they ahve been executed before each time the root background changes (if
+the expression is sensitive to that) or when C<once_again> is called.
+
+=item once_again
+
+Resets all C<once> block as if they had never been called, i.e. on the
+next call they will be reevaluated again.
 
 =cut
 
-   sub rotate($$$$$$) {
-      my $img = pop;
-      $img->rotate (
-         $_[0],
-         $_[1],
-         $_[2] * $img->w,
-         $_[3] * $img->h,
-         $_[4] * (3.14159265 / 180),
-      )
+   sub once(&) {
+      $_ONCE_CACHE{$_[0]+0} ||= $_[0]()
+   }
+
+   sub once_again() {
+      %_ONCE_CACHE = ();
    }
 
 =back