--- rxvt-unicode/src/perl/background 2012/06/15 19:50:56 1.61 +++ rxvt-unicode/src/perl/background 2012/06/28 15:19:15 1.66 @@ -28,11 +28,11 @@ 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"' + urxvt --background-expr 'scale keep { load "/path/to/mybg.png" }' Or specified as a X resource: - URxvt.background-expr: scale load "/path/to/mybg.png" + URxvt.background-expr: scale keep { load "/path/to/mybg.png" } =head1 THEORY OF OPERATION @@ -55,9 +55,9 @@ 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 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 +For example, an expression such as C 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 its size changes. @@ -66,11 +66,13 @@ 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"; + scale keep { + again 3600; + if (localtime now)[6]) { + return load "$HOME/weekday.png"; + } else { + return load "$HOME/sunday.png"; + } } This expression is evaluated once per hour. It will set F as @@ -117,61 +119,92 @@ scale 0.5, 2, load "$HOME/mypic.png" -Other effects than scaling are also readily available, for example, you can -tile the image to fill the whole window, instead of resizing it: +IF you try out these expressions, you might suffer from sluggishness, +because each time the terminal is resized, it again loads the PNG image +and scales it. Scaling is usually fast, but loading the image can be quite +time consuming. This is where C comes in handy: + + scale 0.5, 2, keep { load "$HOME/mypic.png" } + +The C operator executes all the statements inside the braces only +once, or when it thinks the outcome might change. In other cases it +returns the last value computed by the brace block. + +This means that the C is only executed once, which makes it much +faster, but also means that more memory is being used, because the loaded +image must be kept in memory at all times. In this expression, the +trade-off is likely worth it. - tile load "$HOME/mypic.png" +But back to effects: Other effects than scaling are also readily +available, for example, you can tile the image to fill the whole window, +instead of resizing it: -In fact, images returned by C are in C mode by default, so the C operator -is kind of superfluous. + tile keep { load "$HOME/mypic.png" } -Another common effect is to mirror the image, so that the same edges touch: +In fact, images returned by C are in C mode by default, so the +C operator is kind of superfluous. - mirror load "$HOME/mypic.png" +Another common effect is to mirror the image, so that the same edges +touch: -This is also a typical background expression: + mirror keep { load "$HOME/mypic.png" } + +Another common background expression is: 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. +This one first takes a snapshot of the screen background image, and then +moves it to the upper left corner of the screen (as opposed to the upper +left corner of the terminal window)- the result is pseudo-transparency: +the image seems to be static while the window is moved around. + +=head2 CACHING AND SENSITIVITY + +Since some operations (such as C and C) can take a long time, +caching results can be very important for a smooth operation. Caching can +also be useful to reduce memory usage, though, for example, when an image +is cached by C, it could be shared by multiple terminal windows +running inside urxvtd. + +=head3 C caching -=head2 CYCLES AND CACHING +The most important way to cache expensive operations is to use C. The C operator takes a block of multiple statements enclosed +by C<{}> and keeps the return value in memory. -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. +An expression can be "sensitive" to various external events, such as +scaling or moving the window, root background changes and timers. Simply +using an expression (such as C without parameters) that depend on +certain changing values (called "variables"), or using those variables +directly, will make an expression sensitive to these events - for example, +using C or C will make the expression sensitive to the terminal +size, and thus to resizing events. -For example, the C 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. +When such an event happens, C will automatically trigger a +reevaluation of the whole expression with the new value of the expression. -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. +C is most useful for expensive operations, such as C: -This allows you to either speed things up by keeping multiple images in -memory, or conserve memory by loading images more often. + rootalign once { blur 20, root } -For example, you can keep two images in memory and use a random one like -this: +This makes a blurred copy of the root background once, and on subsequent +calls, just root-aligns it. Since C is usually quite slow and +C is quite fast, this trades extra memory (for the cached +blurred pixmap) with speed (blur only needs to be redone when root +changes). - my $img1 = load "img1.png"; - my $img2 = load "img2.png"; - (0.5 > rand) ? $img1 : $img2 +=head3 C caching -Since both images are "loaded" every time the expression is evaluated, -they are always kept in memory. Contrast this version: +The C operator itself does not keep images in memory, but as long as +the image is still in memory, C will use the in-memory image instead +of loading it freshly from disk. - my $path1 = "img1.png"; - my $path2 = "img2.png"; - load ((0.5 > rand) ? $path1 : $path2) +That means that this expression: -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. + keep { load "$HOME/path..." } + +Not only caches the image in memory, other terminal instances that try to +C it can reuse that in-memory copy. =head1 REFERENCE @@ -206,7 +239,7 @@ our %_IMG_CACHE; our $HOME; -our ($self, $old, $new); +our ($self, $frame); our ($x, $y, $w, $h); # enforce at least this interval between updates @@ -215,6 +248,11 @@ { package urxvt::bgdsl; # background language + sub FR_PARENT() { 0 } # parent frame, if any - must be #0 + sub FR_CACHE () { 1 } # cached values + sub FR_AGAIN () { 2 } # what this expr is sensitive to + sub FR_STATE () { 3 } # watchers etc. + use List::Util qw(min max sum shuffle); =head2 PROVIDERS/GENERATORS @@ -230,37 +268,34 @@ Loads the image at the given C<$path>. The image is set to plane tiling mode. -Loaded images will be cached for one cycle, and shared between temrinals -running in the same process (e.g. in C). +If the image is already in memory (e.g. because another terminal instance +uses it), then the in-memory copy us returned instead. =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. +Load uncached - same as load, but does not cache the image, which means it +is I loaded from the filesystem again. =cut sub load_uc($) { + $self->new_img_from_file ($path) + } + + sub load($) { my ($path) = @_; $_IMG_CACHE{$path} || do { - my $img = $self->new_img_from_file ($path); + my $img = load_uc $path; Scalar::Util::weaken ($_IMG_CACHE{$path} = $img); $img } } - sub load($) { - my ($path) = @_; - - $new->{load}{$path} = $old->{load}{$path} || load_uc $path; - } - =item root Returns the root window pixmap, that is, hopefully, the background image -of your screen. The image is set to extend mode. +of your screen. This function makes your expression root sensitive, that means it will be reevaluated when the bg image changes. @@ -268,7 +303,7 @@ =cut sub root() { - $new->{again}{rootpmap} = 1; + $frame->[FR_AGAIN]{rootpmap} = 1; $self->new_img_from_root } @@ -306,7 +341,8 @@ =item merge $img ... Takes any number of images and merges them together, creating a single -image containing them all. +image containing them all. The tiling mode of the first image is used as +the tiling mode of the resulting image. This function is called automatically when an expression returns multiple images. @@ -337,6 +373,7 @@ } my $base = $self->new_img (urxvt::PictStandardARGB32, $x0, $y0, $x1 - $x0, $y1 - $y0); + $base->repeat_mode ($_[0]->repeat_mode); $base->fill ([0, 0, 0, 0]); $base->draw ($_) @@ -450,9 +487,9 @@ 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. +background (that's exactly what C does btw.): - move -TX, -TY, load "mybg.png" + move -TX, -TY, keep { load "mybg.png" } =item TW @@ -468,14 +505,14 @@ 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, once { blur 5, root } + clip move -TX, -TY, keep { blur 5, root } =cut - sub TX() { $new->{again}{position} = 1; $x } - sub TY() { $new->{again}{position} = 1; $y } - sub TW() { $new->{again}{size} = 1; $w } - sub TH() { $new->{again}{size} = 1; $h } + sub TX() { $frame->[FR_AGAIN]{position} = 1; $x } + sub TY() { $frame->[FR_AGAIN]{position} = 1; $y } + sub TW() { $frame->[FR_AGAIN]{size} = 1; $w } + sub TH() { $frame->[FR_AGAIN]{size} = 1; $h } =item now @@ -492,7 +529,8 @@ 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 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png" + again 60; + rotate 50, 50, (now % 86400) * -72 / 8640, scale keep { load "myclock.png" } =item counter $seconds @@ -504,12 +542,12 @@ sub now() { urxvt::NOW } sub again($) { - $new->{again}{time} = $_[0]; + $frame->[FR_AGAIN]{time} = $_[0]; } sub counter($) { - $new->{again}{time} = $_[0]; - $self->{counter} + 0 + $frame->[FR_AGAIN]{time} = $_[0]; + $frame->[FR_STATE]{counter} + 0 } =back @@ -539,7 +577,7 @@ Example: load an image, blur it, and clip it to the window size to save memory. - clip blur 10, load "mybg.png" + clip keep { blur 10, load "mybg.png" } =cut @@ -643,7 +681,7 @@ Example: load an image and center it. - center pad load "mybg.png" + center keep { pad load "mybg.png" } =item rootalign $img @@ -654,7 +692,7 @@ Example: load a background image, put it in mirror mode and root align it. - rootalign mirror load "mybg.png" + rootalign keep { 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. @@ -689,15 +727,14 @@ move -TX, -TY, $_[0] } -=item rotate $center_x, $center_y, $degrees +=item rotate $center_x, $center_y, $degrees, $img -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). +Rotates the image clockwise by C<$degrees> degrees, around the point 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 around it's center. -Example: rotate the image by 90 degrees + rotate 0.5, 0.5, 90, keep { load "$HOME/mybg.png" } =cut @@ -810,29 +847,34 @@ =over 4 -=item once { ... } +=item keep { ... } + + #TODO# -This function takes a code block as argument, that is, one or more +This operator 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 +This can be extremely useful to avoid redoing 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. +In fact, urxvt itself encloses the whole expression in some kind of +C block so it only is reevaluated as required. + Putting the blur into a C block will make sure the blur is only done once: - rootlign once { blur 10, root } + rootlign keep { 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 is called. +This leaves the question of how to force reevaluation of the block, +in case the root background changes: If expression inside the block +is sensitive to some event (root background changes, window geometry +changes), then it will be reevaluated automatically as needed. =item once_again @@ -842,26 +884,35 @@ =cut sub once(&) { - my $once = $self->{once_cache}{$_[0]+0} ||= do { - local $new->{again}; - my @res = $_[0](); - [$new->{again}, \@res] - }; + my $id = $_[0]+0; + + local $frame = $self->{frame_cache}{$id} ||= [$frame]; - $new->{again} = { - %{ $new->{again} }, - %{ $once->[0] } + unless ($frame->[FR_CACHE]) { + $frame->[FR_CACHE] = [ $_[0]() ]; + + my $self = $self; + my $frame = $frame; + Scalar::Util::weaken $frame; + $self->compile_frame ($frame, sub { + # clear this frame cache, also for all parents + for (my $frame = $frame; $frame; $frame = $frame->[0]) { + undef $frame->[FR_CACHE]; + } + + $self->recalculate; + }); }; # in scalar context we always return the first original result, which # is not quite how perl works. wantarray - ? @{ $once->[1] } - : $once->[1][0] + ? @{ $frame->[FR_CACHE] } + : $frame->[FR_CACHE][0] } sub once_again() { - delete $self->{once_cache}; + delete $self->{frame_cache}; } =back @@ -871,7 +922,12 @@ } sub parse_expr { - my $expr = eval "sub {\npackage urxvt::bgdsl;\n#line 0 'background expression'\n$_[0]\n}"; + my $expr = eval + "sub {\n" + . "package urxvt::bgdsl;\n" + . "#line 0 'background expression'\n" + . "$_[0]\n" + . "}"; die if $@; $expr } @@ -880,10 +936,59 @@ sub set_expr { my ($self, $expr) = @_; + $self->{root} = []; $self->{expr} = $expr; $self->recalculate; } +# takes a hash of sensitivity indicators and installs watchers +sub compile_frame { + my ($self, $frame, $cb) = @_; + + my $state = $frame->[urxvt::bgdsl::FR_STATE] ||= {}; + my $again = $frame->[urxvt::bgdsl::FR_AGAIN]; + + # don't keep stuff alive + Scalar::Util::weaken $state; + + if ($again->{nested}) { + $state->{nested} = 1; + } else { + delete $state->{nested}; + } + + if (my $interval = $again->{time}) { + $state->{time} = [$interval, urxvt::timer->new->after ($interval)->interval ($interval)] + if $state->{time}[0] != $interval; + + # callback *might* have changed, although we could just rule that out + $state->{time}[1]->cb (sub { + ++$state->{counter}; + $cb->(); + }); + } else { + delete $state->{time}; + } + + if ($again->{position}) { + $state->{position} = $self->on (position_change => $cb); + } else { + delete $state->{position}; + } + + if ($again->{size}) { + $state->{size} = $self->on (size_change => $cb); + } else { + delete $state->{size}; + } + + if ($again->{rootpmap}) { + $state->{rootpmap} = $self->on (rootpmap_change => $cb); + } else { + delete $state->{rootpmap}; + } +} + # evaluate the current bg expression sub recalculate { my ($arg_self) = @_; @@ -901,67 +1006,34 @@ # set environment to evaluate user expression - local $self = $arg_self; - - local $HOME = $ENV{HOME}; - local $old = $self->{state}; - local $new = my $state = $self->{state} = {}; + local $self = $arg_self; + local $HOME = $ENV{HOME}; + local $frame = []; - ($x, $y, $w, $h) = - $self->background_geometry ($self->{border}); + ($x, $y, $w, $h) = $self->background_geometry ($self->{border}); # evaluate user expression - my $img = eval { urxvt::bgdsl::merge $self->{expr}->() }; + my @img = eval { $self->{expr}->() }; die $@ if $@; - die "background-expr did not return an image.\n" if !UNIVERSAL::isa $img, "urxvt::img"; - - # if the expression is sensitive to external events, prepare reevaluation then + die "background-expr did not return anything.\n" unless @img; + die "background-expr: expected image(s), got something else.\n" + if grep { !UNIVERSAL::isa $_, "urxvt::img" } @img; - my $again = delete $state->{again}; + my $img = urxvt::bgdsl::merge @img; - $again->{size} = 1 + $frame->[FR_AGAIN]{size} = 1 if $img->repeat_mode != urxvt::RepeatNormal; - if (my $again = $again->{time}) { - my $self = $self; - $state->{timer} = $again == $old->{again} - ? $old->{timer} - : urxvt::timer->new->after ($again)->interval ($again)->cb (sub { - ++$self->{counter}; - $self->recalculate - }); - } - - if ($again->{position}) { - $self->enable (position_change => sub { $_[0]->recalculate }); - } else { - $self->disable ("position_change"); - } - - if ($again->{size}) { - $self->enable (size_change => sub { $_[0]->recalculate }); - } else { - $self->disable ("size_change"); - } - - if ($again->{rootpmap}) { - $self->enable (rootpmap_change => sub { - delete $_[0]{once_cache}; # this will override once-block values from - $_[0]->recalculate; - }); - } else { - $self->disable ("rootpmap_change"); - } + # if the expression is sensitive to external events, prepare reevaluation then + $self->compile_frame ($frame, sub { $arg_self->recalculate }); # clear stuff we no longer need - %$old = (); - - unless (%$again) { - delete $self->{state}; - delete $self->{expr}; - } +# unless (%{ $frame->[FR_STATE] }) { +# delete $self->{state}; +# delete $self->{expr}; +# } # set background pixmap