Viewjpeg  v1.0.1

------------------------------------------------------------------
Copyright (C) 1993, 1994 Evan Harris (much of the image prossesing)
Copyright (C) 1995       Eric Gandt  (added menu and improve image 
                                      prossesing)

Permission is granted to freely redistribute and modify this code,
providing the author(s) get credit for having written it.
------------------------------------------------------------------

viewjpeg is Menued JPEG viewer which utilizes svgalib and contains
limited GIF, PPM, BMP, XPM, XBM and TARGA viewing support.

The most useful feature of viewjpeg is that it automatically decides on
the "best" video mode to use based on the image being displayed and
the video card being used.  To aid it, various hints may be given as
program options.  In the worst case, it may be overridden.

Video modes supported are limited to, 1024x768, 800x600,640x480 and 
320x200 in 256, 32K or 16M colours (assuming the video card, supports
 these modes).  Logical screen sizes are only limited by the size of 
video memory and svgalib.

In normal mode, if the image is larger than the screen size the h/j/k/l
or arrows (in ncurses mode) keys may be used to scroll around that part
of the image which could be loaded into video memory.  Using + and - the
size of the screen can be change.  Pressing Enter, N or Space will load the
next image (with space also marking it).  Pressing p will load the prevous 
image.

------------------------------------------------------------------

Program options for the command line version only
=================================================

-q	QUANTIZE PICTURE (256 colour mode)		(JPEG only)
	This option forces the image to be quantized into a colour
	map with 256 entries, and subsequently seejpeg uses a 256
	colour mode.  If this option is not given seejpeg will not
	use a 256 colour mode unless the TESTMODE is not available
	(see below) in which case it will implicitly set -q.
	The default quantization to use is two pass quantization -
	this is memory intensive and may cause the machine to page
	if the image is large or memory is small.  This should be
	the only occasion in which seejpeg causes a machine to page.
-1	ONE PASS QUANTIZATION (-q implicit)		(JPEG only)
	As -q, except that it uses one pass quantization.  This does
	not cause a machine to page, but the results are worse, unless
	the image is greyscale.
-g	FORCE GREYSCALE MODE (-1 implicit)		(JPEG only)
	Display the image in greyscale.  This is not necessary for
	an image compressed using the greyscale option on cjpeg as this
	mode will be set automatically.  It can be used for images
	compressed without the greyscale flag, or for displaying colour
	images in greyscale.
-w	ONLY USE WIDTH TO DETERMINE VIDEO MODE
	By default, the video mode chosen is the smallest one possible
	which is not smaller than the image.  This may not be desirable
	for long, thin images.  It may be preferable to choose the
	video mode based on the width only, rather than the width and
	height, in which case this option should be used.
-f F	SET FUZZ FACTOR TO DETERMINE VIDEO MODE
	A video mode is selected if it is larger than the image.
	Using this option allows a video mode to be selected if it is
	larger than (or equal to) F * image_width and F * image_height.
	Currently, F must be in the range [0.5,1.0].  This option may
	be used in conjunction with -w to only use the image width.
-F S	FORCE THE USE OF THE GIVEN VIDEO MODE
	To completely override the video mode selection routines the
	video mode number see help. If this is a 256 colour mode, 
    quantization (-q) is automatically selected.

Options for the menu version
============================

(these options are when in the menu only)
j or arrow     scroll down an line
k or arrow     scroll up a line
h or arrow     scroll right a colmn
l or arrow     scroll left a colmn
i or arrow     change video options including greyscale, video
               mode forcing and marked file viewing.
u              go to prevous directory
d              change the current directory
r              refresh the screen if crap appears
?              Help screen
   ( these options may be used while viewing graphics also )
ENTER, N       View next Image
BACKSPACE, P   View prevous Image
Space          mark current file
Ctrl-X         Exit the program

also on the command line a remote directory can be entered
ie.  viewjpeg /usr/bin, the remote directory will then be
displayed if it exists.

Options and information for both versions
=========================================

In addition to colour and greyscale JPEG formats, GIF, PPM, BMP and TARGA
image formats are supported to a limited degree.  If the image is in
GIF, BMP, PPM or TARGA format the -q, -1 and -g options are inoperative
and, as a result, some video modes are not available for selection
using -F.

Unfortunately, due to a limitation in libjpeg, the GIF support has to
perform its own colour map construction so it can use 256 colour
modes.  This may cause problems, although I haven't seen any yet.  GIF
support currently only uses 256 colour modes, however changing this
should be easy, if the demand is there for it.  GIF support has had
limited testing.

BMP support is for microsoft 8 and 24 bit bitmaps both uncompressed and 
compressed.  1 and 4 bit bitmaps are not supported since who would want 
to view them any ways.  Also os2 2.1+ bitmaps should be supported in 8 and
24bit modes but this is untested.  You can not quantize a 24bit bitmap yet
since I do not understand how this is done.

