This file contains the documentation specific to the Linux version of
POV-Ray.  This archive contains both an X Windows and an SVGAlib version
of POV-Ray 3.0.1.  Either of these programs can also be run from a text
console without any graphical output.  Both binaries are in ELF
format.  Because the binaries are dynamically linked against either
libX11.so.6 or libvga.so.1 and libvgagl.so.1, you have to have one of
these libraries to run the corresponding version of POV-Ray, even if you
are not displaying anything.

The preferred location for installing POV-Ray for Linux is under
/usr/local/lib/povray3 for all of the INI, scene, and include files,
and /usr/local/bin for s-povray and x-povray.  Each user will also
need to have an INI file to tell POV-Ray where to look for these files.

The POV-Ray man page, povray.1, should be placed in a similarly accessible
location, such as /usr/local/man/man1.  If it is expected that many people
will be using one version of POV-Ray, it would be a good idea to edit
povray.1, under the section 'FILES' to specify where all of the
documentation, scenes, and include files are actually stored, if they
aren't installed as suggested above.


INI files:
   POV-Ray allows the use of files to store common configuration
   settings, such as the output format, image size, and library paths.
   If the environment variable POVINI is set, then POV-Ray will look at
   the file that POVINI is pointing to to read configuration
   information.  If POVINI is not set, then POV-Ray will try to read
   the file ".povrayrc" in your home directory, or failing this, it will
   try to read the file "povray.ini", in the current directory.  The
   POVRAYOPT environment variable is no longer used by POV-Ray.
    
   The default povray.ini file that is shipped with the Linux archive
   assumes that POV-Ray will be installed under /usr/local/lib/povray3.
   If you are not installing POV-Ray there, you should edit the Library_Path 
   specifications in this file to point to the location where POV-Ray is
   installed.  Each user should copy this file to ".povrayrc" in their home
   directory. 

   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.

X Windows display:
   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.  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 rendering 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 the icon, move it to the
   directory pointed to by your PixmapPath, often /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.
 
   The X-windows version also supports these standard command-line options
   in addition to those given in the generic POV-Ray documentation:
 
   -display <display name>           Preview on the specified display
   -geometry <WIDTHxHEIGHT+XXX+YYY>  Start with the given size and position
   -visual <visual type>             Use specified visual if available
   -title <title>                    Use the given title for the window
   -icon                             Start iconified
   -borderwidth <width>              Use a border of the given width in pixels
   -help                             Output these X Windows options
 
SVGAlib display:
   The SVGAlib version must be installed as a setuid root executable to
   be able to run properly.  This is a limitation imposed by libvga, and
   has nothing to do with POV-Ray.  If s-povray doesn't work (usually
   complaining about being unable to get I/O permissions) try (as root):

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

   And, 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 handle the 320x200 mode (ie regular VGA) should
   be fine, although modes up to 1280x1024x16M are possible.  If you do
   not have root privelidges or can't have the system administrator install
   POV-Ray, then you must use the X Windows version.  If you are using a
   display resolution that is lower than what you are rendering, the
   display will be scaled to fit into the viewing window.

File Formats:
   The default file format for Linux is "TGA" format (+ft).  Optionally,
   the "PPM" format, popular on UNIX platforms, or the new "PNG" format
   can be set as the default output format by setting "Output_File_Type = p"
   or "Output_File_Type = n" in your .povrayrc file or by using +fp or +fn
   on the command-line.
 
   The documentation included with POV-Ray for Linux is in ACSII text
   format.  The scene files for generating the images that belong with
   the documentation are located in the docscn subdirectory.  The
   documentation is also available separately in HTML format, including
   all of the images, at ftp.povray.org/pub/povray/Official/3.0-beta/
   or wherever you got your copy of povlinux.tar.gz.

   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.  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 are running on a console.
   XV 3.10a is usually included with Linux distributions, and can be used
   under X Windows to view PPM and TGA files, although 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, available at the PNG home page
   http://www.wco.com/~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 Andreas
Dilger.  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.

Andreas Dilger
Internet:   adilger@povray.org  or adilger@enel.ucalgary.ca
