                           The V11 JFIF viewer
                          for the Atari Falcon

                    030-only version 2.14, 7/11/93.

        By David R. Oldcorn of Volume 11 Software Development
   All Falcon-specific parts (c) 1993 Volume 11 Software/DR Oldcorn.
      Based on the JFIF C conversion software originally by the
                      Independent JPEG Group.

       DSP56001 code and interface written 23/7/93 - 28/7/93
                          (not included)

 GIF and Graphics Interchange Format are trademarks of Compuserve, Inc.




Usage:

About the easiest setup is to set it on a function key and as a
JPG extension triggered system, so double-clicking a JPG file will
show it onscreen, and an F-key will bring up the viewer.

Once it is running the controls are as follows:

File selection screen:
A-Z:       select drive to be displayed.
Cursors:   move file cursor
RETURN:    show file / enter subdirectory
BACKSPACE: exit subdirectory
*:         show info on current file
Esc:       exit to desktop
Space:     mark file for slideshow
Tab:       start slideshow (show all if no files selected)
Insert:    switch to preferences screen
Help:      show keylist & program info


In display mode:
Cursors:   move screen
Esc:       exit now
Return:    exit / next slideshow file
Space:     halfsize picture
Backspace: switch interlaced frame alternacy (not enormously useful)


On preferences screen:
Cursors:  move cursor / alter contrast settings
Space:    change status
Shift+Curs: +- 10 to contrast settings
Return/Esc/Insert: exit


This 030 version is entirely public domain, and you are free to distribute
it as much as you like AS LONG AS it and this file are NOT ALTERED in
ANY way, and that it is always accompanied by this file.

The full DSP version of this software is available for 5 from:
             Volume 11 Software Development,
             PO Box 311,
             Broughton
             Preston
             PR3 5DZ
             (England)

All monies should be made payable to D. Oldcorn.

Note that the DSP version is not at all public domain in any way, shape
or form and may not be copied for distribution.

I can be contacted until at least August 1994 on email at:
oldcornd@cs.man.ac.uk

All feedback, suggestions and comments welcome.




GENERAL NOTES

All pictures are displayed in standard Falcon 16-bit Truecolour.
Although, to tell the truth, 1 part in 64 of green really makes
very little difference. Even the ST formats (Degas etc.) are run in TC
mode, so all the halfsize features still work.

Working memory is 2x size of the loaded file + about 50K + size of the
selected image buffer.
       For 384x240, this will be around 0.5 Meg
       For 768x480, this will be around 1.5 Megs.
For VERY large pictures operating in hardware scroll mode can require
around 2.5-3 Megs (think about it... that's a 1.9 Meg display area,
plus the fact that the data is likely to be a bit on the big side....)
It won't work with less than 4 megs except on very small pictures.
GIF conversions may require MORE memory than JFIF's due to the
larger files. They usually take longer, too.
If you get an 'out of memory' error, set a lower res video mode and
turn hardware scroll off and/or set halfsize on - this will
limit the screen size by not allocating memory for areas outside
the left and right of the visible screen area (it WILL still allocate
for VERTICAL scroll but if halfsize is on this is unlikely to be
necessary).

It has displayed JPEGs as big as 640x2500 and 1700x1700 (halfsized).

In slideshow mode, remember it has to hold TWO pictures in memory at
once... so you won't be able to show big pictures one after
another without running out of memory. That said, if you're running
it in a clear Falcon with just the Control Panel installed, you
should have about 3.8 megs free, so the pics will have to be pretty
huge to cause problems (I've found that two 1024x768's is about
big enough to do it).

Due to a slightly unhinged design flaw in the Falcon video XBIOS
(which was always present on the ST too, but because direct hardware
accesses were OK you could get round it) the screen resolution can't
be changed without clearing the screen (to white, of all things) which
1) leads to the flicker when an image starts loading, 2) leads to
flickering and unusual output when the slideshow swaps an image,
especially if it has to change resolutions.
(I think this actually goes against Atari's own Falcon specifications
which says 'Vsetmode does not initialise the VDI etc.')

