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

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.40 by root, Fri Jun 8 22:19:21 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;
 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"
 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"
 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
 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.
 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
 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.
 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 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 percentage of image
+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?
    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.40 by root, Fri Jun 8 22:19:21 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.40 by root, Fri Jun 8 22:19:21 2012 UTC vs.
Revision 1.44 by root, Sun Jun 10 11:31:22 2012 UTC