--- rxvt-unicode/src/perl/background 2012/06/08 20:35:43 1.37 +++ rxvt-unicode/src/perl/background 2012/06/10 11:31:22 1.44 @@ -5,14 +5,16 @@ #TODO: once, rootalign -=head1 background - manage terminal background +=head1 NAME -=head2 SYNOPSIS + background - manage terminal background + +=head1 SYNOPSIS urxvt --background-expr 'background expression' --background-border -=head2 DESCRIPTION +=head1 DESCRIPTION This extension manages the terminal background by creating a picture that is behind the text, replacing the normal background colour. @@ -32,7 +34,7 @@ URxvt.background-expr: scale load "/path/to/mybg.png" -=head2 THEORY OF OPERATION +=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 @@ -59,7 +61,7 @@ example. That ensures that the picture always fills the terminal, even after it's size changes. -=head3 EXPRESSIONS +=head2 EXPRESSIONS Expressions are normal Perl expressions, in fact, they are Perl blocks - which means you could use multiple lines and statements: @@ -72,7 +74,7 @@ } This expression gets evaluated once per hour. It will set F as -background on sundays, and F on all other days. +background on Sundays, and F on all other days. Fortunately, we expect that most expressions will be much simpler, with little Perl knowledge needed. @@ -99,9 +101,10 @@ 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: +an additional argument, it uses it as a scale factor (multiply by 100 to +get a percentage): - scale 200, load "$HOME/mypic.png" + 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 @@ -112,20 +115,67 @@ horizontal and vertical dimensions. For example, this halves the image width and doubles the image height: - scale 50, 200, load "$HOME/mypic.png" + scale 0.5, 2, load "$HOME/mypic.png" + +Other effects than scalign are also readily available, for exmaple, 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. + +=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. -TODO +This allows you to either speed things up by keeping multiple images in +memory, or comserve memory by loading images more often. -=head3 CYCLES AND CACHING +For example, you can keep two images in memory and use a random one like +this: -TODO + my $img1 = load "img1.png"; + my $img2 = load "img2.png"; + (0.5 > rand) ? $img1 : $img2 -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 +Since both images are "loaded" every time the expression is evaluated, +they are always kept in memory. Contrast this version: -=head2 REFERENCE + my $path1 = "img1.png"; + my $path2 = "img2.png"; + load ((0.5 > rand) ? $path1 : $path2) -=head3 COMMAND LINE SWITCHES +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 @@ -145,19 +195,6 @@ =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 -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 - our $HOME; our ($self, $old, $new); our ($x, $y, $w, $h); @@ -168,6 +205,8 @@ { 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 @@ -213,12 +252,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); @@ -230,10 +269,11 @@ =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. +The following functions provide variable data such as the terminal window +dimensions. They are not (Perl-) variables, they jsut 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 @@ -444,31 +484,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 + +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. -#TODO: maximise, maximise_fill? +=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) } @@ -477,6 +531,20 @@ $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 @@ -486,6 +554,14 @@ move 20, 30, ... +=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). + =item rootalign $img Moves the image so that it appears glued to the screen as opposed to the @@ -510,6 +586,14 @@ $img } + sub center($;$$) { + my $img = pop; + my $w = $_[0] || TW; + my $h = $_[0] || TH; + + move 0.5 * ($w - $img->w), 0.5 * ($h - $img->h), $img + } + sub rootalign($) { move -TX, -TY, $_[0] } @@ -522,12 +606,16 @@ Adjusts the I of an image. +#TODO# + =item brightness $factor, $img =item brightness $r, $g, $b, $img =item brightness $r, $g, $b, $a, $img +Adjusts the brightness of an image. + =cut sub contrast($$;$$;$) { @@ -554,18 +642,45 @@ $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 * .01, - $_[3] * $img->h * .01, + $_[2] * $img->w, + $_[3] * $img->h, $_[4] * (3.14159265 / 180), ) }