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

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.33 by root, Thu Jun 7 16:30:58 2012 UTC vs.
Revision 1.39 by root, Fri Jun 8 22:19:03 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:%.border.:boolean:respect the terminal border	4	#:META:X_RESOURCE:%.border.:boolean:respect the terminal border
5		5
		6	#TODO: once, rootalign
		7
6	=head1 background - manage terminal background	8	=head1 background - manage terminal background
7		9
8	=head2 SYNOPSIS	10	=head2 SYNOPSIS
9		11
10	rxvt -background-expr 'background expression'	12	urxvt --background-expr 'background expression'
11	-background-border	13	--background-border
12		14
13	=head2 DESCRIPTION	15	=head2 DESCRIPTION
14		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	Other effects than scalign are also readily available, for exmaple, you can
		118	tile the image to fill the whole window, instead of resizing it:
		119
		120	tile load "$HOME/mypic.png"
		121
		122	In fact, images returned by C<load> are in C<tile> mode by default, so the C<tile> operator
		123	is kind of superfluous.
		124
		125	Another common effect is to mirror the image, so that the same edges touch:
		126
		127	mirror load "$HOME/mypic.png"
		128
		129	This is also a typical background expression:
		130
		131	rootalign root
		132
		133	It first takes a snapshot of the screen background image, and then
		134	moves it to the upper left corner of the screen - the result is
		135	pseudo-transparency, as the image seems to be static while the window is
		136	moved around.
		137
		138	=head3 CYCLES AND CACHING
		139
		140	As has been mentioned before, the expression might be evaluated multiple
		141	times. Each time the expression is reevaluated, a new cycle is said to
		142	have begun. Many operators cache their results till the next cycle.
		143
		144	For example, the C<load> operator keeps a copy of the image. If it is
		145	asked to load the same image on the next cycle it will not load it again,
		146	but return the cached copy.
		147
		148	This only works for one cycle though, so as long as you load the same
		149	image every time, it will always be cached, but when you load a different
		150	image, it will forget about the first one.
		151
		152	This allows you to either speed things up by keeping multiple images in
		153	memory, or comserve memory by loading images more often.
		154
		155	For example, you can keep two images in memory and use a random one like
		156	this:
		157
		158	my $img1 = load "img1.png";
		159	my $img2 = load "img2.png";
		160	(0.5 > rand) ? $img1 : $img2
		161
		162	Since both images are "loaded" every time the expression is evaluated,
		163	they are always kept in memory. Contrast this version:
		164
		165	my $path1 = "img1.png";
		166	my $path2 = "img2.png";
		167	load ((0.5 > rand) ? $path1 : $path2)
		168
		169	Here, a path is selected randomly, and load is only called for one image,
		170	so keeps only one image in memory. If, on the next evaluation, luck
		171	decides to use the other path, then it will have to load that image again.
		172
15	=head2 REFERENCE	173	=head2 REFERENCE
16		174
17	=cut	175	=head3 COMMAND LINE SWITCHES
18		176
19	our $EXPR;	177	=over 4
20	#$EXPR = 'move W * 0.1, -H * 0.1, resize W * 0.5, H * 0.5, repeat_none load "opensource.png"';
21	$EXPR = 'move -TX, -TY, load "argb.png"';
22	#$EXPR = '
23	# rotate W, H, 50, 50, counter 1/59.95, repeat_mirror,
24	# clip X, Y, W, H, repeat_mirror,
25	# load "/root/pix/das_fette_schwein.jpg"
26	#';
27	#$EXPR = 'solid "red"';
28	#$EXPR = 'blur root, 10, 10'
29	#$EXPR = 'blur move (root, -x, -y), 5, 5'
30	#resize load "/root/pix/das_fette_schwein.jpg", w, h
31		178
		179	=item --background-expr perl-expression
		180
		181	Specifies the Perl expression to evaluate.
		182
		183	=item --background-border
		184
		185	By default, the expression creates an image that fills the full window,
		186	overwriting borders and any other areas, such as the scrollbar.
		187
		188	Specifying this flag changes the behaviour, so that the image only
		189	replaces the background of the character area.
		190
		191	=back
		192
		193	=cut
		194
		195	our $HOME;
