HELLO, WORLD
This is my "port" of POV-Ray 2.2 to Linux.  This version is almost
exactly the same as the one distributed by the POV-Team, but support
has been added for a dithered color X display and linux SVGALIB
display for 256, 32k, 64k, and 16m color modes.

I have compiled and tested these sources on only one Linux machine, a
386-40 with 387 running Linux 0.99.15, GCC 2.5.9 and libc-4.5.19.  I am
relatively confident that it will require little to no twiddling to
get it to compile on other Linux systems and even general UNIX
systems.

Compared to version 2.0 or 2.1, there aren't any real added features, 
just some bugfixes.  If you haven't noticed any problems with 2.0 or
2.1, you probably don't need to bother upgrading.  In any case, you
should probably only get the new source or binary archive, as the
docs, include, and scene files are unchanged as far as I know.

ABOUT THE SOFTWARE/WHERE TO FTP/WHERE TO COMPLAIN

This archive should have contained the file "povlegal.doc" which
tells you about my responsibilities and your rights.  If it is not
present, you can find it in a copy of the real distribution.
Basically, this is free software, but the license does have some
restrictions.

If you want to get the real distribution for any reason, it is
available at many FTP sites and BBSs.  Specifically, the FTP site
alfred.ccs.carleton.ca is the official distribution point of the
POV-Team to the internet.  Look in pub/pov-ray.  The current 2.1 files
are in
/pub/pov-ray/POV-Ray2.2/povsrc.tar.Z
                        povscn.tar.Z
                        povdoc.tar.Z

This (my) distribution is divided into several archives:
povsrc-2.2.tar.gz contains the source/ directory
povscn-2.2.tar.gz contains the scenes/ directory
povinc-2.2.tar.gz contains the include/ directory
povdoc-2.2.tar.gz contains the doc/ and demo/ directories
povbin-2.2.tar.gz contains the bin/ directory

Each archive contains the toplevel README.linux and povlegal.doc files.

The minimum required is the include directory plus either binaries or
source.  I recommend that you get the documentation and scenes unless
you're sure you know what you're doing.  (The scenes/ directory is
basically the same as POV 1.0, but the syntax has changed.)

HOW TO INSTALL:
If you've gotten the binary archive, pick one of povray.? and copy it
to a binary directory on your home system as "povray".

If you've gotten the source archive, change the INSTBIN= line of the
Makefile, and "make install?" where ? is one of s, x, or v.  S stands
for 'standard' and the resulting binary will not support a +d option.  X
stands for Xwindows, and the resulting binary will support display on
a 256 color X server.  V stands for VGA, and will support display on
a (S)VGA monitor.  If you install the VGA version, you must do the
installation as root because of the way svgalib operates.

Once you've done one of the two above things, you need to put
(somewhere like .cshrc)
setenv POVRAYOPT -l$HOME/povray/include
to tell POVRAY where to find your include files.  You can actually
specify any command-line options here, but this is the only one that's
really necessary.

Now, render your scene:
povray -w320 -h200 -ifoo.pov -ofoo.tga +ft -a +dG -v

WHAT TO VIEW/CONVERT PICTURES WITH:

XWINDOWS
I recommend 'xli', which can apparently be obtained only in source
form from ftp.x.org:/contrib/xli*

It can view the targa files that POV generates, as well as many other
formats (gif, jfif, ...) and (on my 5 meg machine) faster output than

'xv', the other picture display I know of for X.  It seems slower but
has a nicer (xview?) interface.  This one is available in binary
format from sunsite.unc.edu:/pub/Linux/X11/something.  I prefer the
2.11(?) version to version 3.x because it seems somewhat faster.  Xv
doesn't support direct viewing of targa images, so you'll have to
convert them to something else.

SVGALIB
There isn't that much out there for SVGALIB.  Try 'spic' (apparently
not intended as a racial slur) from something like
sunsite.unc.edu:/pub/Linux/apps/graphics/viewers/spic06.tgz for an
archive of the source.  It views only gifs and jfif images, so take a
look at one of the converters below.

CONVERTERS
I'm not really sure if it's best to convert raytraced images into gif
or jfif images.  Gif compression is "lossy" because it only allows for
256 colors per image, instead of 16 million like Targa allows.  Jfif
(known commonly as jpg) is lossy in the true sense, but it seems to be
better for display than a 256 color image when encoded at a high
quality setting and viewed in a truecolor video mode.  And at the same
time this file will generally have a smaller size on disk.

