[ViewVC] Diff of: cvs/rxvt-unicode/src/perl/background

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.37 by root, Fri Jun 8 20:35:43 2012 UTC vs.
Revision 1.44 by root, Sun Jun 10 11:31:22 2012 UTC

 #:META:X_RESOURCE:%.expr:string:background expression
 #:META:X_RESOURCE:%.border.:boolean:respect the terminal border
 #TODO: once, rootalign
+=head1 NAME
-=head1 background - manage terminal background
+   background - manage terminal background
-=head2 SYNOPSIS
+=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.
 It does so by evaluating a Perl expression that I<calculates> the image on
 Or specified as a X resource:
    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
 extended as necessary to cover the whole terminal window, and is set as a
 background pixmap.
 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
+=head2 EXPRESSIONS
 Expressions are normal Perl expressions, in fact, they are Perl blocks -
 which means you could use multiple lines and statements:
    again 3600;
    } else {
       return scale load "$HOME/sunday.png";
    }
 This expression gets evaluated once per hour. It will set F<sunday.png> as
-background on sundays, and F<weekday.png> on all other days.
+background on Sundays, and F<weekday.png> 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
 its result becomes the argument to the C<scale> function.
 Many operators also allow some parameters preceding the input image
 that modify its behaviour. For example, C<scale> 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<scale>
 has now two arguments, the C<200> and the C<load> expression, while
 C<load> 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"
+   scale 0.5, 2, load "$HOME/mypic.png"
-TODO
+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<load> are in C<tile> mode by default, so the C<tile> 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.
-=head3 CYCLES AND CACHING
+=head2 CYCLES AND CACHING
-TODO
+As has been mentioned before, the expression might be evaluated multiple
-Each time the expression is reevaluated, a new cycle is said to have begun. Many operators
+times. Each time the expression is reevaluated, a new cycle is said to
-cache their results till the next cycle. For example
+have begun. Many operators cache their results till the next cycle.
+For example, the C<load> 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 comserve 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.
-=head2 REFERENCE
+=head1 REFERENCE
-=head3 COMMAND LINE SWITCHES
+=head2 COMMAND LINE SWITCHES
 =over 4
 =item --background-expr perl-expression
 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 -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);
 our $MIN_INTERVAL = 1/100;
 {
    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
 from the root screen or by simply generating it. They are used as starting
 points to get an image you can play with.
 =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
+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);
       $img->fill ($colour);
       $img
 =back
 =head2 VARIABLES
-The following functions provide variable data such as the terminal
+The following functions provide variable data such as the terminal window
+dimensions. They are not (Perl-) variables, they jsut return stuff that
-window dimensions. Most of them make your expression sensitive to some
+varies. Most of them make your expression sensitive to some events, for
-events, for example using C<TW> (terminal width) means your expression is
+example using C<TW> (terminal width) means your expression is evaluated
-evaluated again when the terminal is resized.
+again when the terminal is resized.
 =over 4
 =item TX
       $img->sub_rect ($_[0], $_[1], $w, $h)
    }
 =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
+Scales the image by the given factors in horizontal
-(C<$width_percent>) and vertical (C<$height_percent>) direction.
+(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
-#TODO: maximise, maximise_fill?
+=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.
+=item cover $img
+=item cover $width, $height, $img
+Similar to C<fit>, 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)
+      @_ == 2 ? $img->scale ($_[0] * $img->w, $_[1] * $img->h)
-      : @_    ? $img->scale ($_[0] * $img->w * 0.01, $_[0] * $img->h * 0.01)
+      : @_    ? $img->scale ($_[0] * $img->w, $_[0] * $img->h)
               : $img->scale (TW, TH)
    }
    sub resize($$$) {
       my $img = pop;
       $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 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
 window. This gives the illusion of a larger area behind the window. It is
       my $img = pop->clone;
       $img->move ($_[0], $_[1]);
       $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]
    }
 =item contrast $factor, $img
 =item contrast $r, $g, $b, $a, $img
 Adjusts the I<contrast> 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($$;$$;$) {
       my $img = pop;
       $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<very> 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,
+         $_[2] * $img->w,
-         $_[3] * $img->h * .01,
+         $_[3] * $img->h,
          $_[4] * (3.14159265 / 180),
       )
    }
 =back

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing rxvt-unicode/src/perl/background (file contents): Revision 1.37 by root, Fri Jun 8 20:35:43 2012 UTC vs. Revision 1.44 by root, Sun Jun 10 11:31:22 2012 UTC

Diff Legend

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.37 by root, Fri Jun 8 20:35:43 2012 UTC vs.
Revision 1.44 by root, Sun Jun 10 11:31:22 2012 UTC