zgv - picture viewer for VGA/SVGA displays
zgv [ options
(NB: This man page is automagically generated from zgv's texinfo file, and so
may look a bit odd. We apologise for the inconvenience. :-))
zgv lets you view pictures on Linux or FreeBSD boxes with VGA/SVGA displays. The
kinds of pictures it supports are raster-format pictures (sometimes called
`bitmaps' and/or `pixmaps'); things like GIF files, JPEG files, PNG files, and
so on. (The full list of file formats supported is listed elsewhere. See
Supported File Formats
Most of the time, you will probably want to use zgv's file selector (see The
) to pick which file(s) to view. This is what appears when
you start zgv as just ` zgv
' (see Options
). It displays a list
of subdirectories and picture files in the current directory, along with small
`thumbnail' versions of the pictures if they exist. (If no thumbnails appear
for a given directory, or if they are missing for some files, you can
create/update them by pressing ` u
'. See Updating Thumbnails
When you've picked a file to view, you can view it by pressing ` Enter
This puts you into the viewer, where the whole screen is used to display the
picture (see The Viewer
). You can then move around the picture (if it
is larger than the screen) using the cursor keys. Pressing ` Esc
returns you to the file selector, where you can pick another file to view, or
you can quit zgv by pressing ` Esc
While zgv is by default controlled entirely from the keyboard, it does have
quite good mouse support you can enable if you like that sort of thing. See
Using a Mouse
This overview is, as you might expect, only the very simplest of introductions
to what zgv can do, and describes only a very basic use of zgv. zgv can do a
lot more; read on to find out what.
zgv was primarily written by Russell Marks, who also wrote this manual.
Matan Ziv-Av added multiple-image animated GIF support, Photo-CD support,
brightness/contrast support in high-colour modes, the original file-rename
code, and some of the support for 32-bit modes, as well as inspiring a few
other changes like high-res file selector support.
Carsten Engelmann wrote the BMP support.
Edwin Fong added support for command-line slideshows, and a few other features
including the original mouse support.
Radim Kolar added support for FreeBSD.
Costa Sapuntzakis contributed code for much faster JPEG thumbnail generation.
Dimitar Zhekov added SDL mouse support.
' is a (very) slightly modified version of the original
(which is part of the ` texinfo
' package). This program is used during
installation. I think it was mostly written by Karl Berry, but it's not
The authors of the special-purpose libraries zgv uses deserve credit --- JPEG
and PNG might not have been supported in zgv without the JPEG library, libpng
and zlib. Most of all though, zgv would certainly not have been written
without VGAlib and later svgalib, and thanks are due to Tommy Frandsen, Harm
Hanemaayer, Michael Weller, Matan Ziv-Av and many others for that.
Thanks also to the zgv users who've contributed bug reports, suggestions, ideas
for features, and even... dare I say... compliments. zgv would be even worse
without their input, so count your lucky stars. :-)
This program is based in part on the work of the Independent JPEG Group.
``The Graphics Interchange Format(c) is the Copyright property of CompuServe
Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated.''
Normally you'd invoke zgv as plain ` zgv
'. However, you can directly
specify files to view or a start directory on the command-line. In addition,
there are various options.
(If you're new to zgv, you should probably skip the rest of this section for now
and come back to it later.)
The general format of the zgv command-line goes roughly like this:
zgv [ options
Two types of options are supported --- the traditional Unix single-letter
options, and GNU-style long options. Both forms are listed in the table below,
but not all long options have single-letter equivalents.
Note that all options are processed after any configuration file(s). Config file
settings are just like the long-option names below minus the ` --
), though a few command-line options are not permitted
as config file settings (e.g. ` help
'), and vice versa.
Here's what the options do:
Automatically animate multiple-image GIF files (see
Multiple-image GIF Animation). This limits your viewing options
greatly, but can be handy for slideshows and the like.
Automatically switch modes to suit image size.
` --auto-mode-fit-diff diff
When choosing an auto-mode-fit mode, add diff to
each mode's width and height. For example, with a value of 20 any picture up
to 820x620 will be displayed in an 800x600 mode if possible. If diff is
negative, for example -20, the effect is reversed; any picture above 780x580
will be displayed in a mode with a resolution higher than 800x600 if
Don't show progress indicator when loading a single file
from the command-line.
Try to use a black (or nearest-to-black) background when
in 8-bit modes. This can be quite nice for consistency's sake when viewing
(say) a mixture of GIFs and JPEGs, but the extra pass over the loaded image
slows things down slightly.
Use a blocky outline cursor in the selector, which is
rather unsubtle but more obvious.
` --brightness adjust_val
Specify how much to add to colour values to change
brightness (default 0). Values less than zero decrease brightness, values
greater than zero increase it. Brightness is applied after contrast by
(Normally enabled, use e.g. `--centre=off' to
disable.) By default zgv centres pictures smaller than the screen, in
whichever dimensions they are smaller. This setting gives you a way to disable
this, so that pictures always start in the top-left.
Clear the screen on exit. (Normally, zgv leaves the
original screen contents intact.)
` --col-black r g b
Set colour used for `black' (text) in selector; RGB
values should be in the range 0-63 for this and the other colour settings
below, and the three numbers should be quoted, e.g. ` --col-black "10
` --col-dark r g b
Set colour used for lowlights in selector.
` --col-light r g b
Set colour used for highlights in selector.
` --col-medium r g b
Set colour used for background in selector.
` --col-tagged r g b
Set colour used for tagged files in selector.
` --contrast multiplier
Specify how much to multiply colour values by to change
contrast (default 1.0). zgv multiplies each colour's difference from grey by
this number; values less than one decrease contrast, values greater than one
increase it. Negative values are also allowed, and act in a similar way, but
with the picture's colours inverted. Contrast is applied before brightness by
(Normally enabled, use
`--delete-single-prompt=off' to disable.) If disabled, don't prompt for
confirmation when deleting a single file.
(Normally enabled, use
`--delete-tagged-prompt=off' to disable.) If disabled, don't prompt for
confirmation when deleting all tagged files.
(Normally enabled, use `--dither-16col-fast=off'
to disable.) By default, zgv uses a (reasonably fast) ordered dither when
displaying a dithered colour image in 640x480x4 mode. But if you disable this
setting, it uses error-diffused dithering (which looks better but is rather
If enabled, use dithering in `high-colour' modes, i.e.
15/16-bit modes. This makes colour gradients smoother, but slows things down
quite a bit.
(Normally enabled, use `--fake-cols=off' to
disable.) If disabled, don't fake extra greyscales and colour depth in 8-bit
modes. See Increased Greyscales, for details.
Force the use of the 640x480 16-colour mode for the
Force all images to be loaded as 8-bit. Normally zgv will
load 24-bit images (e.g. colour JPEGs) as 24-bit if you have any modes capable
of displaying the image in 15, 16, 24, or 32-bit colour.
Use low-quality colour thumbnail pictures when the file
selector is using 640x480 16-colour mode. Normally zgv uses higher-quality
monochrome thumbnails in this situation.
Don't recall previous cursor position in a directory when
returning to it later. (This mechanism only applies when changing directory
`normally'; jumping directly to another dir with ` G' never does such a
save/restore (see Changing Directory).)
Use `magic number'-type identification to determine which
files should be listed in the file selector. This is more accurate, but very
much slower. See File Type Identification, for a discussion of the
Don't change thumbnail colours when using the file
selector to make the rest of the selector look right. See Thumbnail
`Walk' through the directory when updating thumbnails,
moving the cursor over every single picture whether it needs updating or not.
Normally, zgv completely skips any pictures which don't need updating, which
makes it considerably faster on large directories and/or slow machines.
Reduce the size of the filename text in the selector. You
may find this useful if you think the text is too big, or if you'd like to see
more of the filename without having to press ` :'.
` --fs-start-mode modespec
Specify the video mode zgv should start off using for the
file selector. (The default is 640x480x8 if possible, otherwise 640x480x4.)
The `modespec' should be the width, height, and depth in quotes, e.g. `
"640 480 8"'. See Video Modes, for details of
precisely what this means. The specified depth is actually ignored in this
case, as you can only choose 8-bit modes for the selector.
Thicken the text (filenames etc.) in the file selector
(and elsewhere). (Note that if line-text has been enabled, then
fs-thick-text only has an effect if block-cursor is on as
(Normally enabled, use `--fullscreen=off' to
disable.) This option only applies when using the SDL backend. By default, zgv
generally uses the entire screen for its display. But if you disable this
option, it tries to run in a window when possible (e.g. when running under X).
Note that zgv won't be able to fill the screen in modes it doesn't natively
support, in either case.
` -G val
` --gamma val
Set the gamma adjustment used (see Gamma
Adjustment). This also sets the `initial value' used when resetting the
gamma adjustment. The default is 1.0, i.e. no adjustment.
GNU has POSIXLY_CORRECT for compatibility with
silly POSIX misfeatures, and zgv has...
Display a list of options and a terse description of what
the options do.
When loading a single file from the command-line, ignore
(some) errors. Only meaningful for PNG currently.
` --jpeg-index-style style
Specify how to read JPEGs when creating thumbnails. Style
` 1' is the quickest, but sometimes generates rather fuzzy/blocky
thumbnails; ` 2' is fairly cautious (and the default), but still quite
fast; ` 3' is an extremely cautious and slow method.
` -J type
` --jpeg-speed type
Set JPEG speed/quality tradeoff. Type `1' is slow
but accurate; ` 2' is faster but not as accurate (and the default);
`3' is the fastest but the least accurate.
Draw text by drawing lines rather than using bitmap
fonts. This looks worse but is faster.
Enable mouse support in zgv. /dev/mouse must be
(usually a symlink to) the mouse device. The actual configuration of the mouse
should be done via svgalib's config file libvga.config; see the man
page for that for details.
` --mouse-scale scale
Set the ratio of `mouse pixels' to onscreen pixels. The
larger the number, the slower the mouse moves, and vice versa. (However, the
number must be greater than zero.) If the mouse pointer moves at the wrong
speed for your tastes, play about with this setting and you should be able to
` --pcd-res resnum
Selects the resolution used for Photo-CD files;
1=192x128, 2=384x256, 3=768x512 (default), 4=1536x1024, 5=3072x2048. (This
setting only has an effect if Photo-CD support was enabled at
This one needs some background to fully explain ---
greyscale files are normally displayed in 8-bit modes, which due to VGA's
limited palette means that only 64 greyscales can be shown (zgv normally fakes
extra ones, though; see Increased Greyscales). But for people who work
with greyscale files and have 24/32-bit video modes available this can be
frustrating, as 24/32-bit modes display 256 greyscales. For this reason, using
the ` --pgm-truecol' option enables a special-case hack to read (only)
PGM files as if they were 24-bit. Using a 24/32-bit mode then gives you 256
greyscales. (Be careful to avoid 15/16-bit modes as these will only give 32!
See Drawbacks of 15/16-bit Modes.)
` -r seconds
` --reload-delay seconds
If seconds is positive, then any picture displayed
is re-read and redisplayed (without clearing the screen first) every
seconds seconds. If it's ` 0' (zero), or negative, 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. :-)
Normally, any brightness modification is applied after
applying any contrast. Enabling this reverses the order.
(Normally enabled, use `--revert-orient=off' to
disable.) If disabled, orientation (flip/mirror/rotate) state is retained
(Normally enabled, use `--revert-scale=off' to
disable.) If disabled, scaling is retained between pictures.
(Normally enabled, use `--scrollbar=off' to
disable.) If disabled, don't show a scrollbar below the selector.
Cause zgv to output the x and y offsets, and width and
height of the section of the image being displayed when you exit zgv. Can be
useful for things like ` pnmcut `zgv -s input.ppm` input.ppm >
Print names of tagged files on exit. This can be useful
in constructions something like ` mv `zgv -T` /tmp', which moves to
/tmp only the files you select.
Show any .xvpics directories so that the
thumbnails can be viewed even if the files they referred to no longer exist.
(However, it's usually easier to simply start zgv in the .xvpics
` -S delay
` --slideshow-delay delay
Set time to wait in seconds before loading the next
picture in a slideshow. The default is 4.
Loop in slideshows `forever' (or rather, until you
Randomise picture order in slideshows. Due to the
shuffling approach taken, there will be no repeats or omissions.
Give a dithered colour image in 640x480x4 mode when in
the viewer (see The Viewer 640x480x4 Mode), rather than
` -m modespec
` --viewer-start-mode modespec
Specify the video mode zgv should start off using for the
viewer. The default is generally 640x480x8, but it's actually a bit more
complicated than that (see Default Video Mode). The `modespec' should
be the width, height, and depth in quotes, e.g. ` "640 480
8"'. See Video Modes, for details of precisely what
(Normally enabled, use `--visual=off' to disable.)
If disabled, no thumbnails are shown.
enables vkludge, which smoothes slightly when `zooming' a
big picture down to screen size, and also when in 320x400 and 360x480
Show version number.
Write the file as a PPM to stdout rather than viewing it.
(This only works if you run zgv on a single file, specified on the
command-line.) You're usually better off using a dedicated image-converting
Makes zgv acts a bit more like xzgv, at least in terms of
the keypresses it supports (see xzgv Compatibility).
Enable zoom mode, which resizes the picture to fit the
screen. See Zoom Mode.
When in zoom mode, only reduce pictures to fit;
i.e. make big pictures viewable all-at-once while leaving small picures
If zgv is started with ` zgv file
', zgv auto-loads the file
(bypassing the file selector), and exits when you exit from viewing the
picture. (By the way, this also makes it possible to view single files without
the usual extensions such as .gif
, etc. See File Type
If started with ` zgv file file2 ...
' --- i.e. with more than one
filename --- zgv works in a similar way, except the multiple files are shown
as a slideshow, one after the other. You may want to specify ` -l
that zgv will loop around these pictures until ` Esc
' is pressed, and
the ` -R
' option to shuffle (randomise) the picture order may also be
If started with ` zgv start-dir
', zgv starts up with the usual
file selector, but with the current directory being the one specified.
Settings which are either on or off (boolean) are, as you might expect, enabled
by using e.g. ` -z
' or `--zoom
'. However, there's an alternative
long-option form for setting these, resembling how they're set in config files
--- the syntax is ` --option=state
', where state
' to enable the option, or `
' to disable it. The most useful
thing about this is that it allows you to disable options which were
previously enabled, by using e.g. ` --zoom=off
(Readers used to the way GNU-style long options work should note that, since
this ` on
'/etc. arg is optional, you can't use the `
' form in this case; it must be ` --option=arg
it to work.)
Online help (of a sort) is available in both the file selector and viewer:
Gives online help. This lists some of the most
commonly-used keypresses in the current context.
In the viewer, you can also get a list of which key combinations select which
video modes. See Selecting a Video Mode
Usually, on starting up zgv, you will enter the file selector, which lets you
pick files to view (among other things). This lists the subdirectories and
picture files in the current directory, along with small `thumbnail' versions
of the pictures if they exist.
Exiting zgv can be achieved two ways:
Quit zgv normally.
Quit zgv in a rather immediate and nasty way, by sending
. (This is actually dealt with by svgalib.) You should only use
^C to quit if zgv appears to lock up or takes an unbearably long time to do
(Technically it may not be ` ^C
' which sends SIGINT
, but you would
have to have a strange setup for this to be the case.)
(This section is deliberately early on in the manual, as thumbnails are probably
the most important feature of the file selector, so it's best that you know
how to create/update them sooner rather than later.)
Thumbnails are small versions of the pictures they represent, and are displayed
by the file selector if they exist. zgv uses xv-compatible thumbnails --- if
you create thumbnails with xv they will work with zgv, and vice versa. zgv's
thumbnails are also compatible with the Gimp, and xzgv.
If no thumbnail exists for a file or directory, a small `document' or `folder'
graphic appears instead.
While thumbnails can be made relatively quickly, it's by no means an instant
process. For this reason, thumbnails have to be created in advance, and are
stored as files in their own right in (usually) a subdirectory .xvpics
zgv never creates/updates thumbnails without you telling it to. So, if you enter
a directory where the picture files don't have any thumbnails, or where the
thumbnails seem to be out of date, you should press ` u
Alternatively, you can create/update thumbnails for the current directory and
all subdirectories by using ` Alt-u
'. But be warned that a recursive
update can take some time!
Create thumbnails for any files which don't have them,
and update thumbnails which are older than than the corresponding file. While
this is going on, the text updating index of
prefixes the usual display
of the current directory's name.
You can press ` Esc
' while the update is in progress to abort it; zgv
will stop once it has finished the thumbnail it is currently working on (if
If you switch consoles while the update is in progress, it will continue to run
`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 current thumbnail has been dealt
Create/update thumbnails for all files in the current
directory and all subdirectories --- in other words, do a recursive update.
This can take some time, so you are prompted to confirm that you really want
to do this (see Dialog Boxes). As above, it will continue running `in
the background' if you switch consoles, and you can press ` Esc' to
Create thumbnails for subdirectories. Don't confuse this
with the recursive update; this generates thumbnails for the directories
themselves, not the files within them. (Most people probably won't want
to bother with these, as they're not as helpful as you might think.) These
consist of the first four files in the subdir, squeezed together into a single
thumbnail. There is (currently) no `update' mechanism for subdir thumbnails
--- all of them are newly created each time you press ` d'.
Normally, thumbnails are stored in the subdirectory .xvpics
dir first if needed), with the same name as the filename they represent.
However, there are times when using .xvpics
isn't possible --- for
example, the filesystem may be read-only (such as on a CD), or may not support
name (such as on an msdos
filesystem), or you may
not have permission to write to the directory.
In these situations, zgv stores the thumbnails elsewhere. They go in directories
under the .xvpics
dir in your home directory. The name for the
directory they go in there is the directory name they were found in, but with
slashes (` /
') converted to underscores (` _
An example should make things clearer. Say zgv needs to create a thumbnail for
, in the directory /foo/bar/baz
, but can't use
. It will put the thumbnail in
, creating directories as
Where a thumbnail is stored makes virtually no difference to how zgv works; the
main difference is that the latter, more indirect way of storing thumbnails
means that thumbnails will take slighter longer to display.
The thumbnails used in zgv require 256 colours to display. Unfortunately, the
rest of zgv's file selector needs an additional five colours. Normally this is
dealt with by finding the `closest' thumbnail colours, and (this is the
important part) changing them to the file selector colours. The disturbance to
the thumbnails should be barely noticeable.
(All the same, you can disable this using the config file setting
(see Configuring zgv
). But bear in mind that the
selector will then look rather strange!)
In 16-colour mode (see 16-colour File Selector
), the way it works means
fewer colours are needed, and the file selector's five colours can be (and
are) separate from the thumbnail colours.
The file selector is simply a list of subdirectories and filenames, along with
any thumbnails that exist for them. The list is in asciibetical order (but you
can change this; see Changing the Sorting Order
). Names of
directories are shown (like this), and they are shown in order at the
beginning of the list, before all the picture files. Long filenames are
truncated to fit; three dots indicate where this has happened. (See Other
File Sel Commands
, for how to display the full filename.)
The list is often larger than can fit on the screen at once. If this is the
case, only part is shown at a time, but you can move around the list with the
cursor keys and the like.
The colours used for the file selector can be changed, if you dislike the
defaults (see Configuring zgv
The cursor in zgv is (normally) shown as a `raised' entry in the list. The
cursor has two main functions:
It selects a file for `view', `tag' etc. commands to operate on.
It determines which part of the list is shown, as the part of the list
shown onscreen always contains the cursor.
There are many commands for moving the cursor. In summary, most `special' keys
like the cursors do what you'd imagine they do --- also, a few Emacs-like
keys, a few vi-like keys, and the Sinclair Spectrum-style (!) QAOP keys are
Using a mouse in the file selector is not covered here. See Mouse
Funcs in the File Selector
, for details of what you can do with a
mouse. (Experienced users may wish to consult the Tom & Jerry
Pinky and the Brain
cartoons for further enlightenment on this
` Cursor Up
Move up. Moving up from a topmost entry moves to the
bottom of the previous column.
` Cursor Down
Move down. Moving down from a bottommost entry moves to
the top of the next column.
` Cursor Left
Move left one column.
` Cursor Right
Move right one column.
` Page Up
Move the cursor back (nearly) a page.
` Page Down
Move the cursor forward (nearly) a page.
Move the cursor to the start of the list.
Move the cursor to the end of the list.
Move the cursor to the first filename starting with the
next key pressed, which would generally be a letter or number. Case is
significant; ` a
' and `A
' are different.
If no files start with the specified character, it moves to the first file which
starts with a later char (in asciibetical order). If there are none for which
this is the case, it moves to the last file --- unless there are no files
(just directories), in which case it has no effect.
There are two ways to view files from the file selector. The usual way is to
press ` Enter
' when you've moved the cursor to the file to view.
However, you can also view tagged files as a `slideshow', which is described
later (see Tagging
View a picture file, or if the cursor is on a
subdirectory, make that the current directory. A progress indicator is shown
when reading in a file --- while this is onscreen, you can use ` Esc'
If zgv has a serious problem reading a file, it will give an error. Errors are
shown in boxes which appear in the middle of the screen --- they stay there
until you press ` Enter
' or `Esc
' (if using a mouse, clicking
has the same effect).
zgv also uses similar dialog boxes for other things:
Getting a yes or no answer. ` Enter
' or `y
' picks `yes';
' or `n
' picks no. (Again, you can click on the relevant
button with the mouse to do the same.)
Reading a directory name. Here you should type the directory name then
', or press `Esc
' to abort. In fact, this line-input
dialog allows a certain amount of editing, and so supports these additional
` Cursor Left
Move the cursor left. (An underline character shows the
` Cursor Right
Move the cursor right.
Move the cursor to the start of the line.
Move the cursor to the end of the line.
Toggle insert/overwrite mode. (Insert mode is the
default.) In insert mode, characters you type are inserted at the cursor
position. In overwrite mode, they replace the existing chars.
Delete char to the left of the cursor. (This assumes
`Backspace' really generates a ` DEL', which is the usual setup
on Linux. Note that ` Backspace' is (usually) the key above the main
`Enter' key; it is often labelled simply as an arrow.)
Delete the char the cursor is on.
The file selector is not restricted to working on one file at a time. You can
`tag' as many (or as few) files as you wish, and certain commands described in
this section will act on them.
Initially, all files are untagged, and the filenames appear in black. Tagged
files appear in red. (See Configuring zgv
, if you'd prefer zgv to use
There are several ways to tag or untag files. The ones which work on individual
files also move the cursor forward one place afterwards, to make tagging or
untagging multiple files easier.
As elsewhere in zgv, the case of the keys is significant --- the ` t
(unshifted ` t
') command has quite a different effect to that of `
' (shifted ` t
There is also a command available in the viewer to tag the currently-viewed
file. See Changing Picture
, for details.
Untag file. Note that this is `n' (for `no tag',
er, or something like that); ` u' would be more logical, but that is
used for updating thumbnails.
Tag all files.
Untag all files. This is on `N' rather than
`U' for consistency.
Toggle the tag status of the file --- if it's tagged,
untag it; if it's untagged, tag it.
To see how many files are tagged, use ` Alt-f
' (see Other File Sel
A `slideshow' lets you view all the tagged files in the current directory one
after the other, or in a randomised order if `shuffling' is enabled (see
File Selector Toggles
View the tagged files as a slideshow. (`Tab' is
usually the key above ` Caps Lock', which is often labelled with two
Each file is shown for a certain amount of time, normally 4 seconds. (See
, if you find this too short or long.) After the time runs out,
the next file is shown. You can cut this delay short by hand using one of the
viewer's change-picture commands such as ` Space
' (see Changing
), or abort the slideshow prematurely by pressing ` Esc
You can also pause a slideshow so that you remain on the current file until
you unpause it (see Pausing Slideshows
Normally, once each file has been shown the slideshow ends, and you are returned
to the file selector. But if looping is enabled, the slideshow repeats until
you press ` Esc
' (see File Selector Toggles
You can copy or move tagged files to a directory you specify, or delete all
tagged files. If no files are tagged, zgv copies/moves/deletes the file the
cursor is currently on --- unless the cursor is on a subdirectory, in which
case it gives an error.
Note that the commands given here are uppercase --- lowercase ` c
', and ` d
' do not do the same thing.
Copy tagged files (or the current file) to a given
directory. zgv asks for the destination directory using a dialog (see
Dialog Boxes) and copies the files there. If it comes to copy a file
but there is an existing file in the dir with the same name, the file is not
copied and nor are any of the remaining files.
Move tagged files (or the current file) similarly.
Delete tagged files (or the current file) similarly. In
this case, there's obviously no need to specify any directory :-) but you're
prompted before deletion starts (unless this is disabled, see Configuring
zgv). It also deletes thumbnails, for those files which have them.
As well as copying/moving files, you can rename them:
Rename the current file or directory --- zgv will refuse
to overwrite any existing files/directories. The new name must remain in the
current directory. (See Copying/Moving/Deleting Files, for how to move
a file to a different directory (albeit keeping the same name).)
It's better to use ` R
' than `Alt-r
'; the latter never made much
sense, and is likely to be removed before long.
The easiest way to change the current directory in zgv is usually to select a
directory entry in the file list and press ` Enter
'. (Selecting `
' moves to the parent directory of the current one.)
There is an alternative though:
(Note that this command is shift-` g
', not `g
Go to a specified directory. zgv asks for the destination
directory using a dialog box which you should type the dir's name into (see
), and moves to that directory if it exists.
If the directory turns out to be unreadable --- i.e. you do not have permission
to read it --- zgv resorts to going to your home directory. (This is actually
a general mechanism in zgv, but this command is the most likely trigger of
it.) If that in turn is unreadable, zgv gives up in disgust and exits.
Normally, the files are listed in asciibetical order by name. However, you can
instead have the file list sorted by size, last-modified date/time, or by
`extension' (the file type).
(Only the order of files can be altered; directories are always listed first,
and always in name order.)
Sort by name. This is the default.
Sort by size. The biggest files are listed last.
Sort by last-modified date/time. The newest files are
Sort by extension.
Various aspects of the file selector's behaviour can be configured while zgv is
running, by using these toggle commands (which enable the feature if it was
previously disabled, and vice versa).
These settings can also be altered using command-line options (see
) and/or config file settings (see Configuring
Toggle display of thumbnails (default is on). The
without-thumbnails display can sometimes be useful for navigating around large
directories (many filenames are shown onscreen at once), and it is of course
Toggle scrollbar on/off (default is on). The scrollbar
shows which part and which proportion of the list is currently being shown
onscreen, and when mouse support is enabled can be used to move around the
Toggle shuffling (randomising) of slideshows. See
Toggle looping in slideshows. See
Toggle use of `magic numbers' (identifiers at the start
of a file) to pick which files in a directory to list in the selector. The
usual method of doing this is based on the file's extension (see File
Type Identification, which is much faster but won't catch e.g.
files without extensions.
If the file selector is running in 16-colour mode (it
usually doesn't unless zgv has no choice --- see 16-colour File
Selector), toggle between greyscale (default) and colour thumbnails.
There are some other commands in the file selector which don't easily fit
anywhere else. Here they are:
Delete (only) the file the cursor is on. Asks for
confirmation (unless this is disabled, see Configuring zgv). It also
deletes the file's thumbnail, if it has one. See Copying/Moving/Deleting
Files, for a more general command which deletes all tagged files.
Show various details about the file the cursor is on; the
(full) filename, the size in kilobytes, width/height if recorded in any
thumbnail, last-modified date, etc. You can also use the ` ;' key to
Show the number of (picture) files in the current
directory, and the number of tagged files (see Tagging).
Rescan the directory contents, and redraw the
Kill mouse --- disable mouse for the rest of this zgv
session. (It prompts to check if you really want to do so.) This can be useful
if you have the mouse enabled in a config file, so that zgv always starts up
with the mouse on, but you're currently using just the keyboard. In such a
situation the mouse pointer can be a bit annoying. This command lets you
disable the mouse completely for the current zgv process.
The file selector normally runs at a relatively low resolution (640x480),
meaning it can only show 20 thumbnails at once. This keeps the selector
running at a reasonable speed even on slow machines.
If you have a faster machine, however, and your video card has 256-colour modes
with higher resolutions than 640x480 (see Video Modes
), you may
want to see more thumbnails onscreen at once.
(zgv tends not to look as `right' in such modes as it does in the usual 640x480,
but apart from that it's much the same.)
Select 640x480 mode. This is the default.
Select 800x600 mode.
Select 1024x768 mode.
Select 1280x1024 mode.
If you want to change the default mode used in the file selector, use the
config file setting (see Configuring zgv
example, to use 800x600 by default, you'd use fs-start-mode 800 600
Note these modes are subject to the same checks as in the viewer --- in
particular, this means that the file selector obeys the viewer's
, etc. settings. See Config
Finally, if you have no 640x480 256-colour mode, or if force-fs-16col
been set, the 640x480 16-colour mode is all that is available.
The file selector normally operates in a 256-colour mode (by default, the
640x480 one). However, the original VGA cards didn't have this mode, and SVGA
cards not supported by svgalib won't have it as far as zgv is concerned
For such cards, zgv supports a more limited and slower file selector which works
in 640x480 16-colour mode. It should be easy to tell which zgv is using --- if
thumbnails appear in monochrome rather than colour (and the files are colour
pictures ;-)) then it's running in 16-colour mode. (Another hint is that
16-colour mode has an extra border around the edge of the screen which
256-colour mode probably won't have.)
As you might imagine, having 240 fewer colours makes things difficult. The
default way of coping with this is the greyscale thumbnails (eleven grey
levels are used), which are reasonably fast and quite faithful to the
originals. If you'd prefer less accurate --- but colour --- thumbnails (eight
colours are used, with dithering and increased contrast), you can press `
' to toggle between the two, or set zgv up to default to using colour
thumbnails instead with fs-16col-colour-thumbnails on
in a config file
(see Configuring zgv
(For those of you out there who have a 640x480 256-colour mode, but feel you're
missing out by not seeing this 16-colour file selector :-), you can force zgv
to use it by using the --force-fs-16col
When a picture is being shown onscreen, you're in the viewer. This section
describes what you can do while viewing the picture.
Exiting the viewer is simple:
Exit the viewer.
If you got to the viewer from the file selector, you're returned there; if you
bypassed the file selector (by running zgv with a file (or files) to view
specified on the command-line --- see Options
) then exiting the viewer
also exits zgv.
A picture may well be too large to fit entirely on the screen. There are two
general ways to see the whole of the picture, and in addition to those, you
may be able to fit more on by choosing a different video mode (see Video
), either manually or by using auto-mode-fit.
(For multi-resolution Photo-CD files, there is yet another alternative approach
(see Supported File Formats
Scrolling is the default approach to handling big pictures in zgv. When the
viewer is started up, the top-left of the picture is shown --- you can use the
cursor keys (and many others) to move around the rest of the picture.
` Cursor Up
Move up 100 pixels. `k' and `q' move up 10
` Cursor Down
Move down 100 pixels. `j' and `a' move down
` Cursor Left
Move left 100 pixels. `h' and `o' move left
` Cursor Right
Move right 100 pixels. `l' and `p' move
right 10 pixels.
` Page Up
Move up (nearly) a screenful. (It moves 90% of the screen
` Page Down
Move down (nearly) a screenful.
Move left (nearly) a screenful. (It moves 90% of the
Move right (nearly) a screenful.
Move to the top-left of the picture.
Move to the bottom-right of the picture.
An alternative way of viewing the whole picture, one which lets you see the
picture onscreen all at once no matter how big (or small) it is, is zoom mode.
Zoom mode's name derives from the idea of `zooming' a small file up to fit the
screen. But in reality, it is more often used to reduce a large file to fit
Zoom mode is not the default, and has to be enabled. Once enabled, it stays on
until you turn it off again.
By default, the way zoom mode reduces a file to fit the screen is (relatively)
quick but harsh, and may make the picture look ugly. Enabling vkludge
smoothes the picture, giving a better and more accurate result, but takes
longer. It too is not the default, but stays on until turned off again.
Toggle zoom mode.
When in zoom mode, only reduce pictures to fit.
This can be useful when going through a lot of unpredictably-sized pictures,
as it means that you can see all of a big picture easily without also meaning
that tiny little icons assume a scale of Biblical proportions. :-)
Toggle vkludge, which enables appropriate
smoothing when zoom mode is reducing a picture to fit the screen. It also
enables similar smoothing for non-zoomed pictures in 320x400x8 and 360x480x8
modes. See Virtual Modes.
Resume `normal' display --- disables zoom mode (and
If it seems strange to you to use scrolling or zoom mode to see the whole
picture when you could just use a different video mode (to change the size of
the pixels displayed onscreen), you may find auto-mode-fit useful.
If enabled, and when a picture is loaded, the current mode is automatically
switched to the `smallest' mode which is both wider and taller than the
picture is (or of equal width/height). In other words, the (theoretically)
most appropriate mode. If no mode can fit the picture onscreen, the `largest'
mode is chosen.
Auto-mode-fit is not the default, so you have to enable it if you want to use
Toggle auto-mode-fit mode. Usually this only takes effect
when a picture is loaded (so that manual mode switching still works), but when
you enable it zgv does a one-off auto-mode-fit on the current picture. (Note
also that disabling it leaves you in the current mode, so that has no obvious
effect; for this reason, the picture is redrawn (as a visual cue that you
haven't just been ignored :-)).)
I should point out that all the mode-switching can be a bit hard on your
monitor, so even if you really like this option you might not want to enable
it all the time (e.g. in a config file), but instead only turn it on when you
`need' it. Still, it's up to you.
Certain modes are excluded from those chosen by auto-mode-fit. In particular, no
320x200 mode is ever chosen, nor is 320x400x8. These exceptions are made due
to the unusual aspect ratio. 640x480x4 is excluded due to the slightly odd way
it works, which makes it ill-suited to automatic selection. 360x480x8
considered, despite the aspect ratio, if no 640x480x8 mode exists.
You can scale a picture --- this makes it appear larger onscreen. zgv acts
exactly as if the scaled-up picture were the real picture; for example, the
cursors scroll around in steps of 100 scaled-up pixels, even if this means
moving a fraction of a pixel in the original picture.
The main limitation of scaling is that you can only scale up by integer values,
so you can only make each pixel in the image twice as wide/high, or three
times as wide/high, or four times, and so on.
(It may seem odd saying e.g. `twice as wide/high' rather than `twice the size',
but technically `twice the size' would be referring to scaling up the width
(and height) by about 1.414...)
Normally, zgv does no scaling, which could be considered a ratio of 1:1. Scaling
up increases that ratio. How it is increased depends on which key you use:
Increase the ratio by adding one --- this leads to ratios
of 2:1, 3:1, 4:1...
Increase the ratio by doubling it --- leads to ratios of
2:1, 4:1, 8:1...
Usually ` d
' is more useful.
There are similar commands to decrease the ratio (when it reaches 1:1 scaling is
Decrease the ratio by subtracting one.
Decrease the ratio by halving it.
The scaling ratio is never decreased below 1:1. It is also never increased
beyond 512:1, where zgv stops so that pixels may be conserved for future
You can undo the effect of scaling at any time by using ` n
' (which also
disables zoom mode).
Normally, scaling works by simply making the pixels into larger and larger
squares (in effect), which remain the same colour. However, if you are using a
15/16/24/32-bit mode (see Video Modes
), you can enable a feature called
`interpolation' which smoothly graduates the colour change between the
top-left corners of each pixel. This is very
slow, but looks nice.
Toggle interpolation in scaling mode.
Toggle off-by-one interpolation (disabled by default).
Using this off-by-one method gives incorrect results, but this can
occasionally be useful at ratios of 2:1 and 3:1 for relatively low-quality
(If you like the appearance of scaling with interpolation, you may also be
interested in a program I wrote called pnminterp
, which can scale up a
PGM or PPM file while applying this effect.)
Sometimes when viewing a picture you will want to flip it horizontally or
vertically, or rotate it:
`Mirror' the picture (flip it horizontally).
`Flip' the picture (flip it vertically).
Rotate the picture 90 degrees clockwise.
Rotate the picture 90 degrees anti-clockwise. (This is a
little slower as it works by effectively doing ` r' then `f'
then ` m'.)
Restore the picture orientation to normal. This undoes
the effect of any mirrors, flips, and/or rotations.
zgv normally reverts the picture orientation (the way the picture has been
transformed by mirror/flip/rotate) back to normal when you view a new picture.
However, there are various ways you can retain the orientation between
pictures, so that the new picture is mirrored, flipped, and/or rotated in the
same way. Here are two of the ways:
Re-use the previous picture's orientation for this
Save the current picture orientation, making all pictures
viewed until you press ` Esc' use it. (The orientation reverts to
normal after that, though.)
Finally, you can choose to have the orientation preserved the whole time. To do
this, put revert-orient off
in a config file (see Configuring
zgv provides support for changing brightness and contrast in all modes, though
it does slow things down a little in 15/16/24/32-bit modes (see Video
Reset contrast and brightness to normal. (`*' is
also supported, for hysterical raisins.)
Any contrast change is applied before any brightness change by default. However,
you can reverse the order easily enough:
Reverse the order in which brightness and contrast are
The order they're applied in does make a difference --- assuming you've modified
both brightness and contrast, of course. :-) The normal order simply means you
have a increased-contrast image which you change the brightness of. Obviously
then, the reverse order reverses this, but it has the additional effect of
changing the point around which contrast is applied.
Ah yes, gamma. What fun. The basic problem is this --- differing displays have
differing intensity response curves. ``This has made a lot of people very
angry and been widely regarded as a bad move.'' :-)
It means that you need some way of adjusting how brightly you display the
picture to compensate. But since we're dealing with response curves, this
isn't just a matter of changing the brightness in a linear fashion.
That doesn't seem so hard to deal with, right? All you need is to get the gamma
(a number which specifies how much the curve bends) for the image, and for the
screen, divide one by the other and adjust as appropriate. Joy.
But, given that the problem has existed since we started displaying more than
eight colours, you won't be surprised to find that it's already been fixed.
And the fixes all tend to clash, and everybody has a different notion of how
to fix it. The usual `fix' is to assume that whoever made the image made it
with a gamma matching the gamma of your display, so you can just stuff the
bits right on the screen. Since this is easy, it's the most widespread
approach. But it's a bit stupid, so not everyone does it. Combine that with
the lack of gamma specification in most image formats, and the often-bogus
values specified by people in those that do, and hey presto --- the image
gamma could be just about anything. And the screen's gamma also tends not to
be easily determined.
So how on earth do you deal with something like that
in a remotely sane
The answer chosen in zgv is to just live with the fact that the probability of
automatically obtaining correct values for both the screen and image gamma is
basically zero. Once you accept that, the sensible thing to do is to make it
easy and fast to change gamma adjustment to commonly-required
values. So here's how to do it:
Set gamma adjustment to 1.0, i.e. no adjustment. This is
the default setting.
Set gamma adjustment to 2.2. This is useful for viewing
linear-gamma files (one classic example being raytracer output) on an average
Set gamma adjustment to 1 divided by 2.2, i.e. roughly
0.45. This is useful for the reverse --- viewing average-PC-monitor-gamma
files on a linear-gamma display. Historically I believe the classic example
would have been viewing PC files on a Mac, but I don't know how true that is
Set gamma adjustment to its initial value, as specified
by a ` -G' command-line option (see Options) or gamma
config file setting (see Configuring zgv). The default value used if
none was specified is 1.0.
A brief clarification is probably in order. The gamma adjustment value which you
set in zgv is actually inverted from (i.e. one divided by) the true adjustment
value used. This is (believe it or not :-)) intended to avoid confusion by
reflecting the fact that screen
gamma is the one most widely
You can also tweak the adjustment more precisely, in a similar way to
Decrease gamma adjustment (divide it by 1.05).
Increase gamma adjustment (multiply it by 1.05).
Note that ` ;
', and the other keys which reset the brightness/contrast,
deliberately avoid resetting the gamma adjustment.
zgv normally displays greyscale pictures in 8-bit modes (see Video
). Due to a limitation of the original VGA cards, these can have a
maximum of 64 greyscales. This can give noticeable `edges' in some pictures.
So when using 8-bit video modes, zgv uses some trickery to try and increase the
apparent colour depth a little. 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. (It can get less convincing if you scale
up the picture, but it usually looks reasonable even then.)
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
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).
You can toggle this feature in the viewer:
Toggle whether to fake some extra greyscales/colours in
To disable it by default, put fake-cols off
in a config file (see
While in the viewer, it's possible to go directly to the previous or next file
in the directory without having to exit to the file selector and pick the
relevant file by hand.
There are two ways to do this; one way leaves the old picture onscreen until the
new one is read in, the other (on ` ^P
' and `^N
returns to the file selector and shows the usual progress indicator while it's
In addition, one of the next-file-in-dir commands lets you tag the file
currently being viewed first, without having to return to the file selector to
Note that the meanings of the commands change when you are viewing a slideshow;
the details are covered below.
(See Dialog Boxes
, to see what `Backspace
' is being used to mean
View previous file in dir, without progress indicator.
(In slideshow, move to next file without waiting.)
View next file in dir, without progress indicator. (In
slideshow, move to next file without waiting.)
Tag current file, then view next file in dir, without
progress indicator. (In slideshow, move to next file without waiting; it has
no tagging effect during a slideshow.)
View previous file in dir, with progress indicator. (In
slideshow, acts like ` Esc'.)
View next file in dir, with progress indicator. (In
slideshow, acts like ` Esc'.)
Note that ` Space
' tags the file, rather than toggling the tag status as
it does in the file selector. This mismatch is unfortunate, but in the viewer
context the always-tag function is more likely to be what you'd want, since
you can't see the file selector to see which files are tagged.
While you can get file details when in the file selector, you can't always get
to the selector --- for example, you might be running zgv on a single image
from the command-line, or using it in that way from another program (such as
lynx). So zgv can also report file details when in the viewer:
Show file details, including such things as the filename,
size, and width/height. This is almost identical to the equivalent command in
the selector (see Other File Sel Commands); the only difference is that
you can't use ` ;' to get this in the viewer, and the viewer doesn't
depend on thumbnails for the width/height info.
Sometimes you may want to temporarily stop a slideshow, when you get to an
interesting image. You can do this the same way you would temporarily stop
Pause slideshow, leaving you on the current image until
you resume. You can still abort early with ` Esc', go to the next image
with ` Enter', or in fact use any viewer commands at all.
Resume slideshow. If the timer has already run out (it
keeps running while paused), this will go straight to the next image without
any further delay, other than that needed to read the new picture.
The analogy with XON/XOFF isn't really that close --- for example, it's worth
noting that when the slideshow is `paused', you can actually do anything you
normally might in the viewer.
While zgv is for the most part a straightforward viewer, it has special support
for multiple-image animated GIF files. These are loaded as a `column' of
images, one on top of the other --- this column is the single image which is
then displayed, enabling you to see all the `frames' of the GIF. (Though not
in an image thumbnail; in those, only the first image is shown.)
You can also switch to an `animation' mode in the viewer, where each `frame' is
shown one after the other, with (roughly) the delay specified in the GIF
(This animation mode is automatically enabled if you start zgv with the `
' or ` --auto-animate
' command-line option. See
Enter animation mode. (I don't know what the `e'
stands for either. :-)) In this mode the normal viewer keys have no effect,
and instead, a more limited set of keys are supported:
Stop the animation and return to the viewer. If
auto-animation mode is enabled, it exits the viewer too.
Pause (or unpause) the animation.
Skip to the next frame. Generally only useful when
If auto-animation is enabled, the ` Backspace
', and `
' keys do the same as they do in the normal viewer (see
). Otherwise they act the same as ` Esc
zgv can display pictures in a wide variety of different video modes. While you
can kind of get by in zgv without knowing anything about video modes, they
have a very direct impact on how the picture appears, and it's important to
know why to understand just how zgv works and how best to use zgv.
A video mode is essentially a certain way of displaying dots on the screen. The
important aspects of a video mode in zgv are the number of dots (or `pixels')
that can be shown horizontally and vertically in the mode, and the number of
colours that the mode can handle simultaneously (also called the `depth' of
In fact, this is how a video mode is usually referred to. One might talk of a
640x480 256-colour mode, for example; This would have 640 pixels from left to
right, and 480 from top to bottom, with no more than 256 colours on the screen
A variant notation width
is often used by zgv
and this documentation. But here the `depth' is given in bits. This usage,
while compact, probably makes more sense to programmers than to anyone else.
Here's a list showing which `bit depths' match which number of colours:
(These are the only bit depths relevant to zgv.)
4-bit means 16 colours.
8-bit means 256 colours.
15-bit means 32768 colours.
16-bit means 65536 colours.
24-bit means 16777216 colours (over 16 million).
32-bit means 16777216 colours too (!), since only 24 of the 32 bits are
used for display purposes.
From the number of colours available in the latter modes, you can see why a bit
depth notation is so useful!
So, in the width
notation, our 640x480
256-colour mode would be 640x480x8, a 16-colour mode of the same size would be
640x480x4, and an equivalent `true-colour' (24-bit) mode would be 640x480x24.
Whenever you see a mode referred to as x
in zgv or in
this documentation, it is always
specifying a video mode in this
The obvious implication of differing video modes is that modes with more pixels
horizontally and vertically will have smaller pixels, and so be able to show
more of large pictures. The reverse (bigger pixels, making small pictures
appear large) is not as important a consideration, as zgv can achieve much the
same effect with scaling (see Scaling
). Using video modes to do it is
faster, but usually less convenient.
A more subtle, but much more important, implication of differing modes is
related to the colour depth. More precisely, it's due to the differing ways
the actual colours shown onscreen are obtained. In 15, 16, and 24/32-bit
modes, the colour is specified `directly'; in 8-bit modes, a pixel's `colour'
is really a number which selects one of 256 different colours to show. The
overhead of translating from 8-bit to 15/16/24/32-bit is relatively minor, but
in the 15/16/24/32-bit to 8-bit direction, it's considerable.
For this reason, and since converting from 24-bit to 15/16/32-bit is very easy,
when zgv reads a picture it stores it in memory in one of two internal formats
--- either as 8-bit, or as 24-bit. See File Format Depths
discussion on which format zgv uses for which files.
But what difference does all this make when you're using zgv? Well, here's the
A file loaded as 8-bit can only ever display in 8-bit modes. Trying to
choose a 15/16/24/32-bit mode will have no effect.
A file loaded as 24-bit will only display in 15/16/24/32-bit modes,
unless you have no
15/16/24/32-bit modes, in which case it will be
dithered when it is read in. (But the config file setting
can be enabled to force the dithering behaviour. See
zgv normally remembers the last mode you switched to (the initial mode
is usually 640x480x8), and keeps using that until you specify another to use.
However, it will automatically choose the most similar 15/16/24/32-bit mode
for a 24-bit file if the last mode was 8-bit, and vice versa.
Confused? Head hurting? Don't worry, it happens to the best of us. Especially
where zgv is concerned. :-) Just play around with zgv for a while, and come
back to this later on. It may make more sense after you've got a feel for
what's going on.
zgv using the last mode you selected is all very well, but that doesn't explain
what happens if you've not chosen one. What happens is that it uses the
default video mode.
The default mode is (unless you change it) the 640x480x8 mode. If this is not
available or has been disabled, zgv defaults to 360x480x8 --- if this in turn
is not available or has been disabled, it uses 320x200x8.
There are many different video modes supported by svgalib, and zgv lets you use
most of them. To do so, it reserves many different keys for selecting video
modes. These largely fall into four groups:
The original VGA modes. These are on the number keys for historical
reasons. (The reason being, the number keys exactly matched the mode numbers
used by the old VGAlib.)
The first group of SVGA modes. These are on the function keys `
' to ` F10
'. These are generally the first modes to try, if
you have them.
The second group of SVGA modes. These are on the shifted function keys,
here represented as ` SF1
', and so on. (The first two of
these are also available on ` F11
' and `F12
'.) Not all of the
shifted function keys are currently used by zgv.
The third group of SVGA modes. These are again on unshifted function
keys, but you must press ` Tab
' before pressing the function key ---
i.e. press ` Tab
', let go, then press the function key. These are shown
below as ` Tab-F1
There are also the ` [
' and `]
' keys, which select the next
smaller/bigger mode. These are especially useful if you don't happen to have a
spare lifetime in which to learn the `normal' mode-selecting keys. :-)
So, here's the list of mode-related commands:
List which key combination selects which video
Select the next smaller (lower-res) mode.
Select the next bigger (higher-res) mode. Both these
mode-changing keys have the limits on modes selected that auto-mode-fit has
Select 640x480x4 mode. This emulates an 8-bit mode. See
The Viewer 640x480x4 Mode.
Select 320x200x8 mode.
Select 320x240x8 mode.
Select 320x240x24 mode. (`^' is often on
Select 320x400x8 mode. This emulates a 640x400 mode. See
Select 360x480x8 mode. This emulates a 720x480 mode. See
Select 640x480x8 mode.
Select 800x600x8 mode.
Select 1024x768x8 mode.
Select 1280x1024x8 mode.
Select 320x200x15 mode.
Select 320x200x16 mode.
Select 320x200x24 mode.
Select 640x480x15 mode.
Select 640x480x16 mode.
Select 640x480x24 mode.
Select 800x600x15 mode.
Select 800x600x16 mode.
Select 800x600x24 mode.
Select 1024x768x15 mode.
Select 1024x768x16 mode.
Select 1024x768x24 mode.
Select 1280x1024x15 mode.
Select 1280x1024x16 mode.
Select 1280x1024x24 mode.
Select 1152x864x8 mode.
Select 1152x864x15 mode.
Select 1152x864x16 mode.
Select 1152x864x24 mode.
Select 1600x1200x8 mode.
Select 1600x1200x15 mode.
Select 1600x1200x16 mode.
Select 1600x1200x24 mode.
Normally, each pixel in the image is written more-or-less directly to the screen
from zgv's internal copy of the picture (unless zoom mode and/or scaling have
been enabled). However, there are three modes where zgv does things
differently to make the modes more useful.
(These are mainly intended for users with only the original VGA modes
The original VGA hardware only had one `official' 256-colour mode, the 320x200
one. But it could be reprogrammed to allow other useful modes (known as
`mode-X' modes) --- the ones svgalib provides are 320x240, 320x400, and
These modes are available on all VGA cards. However, it's possible (perhaps even
likely?) that some non-CRT displays may not be able to cope with them. All
monitors should, though, even ordinary VGA monitors.
Now, while 320x240 is a nice sensible mode and can be used directly, 320x400 and
360x480 have very wide pixels. To deal with this, in these latter modes zgv
maps every two pixels horizontally to one pixel onscreen. (Hence `virtual
modes' --- physically they are 320x400 and 360x480, but in zgv they are
virtual 640x400 and 720x480 modes.) This means that you still get a reasonable
aspect ratio, one similar to (though not quite the same as) most other modes.
This raises the question of how this mapping is done. The normal approach is the
quickest, but is very crude --- zgv simply uses the leftmost pixel of the two,
and completely ignores the rightmost one. But if vkludge
enabled (see Zoom Mode
), zgv will average the pixels' colours together
and use the closest match available in the picture's palette. This usually
gives a better result, but is considerably slower.
As well as the non-standard VGA modes, zgv allows you to use the 640x480x4
(16-colour) VGA mode as if it were an 8-bit mode. (Pressing ` 0
selects this mode.) As with the file selector's 16-colour mode, it can work
either in greyscale (the default) or in colour.
If in 640x480x4 mode, toggle between greyscale and
In greyscale mode, the picture is displayed using 16 greyscale levels dithered
to give the appearance of 61. In colour mode, the picture is dithered to eight
colours. (It's difficult to use all 16 colours effectively for a colour dither
without slowing things down.)
The greyscale uses an ordered (pattern-based) dither. The colour uses ordered
dithering by default too, which is fast but pretty rough. If you'd prefer to
sacrifice speed for better dithering, you can switch to error-diffused
dithering by putting `dither-16col-fast' in a config file (see Config
), or you can toggle the setting interactively:
If in 640x480x4 mode and using colour dithering, toggle
between ordered and error-diffused dither.
All the features which work in 8-bit modes work in the 4-bit mode.
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 drawbacks to using
them. Firstly, the image is converted to the 2-byte-per-pixel format as it is
drawn (see Video Mode Issues
, for the reason why zgv works this way);
and secondly, 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, there are fewer colours to choose from.
A good way to illustrate this point is by considering the number of greyscales
each mode can display. In a 256-colour video mode, only 64 greys can be shown,
since an 18-bit palette is used --- 2^(18/3) = 64. But with a 15-bit video
mode, even fewer can be shown --- 2^(15/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 too can only show 32 greys. Put
another way, 2^int(16/3) = 32. (Of course, 24/32-bit modes will show all 256
One way to gain some illusion of extra colours in these modes is to use
dithering, based on the colour detail ``below'' the level which can be shown
Toggle whether to use dithering in 15/16-bit modes. This
makes picture display considerably slower when used.
To enable this by default, put dither-hicol on
in a config file (see
One oddity in mode-land is the 32-bit mode. Like 24-bit modes, 32-bit modes can
display over 16 million colours. But there are no obvious advantages to using
32-bit modes, at least as far as zgv is concerned. So why does it support
Simply put, some SVGA hardware provides 32-bit modes without providing
equivalent 24-bit ones. Hence zgv's support for them.
That should also explain why zgv treats them the way it does. Here's how it all
When using zgv, you don't select a 32-bit mode directly. Instead, you
select a 24-bit mode --- and if no matching 24-bit mode exists, but a matching
32-bit one does
, zgv sneakily uses the 32-bit one behind your back. :-)
zgv's `choose most similar mode' code prefers 24-bit modes to 32-bit
ones, but similarly, if it has the 32-bit mode without the 24-bit one, it'll
take the smoke-and-mirrors route.
As an exception to the overall rule, when specifying modes on the
command-line or in the config file, you do
need to explicitly specify a
32-bit mode in order to get one.
For the most part you needn't worry about 32-bit modes, though; you can just
ignore them and think in terms of 8/15/16/24-bit modes and you'll be ok.
In some situations you might want to disable certain video modes. For example,
perhaps your video card supports modes which your monitor cannot display;
clearly you would want to disable these, as zgv only knows about your video
(To be fair though, if you have svgalib configured correctly for your monitor,
this should never be a problem. See the libvga.config(5)
man page for
To disable video modes, you should give appropriate mode-bad
entries in a
config file (preferably /usr/local/etc/zgv.conf
for such system-wide
configuration). See Config Variables
, for details.
You could also do mode-all-bad
then enable a few modes with
entries --- but most cards support so many video modes that
approach is usually the right one.
You may well want to skip this section if you don't use xzgv.
Some time after first writing zgv, I decided to do a port/rewrite for X, called
`xzgv'. Since I started this about six years after originally writing zgv,
it's understandable that I chose to do some things slightly differently. :-)
The main difference, other than the obvious difference in appearance, is that a
few of the keys used differ. This can be a pain if you primarily use xzgv, but
use zgv every so often (or vice versa). To avoid this problem, zgv supports an
`xzgv-keys' mode, enabled by putting xzgv-keys on
in a config file (see
). This enables an overriding routine which interprets
xzgv-like keys to `native' zgv ones --- in practice, the effect is of some
xzgv keys being added, overriding any conflicting zgv ones.
So, if you enable xzgv-keys, there are these differences in/additions to the
View a picture file, or if the cursor is on a
subdirectory, make that the current directory. (Like the native `
Enter', which still works.)
` Alt -
(i.e. Alt-minus) Untag all files.
` Alt =
(i.e. Alt-equals) Tag all files.
Note that there is no replacement for the usual zgv meaning of ` Space
that is, in xzgv-keys mode, there is (currently) no key which lets you toggle
a file's tag state. (This will change if/when I add such a key to xzgv. :-))
In the viewer, there are these changes:
View previous file in dir.
View next file in dir.
Tag current file, then view next file in dir.
(In short, ` b
' act like the native `
'. The same mappings also apply
when animating a multiple-image GIF file (see Multiple-image GIF
Exit viewer (i.e. `close file').
Restore the picture orientation to normal. This undoes
the effect of any mirrors, flips, and/or rotations. (Like the native `
There are some omissions in the viewer's xzgv-ish keys:
The ` Ctrl
' + cursor-key alternatives to `
' don't exist, as these can't be
distinguished from `normal' cursors given the way zgv reads keys.
The alternative ` Shift
' + cursor-key means of paging
up/down/left/right is similarly missing.
Supporting ` Ctrl-q
' would have got in the way of slideshow
pausing, so I decided against it, and omitted ` q
' from the viewer for
some sort of consistency.
Supporting ` Tab
' would break selecting some video modes, and
probably would have seemed a bit surreal in zgv anyway. :-)
That about wraps it up for the keys... but, of course, there are
One is the way zgv has `flat' mouse menus for the selector/viewer, while xzgv
has hierarchical ones. That would be nice to replicate, but I don't think I'm
A more dramatic difference (IMHO) is the way moving around the picture with the
mouse works. In zgv, you move the screen around `over' the picture, with a
fixed amount of mouse movement needed to cover any picture size. In xzgv, you
move the picture around `under' the window, with the mouse movement needed
being proportional to the picture size (this follows from the picture directly
mimicking the mouse pointer's movement). The most obvious problem here is that
moving the mouse right on zgv is like pressing cursor-right, while doing the
same in xzgv is like pressing cursor-left. Now, I may
eventually add an
option to reverse zgv's reaction to mouse movement, but `fixing' the
non-proportionality without a pointer onscreen might seem awfully strange.
Hmm. An interesting problem to tackle at some point, I suppose. :-)
Picture files are stored in a variety of different forms. These forms are
usually called `file formats'. zgv supports several.
The format a file is in is identified in two different ways. The file selector
(by default) picks filenames to display based on the `extension' --- for
instance, if a filename ends in .jpg
, zgv assumes it is
a JPEG. This way of working is not always right, but it's much faster than the
alternative (reading part of every single file) and is usually sufficient. (If
it's not, you can enable slower `magic number'-based identification with `
' (see File Selector Toggles
The file-reading code uses the format's `magic number' to determine file type
--- e.g. a JPEG/JFIF file starts with the (hex) bytes ` FF D8
'. So if
you start zgv with zgv foo
, and foo is in a format supported by zgv
(such as JPEG), the format will be figured out and the file loaded even though
the `extension' is absent.
zgv supports the following file formats:
GIF. Multiple-image GIFs are treated specially (see
Multiple-image GIF Animation
PBM/PGM/PPM, collectively known as `PNM'. This is a nice simple format
used by pbmplus and netpbm.
mrf. Mrf files can be converted to/from PBM with mrftopbm/pbmtomrf, and
the format is documented in the mrf(5)
PRF. PRF is an extension of mrf, similarly converted with
prftopnm/pnmtoprf, and documented in the prf(5)
XBM (X bitmap files).
XPM. zgv reads the file /usr/X11R6/lib/X11/rgb.txt
to look up X
colour names. (The location of the file is a compile-time option; you can edit
to change it.)
Photo-CD. This is only supported if ` PCD_SUPPORT
' was defined
at compile-time; by default, PCD support is omitted. PCD files contain
multiple image resolutions --- to choose which to view, use ` Alt-1
(lowest) to ` Alt-5
' (highest) in the viewer.
Xv format thumbnail files. Normally you won't want to view these other
than in the file selector, but zgv lets you view them as normal picture files
if you want. Note that in the file selector, thumbnail files are
indistinguishable from the files they represent (other than the .xvpics
in the directory's filename) --- they have the same filenames, and thumbnails
are their own thumbnails. :-)
No matter what bit depth a file format uses, zgv reads files in as one of two
internal formats --- 8-bit (with a palette), or 24-bit. (See Video Mode
, for why zgv works this way. See What a Video Mode
, for more on bit depth.) Usually, zgv works internally with the lowest
bit depth which doesn't lose data. So a 1-bit-per-pixel (mono) file is loaded
as 8-bit, as are 4-bit and 8-bit ones, but a 24-bit file is loaded as 24-bit.
For the most part, it's obvious which depth zgv reads a file as, if you know how
the files are stored. But if you don't happen to know that, then it can seem
like some bizarre black art dependent on the phase of the moon. So here's how
the differing file formats are read:
GIF, PBM, PGM, mrf, XBM.
24-bit if file is, else 8-bit:
JPEG, PNG, BMP, TGA, PCX, XPM, PRF.
XPM is really a special case, being a palette-based format which can handle an
arbitrary number of colours. (This means XPMs don't have any inherent `depth'
as such, unlike most other files --- you couldn't legitimately talk of a
`24-bit XPM file'.) XPMs are loaded as 8-bit if they have 256 colours or less,
otherwise they're loaded as 24-bit.
Another special feature of XPM is that, since XPM files are primarily used as
icons, they are often partly transparent, and usually not designed to be
viewed on a black background. For this reason, transparent pixels are shown as
grey, and if the XPM contains less than 256 colours, the screen's background
colour is made grey as well.
zgv tries to deal sensibly with Linux and FreeBSD's provision for multiple
`virtual consoles'. This section covers the details of this.
Normally when you do a console switch away from zgv, it is suspended --- nothing
at all happens in that zgv process (and it takes no CPU) until you switch back
However, there are two circumstances (both in the file selector) when it makes
sense for zgv to keep running `in the background', and in these cases it does
When updating thumbnails. See Updating Thumbnails
, for what
happens in this case.
When reading a picture file. If it finishes reading it before you
return, zgv is suspended as usual.
If it's not run from a console tty (and if you are the owner of the
currently-selected console), 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. This
means you can run zgv reasonably transparently from X, Emacs, etc.
One problem with this is that, since zgv uses ` fork()
' and other things which give output on stdout will give confusing
results; the original zgv process will have exited before the new
(replacement) zgv process exits. Redirect stdout if you want things to make a
bit more sense --- for example, ` zgv -h | less
' will do what you'd
expect. For more `normal' uses where zgv doesn't give any output, there's no
However, there's a problem running zgv from X, when it's invoked from a window
manager's 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. So zgv will run on the console you started X from, but won't
switch there. As luck would have it, there's an easy workaround; when invoking
zgv from the menu, just redirect stderr to a non-console, such as
. The details of how to arrange this vary depending on the
window manager you're using, but generally you'd want a line ending in
something like ` Exec zgv 2>/dev/null &
' to do this.
It may seem a bit odd running zgv from X, but it can be useful if you have a
15/16/24/32-bit card and normally run X in monochrome or 8-bit colour. Or if
you just happen to like zgv. :-)
Running zgv from an xterm with a filename as an argument is probably how you'd
usually do this, though --- e.g. ` zgv wibble.jpg
'. zgv then runs on a
free console and switches back when you exit. If you want to switch back to X
before exiting zgv, it's just a matter of switching consoles, as usual. X will
be running on what was the first free console when it started; often this is
When mouse support is enabled in zgv, you can do almost everything with it that
you would ordinarily do with the keyboard.
To use the mouse support for just one zgv session, start zgv with something like
` zgv -M
'. To enable it by default, add mouse on
config file (see Config Files
zgv uses svgalib's mouse configuration; if you have not set that up, you will
probably need to do so before zgv's mouse support will work. See the
man page for details.
If you find that the mouse pointer moves too quickly or too slowly, you should
change zgv's mouse-scale
setting (see Config Variables
The file selector and viewer use the mouse differently for the most part, but
they do have one feature in common --- clicking the right mouse button brings
up a menu. (This is called, not unreasonably, the `right-button menu'.)
All the menu items correspond directly to commands available from the keyboard.
So if you are not very familiar with zgv, it may be best to read all about
those before making extensive use of the menu. See The File
, for file selector commands. See The Viewer
, for viewer
Some commands are `greyed out' on the menu if they are unavailable. For example,
if you are viewing an 8-bit picture in the viewer, the 15/16/24-bit modes
listed on the menu will be greyed out.
To remove the menu from the screen without selecting a command, either click
somewhere on the screen not covered by the menu, or press ` Esc
In the file selector, the mouse controls a conventional mouse pointer. In
addition to the right button calling up a menu, there are these actions you
can take with the mouse:
Clicking on a file views it.
Clicking on the area which shows the current directory prompts you for
a directory to change to (see Dialog Boxes
The scrollbar can be used to move along the file list, in a few
Clicking on the scrollbar's arrows moves along the file list a column
at a time.
Clicking on either side of the scrollbar's `slider' (only possible if
the slider does not fill the scrollbar, i.e. only possible if there are more
files than are shown onscreen) moves along the dir a page at a time.
Clicking on the slider and dragging it moves the file cursor along the
directory. It works in a slightly unusual way --- if you bear in mind that the
slider represents the screen `sliding' along the directory listing, and
remember that you're moving the cursor
not the screen itself (at least
not directly), the way it works may make a bit more sense.
Once you've got used to this, and got used to the menu, you may wonder how
exactly you're meant to (say) delete a file with the mouse. After all, while
clicking on it does select it, it also views it! Well, there is a way,
Click on the file you want to select, but hold down the mouse button. While
holding the button, click the right button. The menu should appear, and you
can let both buttons go. You can then select whatever you want to do from the
In the viewer, the mouse is mainly used for moving around the picture. To use it
for this, you should hold down the left button and drag the mouse around. It's
a little difficult to explain, but the basic idea is that you drag the screen
around the picture --- experiment with it and you should get the idea. No
mouse pointer appears while doing this, which is a feature not a bug. :-)
(If redisplay of the picture takes a long time, zgv can lag behind your mouse
movements somewhat. Hopefully this shouldn't be too much of a problem.)
There is also a right-button menu much like the file selector's one, and a mouse
pointer does appear when using that. Some notes on the menu:
Only a fixed selection of possible video modes are given as options on
the menu, to keep things manageable. The others are only available using the
relevant keys. (See Selecting a Video Mode
The ...smooth on/off
entries on the menu refer to the
and `interpolation in scaling mode' settings respectively, as
should hopefully be clear from the context.
When using an 8-bit mode for the viewer, the right-button menu has to
allocate some colours for its display from those normally used to show the
picture. This means that the picture might look a little odd when the menu is
onscreen in 8-bit modes. (zgv does try to minimise the disturbance by using
the closest available colours, though.)
The viewer's menu is disabled in modes which are less than 480 pixels
high, since that's the minimum screen height required to display it. (This
explains a number of the modes omitted from the menu. If (say) 320x200x8 was
on there, you'd then be able to switch to the mode using the mouse (of
course), but once there you wouldn't be able to use the mouse for anything
other than moving around the picture!)
Finally, while viewing an animated GIF file (see Multiple-image GIF
), you can right-click to exit the animation, or left-click to
You can do most things in zgv with the mouse, but you can't do everything. The
main problem is that there are still a few things which effectively ignore the
When thumbnails are being updated, or a picture being read, there's no
mouse equivalent of ` Esc
When you're prompted for a directory name, there's no mouse equivalent
of ` Esc
' or `Enter
Many aspects of the way zgv works can be modified by using a configuration file.
A configuration file lets you alter aspects of zgv's behaviour. zgv supports two
possible config files --- a system-wide one, /usr/local/etc/zgv.conf
and one for each user in their home directory, $HOME/.zgvrc
. Both are
optional. If $HOME/.zgvrc
exists, it is used instead of
Before describing the format of config files, it may help to give an example
# Sample zgv config file
# Comment lines begin with `#' and are ignored,
# as are blank lines.
# do faster jpeg thumbnails
# make tagged files' filenames blue
col-tagged 0 0 63
It is a line-based format. Each line (or rather, each line which is not a
comment line and is not blank) assigns a value to a single predefined
`variable'. zgv has many such variables it lets you modify in this way. For
example, the slideshow-randomise
option above controls whether or not
zgv shuffles the file order in slideshows. If it is given the value `on',
`yes', or `1' it does; if `off', `no', or `0' it doesn't.
Most variables are of this yes-or-no `boolean' type. Some others like
are integers (whole numbers). And there are other
Since the variables set in a config file have a direct effect on how zgv works,
it can be easier to simply call them `settings'. Indeed, such terminology is
used on occasion in this documentation.
There are various types of variable:
Boolean. These are on-or-off, yes-or-no variables. Most of zgv's config
file variables are of this type. Use `on', `yes', or `1' to enable the
setting, and `off', `no', or `0' to disable.
Integer. These are whole numbers. The meaning of the number depends on
what the variable is used for.
Real (floating-point). This can be a whole number or a decimal
fraction. Only the contrast
variables are of this
RGB. This is a special type used for specifying colours. It consists of
three numbers given one after the other, in the order red, green, blue. Each
must be in the range 0 to 63 inclusive. Together these specify the colour ---
for example, 63 63 63
is white, 32 32 32
a medium grey, and
63 63 0
Video mode (also called just `mode'). This is also a special type, used
for specifying a mode. It uses the width
notation mentioned elsewhere (see What a Video Mode is
), but with
spaces and/or tabs as separators, so you're actually giving three separate
numbers. For example, 640 480 8
specifies a 640x480x8 (256-colour)
The `no args' type. Settings of this form aren't variables as such, but
commands. See Config Variables
, for details of these (
Most configuration variables are directly equivalent to the long option names,
and documented elsewhere (see Options
). For example, where you'd do
on the command-line, you'd do zoom on
in a config
file. Be careful to avoid quoting arguments; if you do this in a config file,
you'll get an error. So --viewer-start-mode "800 600
on the command-line becomes viewer-start-mode 800 600
in a config file.
Now, let's go back to that "most". The options which can only
be specified on the command-line are the following, `one-off' options:
Equally, there are some configuration variables which can only be modified in a
config file. Here they are:
(No args; this is a command, not a variable as such.)
Stops zgv from allowing any video modes. This is usually followed by
some mode-good assignments. If it isn't, zgv simply assumes the
320x200x8 mode can be used.
(No args; this is a command, not a variable as such.)
This instructs zgv to assume that all modes can be used, providing your video
card has them. This is how zgv usually acts.
Mark the specified mode as `bad', so zgv will not allow
it. The `modespec' should be the width, height, and depth separated by spaces,
e.g. ` 640 480 8'.
Mark the specified mode as `good', so zgv will allow
(Enabled by default.) If enabled, throws away any byte
which appears from the mouse device in the first 50ms. This is to work around
a problem with my `mouse' (a Logitech trackball) which sends a bogus `
M' byte on initialisation for no obvious reason --- yet input is meant
to be in packets of 3 bytes! Anyway, this fixes it, and shouldn't break any
other mice, but if you have inexplicable mouse problems you may want to try
disabling this just to make sure it's not the problem.
Many of the config variable names were changed (in an attempt to rationalise
them to some extent, and behave a bit more like xzgv) in zgv 5.5, when
GNU-style long command-line options were added. However, being fully aware of
the number of complaints I would get if I made a clean break with the past
;-), almost all the old config file variable names are still supported (though
not on the command-line).
Rather than document the options again, here's a simple list of which old
options map to which current ones. (See Options
, for documentation on
most. See Config Variables
, for a few others.)
= force-viewer-8bit (sense inverted)
= delete-single-prompt (sense inverted)
= avoid-single-progress (sense inverted)
The old fullsel
, and hicontrol
options are no
longer supported (i.e. zgv's previously-default behaviour for those is now
permanent), and have no effect other than to give a warning.
Here I (RJM) attempt to explain why I did things the way I did. This is
presented in a question-and-answer format of sorts.
Often the simple answer to this is ``Actually, zgv was here first --- ask the
other guy.'' This is true of any viewer written since 1993, anyway.
Most of the time though, this is phrased as ``Why not just use xv?''. That's a
fair point; xv is quite a good program, and it has some nice features. But
briefly, here are my problems with it, the areas where I personally feel zgv
is (at least arguably) better than xv:
xv is shareware. Personally, I don't think selling picture viewers is
all that sensible when things like the Gimp are free.
I find the interface really, really weird. In particular, the visual
schnauzer feels rather `bolted on'.
xv tries to be a Swiss-Army knife of graphics, rather than
concentrating on what it really is, a picture viewer. zgv has some problems in
this area too, but it's much closer to the `do one thing well' software tools
philosophy (see Opening the software toolbox
in the textutils
I'm not saying zgv is great and xv is terrible, and it's clear that many people
prefer using (or have to use) an X picture viewer --- an area where xv has no
obvious zgv-like competition (er, not any more; see below). But I don't think
xv is even remotely close to being the category-killer for picture viewing
that some people seem to think it is.
(Update: Since I originally wrote the ``no obvious zgv-like competition'' line
above, I've written xzgv, which is a GTK+/Imlib-based port/rewrite of zgv for
X. What can I say, I liked it so much I wrote the code. :^)
`Electric Eyes' is another alternative to xv, but personally I find that much
too xv-like (hence my work on xzgv).)
For years, I maintained a conventional `man page' for zgv. But over time, I
realised just how impossibly confusing the zgv man page had become.
So I wanted to rewrite zgv's documentation in a more sensible way, in some other
format than a man page. I wanted an established, well-supported format with
structure and cross-referencing. I felt this made it a choice between HTML and
texinfo. HTML seemed to me to be a moving target like no other, and not as
well supported on text-only terminals as Info (and thus texinfo). When I
noticed that a converter existed to convert texinfo to HTML in any case, the
case was closed.
Don't get me wrong --- I like man pages. And even with the excellent Texinfo
documentation and Emacs' very helpful Texinfo mode, writing texinfo is hardly
easy. (Without Texinfo mode's node- and menu-update commands, I personally
would find it near-impossible!) But big man pages just aren't that good for
reference, and this is made worse by the relative lack of structure.
The conventional way to write texinfo is to follow each sentence with two spaces
after the dot (or whatever ends the sentence). Many people normally write this
way in a non-texinfo context too. But a sizeable proportion of people normally
write text with only one space after the dot --- and I'm one of them.
The Texinfo documentation gives the impression that two-space must
used; it says ``it is important to put two spaces at the end of sentences in
Texinfo documents.'' But the only circumstance in which spacing from the
texinfo file is preserved at all (in any sense other than `there is a space
here') is when the texinfo is converted to Info format. So, in fact, the
decision to use two-space depends on how the author wants Info output to
appear --- this is a subjective decision which should be entirely down to
the preference of the author
, despite the Texinfo documentation's attempt
to make two-space sound like an objective you-must-do-this kind of thing.
You might wonder what the problem with using one-space is, then. Well,
`makeinfo' has to reformat paragraphs, and whenever it needs to insert space
at (what appears to it to be) the end of a sentence, it inserts two spaces.
This behaviour cannot be altered, unlike in Emacs (
; see Fill Commands
in the emacs
info file) and GNU fmt ( -u
; see fmt invocation
info file). Also, attempting to `fix' the output Info with
sed doesn't work properly because the `tags' used to find nodes quickly are
then incorrect. These could of course also be fixed, but this would involve a
lot more work than a simple sed invocation.
So realistically, anyone who writes texinfo with one-space has to put up with
the occasional two-space sentence end being inserted into their text --- worse
still, the current `makeinfo' formatting algorithm seems to insert two spaces
even after abbreviations (such as `e.g.' and `etc.'), which breaks even
two-space texinfo. (This is particularly ironic, by the way, since two-space
partisans' main argument in favour of the practice is the way it makes it
possible to tell the difference between abbreviations and the end of a
One last point may be worth noting; I am not the first person to write texinfo
files using one-space. At the time of writing, it is used in the texinfo
documentation for BFD, gdbm, GTK, IPC, ld.so, and viper, and I expect there
are instances I'm not aware of.
All (non-trivial) programs have bugs. Anyone who denies this...
clearly hasn't written too many programs.
is wrong. ;-)
It follows that zgv, like everything else, always has some bugs. Usually these
are not serious, or I'd have fixed them before releasing zgv. Either way, bugs
and other problems with zgv are noted here.
If an XPM file using a chars-per-pixel setting of two or less uses an
undefined colour code in the image, this is not reported, and such pixels are
shown as the background colour. (But then, reading XPMs in the
three-chars-or-more manner, which does
detect undefined colours, would
make it (at best) half as fast.)
If you have both slideshow looping and shuffling enabled, sometimes you
can get the same picture twice in a row. This is due to the last picture
chosen for one loop round the pictures being the same as the first of the next
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.
Renaming a file renames the thumbnail too, but currently it ignores any
If you use the old line-based text, or use the `fs-thick-text' option,
some of the text in the right-button menus slightly overruns the `buttons'
they're on, which is harmless but doesn't look very nice.
If you look up `joe code' in a dictionary, it says ``see zgv''. :-)
You don't currently get a progress report when TIFFs are being read.
Some of the things the change-picture viewer keys do when viewing a
slideshow are pretty stupid (` ^P
' and `^N
' suck, for example).
For multiple-image GIFs, the progress indicator only indicates how much
of the current image has been read, rather than how much of the file as a
whole has been. There's some precedent for this approach (e.g. the Gimp), but
it's not terribly elegant.
Corrupt JPEG or PNG data warnings are not reported by zgv.
In the 640x480x4 mode in the viewer, when scaling a picture where the
scaled picture remains narrower than the screen's width, the background to the
left and right of the picture is filled in with the picture's background
colour (though you'll only be able to see this if the picture's background
colour isn't black). This is harmless but looks strange.
The help pages only list a few of the keys.
Most GIF89a extension blocks are ignored. (The exception is the
Graphics Control Block, used for delay times and transparency in animated
XPM files with more than 256 colours are shown with a black background
(not the grey background usually used for XPMs), and those with exactly 256
colours are shown with the background being the first colour specified in the
If you find zgv does something wrong, which you suspect might be a fault of some
sort (a bug) in the program, it is best to report it as I may not be aware of
the problem. (But first, check it is not a `known bug'. See Known Bugs
It is not usually helpful to report a bug I already know about.)
zgv uses various libraries; if you find a problem, it could
be a bug in
one of them. This is not an attempt at buck-passing :-), rather concern that
bugs should be reported to the people best able to fix them.
Most bugs will turn out to be in zgv itself, but in the past, some
display bugs have turned out to be bugs in svgalib. If it is a display bug,
try zgv on other machines if you can, and try other svgalib programs which use
the same video mode(s). (Svgalib's example program `vgatest' can be useful for
this; see its man page for details.) This should help you determine whether it
is an svgalib bug or not. (If you really can't figure out whether it's a bug
in zgv or in svgalib, it may be best to report it as a possible bug in both.)
It is important to include as much detail in a bug report as you can. Here are
some details you should include:
The version of zgv you are running (` zgv --version
The version of svgalib (try ` ls /usr/lib/libvga.*
' for this).
What your machine's (S)VGA card is described as, and (generally more
useful) what svgalib reports it to be. zgv suppresses this report, but most
other svgalib programs (`vgatest' which comes with svgalib being a simple
example) will report it when they start up.
A description of the bug --- what effects it has, the circumstances it
occurs in, and so on. Does it only happen for certain types of file? Only when
in 8-bit modes? Only when avoid-single-progress
is enabled? Even
`irrelevant' details can sometimes be useful.
Finally, if you are a programmer and believe you have managed to fix
the bug yourself, patches are gratefully accepted. :-) You should generate the
patch using ` diff -c
' or (preferably) `diff -u
So, if you think you've found a bug in zgv, report it by emailing me at
Bugs in the documentation can sometimes cause as much trouble as bugs in the
program; if you notice a problem in the documentation, it's a good idea to
For reports of documentation bugs, you should include these details:
The version of zgv the documentation is for.
If it is a problem in one specific section of the documentation,
specify which part it is (by this I mean the heading it comes under;
texinfophiles should read this as `the node name' :-)).
The format of the documentation you saw the problem in (e.g. info, man
A description of the problem.
See Reporting Bugs
, for details of where to send the bug report. I have
given up on the apparently naive notion that zgv will ever be `finished'.
Every time I think that, some other idea for a new feature pops into my head
(or is forced there by someone else).
If you want to suggest a feature you'd like in zgv, or a change to an existing
feature, contact me at <email@example.com>.
Here is a list of features and/or changes which may hopefully be implemented in
future, in approximate priority order. (This is updated less often than zgv's
file, so you should check that too if you're interested in this
Fix the progress indicator problem with multiple-image GIFs.
Mouse support isn't really finished --- the goto-dir dialog should have
ok/cancel buttons, and currently you can't interrupt file loading and
thumbnail updates. The latter two would need a custom mouse event handler
temporarily installed, so that we could avoid losing any clicks. Actually it
might not be too bad an idea to always use a custom handler; that would be
easier. After all, on a slow machine you can already lose clicks during a
file-selector screen redraw!
File move should probably delete any existing thumbnail for the file if
the file itself is moved successfully.
Russell Marks <firstname.lastname@example.org> and others; see the section