zgv.1

一个利用SDL语言来实现svgalib函数的示例程序

.PP
.SH "MIRROR AND ROTATE"
Sometimes when viewing a picture you will want to flip it horizontally
or vertically, or rotate it:
.PP
`\fBm\fR'
.RS
`Mirror' the picture (flip it horizontally).
.PP
.RE
`\fBf\fR'
.RS
`Flip' the picture (flip it vertically).
.PP
.RE
`\fBr\fR'
.RS
Rotate the picture 90 degrees clockwise.
.PP
.RE
`\fBR\fR'
.RS
Rotate the picture 90 degrees anti-clockwise. (This is a little slower
as it works by effectively doing `\fBr\fR' then `\fBf\fR' then `\fBm\fR'.)
.PP
.RE
`\fBAlt-n\fR'
.RS
Restore the picture orientation to normal. This undoes the effect of any
mirrors, flips, and/or rotations.
.RE
.PP
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:
.PP
`\fBAlt-o\fR'
.RS
Re-use the previous picture's orientation for this picture.
.PP
.RE
`\fBAlt-s\fR'
.RS
Save the current picture orientation, making all pictures viewed until
you press `\fBEsc\fR' use it. (The orientation reverts to normal after
that, though.)
.RE
.PP
Finally, you can choose to have the orientation preserved the whole
time. To do this, put \fIrevert-orient off\fR in a config file
(see \fBConfiguring zgv\fR).
.PP
.SH "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 \fBVideo Modes\fR).
.PP
`\fB,\fR'
.RS
Decrease contrast.
.PP
.RE
`\fB.\fR'
.RS
Increase contrast.
.PP
.RE
`\fB<\fR'
.RS
Decrease brightness.
.PP
.RE
`\fB>\fR'
.RS
Increase brightness.
.PP
.RE
`\fB;\fR'
.RS
Reset contrast and brightness to normal. (`\fB*\fR' is also supported, for
hysterical raisins.)
.RE
.PP
Any contrast change is applied before any brightness change by default.
However, you can reverse the order easily enough:
.PP
`\fBB\fR'
.RS
Reverse the order in which brightness and contrast are applied.
.RE
.PP
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.
.PP
.SH "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.'' :-)
.PP
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.
.PP
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.
.PP
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.
.PP
So how on earth do you deal with something like \fIthat\fR in a
remotely sane fashion?
.PP
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 \fIvery\fR easy and fast to change
gamma adjustment to commonly-required values. So here's how to do it:
.PP
`\fB1\fR'
.RS
Set gamma adjustment to 1.0, i.e. no adjustment. This is the default
setting.
.PP
.RE
`\fB2\fR'
.RS
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.
.PP
.RE
`\fB3\fR'
.RS
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.
.PP
.RE
`\fB4\fR'
.RS
Set gamma adjustment to its initial value, as specified by a `\fB-G\fR'
command-line option (see \fBOptions\fR) or \fIgamma\fR config file
setting (see \fBConfiguring zgv\fR). The default value used if none was
specified is 1.0.
.RE
.PP
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 \fIscreen\fR gamma is the
one most widely considered/well known.
.PP
You can also tweak the adjustment more precisely, in a similar way to
brightness/contrast:
.PP
`\fBAlt-,\fR'
.RS
Decrease gamma adjustment (divide it by 1.05).
.PP
.RE
`\fBAlt-.\fR'
.RS
Increase gamma adjustment (multiply it by 1.05).
.RE
.PP
Note that `\fB;\fR', and the other keys which reset the
brightness/contrast, deliberately avoid resetting the gamma adjustment.
.PP
.SH "INCREASED GREYSCALES"
zgv normally displays greyscale pictures in 8-bit modes (see \fBVideo
Modes\fR). 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.
.PP
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.)
.PP
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.
.PP
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).
.PP
You can toggle this feature in the viewer:
.PP
`\fBG\fR'
.RS
Toggle whether to fake some extra greyscales/colours in 8-bit modes.
.RE
.PP
To disable it by default, put \fIfake-cols off\fR in a config file
(see \fBConfiguring zgv\fR).
.PP
.SH "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.
.PP
There are two ways to do this; one way leaves the old picture onscreen
until the new one is read in, the other (on `\fB^P\fR' and `\fB^N\fR')
temporarily returns to the file selector and shows the usual progress
indicator while it's being read.
.PP
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.
.PP
Note that the meanings of the commands change when you are viewing a
slideshow; the details are covered below.
.PP
(See \fBDialog Boxes\fR, to see what `\fBBackspace\fR' is being used to mean
here.)
.PP
`\fBBackspace\fR'
.RS
View previous file in dir, without progress indicator. (In slideshow,
move to next file without waiting.)
.PP
.RE
`\fBEnter\fR'
.RS
View next file in dir, without progress indicator. (In slideshow, move
to next file without waiting.)
.PP
.RE
`\fBSpace\fR'
.RS
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.)
.PP
.RE
`\fB^P\fR'
.RS
View previous file in dir, with progress indicator. (In slideshow, acts
like `\fBEsc\fR'.)
.PP
.RE
`\fB^N\fR'
.RS
View next file in dir, with progress indicator. (In slideshow, acts
like `\fBEsc\fR'.)
.PP
.RE
.PP
Note that `\fBSpace\fR' 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.
.PP
.SH "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:
.PP
`\fB:\fR'
.RS
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 \fBOther File Sel Commands\fR); the only difference is that
you can't use `\fB;\fR' to get this in the viewer, and the viewer doesn't
depend on thumbnails for the width/height info.
.RE
.PP
.SH "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:
.PP
`\fB^S\fR'
.RS
Pause slideshow, leaving you on the current image until you resume. You
can still abort early with `\fBEsc\fR', go to the next image with
`\fBEnter\fR', or in fact use any viewer commands at all.
.PP
.RE
`\fB^Q\fR'
.RS
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.
.RE
.PP
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.
.PP
.SH "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.)
.PP
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.
.PP
(This animation mode is automatically enabled if you start zgv with the
`\fB-A\fR' or `\fB--auto-animate\fR' command-line option. See \fBInvoking
zgv\fR.)
.PP
`\fBe\fR'
.RS
Enter animation mode. (I don't know what the `\fBe\fR' stands for either.
:-)) In this mode the normal viewer keys have no effect, and instead, a
more limited set of keys are supported:
.PP
.RE
`\fBEsc\fR'
.RS
.RE
`\fBx\fR'
.RS
Stop the animation and return to the viewer. If auto-animation mode is
enabled, it exits the viewer too.
.PP
.RE
`\fBp\fR'
.RS
Pause (or unpause) the animation.
.PP
.RE
`\fBn\fR'
.RS
Skip to the next frame. Generally only useful when paused.
.RE
.PP
If auto-animation is enabled, the `\fBBackspace\fR', `\fBEnter\fR', and
`\fBSpace\fR' keys do the same as they do in the normal viewer
(see \fBChanging Picture\fR). Otherwise they act the same as `\fBEsc\fR'.
.PP
.SH "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.
.PP
.SS "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).
.PP
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.
.PP
A variant notation \fIwidth\fRx\fIheight\fRx\fIdepth\fR 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:
.PP
(These are the only bit depths relevant to zgv.)
.PP
\fB-\fR 
4-bit means 16 colours.
.PP
\fB-\fR 
8-bit means 256 colours.
.PP
\fB-\fR 
15-bit means 32768 colours.
.PP
\fB-\fR 
16-bit means 65536 colours.
.PP
\fB-\fR 
24-bit means 16777216 colours (over 16 million).
.PP
\fB-\fR 
32-bit means 16777216 colours too (!), since only 24 of the 32 bits are
used for display purposes.
.RE
.PP
From the number of colours available in the latter modes, you can see
why a bit depth notation is so useful!
.PP
So, in the \fIwidth\fRx\fIhe