*

   This file describes `Mostra' 1.09, a shareware IFF utility featuring
real-time unpacking scroll, dozens of options, "smart" analysis of any
IFF file (FORMs, LISTs,...  also nested ILBM!), total control over
display modes, simple slideshow processing, pattern matching,
multipalette, double buffering, fast decompression, color cycling,
TeXdocs, startup files for easy custom configurations and complete WB
support.


Introduction
*************

   `Mostra' is an IFF ILBM viewer that can process *any* IFF ILBM file;
this means not only IFF ILBM FORMs, but also nested ILBM, FTXT, FORMs,
CATs, LISTs and PROPs. It has become reknown in the Amiga community for
both its robustness and its flexibility.

   Any design requires tradeoffs: `Mostra' tries to give you a good
balance of program size (less than 15K), speed (optimized assembler
decompression routines) and features. It tries to be enough smart to
have always reasonable defaults, but also lets you force any aspect of
the display, such as resolution and video flags. While it is not
possible to foresee every possible race condition, `Mostra' should be
able to cope with any reasonable ILBM file.

   `Mostra' currently relies on ARP v39 in order to work. Thus, the
`arp.library' file has to be in your `libs:' directory if you want to
run `Mostra'. Otherwise, a message will be displayed, and `Mostra' will
refuse to run. (Without ARP's powerful functions, `Mostra' would have
never been released.) However, `Mostra' 2.0 will work only under
Release 2 and will not need ARP.

   One of the major features in this release is support for
multi-palette pictures, i.e., pictures with the new PCHG chunk which
should substitute the old CTBL and SHAM chunks. See the `Changes.doc'
file for additional informations. SHAM is still supported, but the
support of CTBL pictures via external call has been dropped since it
was shown to be unreliable.

   The other major improvement is complete support for the AGA chip set.


Syntax
*******

`Mostra' can be called both from the CLI and from the Workbench. It is
also a pure program, i.e., it can be made resident.


Command Line Usage
===================

   To get the command line syntax in AmigaDOS style, type:
     M ?

This will produce the input template:
     Files/...,A=All/S,R=Repeat/S,Q=Quiet/S,NoFastDraw/S,
     C=Center/S,B=BlackBackground/S,W=Width/K,H=Height/K,Cycle/S,
     Secs/K,Fade/K,NO=NoStartup/S,Batch/K,LockPic/S,
     N=NoMouse/S,F=FreeMouse/S,LockKeys/S,NA=NoActivate/S,DB=DoubleBuffering/S,
     Hires/S,Lace/S,Lores/S,NoLace/S,HAM/S,Halfbrite/S

If you ask for more help by typing `?' again, you will see:
     Mostra 1.09 (C) 1990,1991,1992 Sebastiano Vigna
     Usage: M <wildcards [...] | !> [All] [Repeat] [Quiet] [NoFastDraw]
     [Center] [BlackBackground] [Width n] [Height n] [Cycle]
     [Secs time] [Fade speed] [NoStartup] [Batch file] [LockPic]
     [NoMouse] [FreeMouse] [LockKeys] [NoActivate] [DoubleBuffering]
     [Hires | Lores] [Lace | NoLace] [HAM | Halfbrite]

The same help is displayed if you call `Mostra' with no arguments.

   `Mostra''s first argument is a list of patterns (or file names) as
long as you want; you will get every picture whose name matches one of
the patterns.

   Alternatively, you can type only the `!' character, and `Mostra'
will display the ARP file requester, allowing you to search for the
picture you want to show.


Workbench Usage
================

   When `Mostra' is called from Workbench without any argument icon, it
will pop the file requester and will allow you to select pictures to
show until you select `Cancel' or close the file requester window.
Alternatively, you can SHIFT-select multiple icons together with
`Mostra''s one, or you can change the default tool of your pictures.
For details about this, see Startup Tool Types. Note that if you select
an IFF CAT or LIST you will have an automatic little slideshow.


Keyboard Usage
===============

   Once you are looking at the picture you selected, you can exit by
moving the mouse pointer to the very top of the screen and pressing the
right button (you can also press the RETURN, SPACE or ESCAPE keys). You
can drag or depth arrange the screen with the left mouse button (the
gadget(s) are invisible, but they really are there!). TAB will toggle
on/off color cycling. To stop pattern matching or IFF scanning use
`CTRL-C' at any moment.

   If the screen size is less than the size of the picture, you can
