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

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.64 by root, Tue Jun 19 20:49:53 2012 UTC vs.
Revision 1.82 by sf-exg, Sat Jan 19 10:04:34 2013 UTC

 #:META:X_RESOURCE:%.border:boolean:respect the terminal border
 #:META:X_RESOURCE:%.interval:seconds:minimum time between updates
 =head1 NAME
-   background - manage terminal background
+background - manage terminal background
 =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 fats, 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
 returns the last value computed by the brace block.
 This means that the C<load> is only executed once, which makes it much
-faster, but alos means that more memory is being used, because the loaded
+faster, but also means that more memory is being used, because the loaded
 image must be kept in memory at all times. In this expression, the
 trade-off is likely worth it.
 But back to effects: Other effects than scaling are also readily
 available, for example, you can tile the image to fill the whole window,
 Another common background expression is:
    rootalign root
 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 upepr
+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
 The most important way to cache expensive operations is to use C<keep {
 ... }>. The C<keep> operator takes a block of multiple statements enclosed
 by C<{}> and keeps the return value in memory.
 An expression can be "sensitive" to various external events, such as
-scaling or moving the window, root backgorund changes and timers. Simply
+scaling or moving the window, root background changes and timers. Simply
-using an expression (such as C<scale> without parameters) that depend on
+using an expression (such as C<scale> without parameters) that depends on
 certain changing values (called "variables"), or using those variables
 directly, will make an expression sensitive to these events - for example,
 using C<scale> or C<TW> will make the expression sensitive to the terminal
 size, and thus to resizing events.
 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
 =item load $path
 Loads the image at the given C<$path>. The image is set to plane tiling
 mode.
-If the image is already in memory (e.g. because another temrinal instance
+If the image is already in memory (e.g. because another terminal instance
 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) = @_;
 =item merge $img ...
 Takes any number of images and merges them together, creating a single
 image containing them all. The tiling mode of the first image is used as
-the tiling mdoe of the resulting image.
+the tiling mode of the resulting image.
 This function is called automatically when an expression returns multiple
 images.
 =cut
       $base->draw ($_)
          for @_;
       $base
    }
+=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.
    move -TX, -TY, keep { load "mybg.png" }
 =item TW
+=item TH
 Return the width (C<TW>) and height (C<TH>) of the terminal window (the
 terminal window is the full window by default, and the character area only
 when in border-respect mode).
 Using these functions make your expression sensitive to window resizes.
 Clips an image to the given rectangle. If the rectangle is outside the
 image area (e.g. when C<$x> or C<$y> are negative) or the rectangle is
 larger than the image, then the tiling mode defines how the extra pixels
 will be filled.
-If C<$x> an C<$y> are missing, then C<0> is assumed for both.
+If C<$x> and C<$y> are missing, then C<0> is assumed for both.
 If C<$width> and C<$height> are missing, then the window size will be
 assumed.
 Example: load an image, blur it, and clip it to the window size to save
 =item scale $width_factor, $height_factor, $img
 Scales the image by the given factors in horizontal
 (C<$width>) and vertical (C<$height>) direction.
-If only one factor is give, it is used for both directions.
+If only one factor is given, it is used for both directions.
 If no factors are given, scales the image to the window size without
 keeping aspect.
 =item resize $width, $height, $img
 =item rotate $center_x, $center_y, $degrees, $img
 Rotates the image clockwise by C<$degrees> degrees, around the point at
 C<$center_x> and C<$center_y> (specified as factor of image width/height).
-Example: rotate the image by 90 degrees around it's center.
+Example: rotate the image by 90 degrees around its center.
    rotate 0.5, 0.5, 90, keep { load "$HOME/mybg.png" }
 =cut
 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 shade $factor, $img
+Shade the image by the given factor.
+=cut
+   sub shade($$) {
+      $_[1]->shade ($_[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 multiplies the pixels by C<$mul>, then adds C<$add>. This can 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
 Anything that didn't fit any of the other categories, even after applying
 force and closing our eyes.
 =over 4
-=item once { ... }
+=item keep { ... }
-This function takes a code block as argument, that is, one or more
+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 once { 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.64 by root, Tue Jun 19 20:49:53 2012 UTC vs. Revision 1.82 by sf-exg, Sat Jan 19 10:04:34 2013 UTC

Diff Legend

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.64 by root, Tue Jun 19 20:49:53 2012 UTC vs.
Revision 1.82 by sf-exg, Sat Jan 19 10:04:34 2013 UTC