--- rxvt-unicode/src/perl/background 2012/06/20 18:18:14 1.65 +++ rxvt-unicode/src/perl/background 2012/08/10 20:07:11 1.75 @@ -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 fast, 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" } @@ -158,6 +183,22 @@ 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, @@ -174,7 +215,7 @@ 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 +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 @@ -274,12 +315,13 @@ =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($) { @@ -755,6 +797,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 +853,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 +881,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 @@ -847,41 +929,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 +990,9 @@ : $frame->[FR_CACHE][0] } - sub once_again() { - delete $self->{frame_cache}; - } +# sub keep_clear() { +# delete $self->{frame_cache}; +# } =back @@ -934,7 +1015,7 @@ sub set_expr { my ($self, $expr) = @_; - $self->{root} = []; + $self->{root} = []; # the outermost frame $self->{expr} = $expr; $self->recalculate; } @@ -1006,7 +1087,7 @@ local $self = $arg_self; local $HOME = $ENV{HOME}; - local $frame = []; + local $frame = $self->{root}; ($x, $y, $w, $h) = $self->background_geometry ($self->{border});