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

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.32 by sf-exg, Thu Jun 7 13:56:27 2012 UTC vs.
Revision 1.36 by root, Fri Jun 8 20:23:09 2012 UTC

…		…
1	#! perl	1	#! perl
2		2
3	#:META:X_RESOURCE:%.expr:string:background expression	3	#:META:X_RESOURCE:%.expr:string:background expression
4	#:META:X_RESOURCE:%.enable:boolean:some boolean	4	#:META:X_RESOURCE:%.border.:boolean:respect the terminal border
5	#:META:X_RESOURCE:%.extra.:value:extra config
6		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
7	our $EXPR;	148	our $EXPR;#d#
8	#$EXPR = 'move W * 0.1, -H * 0.1, resize W * 0.5, H * 0.5, repeat_none load "opensource.png"';	149	#$EXPR = 'move W * 0.1, -H * 0.1, resize W * 0.5, H * 0.5, repeat_none load "opensource.png"';
9	$EXPR = 'move -TX, -TY, load "argb.png"';	150	$EXPR = 'move -TX, -TY, load "argb.png"';
10	#$EXPR = '	151	#$EXPR = '
11	# rotate W, H, 50, 50, counter 1/59.95, repeat_mirror,	152	# rotate W, H, 50, 50, counter 1/59.95, repeat_mirror,
12	# clip X, Y, W, H, repeat_mirror,	153	# clip X, Y, W, H, repeat_mirror,
15	#$EXPR = 'solid "red"';	156	#$EXPR = 'solid "red"';
16	#$EXPR = 'blur root, 10, 10'	157	#$EXPR = 'blur root, 10, 10'
17	#$EXPR = 'blur move (root, -x, -y), 5, 5'	158	#$EXPR = 'blur move (root, -x, -y), 5, 5'
18	#resize load "/root/pix/das_fette_schwein.jpg", w, h	159	#resize load "/root/pix/das_fette_schwein.jpg", w, h
19		160
20	use Safe;	161	our $HOME;
21
22	our ($bgdsl_self, $old, $new);	162	our ($self, $old, $new);
23	our ($x, $y, $w, $h);	163	our ($x, $y, $w, $h);
24		164
25	# enforce at least this interval between updates	165	# enforce at least this interval between updates
26	our $MIN_INTERVAL = 1/100;	166	our $MIN_INTERVAL = 1/100;
27		167
…		…
46	=cut	186	=cut
47		187
48	sub load($) {	188	sub load($) {
49	my ($path) = @_;	189	my ($path) = @_;
50		190
51	$new->{load}{$path} = $old->{load}{$path} \|\| $bgdsl_self->new_img_from_file ($path);	191	$new->{load}{$path} = $old->{load}{$path} \|\| $self->new_img_from_file ($path);
52	}	192	}
53		193
54	=item root	194	=item root
55		195
56	Returns the root window pixmap, that is, hopefully, the background image	196	Returns the root window pixmap, that is, hopefully, the background image
…		…
79	=cut	219	=cut
80		220
81	sub solid($$;$) {	221	sub solid($$;$) {
82	my $colour = pop;	222	my $colour = pop;
83		223
84	my $img = $bgdsl_self->new_img (urxvt::PictStandardARGB32, $_[0] \|\| 1, $_[1] \|\| 1);	224	my $img = $self->new_img (urxvt::PictStandardARGB32, $_[0] \|\| 1, $_[1] \|\| 1);
85	$img->fill ($colour);	225	$img->fill ($colour);
86	$img	226	$img
87	}	227	}
88		228
89	=back	229	=back
…		…
135	sub TX() { $new->{position_sensitive} = 1; $x }	275	sub TX() { $new->{position_sensitive} = 1; $x }
136	sub TY() { $new->{position_sensitive} = 1; $y }	276	sub TY() { $new->{position_sensitive} = 1; $y }
137	sub TW() { $new->{size_sensitive} = 1; $w }	277	sub TW() { $new->{size_sensitive} = 1; $w }
138	sub TH() { $new->{size_sensitive} = 1; $h }	278	sub TH() { $new->{size_sensitive} = 1; $h }
139		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
140	sub now() { urxvt::NOW }	304	sub now() { urxvt::NOW }
141		305
142	sub again($) {	306	sub again($) {
143	$new->{again} = $_[0];	307	$new->{again} = $_[0];
144	}	308	}
145		309
146	sub counter($) {	310	sub counter($) {
147	$new->{again} = $_[0];	311	$new->{again} = $_[0];
148	$bgdsl_self->{counter} + 0	312	$self->{counter} + 0
149	}	313	}
150		314
151	=back	315	=back
152		316
153	=head2 TILING MODES	317	=head2 TILING MODES
…		…
159		323
160	=item tile $img	324	=item tile $img
161		325
162	Tiles the whole plane with the image and returns this new image - or in	326	Tiles the whole plane with the image and returns this new image - or in
163	other words, it returns a copy of the image in plane tiling mode.	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"
164		334
165	=item mirror $img	335	=item mirror $img
166		336
167	Similar to tile, but reflects the image each time it uses a new copy, so	337	Similar to tile, but reflects the image each time it uses a new copy, so
168	that top edges always touch top edges, right edges always touch right	338	that top edges always touch top edges, right edges always touch right
169	edges and so on (with normal tiling, left edges always touch right edges	339	edges and so on (with normal tiling, left edges always touch right edges
170	and top always touch bottom edges).	340	and top always touch bottom edges).
171		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
172	=item pad $img	347	=item pad $img
173		348
174	Takes an image and modifies it so that all pixels outside the image area	349	Takes an image and modifies it so that all pixels outside the image area
175	become transparent. This mode is most useful when you want to place an	350	become transparent. This mode is most useful when you want to place an
176	image over another image or the background colour while leaving all	351	image over another image or the background colour while leaving all
177	background pixels outside the image unchanged.	352	background pixels outside the image unchanged.
178		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
179	=item extend $img	360	=item extend $img
180		361
181	Extends the image over the whole plane, using the closest pixel in the	362	Extends the image over the whole plane, using the closest pixel in the
182	area outside the image. This mode is mostly useful when you more complex	363	area outside the image. This mode is mostly useful when you more complex
183	filtering operations and want the pixels outside the image to have the	364	filtering operations and want the pixels outside the image to have the
184	same values as the pixels near the edge.	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"
185		370
186	=cut	371	=cut
187		372
188	sub pad($) {	373	sub pad($) {
189	my $img = $_[0]->clone;	374	my $img = $_[0]->clone;
…		…
277		462
278	=cut	463	=cut
279		464
280	#TODO: maximise, maximise_fill?	465	#TODO: maximise, maximise_fill?
281		466
282	sub scale($$$) {	467	sub scale($;$;$) {
283	my $img = pop;	468	my $img = pop;
284		469
285	@_ == 2 ? $img->scale ($_[0] * $img->w * 0.01, $_[1] * $img->h * 0.01)	470	@_ == 2 ? $img->scale ($_[0] * $img->w * 0.01, $_[1] * $img->h * 0.01)
286	: @_ ? $img->scale ($_[0] * $img->w * 0.01, $_[0] * $img->h * 0.01)	471	: @_ ? $img->scale ($_[0] * $img->w * 0.01, $_[0] * $img->h * 0.01)
287	: $img->scale (TW, TH)	472	: $img->scale (TW, TH)
…		…
290	sub resize($$$) {	475	sub resize($$$) {
291	my $img = pop;	476	my $img = pop;
292	$img->scale ($_[0], $_[1])	477	$img->scale ($_[0], $_[1])
293	}	478	}
294		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
295	sub move($$;$) {	507	sub move($$;$) {
296	my $img = pop->clone;	508	my $img = pop->clone;
297	$img->move ($_[0], $_[1]);	509	$img->move ($_[0], $_[1]);
298	$img	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])
299	}	560	}
300		561
301	sub rotate($$$$$$) {	562	sub rotate($$$$$$) {
302	my $img = pop;	563	my $img = pop;
303	$img->rotate (	564	$img->rotate (
…		…
307	$_[3] * $img->h * .01,	568	$_[3] * $img->h * .01,
308	$_[4] * (3.14159265 / 180),	569	$_[4] * (3.14159265 / 180),
309	)	570	)
310	}	571	}
311		572
312	sub blur($$;$) {
313	my $img = pop;
314	$img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
315	}
316
317	sub contrast($$;$$;$) {
318	my $img = pop;
319	my ($r, $g, $b, $a) = @_;
320
321	($g, $b) = ($r, $r) if @_ < 4;
322	$a = 1 if @_ < 5;
323
324	$img = $img->clone;
325	$img->contrast ($r, $g, $b, $a);
326	$img
327	}
328
329	sub brightness($$;$$;$) {
330	my $img = pop;
331	my ($r, $g, $b, $a) = @_;
332
333	($g, $b) = ($r, $r) if @_ < 4;
334	$a = 1 if @_ < 5;
335
336	$img = $img->clone;
337	$img->brightness ($r, $g, $b, $a);
338	$img
339	}
340
341	=back	573	=back
342		574
343	=cut	575	=cut
344		576
345	}	577	}
…		…
358	$self->recalculate;	590	$self->recalculate;
359	}	591	}
360		592
361	# evaluate the current bg expression	593	# evaluate the current bg expression
362	sub recalculate {	594	sub recalculate {
363	my ($self) = @_;	595	my ($arg_self) = @_;
364		596
365	# rate limit evaluation	597	# rate limit evaluation
366		598
367	if ($self->{next_refresh} > urxvt::NOW) {	599	if ($arg_self->{next_refresh} > urxvt::NOW) {
368	$self->{next_refresh_timer} = urxvt::timer->new->after ($self->{next_refresh} - urxvt::NOW)->cb (sub {	600	$arg_self->{next_refresh_timer} = urxvt::timer->new->after ($arg_self->{next_refresh} - urxvt::NOW)->cb (sub {
369	$self->recalculate;	601	$arg_self->recalculate;
370	});	602	});
371	return;	603	return;
372	}	604	}
373		605
374	$self->{next_refresh} = urxvt::NOW + $MIN_INTERVAL;	606	$arg_self->{next_refresh} = urxvt::NOW + $MIN_INTERVAL;
375		607
376	# set environment to evaluate user expression	608	# set environment to evaluate user expression
377		609
378	local $bgdsl_self = $self;	610	local $self = $arg_self;
379		611
		612	local $HOME = $ENV{HOME};
380	local $old = $self->{state};	613	local $old = $self->{state};
381	local $new = my $state = $self->{state} = {};	614	local $new = my $state = $self->{state} = {};
382		615
383	my $border = 0; #d#
384
385	($x, $y, $w, $h) =	616	($x, $y, $w, $h) =
386	$self->background_geometry ($border);	617	$self->background_geometry ($self->{border});
387		618
388	# evaluate user expression	619	# evaluate user expression
389		620
390	my $img = eval { $self->{expr}->() };	621	my $img = eval { $self->{expr}->() };
391	warn $@ if $@;#d#	622	warn $@ if $@;#d#
392	die if !UNIVERSAL::isa $img, "urxvt::img";	623	die if !UNIVERSAL::isa $img, "urxvt::img";
393		624
		625	$state->{size_sensitive} = 1
		626	if $img->repeat_mode != urxvt::RepeatNormal;
		627
394	# if the expression is sensitive to external events, prepare reevaluation then	628	# if the expression is sensitive to external events, prepare reevaluation then
395		629
396	my $repeat;	630	my $repeat;
397		631
398	if (my $again = $state->{again}) {	632	if (my $again = $state->{again}) {
399	$repeat = 1;	633	$repeat = 1;
		634	my $self = $self;
400	$state->{timer} = $again == $old->{again}	635	$state->{timer} = $again == $old->{again}
401	? $old->{timer}	636	? $old->{timer}
402	: urxvt::timer->new->after ($again)->interval ($again)->cb (sub {	637	: urxvt::timer->new->after ($again)->interval ($again)->cb (sub {
403	++$self->{counter};	638	++$self->{counter};
404	$self->recalculate	639	$self->recalculate
…		…
433	unless ($repeat) {	668	unless ($repeat) {
434	delete $self->{state};	669	delete $self->{state};
435	delete $self->{expr};	670	delete $self->{expr};
436	}	671	}
437		672
438	# prepare and set background pixmap	673	# set background pixmap
439		674
440	$img = $img->sub_rect (0, 0, $w, $h)
441	if $img->w != $w \|\| $img->h != $h;
442
443	$self->set_background ($img, $border);	675	$self->set_background ($img, $self->{border});
444	$self->scr_recolour (0);	676	$self->scr_recolour (0);
445	$self->want_refresh;	677	$self->want_refresh;
446	}	678	}
447		679
448	sub on_start {	680	sub on_start {
449	my ($self) = @_;	681	my ($self) = @_;
450		682
		683	my $expr = $self->x_resource ("background.expr")
		684	or return;
		685
451	$self->set_expr (parse_expr $EXPR);	686	$self->set_expr (parse_expr $expr);
		687	$self->{border} = $self->x_resource_boolean ("background.border");
452		688
453	()	689	()
454	}	690	}
455		691

Diff Legend

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

Comparing rxvt-unicode/src/perl/background (file contents): Revision 1.32 by sf-exg, Thu Jun 7 13:56:27 2012 UTC vs. Revision 1.36 by root, Fri Jun 8 20:23:09 2012 UTC

Diff Legend

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.32 by sf-exg, Thu Jun 7 13:56:27 2012 UTC vs.
Revision 1.36 by root, Fri Jun 8 20:23:09 2012 UTC