@database Aquarium.guide
@master Aquarium.guide
@$VER: Aquarium.guide 1.0 (12-Sep-97)
@author "Ingo Schmiegel"
@(c) "© 1997 Ingo Schmiegel"

@node "Main" "Aquarium.guide/Main"
@{u}@{FG shine}Aquarium v1.0@{FG text}@{uu}

Aquarium is another one of those fine modules for the famous
Garshneblanker screensaver.

This module shows animations on the screen.
It can move the objects displaying those animations around in
given patterns which you can select.
You can draw your own animations and you've full control over
a preferences file which lists the objects and animations which
are used.

The modules preferences let you control the display resolution
and the preferences file used.

@{" Installation     " link "installation"}
@{" Parameters       " link "parameters"  }
@{" Preferences file " link "prefsfile"   }
@{" Animation format " link "animation"   }
@{" Author           " link "author"      }
@{" Copyright        " link "copyright"   }
@{" Disclaimer       " link "disclaimer"  }
@{" Future           " link "future"      }
@{" History          " link "history"     }
@endnode

@node "installation" "Aquarium.guide/installation"
Just unpack the archive with:
    lha -xa x GBAquari.lha ram:
(Probably you've done that already.)

Then just copy the files
    @{FG fill}Aquarium@{FG text}
    @{FG fill}Aquarium.ifc@{FG text}
    @{FG fill}Aquarium.prefs@{FG text}
    @{FG fill}Aquarium.txt@{FG text}
to your Garshneblanker modules directory


Copy @{FG fill}Aquarium.guide@{FG text} (this documentation) anywhere you like.

Copy the directory @{FG fill}AquariumData@{FG text} anywhere you like and set
the path to it in Aquarium's settings window


I'm sorry that there's no source code included in this distribution.
But I used several classes I compiled as link libraries and I don't
intend to distribute those. To enable you to recompile this source
the archive would contain about 500KByte data. And that would be much
too much for a screen saver module!

If you're really interested in the source or in any recompiled versions
for 680xx email me and I'll email you anything you like. (Hope your
account does accept mails above 100K!)


That's all.
To see it working just use "Exchange" to open Garshneblanker's
front-end, click on "settings" then on "save" and finally select
"Aquarium" from the menu via a left button double click.
I think the gadgets are quite self-explanatory.
If not, see the @{"parameters" link parameters } section of this guide.
@endnode

@node "parameters" "Aquarium.guide/Parameters"
@{u}@{FG shine}String gadget "Base path"@{FG text}@{uu}
        This is the path to the directory where the preferences file resides.
        The module will treat ALL filenames given in the settings window and
        in the prefsfile as relative to this base path
        default: The default string just points to my developer path

@{u}@{FG shine}String gadget "Prefsfile"@{FG text}@{uu}
        The name of the preferences file, relative to the above base path.
        Note: If you'd like to use different settings which should be
              randomly selected on startup just duplicate the files "Aquarium",
              "Aquarium.ifc" and "Aquarium.prefs" and name the new files e.g.
              "Aquarium2", "Aquarium2.ifc" and "Aquarium2.prefs". Garshneblanker
              will treat them as two different modules and you can specify in
              each module other preferences files.
              You can do this trick with any module.
        default: PrefsForTheAquarium

@{u}@{FG shine}Cycle gadget "Store messages"@{FG text}@{uu}
        yes -> Any error messages or warnings are stored to the file
               specified in the next string gadget.
               (It needs almost no time during showtime. Any errors that
               occur will most likely do so during startup.)
               This is especially helpful if a command of the prefsfile
               doesn't result in an animation displayed.
               The error messages are my internal ones, so they may seem a
               bit weird. But you can see if the file wasn't found, too less
               memory, and the message "Couldn't attach" xyz... often means
               that the display you've selected supports more or less colours
               than the animation you've tried to open.
        no  -> No error logging is done.
        default: yes

@{u}@{FG shine}String gadget "Msgsfile"@{FG text}@{uu}
        The name of the error message file, relative to the base path.
        default: MsgsOfAquarium
@endnode


@node "prefsfile" "Aquarium.guide/Syntax of the preferences file"
Here are the rules for writing own preferences files:

1.) The first line @{u}must always@{uu} contain the filename of a
    valid palette. To create one just use your most famous gfx-tool,
    edit the colours and save a palette.

2.) From here on you can use line comments to make the file more
    readable. Lines starting with a @{FG fill}#@{FG text} are treated
    as comments.

3.) Now you can specify as much commands as you like. Each command
    starts with the name of the object you want to create. Following
    are the object's parameters which vary from object to object.
    See the example file below for a summary of available objects


