                 Persistence of Vision Ray Tracer
                           Version 3.5
                    Unix Specific Documentation

   This file contains the documentation specific to compiling POV-Ray
   on Unix systems.  Those who have compiled earlier versions of 
   POV-Ray will notice significant changes in the build 
   infrastructure, as POV-Ray now uses autoconf and automake, which 
   allow the creation of portable configure scripts.  This should 
   eliminate the need for manual editing of makefiles and should 
   generally improve portability.

   The configure script should support all the standard configure
   options.  More may be added with time.  For complete details, 
   run "configure --help".

   POV-Ray may not compile directly on all systems as is.  Every effort
   has been made to make it compile on as many systems as we have access
   to.  If you have problems compiling, try checking with a local Unix
   guru first.  If you still have problems and have internet access,
   check out the comp.graphics.rendering.raytracing newsgroup.  The 
   POV-Team also has newsgroups at news.povray.org that are not
   distributed on the Internet.  The povray.unix group on this server
   is a useful resource for those who may be having difficult
   compiling POV-Ray on various Unix systems.  Make sure you read the 
   FAQ first (if you don't see it, ask for it.)

   If you are trying to compile POV-Ray on an unsupported platform,
   this version is the best one to use as a base.  The platform
   specific configuration is in the file config.h, so it is possible
   that you can change the configuration to suit your system without
   changing any code.

Executables:
   Official executables are provided for only glibc 2.2 GNU/Linux on 
   x86 because there are so many possible Unix executable formats.  In 
   general, however, Unix systems come bundled with a C compiler, so 
   recompiling the source for your target system shouldn't cause a 
   problem. If you want to distribute an executable created by yourself 
   you must comply with POVLEGAL.DOC.

   An official GNU/Linux (a free Unix variant) version is available as 
   povlinux.tgz.  If you can't find it at the same place you got this 
   from, and don't want to compile it yourself from the Unix directory, 
   then try one of the following sites:

     - The POV-Ray FTP site, ftp.povray.org in /pub/povray/Official/Linux.
     - There are many sites around the world that mirror the povray.org
       site.  These are listed in README.MIRRORS at ftp.povray.org, and
       you should try to use the closest site for the best speed.
     - We also have a web site with a link to the binary. Point your
       browser at http://www.povray.org/.

   povlinux.tgz is a very generic binary package, dynamically linked
   against glibc 2.2, statically linked against various other
   libraries for greater binary compatibility.  It comes with an
   install script that installs POV-Ray into the /usr/local prefix.
   Packages may be made available in other formats (rpm, dpkg) at a
   later date.

File locations:
   The default location for installing POV-Ray for Unix is under
   /usr/local/lib/povray35 for all of the INI, scene, and include files,
   and /usr/local/bin for the povray binary itself.  Each user will also 
   need to have an INI file, actually called .povrayrc on Unix systems
   and located in $HOME, to tell POV-Ray where to look for these files.
   The POV-Ray man page, is by default installed into /usr/local/man/man1.  
   The default can be changed from /usr/local to another directory using
   the --prefix flag to the configure script.  For example, to build
   POV-Ray such that it will be installed in /usr, run:
   configure --prefix=/usr

INI files:
   POV-Ray allows the use of files to store common configuration
   settings, such as the output format, image size, and library paths.
   Upon startup, the Unix version of POV-Ray will use the environment
   variable POVINI to determine custom configuration information if \
   that environment variable is set.  Otherwise, it will look for the 
   file "povray.ini" in the current directory.  If neither of these works,
   then POV-Ray will try to read a file called ".povrayrc" stored
   in the user's home directory.  If none of these work, then POV-Ray will
   try to read the file "povray.ini" in a default system-wide directory 
   defined at compile time (/usr/local/lib/povray35 by default).
   Each user should copy the system-wide "povray.ini" file to 
   "$HOME/.povrayrc".

   The file gamma.gif.txt explains how to find the correct
   Display_Gamma value for your .povrayrc file using the gamma.gif
   image.  As this is specific to each display, you may need to make
   separate INI files to include on the command line if you are using
   various displays that have different gamma characteristics.

   The other INI files, like zipfli.ini and tgaflc.ini are of limited
   use under Unix, but are included as examples of how to automate
   operations from within POV-Ray, and can be customized to use
   whatever programs you have installed.

Display Formats:
   There are two different methods of displaying images as they are
   rendered with POV-Ray on most Unix systems, and an additional
   display method on GNU/Linux systems. The first way is the text format,
   which can output a crude 75x24 ASCII version of the image, to give an
   idea of what POV-Ray is doing.  This doesn't work very well if you
   are also using the Verbose (+v) status output.  It also isn't very
   satisfying for the output of a ray tracer, but may be useful in some
   cases.

X Windows Display:
   Alternately, if you have X-Windows, you can compile in the X-Windows
   display capability.  This will allow you to preview the image using
   any kind of visual, at any depth, and remotely if desired.  During
   rendering, the window will be updated after every scanline has been
   rendered, or sooner if the rendering is taking a long time.  To
   update it sooner you can click any mouse button in the window or
   press (almost) any key.  Pressing <CTRL-R> or <CTRL-L> during
   rendering will refresh the whole screen.  If you have the Exit_Enable
   or +X flag set, pressing 'q' or 'Q' at any time during the rendering
   will stop POV-Ray rendering and exit.  The rendering will pause when
   complete if the Pause_When_Done (or +P) flag is set.  To exit at
   this point, press the 'q' or 'Q' key or click any mouse button in
   the window.

   The xpovicon.xpm is a color icon for use with fvwm or other window
   manager which can use external icons.  To have fvwm use this icon,
   move the icon to the directory pointed to by your PixmapPath, usually
   /usr/include/X11/pixmaps/, add the following line to your .fvwmrc:

       Style "Povray" Icon xpovray.xpm

   and re-start X Windows.  Re-starting fvwm will not be enough.  If you
   don't restart, or choose not to do this this, POV-Ray will use a
   similar built-in monochrome icon.  Using this icon with another window
   manager may use a different procedure.

   The X-windows version also supports these standard command-line options
   in addition to those given in the generic POV-Ray documentation.  See
   the X(1) man page for further explanation of these options.

   -display <display name>           Preview on the specified display
   -geometry <WIDTHxHEIGHT+XXX+YYY>  Start with the given size/position
   -visual <visual type>             Use specified visual if available
   -title <title>                    Use the given title for the window
   -icon                             Start iconified
   -owncmap                          Force POV-Ray to use a private colormap
   -borderwidth <width>              Use a border of the given width
   -help                             Output these X Windows options

SVGAlib display:
   For GNU/Linux systems that don't have X Windows installed, it is
   possible to use the libvga library to display directly to the
   screen, similar to the MS-DOS version.  The SVGAlib version must be
   installed as a setuid root executable to be able to run properly.
   If s-povray doesn't work (usually complaining about being unable to
   get I/O permissions) first try (as root):

       chown root.root s-povray
       chmod 4755 s-povray

   NOTE: Given the likely number of exploitable buffer overflows in
   POV-Ray, doing this has serious security implications.  Running
   POV-Ray as root or through sudo might be a better idea.
   If it still doesn't work then make sure svgalib is installed on your
   machine and works properly (sdoom is a good way of doing this :-).
   Anything that can at least use the 320x200x256 mode (ie regular VGA)
   should be fine, although modes up to 1280x1024x16M are possible.  If
   you do not have root priviledges or can't have the system admin
   install POV-Ray, then you must use the X Windows or text-only
   version, which do not require any special system priviledges to
   run.  If you are using a display resolution that is lower than what
   you are rendering, the display will be scaled to fit as much of the
   viewing window as possible.

