                      .........     ........  ....      ...
                         -===.   -===.        ==o=.   .-=.
 ::|:|||||#|#|#####:  .=***=   .*o*o          ****.  =*=  :####|#|#|||||::
                     =###=    -*##*    o**o   ##** .**-
 :::.... . . .     =*o*-      o**o-   =o*o   -o**o-*-   . . . . ...:.:::::
 ::.... . .      o#@@#-...-=. ##@@*-.=@@@-   =@@@@#-       . . . ...:.::::
               -@@@@@@@@@@*.   o#@@@@@@@o     *@@*
                                

     Zgv v1.3 - GIF and JPEG viewer, for PCs with VGA running Linux

         Copyright (C) 1993 Russell Marks for improbabledesigns


This README covers description and use of the programs. See README.src in
the source distribution, or README.bin in the binaries distribution for
other details. (In fact, you should read those first.) CHANGES describes the
changes made since the most recent publicly released version, and CHANGELOG
describes differences between all versions, so if you are upgrading from an
old version, check those files out too. The file BUGS describes known bugs
which may affect your use of the programs.  



Distribution and Conditions of Use (License)
--------------------------------------------

These programs, and any output from them, can be freely used and
distributed. No modified versions of any or all of the programs, or
derivative works, may be distributed unless specifically permitted by the
author, with the following exception; if the modification is reverseable and
intended in good faith to aid distribution (common occurances include
using 'tar', compression software, etc.), then it is permitted.  

I supply each of the programs on an 'as is' basis in the hope that they will
be useful but with absolutely no warranty of any kind, and assume no
liability or responsibility for any ill they may cause whatsoever.  


Description of the Programs
---------------------------

'zgv' is a viewer which views GIF87a, GIF89a and JPEG/JFIF files on a
standard VGA and some SVGAs, with a full-screen file selector front-end.

'tnpic' produces a JPEG file containing small versions (thumbnails) of other
picture files. Once the programs are installed, do 'man tnpic' for more
details. (Or if they aren't installed, you could do 'nroff -man
tnpic.1 | less'.) 


Display of Pictures
-------------------

Zgv defaults to using 640x480x256 mode if possible - otherwise it uses
360x480x256 mapping two picture pixels to each display pixel, giving a
pseudo-720x480. Although 640x480, 800x600 and 1024x768 should all give
square pixels, which is the Right Thing, the effective 720x480 doesn't.

The modes that do give square pixels on a normal VGA (or unsupported SVGA)
are 640x480x16, 640x480x2, and 320x240x256. The video mode can be changed
using the number keys '1' to '9'. (The numbers match svgalib and VGAlib's
mode numbers - the man page for zgv lists them all.) 

The '0' key changes between the 2 to 1 pixel mapping and the usual 1 to 1 -
this can be toggled in any mode, although it can look weird.

Zgv's file selection screen is always displayed in 640x480x16 mode.

A 256 colour file won't display properly on a mode with 16 or 2 colours
only. And similarly a 16 colour file won't display on the 2 colour mode.
More accurately, a file with too many colours for a given mode will display
incorrectly on that mode. For the purposes of zgv, a JPEG file should be
considered 256 colour, not 16,777,216 colour, as zgv reduces the number of
colours. Currently, zgv won't display any file correctly on a mode using
more than 256 colours at once, e.g. 24-bit modes. See 24bit.txt for an
explanation of why, and when this will probably be fixed. You may want to
check out 'spic' by the author of svgalib, which does allow the use of high-
and true-colour modes. This paragraph has just redlined my 'overuse of the
word colour'-meter. :) 


Keys Used
---------

The keys used in zgv are explained on its' help page (press '?' at either
the file selection or file display screens). They're also covered in the man
page. The ones you most need to know are:  

Esc or x = exit
q = pan up, a = pan down, o = pan left, p = pan right
z = switch between pan and 'zoom' mode