Following is a sample prefs file, accompanying this distribution:
--------------- snip here --------------------------------------------
Aquarium.palette
# The above first line of the file MUST ALWAYS be the filename of the
# palette which shall be used for the aquarium.
# (Any palette associated with the objects defined below is ignored.)
#
# All lines beginning with the character '#' are treated as comments
#
# All other lines should define one of the below objects
# The number of spaces between two words doesn't matter. Tabs and
# newlines are allowed, too.
#
# Currently there are three valid objects with the following syntax:
# ------------------------------------------------------------------
# BUBBLE <x> <y> <width> <height> <fullname>
#   ...which shows a bubble.
#   It's initial position will be at <x>,<y>. Then it's steadily moving
#   upward. In an aquarium you wouldn't normally create such an object
#   by yourself. The object GUPPY can be enabled to automatically
#   produce BUBBLEs from time to time.
#   Of course you could draw a balloon and let it rise with this kind
#   of object
#
# GUPPY  <width> <height> <basename>
#        <maxBubbleDelay> <bubblefile> <bubbleWidth> <bubbleHeight>
#   ...which shows a fish swimming around.
#   After some iterations it will produce a bubble which rises to the
#   top and then kills itself.
#   There must be four animation files present to be able to show the
#   fish. They must be named:
#    <basename>-l.iff    --> Shows the fish swimming to the left
#    <basename>-r.iff    --> Shows the fish swimming to the right
#    <basename>-tlr.iff  --> Fish's turning around (from left to right)
#    <basename>-trl.iff  --> Fish's turning around (from right to left)
#   The <bubblefile> must be the complete filename of the bubble's
#   animation.
#
# STILL  <x> <y> <width> <height> <fullname>
#   ...which shows the animation <fullname> at the given position.
#   Nothing will move here. (Of course you can draw an animation where
#   something moves. E.g. for a night sky you could draw two stars
#   encircling each other.
# ------------------------------------------------------------------
#
# A note on the object names:
# Don't limit your fantasies! Do NOT assume that a GUPPY _must_ be a fish.
# The above objects are only names for certain movement patterns. It
# doesn't matter what the actual animation looks like! You could easily
# let spaceships fly by loading them with a GUPPY onto the display.
# (The name "Aquarium" of this blanker was just better than "Showglass" or
# something else.)
#
# If YOU need some other movement patterns don't hesitate to contact me!
# I'll implement it!
#
#
#
# Now here comes an aquarium:

GUPPY   16 16 fish_guppy 200 bubble.iff 16 16
GUPPY   16 16 fish_guppy 100 bubble.iff 16 16

STILL   160 110 16 16 fish_guppy-r.iff

GUPPY   16 16 fish_guppy 50  bubble.iff 16 16
GUPPY   16 16 fish_guppy 25  bubble.iff 16 16
@endnode

@node "animation" "Aquarium.guide/How to draw your own animations"
The animation has to be a valid Amiga IFF picture file.

The images which you want to be loaded into the animation must be of the
same size, and they must be located one below the other, building a
vertical oriented image sequence. (Like a movie tape)

This rectangle must be surrounded by a frame, which has to be one point
thick. The images must be seperated by a line, one point thick, too.

To the right side of that image sequence you can draw anything you like.
(Perhaps you want to write some comments there.)
Note that the entire picture must not be taller than the image sequence
with its borders.

Here´s a little picture which clarifies things more than the paragraph
above ;-)

+----+----------------------------------------------
|    |  1. frame    the file must not be taller than this line
|    |
+----+
|    |  2. frame
|    |
+----+    <-- These lines help you to arrange the little images.
|    |
 ....      ...
|    |
+----+
|    |  last frame
|    |              the file must not be taller than this line
+----+--------------------------------------------------------------

To draw such animations easily I'll use a big image where I draw all my
animations. If I've a new one ready, I just mark it as a brush and save
that brush.

Be aware that the top border of the image strip must be the first line
of the brush.
Be aware that the bottom border of the image strip must be the last line
of the brush.
Be aware that the left border of the image strip must be the first column
of the brush.


To be able to load those strips correctly and detect some errors you have
to specify the width and height of the images with each object you're
defining in the preferences file. Note that these with and height parameters
refer to one image of the animation without any borders!

If you only want a picture and not an animation just enclose it with
a border of one pixel and load it as if it were an animation.

If there're any questions left, look at the animation files in the
distribution. (You can view them with "Visage" or load them into a gfx-tool)


A last word to colours and resolution:
Since all animations have to be displayed on the same screen they use the
same colours. I've decided to set the palette by loading an initial palette
(thefirst line of the prefsfile) which cannot be modified by objects.
Thus all images are displayed in the resolution you specified in the
settings window and use the colours loaded with the initial palette.
@endnode

@node "author" "Aquarium.guide/About the Author"
This module was written by: Ingo Schmiegel


snail mail to:
Noppiusstraße 6,
52062 Aachen
Germany

Tel.: +49-241-38421
(don't phone me at 2 o'clock a.m!!)

email: schmiegel@eecs.rwth-aachen.de
(Email is always preferred to other ways of communication
 - except you live next door ;-)
@endnode


@node "copyright" "Aquarium.guide/Copyright Information"

This module and all accompanying files are completely public domain!

Use it, play with it, make it a virus (but don't blame me!!),
do with it whatever you want.

If you detected an error or bug or you just have an idea for
improvement, please contact @{"me" link "author"} immediately!

If you like this module please send me an email.
(I would prefer a postcard with a nice stamp, but nowadays you can't
hope for much *sigh*)
@endnode

@node "disclaimer" "Aquarium.guide/Disclaimer"
This piece of software came to you with no warranty at all.

If your computer or you or anything or anyone else gets any damage
I am not to blame!!

(Don't like the legal stuff. But I'm sure you've got my meaning, hmm?)
@endnode


@node "history" "Aquarium.guide/History"

@{u}Version Date       Released Comments@{uu}
1.0     12-Sep-97  public  First aminet version with a fish, a bubble and a
                           still object
@endnode


@node "future" "Aquarium.guide/Future"

Any ideas ?
Send them to @{"me" link "author" }!

For those of you who have really read this document to its end,
I provide a special service ;-)
If you like this module very much, and would like to hear about
updates or other modules, write me an email. I will store your
email address in a list; and everytime I update this module or
I upload another module to the aminet I will send you an email
alarming you to download the new stuff from aminet.
I promise that I won't use the collected email addresses to send
you any other unwanted material. I won't send you the archives
directly per email, so you can choose yourself what you download.
Again a short email is enough to stop this service.
I won't give your address to others.
@endnode