--- rxvt-unicode/src/perl/background 2012/06/10 19:01:03 1.51 +++ rxvt-unicode/src/perl/background 2012/07/02 01:32:26 1.69 @@ -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,15 +66,18 @@ 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 gets evaluated once per hour. It will set F as -background on Sundays, and F on all other days. +This inner expression is evaluated once per hour (and whenever the +temrinal window is resized). It sets F as background on +Sundays, and F on all other days. Fortunately, we expect that most expressions will be much simpler, with little Perl knowledge needed. @@ -117,61 +120,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 some sluggishness, +because each time the terminal is resized, it loads the PNG image agin +and scales it. Scaling is usually fast (and unavoidable), 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. - tile load "$HOME/mypic.png" +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. -In fact, images returned by C are in C mode by default, so the C operator -is kind of superfluous. +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: -Another common effect is to mirror the image, so that the same edges touch: + tile keep { load "$HOME/mypic.png" } - mirror load "$HOME/mypic.png" +In fact, images returned by C are in C mode by default, so the +C operator is kind of superfluous. -This is also a typical background expression: +Another common effect is to mirror the image, so that the same edges +touch: + + 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 -=head2 CYCLES AND CACHING +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. -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. +=head3 C caching -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. +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. -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. +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 depends 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. -This allows you to either speed things up by keeping multiple images in -memory, or conserve memory by loading images more often. +When such an event happens, C will automatically trigger a +reevaluation of the whole expression with the new value of the expression. -For example, you can keep two images in memory and use a random one like -this: +C is most useful for expensive operations, such as C: - my $img1 = load "img1.png"; - my $img2 = load "img2.png"; - (0.5 > rand) ? $img1 : $img2 + rootalign keep { blur 20, root } -Since both images are "loaded" every time the expression is evaluated, -they are always kept in memory. Contrast this version: +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 $path1 = "img1.png"; - my $path2 = "img2.png"; - load ((0.5 > rand) ? $path1 : $path2) +=head3 C caching -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. +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. + +That means that this expression: + + 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 @@ -204,9 +238,9 @@ =cut -our %_IMGCACHE; +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 +249,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,20 +269,30 @@ Loads the image at the given C<$path>. The image is set to plane tiling mode. -Loaded images will be cached for one cycle. +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, which means it +is I loaded from the filesystem again. =cut sub load($) { my ($path) = @_; - $new->{load}{$path} = $old->{load}{$path} || $self->new_img_from_file ($path); + $_IMG_CACHE{$path} || do { + my $img = $self->new_img_from_file ($path); + Scalar::Util::weaken ($_IMG_CACHE{$path} = $img); + $img + } } =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. @@ -251,8 +300,8 @@ =cut sub root() { - $new->{rootpmap_sensitive} = 1; - die "root op not supported, exg, we need you"; + $frame->[FR_AGAIN]{rootpmap} = 1; + $self->new_img_from_root } =item solid $colour @@ -270,7 +319,7 @@ sub solid($;$$) { my $colour = pop; - my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1); + my $img = $self->new_img (urxvt::PictStandardARGB32, 0, 0, $_[0] || 1, $_[1] || 1); $img->fill ($colour); $img } @@ -286,7 +335,49 @@ $_[0]->clone } -=back +=item merge $img ... + +Takes any number of images and merges them together, creating a single +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. + +=cut + + sub merge(@) { + return $_[0] unless $#_; + + # rather annoyingly clumsy, but optimisation is for another time + + my $x0 = +1e9; + my $y0 = +1e9; + my $x1 = -1e9; + my $y1 = -1e9; + + for (@_) { + my ($x, $y, $w, $h) = $_->geometry; + + $x0 = $x if $x0 > $x; + $y0 = $y if $y0 > $y; + + $x += $w; + $y += $h; + + $x1 = $x if $x1 < $x; + $y1 = $y if $y1 < $y; + } + + 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 ($_) + for @_; + + $base + } =head2 TILING MODES @@ -393,9 +484,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 @@ -411,14 +502,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, blur 5, root + clip move -TX, -TY, keep { blur 5, root } =cut - 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 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 @@ -435,7 +526,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 TW, TH, 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 @@ -447,12 +539,12 @@ sub now() { urxvt::NOW } sub again($) { - $new->{again} = $_[0]; + $frame->[FR_AGAIN]{time} = $_[0]; } sub counter($) { - $new->{again} = $_[0]; - $self->{counter} + 0 + $frame->[FR_AGAIN]{time} = $_[0]; + $frame->[FR_STATE]{counter} + 0 } =back @@ -482,7 +574,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 @@ -586,7 +678,7 @@ Example: load an image and center it. - center pad load "mybg.png" + center keep { pad load "mybg.png" } =item rootalign $img @@ -597,7 +689,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. @@ -632,6 +724,26 @@ move -TX, -TY, $_[0] } +=item rotate $center_x, $center_y, $degrees, $img + +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). + +Example: rotate the image by 90 degrees around it's center. + + rotate 0.5, 0.5, 90, keep { load "$HOME/mybg.png" } + +=cut + + sub rotate($$$$) { + my $img = pop; + $img->rotate ( + $_[0] * ($img->w + $img->x), + $_[1] * ($img->h + $img->y), + $_[2] * (3.14159265 / 180), + ) + } + =back =head2 COLOUR MODIFICATIONS @@ -723,30 +835,80 @@ $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0]) } -=item rotate $new_width, $new_height, $center_x, $center_y, $degrees +=back + +=head2 OTHER STUFF + +Anything that didn't fit any of the other categories, even after applying +force and closing our eyes. + +=over 4 + +=item keep { ... } + +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 when the outcome +changes - on other calls the C simply returns the image it computed +previously (yes, it should only be used with images). Or in other words, +C I the result of the code block so it doesn't need to be +computed again. -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>. +This can be extremely useful to avoid redoing slow operations - 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. -#TODO# new width, height, maybe more operators? +Another example is C, which can be quite slow. -Example: rotate the image by 90 degrees +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, while the C is still done each time the window moves. + + rootlign 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 +is sensitive to some event (root background changes, window geometry +changes), then it will be reevaluated automatically as needed. =cut - sub rotate($$$$$$) { - my $img = pop; - $img->rotate ( - $_[0], - $_[1], - $_[2] * $img->w, - $_[3] * $img->h, - $_[4] * (3.14159265 / 180), - ) + sub keep(&) { + my $id = $_[0]+0; + + local $frame = $self->{frame_cache}{$id} ||= [$frame]; + + 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 + ? @{ $frame->[FR_CACHE] } + : $frame->[FR_CACHE][0] } +# sub keep_clear() { +# delete $self->{frame_cache}; +# } + =back =cut @@ -754,7 +916,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 } @@ -763,10 +930,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) = @_; @@ -784,68 +1000,34 @@ # set environment to evaluate user expression - local $self = $arg_self; + local $self = $arg_self; + local $HOME = $ENV{HOME}; + local $frame = []; - local $HOME = $ENV{HOME}; - local $old = $self->{state}; - local $new = my $state = $self->{state} = {}; - - ($x, $y, $w, $h) = - $self->background_geometry ($self->{border}); + ($x, $y, $w, $h) = $self->background_geometry ($self->{border}); # evaluate user expression - my $img = eval { $self->{expr}->() }; - warn $@ if $@;#d# - die "background-expr did not return an image.\n" if !UNIVERSAL::isa $img, "urxvt::img"; + my @img = eval { $self->{expr}->() }; + die $@ if $@; + 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 $img = urxvt::bgdsl::merge @img; - $state->{size_sensitive} = 1 + $frame->[FR_AGAIN]{size} = 1 if $img->repeat_mode != urxvt::RepeatNormal; # if the expression is sensitive to external events, prepare reevaluation then - - my $repeat; - - if (my $again = $state->{again}) { - $repeat = 1; - my $self = $self; - $state->{timer} = $again == $old->{again} - ? $old->{timer} - : urxvt::timer->new->after ($again)->interval ($again)->cb (sub { - ++$self->{counter}; - $self->recalculate - }); - } - - if (delete $state->{position_sensitive}) { - $repeat = 1; - $self->enable (position_change => sub { $_[0]->recalculate }); - } else { - $self->disable ("position_change"); - } - - if (delete $state->{size_sensitive}) { - $repeat = 1; - $self->enable (size_change => sub { $_[0]->recalculate }); - } else { - $self->disable ("size_change"); - } - - if (delete $state->{rootpmap_sensitive}) { - $repeat = 1; - $self->enable (rootpmap_change => sub { $_[0]->recalculate }); - } else { - $self->disable ("rootpmap_change"); - } + $self->compile_frame ($frame, sub { $arg_self->recalculate }); # clear stuff we no longer need - %$old = (); - - unless ($repeat) { - delete $self->{state}; - delete $self->{expr}; - } +# unless (%{ $frame->[FR_STATE] }) { +# delete $self->{state}; +# delete $self->{expr}; +# } # set background pixmap