32	our ($self, $old, $new);	196	our ($self, $old, $new);
33	our ($x, $y, $w, $h);	197	our ($x, $y, $w, $h);
34		198
35	# enforce at least this interval between updates	199	# enforce at least this interval between updates
36	our $MIN_INTERVAL = 1/100;	200	our $MIN_INTERVAL = 1/100;
158		322
159	When this function is used the expression will be reevaluated again in	323	When this function is used the expression will be reevaluated again in
160	C<$seconds> seconds.	324	C<$seconds> seconds.
161		325
162	Example: load some image and rotate it according to the time of day (as if it were	326	Example: load some image and rotate it according to the time of day (as if it were
163	the hour pointer of a clock). update this image every minute.	327	the hour pointer of a clock). Update this image every minute.
164		328
165	again 60; rotate TW, TH, 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png"	329	again 60; rotate TW, TH, 50, 50, (now % 86400) * -720 / 86400, scale load "myclock.png"
166		330
167	=item counter $seconds	331	=item counter $seconds
168		332
…		…
193		357
194	=item tile $img	358	=item tile $img
195		359
196	Tiles the whole plane with the image and returns this new image - or in	360	Tiles the whole plane with the image and returns this new image - or in
197	other words, it returns a copy of the image in plane tiling mode.	361	other words, it returns a copy of the image in plane tiling mode.
		362
		363	Example: load an image and tile it over the background, without
		364	resizing. The C<tile> call is superfluous because C<load> already defaults
		365	to tiling mode.
		366
		367	tile load "mybg.png"
198		368
199	=item mirror $img	369	=item mirror $img
200		370
201	Similar to tile, but reflects the image each time it uses a new copy, so	371	Similar to tile, but reflects the image each time it uses a new copy, so
202	that top edges always touch top edges, right edges always touch right	372	that top edges always touch top edges, right edges always touch right
203	edges and so on (with normal tiling, left edges always touch right edges	373	edges and so on (with normal tiling, left edges always touch right edges
204	and top always touch bottom edges).	374	and top always touch bottom edges).
205		375
		376	Example: load an image and mirror it over the background, avoiding sharp
		377	edges at the image borders at the expense of mirroring the image itself
		378
		379	mirror load "mybg.png"
		380
206	=item pad $img	381	=item pad $img
207		382
208	Takes an image and modifies it so that all pixels outside the image area	383	Takes an image and modifies it so that all pixels outside the image area
209	become transparent. This mode is most useful when you want to place an	384	become transparent. This mode is most useful when you want to place an
210	image over another image or the background colour while leaving all	385	image over another image or the background colour while leaving all
211	background pixels outside the image unchanged.	386	background pixels outside the image unchanged.
212		387
		388	Example: load an image and display it in the upper left corner. The rest
		389	of the space is left "empty" (transparent or wahtever your compisotr does
		390	in alpha mode, else background colour).
		391
		392	pad load "mybg.png"
		393
213	=item extend $img	394	=item extend $img
214		395
215	Extends the image over the whole plane, using the closest pixel in the	396	Extends the image over the whole plane, using the closest pixel in the
216	area outside the image. This mode is mostly useful when you more complex	397	area outside the image. This mode is mostly useful when you more complex
217	filtering operations and want the pixels outside the image to have the	398	filtering operations and want the pixels outside the image to have the
218	same values as the pixels near the edge.	399	same values as the pixels near the edge.
		400
		401	Example: just for curiosity, how does this pixel extension stuff work?
		402
		403	extend move 50, 50, load "mybg.png"
