--- rxvt-unicode/src/perl/background 2012/06/19 20:49:53 1.64 +++ rxvt-unicode/src/perl/background 2012/10/23 21:08:27 1.80 @@ -6,7 +6,7 @@ =head1 NAME - background - manage terminal background +background - manage terminal background =head1 SYNOPSIS @@ -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 @@ -75,8 +99,9 @@ } } -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. @@ -119,10 +144,10 @@ scale 0.5, 2, load "$HOME/mypic.png" -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 fats, but loading the image can be quite -time consuming. This is where C comes in handy: +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: scale 0.5, 2, keep { load "$HOME/mypic.png" } @@ -131,7 +156,7 @@ returns the last value computed by the brace block. This means that the C is only executed once, which makes it much -faster, but alos means that more memory is being used, because the loaded +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. @@ -154,10 +179,26 @@ rootalign root 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 upepr +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 COLOUR SPECIFICATIONS + +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: + + "red" # named colour + "#f00" # simple rgb + "[50]red" # red with 50% alpha + "TekHVC:300/50/50" # anything goes + +OR as an array reference with one, three or four components: + + [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 + =head2 CACHING AND SENSITIVITY Since some operations (such as C and C) can take a long time, @@ -173,8 +214,8 @@ by C<{}> and keeps the return value in memory. An expression can be "sensitive" to various external events, such as -scaling or moving the window, root backgorund changes and timers. Simply -using an expression (such as C without parameters) that depend on +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 @@ -185,7 +226,7 @@ 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 @@ -268,18 +309,19 @@ Loads the image at the given C<$path>. The image is set to plane tiling mode. -If the image is already in memory (e.g. because another temrinal instance +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. +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 ($path) + $self->new_img_from_file ($_[0]) } sub load($) { @@ -342,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. @@ -382,6 +424,8 @@ $base } +=back + =head2 TILING MODES The following operators modify the tiling mode of an image, that is, the @@ -493,6 +537,8 @@ =item TW +=item TH + Return the width (C) and height (C) of the terminal window (the terminal window is the full window by default, and the character area only when in border-respect mode). @@ -569,7 +615,7 @@ 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<$x> and 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. @@ -755,6 +801,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 @@ -793,6 +857,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($$;$$;$) { @@ -819,6 +885,26 @@ $img } +=item muladd $mul, $add, $img # EXPERIMENTAL + +First multiplies the pixels by C<$mul>, then adds C<$add>. This can 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 @@ -847,41 +933,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]; @@ -909,9 +994,9 @@ : $frame->[FR_CACHE][0] } - sub once_again() { - delete $self->{frame_cache}; - } +# sub keep_clear() { +# delete $self->{frame_cache}; +# } =back @@ -934,7 +1019,7 @@ sub set_expr { my ($self, $expr) = @_; - $self->{root} = []; + $self->{root} = []; # the outermost frame $self->{expr} = $expr; $self->recalculate; } @@ -1006,7 +1091,7 @@ local $self = $arg_self; local $HOME = $ENV{HOME}; - local $frame = []; + local $frame = $self->{root}; ($x, $y, $w, $h) = $self->background_geometry ($self->{border});