--- rxvt-unicode/src/perl/background 2012/06/07 16:30:58 1.33 +++ rxvt-unicode/src/perl/background 2012/06/10 19:01:03 1.51 @@ -1,43 +1,222 @@ #! perl #:META:X_RESOURCE:%.expr:string:background expression -#:META:X_RESOURCE:%.border.:boolean:respect the terminal border +#:META:X_RESOURCE:%.border:boolean:respect the terminal border +#:META:X_RESOURCE:%.interval:seconds:minimum time between updates -=head1 background - manage terminal background +=head1 NAME -=head2 SYNOPSIS + background - manage terminal background - rxvt -background-expr 'background expression' - -background-border +=head1 SYNOPSIS -=head2 DESCRIPTION + urxvt --background-expr 'background expression' + --background-border + --background-interval seconds -=head2 REFERENCE +=head1 DESCRIPTION -=cut +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" + +=head1 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 its size changes. + +=head2 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 scale factor (multiply by 100 to +get a percentage): + + scale 2, 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 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: + + tile load "$HOME/mypic.png" + +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: + + mirror load "$HOME/mypic.png" + +This is also a typical background expression: + + 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. -our $EXPR; -#$EXPR = 'move W * 0.1, -H * 0.1, resize W * 0.5, H * 0.5, repeat_none load "opensource.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, -# load "/root/pix/das_fette_schwein.jpg" -#'; -#$EXPR = 'solid "red"'; -#$EXPR = 'blur root, 10, 10' -#$EXPR = 'blur move (root, -x, -y), 5, 5' -#resize load "/root/pix/das_fette_schwein.jpg", w, h +=head2 CYCLES AND CACHING +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. + +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. + +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. + +This allows you to either speed things up by keeping multiple images in +memory, or conserve memory by loading images more often. + +For example, you can keep two images in memory and use a random one like +this: + + my $img1 = load "img1.png"; + my $img2 = load "img2.png"; + (0.5 > rand) ? $img1 : $img2 + +Since both images are "loaded" every time the expression is evaluated, +they are always kept in memory. Contrast this version: + + my $path1 = "img1.png"; + my $path2 = "img2.png"; + load ((0.5 > rand) ? $path1 : $path2) + +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. + +=head1 REFERENCE + +=head2 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. + +=item --background-interval seconds + +Since some operations in the underlying XRender extension can effectively +freeze your X-server for prolonged time, this extension enforces a minimum +time between updates, which is normally about 0.1 seconds. + +If you want to do updates more often, you can decrease this safety +interval with this switch. + +=back + +=cut + +our %_IMGCACHE; +our $HOME; our ($self, $old, $new); our ($x, $y, $w, $h); # enforce at least this interval between updates -our $MIN_INTERVAL = 1/100; +our $MIN_INTERVAL = 6/59.951; { package urxvt::bgdsl; # background language + use List::Util qw(min max sum shuffle); + =head2 PROVIDERS/GENERATORS These functions provide an image, by loading it from disk, grabbing it @@ -83,12 +262,12 @@ 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 +If C<$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($$;$) { + sub solid($;$$) { my $colour = pop; my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1); @@ -96,14 +275,108 @@ $img } +=item clone $img + +Returns an exact copy of the image. This is useful if you want to have +multiple copies of the same image to apply different effects to. + +=cut + + sub clone($) { + $_[0]->clone + } + =back -=head2 VARIABLES +=head2 TILING MODES -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. +The following operators modify the tiling mode of an image, that is, the +way that pixels outside the image area are painted when the image is used. + +=over 4 + +=item tile $img + +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 +that top edges always touch top edges, right edges always touch right +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 +become transparent. This mode is most useful when you want to place an +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 whatever your compositor 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 +area outside the image. This mode is mostly useful when you use more complex +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($) { + my $img = $_[0]->clone; + $img->repeat_mode (urxvt::RepeatNone); + $img + } + + sub tile($) { + my $img = $_[0]->clone; + $img->repeat_mode (urxvt::RepeatNormal); + $img + } + + sub mirror($) { + my $img = $_[0]->clone; + $img->repeat_mode (urxvt::RepeatReflect); + $img + } + + sub extend($) { + my $img = $_[0]->clone; + $img->repeat_mode (urxvt::RepeatPad); + $img + } + +=back + +=head2 VARIABLE VALUES + +The following functions provide variable data such as the terminal window +dimensions. They are not (Perl-) variables, they just return stuff that +varies. 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 @@ -160,7 +433,7 @@ 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. +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" @@ -184,83 +457,12 @@ =back -=head2 TILING MODES +=head2 SHAPE CHANGING OPERATORS -The following operators modify the tiling mode of an image, that is, the -way that pixels outside the image area are painted when the image is used. +The following operators modify the shape, size or position of the image. =over 4 -=item tile $img - -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. - -=item mirror $img - -Similar to tile, but reflects the image each time it uses a new copy, so -that top edges always touch top edges, right edges always touch right -edges and so on (with normal tiling, left edges always touch right edges -and top always touch bottom edges). - -=item pad $img - -Takes an image and modifies it so that all pixels outside the image area -become transparent. This mode is most useful when you want to place an -image over another image or the background colour while leaving all -background pixels outside the image unchanged. - -=item extend $img - -Extends the image over the whole plane, using the closest pixel in the -area outside the image. This mode is mostly useful when you more complex -filtering operations and want the pixels outside the image to have the -same values as the pixels near the edge. - -=cut - - sub pad($) { - my $img = $_[0]->clone; - $img->repeat_mode (urxvt::RepeatNone); - $img - } - - sub tile($) { - my $img = $_[0]->clone; - $img->repeat_mode (urxvt::RepeatNormal); - $img - } - - sub mirror($) { - my $img = $_[0]->clone; - $img->repeat_mode (urxvt::RepeatReflect); - $img - } - - sub extend($) { - my $img = $_[0]->clone; - $img->repeat_mode (urxvt::RepeatPad); - $img - } - -=back - -=head2 PIXEL OPERATORS - -The following operators modify the image pixels in various ways. - -=over 4 - -=item clone $img - -Returns an exact copy of the image. - -=cut - - sub clone($) { - $_[0]->clone - } - =item clip $img =item clip $width, $height, $img @@ -293,31 +495,45 @@ =item scale $img -=item scale $size_percent, $img +=item scale $size_factor, $img -=item scale $width_percent, $height_percent, $img +=item scale $width_factor, $height_factor, $img -Scales the image by the given percentages in horizontal -(C<$width_percent>) and vertical (C<$height_percent>) direction. +Scales the image by the given factors in horizontal +(C<$width>) and vertical (C<$height>) direction. -If only one percentage is give, it is used for both directions. +If only one factor is give, it is used for both directions. -If no percentages are given, scales the image to the window size without +If no factors are given, scales the image to the window size without keeping aspect. =item resize $width, $height, $img Resizes the image to exactly C<$width> times C<$height> pixels. -=cut +=item fit $img + +=item fit $width, $height, $img -#TODO: maximise, maximise_fill? +Fits the image into the given C<$width> and C<$height> without changing +aspect, or the terminal size. That means it will be shrunk or grown until +the whole image fits into the given area, possibly leaving borders. + +=item cover $img + +=item cover $width, $height, $img + +Similar to C, but shrinks or grows until all of the area is covered +by the image, so instead of potentially leaving borders, it will cut off +image data that doesn't fit. + +=cut 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) + @_ == 2 ? $img->scale ($_[0] * $img->w, $_[1] * $img->h) + : @_ ? $img->scale ($_[0] * $img->w, $_[0] * $img->h) : $img->scale (TW, TH) } @@ -326,34 +542,150 @@ $img->scale ($_[0], $_[1]) } + sub fit($;$$) { + my $img = pop; + my $w = ($_[0] || TW) / $img->w; + my $h = ($_[1] || TH) / $img->h; + scale +(min $w, $h), $img + } + + sub cover($;$$) { + my $img = pop; + my $w = ($_[0] || TW) / $img->w; + my $h = ($_[1] || TH) / $img->h; + scale +(max $w, $h), $img + } + +=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 align $xalign, $yalign, $img + +Aligns the image according to a factor - C<0> means the image is moved to +the left or top edge (for C<$xalign> or C<$yalign>), C<0.5> means it is +exactly centered and C<1> means it touches the right or bottom edge. + +Example: remove any visible border around an image, center it vertically but move +it to the right hand side. + + align 1, 0.5, pad $img + +=item center $img + +=item center $width, $height, $img + +Centers the image, i.e. the center of the image is moved to the center of +the terminal window (or the box specified by C<$width> and C<$height> if +given). + +Example: load an image and center it. + + center pad load "mybg.png" + +=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 } - sub rotate($$$$$$) { + sub align($;$$) { my $img = pop; - $img->rotate ( - $_[0], - $_[1], - $_[2] * $img->w * .01, - $_[3] * $img->h * .01, - $_[4] * (3.14159265 / 180), - ) + + move $_[0] * (TW - $img->w), + $_[1] * (TH - $img->h), + $img } - sub blur($$;$) { + sub center($;$$) { my $img = pop; - $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0]) + my $w = $_[0] || TW; + my $h = $_[1] || TH; + + move 0.5 * ($w - $img->w), 0.5 * ($h - $img->h), $img + } + + sub rootalign($) { + move -TX, -TY, $_[0] } +=back + +=head2 COLOUR MODIFICATIONS + +The following operators change the pixels of the image. + +=over 4 + +=item contrast $factor, $img + +=item contrast $r, $g, $b, $img + +=item contrast $r, $g, $b, $a, $img + +Adjusts the I of an image. + +The first form applies a single C<$factor> to red, green and blue, the +second form applies separate factors to each colour channel, and the last +form includes the alpha channel. + +Values from 0 to 1 lower the contrast, values higher than 1 increase the +contrast. + +Due to limitations in the underlying XRender extension, lowering contrast +also reduces brightness, while increasing contrast currently also +increases brightness. + +=item brightness $bias, $img + +=item brightness $r, $g, $b, $img + +=item brightness $r, $g, $b, $a, $img + +Adjusts the brightness of an image. + +The first form applies a single C<$bias> to red, green and blue, the +second form applies separate biases to each colour channel, and the last +form includes the alpha channel. + +Values less than 0 reduce brightness, while values larger than 0 increase +it. Useful range is from -1 to 1 - the former results in a black, the +latter in a white picture. + +Due to idiosyncrasies in the underlying XRender extension, biases less +than zero can be I slow. + +=cut + sub contrast($$;$$;$) { my $img = pop; my ($r, $g, $b, $a) = @_; - ($g, $b) = ($r, $r) if @_ < 4; - $a = 1 if @_ < 5; + ($g, $b) = ($r, $r) if @_ < 3; + $a = 1 if @_ < 4; $img = $img->clone; $img->contrast ($r, $g, $b, $a); @@ -364,14 +696,57 @@ my $img = pop; my ($r, $g, $b, $a) = @_; - ($g, $b) = ($r, $r) if @_ < 4; - $a = 1 if @_ < 5; + ($g, $b) = ($r, $r) if @_ < 3; + $a = 1 if @_ < 4; $img = $img->clone; $img->brightness ($r, $g, $b, $a); $img } +=item blur $radius, $img + +=item blur $radius_horz, $radius_vert, $img + +Gaussian-blurs the image with (roughly) C<$radius> pixel radius. The radii +can also be specified separately. + +Blurring is often I slow, at least compared or other +operators. Larger blur radii are slower than smaller ones, too, so if you +don't want to freeze your screen for long times, start experimenting with +low values for radius (<5). + +=cut + + sub blur($$;$) { + my $img = pop; + $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0]) + } + +=item rotate $new_width, $new_height, $center_x, $center_y, $degrees + +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>. + +#TODO# new width, height, maybe more operators? + +Example: rotate the image by 90 degrees + +=cut + + sub rotate($$$$$$) { + my $img = pop; + $img->rotate ( + $_[0], + $_[1], + $_[2] * $img->w, + $_[3] * $img->h, + $_[4] * (3.14159265 / 180), + ) + } + =back =cut @@ -411,6 +786,7 @@ local $self = $arg_self; + local $HOME = $ENV{HOME}; local $old = $self->{state}; local $new = my $state = $self->{state} = {}; @@ -421,7 +797,10 @@ my $img = eval { $self->{expr}->() }; warn $@ if $@;#d# - die if !UNIVERSAL::isa $img, "urxvt::img"; + die "background-expr did not return an image.\n" 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 @@ -429,6 +808,7 @@ 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 { @@ -467,10 +847,7 @@ delete $self->{expr}; } - # prepare and set background pixmap - - $img = $img->sub_rect (0, 0, $w, $h) - if $img->w != $w || $img->h != $h; + # set background pixmap $self->set_background ($img, $self->{border}); $self->scr_recolour (0); @@ -480,11 +857,16 @@ sub on_start { my ($self) = @_; - my $expr = $self->x_resource ("background.expr") + my $expr = $self->x_resource ("%.expr") or return; + $self->has_render + or die "background extension needs RENDER extension 0.10 or higher, ignoring background-expr.\n"; + $self->set_expr (parse_expr $expr); - $self->{border} = $self->x_resource_boolean ("background.border"); + $self->{border} = $self->x_resource_boolean ("%.border"); + + $MIN_INTERVAL = $self->x_resource ("%.interval"); () }