electric sheep - a collaborative screen saver
Scott Draves <readme@electricsheep.org>
http://electricsheep.org
see the file COPYING for the license covering this software.


Electric Sheep is an xscreensaver module that displays mpeg video of
an animated fractal flame.  In the background it contributes render
cycles to the next animation.  Periodically it uploades completed
frames to the server, where they are compressed for distribution to
all clients.

This program is recommended only if you have a high bandwidth
connection to the internet such as DSL or cable modem.

As usual, to configure, build, and install:

	./configure
	make
	sudo make install

This package depends on curl, xloadimage, and expat.  If you don't
have them already you can find them with http://rpmfind.net.

After that you can test it by just running it from the commandline
without arguments, ie "electricsheep".  After several minutes of
downloading a window will appear and the first sheep will be drawn.

An xscreensaver configuration file is installed so that
xscreensaver-demo should list electricsheep as an option with a
graphical configuration panel.  xscreensaver is documented at
http://www.jwz.org/xscreensaver/man.html

If you install the hacked version of xscreensaver, then you can vote
for the sheep with the up and down arrow keys.  These keys will vote
for the sheep currently displayed rather than exit the saver.

----

todo:

if LIBVO_XV not defined should disable overlays.

video_out_x11.c:146 assumes cache dir is .sheep

----

changelog (note that the flame subdirectory has its own README &
changelog there):

v2.6.8 7/2006 use new libpng api, handle libpng errors properly (from
	nix at esperi.org.uk).  name the window.  update
	documentation. update use of AC_OUTPUT.  handle readonly
	parts of the cache.  avoid playing files partially downloaded
	by bittorrent.  add --show-errors option.

v2.6.7 4/2006 save sheep in the proper directory instead of ~ (from
	tais.hansen at osd.dk).  remove max_anims (more storage cleanup).

v2.6.6 4/2006 remove nplays_by_id and its associated stats.  make
 	anim_t arrays dynamically allocated (some kernels had
	trouble with the 800M of static storage.  ooops).  when
	changing generations only delete sheep from the generation we
	are leaving.  this allows users to keep archives of sheep in
	their caches without fear of deletion.  version to 2.6.6

v2.6.5 3/2006 support recursively searching cache directory to be
	compatible with subscribers to the feed of torrents.

v2.6.4 12/2005 protect again buffer overflows.  remove use of tif and xsetbg.

v2.6.3 7/2005 autogenerate electricsheep.spec and electricsheep.xml with
	current version number.  zoom down to fit in the xscreensaver
	preview window.  better logging.  fix bug where special env
	args to flam3-animate were not necessarily null-terminated!
	update to latest flam3 library.  make gcc4 happy & update
	autotools.  update man page.  man page generated by configure.
	fix bug where all sheep could be deleted because of network
	errors!

v2.6.2 6/2005 generate uniqueid in client and save in in .sheep/rc
       instead of at install time in /usr/share/local...  add
       init_delay_list to be even nicer to servers.  fix the RPM.

v2.6.1 5/2005 update flam3.  add init_delay and list_freshness to
	avoid too many server accesses.

v2.6 5/2005 replace voting icons.  2.6 final.

v2.6b7 5/2005 pickup flam3 fixes, by default 1 render thread, default
	is now 1000 megabyte cache.

v2.6b4 4/2005 do not complain about partial downloads.  use more
       modern nice syntax.  configuration improvements from nix at
       esperi dot org dot uk.  update flam3 module.

v2.6b3 3/2005 voting now works much better: include a modified version
           xscreensaver that passes keypresses onto the graphics hack.
           and spawn a separate process to watch for up/down arrow on
           the root window.  and the mpeg decoder composites votes
           over the video. use new flam3 tools.  add bracket begin/end
           options to limit display to sheep within a range of dates
           or ID numbers.  history is now 300.  max_anims now 100000.
	   add logfile option.  a default value for --max-megabytes is
	   stored in the .sheep directory.  sheep are now stored with
	   the generation number in the filename.  instead of
	   hardwired bits=32 and jpeg=90, specially parse these out of
	   the genome.

v2.4 7/31/03    make history length a parameter and set the default to
		30 (it was 3).  change splash screen to include a "wait
		for download" message.  -window-id disables --zoom 1,
		this avoids a warning from xscreensaver-demo.

v2.4b7 7/16/03  minor bug in flame interpolation.

v2.4b6 7/10/03  major bug fixes in flame algorithm.  change
		--maxrepeats option to --max-repeats.

v2.4b5 6/21/03  C1 continuous interpolation and symmetries in the flame
		module, fullscreen zooming from Dan Nelson.

v2.4b3 5/27/03  change server to sheepserver.net

v2.4b2 5/7/03	fix the shared memory leak in mpeg2dec from Dan Nelson
		(according to the comment it breaks solaris
		compatibility).  install xml configuration for redhat
		9 and redhat 8.  make the default sheep cache be 100
		megabytes in the executable and in the xscreensaver
		xml configuration file.  add maxrepeats.

v2.4b1 4/12/03  support mplayer directly.  patches that fix bugs and
		FreeBSD compatibility issues from Dan Nelson:  memory
		allocation bug where filenames were stored on the
		stack after they left scope.  more error information
		from curl.  off_t may not be an integer. use
		setproctitle if supported.  use statvfs as needed, and 
		call setpgrp with 0 or 2 arguments as appropriate.
		include ctype.h.

