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

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.66 by root, Thu Jun 28 15:19:15 2012 UTC vs.
Revision 1.72 by root, Mon Jul 2 02:01:41 2012 UTC

       } 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
+temrinal 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 agin
-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 oprator 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 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 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
 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
 =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 }
 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

Diff Legend

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

Comparing rxvt-unicode/src/perl/background (file contents): Revision 1.66 by root, Thu Jun 28 15:19:15 2012 UTC vs. Revision 1.72 by root, Mon Jul 2 02:01:41 2012 UTC

Diff Legend

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.66 by root, Thu Jun 28 15:19:15 2012 UTC vs.
Revision 1.72 by root, Mon Jul 2 02:01:41 2012 UTC