Section 1
Introduction

This document details the use of the Persistence of Vision(tm) Ray-Tracer (POV-Ray(tm)). It is broken down into four parts: the installation guide, the tutorial guide, the reference guide and the appendix. The first part (see chapter "Program Description" and chapter "Quick Start") tells you where to get and how to install POV-Ray. It also gives a short introduction to ray-tracing. The tutorial explains step by step how to use the different features of POV-Ray (see chapter "Beginning Tutorial"). The reference gives a complete description of all features available in POV-Ray by explaining all available options (set either by command line switches or by INI file keywords) and the scene description language (see chapter "POV-Ray Reference", chapter "POV-Ray Options" and chapter "Scene Description Language"). The appendix includes some tips and hints, suggested reading, contact addresses and legal information.

POV-Ray(tm) is based on DKBTrace 2.12 by David K. Buck and Aaron A. Collins.


Section 1.1
Notation

Throughout this document the following notation is used to mark keywords of the scene description language, command line switches, INI file keywords and file names.

  name  scene description keyword
  name  command line option
  name  INI file keyword
  name  file name
  name  Internet address, Usenet group

In the plain ASCII version of the document there is no difference between the different notations.


Section 2
Program Description

The Persistence of Vision(tm) Ray-Tracer 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.

Section 2.1
What is Ray-Tracing?

Ray-tracing is a rendering technique that calculates an image of a scene by shooting rays into the scene. The scene is built from shapes, light sources, a camera, materials, special features, etc.

For every pixel in the final image one or more viewing rays are shot into the scene and tested for intersection with any of the objects in the scene. Viewing rays originate from the viewer, represented by the camera, and pass through the viewing window (representing the final image).

Every time an object is hit, the color of the surface at that point is calculated. For this purpose the amount of light coming from any light source in the scene is determined to tell whether the surface point lies in shadow or not. If the surface is reflective or translucent new rays are set up and traced in order to determine the contribution of the reflected and refracted light to the final surface color.

Special features like inter-diffuse reflection (radiosity), atmospheric effects and area lights make it necessary to shoot a lot of additional rays into the scene for every pixel.


Section 2.2
What is POV-Ray?

The Persistence of Vision(tm) Ray-Tracer was developed from DKBTrace 2.12 (written by David K. Buck and Aaron A. Collins) by a bunch of people, called the POV-Team(tm), in their spare time. The headquarters of the POV-Team is in the POVRAY forum on CompuServe (see "POV-Ray Forum on CompuServe" for more details).

The POV-Ray(tm) package includes detailed instructions on using the ray-tracer and creating scenes. Many stunning scenes are included with POV-Ray so you can start creating images immediately when you get the package. These scenes can be modified so you don't have to start from scratch.

In addition to the pre-defined scenes, a large library of pre-defined shapes and materials is provided. You can include these shapes and materials in your own scenes by just including the name of the shape or material and their name of their appropriate source file.

Here are some highlights of POV-Ray's features:

*Easy to use scene description language.
*Large library of stunning example scene files.
*Standard include files that pre-define many shapes, colors and textures.
*Very high quality output image files (up to 48-bit color).
*15 and 24 bit color display on IBM-PC's using appropriate hardware.
*Create landscapes using smoothed height fields.
*Spotlights, cylindrical lights and area lights for sophisticated lighting.
*Phong and specular highlighting for more realistic-looking surfaces.
*Inter-diffuse reflection (radiosity) for more realistic lighting.
*Atmospheric effects like atmosphere, fog and rainbow.
*Halos to model effects like clouds, dust, fire and steam.
*Several image file output formats including Targa, PNG and PPM.
*Basic shape primitives such as ... spheres, boxes, quadrics, cylinders, cones, triangles and planes.
*Advanced shape primitives such as ... torii (donuts), bezier patches, height fields (mountains), blobs, quartics, smooth triangles, text, fractals, superquadrics, surfaces of revolution, prisms, polygons, lathes and fractals.
*Shapes can easily be combined to create new complex shapes using Constructive Solid Geometry (CSG). POV-Ray supports unions, merges, intersections and differences.
*Objects are assigned materials called textures (a texture describes the coloring and surface properties of a shape).
*Built-in color and normal patterns: Agate, Bozo, Bumps, Checker, Crackle, Dents, Granite, Gradient, Hexagon, Leopard, Mandel, Marble, Onion, Quilted, Ripples, Spotted, Sprial, Radial, Waves, Wood, Wrinkles and image file mapping.
*Users can create their own textures or use pre-defined textures such as ... Brass, Chrome, Copper, Gold, Silver, Stone, Wood.
*Combine textures using layering of semi-transparent textures or tiles of textures or material map files.
*Display preview of image while computing (not available on all platforms).
*Halt rendering when part way through.
*Continue rendering a halted partial scene later.

Section 2.3
Which Version of POV-Ray should you use?

