                                Sprv and Msprv
                                ==============

Sprite Viewer and Multi Sprite Viewer are pjwitte 2oo4
ptrmen is part of EasyPtr II,  Albin Hessler 1991-1997

These programs and their associated files may be freely used, copied,
modified and distributed provided:

1) This is done non-commercially (ie, not for profit)
2) The authors are acknowledged
3) Improvements and bug fixes are passed back to me for possible inclusion
   in future versions
4) Users use this product at their own risk
5) These terms are not varied without my consent

ptrmen is integral to this suit of programs and my not be used for other
purposes without permission from its author.

I can be contacted at: pj@witte.fsbusiness.co.uk

Per Witte March 21st 2004


                                User instructions
                                =================

General
-------

System requirements: (Both programs are intended for all Wman2 systems, but
have only been tested on QPC2.) SMSQ/E 3.03+ or QDOS with PE 2.01+ (nearly
there, but not quite yet); QLib_run or better; ptrmen_cde (included with
distribution); QMenu by JMS (Msprv only).

To test, unzip the files into ram1_ and run from there, then no configuration
is necessary.

ptrmen must be loaded (LRESPRed) once to use either of these programs.
(See the boot file)


Note: Not all sprites are displayable in all colour modes. Where a sprite
cannot be displayed in the current mode a place-holder sprite is displayed
instead, eg GD2 or the mode sprite. However, the sprite information relates
to the undisplayable sprite, not the place-holder.


Sprv
====

Sprv is a simple utility to view a single plain or complex sprite. It was
cobbled together through trial and error during early experimentation with
the new sprite definitions rather than by design - and this shows. The program
is not complete and error checking is minimal. In fact, the compiled version
does not even report the errors it does discover; it just dies without a
squeak. Plenty of scope for improvement, then.

To invoke use

        EX <path>Sprv_obj; '<path>spritefile_spr'

where <path> is the device name and location of the object

or better still, add it to your FileInfo2 database, as this is how it was
"designed" to operate.

Once Sprv is up and running you can use the normal window controls Move and
Exit. You can also toggle the status of the displayed sprite by HITing it or
Unavailableing it by DOing the sprite. Sprites having different states will
display as expected (but no emulation of animated/dynamic sprites yet).

Click on the Info sprite to toggle between Display mode and Information mode

If multiple sprites are linked together in a complex sprite, each HIT on the
down-arrow sprite will display the next sprite in the chain. A DO resets the
display to the first sprite in the chain.

Click Wake to reset the selection status of the sprite to Available and to
re-display the current sprite in its default form.

The single digit refers to the palette number in use. Each click on the digit
increments the palette number (0..3,0..)

It is also possible to start Sprv up with a specified palette, just add a
' %' to the end of the file name followed by the palette number:

        EX <path>Sprv_obj; '<path>spritefile_spr %<pal>'

where <pal> is a single digit in the range 0..3


Msprv
=====

Mpsrv displays all the sprites found in a directory. Also here error checking
is rather minimal, so "unusual" situations (very large sprites or very many
sprites) will confuse or even crash the program.

Msprv uses a configuration file, Msprv_cfg. The location of this file must
be configured in the Msprv object file (use Config/MenuConfig for this).

The format of the configuration file, which is a plain text file, and which
must be configured by hand is:

mspv01                  - ID
ram1_spr_               - default sprite directory
ram1_spv_Sprv_obj       - location and name of sprite viewer program
Sprv                    - job name of sprite viewer program
0                       - default palette to start

As the program comes preconfigured to run from ram1_, if you unzip it there, no
configuration is necessary. Useful if you only want to try it out.


Standard window controls
------------------------

Window Move operation depends on you WM_MOVEMODE setting, ie click and move or
click and drag.

Window resize:

HIT and move to adjust window size. Once the size has been adjusted it will
remain fixed unless a large sprite forces a size increase.

DO to force Msprv to adjust the window to fit the current sprite layout. This
also releases the fixed size window restraint.

Quit:

HIT to exit program without ado.

DO to quit and kill off any Sprv programs currently displaying.


Commands
--------

Load:

Click Load to open the directory selector and select the directory to view.

HIT Load to use the last directory used.

DO Load to reset and use the configured directory.

Sprv:

HIT Sprv to Pick all instances of the sprite viewer program to the
top (A Wake event to the Msprv program has the same effect)

DO the Sprv item to kill off all instances of the sprite viewer program.

Pal:

Clicking the Pal item (the digit, not the name), cycles through the four
possible system palettes.


Application window
------------------

HITing one of the displayed sprites causes its name, size and origin to be
displayed in the top right information window. If the proper sprite cannot be
displayed the mode information is flagged with an asterix.

DOing a displayed sprite opens it in the sprite viewer program, if available.



Development notes for programmers
=================================

System requirements and environment as under General, above. In addition, for
best results, you will need QD (by JMS) with the SBAS F10 Thing loaded. To
fiddle with the assembler bits you will also need QMake (JMS). To compile
you'll need QLiberator.

The system key files are expected to reside on dev8_ as is now the convention.
These are also not included, but can be obtained free, from Wolfgang Lenerz.

Obviously, other setups are possible if you make the necessary modifications.

Note: EasyPtr is not required, apart form the included ptrmen_cde file. None of
the menus can be reloaded into EasyMen, so dont spoil your evening by trying!

If you have the recommended setup, and install the whole package in ram1_, you
can try everything out in situ without modification.

Have fun!

Per Witte March 6th 2004



Troubleshooting
===============
Mode 8 sprites dont display properly in mode 16 (Aurora). This is undetectable
by the place-holder mechanism (for some unknown reason).



The Future
==========

I dont intend to develop these program to full "production" quality - its just
too much trouble for too little reward!

However, there are a few things Id still like to do before packing in:

General
-------

Both programs will support display modes 4, 8 (at a pinch), 16 and 32/33. The
next versions are well advanced, but there is a limit on the time I have
available to complete them, so dont hold your breath!

Sprv
----

The next release version will see a considerable re-write, as I think I now
know how to do it! Better handling of undisplayable sprites and slightly
improved analysis of complex spites. Possibly: emulation of dynamic sprites.

Msprv
-----

Prefered size and position on startup. Possibly - just possibly - choice of
colour in display window separate from the palette.
