ZGV(1)

NAME
zgv - view GIF/JPEG/PPM/BMP/TGA/PNG files on VGA/SVGA displays

SYNOPSIS
zgv [ -bcghijklpstz ] [ -J jpg_decmp_type ] [ -M mousetype ] [ -m modespec ] [ -r seconds ] [ dirname | filename | filename1 ... filenameN ]

DESCRIPTION
Zgv is a picture viewer capable of displaying GIF files as defined by CompuServe, with the exceptions listed in the RESTRICTIONS section. It is also capable of displaying JPEG/JFIF files using the Independant JPEG Group's JPEG software, PBM/PGM/PPM files as used by pbmplus and netpbm, Microsoft Windows and OS/2 BMP files, Targa (TGA) files, and the new PNG format.

Zgv displays which picture files are in the current directory, and also lists subdirectories and a parent directory if there are any present. On selecting one of these, zgv will either display it if it is an image, or change directory if not. By default, small "thumbnail" versions of the pictures are also shown on the file selector. However, to create these, you should press 'u' (see VISUAL SELECTOR and KEYS below).

OPTIONS

-b  blockcursor toggle, gives outline cursor not the '3d effect' cursor
-c  centre toggle, whether to centre pictures on the screen (defaults to on, so using -c will turn it off)
-g  betterpgm toggle, whether to use 8-bit or high-colour modes for PGM files (defaults to on, so using -g will turn it off)
-h  display a list of options and a terse description of what the options do
-i  ignore errors and display what picture has been able to be read anyway, if possible. The flag has no effect if zgv isn't started on a file or files as given on the command line. (Even then it currently only has an effect for GIF and PNG files, which in zgv give errors rather than warnings perhaps a little too freely.) You can view a file you are downloading as it downloads with something like 'zgv -ir 1 filename'. This should work for all file types. It's particularly effective with interlaced PNG files - with those you should be able to see a blocky but full-size image when only 15% of the file has been downloaded. The quality gets progressively better as the file downloads (though due to the implementation of the PNG decompression, the image is likely to appear in 'chunks'). The same applies to interlaced GIFs, to a lesser degree. With other image types, the effect is more as you might expect - the as-yet-unloaded area of the image, usually the bottom, is blank.
-J  sets JPEG speed/quality tradeoff - '1' = floating-point - slow but accurate, '2' = slow integer - faster but not as accurate, '3' = fast integer - fastest but less accurate still. The default tradeoff is '2'.
-j  jpeg24bit toggle - defaults to on, so using -j will turn it off.
-k  vkludge toggle, smooths slightly in 320x400 and 360x480 modes, and also when 'zooming' a big picture down to screen size
-l  loop 'forever' in slideshows (actually until you press Esc). If this option is not specified, zgv will stop the slideshow at the end of the file list.
-M  tell zgv to use mouse support. The mousetype argument should be one of 'ms' (Microsoft), 'msc' (Mouse Systems Corp.), 'mm' (MM Series), 'logi' (Logitech), 'bm' (BusMouse), 'sun' (MSC 3-bytes), or 'ps2' (PS/2) - this sets which type of mouse you have. The file /dev/mouse must be (possibly a link to) the device your mouse is connected to, for example /dev/ttyS0.
-m  startup mode; the modespec should be in quotes but otherwise in the same format as the .zgvrc entry startmode e.g. "640 480 8" (see CONFIGURATION below).
-p  toggles progress report when loading single file. If set, this stops zgv displaying the progress report bar while loading files when invoked with something similar to "zgv wibble.gif". The onefile_progress config file option has the same effect.
-r  if seconds is >0, then any picture displayed is re-read and redisplayed (without clearing the screen first) every seconds seconds. If it is equal to -1, then the picture is re-read as often as possible. If zero, the picture is only read once - the default. Unless this option has suddenly inspired you to write an interesting little shell script, you're unlikely ever to have a use for it. :-)
-s  causes zgv to output the x and y offsets, width and height of the section of the image being displayed when you press Esc. Can be useful for things like "pnmcut `zgv -s input.ppm` input.ppm > output.ppm".
-t  thicktext toggle, makes the text a little bit clearer, kind of
-z  zoom toggle, i.e. whether to scale pictures to the screen size
filename
    makes zgv auto-load the file, and exit when you exit from viewing the picture. This also makes it possible to view single files without the usual extensions such as '.gif', etc.
