NAME
zgv - picture viewer for VGA/SVGA displays
SYNOPSIS
zgv [options] [start-dir | file [file2 ...]]
DESCRIPTION
(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 File Selector) 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’ again.
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.
ACKNOWLEDGEMENTS
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.
‘install-info’ 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
terribly clear.
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.’’
OPTIONS
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] [start-dir | file [file2 ...]]
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 ‘--’ (see Configuring zgv), 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:
‘-A’
‘--auto-animate’
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.
‘--auto-mode-fit’
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 possible.
‘-p’
‘--avoid-single-progress’
Don’t show progress indicator when loading a single file from
the command-line.
‘--black-background’
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.
‘-b’
‘--block-cursor’
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 default.
‘--centre’
‘--center’
(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-screen-on-exit’
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 20 30"’.
‘--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 default.
‘--delete-single-prompt’
(Normally enabled, use ‘--delete-single-prompt=off’ to disable.)
If disabled, don’t prompt for confirmation when deleting a
single file.
‘--delete-tagged-prompt’
(Normally enabled, use ‘--delete-tagged-prompt=off’ to disable.)
If disabled, don’t prompt for confirmation when deleting all
tagged files.
‘--dither-16col-fast’
(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 noticeably slower).
‘--dither-hicol’
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.
‘--fake-cols’
(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-fs-16col’
Force the use of the 640x480 16-colour mode for the selector.
‘-j’
‘--force-viewer-8bit’
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.
‘--fs-16col-colour-thumbnails’
‘--fs-16col-color-thumbnails’
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.
‘--fs-ignore-old-pos’
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).)
‘--fs-magic’
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 tradeoffs involved.
‘--fs-perfect-cols’
Don’t change thumbnail colours when using the file selector to
make the rest of the selector look right. See Thumbnail Issues.
‘--fs-slow-thumbnail-update’
‘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.
‘--fs-small-text’
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.
‘-t’
‘--fs-thick-text’
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 well.)
‘--fullscreen’
(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.
‘--gnulitically-correct’
GNU has POSIXLY_CORRECT for compatibility with silly POSIX
misfeatures, and zgv has...
‘-h’
‘--help’
Display a list of options and a terse description of what the
options do.
‘-i’
‘--ignore-errors’
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.
‘--line-text’
Draw text by drawing lines rather than using bitmap fonts. This
looks worse but is faster.
‘-M’
‘--mouse’
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 fix it.
‘--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
compile-time.)
‘-g’
‘--pgm-truecol’
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. :-)
‘--reverse-bc-order’
Normally, any brightness modification is applied after applying
any contrast. Enabling this reverses the order.
‘--revert-orient’
(Normally enabled, use ‘--revert-orient=off’ to disable.) If
disabled, orientation (flip/mirror/rotate) state is retained
between pictures.
‘--revert-scale’
(Normally enabled, use ‘--revert-scale=off’ to disable.) If
disabled, scaling is retained between pictures.
‘--scrollbar’
(Normally enabled, use ‘--scrollbar=off’ to disable.) If
disabled, don’t show a scrollbar below the selector.
‘-s’
‘--show-dimensions’
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 >
output.ppm’.
‘-T’
‘--show-tagged’
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-xvpics-dir’
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
dir.)
‘-S delay’
‘--slideshow-delay delay’
Set time to wait in seconds before loading the next picture in a
slideshow. The default is 4.
‘-l’
‘--slideshow-loop’
Loop in slideshows ‘forever’ (or rather, until you exit).
‘-R’
‘--slideshow-randomise’
‘--slideshow-randomize’
Randomise picture order in slideshows. Due to the shuffling
approach taken, there will be no repeats or omissions.
‘--viewer-16col-colour’
‘--viewer-16col-color’
Give a dithered colour image in 640x480x4 mode when in the
viewer (see The Viewer 640x480x4 Mode), rather than greyscale.
‘-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 this means.
‘--visual’
(Normally enabled, use ‘--visual=off’ to disable.) If disabled,
no thumbnails are shown.
‘-k’
‘--vkludge’
enables vkludge, which smoothes slightly when ‘zooming’ a big
picture down to screen size, and also when in 320x400 and
360x480 modes.
‘--version’
Show version number.
‘-w’
‘--write-ppm’
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 program, though.
‘--xzgv-keys’
Makes zgv acts a bit more like xzgv, at least in terms of the
keypresses it supports (see xzgv Compatibility).
‘-z’
‘--zoom’
Enable zoom mode, which resizes the picture to fit the screen.
See Zoom Mode.
‘--zoom-reduce-only’
When in zoom mode, only reduce pictures to fit; i.e. make big
pictures viewable all-at-once while leaving small picures
intact.
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 Identification.)
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’
so that zgv will loop around these pictures until ‘Esc’ is pressed, and
the ‘-R’ option to shuffle (randomise) the picture order may also be of
interest.
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 is
‘on’/‘y’/‘yes’/‘1’ to enable the option, or ‘off’/‘n’/‘no’/‘0’ 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’/‘off’/etc. arg is optional, you can’t use the ‘--option
arg’ form in this case; it must be ‘--option=arg’ for it to work.)
ONLINE HELP
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.
THE FILE SELECTOR
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
Exiting zgv can be achieved two ways:
‘Esc’
‘x’
Quit zgv normally.
‘^C’
Quit zgv in a rather immediate and nasty way, by sending SIGINT.
(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 something.
(Technically it may not be ‘^C’ which sends SIGINT, but you
would have to have a strange setup for this to be the case.)
THUMBNAILS
(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.
Updating Thumbnails
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!
‘u’
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 any).
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 with.
‘Alt-u’
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 abort.
‘d’
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’.
Thumbnail Storage
Normally, thumbnails are stored in the subdirectory .xvpics (creating
the 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 the .xvpics 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 wibble.jpg, in the directory /foo/bar/baz, but can’t use
.xvpics. It will put the thumbnail in
$HOME/.xvpics/_foo_bar_baz/wibble.jpg, creating directories as
necessary.
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.
Thumbnail Issues
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 fs-
perfect-cols (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.
SCREEN LAYOUT
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).
MOVING AROUND THE LIST
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 supported.
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 and Pinky and
the Brain cartoons for further enlightenment on this subject.)
‘Cursor Up’
‘^P’
‘k’
‘q’
Move up. Moving up from a topmost entry moves to the bottom of
the previous column.
‘Cursor Down’
‘^N’
‘j’
‘a’
Move down. Moving down from a bottommost entry moves to the top
of the next column.
‘Cursor Left’
‘^B’
‘h’
‘o’
Move left one column.
‘Cursor Right’
‘^F’
‘l’
‘p’
Move right one column.
‘Page Up’
‘^U’
Move the cursor back (nearly) a page.
‘Page Down’
‘^V’
Move the cursor forward (nearly) a page.
‘Home’
‘^A’
Move the cursor to the start of the list.
‘End’
‘^E’
Move the cursor to the end of the list.
‘g’
‘’’
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.
VIEWING A FILE
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).
‘Enter’
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’
to abort.
DIALOG BOXES
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 OK has the same effect).
zgv also uses similar dialog boxes for other things:
- Getting a yes or no answer. ‘Enter’ or ‘y’ picks ‘yes’; ‘Esc’ 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 ‘Enter’, or press ‘Esc’ to abort. In fact, this line-input dialog
allows a certain amount of editing, and so supports these additional
keys:
‘Cursor Left’
‘^B’
Move the cursor left. (An underline character shows the cursor
position.)
‘Cursor Right’
‘^F’
Move the cursor right.
‘Home’
‘^A’
Move the cursor to the start of the line.
‘End’
‘^E’
Move the cursor to the end of the line.
‘Insert’
‘^I’
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.
‘Backspace’
‘^H’
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’
‘^D’
Delete the char the cursor is on.
TAGGING
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 different colours.)
Tag and Untag Commands
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 ‘T’
(shifted ‘t’).
There is also a command available in the viewer to tag the currently-
viewed file. See Changing Picture, for details.
‘t’
Tag file.
‘n’
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.
‘T’
Tag all files.
‘N’
Untag all files. This is on ‘N’ rather than ‘U’ for consistency.
‘Space’
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
Commands).
Slideshows
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):
‘Tab’
View the tagged files as a slideshow. (‘Tab’ is usually the key
above ‘Caps Lock’, which is often labelled with two arrows.)
Each file is shown for a certain amount of time, normally 4 seconds.
(See Options, 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 Picture), 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).
Copying/Moving/Deleting Files
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’, ‘m’,
and ‘d’ do not do the same thing.
‘C’
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.
‘M’
Move tagged files (or the current file) similarly.
‘D’
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.
RENAMING A FILE
As well as copying/moving files, you can rename them:
‘R’
‘Alt-r’
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.
CHANGING DIRECTORY
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’.)
‘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 Dialog Boxes), 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. :-)
CHANGING THE SORTING ORDER
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.)
‘Alt-n’
Sort by name. This is the default.
‘Alt-s’
Sort by size. The biggest files are listed last.
‘Alt-d’
‘Alt-t’
Sort by last-modified date/time. The newest files are listed
last.
‘Alt-e’
Sort by extension.
FILE SELECTOR TOGGLES
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
Options) and/or config file settings (see Configuring zgv).
‘v’
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 faster.
‘s’
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 list.
‘S’
Toggle shuffling (randomising) of slideshows. See Slideshows.
‘L’
Toggle looping in slideshows. See Slideshows.
‘Alt-m’
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.
‘c’
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.
OTHER FILE SEL COMMANDS
There are some other commands in the file selector which don’t easily
fit anywhere else. Here they are:
‘Delete’
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 get this.
‘Alt-f’
Show the number of (picture) files in the current directory, and
the number of tagged files (see Tagging).
‘^L’
‘^R’
Rescan the directory contents, and redraw the screen.
‘K’
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.
SHOWING MORE FILES
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.)
‘F1’
Select 640x480 mode. This is the default.
‘F2’
Select 800x600 mode.
‘F3’
Select 1024x768 mode.
‘F4’
Select 1280x1024 mode.
If you want to change the default mode used in the file selector, use
the fs-start-mode config file setting (see Configuring zgv). For
example, to use 800x600 by default, you’d use fs-start-mode 800 600 8.
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 mode-
good, mode-bad, etc. settings. See Config Variables.
Finally, if you have no 640x480 256-colour mode, or if force-fs-16col
has been set, the 640x480 16-colour mode is all that is available.
16-COLOUR FILE SELECTOR
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 either.
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 ‘c’ 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 option.)
THE VIEWER
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
Exiting the viewer is simple:
‘Esc’
‘x’
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.
BIG PICTURES
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 Modes), 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
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’
‘K’
‘Q’
Move up 100 pixels. ‘k’ and ‘q’ move up 10 pixels.
‘Cursor Down’
‘J’
‘A’
Move down 100 pixels. ‘j’ and ‘a’ move down 10 pixels.
‘Cursor Left’
‘H’
‘O’
Move left 100 pixels. ‘h’ and ‘o’ move left 10 pixels.
‘Cursor Right’
‘L’
‘P’
Move right 100 pixels. ‘l’ and ‘p’ move right 10 pixels.
‘Page Up’
‘^U’
Move up (nearly) a screenful. (It moves 90% of the screen
height.)
‘Page Down’
‘^V’
Move down (nearly) a screenful.
‘-’
Move left (nearly) a screenful. (It moves 90% of the screen
width.)
‘=’
Move right (nearly) a screenful.
‘Home’
‘^A’
Move to the top-left of the picture.
‘End’
‘^E’
Move to the bottom-right of the picture.
Zoom Mode
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 the screen.
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.
‘z’
Toggle zoom mode.
‘Alt-r’
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. :-)
‘v’
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.
‘n’
Resume ‘normal’ display --- disables zoom mode (and scaling
mode).
Auto-mode-fit
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 it.
‘Z’
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 is considered, despite the
aspect ratio, if no 640x480x8 mode exists.
SCALING
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:
‘s’
Increase the ratio by adding one --- this leads to ratios of
2:1, 3:1, 4:1...
‘d’
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 disabled):
‘S’
Decrease the ratio by subtracting one.
‘D’
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 generations. :-)
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.
‘i’
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 JPEGs.
(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.)
MIRROR AND ROTATE
Sometimes when viewing a picture you will want to flip it horizontally
or vertically, or rotate it:
‘m’
‘Mirror’ the picture (flip it horizontally).
‘f’
‘Flip’ the picture (flip it vertically).
‘r’
Rotate the picture 90 degrees clockwise.
‘R’
Rotate the picture 90 degrees anti-clockwise. (This is a little
slower as it works by effectively doing ‘r’ then ‘f’ then ‘m’.)
‘Alt-n’
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:
‘Alt-o’
Re-use the previous picture’s orientation for this picture.
‘Alt-s’
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).
BRIGHTNESS AND CONTRAST
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 Modes).
‘,’
Decrease contrast.
‘.’
Increase contrast.
‘<’
Decrease brightness.
‘>’
Increase brightness.
‘;’
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:
‘B’
Reverse the order in which brightness and contrast are applied.
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.
GAMMA ADJUSTMENT
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
fashion?
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 very easy and fast to change gamma
adjustment to commonly-required values. So here’s how to do it:
‘1’
Set gamma adjustment to 1.0, i.e. no adjustment. This is the
default setting.
‘2’
Set gamma adjustment to 2.2. This is useful for viewing linear-
gamma files (one classic example being raytracer output) on an
average PC monitor.
‘3’
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 these days.
‘4’
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 considered/well known.
You can also tweak the adjustment more precisely, in a similar way to
brightness/contrast:
‘Alt-,’
Decrease gamma adjustment (divide it by 1.05).
‘Alt-.’
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.
INCREASED GREYSCALES
zgv normally displays greyscale pictures in 8-bit modes (see Video
Modes). 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 balance.
However, the difference this feature makes is very slight. The image
will probably be very, very slightly brighter than it would be
otherwise, and possibly a little ‘warmer’ because of the minor use of
colour and the eye’s green/red bias (I think).
You can toggle this feature in the viewer:
‘G’
Toggle whether to fake some extra greyscales/colours in 8-bit
modes.
To disable it by default, put fake-cols off in a config file (see
Configuring zgv).
CHANGING PICTURE
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’) temporarily
returns to the file selector and shows the usual progress indicator
while it’s being read.
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 do it.
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 here.)
‘Backspace’
View previous file in dir, without progress indicator. (In
slideshow, move to next file without waiting.)
‘Enter’
View next file in dir, without progress indicator. (In
slideshow, move to next file without waiting.)
‘Space’
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.)
‘^P’
View previous file in dir, with progress indicator. (In
slideshow, acts like ‘Esc’.)
‘^N’
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.
FILE DETAILS
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.
PAUSING SLIDESHOWS
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 terminal output:
‘^S’
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.
‘^Q’
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.
MULTIPLE-IMAGE GIF ANIMATION
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 between updates.
(This animation mode is automatically enabled if you start zgv with the
‘-A’ or ‘--auto-animate’ command-line option. See Invoking zgv.)
‘e’
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:
‘Esc’
‘x’
Stop the animation and return to the viewer. If auto-animation
mode is enabled, it exits the viewer too.
‘p’
Pause (or unpause) the animation.
‘n’
Skip to the next frame. Generally only useful when paused.
If auto-animation is enabled, the ‘Backspace’, ‘Enter’, and ‘Space’
keys do the same as they do in the normal viewer (see Changing
Picture). Otherwise they act the same as ‘Esc’.
VIDEO MODES
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.
What a Video Mode is
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 the mode).
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 at once.
A variant notation widthxheightxdepth 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 widthxheightxdepth 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 xxyxz in zgv or in this
documentation, it is always specifying a video mode in this notation.
Video Mode Issues
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, for 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 bottom line:
o 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.
o 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 force-
viewer-8bit can be enabled to force the dithering behaviour. See
Configuring zgv.)
o 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.
Default Video Mode
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.
Selecting a Video Mode
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 ‘F1’ 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’, ‘SF2’, 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’, ‘Tab-F2’, etc.
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 mode.
‘[’
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 (see Auto-mode-fit).
‘0’
Select 640x480x4 mode. This emulates an 8-bit mode. See The
Viewer 640x480x4 Mode.
‘5’
Select 320x200x8 mode.
‘6’
Select 320x240x8 mode.
‘^’
Select 320x240x24 mode. (‘^’ is often on shift-6.)
‘7’
Select 320x400x8 mode. This emulates a 640x400 mode. See Virtual
Modes.
‘8’
Select 360x480x8 mode. This emulates a 720x480 mode. See Virtual
Modes.
‘F1’
Select 640x480x8 mode.
‘F2’
Select 800x600x8 mode.
‘F3’
Select 1024x768x8 mode.
‘F4’
Select 1280x1024x8 mode.
‘F5’
Select 320x200x15 mode.
‘F6’
Select 320x200x16 mode.
‘F7’
Select 320x200x24 mode.
‘F8’
Select 640x480x15 mode.
‘F9’
Select 640x480x16 mode.
‘F10’
Select 640x480x24 mode.
‘SF1’
‘F11’
Select 800x600x15 mode.
‘SF2’
‘F12’
Select 800x600x16 mode.
‘SF3’
Select 800x600x24 mode.
‘SF4’
Select 1024x768x15 mode.
‘SF5’
Select 1024x768x16 mode.
‘SF6’
Select 1024x768x24 mode.
‘SF7’
Select 1280x1024x15 mode.
‘SF8’
Select 1280x1024x16 mode.
‘Tab-F1’
Select 1280x1024x24 mode.
‘Tab-F2’
Select 1152x864x8 mode.
‘Tab-F3’
Select 1152x864x15 mode.
‘Tab-F4’
Select 1152x864x16 mode.
‘Tab-F5’
Select 1152x864x24 mode.
‘Tab-F6’
Select 1600x1200x8 mode.
‘Tab-F7’
Select 1600x1200x15 mode.
‘Tab-F8’
Select 1600x1200x16 mode.
‘Tab-F9’
Select 1600x1200x24 mode.
Special Modes
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
available.)
Virtual 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 360x480.
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 mode is 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.
The Viewer 640x480x4 Mode
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.
‘c’
If in 640x480x4 mode, toggle between greyscale and colour.
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 Files), or you can toggle the setting interactively:
‘Alt-c’
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.
Drawbacks of 15/16-bit Modes
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
greyscales.)
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 directly:
‘F’
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
Configuring zgv).
32-bit Video Modes
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 them?
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 works:
o 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. :-)
o 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.
o 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.
Disabling Video Modes
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 card.
(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 details.)
To disable video modes, you should give appropriate mode-bad entries in
a config file (preferably /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 mode-good
entries --- but most cards support so many video modes that the mode-
bad approach is usually the right one.
XZGV COMPATIBILITY
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 Config Files). 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 selector:
‘Space’
View a picture file, or if the cursor is on a subdirectory, make
that the current directory. (Like the native ‘Enter’, which
still works.)
‘-’
Untag file.
‘=’
Tag file.
‘Alt -’
(i.e. Alt-minus) Untag all files.
‘Alt =’
(i.e. Alt-equals) Tag all files.
‘Ctrl-n’
Rename file.
‘Ctrl-d’
Delete file.
‘q’
‘Ctrl-q’
Exit zgv.
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:
‘b’
View previous file in dir.
‘Space’
View next file in dir.
‘Ctrl-Space’
Tag current file, then view next file in dir.
(In short, ‘b’/‘Space’/‘Ctrl-Space’ act like the native
‘Backspace’/‘Enter’/‘Space’. The same mappings also apply when
animating a multiple-image GIF file (see Multiple-image GIF
Animation).)
‘Ctrl-w’
Exit viewer (i.e. ‘close file’).
‘N’
Restore the picture orientation to normal. This undoes the
effect of any mirrors, flips, and/or rotations. (Like the native
‘Alt-n’.)
There are some omissions in the viewer’s xzgv-ish keys:
- The ‘Ctrl’ + cursor-key alternatives to ‘h’/‘j’/‘k’/‘l’ 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 other
interface differences.
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 likely to.
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. :-)
FILE FORMATS
Picture files are stored in a variety of different forms. These forms
are usually called ‘file formats’. zgv supports several.
FILE TYPE IDENTIFICATION
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 or .jpeg, 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 ‘Alt-m’ (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.
SUPPORTED FILE FORMATS
zgv supports the following file formats:
o GIF. Multiple-image GIFs are treated specially (see Multiple-image
GIF Animation).
o JPEG.
o PNG.
o PBM/PGM/PPM, collectively known as ‘PNM’. This is a nice simple
format used by pbmplus and netpbm.
o BMP.
o TGA (Targa).
o PCX.
o mrf. Mrf files can be converted to/from PBM with mrftopbm/pbmtomrf,
and the format is documented in the mrf(5) man page.
o PRF. PRF is an extension of mrf, similarly converted with
prftopnm/pnmtoprf, and documented in the prf(5) man page.
o XBM (X bitmap files).
o 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 config.mk to change it.)
o TIFF.
o 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.
o 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. :-)
FILE FORMAT DEPTHS
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 Issues, for why zgv works this way. See What a Video Mode
is, 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:
Always 8-bit:
GIF, PBM, PGM, mrf, XBM.
Always 24-bit:
PPM, TIFF.
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.
CONSOLES
zgv tries to deal sensibly with Linux and FreeBSD’s provision for
multiple ‘virtual consoles’. This section covers the details of this.
RUNNING IN THE BACKGROUND
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 to it.
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 keep running:
- 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.
RUNNING FROM NON-CONSOLES
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()’, ‘zgv -h’ 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
problem.
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 /dev/null. 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 number 7.
USING A MOUSE
When mouse support is enabled in zgv, you can do almost everything with
it that you would ordinarily do with the keyboard.
ENABLING THE MOUSE
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 to a
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 libvga.config(5) 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).
MOUSE MENUS
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 Selector, for file selector commands. See The Viewer, for viewer
commands.
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’.
MOUSE FUNCS IN THE FILE SELECTOR
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:
o Clicking on a file views it.
o Clicking on the area which shows the current directory prompts you
for a directory to change to (see Dialog Boxes).
o The scrollbar can be used to move along the file list, in a few
different ways:
- 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, described below.
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 menu.
MOUSE FUNCS IN THE VIEWER
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:
o 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.)
o The ...smooth on/off entries on the menu refer to the vkludge and
‘interpolation in scaling mode’ settings respectively, as should
hopefully be clear from the context.
o 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.)
o 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
Animation), you can right-click to exit the animation, or left-click to
pause/unpause.
MOUSE DEFICIENCIES
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 mouse:
o When thumbnails are being updated, or a picture being read, there’s
no mouse equivalent of ‘Esc’.
o When you’re prompted for a directory name, there’s no mouse
equivalent of ‘Esc’ or ‘Enter’.
CONFIGURING ZGV
Many aspects of the way zgv works can be modified by using a
configuration file.
CONFIG FILES
A configuration file lets you alter aspects of zgv’s behaviour. zgv
supports two possible config files --- a system-wide one,
/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 /etc/zgv.conf.
Before describing the format of config files, it may help to give an
example file:
# Sample zgv config file
# Comment lines begin with ‘#’ and are ignored,
# as are blank lines.
slideshow-randomise on
# do faster jpeg thumbnails
jpeg-index-style 1
# 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
jpeg-index-style are integers (whole numbers). And there are other
types, too.
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.
CONFIG VARIABLE TYPES
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 and gamma variables are of this type.
- 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 is yellow.
- Video mode (also called just ‘mode’). This is also a special type,
used for specifying a mode. It uses the widthxheightxdepth 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) mode.
- The ‘no args’ type. Settings of this form aren’t variables as such,
but commands. See Config Variables, for details of these (mode-all-bad
and mode-all-good).
CONFIG VARIABLES
Most configuration variables are directly equivalent to the long option
names, and documented elsewhere (see Options). For example, where you’d
do --zoom 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 8" on the command-
line becomes viewer-start-mode 800 600 8 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:
o --help
o --version
o --reload-delay
o --show-tagged
o --show-dimensions
o --write-ppm
Equally, there are some configuration variables which can only be
modified in a config file. Here they are:
mode-all-bad
(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.
mode-all-good
(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.
mode-bad modespec
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’.
mode-good modespec
Mark the specified mode as ‘good’, so zgv will allow it.
mouse-kludge
(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.
CONFIG FILE BACKWARD COMPATIBILITY
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.)
allmodesbad
= mode-all-bad
allmodesgood
= mode-all-good
automodefit
= auto-mode-fit
badmode
= mode-bad
bc_order_rev
= reverse-bc-order
betterpgm
= pgm-truecol
black
= col-black
blockcursor
= block-cursor
cleartext
= clear-screen-on-exit
dark
= col-dark
fakecols
= fake-cols
fastdither16col
= dither-16col-fast
force16fs
= force-fs-16col
forgetoldpos
= fs-ignore-old-pos
fs16col
= fs-16col-colour-thumbnails
fs_startmode
= fs-start-mode
fsmagic
= fs-magic
goodmode
= mode-good
gnulitically_correct
= gnulitically-correct
jpeg24bit
= force-viewer-8bit (sense inverted)
jpegindexstyle
= jpeg-index-style
jpegspeed
= jpeg-speed
light
= col-light
linetext
= line-text
medium
= col-medium
mousekludge
= mouse-kludge
mousescale
= mouse-scale
nodelprompt
= delete-single-prompt (sense inverted)
onefile_progress
= avoid-single-progress (sense inverted)
pcdres
= pcd-res
perfectindex
= fs-perfect-cols
revert
= revert-scale
revert_orient
= revert-orient
showxvpicdir
= show-xvpics-dir
shuffleslideshow
= slideshow-randomise
slowupdate
= fs-slow-thumbnail-update
smallfstext
= fs-small-text
startmode
= viewer-start-mode
tagged
= col-tagged
tagtimeout
= slideshow-delay
thicktext
= fs-thick-text
viewer16col
= viewer-16col-colour
xzgvkeys
= xzgv-keys
zoom_reduce_only
= zoom-reduce-only
The old fullsel, hicolmodes, 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.
RATIONALE
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.
WHY YET ANOTHER VIEWER?
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:
o xv is shareware. Personally, I don’t think selling picture viewers is
all that sensible when things like the Gimp are free.
o I find the interface really, really weird. In particular, the visual
schnauzer feels rather ‘bolted on’.
o 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 info file).
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).)
WHY A TEXINFO MANUAL?
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.
WHY ONE-SPACE SENTENCE ENDS?
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 be
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
(sentence-end-double-space; see Fill Commands in the emacs info file)
and GNU fmt (-u; see fmt invocation in the textutils 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 sentence.)
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.
BUGS AND RESTRICTIONS
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.
KNOWN BUGS
- 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 loop.
- 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 ~/.xvpics/_foo_bar/baz thumbnail.
- 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’’. :-)
SUBOPTIMAL FEATURES
- 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.
RESTRICTIONS
- Most GIF89a extension blocks are ignored. (The exception is the
Graphics Control Block, used for delay times and transparency in
animated GIFs.)
- 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 file.
REPORTING BUGS
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:
o The version of zgv you are running (‘zgv --version’ reports this).
o The version of svgalib (try ‘ls /usr/lib/libvga.*’ for this).
o 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.
o 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.
o 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
<rus@svgalib.org>.
REPORTING DOCUMENTATION BUGS
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 report it.
For reports of documentation bugs, you should include these details:
o The version of zgv the documentation is for.
o 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’ :-)).
o The format of the documentation you saw the problem in (e.g. info,
man page, HTML).
o A description of the problem.
FUTURE CHANGES
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 <rus@svgalib.org>.
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 TODO file, so you should check that too if you’re
interested in this stuff.)
o Fix the progress indicator problem with multiple-image GIFs.
o 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!
o File move should probably delete any existing thumbnail for the file
if the file itself is moved successfully.
AUTHOR
Russell Marks <rus@svgalib.org> and others; see the section
ACKNOWLEDGEMENTS for details.
SEE ALSO
xzgv(1), cjpeg(1), djpeg(1), pbm(5), pgm(5), ppm(5), mrf(5),
svgalib(7), libvga.config(5)