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

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.67 by sf-exg, Fri Jun 29 18:12:25 2012 UTC vs.
Revision 1.75 by root, Fri Aug 10 20:07:11 2012 UTC

 =head1 SYNOPSIS
    urxvt --background-expr 'background expression'
          --background-border
          --background-interval seconds
+=head1 QUICK AND DIRTY CHEAT SHEET
+Just load a random jpeg image and tile the background with it without
+scaling or anything else:
+   load "/path/to/img.jpg"
+The same, but use mirroring/reflection instead of tiling:
+   mirror load "/path/to/img.jpg"
+Load an image and scale it to exactly fill the terminal window:
+   scale keep { load "/path/to/img.jpg" }
+Implement pseudo-transparency by using a suitably-aligned root pixmap
+as window background:
+   rootalign root
+Likewise, but keep a blurred copy:
+   rootalign keep { blur 10, root }
 =head1 DESCRIPTION
 This extension manages the terminal background by creating a picture that
 is behind the text, replacing the normal background colour.
       } else {
          return load "$HOME/sunday.png";
       }
    }
-This expression is evaluated once per hour. It will set F<sunday.png> as
+This inner expression is evaluated once per hour (and whenever the
+terminal window is resized). It sets F<sunday.png> as background on
-background on Sundays, and F<weekday.png> on all other days.
+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
 horizontal and vertical dimensions. For example, this halves the image
 width and doubles the image height:
    scale 0.5, 2, load "$HOME/mypic.png"
-IF you try out these expressions, you might suffer from sluggishness,
+IF you try out these expressions, you might suffer from some sluggishness,
-because each time the terminal is resized, it again loads the PNG image
+because each time the terminal is resized, it loads the PNG image again
-and scales it. Scaling is usually fast, but loading the image can be quite
+and scales it. Scaling is usually fast (and unavoidable), but loading the
-time consuming. This is where C<keep> comes in handy:
+image can be quite time consuming. This is where C<keep> comes in handy:
    scale 0.5, 2, keep { load "$HOME/mypic.png" }
 The C<keep> operator executes all the statements inside the braces only
 once, or when it thinks the outcome might change. In other cases it
 This one first takes a snapshot of the screen background image, and then
 moves it to the upper left corner of the screen (as opposed to the upper
 left corner of the terminal window)- the result is pseudo-transparency:
 the image seems to be static while the window is moved around.
+=head2 COLOUR SPECIFICATIONS
+Whenever an operator expects a "colour", then this can be specified in one
+of two ways: Either as string with an X11 colour specification, such as:
+   "red"               # named colour
+   "#f00"              # simple rgb
+   "[50]red"           # red with 50% alpha
+   "TekHVC:300/50/50"  # anything goes
+OR as an array reference with one, three or four components:
+   [0.5]               # 50% gray, 100% alpha
+   [0.5, 0, 0]         # dark red, no green or blur, 100% alpha
+   [0.5, 0, 0, 0.7]    # same with explicit 70% alpha
 =head2 CACHING AND SENSITIVITY
 Since some operations (such as C<load> and C<blur>) can take a long time,
 caching results can be very important for a smooth operation. Caching can
 When such an event happens, C<keep> will automatically trigger a
 reevaluation of the whole expression with the new value of the expression.
 C<keep> is most useful for expensive operations, such as C<blur>:
-   rootalign once { blur 20, root }
+   rootalign keep { blur 20, root }
 This makes a blurred copy of the root background once, and on subsequent
 calls, just root-aligns it. Since C<blur> is usually quite slow and
 C<rootalign> is quite fast, this trades extra memory (for the cached
 blurred pixmap) with speed (blur only needs to be redone when root
 uses it), then the in-memory copy us returned instead.
 =item load_uc $path
 Load uncached - same as load, but does not cache the image, which means it
