--- rxvt-unicode/src/perl/background 2012/06/07 13:12:08 1.29 +++ rxvt-unicode/src/perl/background 2012/06/08 20:35:43 1.37 @@ -1,12 +1,153 @@ #! perl #:META:X_RESOURCE:%.expr:string:background expression -#:META:X_RESOURCE:%.enable:boolean:some boolean -#:META:X_RESOURCE:%.extra.:value:extra config +#:META:X_RESOURCE:%.border.:boolean:respect the terminal border -our $EXPR; +#TODO: once, rootalign + +=head1 background - manage terminal background + +=head2 SYNOPSIS + + urxvt --background-expr 'background expression' + --background-border + +=head2 DESCRIPTION + +This extension manages the terminal background by creating a picture that +is behind the text, replacing the normal background colour. + +It does so by evaluating a Perl expression that I the image on +the fly, for example, by grabbing the root background or loading a file. + +While the full power of Perl is available, the operators have been design +to be as simple as possible. + +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"' + +Or specified as a X resource: + + URxvt.background-expr: scale load "/path/to/mybg.png" + +=head2 THEORY OF OPERATION + +At startup, just before the window is mapped for the first time, the +expression is evaluated and must yield an image. The image is then +extended as necessary to cover the whole terminal window, and is set as a +background pixmap. + +If the image contains an alpha channel, then it will be used as-is in +visuals that support alpha channels (for example, for a compositing +manager). In other visuals, the terminal background colour will be used to +replace any transparency. + +When the expression relies, directly or indirectly, on the window size, +position, the root pixmap, or a timer, then it will be remembered. If not, +then it will be removed. + +If any of the parameters that the expression relies on changes (when the +window is moved or resized, its position or size changes; when the root +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 +example. That ensures that the picture always fills the terminal, even +after it's size changes. + +=head3 EXPRESSIONS + +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"; + } + +This expression gets evaluated once per hour. It will set 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. + +Basically, you always start with a function that "generates" an image +object, such as C, which loads an image from disk, or C, which +returns the root window background image: + + load "$HOME/mypic.png" + +The path is usually specified as a quoted string (the exact rules can be +found in the L manpage). The F<$HOME> at the beginning of the +string is expanded to the home directory. + +Then you prepend one or more modifiers or filtering expressions, such as +C: + + scale load "$HOME/mypic.png" + +Just like a mathematical expression with functions, you should read these +expressions from right to left, as the C is evaluated first, and +its result becomes the argument to the C function. + +Many operators also allow some parameters preceding the input image +that modify its behaviour. For example, C without any additional +arguments scales the image to size of the terminal window. If you specify +an additional argument, it uses it as a percentage: + + scale 200, load "$HOME/mypic.png" + +This enlarges the image by a factor of 2 (200%). As you can see, C +has now two arguments, the C<200> and the C expression, while +C only has one argument. Arguments are separated from each other by +commas. + +Scale also accepts two arguments, which are then separate factors for both +horizontal and vertical dimensions. For example, this halves the image +width and doubles the image height: + + scale 50, 200, load "$HOME/mypic.png" + +TODO + +=head3 CYCLES AND CACHING + +TODO + +Each time the expression is reevaluated, a new cycle is said to have begun. Many operators +cache their results till the next cycle. For example + +=head2 REFERENCE + +=head3 COMMAND LINE SWITCHES + +=over 4 + +=item --background-expr perl-expression + +Specifies the Perl expression to evaluate. + +=item --background-border + +By default, the expression creates an image that fills the full window, +overwriting borders and any other areas, such as the scrollbar. + +Specifying this flag changes the behaviour, so that the image only +replaces the background of the character area. + +=back + +=cut + +our $EXPR;#d# #$EXPR = 'move W * 0.1, -H * 0.1, resize W * 0.5, H * 0.5, repeat_none load "opensource.png"'; -$EXPR = 'move -X, -Y, load "argb.png"'; +$EXPR = 'move -TX, -TY, load "argb.png"'; #$EXPR = ' # rotate W, H, 50, 50, counter 1/59.95, repeat_mirror, # clip X, Y, W, H, repeat_mirror, @@ -17,9 +158,8 @@ #$EXPR = 'blur move (root, -x, -y), 5, 5' #resize load "/root/pix/das_fette_schwein.jpg", w, h -use Safe; - -our ($bgdsl_self, $old, $new); +our $HOME; +our ($self, $old, $new); our ($x, $y, $w, $h); # enforce at least this interval between updates @@ -30,6 +170,10 @@ =head2 PROVIDERS/GENERATORS +These functions provide an image, by loading it from disk, grabbing it +from the root screen or by simply generating it. They are used as starting +points to get an image you can play with. + =over 4 =item load $path @@ -37,24 +181,48 @@ Loads the image at the given C<$path>. The image is set to plane tiling mode. - +Loaded images will be cached for one cycle. =cut sub load($) { my ($path) = @_; - $new->{load}{$path} = $old->{load}{$path} || $bgdsl_self->new_img_from_file ($path); + $new->{load}{$path} = $old->{load}{$path} || $self->new_img_from_file ($path); } +=item root + +Returns the root window pixmap, that is, hopefully, the background image +of your screen. The image is set to extend mode. + +This function makes your expression root sensitive, that means it will be +reevaluated when the bg image changes. + +=cut + sub root() { $new->{rootpmap_sensitive} = 1; die "root op not supported, exg, we need you"; } - sub solid($;$$) { - my $img = $bgdsl_self->new_img (urxvt::PictStandardARGB32, $_[1] || 1, $_[2] || 1); - $img->fill ($_[0]); +=item solid $colour + +=item solid $width, $height, $colour + +Creates a new image and completely fills it with the given colour. The +image is set to tiling mode. + +If <$width> and C<$height> are omitted, it creates a 1x1 image, which is +useful for solid backgrounds or for use in filtering effects. + +=cut + + sub solid($$;$) { + my $colour = pop; + + my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1); + $img->fill ($colour); $img } @@ -62,14 +230,76 @@ =head2 VARIABLES +The following functions provide variable data such as the terminal +window dimensions. Most of them make your expression sensitive to some +events, for example using C (terminal width) means your expression is +evaluated again when the terminal is resized. + =over 4 +=item TX + +=item TY + +Return the X and Y coordinates of the terminal window (the terminal +window is the full window by default, and the character area only when in +border-respect mode). + +Using these functions make your expression sensitive to window moves. + +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. + + move -TX, -TY, load "mybg.png" + +=item TW + +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). + +Using these functions make your expression sensitive to window resizes. + +These functions are mainly useful to scale images, or to clip images to +the window size to conserve memory. + +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 + =cut - sub X() { $new->{position_sensitive} = 1; $x } - sub Y() { $new->{position_sensitive} = 1; $y } - sub W() { $new->{size_sensitive} = 1; $w } - sub H() { $new->{size_sensitive} = 1; $h } + 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 } + +=item now + +Returns the current time as (fractional) seconds since the epoch. + +Using this expression does I make your expression sensitive to time, +but the next two functions do. + +=item again $seconds + +When this function is used the expression will be reevaluated again in +C<$seconds> seconds. + +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" + +=item counter $seconds + +Like C, but also returns an increasing counter value, starting at +0, which might be useful for some simple animation effects. + +=cut sub now() { urxvt::NOW } @@ -79,7 +309,7 @@ sub counter($) { $new->{again} = $_[0]; - $bgdsl_self->{counter} + 0 + $self->{counter} + 0 } =back @@ -96,6 +326,12 @@ Tiles the whole plane with the image and returns this new image - or in other words, it returns a copy of the image in plane tiling mode. +Example: load an image and tile it over the background, without +resizing. The C call is superfluous because C already defaults +to tiling mode. + + tile load "mybg.png" + =item mirror $img Similar to tile, but reflects the image each time it uses a new copy, so @@ -103,6 +339,11 @@ edges and so on (with normal tiling, left edges always touch right edges and top always touch bottom edges). +Example: load an image and mirror it over the background, avoiding sharp +edges at the image borders at the expense of mirroring the image itself + + mirror load "mybg.png" + =item pad $img Takes an image and modifies it so that all pixels outside the image area @@ -110,6 +351,12 @@ image over another image or the background colour while leaving all background pixels outside the image unchanged. +Example: load an image and display it in the upper left corner. The rest +of the space is left "empty" (transparent or wahtever your compisotr does +in alpha mode, else background colour). + + pad load "mybg.png" + =item extend $img Extends the image over the whole plane, using the closest pixel in the @@ -117,6 +364,10 @@ filtering operations and want the pixels outside the image to have the same values as the pixels near the edge. +Example: just for curiosity, how does this pixel extension stuff work? + + extend move 50, 50, load "mybg.png" + =cut sub pad($) { @@ -186,8 +437,8 @@ sub clip($;$$;$$) { my $img = pop; - my $h = pop || H; - my $w = pop || W; + my $h = pop || TH; + my $w = pop || TW; $img->sub_rect ($_[0], $_[1], $w, $h) } @@ -213,12 +464,12 @@ #TODO: maximise, maximise_fill? - sub scale($$$) { + sub scale($;$;$) { my $img = pop; @_ == 2 ? $img->scale ($_[0] * $img->w * 0.01, $_[1] * $img->h * 0.01) : @_ ? $img->scale ($_[0] * $img->w * 0.01, $_[0] * $img->h * 0.01) - : $img->scale (W, H) + : $img->scale (TW, TH) } sub resize($$$) { @@ -226,35 +477,58 @@ $img->scale ($_[0], $_[1]) } - # TODO: ugly +=item move $dx, $dy, $img + +Moves the image by C<$dx> pixels in the horizontal, and C<$dy> pixels in +the vertical. + +Example: move the image right by 20 pixels and down by 30. + + move 20, 30, ... + +=item rootalign $img + +Moves the image so that it appears glued to the screen as opposed to the +window. This gives the illusion of a larger area behind the window. It is +exactly equivalent to C, that is, it moves the image to the +top left of the screen. + +Example: load a background image, put it in mirror mode and root align it. + + rootalign 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. + + rootalign root + +=cut + sub move($$;$) { my $img = pop->clone; $img->move ($_[0], $_[1]); $img -# my $img = pop; -# $img->sub_rect ( -# $_[0], $_[1], -# $img->w, $img->h, -# $_[2], -# ) } - sub rotate($$$$$$) { - my $img = pop; - $img->rotate ( - $_[0], - $_[1], - $_[2] * $img->w * .01, - $_[3] * $img->h * .01, - $_[4] * (3.14159265 / 180), - ) + sub rootalign($) { + move -TX, -TY, $_[0] } - sub blur($$;$) { - my $img = pop; +=item contrast $factor, $img - $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0]); - } +=item contrast $r, $g, $b, $img + +=item contrast $r, $g, $b, $a, $img + +Adjusts the I of an image. + +=item brightness $factor, $img + +=item brightness $r, $g, $b, $img + +=item brightness $r, $g, $b, $a, $img + +=cut sub contrast($$;$$;$) { my $img = pop; @@ -280,6 +554,22 @@ $img } + sub blur($$;$) { + my $img = pop; + $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0]) + } + + sub rotate($$$$$$) { + my $img = pop; + $img->rotate ( + $_[0], + $_[1], + $_[2] * $img->w * .01, + $_[3] * $img->h * .01, + $_[4] * (3.14159265 / 180), + ) + } + =back =cut @@ -302,30 +592,29 @@ # evaluate the current bg expression sub recalculate { - my ($self) = @_; + my ($arg_self) = @_; # rate limit evaluation - if ($self->{next_refresh} > urxvt::NOW) { - $self->{next_refresh_timer} = urxvt::timer->new->after ($self->{next_refresh} - urxvt::NOW)->cb (sub { - $self->recalculate; + if ($arg_self->{next_refresh} > urxvt::NOW) { + $arg_self->{next_refresh_timer} = urxvt::timer->new->after ($arg_self->{next_refresh} - urxvt::NOW)->cb (sub { + $arg_self->recalculate; }); return; } - $self->{next_refresh} = urxvt::NOW + $MIN_INTERVAL; + $arg_self->{next_refresh} = urxvt::NOW + $MIN_INTERVAL; # set environment to evaluate user expression - local $bgdsl_self = $self; + local $self = $arg_self; + local $HOME = $ENV{HOME}; local $old = $self->{state}; local $new = my $state = $self->{state} = {}; - my $border = 0; #d# - ($x, $y, $w, $h) = - $self->background_geometry ($border); + $self->background_geometry ($self->{border}); # evaluate user expression @@ -333,12 +622,16 @@ warn $@ if $@;#d# die if !UNIVERSAL::isa $img, "urxvt::img"; + $state->{size_sensitive} = 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 { @@ -377,12 +670,9 @@ delete $self->{expr}; } - # prepare and set background pixmap + # set background pixmap - $img = $img->sub_rect (0, 0, $w, $h) - if $img->w != $w || $img->h != $h; - - $self->set_background ($img, $border); + $self->set_background ($img, $self->{border}); $self->scr_recolour (0); $self->want_refresh; } @@ -390,7 +680,11 @@ sub on_start { my ($self) = @_; - $self->set_expr (parse_expr $EXPR); + my $expr = $self->x_resource ("background.expr") + or return; + + $self->set_expr (parse_expr $expr); + $self->{border} = $self->x_resource_boolean ("background.border"); () }