                     Persistence of Vision Ray Tracer
                               Version 3.6
                        UNIX Specific Documentation


   This file contains generic information for running POV-Ray on UNIX
   systems.  It briefly describes the UNIX-specific features of POV-Ray
   from configuration and command-line perspectives.  As such, it is not
   a replacement for the HTML user documentation located in the doc/html
   directory (chapter 1 in particular).  This document also does not cover
   the program installation which is described in either the INSTALL file
   (for the generic UNIX source distribution) or in the README file (for
   the PC-Linux binary distribution).


Executables

   Official executables of POV-Ray for UNIX are only provided for the
   x86 (and compatible) platform running the GNU/Linux operating system.
   Due to the very large variety of UNIX platforms, the POV-Team cannot
   provide official binaries for all of them.  However, since POV-Ray
   is also available as a source package, recompiling the source for
   your target system shouldn't cause a problem.  Note that if you want
   to distribute an executable created by yourself, you must comply with
   the POV-Ray License Agreement (povlegal.doc).

   The official GNU/Linux (a free UNIX variant) version is available as
   povlinux-3.6.tgz (or povlinux-3.6.tar.gz).  The generic UNIX source
   distribution is available as povray-3.6.tgz (or povray-3.6.tar.gz).
   Both binary and source packages can be found at the following sites:

     - The POV-Ray website, www.povray.org in the Download section.
     - 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
       website.  These are listed in /pub/povray/README.MIRRORS at
       ftp.povray.org .  You should try to use the closest site for
       faster downloads.

   povlinux-3.6.tgz contains a very generic povray executable that should
   run on most GNU/Linux distributions with a 2.2 kernel or above.  It is
   a fully static binary that should not depend on any installed library.
   The povray executable includes support for X Window and SVGA display
   (see below).  It comes with an install script that installs POV-Ray
   into the /usr/local prefix or any directory you have write access to.
   Vendor-specific package formats such as RedHat RPM or Debian DEB are
   not available at the moment.


File locations

   The default location for installing POV-Ray for UNIX is under
   /usr/local/share/povray-3.6 for all INI, scene, and include files,
   and /usr/local/bin for the povray binary itself.  The POV-Ray man page
   is by default installed into /usr/local/man/man1 .  The system-level
   povray.ini and povray.conf files, which store default settings for
   POV-Ray, are installed in the /usr/local/etc/povray/3.6 directory.  
   The default installation location can be changed from /usr/local
   to another directory when installing the PC-Linux binary or when
   configuring the source package of POV-Ray.  See the relevant install
   documentation for further details.  When installing POV-Ray (binary
   and source distributions) the povray.ini and povray.conf files are
   also placed under the $HOME/.povray/3.6 directory.  Refer to the
   user documentation for INI and I/O restriction settings.


INI files

   POV-Ray allows the use of INI 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 the user "povray.ini" file (located under
   $HOME/.povray/3.6) or, otherwise, the system-level "povray.ini" (by
   default in /usr/local/etc/povray/3.6).  If none of these work, for
   backward compatibility with version 3.5 and earlier, POV-Ray finally
   searches for INI files as "$HOME/.povrayrc" or otherwise a "povray.ini"
   file in PREFIX/etc (where PREFIX is /usr/local by default).

   The other INI files found under the ini/ directory, such as 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.  They can be customized
   to use whatever programs you have installed.


CONF files

   POV-Ray 3.5 has introduced the I/O Restriction feature as an attempt
   to at least partially protect a machine running the program to perform
   forbidden file operation and/or run external programs.  I/O Restriction
   settings are specified in a "povray.conf" configuration file.  There are
   two configuration levels within POV-Ray for UNIX: a system and a user-
   level configuration.  The system-level povray.conf file (by default in
   /usr/local/etc/povray/3.6) is intended for system administrators to
   setup minimal restrictions for the system on which POV-Ray will run.
   The user $HOME/.povray/3.6/povray.conf file allows further restrictions
   to be set.  For obvious security reasons, the user's settings can only
   be more (or equally) restrictive than the system-level settings.  See
   chapter 1 of the documentation for details.  In POV-Ray 3.6 the format
   of the configuration file has changed and is not backward compatible
   with POV-Ray 3.5.  Note that I/O Restrictions are still subject to the
   operating system permissions.  Also the feature is not mature enough,
   especially since it has been completely reworked in the UNIX version
   of POV-Ray 3.6.


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.  The second way requires the X Window System to be installed
   on your machine, which should be the case on most UNIX systems.  The
   X Window System allows full-color display of any image size, and at
   any screen resolution and color depth.  Some limited user interactions
   with the display are also allowed.  The third way is specific to
   GNU/Linux systems and allows to display the rendered image directly
   on the console screen using the SVGA library.  Both X Window and SVGA
   displays are discussed in more detail below.