File Formats:
   The default file format for Unix is "targa" format (+ft).
   Optionally, the "PPM" format, popular on Unix platforms, or the
   new "PNG" format can be set as the default format by setting
   DEFAULT_FILE_FORMAT = 'p' or DEFAULT_FILE_FORMAT = 'n' in the
   unixconf.h file before compiling, by using +fp or +fn on the
   command-line or with "Output_File_Type = p" "Ouput_File_Type = n" in
   your .povrayrc file.  There is more information about output file
   formats in the POV-Ray documentation.

   The documentation included with POV-Ray for Unix is in HTML format.
   The documentation is also available separately in PDF and Microsoft 
   Word document formats, including all of the images, at: 
   ftp://ftp.povray.org/pub/povray/Official/Docs/ or wherever you got 
   your copy of this archive.

   If you are generating histogram files in the CSV format (comma
   separated values), then the units of time are in tens of microseconds
   (10 x 10^-6 s), and each grid block can store times up to 12 hours.

Interrupting POV-Ray:
   To interrupt a rendering in progress, you can use CTRL-C (SIGINT),
   which will allow POV-Ray to finish writing out any rendered data
   before it quits.  For the two display versions, you can also press
   the 'q' or 'Q' keys in the rendering preview window to interrupt the
   trace if the Test_Abort (or +X) flag is set.

Post-processing Images:
   For Unix systems, the PBM utilities are an excellent choice for
   post-processing utilities, especially if you only have a command-line
   interface to Unix.  XV 3.10a is also commonly installed at Unix sites,
   and can be used under X Windows to view PPM and TGA files, but XV 3.00
   cannot view TGA images.  There is also a patch to XV 3.10a to allow it
   to read and write PNG format images, although you will have to
   re-compile XV in order to use it.  The PNG patch for XV, as well as lots
   of other PNG information is available at the PNG home page
   http://quest.jpl.nasa.gov/PNG/.

   POV-Ray can also pipe its output directly into a post-processor.  For
   example, 'povray -iscene.pov -fp -o- | cjpeg > scene.jpg' will create
   a JPEG output file, because specifing an output filename of '-' to
   POV-Ray tells it to pipe its output to stdout, which is piped through
   cjpeg in this example.

Questions and problems with Unix versions can be directed to Mark Gordon
Please make sure you have consulted with a local Unix person first if 
you think the problem is likely to be on your end.  If you are installing 
POV-Ray in a publicly accessible location, you must read and comply with 
the 'Online or Remote Execution' conditions in POVLEGAL.DOC.

Mark Gordon
Internet:   mtgordon@povray.org