dirname
    causes the program to start with dirname as the current directory for the file selector. (What really happens is that whenever a filename or dirname is specified on the command line, the named file is tested to see if it is a directory, and the according action is taken.)
filename1 ... filenameN
    causes zgv to do a slideshow of the specified files. This is useful for things like 'zgv ~/graphics/*.jpg'. You may want to specify -l so that zgv will loop around these pictures until Esc is pressed.

All options are processed after any $HOME/.zgvrc or /etc/zgv.conf file.

KEYS
The keys when using the file selection screen are as follows:

Esc exit zgv
x   same as above
k   move the selection pointer up
j   move the selection pointer down
h   move the selection pointer left
l   move the selection pointer right
Home or Ctrl-A
    move to the start of the directory listing
End or Ctrl-E
    move to the end of the directory listing
PgUp or Ctrl-U
    move back (almost) a page in the directory listing
PgDn or Ctrl-V
    move forward (almost) a page in the directory listing
Enter
    views the image, or changes to the directory (while waiting for an image to be loaded, you can press Esc to abort - on JPEG files in 8-bit mode, you may have to wait a while for this to be acknowledged)
v   switch between the visual selector (default, filenames + pictures) and the text selector (filenames only).
c   in 640x480x16 mode, switch between colour and monochrome thumbnails.
Ctrl-R or Ctrl-L
    rescan the current directory, and redisplay the screen.
D or Delete
    deletes the image file, if you have permission to do so. You are prompted to confirm the deletion, unless nodelprompt is set (see CONFIGURATION).
t   tags an image.
T   tags all images in the current directory.
n   untags an image.
N   untags all images in the current directory.
Space
    toggle whether an image is tagged or not.
Tab does a 'slide show' of all tagged files, waiting a few seconds between displaying each image. (In practice, the wait time will vary as the next image is loaded while the previous image is still onscreen.) Pressing Esc will abort the 'slide show'.
?   shows a help page summarising (some of) these keys.

The cursor keys or the keys 'q', 'a', 'o', 'p' can also be used to move the pointer. Note that PgUp/Ctrl-U and PgDn/Ctrl-V actually move the pointer back/forward (nearly) a page rather than the files listed back/forward, which will probably seem a little odd.

When using the visual selector, there is the addition of 'u', which updates the picture index. New thumbnail files are created if either no thumbnail exists for a given file, or if the file was modified more recently than the existing thumbnail file. Note that errors reading a picture file are not reported when generating thumbnail files - the file is simply left without a thumbnail.

The keys used by zgv when viewing an image are as follows:

Esc returns to file selection screen
x   same as above
k   scrolls up the image
j   scrolls down the image
h   scrolls left along the image
l   scrolls right along the image
K   scrolls up (larger step)
J   scrolls down (larger step)
H   scrolls left (larger step)
L   scrolls right (larger step)
Home or Ctrl-A
    moves to the top-left of the image
End or Ctrl-E
    moves to the bottom-right of the image
PgUp or Ctrl-U
    moves (almost) a screen's height up in the image
PgDn or Ctrl-V
    moves (almost) a screen's height down in the image
-   moves (almost) a screen's width left in the image
=   moves (almost) a screen's width right in the image
5   changes to 320x200x256 mode
6   changes to 320x240x256 mode
7   changes to 320x400x256 mode
8   changes to 360x480x256 mode
0   toggles 'virtual' mode which provides an effective 640x400 in 320x400 and 720x480 in 360x480 mode but 'squashing' the image horizontally (it is the default in those two modes, but not in others)
v   toggles vkludge mode, which smooths when in zoom mode or virtual mode

The following modes are available only on SVGA cards supported by svgalib, and then only if your card has such a mode.

F1  changes to 640x480x256 SVGA mode
F2  changes to 800x600x256 SVGA mode
F3  changes to 1024x768x256 SVGA mode
F4  changes to 320x200x15bit SVGA mode
F5  changes to 320x200x16bit SVGA mode
F6  changes to 320x200x24bit SVGA mode
F7  changes to 640x480x15bit SVGA mode
F8  changes to 640x480x16bit SVGA mode
F9  changes to 640x480x24bit SVGA mode
F10 changes to 800x600x15bit SVGA mode
SF1 (i.e. shift + F1) changes to 800x600x16bit SVGA mode
SF2 changes to 800x600x24bit SVGA mode
SF3 changes to 1024x768x15bit SVGA mode
SF4 changes to 1024x768x16bit SVGA mode
SF5 changes to 1024x768x24bit SVGA mode
SF6 changes to 1280x1024x256 SVGA mode
SF7 changes to 1280x1024x15bit SVGA mode
SF8 changes to 1280x1024x16bit SVGA mode
SF9 changes to 1280x1024x24bit SVGA mode
z   toggles 'zoom' mode which scales the image to fit the screen
s   scales up the image (see SCALING below for details)
S   scales down the image
d   scales up the image by doubling the size of pixels
D   the opposite - halves the pixel size
i   toggles interpolation in scaling mode - this is slow!
1 (one)
    toggles between next pixel and next-but-one pixel to interpolate towards in interpolation + scaling mode