POV-Ray can be used under MS-DOS, Windows 3.x, Windows for Workgroups 3.11, Windows 95, Windows NT, Apple Macintosh 68k, Power PC, Commodore Amiga, Linux, UNIX and other platforms.

The latest versions of the necessary files are available over CompuServe, Internet, America Online and several BBS's. See section "Where to Find POV-Ray Files" for more info.


Section 2.3.1
IBM-PC and Compatibles

Currently there are three different versions for the IBM-PC running under different operating systems (MS-DOS, Windows and Linux) as described below.

Section 2.3.1.1
MS-DOS

The MS-DOS version runs under MS-DOS or as a DOS application under Windows 95, Windows NT, Windows 3.1 or Windows for Workgroups 3.11. It also runs under OS/2 and Warp.

Required hardware and software:

-A 386 or better CPU and at least 4 meg of RAM.
-About 6 meg disk space to install and 2-10 meg or more beyond that for working space.
-A text editor capable of editing plain ASCII text files. The EDIT program that comes with MS-DOS will work for moderate size files.
-Graphic file viewer capable of viewing GIF and perhaps TGA and PNG formats.

Required POV-Ray files:

-POVMSDOS.EXE - a self-extracting archive containing the program, sample scenes, standard include files and documentation in a hypertext help format with help viewer. This file may be split into smaller files for easier downloading. Check the directory of your download or ftp site to see if other files are needed.

Recommended:

-Pentium or 486dx or math co-processor for 386 or 486sx.
-8 meg or more RAM.
-SVGA display preferably with VESA interface and high color or true color ability.

Optional: The source code is not needed to use POV-Ray. It is provided for the curious and adventurous.

-POVMSD_S.ZIP - The C source code for POV-Ray for MS-DOS Contains generic parts and MS-DOS specific parts. It does not include sample scenes, standard include files and documentation so you should also get the executable archive as well
-A C compiler that can create 32-bit protected mode applications. We support Watcom 10.5a, Borland 4.52 with DOS Power Pack and limited graphics under DJGPP 1.12maint4. DJGPP 2.0 not supported.

Section 2.3.1.2
Windows

The Windows version runs under Windows'95, Windows NT and under Windows 3.1 or 3.11 if Win32s extensions are added. Also runs under OS/2 Warp.

Required hardware and software:

-A 386 or better CPU and at least 8 meg of RAM.
-About 12 meg disk space to install and 2-10 meg or more beyond that for working space.

Required POV-Ray files:

-User archive POVWIN3.EXE - a self-extracting archive containing the program, sample scenes, standard include files and documentation. This file may be split into smaller files for easier downloading. Check the directory of your download or ftp site to see if other files are needed.

Recommended:

-Pentium or 486dx or math co-processor for 386 or 486sx.
-16 meg or more RAM.
-SVGA display preferably with high color or true color ability and drivers installed.

Optional: The source code is not needed to use POV-Ray. It is provided for the curious and adventurous.

-POVWIN_S.ZIP --- The C source code for POV-Ray for Windows. Contains generic parts and Windows specific parts. It does not include sample scenes, standard include files and documentation so you should also get the executable archive as well.
-POV-Ray can only be compiled using C compilers that create 32-bit Windows applications. We support Watcom 10.5a, Borland 4.52/5.0 compilers. The source code is not needed to use POV-Ray. It is provided for the curious and adventurous.

Section 2.3.1.3
Linux

Required hardware and software:

-A 386 or better CPU and at least 4 meg of RAM.
-About 6 meg disk space to install and 2-10 meg or more beyond that for working space.
-A text editor capable of editing plain ASCII text files.
-Any recent (1994 onwards) Linux kernel and support for ELF format binaries. POV-Ray for Linux is not in a.out-format.
-ELF libraries libc.so.5, libm.so.5 and one or both of libX11.so.6 or libvga.so.1.

Required POV-Ray files:

-POVLINUX.TGZ or POVLINUX.TAR.GZ - archive containing an official binary for each SVGALib and X-Windows modes. Also contains sample scenes, standard include files and documentation.

Recommended:

-Pentium or 486dx or math co-processor for 386 or 486sx.
-8 meg or more RAM.
-SVGA display preferably high color or true color ability.
-If you want display, you'll need either SVGALib or X-Windows.
-Graphic file viewer capable of viewing PPM, TGA or PNG formats.

Optional: The source code is not needed to use POV-Ray. It is provided for the curious and adventurous.

-POVUNI_S.TAR.GZ or POVUNI_S.TGZ - The C source code for POV-Ray for Linux. Contains generic parts and Linux specific parts. It does not include sample scenes, standard include files and documentation so you should also get the executable archive as well.
-The GNU C compiler and (optionally) the X include files and libraries and KNOWLEDGE OF HOW TO USE IT. Although we provide source code for generic Unix systems, we do not provide technical support on how to compile the program.

Section 2.3.2
Apple Macintosh