-is I<always> loaded from the filesystem again.
+is I<always> loaded from the filesystem again, even if another copy of it
+is in memory at the time.
 =cut
    sub load_uc($) {
-      $self->new_img_from_file ($path)
+      $self->new_img_from_file ($_[0])
    }
    sub load($) {
       my ($path) = @_;
 The following operators change the pixels of the image.
 =over 4
+=item tint $color, $img
+Tints the image in the given colour.
+Example: tint the image red.
+   tint "red", load "rgb.png"
+Example: the same, but specify the colour by component.
+   tint [1, 0, 0], load "rgb.png"
+=cut
+   sub tint($$) {
+      $_[1]->tint ($_[0])
+   }
 =item contrast $factor, $img
 =item contrast $r, $g, $b, $img
 =item contrast $r, $g, $b, $a, $img
 latter in a white picture.
 Due to idiosyncrasies in the underlying XRender extension, biases less
 than zero can be I<very> slow.
+You can also try the experimental(!) C<muladd> operator.
 =cut
    sub contrast($$;$$;$) {
       my $img = pop;
       my ($r, $g, $b, $a) = @_;
       $a       = 1        if @_ < 4;
       $img = $img->clone;
       $img->brightness ($r, $g, $b, $a);
       $img
+   }
+=item muladd $mul, $add, $img # EXPERIMENTAL
+First multipliesthe pixels by C<$mul>, then adds C<$add>. This cna be used
+to implement brightness and contrast at the same time, with a wider value
+range than contrast and brightness operators.
+Due to numerous bugs in XRender implementations, it can also introduce a
+number of visual artifacts.
+Example: increase contrast by a factor of C<$c> without changing image
+brightness too much.
+   muladd $c, (1 - $c) * 0.5, $img
+=cut
+   sub muladd($$$) {
+      $_[2]->muladd ($_[0], $_[1])
    }
 =item blur $radius, $img
 =item blur $radius_horz, $radius_vert, $img
 =over 4
 =item keep { ... }
-   #TODO#
 This operator takes a code block as argument, that is, one or more
 statements enclosed by braces.
-The trick is that this code block is only evaluated once - future calls
+The trick is that this code block is only evaluated when the outcome
-will simply return the original image (yes, it should only be used with
+changes - on other calls the C<keep> simply returns the image it computed
-images).
+previously (yes, it should only be used with images). Or in other words,
+C<keep> I<caches> the result of the code block so it doesn't need to be
+computed again.
-This can be extremely useful to avoid redoing the same slow operations
+This can be extremely useful to avoid redoing slow operations - for
-again and again- for example, if your background expression takes the root
+example, if your background expression takes the root background, blurs it
-background, blurs it and then root-aligns it it would have to blur the
+and then root-aligns it it would have to blur the root background on every
-root background on every window move or resize.
+window move or resize.
+Another example is C<load>, which can be quite slow.
 In fact, urxvt itself encloses the whole expression in some kind of
-C<once> block so it only is reevaluated as required.
+C<keep> block so it only is reevaluated as required.
-Putting the blur into a C<once> block will make sure the blur is only done
+Putting the blur into a C<keep> block will make sure the blur is only done
-once:
+once, while the C<rootalign> is still done each time the window moves.
-   rootlign keep { blur 10, root }
+   rootalign keep { blur 10, root }
 This leaves the question of how to force reevaluation of the block,
 in case the root background changes: If expression inside the block
 is sensitive to some event (root background changes, window geometry
 changes), then it will be reevaluated automatically as needed.
-=item once_again
-Resets all C<once> block as if they had never been called, i.e. on the
-next call they will be reevaluated again.
 =cut
-   sub once(&) {
+   sub keep(&) {
       my $id = $_[0]+0;
       local $frame = $self->{frame_cache}{$id} ||= [$frame];
       unless ($frame->[FR_CACHE]) {
       wantarray
          ? @{ $frame->[FR_CACHE] }
          : $frame->[FR_CACHE][0]
    }
-   sub once_again() {
+#   sub keep_clear() {
-      delete $self->{frame_cache};
+#      delete $self->{frame_cache};
-   }
+#   }
 =back
 =cut
 # compiles a parsed expression
 sub set_expr {
    my ($self, $expr) = @_;
-   $self->{root} = [];
+   $self->{root} = []; # the outermost frame
    $self->{expr} = $expr;
    $self->recalculate;
 }
 # takes a hash of sensitivity indicators and installs watchers
    # set environment to evaluate user expression
    local $self  = $arg_self;
    local $HOME  = $ENV{HOME};
-   local $frame = [];
+   local $frame = $self->{root};
    ($x, $y, $w, $h) = $self->background_geometry ($self->{border});
    # evaluate user expression

Diff Legend

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

Comparing rxvt-unicode/src/perl/background (file contents): Revision 1.67 by sf-exg, Fri Jun 29 18:12:25 2012 UTC vs. Revision 1.75 by root, Fri Aug 10 20:07:11 2012 UTC

Diff Legend

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.67 by sf-exg, Fri Jun 29 18:12:25 2012 UTC vs.
Revision 1.75 by root, Fri Aug 10 20:07:11 2012 UTC