r   rotates the image by 90 degrees clockwise
R   rotates the image by 90 degrees anti-clockwise
m   mirrors (horizontally reflects) the image
f   'flips' (vertically reflects) the image
,   decreases contrast
.   increases contrast
<   decreases brightness
>   increases brightness
*   reset contrast and brightness to normal
Ctrl-N
    view previous file in directory
Ctrl-P
    view next file in directory
Backspace
    view previous file in directory, without showing progress report while loading; during a slideshow, skips to next file without waiting
Enter
    view next file in directory, without showing progress report while loading; during a slideshow, skips to next file without waiting
Space
    toggle whether this image is tagged or not, then view next file in directory; during a slideshow, skips to next file without waiting
Enter
?   shows a help page summarising (some of) these keys

The cursor keys act like 'H', 'J', 'K', 'L' in that they move around the image in larger steps. The keys 'q', 'a', 'o', 'p' can be used in exactly the same way the 'h', 'j', 'k', 'l' keys can (i.e. with or without shift). Note that F11 is equivalent to SF1, and F12 is equivalent to SF2.

If you are viewing a GIF (or a JPEG in 8-bit mode) then you must use 256 colour (eight bit) modes - 15, 16 and 24-bit modes are not allowed. The reverse is true when viewing a JPEG in 24-bit mode.

You can use the ^C key at any time to instantly stop the program. This is rather a last-ditch exit, however, and should only be used if some operation is unbearably slow and you want to kill the whole thing off.

USING A MOUSE
You must either specify the -M option when starting zgv for mouse support to be enabled (see OPTIONS for details), or, probably more convenient if you intend to use the mouse often, put mouse type in the config file (see CONFIGURATION for details).

Moving the mouse acts as the cursor keys would, in both the file selector and when viewing a picture.

In the file selector, the left button views a picture (like Enter) and the right button tags/untags a picture (like Space).

When viewing a picture, the left button goes to the next picture (like Enter) and the right button goes to the previous picture (like Backspace).

If redisplay of the picture takes a long time, zgv can lag behind mouse input somewhat. This shouldn't be much of a problem unless you use scaling with interpolation, and if you use that you're beyond help anyway. :-)

VISUAL SELECTOR
The visual selector works in a similar manner to the 'Visual Schnauzer' provided in xv. In fact, it operates by using the same format "thumbnail" files in the same subdirectory, .xvpics. This means that indexes of thumbnail files created by zgv can be used by xv, and vice versa. But if you don't use xv, or use it but not its' visual schnauzer, then you need to 'update' the picture index from zgv. As in xv, this is a fairly time-consuming process the first time around, but saves zgv from having to repeat the calculations every time it wants to show you roughly what the file looks like. After the first 'update', further updates only need to re-index those pictures which have changed or are new.

In general, you need to re-index the current directory (by pressing 'u') whenever any filenames (other than directories) appear with not a picture below them, but a 'document' symbol - a rectangle with one corner 'folded over'. Directories are always shown with a 'folder' symbol.

While the index is being generated, the message "Updating index of ..." replaces the usual "Directory of ...". The Esc key can be used to abort the update process; zgv may take a while to respond, however, as it finishes creating the current thumbnail image first.

If you switch virtual consoles while zgv is updating the thumbnails, it will keep updating them 'in the background'. When you switch back, if the update is still in progress, it may look as though zgv is doing nothing (or the screen may look a bit confusing) for some time. The reason is that the screen is not updated unless zgv is running on the currently displayed console (this is unfortunately necessary). The screen is redrawn when the thumbnail currently being dealt with has been finished.

The visual selector normally operates in 640x480x256 mode; if this mode is not available, 640x480x16 mode will be used instead, but using this mode means that display will be slower. It also means that you must choose between either low-quality eight-colour thumbnail pictures, or higher quality eleven-greyscale monochrome thumbnails. Zgv defaults to using monochrome. If you'd prefer to have colour, put the line 'fs16col on' in your ~/.zgvrc file. You can switch between monochrome and colour while running zgv by pressing 'c'.