move around with cursor keys alone (moving by 8 pixels) or in
combination with the SHIFT (a screenful minus 16 pixels), ALT (which
brings you to the borders), or CTRL (16 pixels) keys. A noteworthy
feature of `Mostra' is that the picture is *not* decrunched all at one
time in a very large chunk of memory; instead, a fast LM routine
decrunches the file in real-time every time you move (the routine could
be faster, but it has lots of controls to get rid of damaged IFF BODY
chunks; safety always first). This is not as fast as the memory-eating
method, but I think it's *much* better. Very large pictures (like
800x900) will be shown in a full screen (generated on the fly at
Workbench size) which you can move around. Overscan pictures will
retain their size of it's not greater than 362x283 lo-res pixels
(362x241 on a NTSC Amiga). For hi-res pictures, there is also a 704
pixel width limit due to Intuition (724 under Release 2). Small brushes
will be shown in a minimum 256x128 pixel screen. Of course, moving
vertically with multi-palette pictures involves a high system overhead,
since Copper lists are continuously built and deleted.

   A weird effect of this method is that you can see pictures that
can't even be *loaded* into your Amiga. Let's suppose you have a really
crunched picture; the BODY chunk and a 256x256 lo-res screen could take
much less space than the decrunched picture, so you could create
pictures that only `Mostra' could let you see in all of their parts.
Why you would want to do this, well, that's another matter.


Options
========

   This list describes all the options available in `Mostra'. The
letters between parentheses denote availability of a shortening.
Options can be put anywhere on the command line, or in Tool Types (see
Startup Tool Types).

`All (A)'
     forces a recursive scan of all of the subdirectories during the
     wildcard search.

`Repeat (R)'
     will endlessly restart from the first pattern when it has finished
     with the last; if you used the `!' line arguments, the file
     requester will pop up after every picture until you `Cancel' or
     close.

`Quiet (Q)'
     turns off all messages except in case of error.

`NoFastDraw'
     leaves the program at priority 0; by default, `Mostra' will
     surround the BODY decrunching operations with a `SetTaskPri(1)'.
     This will not lock the system, but in a multitasking situation
     `Mostra' will perform quickly when needed.

`Center (C)'
     will force the screen to be centered (640x200 pictures on PAL
     screens look so ugly...) and will use overscan if necessary. Note
     that if you move the screen, and you are not under Release 2, the
     centering will go away.

`BlackBackground (B)'
     will create a 0-bitplane black screen that will stay until you saw
     the last picture. This is for aesthetic purposes only (note that
     no Chip memory will be used).

`Width (W)'
`Height (H)'
     want an argument that specifies a dimension of the viewing screen.
     However, `Mostra' is an intelligent program, and will almost always
     find the correct screen by itself. *Warning*:  dimensions allowed
     are from 64 to 1024, at your own risk. Your Amiga won't crash, but
     weird things can happen...

`Cycle'
     will automatically activate color cycling on every picture.
     Usually this happens only by request, through TAB.

`Secs'
     must be followed by a number between 0 and 1000 (the zero delay
     was a request from a BIXen). `Mostra' will display each picture
     for the number of seconds specified, but you can skip using the
     mouse or the keyboard as usual (see Keyboard Usage) or stop the
     show with `CTRL-C'. Cursor keys are disabled. Greatly reworked on
     Warren's request.

`Fade'
     lets you specify a speed for pictures to fade in and out. Valid
     numbers are 1 to 4, with four the slowest. Note that HAM pictures
     can't be faded.

`NoMouse (N)'
     will hide the mouse pointer while `Mostra' is displaying a picture.

`FreeMouse (F)'
     will let you pass from one picture to another by clicking either
     of the mouse buttons at any position on the screen.

`LockKeys'
     will discard any input from the keyboard during the display. You
     must use the mouse to pass to the following picture. Note that if
     `FreeMouse' is not activated, the only way to go is clicking the
     right mouse button while the mouse pointer is at the top of the
     screen.

`LockPic'
     will lock the picture displayed. You won't be able to scroll
     around, but the memory in which the file is loaded will be
     immediately freed after the decompression, thus minimizing the
     memory usage.