X Window Display

   Using the X Window display allows you to preview the image using any
   kind of visual, at any depth, and even 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.

   Depending on your window manager (e.g. KDE, Gnome, fvwm), POV-Ray may
   use a color icon for the window (in the title bar) and its corresponding
   button in the task bar.  The use of a color icon also depends on whether
   the POV-Ray executable has been linked with the Xpm library.  The latter
   is usually shipped with the X Window System.  In case the Xpm library
   cannot be used, a built-in monochrome icon is used instead.  Some
   window managers also need to be configured in order to use the color
   icon.  The "xpovicon.xpm" file can be used in this case, but the exact
   procedure depends on the window manager.  The following shows how to
   make the fvwm window manager use this icon.  First, copy the icon file
   to one of the directories listed by PixmapPath (or ImagePath) in your
   $HOME/.fvwmrc configuration file.  Second, edit the latter to add the
   following line:

     Style "Povray" Icon xpovicon.xpm

   Third, restart the X server (e.g. by typing 'startx' on the console).
   Restarting fvwm alone will not be enough.

   In POV-Ray 3.6 the X Window display comes with a gray/white checkered
   background by default, instead of the black color implemented in the
   earlier versions.  The new default background is particularly useful
   when rendering images using the alpha channel (+UA option).  In case
   you don't feel comfortable with this default background, you can make
   POV-Ray for UNIX use a custom background image instead.  The user-
   supplied background image must be placed under the $HOME/.povray/3.6
   directory as "background.ext" (where "ext" is either "jpg", "jpeg",
   "png", "ppm", "tga" or "gif"); for instance "background.png".  The
   filename must be all lowercase.  POV-Ray will detect the image format
   depending on the filename extension (so this is different from the
   other image-related features in the POV-Ray scene description language).
   In case you place several background.* files under $HOME/.povray/3.6
   the first file matching the list of extensions given above will be used.
   For instance, POV-Ray will use "background.jpg" if both "background.jpg"
   and "background.tga" are present.  Note there is not support for the
   TIFF format at the moment, since TIFF support is still an experimental
   feature in POV-Ray 3.6.  Also the background image is NOT output to
   the rendered image file, so you cannot use it as e.g. an image map.
   IMPORTANT NOTE: the user-supplied background image is an EXPERIMENTAL
   feature and is specific to the X Window display of POV-Ray for UNIX.
   No provision is made that this new feature will be available in future
   releases of POV-Ray.

   When POV-Ray is compiled with support for the X Window display, the
   program also understands the standard X Window 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 Window specific options


SVGAlib display

   For GNU/Linux systems that don't have the X Window System installed,
   it is possible to use the SVGA library (SVGAlib) to display directly
   to the screen.  The POV-Ray binary using SVGAlib must be installed as
   a setuid root executable to be able to run properly.  If it doesn't
   work (usually complaining about being unable to get I/O permissions)
   first try (as root):

     chown root.root povray
     chmod 4755 povray

   IMPORTANT NOTE: doing this may have 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 your system admin
   install POV-Ray for you, then you should rather use the X Window or
   text-only display, 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.


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.  When using a rendering display, 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 (PBMPLUS, NetPBM) and ImageMagick
   are an excellent choice for post-processing tools, especially if you
   only have a command-line interface to UNIX:
     http://www.acme.com/software/pbmplus
     http://netpbm.sourceforge.net
     http://www.imagemagick.org

   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, since specifing the '-' output filename
   (+o option) tells POV-Ray to send the output image data to stdout, which
   is piped through cjpeg in this example.


Questions and problems with POV-Ray for UNIX should be posted on the
news.povray.org news server under the povray.unix newsgroup.  This news
server also has a web interface at http://news.povray.org/groups/ .
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

Revised for POV-Ray 3.6 by Nicolas Calimet <pov4grasp@free.fr>