You can switch between the visual selector and the filenames-only selector by pressing 'v' while on the file selection screen. The filenames-only selector has two main advantages - it shows many more files onscreen at once, and it doesn't need lots of disk space for thumbnail files, which range from around 1K to 5K each.

The thumbnail images are dithered to a 3:3:2 palette - 3 bits red, 3 bits green, and 2 bits blue. This results in only four greyscales, but for the average colour image, it's a reasonable spread (the eye is more sensitive to green - and red - than to blue). Since this uses up all 256 colours available, providing the file selector with the colours used for drawing the cursor, the text, etc. is awkward. The manner in which this is dealt with by default is to select the colours in the 3:3:2 palette 'closest' to the colours required, and then to change them to the file selector colours. In my experience, this results in a mininal disturbance to the thumbnail images. However, the option perfectindex in either configuration file can be used to stop zgv changing the colours. This will probably result in the file selector looking a little (or a lot) strange, but the thumbnail images should be restored to normality. Anything you cannot cope with then is therefore your own problem. :-)

When the visual selector is operating in 640x480x16 mode, these 3:3:2 images are (currently) mapped to 11 greyscales. In this mode, zgv always acts as though perfectindex was specified, as five palette entries are reserved for the colours used by the selector.

If the directory .xvpics can't be created or written to - such as when using an MS-DOS partition or floppy, or a CD-ROM - zgv will use a different strategy for storing the thumbnails. It creates the directory ~/.xvpics/_sample_path_name and stores the file there if possible. The _sample_path_name is the original path (in this case /sample/path/name) with the slashes converted to underscores. The fact that zgv is storing the thumbnails somewhere else won't make any noticeable difference when using zgv. (Except that the delete feature will not delete any thumbnails in or under ~/.xvpics.)

SCROLLING, ZOOM MODE, AND VIDEO MODES
When you're viewing a picture, there are lots of curious things you can do - some useful, some useless. This section covers most of the useful ones.

If a picture is bigger than the screen, there are two different ways to view the rest of the picture. First you can scroll around the image - using the cursor keys or 'h', 'j', 'k', 'l' or 'q', 'a', 'o', 'p' - which means you can only see part of it at once, or you can fit the image to the screen, which loses resolution and makes the image look either gritty or smudged (depending on whether the 'vkludge' option is being used - more about that later).

Scrolling is probably the more useful of the two, and is the default method used. The cursor keys move around the image in 100-pixel steps, as do 'H', 'J', 'K', 'L' and 'Q', 'A', 'O', 'P' (i.e. hold shift). Using 'h', 'j', 'k', 'l' or 'q', 'a', 'o', 'p' unshifted moves around the image in 10-pixel steps. The Home key moves to the top-left of the image, and the End key moves to the bottom-right. PgUp and PgDn move up and down in pages, oddly enough. '-' and '=' move left and right in pages, which really is odd.

The method which fits the image to the screen, or 'zoom' mode as it is confusingly called, is toggled on or off by pressing 'z'. The scrolling keys will no longer have any effect, because there's nowhere to scroll to (you can see it all). You can toggle the 'vkludge' mode on or off by pressing 'v'.

In zoom mode, having vkludge on causes zgv to average out an appropriate area from the unzoomed image for each new onscreen pixel, so what you see looks better, but takes longer to draw. (The word 'appropriate' is being used in a rather dubious and optimistic sense here.)

When using either 320x400 or 360x480 mode, having vkludge on means that zgv does a similar kind of averaging between the two pixels which are being mapped to one onscreen pixel. (Zgv does this 2-to-1 mapping normally with these modes so that the modes are pseudo-640x400 and 720x480 modes, which should be more useful. Vkludge makes it look better, but takes longer. To disable this mapping altogether when in the mode, press '0' (zero).)

When not in zoom mode and not in a 'virtual' mode, vkludge has no effect.

8-BIT AND 24-BIT MODES
Zgv allows for the varying types of video modes available from modern SVGA cards by using two different internal modes. This controls only how the image is stored in memory, but can affect how it appears on the screen.

GIF files contain up to 256 colours from a palette of 16.7 million, although in practice most GIF files follow the VGA hardware's capabilities of 256 colours from a palette of 262,144. Zgv always displays GIF files in 8-bit (256 colour) video modes.