VGA mode is limited to 320x240 because the Falcon doesn't support
640-wide screen modes in VGA Truecolour. The hardware scroll and
halfsize should still be OK so you WILL be able to see a full picture.
All VGA modes are currently untested, because I don't have a VGA monitor!

Full PAL height uses direct access to the video hardware to remove the
top and bottom borders produced when using overscan on a PAL (50Hz)
TV or monitor.
If when you select this mode your monitor does ANYTHING strange
(minor distortion on the top couple of lines is OK) like not syncing
properly (a rolling screen), then don't use it (most likely you will
have some, as yet unknown, future version of the Falcon video system).
This produces the maximum 600 data lines, although you'll probably need
a vertical resize to see the top 30 and bottom 10 of these.

The STe hardware scroll registers are also used for pictures which
are wider than the screen. These should be valid on all Falcons, but
an option is given to disable horizontal scrolling, in which case the
hardware register will not be accessed. If hardware scrolling is active,
out of memory messages will not appear correctly due to the operating
system not having been configured for the hardware register control.

Another hardware access is made, to set the border colour (if
visible) to black

All of these accesses can be disabled with an option, which will prevent
any possibility of any illegal hardware access.

It pings when it's finished loading whatever it's loading, and usually
when it runs out of memory.

Using it under MultiTOS is a Real Bad Idea but it is quite legal in memory
usage and management. Running this under MultiTOS would be like
putting the Williams Renault engine in a Robin Reliant - completely
pointless. (As far as I can tell, the incompatibility is caused by
changing screen res + direct screen access: although this program
could manage without res changes, if it used the VDI it'd take weeks...
currently plotting one pixel takes 9 instructions in YCrCb...)
(P.S. The reason it doesn't work is it kills the AES process which is
invariably very very fatal).

Error messages will not be printed unless using 'info' on a file.



GENERAL NOTES ON JFIF CONVERTER.

Current version implements a subset of JFIF.
BUT most standard JFIF's will certainly be supported, if they
have been compacted using a range of standard parameters.

It will only handle images in YCrCb and greyscale (the only two
colourspaces for general use).
Noninterleaved scans are not supported. (These are currently rare).
A couple of VERY strange sampling ratios may produce unusual output:
anything mixing 3's and 2's or 4's and 3's may do it...
3x1 2x1 1x1, 1x4 1x3 1x1... something like that (anything which
produces non-integral upsampling ratios).