In zgv, the q,a,o,p keys are also used with enter on the selection screen to
view a file or change to a directory, and Esc to exit. The cursor keys, or
the vi keys h,j,k,l, can be used in place of q,a,o,p if you prefer. 's' can
be used to save the current configuration at the file selector screen.


Super VGA and... not so super VGA
---------------------------------

Zgv uses svgalib to support SVGA cards, as well as using it as it previously
used VGAlib. Notice there are some fairly popular SVGA cards which aren't
supported - Paradise for example - and this isn't really something I'm in a
position to do anything about. (I have a Cirrus, and hackers have a tendancy
to be satisfied with something as soon as it runs on *their* machine. :) )
If you'd like to volunteer to implement support for your (unsupported) SVGA,
you should probably contact the maintainer of svgalib, Harm Hanemaayer
(hhanemaa@cs.ruu.nl).

Now to the not so super VGA - the type you apparently get on laptops. Again,
if possible, I'd like to know which of the modes zgv allows work on your
laptop (if you have one). Another idea I've had but not implemented yet is
for a environment variable to mask out certain modes so you can't choose
them - and I'd like to be able to provide a sensible example of what this
should be for most laptops. I have no experience of VGAs on laptops, but the
320x480 and 360x480 modes are bound not to work, and probably several of the
others - but some input on this would be most welcome. For now you could use
the save setup option by pressing 's' at the zgv file selector screen after
having got zgv into the right mode (say 320x200x256) previously by viewing
some picture or other. 



Miscellaneous
-------------

On slower machines, or those without much memory, switching on zoom mode may
cause a delay while the required memory is allocated. Although it could get
annoying on, say, a 2Mb machine, it's harmless and nothing to worry about.
(Unfortunately, it appears that a reasonable definition of 'slow machine' in
this case may be 'less than 486DX'. Hmm.) 

The bar in zgv that shows how far the decompression has progressed (and the
percentage display in gifview) is rather inaccurate for JPEG files, as only
the quantization is taken into consideration. This is however usually the
longest part of converting a JPEG to display.

Zgv needs to be run setuid root. So you'll have to be on as root when
installing them ('make install' does all this sort of thing for you).

A quick note about the way zgv/gifview works. It allocates a (width) by
(height) area of memory. Even 1-bit mono files require a byte per pixel. So
you need that much memory. Unless you're viewing *big* GIFs, that shouldn't
get much over a megabyte. For rotating, mirroring and flipping, gifview uses
a temporary block of memory of the same size again. The point is, if you
haven't got enough memory (if you have less than 8M ram+swap you *might* not
have, if you have less than 4M you definitely don't) then you'll need to set
up a swapfile or swap partition. You should really do this anyway - see the
main Linux FAQ for more details.  

Zooming a smaller picture than the current screen allocates a screens-worth
of memory temporarily (up to ~350K for VGA, or up to over a Meg for SVGA).
The 'virtual mode kludge' uses a 320K colour matching cache. The JPEG
software uses quite a bit of memory when decompressing and quantizing a JPEG
file, since these are 24-bit files - except for monochrome JPEGs, which
aren't very common.  


Contacting the Author
---------------------

I'd appreciate any input you have on zgv - bug reports, questions, ideas for
improvements (anybody who suggests 'how about deleting it?' will be flamed
to death), and such like.

Although I previously wrote "my email address will be mr1cy2@gre.ac.uk from
Oct '93 onwards", this was based on the naive assumption that the way id's
are constructed around here wouldn't change. But it has. I'm now
rm1ajy2@gre.ac.uk, and should stay that until around June '94. I may not be
contactable via email after that time. If you want to contact me for
whatever reason and can't use email, you could always write to me at my home
address:  

  R J Marks
  3 Rapley Close,
  Camberley,
  Surrey.
  GU15 4ER
  United Kingdom

I'll try to reply if I get any communication, especially if you ask me to.
If you don't have an Internet address, I'd also be interested to know
how/where you got zgv.

Share and enjoy! 

- Russell Marks (rm1ajy2@gre.ac.uk)
