--- rxvt-unicode/src/perl/background 2012/06/19 18:17:56 1.63 +++ rxvt-unicode/src/perl/background 2012/08/14 23:57:07 1.76 @@ -14,6 +14,30 @@ --background-border --background-interval seconds +=head1 QUICK AND DIRTY CHEAT SHEET + +Just load a random jpeg image and tile the background with it without +scaling or anything else: + + load "/path/to/img.jpg" + +The same, but use mirroring/reflection instead of tiling: + + mirror load "/path/to/img.jpg" + +Load an image and scale it to exactly fill the terminal window: + + scale keep { load "/path/to/img.jpg" } + +Implement pseudo-transparency by using a suitably-aligned root pixmap +as window background: + + rootalign root + +Likewise, but keep a blurred copy: + + rootalign keep { blur 10, root } + =head1 DESCRIPTION This extension manages the terminal background by creating a picture that @@ -28,11 +52,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 +79,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 +90,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 is 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 +terminal 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,81 +144,109 @@ 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 again +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: - tile load "$HOME/mypic.png" + scale 0.5, 2, keep { load "$HOME/mypic.png" } -In fact, images returned by C are in C mode by default, so the C operator -is kind of superfluous. +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. -Another common effect is to mirror the image, so that the same edges touch: +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. - mirror 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: -This is also a typical background expression: + tile keep { load "$HOME/mypic.png" } - rootalign root +In fact, images returned by C are in C mode by default, so the +C operator is kind of superfluous. + +Another common effect is to mirror the image, so that the same edges +touch: -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. + mirror keep { load "$HOME/mypic.png" } -=head2 CYCLES AND CACHING +Another common background expression is: + + rootalign root -=head3 C et al. +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. -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. +=head2 COLOUR SPECIFICATIONS -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. +Whenever an operator expects a "colour", then this can be specified in one +of two ways: Either as string with an X11 colour specification, such as: -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. + "red" # named colour + "#f00" # simple rgb + "[50]red" # red with 50% alpha + "TekHVC:300/50/50" # anything goes -This allows you to either speed things up by keeping multiple images in -memory, or conserve memory by loading images more often. +OR as an array reference with one, three or four components: -For example, you can keep two images in memory and use a random one like -this: + [0.5] # 50% gray, 100% alpha + [0.5, 0, 0] # dark red, no green or blur, 100% alpha + [0.5, 0, 0, 0.7] # same with explicit 70% alpha - my $img1 = load "img1.png"; - my $img2 = load "img2.png"; - (0.5 > rand) ? $img1 : $img2 +=head2 CACHING AND SENSITIVITY -Since both images are "loaded" every time the expression is evaluated, -they are always kept in memory. Contrast this version: +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. - 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 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. -=head3 C +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. -Another way to cache expensive operations is to use C. The -C operator takes a block of multiple statements enclosed by C<{}> -and evaluates it only.. once, returning any images the last statement -returned. Further calls simply produce the values from the cache. +When such an event happens, C will automatically trigger a +reevaluation of the whole expression with the new value of the expression. -This is most useful for expensive operations, such as C: +C is most useful for expensive operations, such as C: - rootalign once { blur 20, root } + rootalign keep { blur 20, root } 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 +C is quite fast, this trades extra memory (for the cached blurred pixmap) with speed (blur only needs to be redone when root changes). +=head3 C caching + +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 =head2 COMMAND LINE SWITCHES @@ -254,22 +309,26 @@ 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 -#=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, even if another copy of it +is in memory at the time. =cut + sub load_uc($) { + $self->new_img_from_file ($_[0]) + } + 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 } @@ -325,7 +384,7 @@ 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 mdoe of the resulting image. +the tiling mode of the resulting image. This function is called automatically when an expression returns multiple images. @@ -365,6 +424,8 @@ $base } +=back + =head2 TILING MODES The following operators modify the tiling mode of an image, that is, the @@ -470,9 +531,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 @@ -488,7 +549,7 @@ 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 @@ -512,7 +573,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 @@ -559,7 +621,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 @@ -663,7 +725,7 @@ Example: load an image and center it. - center pad load "mybg.png" + center keep { pad load "mybg.png" } =item rootalign $img @@ -674,7 +736,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. @@ -709,15 +771,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 @@ -738,6 +799,24 @@ =over 4 +=item tint $color, $img + +Tints the image in the given colour. + +Example: tint the image red. + + tint "red", load "rgb.png" + +Example: the same, but specify the colour by component. + + tint [1, 0, 0], load "rgb.png" + +=cut + + sub tint($$) { + $_[1]->tint ($_[0]) + } + =item contrast $factor, $img =item contrast $r, $g, $b, $img @@ -776,6 +855,8 @@ Due to idiosyncrasies in the underlying XRender extension, biases less than zero can be I slow. +You can also try the experimental(!) C operator. + =cut sub contrast($$;$$;$) { @@ -802,6 +883,26 @@ $img } +=item muladd $mul, $add, $img # EXPERIMENTAL + +First multipliesthe pixels by C<$mul>, then adds C<$add>. This cna be used +to implement brightness and contrast at the same time, with a wider value +range than contrast and brightness operators. + +Due to numerous bugs in XRender implementations, it can also introduce a +number of visual artifacts. + +Example: increase contrast by a factor of C<$c> without changing image +brightness too much. + + muladd $c, (1 - $c) * 0.5, $img + +=cut + + sub muladd($$$) { + $_[2]->muladd ($_[0], $_[1]) + } + =item blur $radius, $img =item blur $radius_horz, $radius_vert, $img @@ -830,41 +931,40 @@ =over 4 -=item once { ... } +=item keep { ... } -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 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. +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. + +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. + +Another example is C, which can be quite slow. In fact, urxvt itself encloses the whole expression in some kind of -C block so it only is reevaluated as required. +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: +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 once { blur 10, root } + rootalign 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. -=item once_again - -Resets all C block as if they had never been called, i.e. on the -next call they will be reevaluated again. - =cut - sub once(&) { + sub keep(&) { my $id = $_[0]+0; local $frame = $self->{frame_cache}{$id} ||= [$frame]; @@ -881,12 +981,6 @@ undef $frame->[FR_CACHE]; } - unless ($self->{term}) { - use Data::Dump; - ddx $frame; - exit; - } - $self->recalculate; }); }; @@ -898,9 +992,9 @@ : $frame->[FR_CACHE][0] } - sub once_again() { - delete $self->{frame_cache}; - } +# sub keep_clear() { +# delete $self->{frame_cache}; +# } =back @@ -923,7 +1017,7 @@ sub set_expr { my ($self, $expr) = @_; - $self->{root} = []; + $self->{root} = []; # the outermost frame $self->{expr} = $expr; $self->recalculate; } @@ -995,7 +1089,7 @@ local $self = $arg_self; local $HOME = $ENV{HOME}; - local $frame = []; + local $frame = $self->{root}; ($x, $y, $w, $h) = $self->background_geometry ($self->{border});