This should include the vast majority of JFIF files.
(This covers ALL the JPEGs I have encountered, and all those which can be
created using the Independent JPEG group's CJPEG software).

It is recommended that ALL stored JPEGS should be 2x2 1x1 1x1 (as
recommended in the JFIF standard), other ratios will produce
insignificant improvements whilst increasing the size of the file!

Error checking is performed to a limited extent, but faulty files will
(most likely) halt the decompacter or produce horrible data. Resyncing
is NOT guaranteed even if restart markers are included, but in most
cases some kind of resync should be possible. It won't necessarily be
in the right place for the output stages!

Halfsize reduction is performed by a supersampled zoom at the
upsampling stage (only approximately if you are using non-1x1/2x2
ratios, but this should be fairly rare).


NOTES ON DSP CODE:

The DSP version is slightly more limited than the plain vanilla
030 version, due to the limited memory available to the DSP and the
logistics involved in programming a fast, efficient DSP version. As
a result, some JPEGs will have be processed by the 030 entropy decode
rather than the DSP, which will be slower. Notably, anything with
restart markers will have to be done on the 030, and anything with
silly sampling ratios (CrCb ratios must be 1x1 1x1 to be OK, and Y must
be 1x1, 2x2, 2x1 or 1x2 - i.e. all the normal ones).
The DSP version completely ignores any detected errors in the input
file (e.g. corruption leading to invalid Huffman table entries being
referenced), but this will usually cause major image corruption anyway.
On average it runs about 3 times faster than a pure 030 scan.
If a full DSP scan can't be done, and the DSP is  available, it will
use DSP iDCT and 030 Huffman, which will run about half of full DSP
speed.
All properly written DSP programs should run OK after the JPEG process
has terminated.



NOTES ON GIF CONVERTER

Interleaved scans are not currently supported, because I haven't got
any interlaced GIF's!
If no colour map is present it will do something silly.
Halfsize reduction and cutdown are not supported (i.e. hardware scroll
mode only for images bigger than the screen).
It's bloody slow, but that's LZW for you.




Known bugs:
  Greyscale files can sometimes refuse to decompress on DSP properly when
  the viewer is first loaded into a clear Falcon. Decompressing a colour
  JPEG first will fix this. I am investigating the problem.

  When viewing large pictures, the hardware scroll registers can be
  set wrongly by the viewer if the image is more than 1024 pixels wider
  than the screen resolution, resulting in a corrupted display. Usually
  this only happens if viewing a big picture in reduced resolutions.

  If it is really badly out of memory in slideshow mode it will do some
  very strange and unpredictable things. Usually hitting 'RETURN' a lot
  will wake it up.

  A strange error somewhere in the maths can cause it to distort blocks -
  this bug is very rare and almost impossible to simulate in tests, but
  investigation is under way. It may be due to a corrupted JPEG file with
  poor pickup of restart markers. So far I haven't seen it on a pic without
  restarts.

  Still might be a bit of a bug with the halfsizer, although I'm blown if
  I can find it.


Possibly coming in future versions:

  More pic formats - Targa under development, possibly TIFF and RAW.
  Save preferences, if problems with finding the preference file can be
  fixed.


Code History:

 2.14: Preferences changes, and switch to assemble 030-only version. File
 sizes now shown. GIF bugs fixed. PAL600 fixed for TV's that have fiddly
 syncpulse requirements. Screen scroll system fixed properly. DSP lock
 and error detection now reported to options screen. Upsampler reworked
 to allow halfsizing of all JPEG's. Halfsize bug fixed (sort of). Enabled
 a key to swap frame alternacy to occasionally improve display of some
 JPEGs. Contrast expansion added. Not happy with the control system for it.

 2.13: Added other file format handling: Degas, Spectrum 512 (you
 won't BELIEVE how much fiddling this routine's been through, since
 I had to manually tune it - and a stupid bug didn't help!). Fixed memory
 allocate to only allocate on 4-byte boundaries beacuse otherwise
 the video system complains, sometimes stridently.

 2.12: Fixed a series of bugs in MCU transform and upsampler to get more
 sampling ratios working properly. Improved GIF converter a bit. Added
 SOF1 marker to let low-quality sampled images work properly. Added
 'slideshow all' mode if no files are marked. Switched over to 16-bit
 Truecolour, but can't see the difference, so I dunno whether it works!

 2.11: Fixed PAL600 bug caused by manky video programming. Introduced
 Info. Introduced source history. Which is why it doesn't go too far back!

 2.10: Added slideshow mode, including view-and-decompress any pic,
 including major rewrites to all the video code. Code rearranged into
 logical sections (select/view & scan, JPEG, GIF).
 Added no-hardware access mode. Fixed some minor bugs with selector.
 Rewrote DSP output transform to fix some more sample ratios for DSP.

 2.09: Rewrote upsampler for more than just 2x2/1x1 sample ratios.
 Went over to DSP code 2.01, and rewrote IDCT-on-DSP output transform
 accordingly. Moved big non-initialised data to BSS segment.


DSP code history:

 2.01: All coefficient output converted to be range-limited. Some speed
 modifications made.
 2.00: Huffman/IDCT on DSP.
 1.0: IDCT on DSP.





Rough Execution times for 640x480 colour JPEG:
030 version: 15 seconds
DSP version: 6 seconds

Currently supported file formats:

JPG - Jpeg File Interchange Format
GIF - CompuServe GIF (TM)
PI? - DEGAS uncompressed
PC? - DEGAS compressed
SPC - Spectrum 512 compressed



Regular updates should be available - when I either think of new ideas,
or manage to find a new JPEG it won't handle!

Coming soon: Starball, an ST / Falcon Pinball game, which is completely
awesome, in every respect. Falcon features include 50 frames per second
operation and stereo soundtracker sound. Even on the ST it'll blow your
socks off. Believe it!

