WATCH-IT - Picture Viewer for Atari ST/STE/TT/Falcon030     Version 1.0a
-----------------------------------------------------------------------------

Author : Stefan Bock
email  : sbock@informatik.uni-kl.de

All rights are reserved by the author.


1. What is it ?
----------------

WATCH-IT is a picture viewer for Atari ST/STE/TT/Falcon030 computers.
It was planned as a viewer for the new Falcon computer only, supporting
the 256-colour-resolution and the truecolour-resolution, but as it is a plain
GEM-program, you can also start it on the "old" Ataris as well.
WATCH-IT runs on all memory-configurations, but 512 KByte may be too small
for big pictures.  


2. How to start it 
-------------------

There are three ways to run the program:

  i) application : if you start WATCH-IT as an application, a file selector 
                   will appear. Choose a picture file here (at the moment,
                   only GIF is supported, others will follow soon).
                   Once the file is loaded, depacked and transformed into a
                   bitmap, it will be displayed in a window.
 ii) commandline : starting the program from a shell or from the desktop with
                   one or more filenames as arguments will load all specified
                   files as long as
                   - there are AES-windows left,
                   - there is enough memory left and
                   - the internal limit of 32 windows is not exceeded.
                   WATCH-IT uses ARGV for extended commandlines.
iii) accessory   : clicking on the menu entry will give you the file-selector
                   where you can choose a picture (see i) ).


3. How to operate it
---------------------

- You can move and size the window as usual and scroll the picture with the
  sliders if it is bigger than the window.
  If you move the mouse over the window and the picture can be scrolled, the
  arrow will change into a sort of cross-cursor which indicates the
  directions the picture can be scrolled to (play around with this, it's easy).
  Now press and hold the left mouse-button. The picture can be scrolled by
  moving the mouse until the left button is released again.

- Cursor keys scroll the picture, too, and SHIFT+<cursor key> scrolls a page
  at a time.

- A double-click on the picture or pressing <CONTROL>-I or <TAB> gives you
  an information-window:
  Here you find the width, height and palette size of the picture, the time
  it took WATCH-IT to process the picture (including loading-time) and the
  amount of RAM it uses.
  Note that WATCH-IT uses some bufferspace during depacking and dithering,
  so this displayed amount is smaller than the memory you need to process
  the picture.
  You will also find four buttons labeled "Greyscale", "Colour", "No dither"
  and "FS-Dither". These are not selectable in this release, sorry, but
  definitely will be in the next version, so you can choose your favourite
  display-mode here. At the moment, a default mode is choosen depending on
  the resolution (see below).
                
- Pressing HELP reveals a help window.
  Click on "OK" or press <RETURN> to close this window.

- Click on "LOAD" in the info/help-window or press <CONTROL>-O to load 
  another picture. In accessory-mode clicking on the menu-entry has the same
  effect.

- Press <CONTROL>-W to cycle through all open windows.

- Press <CONTROL>-U to close the actual window or
        <CONTROL>-Q to close all windows (when the program has been started
                                          as an application, this means "Quit") 


4. The picture format(s)
------------------------

At the moment this is only GIF format, but others will follow.
If you have suggestions about what formats should be supported, please contact
the author (format descriptions are welcome, too).

GIF-formats 87a and 89a can be loaded, even though WATCH-IT only inter-
pretes the main picture data. I never came across a GIF-file with more
than one picture in it, but if you have such pictures which you cannot
display properly with WATCH-IT, tell me, perhaps i can change it.

      "The Graphics Interchange Format(c) is the Copyright property of
      CompuServe Incorporated. GIF(sm) is a Service Mark property of
      CompuServe Incorporated."


5. The display modes
---------------------

As mentioned earlier, WATCH-IT was written for the "Falcon resolutions",
and pictures will definitely look best in these resolutions. Nevertheless
I included dither-algorithms for monochrome and 16-colour-modes, too.
Some more dither algorithms and greyscale modes are already finished, but
didn't make it into this first release version, sorry.
Note that pictures have to be processed in device-independant format and
then transformed into the device-dependant format, this will take a little
bit more time than writing the data directly into screen-memory, but is
unavoidable in a GEM-program. On the other hand WATCH-IT will (at least it
should :-)) run on all resolutions. If WATCH-IT does not run on your graphic-
card, please let me know.

  i) Truecolour-mode:
     This mode has only been tested on the Falcons truecolour-mode. It should
     run on all resolutions with a device-independant format containing 16
     planes, but i have no information about how RGB-values are coded on
     other graphic-cards (they _should_ do it like the falcon, otherwise
     the format would not be very device-independant, huh ?).
     You can have multiple pictures at the same time each one having its
     correct palette.
     Hey, this is so great, if you don't have a FALCON, get one :-) !

 ii) 256-colour-mode:
     This mode is used on resolutions with 8 planes, e.g. Falcon or TT-LOW.
     The picture will be displayed without dithering.
     Anyway, WATCH-IT never uses VDI-colours 0 to 15, since these colours
     should be fixed for all applications. Instead, WATCH-IT shuffles around
     the colours and substitutes similiar ones so that the VDI-colours don't
     have to be used. 
     Note that the palette can only be correct for the topped window, other
     pictures may look quite strange. Simply top the window you wish to look at
     and the correct palette is used.
     By the way, pictures look a little bit like "widescreen" cinema on
     TT-LOW. The reason is the strange pixel ratio on this resolution
     (320 x 480). This may be fixed in future releases. 