If you want to convert to jfif, you should use the IJG converters,
jpeg-V4a.  These are available in source and binary form -- Ask Archie
for the former, and take a look around Sunsite.unc.edu for the latter.

To convert to gif, I know of no decent program.  I thought I had found
one, pvquant, but it has some problems.  Its commandline is confusing
or at least brain-damaged.  And apparently it only deals with 320x200
resolution images.  This is a pity since its quantization method (no
dither) seemed to be pretty good.

I'm sure that there is some pair (or more) of programs in the netpbm
or pbmplus packages that will serve to do any of the above.  But I'm
not too familiar with those programs.  Perhaps someone could enlighten
me as to what's out there....

SUMMARY OF CHANGES:

DIRECTORY STRUCTURE
The machine/ directory was removed, and all system-specific files are 
in pov/source with the general c files.

The include files were separated from the documentation, and a total
of 5 archive files now exist, compared to 3 or 4 as distributed.

SOURCE FILES

PLAIN CODE
A minor revision in the code of the matherr() function allows it to be
compiled under Linux:  It is #ifdef'd out.  If someone will tell me
that there are definitions of the macros that matherr() refers to,
I'll be happy to change this.

XWINDOWS CODE
Several changes other than those necessary for a compile were made to
the xwindows.c file.  Two features were added, though the original
behaviour of the xwindows display module can be restored by changing
the -Define parameters to the compile of xwindows.c:

 The first change, reverted by -DWAIT_ON_COMPLETION causes the
 displayed image to be erased at completion (Actually a few seconds
 later) and then terminate POVray.  This option is useful if you use
 POVray in a batch context but would still like to look at the output
 as it renders.  
 
 The second change, reverted by removing -DCDITHER causes the display
 module to do a primitive ordered dither on the displayed images.
 While an ordered dither is not the highest quality attainable, it is
 signifigantly better than the former behaviour:  A nearest colour was
 chosen from a palette of only 216.  This led to severe banding.
 
If you are using the binary distributed, these additions to the X
version will be compiled in.  You will have to get your own copy of
the sources to change the behaviour.

The monochrome display code included seems to be broken, at least on
Linux/XFree86 1.3.  I haven't tested it on any other X displays than
my one at home, however

LINUX CODE
The file linux.c was created, and it holds routines to allow POVray to
render to a VGA or SVGA display, so that non-X users can do something
besides look at the +V display.  The version in the binary is
statically linked to the 0.98 version of svgalib, the minimum required
version.  

 Specify the +D option according to the following table:
  +D0       The mode specified in GSVGAMODE, or 320x200x256 if none
  +D5       320x200x256
  +D6       320x240x256
  +D7       320x400x256
  +D8       360x480x256
  +DA       640x480x256
  +DB       800x600x256
  +DC      1024x768x256
  +DD     1280x1024x256
  +DE       320x200x32K
  +DF       320x200x64K
  +DG       320x200x16M
  +DH       640x480x32K	
  +DI       640x480x64K
  +DJ       640x480x16M
  +DK       800x600x32K
  +DL       800x600x64K
  +DM       800x600x16M
  +DN      1024x768x32K
  +DM      1024x768x65K
  +DO      1024x768x16M
  +DP     1280x1024x32K
  +DQ     1280x1024x64K
  +DR     1280X1024X16M

 Appending a U (IE +DIU) will turn off the dither effect that is in
 effect by default.

 Because the gl libraries do not support 2- and 16-color modes,
 selecting these modes will cause an error condition.  (0-4, 9, S-V)
 This will probably never be fixed, unless the gl libraries are made
 to support these modes.  Of course, I don't actually *check* for this
 happening..

 VC switching in svgalib is still not incredibly robust, so you may end
 up messing up your VCs beyond repair and have to reboot.  Take this up
 with SVGALIB's author, or instead quit wildly pressing alt-fkeys.

 For some reason, when dithering is in effect with unusually bright colors,
 the colors are sometimes displayed incorrectly and rather hideously.  I'm
 sure the cause for this one is obvious, but I sure can't see it.

FROM povinf.doc (Or, What Did I Just FTP?)

                  Persistence of Vision Raytracer
                           Version 2.0
                        Basic Information
                  -------------------------------

    The Persistence of Vision Raytracer creates three-dimensional,
