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

#! perl

#:META:X_RESOURCE:%.expr:string:background expression
#:META:X_RESOURCE:%.border.:boolean:respect the terminal border

#TODO: once, rootalign

=head1 background - manage terminal background

=head2 SYNOPSIS

   urxvt --background-expr 'background expression'
         --background-border

=head2 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
the fly, for example, by grabbing the root background or loading a file.

While the full power of Perl is available, the operators have been design
to be as simple as possible.

For example, to load an image and scale it to the window size, you would
use:

   urxvt --background-expr 'scale load "/path/to/mybg.png"'

Or specified as a X resource:

   URxvt.background-expr: scale load "/path/to/mybg.png"

=head2 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.

If the image contains an alpha channel, then it will be used as-is in
visuals that support alpha channels (for example, for a compositing
manager). In other visuals, the terminal background colour will be used to
replace any transparency.

When the expression relies, directly or indirectly, on the window size,
position, the root pixmap, or a timer, then it will be remembered. If not,
then it will be removed.

If any of the parameters that the expression relies on changes (when the
window is moved or resized, its position or size changes; when the root
pixmap is replaced by another one the root background changes; or when the
timer elapses), then the expression will be evaluated again.

For example, an expression such as C<scale load "$HOME/mybg.png"> scales the
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

Expressions are normal Perl expressions, in fact, they are Perl blocks -
which means you could use multiple lines and statements:

   again 3600;
   if (localtime now)[6]) {
      return scale load "$HOME/weekday.png";
   } else {
      return scale load "$HOME/sunday.png";
   }

This expression gets evaluated once per hour. It will set F<sunday.png> as
background on 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
object, such as C<load>, which loads an image from disk, or C<root>, which
returns the root window background image:

   load "$HOME/mypic.png"

The path is usually specified as a quoted string (the exact rules can be
found in the L<perlop> manpage). The F<$HOME> at the beginning of the
string is expanded to the home directory.

Then you prepend one or more modifiers or filtering expressions, such as
C<scale>:

   scale load "$HOME/mypic.png"

Just like a mathematical expression with functions, you should read these
expressions from right to left, as the C<load> is evaluated first, and
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:

   scale 200, 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"

TODO

=head3 CYCLES AND CACHING

TODO

Each time the expression is reevaluated, a new cycle is said to have begun. Many operators
cache their results till the next cycle. For example

=head2 REFERENCE

=head3 COMMAND LINE SWITCHES

=over 4

=item --background-expr perl-expression

Specifies the Perl expression to evaluate.

=item --background-border

By default, the expression creates an image that fills the full window,
overwriting borders and any other areas, such as the scrollbar.

Specifying this flag changes the behaviour, so that the image only
replaces the background of the character area.

=back

=cut

our $EXPR;#d#
#$EXPR = 'move W * 0.1, -H * 0.1, resize W * 0.5, H * 0.5, repeat_none load "opensource.png"';
$EXPR = 'move -TX, -TY, load "argb.png"';
#$EXPR = '
#   rotate W, H, 50, 50, counter 1/59.95, repeat_mirror,
#   clip X, Y, W, H, repeat_mirror,
#   load "/root/pix/das_fette_schwein.jpg"
#';
#$EXPR = 'solid "red"';
#$EXPR = 'blur root, 10, 10'
#$EXPR = 'blur move (root, -x, -y), 5, 5'
#resize load "/root/pix/das_fette_schwein.jpg", w, h

our $HOME;
our ($self, $old, $new);
our ($x, $y, $w, $h);

# enforce at least this interval between updates
our $MIN_INTERVAL = 1/100;

