WHAT IS IT
----------

Photon is a image viewer that will work in any mode on any QL compatible
(PE or not). Presently it only supports decoding JPEG image (photographs),
but will also at least support PIC files (any mode in any mode) and GIF
images (including animated) in the near future. Other formats (less
frequently found) may be added in due course, as will other bells and
whistles.

Athough it is only intended to be a small (resident) utility without a
pretty menu interface, it is possible that the code can be easily adapted
to make a much larger graphics program (ie, the scale, dither and decoding
parts are separate and can be made utility Things).

Modes supported are standard QL mode 4 or 8, QXL/QPC mode 32 and Q40 mode 33
(65536 colour modes). It should also recognise the new Aurora driver for
mode 16 (256 colour mode) when it appears. I'm not sure about the Aurora
16 colour mode since the documentation I have seen about the colour drivers
suggests that MT.DMODE will return mode 8 (!) if it is implemented, even
though it is a different pixel format!. Support for 24 bit colour on
QPC/QXL will be trivial to add (in fact the easiest and quickest).

In the meantime it is possible to view images in Aurora's 256 and 16 colour
modes by the use of a 'protected mode'. During this mode you can only switch
to another job by quiting the image, whereby the display will be restored/
maintained as normal. In fact this may be a preferable way to view colour
images on the Aurora since the new colour drivers appear only to allow a
one-way transition to the new mode. On the Aurora this means the max display
size will be no more than 512x480 (eg, no going back to higher resolution
mode 4/8 display without a reset).

The present version is a working but far from complete final program, with
a bit of fine tuning yet to be done. Aurora 256 colour dither is accurate
but very slow, might be able to find quicker way. The problem is finding
the nearest colour based on the awkward way bit 0 of Red and Blue are
combined (to be fair though gives most distinct colours). At the moment it
calculates the nearest from the smallest sum of squares of the differences
from the valid colours. Like JPEG decode this makes extensive use of the MULU
instruction which on anything less than a 68060 is slow (even at equivalent
clock rates). To find a quicker way means looking for shortcuts to MULU,
which in itself takes time and the time saved in each situation depends on
the image data.

Dither for Q40 mode not yet done, next version.


HOW TO USE IT
-------------

Photon can be invoked by;

  EXEC Photon;'command string'

or made a resident executable Thing by;

  LRESPR Photon

in which case invoke with the EXEP command, QPAC Exec or Fileinfo 2.

Where command string is;

  'filename\flags'

The filename is delimited by either the end of string (ie, no flags) or by
the first \ character. This allows spaces to be used in filenames. The data
default directory is tried if filename is not found.

Where flags are (in any order, always preceded by \ );

\a           (or \a1) produce image in Aurora 256 colour mode
             \a0 for image in Aurora 16 colour mode

\b           when job starts put gauge in QPAC button frame

\d0 to \d4   dither image 0%, 25%, 50%, 75% or 100%
             not specifying \d uses default for mode

\m4 or \m8   produce image in mode 4 or 8 (ignored if in hi-colour mode)
             else image in mode of that when job started

\r           don't scale image to aspect ratio of display

\w           once image displayed make wallpaper and quit

\y           (or \y1) produce black and white image from colour image
             \y0 produce mode 4/8 using monochrome colour levels


Example: to view JPEG file in Aurora 256 colours, 25% dither, no scaling with
gauge in button frame;

EX Photon;'myphoto_jpg\d1\r\a\b'


IN USE
------

The job will start as a button (small window) just big enough to contain
program name and shortened filename. If the \b option has not been given
then it will be centered in the screen. As the decoding process proceeds the
button will show a gauge of progress. During this time you can switch to
another job and it will continue decoding. If you wish to abort,  switch to
job and press ESCape (it will respond as soon as it has finished the last
chunk).

Once it has finished decoding it will take one of two actions: If it has the
keyboard queue it will immediately show the image, if not it will flash the
button to get your attention (of course if the button is buried you won't see
it until it is at least visible). A flashing button will wait until it gets a
key press before showing the image (ESCape will abort).

Since we don't have a 'type-ahead' mouse pointer like the keyboard I cannot
show pointer whilst decoding the image (requesting pointer input for 0 timeout
is silly, unlike keyboard). But a later version will request pointer input on
a flashing button.

The decoded image will be displayed by using the whole screen (perhaps later
version will only use required size). If width or height is less than screen
then it will be centred, otherwise the top left hand of the image wil be shown.

Using different or no dithering can vastly improve some images. The defaults,
only be arrived at by testing a few images, are: mode 4 & 8 50%, Aurora 16
colour 75%, Aurora (mode 16) 256 colour 100%. It is possible to offer 12.5%
increments in dithering at the cost of a tiny overhead.


Keys;

ESC, SPACE   quits job (for Aurora protected mode the task swap key,
or ENTER     usually CTRL C, will have same effect)

W            if system supports it, make Wallpaper and quit.

F4           redraw image (useful only for non-PE)

           scroll image up/down by one line

           pan image left/right by number of pixels in a long word
             (to be changed soon)


 with

ALT          x 8 movement

SHIFT        by screen width/height

ALT+SHIFT    to image extremes


TO COME
-------

Pic saving & loading, including just screen or defined area.

QMenu and Scrap support

Zoom/Reduce/Fit to screen

Pan by pixel (slower since requires shift/rotates)

Error report in button (for now use EW to find error)


BORING STUFF
------------

Freeware, distribution by cost of disk & post only. I retain copyright.

Suggestions/criticisms/bugs etc to 

Dave.Westbury@btinternet.com


VERSIONS  (dd/mm/yy)
--------

The version number can always be found as ASCII characters in bytes 3 to 6
of the executable file.

0.10      19/04/00    first primitive version
0.11      23/04/00    added \w
0.12      30/04/00    added mode 32 for QXL/QPC
0.13      25/11/00    faster/smaller IDCT