photo-realistic images using a rendering technique called ray tracing.
It reads in a text file containing information describing the objects and
lighting in a scene and generates an image of that scene from the view
point of a camera also described in the text file. Ray tracing is not
a fast process by any means, but it produces very high quality images
with realistic reflections, shading, perspective, and other effects.

From whatsnew.doc: (For users of POV-Ray 1.0)

    What's New in POV-Ray 2.0
    -------------------------
    The following is not intended to be an all-inclusive list of every
    new feature, but should give experienced users a pretty good guide
    of what has been changed and what has been added.  Please refer to
    POVRAY.DOC for details.


    General:
    -------
  - Automatic bounding slabs for greatly enhanced rendering speed of
    most scenes.
  - Adding, subtracting, multiplying & dividing of floats & vectors.
  - Clock global variable for external animation support.
  - X, Y, and Z global vector constants.
  - Improved antialiasing routine with new commandline options.

    Commandline options:
    -------------------
  - Version switch for backwards compatibility.
  - Starting/ending column/row switches for trace window.
  - Relative/absolute values for trace window switches.
  - Antialiasing jitter scale value and toggle.
  - Number of antialiasing rays to shoot.
  - Internal "clock" setting for animations.


    Objects:
    -------
  - Soft penumbral shadows from extended area lights.
  - Smoother Bezier patches.
  - New simplified torus syntax.
  - Heightfield water_level now uses range 0-1 instead of 0-255.
  - Heightfields can now be clipped and used in CSG operations.
  - Heightfields can be phong-shaded with the "smooth" option.
  - New, improved finite cylinders, cones, and discs, with
    optional "capping" of cones and cylinders.
  - More versatile CSG unions have replaced the need for composites.
  - CSG texturing has been made much more flexible.
  - New "merge" removes internal boundaries between transparent
    unioned objects.

    Textures:
    --------
  - Hexagon pigment texture.
  - Radial pigment texture.
  - Mandelbrot pigment texture.
  - Texture attributes grouped into 3 independently scalable groups:
    pigment, normal, and finish.
  - TIR (Total Internal Reflection) for more realistic refraction.
  - Fractional Brownian Motion (fbm) turbulence controls.
  - Turbulence can now be used independently with any pigment or normal
    texture.
  - Optional vector-style turbulence values.
  - Background coloring.
  - Color maps can now be declared.
  - Frequency, phase keywords now available for use with color_maps.
  - Filter keyword replaces "alpha", letting us reserve alpha for other
    uses in the future.
  - Less restrictive distribution policy.  See POVLEGAL.DOC for
    details.

ABOUT THE SPEED OF POVRAY

I have run some simple tests comparing the Linux version with the DOS
version.  I don't have any firm numbers, but renders were "slightly"
faster on my Linux machine than under DOS.

I rendered "basicvue.pov" with the options
-w320 -h240 -a -d -f -v
on both DOS and Linux.  The machine is a 386/40+387 with 5 megabytes
ram.  Times were pretty close: 1 minutes 27 seconds under Linux, 1:35
under DOS.  

I was running several other programs under Linux at the same time, but
nothing too heavy (A 'term' connection at 14.4kbps, with several
remote shells).  On the DOS machine, I had loaded himem.sys but not
emm386.exe, and no other TSRs.

I plan to post some better numbers soon, by running pov-ray in single
user mode on a larger trace.  But it seems apparent to me that Linux
has a small but worthwhile advantage over DOS.  Now if only there were
good CAD systems for Linux or X that could output POV files. :(

FINAL NOTES
If you use a 486, I recommend that you get and compile binaries
yourself.  The change of the -m386 flag to -m486 should increase your
performance by an appreciable percentage.  I do not use this flag by
default as I do not have a 486.

If you have any problems with this software, please leave mail to me
and not any member of the POV-Team.  While it is unlikely that any of
the changes I have made have introduced bugs, it is possible.  (I'm
also supposed to provide this support according to the terms of
povlegal.doc)

Sorry if this "documentation" isn't too great.  While English is my
first language, that doesn't make me very good at it.  Also, I'd
rather be playing with POV-Ray than writing this and then reading it
to see if it made sense.  Hopefully it was enough that you can use the
software I've put together here.

Jeff Epler
jepler@herbie.unl.edu
jepler@nyx.cs.du.edu