`NoActivate (NA)'
     will inhibit the activation of the picture screens, so you can
     keep on typing on your current screen. This was a request from Tom.

`DoubleBuffering (DB)'
     sets a double buffering show mode:  while a new picture is being
     loaded you will see the old one, no Workbench pop-up or black
     screens. It eats lots of memory, too. Again, a request from Tom.
     (Note:  it's canceled if you call the file requester.)

`Hires'
`Lores'
`Lace'
`NoLace'
`HAM'
`HalfBrite'
     force all screens to be in the respective mode (note that if
     `Mostra' finds a six bitplane picture with no CAMG chunk, it won't
     set the `HAM' flag by default). These flags are dumb, that is,
     they will do exactly what you say, even if it is meaningless.
     However, if you use both `HalfBrite' and `HAM' together, only the
     former will take place.

   The `NoStartup' and `Batch' options will be discussed later, in
Startup Files.


Examples
=========

   And now, some examples:

     M MyPics:* Secs 5 Fade 1 NoMouse BlackBackground Repeat Center All

will generate a slide show of the pictures in the `MyPics:' directory
and in all its subdirectories, centered and with no mouse pointer
hanging around. In order to stop the slide show, you must press
`CTRL-C'.

     M df0:*.image df0:pictures/*.pic Hires Lace

will show the files ending with `.image' in the directory `df0:' and
the files ending with `.pic' in the directory `df0:pictures'. `Mostra'
will be forced to use high resolution, interlaced screens. Setting the
`Hires' flag on pictures with more than 4 bitplanes usually leads you
to see absolutely nothing.

     M dh0:hirespic Lores NoLace

will show a hi-res picture in lo-res ("zooming in"). You can move
around with the cursor keys as described above.

   `Width' and `Height' can be useful when you have a picture that
cannot be displayed because there's not enough Chip RAM (you get the
`Can't open Screen' error message). In such a case, try:

     M pic Width 128 Height 128

This will usually allow you to at least get a peek at something.


Advanced Features
******************

   For maximum flexibility, `Mostra' allows you to use "startup files"
and "startup Tool Types", with which you can configure the program to
suit your tastes.


Startup Files
==============

   There is a standard startup file, called `S:Startup-Mostra'.
`Mostra' will search for it when run from the CLI. The format of this
file is *exactly* the same as the `Mostra''s line format minus the
command name. Commands may be spread out over several lines or gathered
together onto a single line. Every switch or keyword in the startup file
will act as a default, and will be toggled or superseded by any command
line arguments. Command line switches will act as toggles (if your
startup file has the keyword `All' and you say `M * All', you *won't* go
into subdirectories), while keywords simply assert the new value (if you
have `Fade 1' in your startup file and you say `Fade 3' in the command
line, your pictures will be faded at speed 3).

   Two options concern startup files:

`NoStartup (NO)'
     inhibits the search for startup files, useful if you have one and
     you want to specify your options from scratch.

`Batch'
     wants a complete path/filename that `Mostra' will use as startup
     file.


Startup Tool Types
===================

   From the Workbench side, you can write the startup options in the
Tool Types of `Mostra''s icon, and it will use them. The format is the
same of `Startup-Mostra'. Please note that `Fade=1', `Width=352' are
valid, but `FreeMouse=ON' is not; use only `FreeMouse'.

   Or you can set the first Tool Type of a project icon to `STARTUP' and
put your options in the following lines; the project picture file will
be shown with those options when you double-click its icon. You can do
the same thing with an icon that has no related file, and put some
wildcards in the Tool Type. The wildcards will then be shown with those
options. If you don't put in wildcards, you get a "style" icon;  you can
SHIFT-click some icons, `SHIFT'-click the "style" icon (in *this*
order) and then SHIFT-double-click `Mostra''s icon (or directly
SHIFT-double-click the last icon, if its default tool is `Mostra'): 
you will see the selected picture files with the options specified in
the style icon. The style icon by itself will pop up the file
requester. Please note that even an icon with wildcards can be used as a
style icon because multiple selections supersede wildcards.

   I know, it seems a little twisted, but using it you'll find,
instead, that it's the way you'd think.

   *Warning*:  strange interactions can take place. If you have some
picture icons, and you SHIFT-click all but one of them and then you
SHIFT-double-click the last one *and* the last picture icon you clicked
had some `STARTUP' options, you will see *all* of the pictures with
those options. Right?

   For curious/tech/interested people, here is the exact algorithm:

  1. If `sm_NumArgs>1' (the user started `Mostra' with al least an icon
     argument), check if `sm_ArgList[1]' (the first real argument) has
     Tool Types with first Tool Type `STARTUP'. If so, scan the whole
     Tool Types list like a command line, accepting mixed commands on a
     single Tool Type as well as separated commands in separated Tool
     Types.

  2. If the first step goes wrong, check the `Mostra' icon Tool Types,
     and take them as a command line. (Note:  `STARTUP' is not
     requested.)

  3. Now, if `sm_NumArgs>1', check every `sm_ArgList[i]' with `i>0' and
     if there is a related file (*not* a `.info' file!) generate a list
     of arguments as if the user entered them manually, *superseding*
     eventual filenames/wildcards found in the previous steps.


Startup Examples
=================

   Now, examples, by means of common problems:

   * "I have a hundred pictures on my 360M hard disk, and I've organized
     them in a few groups. How can I make simple slideshows, with each
     group separate?"

     Simple: create a project icon for each group, and add a Tool Type
     `STARTUP'. Then add a Tool Type like `PICS:Group1/* All Secs 5
     Center' to choose your options, set the default tool to `C:M' (or
     wherever you put it) and double-click (of course, this must be
     done with every group icon). Don't give the icons the same name as
     a directory, or `Mostra' will collapse in confusion.

   * "I want to always see the black screen when I start from WB."

     Set a `Mostra' Tool Type to `BlackBackground'.

   * "I have some pictures. Sometimes I want to see a few of them with a
     full screen and no mouse, sometimes with a 128x128 screen,
     sometimes centered."

     Create three "style" icons. Each icon must have as its first Tool
     Type `STARTUP', and the following ones must be something like
     `NoMouse', `Width 128 Height 128' and `Center'. The default tool
     must be `C:M'. When you want to see in a certain style,
     `SHIFT'-click the picture icons and *then* `SHIFT'-double-click
     the style icon you desire.

   * "I like to click my pics one at a time, each one with different
     options. I'd like also to see them in irregular groups, each
     picture with its options."

     You need a psycho-analyst, not `Mostra'.


Acknowledgments
****************

   I wish to thank some people, first of all the ARP team for the
arp.library and the SAS team for the best Amiga C compiler. Speed and
compactness of `Mostra' come from the fabulous 5.10b release. Also I
would like to thank the people that encouraged me someway or helped me
to find bugs, in particular Steve Tibbett, Warren Block, Tom Rokicki,
Christopher A. Wichura and Loren Wilton.

   If you're reading this, you probably have access to a TeX system.
Anyway, if you spent a good part of your time preparing and printing
documents, I'd suggest you to take a look at AmigaTeX, a wonderful
package from Radical Eye Software which is probably the best
implementation of TeX you can find on any computer.

   `Mostra' is (C) 1990,1991,1992 Sebastiano Vigna and it's not public
domain: it is shareware. You should send me $20 (or more, why not?) if
you find it useful. Please don't send checks drawn on a US bank, they're
almost impossible to cash. I'd prefer postal money orders, currency or
checks drawn on an italian bank (in this order). `Mostra'  is freely
distributable as long as all of its files are included in their original
form without additions, deletions, or modifications of any kind, and
only a nominal fee is charged for its distribution. This software is
provided "AS IS" without warranty of any kind, either expressed or
implied. By using `Mostra', you agree to accept the entire risk as to
the quality and performance of the program.

   Comments, complaints, desiderata are welcome.


Author Info
************

         Sebastiano Vigna
         Via California 22
         I-20144 Milano MI
     
         BIX: svigna
         INTERNET: vigna@imiucca.csi.unimi.it
                   vigna@ghost.sm.dsi.unimi.it
         UUCP:cbmehq!cbmita!sebamiga!seba@cbmvax.cbm.commodore.com
              ...{uunet|pyramid|rutgers}!cbmvax!cbmehq!cbmita!sebamiga!seba
         FIDO: 2:332/607.28