JPEG files are either greyscale or 24-bit. Greyscale JPEGs are always shown in 8-bit video modes. (See point 2 under IMPLEMENTATION for a discussion of greyscale handling in 256 colour modes.) 24-bit JPEGs, which can have any colour from a fixed 16.7 million colour spread can be shown in 24-bit video modes, in 15 and 16-bit video modes (the latter two being 32,768 and 65,536-colour modes respectively), and dithered to 256 colours in an 8-bit mode. Zgv (by default) uses a 15, 16 or 24-bit colour mode to display JPEGs if possible.

PBM files are shown in 8-bit. PGM files are shown in 8-bit unless 'betterpgm' is set, in which case they are converted to 24-bit internally and displayed in 15, 16 and 24-bit modes. PPM files are shown in the same way as 24-bit JPEGs.

Note that if a file is loaded as 8-bit internally (GIF, PBM, usually PGM, sometimes JPEG and PPM) then it can only be displayed in 8-bit video modes. If one is loaded as 24-bit internally (usually JPEG and PPM, sometimes PGM), then it can only be displayed in 15, 16 or 24-bit video modes. This is necessary because of the conversion overhead in the 24 to 8-bit direction.

BMP, TGA and PNG files are treated in the same way as PBM, PGM or PPM files depending on the colour depth.

Since 15 and 16-bit video modes do not have quite the same representation (and depth) that a file loaded as 24-bit does, there are some setbacks to using them. The image is converted to the 2-byte-per-pixel format as it is drawn. Also, the modes actually have less colour depth than 256 colour modes.

In explanation of that last point; although 15 and 16-bit video modes show many colours onscreen at once, these colours are not selected from a palette which restricts the colour depth.

A good way to illustrate this point is by considering a greyscale JPEG image. In a 256 colour video mode, only 64 greys can be shown, since 2^(log2(262144)/3)=64. With a 15-bit video mode, even less can be shown - 2^(log2(32768)/3)=32. Because of the way that 16-bit video modes work, which is by providing the green channel with twice as much colour depth (i.e. an extra bit), they can also only show 32 greys. Put another way, 2^int(log2(65536)/3)=32. (Of course, 24-bit mode will show all 256.)

SCALING
In addition to the 'zoom' facility which resizes an image to fit the screen, zgv can scale up the pixels in an image to make it appear larger. The 's' key scales up ('zooms in', if you like, but remember that this is not what zoom mode does!), and the 'S' key (that's shift + s) scales down ('zooms out'). Note that this 'zooming out' goes no further than the normal 1:1 pixel ratio - if you want to fit a large image to the screen, use zoom mode instead by pressing 'z'.

The way the scaling works is as follows: Normally the pixels in the image are displayed as one pixel in the image = one pixel onscreen. All that happens when the scaling keys are used is that this 1:1 ratio gets changed - for example, if you press 's' then the ratio is now 1:2, and one pixel in the image shows as 2x2 pixels onscreen so that it's double the size of the original. If you then press it again, the ratio becomes 1:3 (note that pressing 's' adds one to the second number, rather than doubling it as is common), and one pixel in the image translates to 3x3 pixels onscreen. You can carry this on up to 1:512 if you wish, where zgv stops so that pixels may be conserved for future generations.

If you want to change the ratio by doubling instead of adding one, you can use 'd' and its' counterpart key 'D'. This causes ratios like 1:1, 1:2, 1:4, 1:8, 1:16, etc.

When an image is scaled up, you should be aware that the movement keys such as the cursor keys operate on the scaled-up image, rather than the image which has been scaled up; even to the extent of moving fractions of an unscaled pixel if appropriate. As such, zgv operates exactly as if you had loaded up directly the scaled-up image... except that everything happens rather slower. :-)

You may find, while scaling back down again, that the screen clears when the image starts returning to normal size. This is perfectly normal, as zgv is clearing the screen to make sure no junk remains from what was previously there. Since this is only necessary when the image as shown is smaller than the screen, zgv only does it then.

