README

   1 I've always liked this little program. An aquarium for your screen, with
   2 fish swimming around on your desktop. It traces its history to the the xfish
   3 program, written around 1987 by John Bradley. Jonathan Greenblatt ported it
   4 to X11 in 1988 and it made its way into the contributed program collection
   5 by about X11R6. Eric Bina worked on the color maps and root window support
   6 and added a lot more fish around 1992. TJ Phan added Truecolor support in
   7 1996. Vincent Renardias contributed a man page, and Joey Hess packaged it up
   8 for Debian.
   9
  10 When I learned xfishtank had been orphaned, I decided to adopt it, or at
  11 least give it a decent home. I've tried to reflect the history in the git
  12 log. If you know of intermediate versions not represented here, send them
  13 along.
  14
  15 Pushed to github Feb 2012 by Jim Rees.
  16
  17 Build and install should go something like this:
  18 tar xfvz xfishtank.tar.gz (or git clone the repo)
  19 cd xfishtank
  20 xmkmf
  21 make
  22 sudo make install
  23
  24 Here's the README as I found it.  Also see README.debian for more recent
  25 history.
  26
  27
  28        ********************** FUN WITH FISH *********************
  29
  30 There are lots of programs for lots of platforms to make fish swim in the
  31 background of your screen.  This is a modification of an old one called
  32 xfish (also called Xaquarium), that I have added more features to.
  33
  34 To not confuse you (or confuse you more) I will call this modified xfish
  35 "xfishtank". ['A rose by any other name...' and all that]
  36
  37
  38 How is this different?  I started with you basic xfish, and I kept the
  39 bubbles (actually I re-wrote some of the bubble code, but it LOOKS the same).
  40 I changed the rest of the code to allow any number of multicolored fish to
  41 swim around.  Each fish can have up to 255 colors, but on startup the program
  42 takes all the colors from all the fish, and squeezes them down to all fit
  43 into the default colormap as best it can.  Any fish can be any size in
  44 width and height.  To make them look more like they are swimming, fish are
  45 animated (Very simple 2 frame animation) [I got this idea from watching
  46 the AfterDark fish on the Mac].  Fish CANNOT swim over each other, they
  47 will turn around if they are about to collide.  I had a version that
  48 had fish swiming over each other, it was WAY to slow to be something to run
  49 on your background while working, so I deleted it.
  50
  51 xfishtank -help to see the command line options.
  52
  53
  54        ********************** NEW FUN WITH FISH *********************
  55
  56 Since the original version, I have received various comments and bug fixes.
  57 This version I know runs on SGIs running 4.0, Sparcs running 4.1,
  58 Decstations running 4.1, and RS6000s running 3.1.  However, there were mongo
  59 memory leaks in the X server distributed with the RS6000, so I had to compile
  60 the X11R5 server and use that.
  61
  62 As you add more fish (especially very colorful fish) the total color use set
  63 becomes quite large (greater than 255).  I added 2 new options to help you
  64 deal with this.  By default xfishtank would find the total color use set
  65 for all the fish you requested, and then start allocating out of the default
  66 colormap until it filled up, it would then match the rest of the colors to
  67 whatever colors it could get.  This first come first serve color allocation
  68 can give really bad results for large color sets.  I added the -m option
  69 to allow you to specify that the program should cut the color use set down
  70 to the number you specify with the -m option before starting to allocate
  71 out of the default colormap.  The algorithm used by -m is considerably better
  72 than first come first serve.  Also, having xfishtank use ALL the available
  73 cells in the default colormap can be bad.  The -C options lets you limit how
  74 many cells xfishtank will take out of the default colormap.
  75 In the first come first serve senario colors are allocated for the fish,
  76 in the order of appearance in the FishList file, and then from the backgound
  77 picture if one exists.
  78
  79 Finally, due to popular demand, I put back in my clipmask code.  By setting
  80 the -d option (for Do clipping), xfishtank will swim its fish over whatever
  81 you already have on your root window.  WARNING:  This will slow down your
  82 machine!  The reason I took this code out originally was it slowed my
  83 machine down too much for me to comfortably work.  But if you think you have
  84 a really spiffy fast workstation, go ahead and give it a try.
  85
  86 If you use the -d option and notice some flicker (which I expect you will),
  87 this is because xfishtank is just doing an XClearArea, and letting the root
  88 redraw its background.  If you know what you want your background picture to
  89 be, use -p <image_file> instead of -d.  The image_file needs to be a gif
  90 image.  Since xfishtank now knows what your background is, xfishtank with
  91 the -p option should have much less flicker.  However, it suffers the
  92 disadvantage that you can't change the background picture without restarting
  93 xfishtank.
  94
  95 The intrepid explorer of the source code will notice that there are some
  96 options not described in xfishtank -help.  In particular -o -and -D.  These
  97 options aren't described because they were stuff I was fussing with and couldn't
  98 get to work.  I left them in on this release so that if someone else wanted
  99 to try and get them to work, they could see what I had already tried.  The -o
 100 option lets fish try and swim on top of each other.  It looks ugly no matter
 101 how I do it, if you can fix it, great.  -D is a special option that is only
 102 active if you have also specified -d and -p.  Normally you never want to specify
 103 both -d and -p because it doesn't make the animation any better, and it
 104 slightly messes up fish to bubble intersections.  However, if you specify
 105 -d -D -o -p you will get as close as I could get to proper fish intersections.
 106 And when you see how crumby these are, and how slow it makes your machine
 107 you will know why I gave up.
 108
 109 Ok, I'll fess up, I'm lying, I did actually get good fish to fish intersections
 110 but only by writing a completely different version of xfishtank that has
 111 each fish be a shaped override-redirect window, that moves itself, and changes
 112 its shape-mask to animate.  This looks REALLY COOL, but grinds any and all
 113 X servers to a complete standstill.
 114
 115
 116        ********************** NEW FISH PICTURES *********************
 117
 118 This release contains a grand total of 29 fish!  These fish were carefully
 119 created through lots of hard work, and the help of many many people who
 120 sent me pictures of fish, non-copyrighted gifs of fish, and allowed me to
 121 borrow their scanners.  I'm not going to try and name them all here, there
 122 are lots of you, and I'm afraid I may miss someone.  You all know who you are,
 123 and you have my heartfelt thanks, I couldn't have done this without you.
 124
 125
 126        ********************** TROUBLE WITH FISH *********************
 127
 128 There is a scarcity of good fish pictures in the world, and they are all
 129 protected by lawyers.  Here is the solution I propose.
 130
 131 Any of you with talent can edit up any pictures you want, somehow get them
 132 into GIF format, and import them into your xfishtank.  The program
 133 "giftofish" that I am supplying here takes as input any 2 GIF files,
 134 and creates a xfishtank header file for that fish.  The 2 files must have
 135 the same width and height, and must both have the same background color.
 136 The pictures are assumed to be the two frames of an animated fish swiming right.
 137 Put this new header file into your fishmaps directory, edit the FishList
 138 file to add the prefix of that header file, and increment the total fishcount
 139 on the first line of that file.  Now recompile xfishtank, and your new fish
 140 will be used.  Also, the program fishtogif will extract the two gifs from
 141 any fish header file so you can touch up what you already have.
 142
 143 Other fish sources:
 144         The AfterDark fish on the Mac are beautiful.  If you
 145 have already shelled out the money to Berkely Systems Software to buy those
 146 fish, and you also want to see them on your UNIX box, here is what you do.
 147 If you can transfer the Mac fish files to UNIX, run the "gofish" program
 148 supplied here, it will write out the fish into two intermediate files.
 149 The files will look strange, they are my own format, just feed them to the
 150 giftofish program (which understands that format), and it will create a
 151 fish header file for you.
 152         OpenWindows 3.0 comes with some fish pictures.  If you have purchased
 153 Openwindows, and want to use those pictures, the program "rasttofish"
 154 supplied here will read one of their sun raster fish pictures, and produce
 155 a xfishtank header file for it.  Note, the Openwindows fish are only one
 156 frame, so the won't be animated.
 157         There is apparently a PC Windows program with some swimming fish.
 158 The individual fish are stored in .fsh files.  The program pcfshtofish
 159 will turn one of these .fsh files into an xfishtank header file.
 160
 161
 162             ********************** THANKS *********************
 163
 164 A really big thanks to well over 100 wonderful people who after downloading
 165 the last version of xfishtank took the time to send me such pleasant,
 166 complimentary, and supportive e-mail.  This version was never planned, but
 167 all of you have made me feel better about writing this code than anything
 168 that any employer has ever paid me for.
 169
 170
 171 As usual, mail any problems, questions, complaints, reccommendations, and
 172 cookies to me.
 173
 174 Eric Bina
 175 508 E. Michigan, #35
 176 Urbana, IL 61801
 177
 178 ebina@ncsa.uiuc.edu
 179
 180 (217)344-9101
 181 Work(217)244-6133
 182
 183