219		404
220	=cut	405	=cut
221		406
222	sub pad($) {	407	sub pad($) {
223	my $img = $_[0]->clone;	408	my $img = $_[0]->clone;
…		…
324	sub resize($$$) {	509	sub resize($$$) {
325	my $img = pop;	510	my $img = pop;
326	$img->scale ($_[0], $_[1])	511	$img->scale ($_[0], $_[1])
327	}	512	}
328		513
		514	=item move $dx, $dy, $img
		515
		516	Moves the image by C<$dx> pixels in the horizontal, and C<$dy> pixels in
		517	the vertical.
		518
		519	Example: move the image right by 20 pixels and down by 30.
		520
		521	move 20, 30, ...
		522
		523	=item rootalign $img
		524
		525	Moves the image so that it appears glued to the screen as opposed to the
		526	window. This gives the illusion of a larger area behind the window. It is
		527	exactly equivalent to C<move -TX, -TY>, that is, it moves the image to the
		528	top left of the screen.
		529
		530	Example: load a background image, put it in mirror mode and root align it.
		531
		532	rootalign mirror load "mybg.png"
		533
		534	Example: take the screen background and align it, giving the illusion of
		535	transparency as long as the window isn't in front of other windows.
		536
		537	rootalign root
		538
		539	=cut
		540
329	sub move($$;$) {	541	sub move($$;$) {
330	my $img = pop->clone;	542	my $img = pop->clone;
331	$img->move ($_[0], $_[1]);	543	$img->move ($_[0], $_[1]);
332	$img	544	$img
333	}	545	}
		546
		547	sub rootalign($) {
		548	move -TX, -TY, $_[0]
		549	}
		550
		551	=item contrast $factor, $img
		552
		553	=item contrast $r, $g, $b, $img
		554
		555	=item contrast $r, $g, $b, $a, $img
		556
		557	Adjusts the I<contrast> of an image.
		558
		559	#TODO#
		560
		561	=item brightness $factor, $img
		562
		563	=item brightness $r, $g, $b, $img
		564
		565	=item brightness $r, $g, $b, $a, $img
		566
		567	Adjusts the brightness of an image.
		568
		569	=cut
		570
		571	sub contrast($$;$$;$) {
		572	my $img = pop;
		573	my ($r, $g, $b, $a) = @_;
		574
		575	($g, $b) = ($r, $r) if @_ < 4;
		576	$a = 1 if @_ < 5;
		577
		578	$img = $img->clone;
		579	$img->contrast ($r, $g, $b, $a);
		580	$img
		581	}
		582
		583	sub brightness($$;$$;$) {
		584	my $img = pop;
		585	my ($r, $g, $b, $a) = @_;
		586
		587	($g, $b) = ($r, $r) if @_ < 4;
		588	$a = 1 if @_ < 5;
		589
		590	$img = $img->clone;
		591	$img->brightness ($r, $g, $b, $a);
		592	$img
		593	}
		594
		595	=item blur $radius, $img
		596
		597	=item blur $radius_horz, $radius_vert, $img
		598
		599	Gaussian-blurs the image with (roughly) C<$radius> pixel radius. The radii
		600	can also be specified separately.
		601
		602	Blurring is often I<very> slow, at least compared or other
		603	operators. Larger blur radii are slower than smaller ones, too, so if you
		604	don't want to freeze your screen for long times, start experimenting with
		605	low values for radius (<5).
		606
		607	=cut
		608
		609	sub blur($$;$) {
		610	my $img = pop;
		611	$img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
		612	}
		613
		614	=item rotate $new_width, $new_height, $center_x, $center_y, $degrees
		615
		616	Rotates the image by C<$degrees> degrees, counter-clockwise, around the
		617	pointer at C<$center_x> and C<$center_y> (specified as percentage of image
		618	width/height), generating a new image with width C<$new_width> and height
		619	C<$new_height>.
		620
		621	#TODO# new width, height, maybe more operators?
		622
		623	Example: rotate the image by 90 degrees
		624
		625	=cut
334		626
335	sub rotate($$$$$$) {	627	sub rotate($$$$$$) {
336	my $img = pop;	628	my $img = pop;
337	$img->rotate (	629	$img->rotate (
338	$_[0],	630	$_[0],
…		…
341	$_[3] * $img->h * .01,	633	$_[3] * $img->h * .01,
342	$_[4] * (3.14159265 / 180),	634	$_[4] * (3.14159265 / 180),
343	)	635	)
344	}	636	}
345		637
346	sub blur($$;$) {
347	my $img = pop;
348	$img->blur ($_[0], @_ >= 2 ? $_[1] : $_[0])
349	}
350
351	sub contrast($$;$$;$) {
352	my $img = pop;
353	my ($r, $g, $b, $a) = @_;
354
355	($g, $b) = ($r, $r) if @_ < 4;
356	$a = 1 if @_ < 5;
357
358	$img = $img->clone;
359	$img->contrast ($r, $g, $b, $a);
360	$img
361	}
362
363	sub brightness($$;$$;$) {
364	my $img = pop;
365	my ($r, $g, $b, $a) = @_;
366
367	($g, $b) = ($r, $r) if @_ < 4;
368	$a = 1 if @_ < 5;
369
370	$img = $img->clone;
371	$img->brightness ($r, $g, $b, $a);
372	$img
373	}
374
375	=back	638	=back
376		639
377	=cut	640	=cut
378		641
379	}	642	}
…		…
409		672
410	# set environment to evaluate user expression	673	# set environment to evaluate user expression
411		674
412	local $self = $arg_self;	675	local $self = $arg_self;
413		676
		677	local $HOME = $ENV{HOME};