Unfortunately, there are a couple of problems with the scaling functions. Firstly, they cannot be used in 320x400 and 360x480 modes (they'll have no effect). If you want to use scaling in that mode, one workaround - admittedly rather clumsy - is to switch to 320x240 or 320x200 mode (press '6' for the former or '5' for the latter), treat this as the 1:2 scaling up, and carry on from there.

Secondly, if you are 'zoomed in' and flip or mirror the picture, then you will (effectively) end up looking at a completely different part of the picture. This is the case normally, but isn't usually quite as noticeable.

Note that by default zgv will reset the scaling to 1:1 whenever a new picture is viewed. To stop this, and have the scaling persist 'between pictures', insert 'revert off' in your configuration file (see CONFIGURATION below).

SCALING WITH INTERPOLATION
This is more a sign of my thinking, "hey that'd be a cool feature to add" than anything else. In scaling mode, there is an additional feature which 'smooths out' the screen pixels which lie in-between image pixels. This is horribly slow, much more so than scaling mode alone; in addition, it only works in a 15, 16 or 24-bit screen mode, which means it will only work for PPM and JPEG files and only if you have a card which supports one or more high-colour modes.

The 'i' key toggles the interpolation on and off. If you do intend to use it, you should probably use normal scaling mode and the panning controls to move to some part of the image, and then turn interpolation on.

At the ratio 1:2 (and, at a stretch, 1:3) it's often good with JPEGs to use the '1' key to toggle next-pixel-bar-one interpolation, which ends up not really interpolating properly; however, it does smooth out some of the blotchiness there is in scaled-up JPEGs. If you use the toggle on a highly scaled image, you should be able to see how inaccurate the interpolation becomes.

CONSOLES
If not run from a console tty, zgv will attempt to run on the first available console - if there are none free, it will exit with an error message. When it has to switch consoles like this, exiting zgv will cause an automatic return to whichever console was current when the program was started.

There is, if not an actual security risk, certainly nuisance value in allowing anyone to run a program which automatically switches to another console. Zgv tries to alleviate this by attempting to open the tty device corresponding to the current console for read/write on startup. If it can manage this, it assumes that the user is 'genuine', closes the tty it opened to test this, and carries on.

There is a problem when running zgv from X, when it's invoked from, say, a twm or fvwm menu. (It works ok from an xterm.) The problem is that the window manager runs the program with its stderr attached to the tty that the X server was started from. Since zgv tests stderr to see if it's a console, which in this case it probably will be, everything gets very confused.

As luck would have it, there's an easy workaround; when invoking zgv from the menu, just redirect the stderr to a non-console, say /dev/null. For example, here's an extract from my system.fvwmrc:

Popup "graphics"
    Exec    "XV    "    exec xv -8 &
    Exec    "Zgv    "    exec zgv 2>/dev/null &
    Exec    "XPaint    "    exec xpaint &
    Exec    "Bitmap    "    exec bitmap &
EndPopup

It seems a bit odd running zgv from X, but it can be useful if you have a 15/16/24-bit card and normally run X in monochrome or 8-bit colour.

Running zgv from an xterm with a filename as an argument is generally how you'd do this, though - e.g. "zgv wibble.jpg". Zgv then runs on a free VT and switches back when you exit, so it's fairly hassle-free. If you want to switch back to X before exiting zgv, it's just a matter of switching VTs, as usual. X will be running on the first free VT; often this is number 7.

Apparently, there can be problems starting zgv from an X session if xdm was used to login. As far as I know, xdm tries to change the ownership of /dev/console to the person it is logging in. This isn't such a great idea - you should get it to 'chown' the console that the X session is running on, which is likely to be console 7.

CONFIGURATION
Some of the ways in which zgv works, and the settings it uses, can be altered using either the file $HOME/.zgvrc or /etc/zgv.conf. The latter is intended as a system zgv defaults file. You should use the former (which overrides /etc/zgv.conf) if more than one person is going to use zgv on the console.

The config file is arranged so that each line is blank, or a comment, or consists of one assignment. (If you're starting to feel ill, look at the sample.zgvrc file supplied with zgv, and work it out from there.) Comment lines begin with the hash ('#') character. Blank lines are ignored. Assignment lines give a new value to an attribute of zgv's operation - the attribute names are listed below. Comments can also be put on assignment lines; anything after a '#' is ignored.

Attributes are defined by a line like this;

<attrib_name> <value1> [value2 ... ]

'Boolean' values are either "on" or "off", integers are small integral numbers (where small is defined as "between -2^31 and 2^31-1 inclusive" - gotta love Unix :-) ), and 'float's are floating-point (i.e. real) numbers.

visual
    whether to use the visual selector or not - boolean
perfectindex
    if set then don't change any colours when using the visual selector (see the VISUAL SELECTOR section above) - boolean
zoom
    sets zoom mode - boolean
centre or center
    whether to centre the pictures or not - boolean
blockcursor
    use a more visible 'block' cursor - boolean
thicktext
    make the file screen text a bit thicker (this only takes effect if blockcursor is on as well) - boolean
nodelprompt
    inhibits the "Really delete <filename>?" prompt when deleting a file from the file selector if set - boolean
cleartext
    specifies whether or not to clear the text screen upon startup and on exit - boolean
onefile_progress
    has the same effect as the -p option (see OPTIONS above) - boolean. Defaults to 'on'.
hicolmodes
    zgv has a short test routine which tries to determine whether your video card has high-colour modes (15, 16 or 24-bit), so it knows whether it's possible to use them or not. If your card has a 640x480 high-colour mode but no 320x200 high-colour mode, this test will fail - this is a bug, not a feature. :-( This (boolean) option is provided so that if you have one of these cards, you can at least force zgv to work with it by inserting "hicolmodes on" in one of the rc files.
force16fs
    if set, forces the program to use 16-colour mode for the file selector. You should do this if, although your video card is capable of 640x480 in 256 colours, the screen is somehow garbled or unusable.
fs16col
    if set, zgv uses low-quality colour thumbnail pictures when the file selector is using 640x480x16 mode (i.e. on vanilla VGA cards). If turned off (default), zgv uses monochrome thumbnails.
revert
    is on by default, and if set zgv resets the scaling ratio to 1:1 each time a new picture is viewed. It also turns off scaling interpolation, if that is set.
jpeg24bit
    sets whether to try and use a 15, 16 or 24-bit display mode for JPEGs. On = try, off = don't try. If 'jpeg24bit on' is used on a card where only 256 colour modes are available, zgv will act as though 'jpeg24bit off' was used.
vkludge
    sets vkludge mode - boolean; this smooths the two image-pixel wide pixels in 320x400 and 360x480 modes, and also - when in zoom mode - smooths images larger than the screen size to reduce the unsightly 'ripples' that the resizing down to fit the screen usually causes. By default, off.
mouse
    enables mouse support and specifies the type of mouse you're using. The mouse type should be specified after mouse, as with the -M command-line option, as described in OPTIONS.
black
    sets RGB value of 'black' on file selection screen - takes three integers in the range 0-63 for RGB value
dark
    sets RGB value of 'dark grey' - see above
medium
    sets RGB value of 'medium grey' - see above
light
    sets RGB value of 'light grey' - see above
tagged
    sets RGB value of 'tagged file' colour - see above
tagtimeout
    sets time between pictures in 'slide show' in seconds (integer). The default value is 4 seconds.
contrast
    sets contrast value. Zgv implements contrast by multiplying the colour value by this number, and so the value is a float.
brightness
    sets brightness, which zgv implements by adding this number to the colour value. (Brightness, contrast, etc. have no effect in 24-bit mode, as they would be wildly slow and very memory hungry. Believe me, using the monitor controls is much less painful.)
gamma
    sets whether to fake more greyscale and colour depth in 8-bit video modes. By default, on. (See point 2 in the next section for more on this.)
allmodesbad
    (no parameter) stops zgv from allowing any modes. This is usually followed by some 'goodmode' assignments. If it isn't, then zgv simply assumes that the 320x200x256 mode can be used.
allmodesgood
    (no parameter) the default - all modes can be used, if your video card has them.
badmode
    marks a mode as 'bad', so it can't be used. Takes three integers, and is used like this: "badmode width height bpp" where bpp = number of bits per pixel, 8 in 256 colour modes, 15 in 32768 colour modes, etc.
goodmode
    similar to "badmode", but marks the mode as 'good' i.e. usable.
startmode
    defines the video mode zgv should start off using when viewing pictures. This is normally set to the equivalent of "startmode 640 480 8" if possible, "startmode 360 480 8" if not, and "startmode 320 200 8" as a last resort. Takes three integers in the same way as "badmode" and "goodmode". Zgv will automatically switch to the 15, 16 or 24-bit mode nearest to the resolution of the 8-bit mode currently being used if 'jpeg24bit on' is being used, and vice versa (sort of).

IMPLEMENTATION
This section covers some aspects of the implementation of zgv which the author thinks may be of interest in some situations. Feel free to skip this section, as I'll indulge in any long-winded, boring discussion I want. ;-)

1. Whenever zgv reads a file, it needs to allocate memory to read or decompress the file into. The size of the memory required varies from file to file, so it must be allocated at the time it is needed (i.e. dynamically). This is all very well so far, but there is a bit of a problem.

Say you start zgv, then view a 1 megabyte file. (This isn't too unlikely - 1024x768 is getting close.) The size of zgv's total memory allocation, i.e. the total memory used by the zgv process, is increased by 1 Mb via malloc() to store the image. Although this allocated memory is free()'d when you quit viewing the image the memory is not returned to Linux. It is recycled by future allocations in the zgv process, however, which is some consolation. Note that this behaviour is the case for all programs that use dynamic allocation via malloc() - it's just that zgv has to use such potentially large blocks of memory, even if only for a short time, that this is more noticeable than is usual. Actually, my experimentation has shown that this doesn't seem to hold exactly true. (Not sure why...) Unfortunately, it's still easy to end up with zgv taking 3 or 4 megs after viewing a big 24-bit image.

So what are the problems with this? Since Linux has virtual memory, there aren't many; any unused data will (presumably) be swapped out to disk when it gets in the way. My advice is to make sure you've got at least eight (preferably twelve) megs of total memory - i.e. real RAM plus swap space.

2. When using 8-bit video modes, zgv uses some trickery to try and increase the apparent colour depth a little. The VGA's 256 colour hardware only has 18-bit palette resolution (where 24-bit would be 'perfect'), which means, among other things, that only 64 greyscales can be shown.

The trick zgv uses is to increase one or two of the red/green/blue channels by one, giving a coloured 'pseudo-grey'. Since the eye is more sensitive to brightness than colour, this is reasonably convincing under normal conditions.

A slightly more unusual use of this technique in zgv, though, is that it carries on using it for colour 8-bit images. I'm not certain how valid this is; the 'sub-depth' value is calculated as a greyscale, and the channels altered are the same, with no consideration given to how this might affect the colour balance.

However, the difference this feature makes is very slight. The image will probably be very, very slightly brighter than it would be otherwise, and possibly a little 'warmer' because of the minor use of colour and the eye's green/red bias (I think).

If you want to disable this pseudo-grey feature, put 'gamma off' in your config file.

FILES
$HOME/.zgvrc - this is where zgv first looks for a config file. If it can't read the file, or it doesn't exist, it tries...

/etc/zgv.conf - which is intended to be the system's default zgv config file. If this can't be read, the built-in defaults are used. (Actually, this isn't quite true - it also checks for /etc/system.zgvrc before giving up, but /etc/zgv.conf should really be used instead.)

.xvpics - this is the subdirectory under which all picture file thumbnails are stored. /dev/mouse - this is the mouse device used if the -M option is given on invocation.

BUGS
Starting zgv in or on a directory which you do not have permission to read will result in a null list of files. You'll have to just press Esc to exit and start zgv again.

If errors occur when zgv is loading a new file while the old file is still being displayed, the error message appears over the top of the old image (which almost always looks terrible, but doesn't cause anything nasty).

PNG files with alpha channels can't be loaded for some reason; they give an 'Extra compressed data' error, implying that the channel is being ignored.

Interlaced PNG files which are very small or thin (less than 8 pixels vertically or horizontally) may not be loadable, or may be loaded incorrectly.

Corrupt JPEG or PNG data warnings are not reported by zgv.

If a GIF file is corrupted in such a way that the decompressed image has a larger number of pixels in it, the extra pixels will be ignored and no error or warning will be generated.

In 320x200 and 320x240 modes, up to 7 of the pixels on the right-hand side of the image are not displayed (in some circumstances).

The help pages only list a few of the keys.

RESTRICTIONS
Zgv does not support any of the extensions in the GIF89a specification, but does read the files - it just skips the extension blocks. Multiple image GIFs are not supported. The combination JPEG/GIF format which can optionally be produced by Handmade Software's GIF2JPG is not supported.

ACKNOWLEDGEMENTS
"The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated." This program is based in part on the work of the Independent JPEG Group. And thanks to Tommy Frandsen for writing VGAlib, and to Harm Hanemaayer and others for extending it to svgalib.

AUTHOR
Russell Marks (mr216@gre.ac.uk).

Mouse support and a few other features by Edwin Fong (hffong@hk.cuhk.cs).

The mouse driving code is taken from selection, which was written by Andrew Haylett (ajh@primag.co.uk).

BMP support by Carsten Engelmann (cengelm@yacc.central.de).

SEE ALSO
xv(1), twm(1), fvwm(1x), xterm(1), XFree86(1), xdm(1), cjpeg(1), djpeg(1), pbm(5), pgm(5), ppm(5), selection(1)