XPM and XBM support is only slightly tested but it seems to work ok.  Note
that this formats are doubled so that you can see them.

PPM support is barely tested.  It uses 16M or 32K modes for colour
images, and 256 modes for greyscale images.

TARGA support is completely untested as I've never seen or generated a
TARGA image.  The -targa option of cjpeg is not included in seejpeg,
let me know if something like it is required.

------------------------------------------------------------------

Compiling
=========

This program requires version 1.25 or higher of svaglib. Also it needs 
ncurses 1.8.7 or higher for the menu version but ncurses is not needed for
the command line version(see USE_NCURSES below).  This is changed from
previous versions because we now call vga_init() which gives up supervisor
rights really quickly.

The following symbols can be defined in the Makefile:
PIX_ALIGN	The constraints on the logical line length for different
		video cards are different.  Some video cards (like my
		CLGD5426) want the logical line length to be a multiple
		of 8 pixels, while others don't look good unless it is a
		multiple of 64 pixels (such as some (all?) Mach32 cards).
		This value also affects the horizontal scrolling, so use
		the smallest you can get away with.
		The default value is now 8 pixels.  Hopefully this
		produces good results for everybody.  Other values that
		may be worth trying would be 8, 16 and 32.  I recommend
		using the lowest value that produces a good display.
NO_32K_CASCADE	If the best mode is available in 16M and 32K modes and
		the complete image doesn't fit in memory using the 16M
		mode, the 16M mode is discarded and 32K mode used instead.
		If you define this option this action does not happen.
		The only time I can think of this option being useful is
		if a video card supports 16M modes but not 32K modes.
TESTMODE	This video mode is tested for -
		If the video card supports it, we assume that hicolor or
		truecolor (32K or 16M) modes are available.
		If the video card doesn't support it, we assume that only
		256 colour modes are supported.
		If this is not set in the Makefile, it is assumed to
		be G640x480x32K.  If there is a video card which supports
		hicolor or truecolor but not this mode, let me know of
		a better default to test for and I'll change it in the
		next release.
BUG_WORKAROUND	Some versions of svgalib with some video cards can scramble
		the video mode when multiple files or slideshows are shown.
		This appears to be avoided somewhat if the text video mode
		is set between each picture.  This is what the workaround
		does.  This may not be needed for some versions of svgalib
		or some video cards.  It is for my CLGD5426 based card with
		svgalib 1.06.  This option is defined by default in the
		makefile.
USE_NCURSES  This options allows use of the arrow key to scroll an image.  
        It is turned on in the menu version and off in the command 
        line version by default.
COOL_EXIT  This options turns on an exit window and prompts for a key to exit
        Try it and see.

Unless you change one of these options, or the default binary
location, changing the Makefile should no longer be necessary.

You now can build a version of viewjpeg which uses libgr-1.3.  This
shared library is NOT included with viewjpeg.  It is available on
sunsite in /pub/Linux/libs, amongst others.  The viewjpeg makefile
assumes that the the installation is as per the README in libgr-1.3.
If this is not the case, the definition of GRHEADERS may have to be
changed in the makefile.  Also Ncurses 1.80 or greater is needed to compile
the menu option.

------------------------------------------------------------------

Acknowledgements
================

The following people have contributed to the development of viewjpeg.
Thanks everyone.

*************************************************************************
Evan Harris evan@cs.mu.oz.au (author of seejpeg)
    For the code from seejpeg which I used to create the new sections of
    code for viewjpeg as well as the large portions that I did not change 
    in the graphics viewer.
*************************************************************************

Greg Seidman <anthro@cs.umd.edu>
	Help with xbitmap support
Harm Hanemaayer <hhanemaa@cs.ruu.nl>
	ongoing svgalib development, putting up with lots of silly
	questions, providing lots of useful information, and a makefile
	bug report
<wolter@wppc9.oz.au>
Jean-Francois Cordeau <cordeauj@jsp.umontreal.ca>
Peter Mutsaers <muts@compi.hobby.nl>
<ahughes@muddcs.cs.hmc.edu>
	makefile bug report in 1.0
Jeff Grills <jefftep@cs.utexas.edu>
	colour lookup (256 colour mode) bug report in 1.2
Michael Weller <eowmob@exp-math.uni-essen.de>
	PIX_ALIGN patches against 1.1, prompting to add multiple
	images and the slideshow
Nils Rennebarth <nils@exp-math.uni-essen.de>
	described how to compile with libgr-1.3 cleanly

------------------------------------------------------------------

Feedback
========

The current version was compiled and tested with svgalib version 1.20
and a 2MB S3864 based video card and a 1MB CL5426.  If you find a bug 
with any configuration please report it.

Please send any feedback, especially bug reports, to:

Eric Gandt <gandt@wam.umd.edu>
