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

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.42 by root, Sun Jun 10 10:42:19 2012 UTC vs.
Revision 1.45 by root, Sun Jun 10 11:53:32 2012 UTC

 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"
 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.
       my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] || 1, $_[1] || 1);
       $img->fill ($colour);
       $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 TILING MODES
+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<tile> call is superfluous because C<load> 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 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
+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.
+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 VARIABLES
+=head2 VARIABLE VALUES
 The following functions provide variable data such as the terminal window
-dimensions. They are not (Perl-) variables, they jsut return stuff that
+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<TW> (terminal width) means your expression is evaluated
 again when the terminal is resized.
 =over 4
       $self->{counter} + 0
    }
 =back
-=head2 TILING MODES
+=head2 SHAPE CHANGING OPERATORS
-The following operators modify the tiling mode of an image, that is, the
+The following operators modify the shape, size or position of the image.
-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<tile> call is superfluous because C<load> 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 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
-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.
-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 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
       $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]
    }
+=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<contrast> of an image.
-#TODO#
+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 $factor, $img
+=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 idiosynchrasies in the underlying XRender extension, biases less
+than zero can be I<very> slow.
 =cut
    sub contrast($$;$$;$) {
       my $img = pop;
    }
 =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.42 by root, Sun Jun 10 10:42:19 2012 UTC vs. Revision 1.45 by root, Sun Jun 10 11:53:32 2012 UTC

Diff Legend

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.42 by root, Sun Jun 10 10:42:19 2012 UTC vs.
Revision 1.45 by root, Sun Jun 10 11:53:32 2012 UTC