{
   package urxvt::bgdsl; # background language

=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.

=over 4

=item load $path

Loads the image at the given C<$path>. The image is set to plane tiling
mode.

Loaded images will be cached for one cycle.

=cut

   sub load($) {
      my ($path) = @_;

      $new->{load}{$path} = $old->{load}{$path} || $self->new_img_from_file ($path);
   }

=item root

Returns the root window pixmap, that is, hopefully, the background image
of your screen. The image is set to extend mode.

This function makes your expression root sensitive, that means it will be
reevaluated when the bg image changes.

=cut

   sub root() {
      $new->{rootpmap_sensitive} = 1;
      die "root op not supported, exg, we need you";
   }

=item solid $colour

=item solid $width, $height, $colour

Creates a new image and completely fills it with the given colour. The
image is set to tiling mode.

If <$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($$;$) {
      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
window dimensions. 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

=item TX

=item TY

Return the X and Y coordinates 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 moves.

These functions are mainly useful to align images to the root window.

Example: load an image and align it so it looks as if anchored to the
background.

   move -TX, -TY, load "mybg.png"

=item TW

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.

These functions are mainly useful to scale images, or to clip images to
the window size to conserve memory.

Example: take the screen background, clip it to the window size, blur it a
bit, align it to the window position and use it as background.

   clip move -TX, -TY, blur 5, root

=cut

   sub TX() { $new->{position_sensitive} = 1; $x }
   sub TY() { $new->{position_sensitive} = 1; $y }
   sub TW() { $new->{size_sensitive}     = 1; $w }
   sub TH() { $new->{size_sensitive}     = 1; $h }

=item now

Returns the current time as (fractional) seconds since the epoch.

Using this expression does I<not> make your expression sensitive to time,
but the next two functions do.

=item again $seconds

When this function is used the expression will be reevaluated again in
C<$seconds> seconds.

Example: load some image and rotate it according to the time of day (as if it were
the hour pointer of a clock). Update this image every minute.

   again 60; rotate TW, TH, 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png"

=item counter $seconds

Like C<again>, but also returns an increasing counter value, starting at
0, which might be useful for some simple animation effects.

=cut

   sub now() { urxvt::NOW }

   sub again($) {
      $new->{again} = $_[0];
   }

   sub counter($) {
      $new->{again} = $_[0];
      $self->{counter} + 0
   }

=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 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

=item clip $x, $y, $width, $height, $img

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<$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
memory.

   clip blur 10, load "mybg.png"

=cut

   sub clip($;$$;$$) {
      my $img = pop;
      my $h = pop || TH;
      my $w = pop || TW;
      $img->sub_rect ($_[0], $_[1], $w, $h)
   }

=item scale $img

=item scale $size_percent, $img

=item scale $width_percent, $height_percent, $img

Scales the image by the given percentages in horizontal
(C<$width_percent>) and vertical (C<$height_percent>) direction.

If only one percentage is give, it is used for both directions.

If no percentages 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

#TODO: maximise, maximise_fill?

   sub scale($;$;$) {
      my $img = pop;

      @_ == 2 ? $img->scale ($_[0] * $img->w * 0.01, $_[1] * $img->h * 0.01)
      : @_    ? $img->scale ($_[0] * $img->w * 0.01, $_[0] * $img->h * 0.01)
              : $img->scale (TW, TH)
   }

   sub resize($$$) {
      my $img = pop;
      $img->scale ($_[0], $_[1])
   }

=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 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
exactly equivalent to C<move -TX, -TY>, that is, it moves the image to the
top left of the screen.

Example: load a background image, put it in mirror mode and root align it.

   rootalign mirror load "mybg.png"

Example: take the screen background and align it, giving the illusion of
transparency as long as the window isn't in front of other windows.

  rootalign root

=cut

   sub move($$;$) {
      my $img = pop->clone;
      $img->move ($_[0], $_[1]);
      $img
   }

   sub rootalign($) {
      move -TX, -TY, $_[0]
   }

=item contrast $factor, $img

=item contrast $r, $g, $b, $img

=item contrast $r, $g, $b, $a, $img

Adjusts the I<contrast> of an image.

=item brightness $factor, $img

=item brightness $r, $g, $b, $img

=item brightness $r, $g, $b, $a, $img

=cut

   sub contrast($$;$$;$) {
      my $img = pop;
      my ($r, $g, $b, $a) = @_;

      ($g, $b) = ($r, $r) if @_ < 4;
      $a       = 1        if @_ < 5;

      $img = $img->clone;
      $img->contrast ($r, $g, $b, $a);
      $img
   }

   sub brightness($$;$$;$) {
      my $img = pop;
      my ($r, $g, $b, $a) = @_;

      ($g, $b) = ($r, $r) if @_ < 4;
      $a       = 1        if @_ < 5;

      $img = $img->clone;
      $img->brightness ($r, $g, $b, $a);
      $img
   }

   sub blur($$;$) {
      my $img = pop;
      $img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
   }

   sub rotate($$$$$$) {
      my $img = pop;
      $img->rotate (
         $_[0],
         $_[1],
         $_[2] * $img->w * .01,
         $_[3] * $img->h * .01,
         $_[4] * (3.14159265 / 180),
      )
   }

=back

=cut

}

sub parse_expr {
   my $expr = eval "sub {\npackage urxvt::bgdsl;\n#line 0 'background expression'\n$_[0]\n}";
   die if $@;
   $expr
}

# compiles a parsed expression
sub set_expr {
   my ($self, $expr) = @_;

   $self->{expr} = $expr;
   $self->recalculate;
}

# evaluate the current bg expression
sub recalculate {
   my ($arg_self) = @_;

   # rate limit evaluation

   if ($arg_self->{next_refresh} > urxvt::NOW) {
      $arg_self->{next_refresh_timer} = urxvt::timer->new->after ($arg_self->{next_refresh} - urxvt::NOW)->cb (sub {
         $arg_self->recalculate;
      });
      return;
   }

   $arg_self->{next_refresh} = urxvt::NOW + $MIN_INTERVAL;

   # set environment to evaluate user expression

   local $self = $arg_self;

   local $HOME = $ENV{HOME};
   local $old = $self->{state};
   local $new = my $state = $self->{state} = {};

   ($x, $y, $w, $h) =
      $self->background_geometry ($self->{border});

   # evaluate user expression

   my $img = eval { $self->{expr}->() };
   warn $@ if $@;#d#
   die if !UNIVERSAL::isa $img, "urxvt::img";

   $state->{size_sensitive} = 1
      if $img->repeat_mode != urxvt::RepeatNormal;

   # if the expression is sensitive to external events, prepare reevaluation then

   my $repeat;

   if (my $again = $state->{again}) {
      $repeat = 1;
      my $self = $self;
      $state->{timer} = $again == $old->{again}
                        ? $old->{timer}
                        : urxvt::timer->new->after ($again)->interval ($again)->cb (sub {
                             ++$self->{counter};
                             $self->recalculate
                          });
   }

   if (delete $state->{position_sensitive}) {
      $repeat = 1;
      $self->enable (position_change => sub { $_[0]->recalculate });
   } else {
      $self->disable ("position_change");
   }

   if (delete $state->{size_sensitive}) {
      $repeat = 1;
      $self->enable (size_change => sub { $_[0]->recalculate });
   } else {
      $self->disable ("size_change");
   }

   if (delete $state->{rootpmap_sensitive}) {
      $repeat = 1;
      $self->enable (rootpmap_change => sub { $_[0]->recalculate });
   } else {
      $self->disable ("rootpmap_change");
   }

   # clear stuff we no longer need

   %$old = ();

   unless ($repeat) {
      delete $self->{state};
      delete $self->{expr};
   }

   # set background pixmap

   $self->set_background ($img, $self->{border});
   $self->scr_recolour (0);
   $self->want_refresh;
}

sub on_start {
   my ($self) = @_;

   my $expr = $self->x_resource ("background.expr")
      or return;

   $self->set_expr (parse_expr $expr);
   $self->{border} = $self->x_resource_boolean ("background.border");

   ()
}

Revision:	1.37
Committed:	Fri Jun 8 20:35:43 2012 UTC (11 years, 11 months ago) by root
Branch:	MAIN
Changes since 1.36:	+1 -1 lines
Log Message:	* empty log message *
#	Content
1	#! perl
2
3	#:META:X_RESOURCE:%.expr:string:background expression
4	#:META:X_RESOURCE:%.border.:boolean:respect the terminal border
5
6	#TODO: once, rootalign
7
8	=head1 background - manage terminal background
9
10	=head2 SYNOPSIS
11
12	urxvt --background-expr 'background expression'
13	--background-border
14
15	=head2 DESCRIPTION
16
17	This extension manages the terminal background by creating a picture that
18	is behind the text, replacing the normal background colour.
19
20	It does so by evaluating a Perl expression that I<calculates> the image on
21	the fly, for example, by grabbing the root background or loading a file.
22
23	While the full power of Perl is available, the operators have been design
24	to be as simple as possible.
25
26	For example, to load an image and scale it to the window size, you would
27	use:
28
29	urxvt --background-expr 'scale load "/path/to/mybg.png"'
30
31	Or specified as a X resource:
32
33	URxvt.background-expr: scale load "/path/to/mybg.png"
34
35	=head2 THEORY OF OPERATION
36
37	At startup, just before the window is mapped for the first time, the
38	expression is evaluated and must yield an image. The image is then
39	extended as necessary to cover the whole terminal window, and is set as a
40	background pixmap.
41
42	If the image contains an alpha channel, then it will be used as-is in
43	visuals that support alpha channels (for example, for a compositing
44	manager). In other visuals, the terminal background colour will be used to
45	replace any transparency.
46
47	When the expression relies, directly or indirectly, on the window size,
48	position, the root pixmap, or a timer, then it will be remembered. If not,
49	then it will be removed.
50
51	If any of the parameters that the expression relies on changes (when the
52	window is moved or resized, its position or size changes; when the root
53	pixmap is replaced by another one the root background changes; or when the
54	timer elapses), then the expression will be evaluated again.
55
56	For example, an expression such as C<scale load "$HOME/mybg.png"> scales the
57	image to the window size, so it relies on the window size and will
58	be reevaluated each time it is changed, but not when it moves for
59	example. That ensures that the picture always fills the terminal, even
60	after it's size changes.
61
62	=head3 EXPRESSIONS
63
64	Expressions are normal Perl expressions, in fact, they are Perl blocks -
65	which means you could use multiple lines and statements:
66
67	again 3600;
68	if (localtime now)[6]) {
69	return scale load "$HOME/weekday.png";
70	} else {
71	return scale load "$HOME/sunday.png";
72	}
73
74	This expression gets evaluated once per hour. It will set F<sunday.png> as
75	background on sundays, and F<weekday.png> on all other days.
76
77	Fortunately, we expect that most expressions will be much simpler, with
78	little Perl knowledge needed.
79
80	Basically, you always start with a function that "generates" an image
81	object, such as C<load>, which loads an image from disk, or C<root>, which
82	returns the root window background image:
83
84	load "$HOME/mypic.png"
85
86	The path is usually specified as a quoted string (the exact rules can be
87	found in the L<perlop> manpage). The F<$HOME> at the beginning of the
88	string is expanded to the home directory.
89
90	Then you prepend one or more modifiers or filtering expressions, such as
91	C<scale>:
92
93	scale load "$HOME/mypic.png"
94
95	Just like a mathematical expression with functions, you should read these
96	expressions from right to left, as the C<load> is evaluated first, and
97	its result becomes the argument to the C<scale> function.
98
99	Many operators also allow some parameters preceding the input image
100	that modify its behaviour. For example, C<scale> without any additional
101	arguments scales the image to size of the terminal window. If you specify
102	an additional argument, it uses it as a percentage:
103
104	scale 200, load "$HOME/mypic.png"
105
106	This enlarges the image by a factor of 2 (200%). As you can see, C<scale>
107	has now two arguments, the C<200> and the C<load> expression, while
108	C<load> only has one argument. Arguments are separated from each other by
109	commas.
110
111	Scale also accepts two arguments, which are then separate factors for both
112	horizontal and vertical dimensions. For example, this halves the image
113	width and doubles the image height:
114
115	scale 50, 200, load "$HOME/mypic.png"
116
117	TODO
118
119	=head3 CYCLES AND CACHING
120
121	TODO
122
123	Each time the expression is reevaluated, a new cycle is said to have begun. Many operators
124	cache their results till the next cycle. For example
125
126	=head2 REFERENCE
127
128	=head3 COMMAND LINE SWITCHES
129
130	=over 4
131
132	=item --background-expr perl-expression
133
134	Specifies the Perl expression to evaluate.
135
136	=item --background-border
137
138	By default, the expression creates an image that fills the full window,
139	overwriting borders and any other areas, such as the scrollbar.
140
141	Specifying this flag changes the behaviour, so that the image only
142	replaces the background of the character area.
143
144	=back
145
146	=cut
147
148	our $EXPR;#d#
149	#$EXPR = 'move W * 0.1, -H * 0.1, resize W * 0.5, H * 0.5, repeat_none load "opensource.png"';
150	$EXPR = 'move -TX, -TY, load "argb.png"';
151	#$EXPR = '
152	# rotate W, H, 50, 50, counter 1/59.95, repeat_mirror,
153	# clip X, Y, W, H, repeat_mirror,
154	# load "/root/pix/das_fette_schwein.jpg"
155	#';
156	#$EXPR = 'solid "red"';
157	#$EXPR = 'blur root, 10, 10'
158	#$EXPR = 'blur move (root, -x, -y), 5, 5'
159	#resize load "/root/pix/das_fette_schwein.jpg", w, h
160
161	our $HOME;
162	our ($self, $old, $new);
163	our ($x, $y, $w, $h);
164
165	# enforce at least this interval between updates
166	our $MIN_INTERVAL = 1/100;
167
168	{
169	package urxvt::bgdsl; # background language
170
171	=head2 PROVIDERS/GENERATORS
172
173	These functions provide an image, by loading it from disk, grabbing it
174	from the root screen or by simply generating it. They are used as starting
175	points to get an image you can play with.
176
177	=over 4
178
179	=item load $path
180
181	Loads the image at the given C<$path>. The image is set to plane tiling
182	mode.
183
184	Loaded images will be cached for one cycle.
185
186	=cut
187
188	sub load($) {
189	my ($path) = @_;
190
191	$new->{load}{$path} = $old->{load}{$path} \|\| $self->new_img_from_file ($path);
192	}
193
194	=item root
195
196	Returns the root window pixmap, that is, hopefully, the background image
197	of your screen. The image is set to extend mode.
198
199	This function makes your expression root sensitive, that means it will be
200	reevaluated when the bg image changes.
201
202	=cut
203
204	sub root() {
205	$new->{rootpmap_sensitive} = 1;
206	die "root op not supported, exg, we need you";
207	}
208
209	=item solid $colour
210
211	=item solid $width, $height, $colour
212
213	Creates a new image and completely fills it with the given colour. The
214	image is set to tiling mode.
215
216	If <$width> and C<$height> are omitted, it creates a 1x1 image, which is
217	useful for solid backgrounds or for use in filtering effects.
218
219	=cut
220
221	sub solid($$;$) {
222	my $colour = pop;
223
224	my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] \|\| 1, $_[1] \|\| 1);
225	$img->fill ($colour);
226	$img
227	}
228
229	=back
230
231	=head2 VARIABLES
232
233	The following functions provide variable data such as the terminal
234	window dimensions. Most of them make your expression sensitive to some
235	events, for example using C<TW> (terminal width) means your expression is
236	evaluated again when the terminal is resized.
237
238	=over 4
239
240	=item TX
241
242	=item TY
243
244	Return the X and Y coordinates of the terminal window (the terminal
245	window is the full window by default, and the character area only when in
246	border-respect mode).
247
248	Using these functions make your expression sensitive to window moves.
249
250	These functions are mainly useful to align images to the root window.
251
252	Example: load an image and align it so it looks as if anchored to the
253	background.
254
255	move -TX, -TY, load "mybg.png"
256
257	=item TW
258
259	Return the width (C<TW>) and height (C<TH>) of the terminal window (the
260	terminal window is the full window by default, and the character area only
261	when in border-respect mode).
262
263	Using these functions make your expression sensitive to window resizes.
264
265	These functions are mainly useful to scale images, or to clip images to
266	the window size to conserve memory.
267
268	Example: take the screen background, clip it to the window size, blur it a
269	bit, align it to the window position and use it as background.
270
271	clip move -TX, -TY, blur 5, root
272
273	=cut
274
275	sub TX() { $new->{position_sensitive} = 1; $x }
276	sub TY() { $new->{position_sensitive} = 1; $y }
277	sub TW() { $new->{size_sensitive} = 1; $w }
278	sub TH() { $new->{size_sensitive} = 1; $h }
279
280	=item now
281
282	Returns the current time as (fractional) seconds since the epoch.
283
284	Using this expression does I<not> make your expression sensitive to time,
285	but the next two functions do.
286
287	=item again $seconds
288
289	When this function is used the expression will be reevaluated again in
290	C<$seconds> seconds.
291
292	Example: load some image and rotate it according to the time of day (as if it were
293	the hour pointer of a clock). Update this image every minute.
294
295	again 60; rotate TW, TH, 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png"
296
297	=item counter $seconds
298
299	Like C<again>, but also returns an increasing counter value, starting at
300	0, which might be useful for some simple animation effects.
301
302	=cut
303
304	sub now() { urxvt::NOW }
305
306	sub again($) {
307	$new->{again} = $_[0];
308	}
309
310	sub counter($) {
311	$new->{again} = $_[0];
312	$self->{counter} + 0
313	}
314
315	=back
316
317	=head2 TILING MODES
318
319	The following operators modify the tiling mode of an image, that is, the
320	way that pixels outside the image area are painted when the image is used.
321
322	=over 4
323
324	=item tile $img
325
326	Tiles the whole plane with the image and returns this new image - or in
327	other words, it returns a copy of the image in plane tiling mode.
328
329	Example: load an image and tile it over the background, without
330	resizing. The C<tile> call is superfluous because C<load> already defaults
331	to tiling mode.
332
333	tile load "mybg.png"
334
335	=item mirror $img
336
337	Similar to tile, but reflects the image each time it uses a new copy, so
338	that top edges always touch top edges, right edges always touch right
339	edges and so on (with normal tiling, left edges always touch right edges
340	and top always touch bottom edges).
341
342	Example: load an image and mirror it over the background, avoiding sharp
343	edges at the image borders at the expense of mirroring the image itself
344
345	mirror load "mybg.png"
346
347	=item pad $img
348
349	Takes an image and modifies it so that all pixels outside the image area
350	become transparent. This mode is most useful when you want to place an
351	image over another image or the background colour while leaving all
352	background pixels outside the image unchanged.
353
354	Example: load an image and display it in the upper left corner. The rest
355	of the space is left "empty" (transparent or wahtever your compisotr does
356	in alpha mode, else background colour).
357
358	pad load "mybg.png"
359
360	=item extend $img
361
362	Extends the image over the whole plane, using the closest pixel in the
363	area outside the image. This mode is mostly useful when you more complex
364	filtering operations and want the pixels outside the image to have the
365	same values as the pixels near the edge.
366
367	Example: just for curiosity, how does this pixel extension stuff work?
368
369	extend move 50, 50, load "mybg.png"
370
371	=cut
372
373	sub pad($) {
374	my $img = $_[0]->clone;
375	$img->repeat_mode (urxvt::RepeatNone);
376	$img
377	}
378
379	sub tile($) {
380	my $img = $_[0]->clone;
381	$img->repeat_mode (urxvt::RepeatNormal);
382	$img
383	}
384
385	sub mirror($) {
386	my $img = $_[0]->clone;
387	$img->repeat_mode (urxvt::RepeatReflect);
388	$img
389	}
390
391	sub extend($) {
392	my $img = $_[0]->clone;
393	$img->repeat_mode (urxvt::RepeatPad);
394	$img
395	}
396
397	=back
398
399	=head2 PIXEL OPERATORS
400
401	The following operators modify the image pixels in various ways.
402
403	=over 4
404
405	=item clone $img
406
407	Returns an exact copy of the image.
408
409	=cut
410
411	sub clone($) {
412	$_[0]->clone
413	}
414
415	=item clip $img
416
417	=item clip $width, $height, $img
418
419	=item clip $x, $y, $width, $height, $img
420
421	Clips an image to the given rectangle. If the rectangle is outside the
422	image area (e.g. when C<$x> or C<$y> are negative) or the rectangle is
423	larger than the image, then the tiling mode defines how the extra pixels
424	will be filled.
425
426	If C<$x> an C<$y> are missing, then C<0> is assumed for both.
427
428	If C<$width> and C<$height> are missing, then the window size will be
429	assumed.
430
431	Example: load an image, blur it, and clip it to the window size to save
432	memory.
433
434	clip blur 10, load "mybg.png"
435
436	=cut
437
438	sub clip($;$$;$$) {
439	my $img = pop;
440	my $h = pop \|\| TH;
441	my $w = pop \|\| TW;
442	$img->sub_rect ($_[0], $_[1], $w, $h)
443	}
444
445	=item scale $img
446
447	=item scale $size_percent, $img
448
449	=item scale $width_percent, $height_percent, $img
450
451	Scales the image by the given percentages in horizontal
452	(C<$width_percent>) and vertical (C<$height_percent>) direction.
453
454	If only one percentage is give, it is used for both directions.
455
456	If no percentages are given, scales the image to the window size without
457	keeping aspect.
458
459	=item resize $width, $height, $img
460
461	Resizes the image to exactly C<$width> times C<$height> pixels.
462
463	=cut
464
465	#TODO: maximise, maximise_fill?
466
467	sub scale($;$;$) {
468	my $img = pop;
469
470	@_ == 2 ? $img->scale ($_[0] * $img->w * 0.01, $_[1] * $img->h * 0.01)
471	: @_ ? $img->scale ($_[0] * $img->w * 0.01, $_[0] * $img->h * 0.01)
472	: $img->scale (TW, TH)
473	}
474
475	sub resize($$$) {
476	my $img = pop;
477	$img->scale ($_[0], $_[1])
478	}
479
480	=item move $dx, $dy, $img
481
482	Moves the image by C<$dx> pixels in the horizontal, and C<$dy> pixels in
483	the vertical.
484
485	Example: move the image right by 20 pixels and down by 30.
486
487	move 20, 30, ...
488
489	=item rootalign $img
490
491	Moves the image so that it appears glued to the screen as opposed to the
492	window. This gives the illusion of a larger area behind the window. It is
493	exactly equivalent to C<move -TX, -TY>, that is, it moves the image to the
494	top left of the screen.
495
496	Example: load a background image, put it in mirror mode and root align it.
497
498	rootalign mirror load "mybg.png"
499
500	Example: take the screen background and align it, giving the illusion of
501	transparency as long as the window isn't in front of other windows.
502
503	rootalign root
504
505	=cut
506
507	sub move($$;$) {
508	my $img = pop->clone;
509	$img->move ($_[0], $_[1]);
510	$img
511	}
512
513	sub rootalign($) {
514	move -TX, -TY, $_[0]
515	}
516
517	=item contrast $factor, $img
518
519	=item contrast $r, $g, $b, $img
520
521	=item contrast $r, $g, $b, $a, $img
522
523	Adjusts the I<contrast> of an image.
524
525	=item brightness $factor, $img
526
527	=item brightness $r, $g, $b, $img
528
529	=item brightness $r, $g, $b, $a, $img
530
531	=cut
532
533	sub contrast($$;$$;$) {
534	my $img = pop;
535	my ($r, $g, $b, $a) = @_;
536
537	($g, $b) = ($r, $r) if @_ < 4;
538	$a = 1 if @_ < 5;
539
540	$img = $img->clone;
541	$img->contrast ($r, $g, $b, $a);
542	$img
543	}
544
545	sub brightness($$;$$;$) {
546	my $img = pop;
547	my ($r, $g, $b, $a) = @_;
548
549	($g, $b) = ($r, $r) if @_ < 4;
550	$a = 1 if @_ < 5;
551
552	$img = $img->clone;
553	$img->brightness ($r, $g, $b, $a);
554	$img
555	}
556
557	sub blur($$;$) {
558	my $img = pop;
559	$img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
560	}
561
562	sub rotate($$$$$$) {
563	my $img = pop;
564	$img->rotate (
565	$_[0],
566	$_[1],
567	$_[2] * $img->w * .01,
568	$_[3] * $img->h * .01,
569	$_[4] * (3.14159265 / 180),
570	)
571	}
572
573	=back
574
575	=cut
576
577	}
578
579	sub parse_expr {
580	my $expr = eval "sub {\npackage urxvt::bgdsl;\n#line 0 'background expression'\n$_[0]\n}";
581	die if $@;
582	$expr
583	}
584
585	# compiles a parsed expression
586	sub set_expr {
587	my ($self, $expr) = @_;
588
589	$self->{expr} = $expr;
590	$self->recalculate;
591	}
592
593	# evaluate the current bg expression
594	sub recalculate {
595	my ($arg_self) = @_;
596
597	# rate limit evaluation
598
599	if ($arg_self->{next_refresh} > urxvt::NOW) {
600	$arg_self->{next_refresh_timer} = urxvt::timer->new->after ($arg_self->{next_refresh} - urxvt::NOW)->cb (sub {
601	$arg_self->recalculate;
602	});
603	return;
604	}
605
606	$arg_self->{next_refresh} = urxvt::NOW + $MIN_INTERVAL;
607
608	# set environment to evaluate user expression
609
610	local $self = $arg_self;
611
612	local $HOME = $ENV{HOME};
613	local $old = $self->{state};
614	local $new = my $state = $self->{state} = {};
615
616	($x, $y, $w, $h) =
617	$self->background_geometry ($self->{border});
618
619	# evaluate user expression
620
621	my $img = eval { $self->{expr}->() };
622	warn $@ if $@;#d#
623	die if !UNIVERSAL::isa $img, "urxvt::img";
624
625	$state->{size_sensitive} = 1
626	if $img->repeat_mode != urxvt::RepeatNormal;
627
628	# if the expression is sensitive to external events, prepare reevaluation then
629
630	my $repeat;
631
632	if (my $again = $state->{again}) {
633	$repeat = 1;
634	my $self = $self;
635	$state->{timer} = $again == $old->{again}
636	? $old->{timer}
637	: urxvt::timer->new->after ($again)->interval ($again)->cb (sub {
638	++$self->{counter};
639	$self->recalculate
640	});
641	}
642
643	if (delete $state->{position_sensitive}) {
644	$repeat = 1;
645	$self->enable (position_change => sub { $_[0]->recalculate });
646	} else {
647	$self->disable ("position_change");
648	}
649
650	if (delete $state->{size_sensitive}) {
651	$repeat = 1;
652	$self->enable (size_change => sub { $_[0]->recalculate });
653	} else {
654	$self->disable ("size_change");
655	}
656
657	if (delete $state->{rootpmap_sensitive}) {
658	$repeat = 1;
659	$self->enable (rootpmap_change => sub { $_[0]->recalculate });
660	} else {
661	$self->disable ("rootpmap_change");
662	}
663
664	# clear stuff we no longer need
665
666	%$old = ();
667
668	unless ($repeat) {
669	delete $self->{state};
670	delete $self->{expr};
671	}
672
673	# set background pixmap
674
675	$self->set_background ($img, $self->{border});
676	$self->scr_recolour (0);
677	$self->want_refresh;
678	}
679
680	sub on_start {
681	my ($self) = @_;
682
683	my $expr = $self->x_resource ("background.expr")
684	or return;
685
686	$self->set_expr (parse_expr $expr);
687	$self->{border} = $self->x_resource_boolean ("background.border");
688
689	()
690	}
691