v2.3 2/23/03	done with beta!  change the server back to 2.3 from
		2.3b.

v2.3b12 2/10/03 remove the splash-prefix argument.  increase the
		default timeout.  add the min-megabytes option.
		remove the trailing slash splash_prefix (now it comes
		from where it is used).  if you give 0 to the
		max-megabytes option then there is no maximum (except
		as imposed by min-megabytes).  there were also changes
		to the flame module.

v2.3b11 1/16/03	fix bug reported by Olin Shivers where even with
		"--root 0" it was drawing the splash/logo on the root.
		anim-flame now supports jpg directly so don't call
		cjpeg.  don't report the cache contents unless the
		debug level is 2 or higher.

v2.3b10 1/5/03	apply patch from Tal Kelrich that makes the voting
		interface optional at runtime instead of compile time,
		and adds an option to preserve the background
		(--anim-only), and fixes a bug resulting in spinning
		when trying to delete files from the local cache.

v2.3b9 12/27/02 download older animations first (instead of newer).
		fix problem of cache churn when client cache was
		smaller than server cache.  the symptom was the client
		would delete and redownload sheep endlessly.  the cure
		is to remember the sheep that have been deleted from
		the client until they are also deleted from the
		server.  the method is to use a zero-length file
		blah.xxx to remember that blah.mpg has been deleted.
		some of the code was 2-space indented.  reformat back
		to 4 spaces.

v2.3b8 12/22/02 change domain name back to electricsheep.org!
		in the flame module: handle numbers of samples that
		overflow 32 bits.  better error detection and
		reporting.  removed hard limits.  renamed hqi.c to
		hqi-flame.c and added it to the makefile so it is
		built & installed (though not used by electric sheep).

v2.3b7 12/18/02 change domain name to just electric-sheep.org.
		update my email address everywhere.

v2.3b6 12/16/02 patch from Dan Nelson fixing lack of null-termination
		of string from server in anim-flame.c

v2.3b5 12/16/02 p.k. dick's birthday is today!  fix formatting of
		source to fit in 80 columns.  improve error reporting
		when disconnected from the server.

v2.3b4 12/15/02 report text messages from the server specified by the
		<message> element.  and deal with <error>.  and an
		empty <get> tag means there are no sheep to render.

v2.3b3 12/13/02 applied patch from Dan Nelson to improve how the
                number of CPUs is calculated. put into CVS (added $Id
                strings).  smarter encoding of nick and url (don't
                escape everything).  add URL option to graphical
                config.  put flame subdirectory under autoconf and
                automake.  added flam3.com as alternate server.  check
		for presence of expat in configure.

v2.3b2 12/9/02 redid how frame rate was maintained in mpeg2dec, and
               added a lock so that multiple executables do not
               conflict (thanks to Jonathan Morton for pointing out
               these problems).  removed unused directories from
               mpeg2dec tree.

v2.3b1 12/5/02 substantial release after too many moons.  replaced
               mpegplay with mpeg2dec, ie play mpeg2 instead of mpeg1.
               protocol is now compressed xml instead of ad hoc
               crud. updated to work with redhat 8, that is, with
               xscreensaver-demo and its xml config file.  many small
               changes.

v2.1 7/3/01 vibrant colors, hue rotation, background color added. bug
            fixed by Matt Reda <mreda@mac.com>: the wrong file was
            getting deleted when it tried to reduce cache size!
            added reset fuse, statistics reporting, proxy
            argument. patch from rockear@hive-mind.net for powerpc.
            handle network disconnection and bad anim files gracefully.

v2.0 5/16/01 the big change from the 0.x to 2.x series is the
             introduction of connectivity and transitions, so the
             animation is always smoothly changing, there are no cuts
             (unless it gets stuck and it has to).  also: multiple
             rendering threads, a separate download thread, voting
             (via xscreensaver or just a named pipe), support for
             rendering single hirez frames of many tiles instead of
             animations of many frames, theoretical support for
             rendering modules other than anim.

v1.10 not released.

v1.9 reconstituted, private pre2.0 release.

v0.5 (not released) removed empty AC_CONFIG_SUBDIRS from configure.in
             and added return 0 to anim.c (bugfixes from Martin Pool).
             added net-present and parasite options, various
             bulletproofing.

v0.4 7/31/00 create ~/.sheep directory if needed (bug report by jai
             young kim).  i'm not bumping the version number since 0.4
             hasn't been distributed yet.

v0.4 6/29/00 by default now save the mpeg files in ~/.sheep/ (it keeps
             the last 50 megabytes), and switch between them instead
             of cycling the same one.  mpeg-play now exits more
             gracefully when it is unable to read the input file,
             preventing evil xscreensaver crashes i hope.  minor
             cleanup.

v0.3 12/24/99 removed curl from distribution (since no longer
              distributing libc5).  bugfix to anim.c from Steinar
              H. Gunderson and Evan Martin.  made more robust in face
              of network failures (thanks to Will Luo for pointing out
              this problem).  automatically installs gnome screensaver
              control panel files.

v0.2.1 10/17/99 splash page error no longer fatal.  added dependencies
              for xloadimage and xscreensaver to rpm spec.  should
              take curl out & use a dependency, but it's too painful
              with libc5/6.

v0.2 10/16/99 adopt curl, separate client & server, adopt automake &
              autoconf, gamma is now 1 on the client side, misc
              features & bugs.

v0.1 10/2/99 first version.  private beta release.