414	local $old = $self->{state};	678	local $old = $self->{state};
415	local $new = my $state = $self->{state} = {};	679	local $new = my $state = $self->{state} = {};
416		680
417	($x, $y, $w, $h) =	681	($x, $y, $w, $h) =
418	$self->background_geometry ($self->{border});	682	$self->background_geometry ($self->{border});
…		…
421		685
422	my $img = eval { $self->{expr}->() };	686	my $img = eval { $self->{expr}->() };
423	warn $@ if $@;#d#	687	warn $@ if $@;#d#
424	die if !UNIVERSAL::isa $img, "urxvt::img";	688	die if !UNIVERSAL::isa $img, "urxvt::img";
425		689
		690	$state->{size_sensitive} = 1
		691	if $img->repeat_mode != urxvt::RepeatNormal;
		692
426	# if the expression is sensitive to external events, prepare reevaluation then	693	# if the expression is sensitive to external events, prepare reevaluation then
427		694
428	my $repeat;	695	my $repeat;
429		696
430	if (my $again = $state->{again}) {	697	if (my $again = $state->{again}) {
431	$repeat = 1;	698	$repeat = 1;
		699	my $self = $self;
432	$state->{timer} = $again == $old->{again}	700	$state->{timer} = $again == $old->{again}
433	? $old->{timer}	701	? $old->{timer}
434	: urxvt::timer->new->after ($again)->interval ($again)->cb (sub {	702	: urxvt::timer->new->after ($again)->interval ($again)->cb (sub {
435	++$self->{counter};	703	++$self->{counter};
436	$self->recalculate	704	$self->recalculate
…		…
465	unless ($repeat) {	733	unless ($repeat) {
466	delete $self->{state};	734	delete $self->{state};
467	delete $self->{expr};	735	delete $self->{expr};
468	}	736	}
469		737
470	# prepare and set background pixmap	738	# set background pixmap
471
472	$img = $img->sub_rect (0, 0, $w, $h)
473	if $img->w != $w \|\| $img->h != $h;
474		739
475	$self->set_background ($img, $self->{border});	740	$self->set_background ($img, $self->{border});
476	$self->scr_recolour (0);	741	$self->scr_recolour (0);
477	$self->want_refresh;	742	$self->want_refresh;
478	}	743	}

Diff Legend

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

Comparing rxvt-unicode/src/perl/background (file contents): Revision 1.33 by root, Thu Jun 7 16:30:58 2012 UTC vs. Revision 1.39 by root, Fri Jun 8 22:19:03 2012 UTC

Diff Legend

Comparing rxvt-unicode/src/perl/background (file contents):
Revision 1.33 by root, Thu Jun 7 16:30:58 2012 UTC vs.
Revision 1.39 by root, Fri Jun 8 22:19:03 2012 UTC