The Macintosh versions run under Apple's MacOS operating system version 7.0 or better, on any 68020/030/040-based Macintosh (with or without a floating point coprocessor) or any of the Power Macintosh computers.

Required hardware and software:

-A 68020 or better CPU without a floating point unit (LC or Performa or Centris series) and at least 8 meg RAM or
-A 68020 or better CPU *with* a floating point unit (Mac II or Quadra series) and at least 8 meg RAM or
-Any Power Macintosh computer and at least 8 meg RAM.
-System 7 or newer and color QuickDraw (System 6 is no longer supported).
-About 6 meg free disk space to install and an additional 2-10 meg free space for working space.
-Graphic file viewer utility capable of viewing Mac PICT, GIF and perhaps TGA and PNG formats (the shareware GIFConverter or GraphicConverter applications are good.)

Required POV-Ray files:

-POVMACNF.SIT or POVMACNF.SIT.HQX - a Stuffit archive containing the non-FPU 68K Macintosh application, sample scenes, standard include files and documentation (slower version for Macs without an FPU) or
-POVMAC68.SIT or POVMAC68.SIT.HQX - a Stuffit archive containing the FPU 68K Macintosh application, sample scenes, standard include files and documentation (faster version for Macs WITH an FPU) or
-POVPMAC.SIT or POVPMAC.SIT.HQX - a Stuffit archive containing the native Power Macintosh application, sample scenes, standard include files and documentation.

Recommended:

-68030/33 or faster with FPU, or any Power Macintosh
-8 meg or more RAM for 68K Macintosh; 16 meg or more for Power Macintosh systems.
-Color monitor preferred, 256 colors OK, but thousands or millions of colors is even better.

Optional: The source code is not needed to use POV-Ray. It is provided for the curious and adventurous. POV-Ray can be compiled using Apple's MPW 3.3, Metrowerks CodeWarrior 8 or Symantec 8.

-POVMACS.SIT or POVMACS.SIT.HQX - The full C source code for POV-Ray for Macintosh. Contains generic parts and Macintosh specific parts. It does not include sample scenes, standard include files and documentation so you should also get the executable archive as well.

Section 2.3.3
Commodore Amiga

The Amiga version comes in several flavors: 68000/68020 without FPU (not recommended, very slow), 68020/68881(68882), 68030/68882 and 68040. There are also two sub-versions, one with a CLI-only interface, and one with a GUI (requires MUI 3.1). All versions run under OS2.1 and up. Support exists for pensharing and window display under OS3.x with 256 color palettes and CybeGFX display library support.

Required:

-at least 4 meg of RAM.
-at least 2 meg of hard disk space for the necessities, 5-20 more recommended for workspace.
-an ASCII text editor, GUI configurable to launch the editor of your choice.
-Graphic file viewer - POV-Ray outputs to PNG, Targa (TGA) and PPM formats, converters from the PPMBIN distribution are included to convert these to IFF ILBM files.

Required POV-Ray files:

-POVAMI.LHA - a LHA archive containing executable, sample scenes, standard include files and documentation.

Recommended:

-8 meg or more of RAM.
-68030 and 68882 or higher processor.
-24-bit display card (CyberGFX library supported)

As soon as a stable compiler is released for Amiga PowerPC systems, plans are to add this to the flavor list.

Optional: The source code is not needed to use POV-Ray. It is provided for the curious and adventurous.

-POVLHA_S.ZIP - The C source code for POV-Ray for Amiga. Contains generic parts and Amiga specific parts. It does not include sample scenes, standard include files and documentation so you should also get the executable archive as well.

Section 2.3.4
SunOS

Required hardware and software:

-A Sun SPARC processor and at least 4 meg of RAM.
-About 6 meg disk space to install and 2-10 meg or more beyond that for working space.
-A text editor capable of editing plain ASCII text files.
-SunOS 4.1.3 or other operating system capable of running such a binary (Solaris or possibly Linux for Sparc).

Required POV-Ray files:

-POVSUNOS.TGZ or POVSUNOS.TAR.GZ - archive containing an official binary for each text-only and X-Windows modes. Also contains sample scenes, standard include files and documentation.

Recommended:

-8 meg or more RAM.
-If you want display, you'll need X-Windows or an X-Term.
-preferably 24-bit TrueColor display ability, although the X display code is known to work with ANY combination of visual and color depth.
-Graphic file viewer capable of viewing PPM, TGA or PNG formats.

Optional: The source code is not needed to use POV-Ray. It is provided for the curious and adventurous.

-POVUNI_S.TGZ or POVUNI_S.TAR.GZ - The C source code for POV-Ray for UNIX. Contains generic UNIX parts and Linux specific parts. It does not include sample scenes, standard include files and documentation so you should also get the executable archive as well.
-A C compiler and (optionally) the X include files and libraries and knowledge of how to use it.

Although we provide source code for generic Unix systems, we do not provide technical support on how to compile the program.


Next Section
Table Of Contents