home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_povray.idb / usr / freeware / lib / povray31 / README.unix.z / README.unix
Encoding:
Text File  |  1999-04-16  |  13.3 KB  |  258 lines
  1.                  Persistence of Vision Ray Tracer
  2.                            Version 3.1e
  3.                     Unix Specific Documentation
  4.  
  5. New in version 3.1:
  6.    The scene description language in POV-Ray 3.1 is not entirely
  7.    backwards-compatible with earlier versions of the POV-Ray scene
  8.    description language.  The 'halo' feature in earlier versions
  9.    is obsolete and has been entirely replaced with a 'media' feature 
  10.    which works better.  Because older files making use of 'halo' 
  11.    will not render in POV-Ray 3.1 without substantial modification,
  12.    you may wish to rename executables for pre-3.1 versions of POV-Ray 
  13.    if you would like to be able to render such older files.  It should
  14.    be noted that .povrayrc as described below can only refer to one
  15.    version.
  16.  
  17. Files:
  18.    If this file has ^M's in it when you're reading it under Unix, then
  19.    you need to make sure that when you extract the source files and
  20.    Unix specific code from the archive it came in, that you tell the
  21.    de-archiver to convert CR-LF's to LF's in text files.
  22.  
  23.    The widely-distributed Info-Zip archiver does this if you supply
  24.    '-a' on the command-line, i.e. 'unzip -a <archive name>'. You may
  25.    also like to use 'unzip -aL <archive name>' if the filenames are
  26.    extracted in upper-case.  Care should be taken when unzipping the
  27.    scene files with older versions of unzip, since using the -a switch
  28.    may corrupt the binary files in the archive (ie GIF and TTF files).
  29.    If you don't see [binary] or [text] after each file, you will need
  30.    to 'unzip -a <archive name>', then 'unzip <archive name> "*.gif"
  31.    "*.ttf" "*.iff"' to get good copies of the binary files (the double
  32.    quotes are needed to avoid file name expansion by the shell).
  33.  
  34.    If you received these files in a .tar.gz (or .tgz) archive then this
  35.    has already been done for you.
  36.  
  37.    This file contains the documentation specific to compiling POV-Ray
  38.    on Unix systems.  Due to the wide variety of Unix systems available,
  39.    POV-Ray may not compile directly on all systems as is.  Every effort
  40.    has been made to make it compile on as many systems as we have access
  41.    to.  If you have problems compiling, try checking with a local Unix
  42.    guru first.  If you still have problems and have internet access,
  43.    check out the comp.graphics.rendering.raytracing newsgroup.  Make sure
  44.    you read the FAQ first (if you don't see it, ask for it.)  Please do
  45.    not contact the POV-Team about problems with compiling POV-Ray.
  46.  
  47.    If you are trying to compile POV-Ray on an unsupported platform,
  48.    this version is the best one to use as a base.  The platform
  49.    specific configuration is in the file config.h, so it is possible
  50.    that you can change the configuration to suit your system without
  51.    changing any code.
  52.  
  53.    This archive does not, however, contain any of the documentation and
  54.    files actually needed to USE POV-Ray.  The documentation and example
  55.    scene files are available in the file POVUNI_D.TGZ, which should be
  56.    available at the same place you got this archive, and it is also in
  57.    the Linux archive (povlinux.tgz).
  58.  
  59. Executables:
  60.    Official executables are provided for only Linux on x86 systems 
  61.    because there are so many possible Unix executable formats.  Since
  62.    the POV-Ray team does not have ready access to other platforms for
  63.    testing and debugging, we are unable to support other Unix platforms.
  64.    In general, however, Unix systems come bundled with a C compiler, so 
  65.    recompiling the source for your target system shouldn't cause a 
  66.    problem. If you want to distribute an executable created by yourself 
  67.    you must comply with POVLEGAL.DOC.
  68.  
  69.    An official Linux (a free Unix variant) version is available as 
  70.    povlinux.tgz.  If you can't find it at the same place you got this 
  71.    from, and don't want to compile it yourself from the Unix directory, 
  72.    then try one of the following sites:
  73.  
  74.      - The POV-Ray FTP site, ftp.povray.org in /pub/povray/Official/Linux.
  75.      - There are many sites around the world that mirror the povray.org
  76.        site.  These are listed in README.MIRRORS at ftp.povray.org, and
  77.        you should try to use the closest site for the best speed.
  78.      - Compuserve's GRAPHDEV forum. (GO GRAPHDEV).
  79.      - We also have a web site with a link to the binary. Point your
  80.        browser at http://www.povray.org/.
  81.  
  82. File locations:
  83.    The preferred location for installing POV-Ray for Unix is under
  84.    /usr/local/lib/povray31 for all of the INI, scene, and include files,
  85.    and /usr/local/bin for povray, x-povray, and/or s-povray.  Each user
  86.    will also need to have an INI file, actually called .povrayrc on
  87.    Unix systems, to tell POV-Ray where to look for these files.
  88.  
  89.    The POV-Ray man page, povray.1, should be placed in a similarly
  90.    accessible location, such as /usr/local/man/man1.  If it is expected
  91.    that many people will be using one version of POV-Ray, it would be a
  92.    good idea to edit povray.1, under the section 'FILES' to specify
  93.    where all of the documentation, scenes, and include files are
  94.    actually stored, if they aren't installed as suggested above.
  95.  
  96. INI files:
  97.    POV-Ray allows the use of files to store common configuration
  98.    settings, such as the output format, image size, and library paths.
  99.    Upon startup, the Unix version of POV-Ray will use the environment
  100.    variable POVINI to determine custom configuration information if \
  101.    that environment variable is set.  Otherwise, it will look for the 
  102.    file "povray.ini" in the current directory.  If neither of these works,
  103.    then POV-Ray will try to read a file called ".povrayrc" stored
  104.    in the user's home directory.  If none of these work, then POV-Ray will
  105.    try to read the file "povray.ini" in a default system-wide directory 
  106.    defined at compile time (/usr/local/lib/povray31 by default).  If it 
  107.    will be stored in a different location, POV-Ray should be recompiled 
  108.    for this option to work.  It is defined by POVLIBDIR in the makefile.  
  109.    The POVRAYOPT environment variable used by earlier versions of POV-Ray
  110.    is no longer used.
  111.  
  112.    The default povray.ini file that is shipped with the Unix archive
  113.    assumes that POV-Ray will be installed under /usr/local/lib/povray31.
  114.    If you are not installing POV-Ray there, you should edit the
  115.    Library_Path specifications in this file to point to the location
  116.    where POV-Ray is installed.  Each user should copy this file to
  117.    ".povrayrc" in their home directory.
  118.  
  119.    The file gamma.gif.txt explains how to find the correct
  120.    Display_Gamma value for your .povrayrc file using the gamma.gif
  121.    image.  As this is specific to each display, you may need to make
  122.    separate INI files to include on the command line if you are using
  123.    various displays that have different gamma characteristics.
  124.  
  125.    The other INI files, like zipfli.ini and tgaflc.ini are of limited
  126.    use under Unix, but are included as examples of how to automate
  127.    operations from within POV-Ray, and can be customized to use
  128.    whatever programs you have installed.
  129.  
  130. Display Formats:
  131.    There are two different methods of displaying images as they are
  132.    rendered with POV-Ray on most Unix systems, and an additional
  133.    display method on Linux systems. The first way is the text format,
  134.    which can output a crude 75x24 ASCII version of the image, to give an
  135.    idea of what POV-Ray is doing.  This doesn't work very well if you
  136.    are also using the Verbose (+v) status output.  It also isn't very
  137.    satisfying for the output of a ray tracer, but may be useful in some
  138.    cases.
  139.  
  140. X Windows Display:
  141.    Alternately, if you have X-Windows, you can compile in the X-Windows
  142.    display capability.  This will allow you to preview the image using
  143.    any kind of visual, at any depth, and remotely if desired.  During
  144.    rendering, the window will be updated after every scanline has been
  145.    rendered, or sooner if the rendering is taking a long time.  To
  146.    update it sooner you can click any mouse button in the window or
  147.    press (almost) any key.  Pressing <CTRL-R> or <CTRL-L> during
  148.    rendering will refresh the whole screen.  If you have the Exit_Enable
  149.    or +X flag set, pressing 'q' or 'Q' at any time during the rendering
  150.    will stop POV-Ray rendering and exit.  The rendering will pause when
  151.    complete if the Pause_When_Done (or +P) flag is set.  To exit at
  152.    this point, press the 'q' or 'Q' key or click any mouse button in
  153.    the window.
  154.  
  155.    The xpovicon.xpm is a color icon for use with fvwm or other window
  156.    manager which can use external icons.  To have fvwm use this icon,
  157.    move the icon to the directory pointed to by your PixmapPath, usually
  158.    /usr/include/X11/pixmaps/, add the following line to your .fvwmrc:
  159.  
  160.        Style "Povray" Icon xpovray.xpm
  161.  
  162.    and re-start X Windows.  Re-starting fvwm will not be enough.  If you
  163.    don't restart, or choose not to do this this, POV-Ray will use a
  164.    similar built-in monochrome icon.  Using this icon with another window
  165.    manager may use a different procedure.
  166.  
  167.    The X-windows version also supports these standard command-line options
  168.    in addition to those given in the generic POV-Ray documentation.  See
  169.    the X(1) man page for further explanation of these options.
  170.  
  171.    -display <display name>           Preview on the specified display
  172.    -geometry <WIDTHxHEIGHT+XXX+YYY>  Start with the given size/position
  173.    -visual <visual type>             Use specified visual if available
  174.    -title <title>                    Use the given title for the window
  175.    -icon                             Start iconified
  176.    -owncmap                          Force POV-Ray to use a private colormap
  177.    -borderwidth <width>              Use a border of the given width
  178.    -help                             Output these X Windows options
  179.  
  180. SVGAlib display:
  181.    For Linux systems that don't have X Windows installed, it is
  182.    possible to use the libvga library to display directly to the
  183.    screen, similar to the MS-DOS version.  The SVGAlib version must be
  184.    installed as a setuid root executable to be able to run properly.
  185.    If s-povray doesn't work (usually complaining about being unable to
  186.    get I/O permissions) first try (as root):
  187.  
  188.        chown root.root s-povray
  189.        chmod 4755 s-povray
  190.  
  191.    If it still doesn't work then make sure svgalib is installed on your
  192.    machine and works properly (sdoom is a good way of doing this :-).
  193.    Anything that can at least use the 320x200x256 mode (ie regular VGA)
  194.    should be fine, although modes up to 1280x1024x16M are possible.  If
  195.    you do not have root priviledges or can't have the system admin
  196.    install POV-Ray, then you must use the X Windows or text-only
  197.    version, which do not require any special system priviledges to
  198.    run.  If you are using a display resolution that is lower than what
  199.    you are rendering, the display will be scaled to fit as much of the
  200.    viewing window as possible.
  201.  
  202. File Formats:
  203.    The default file format for Unix is "targa" format (+ft).
  204.    Optionally, the "PPM" format, popular on Unix platforms, or the
  205.    new "PNG" format can be set as the default format by setting
  206.    DEFAULT_FILE_FORMAT = 'p' or DEFAULT_FILE_FORMAT = 'n' in the
  207.    unixconf.h file before compiling, by using +fp or +fn on the
  208.    command-line or with "Output_File_Type = p" "Ouput_File_Type = n" in
  209.    your .povrayrc file.  There is more information about output file
  210.    formats in the POV-Ray documentation.
  211.  
  212.    The documentation included with POV-Ray for Unix is in ACSII text
  213.    format.  The documentation is also available separately in PDF, HTML, 
  214.    and Microsoft Word 97 document formats, including all of the images, 
  215.    at: ftp://ftp.povray.org/pub/povray/Official/Docs/ or wherever you got 
  216.    your copy of this archive.
  217.  
  218.    If you are generating histogram files in the CSV format (comma
  219.    separated values), then the units of time are in tens of microseconds
  220.    (10 x 10^-6 s), and each grid block can store times up to 12 hours.
  221.  
  222. Interrupting POV-Ray:
  223.    To interrupt a rendering in progress, you can use CTRL-C (SIGINT),
  224.    which will allow POV-Ray to finish writing out any rendered data
  225.    before it quits.  For the two display versions, you can also press
  226.    the 'q' or 'Q' keys in the rendering preview window to interrupt the
  227.    trace if the Test_Abort (or +X) flag is set.
  228.  
  229. Post-processing Images:
  230.    For Unix systems, the PBM utilities are an excellent choice for
  231.    post-processing utilities, especially if you only have a command-line
  232.    interface to Unix.  XV 3.10a is also commonly installed at Unix sites,
  233.    and can be used under X Windows to view PPM and TGA files, but XV 3.00
  234.    cannot view TGA images.  There is also a patch to XV 3.10a to allow it
  235.    to read and write PNG format images, although you will have to
  236.    re-compile XV in order to use it.  The PNG patch for XV, as well as lots
  237.    of other PNG information is available at the PNG home page
  238.    http://quest.jpl.nasa.gov/PNG/.
  239.  
  240.    POV-Ray can also pipe its output directly into a post-processor.  For
  241.    example, 'povray -iscene.pov -fp -o- | cjpeg > scene.jpg' will create
  242.    a JPEG output file, because specifing an output filename of '-' to
  243.    POV-Ray tells it to pipe its output to stdout, which is piped through
  244.    cjpeg in this example.
  245.  
  246. Questions and problems with Unix versions can be directed to Mark Gordon
  247. Please make sure you have consulted with a local Unix person first if 
  248. you think the problem is likely to be on your end.  If you are installing 
  249. POV-Ray in a publicly accessible location, you must read and comply with 
  250. the 'Online or Remote Execution' conditions in POVLEGAL.DOC.
  251.  
  252. Mark Gordon
  253. Internet:   mtgordon@mailbag.com
  254.  
  255.  
  256.  
  257.  
  258.