iii) 16-colour-mode:
     This mode is used on resolutions with 4 planes, e.g. TT-MID or ST-LOW.
     It is the most time-consuming mode, since reducing 256 colours to 16
     colours is not that easy. A special dither-algorithm is used (3 Floyd-
     Steinberg-passes) so that all pictures can use the same palette, that
     means you can have multiple windows which all look correct at the same
     time). 
     Pictures look best when viewed from some distance from the screen.
     There are other possibilities to reduce the colours. An often used method
     is to choose the 16 most used colours. This is definitely faster than
     dithering, but in my opinion often has too poor results.
     If you know better methods, please tell me !
     Anyway, a 16 greyscale-mode will be included in future releases.

 iv) Monochrome-mode:
     If none of the above modes can be used (e.g. on ST-HIGH, ST-MID or 
     TT-HIGH), WATCH-IT will switch to monochrome-mode. 
     The picture is dithered with Floyd-Steinberg error diffusion and 
     displayed in VDI-colours 0 and 1. This normally means black and white,
     but of course you can change this with the control panel (feel like 
     Andy Warhol!) .
       
  
6. WATCH-IT and MultiTos 
-------------------------

WATCH-IT runs under MultiTos, even though it can't handle it's own windows
during depacking and dithering. This is so because depacker and plotter
are written in highly optimized assembler and calling aes-functions
during depack would slow down the whole thing significantly.
However other applications can run during WATCH-IT does its work.

I consider writing a special MultiTos version which forks the depacker
and ditherer so that they can run in the background while WATCH-IT-windows
can still be moved.
Any ideas about this (except from integrating the depacker into the
event-loop which i definitely won't do !) are welcome !

Under MultiTos, no busy-bee is shown as this would be senseless in a
multitasking environment.

The help and info-dialog are shown in windows, so dialog-boxes won't block
the system.


7. Error messages
------------------

Out of AES-windows      : Close some windows and try again or get MultiTos
Max. 32 windows allowed : This is the current limit.
Read error in header,
     palette or image   : The picture file is corrupted, you can try to
                          load it anyway (press "Yes" in the "proceed ?" -
                          alertbox), but the picture may look strange.


8. Disclaimer
--------------

I really don't know how this program could harm you or your computer, but:

The author makes no warranties of quality or performance for this program.
Use it at your own risk !


9. Feedback
------------

If you
- have found bugs,
- don't like the user interface,
- can't get the program to work at all,
- have good ideas how to improve this program,
- or just want to say a few words concerning this program,

contact me via email:  sbock@informatik.uni-kl.de
                       (this address will only be valid until end of
                        september 1992)
or in IRC (nickname : Robo).





Enjoy !
