
@C4@M@bQuick Start


The next section describes how to quickly install POV-Ray and render sample
scenes on your computer. It is assumed that you are using an IBM-PC
compatible computer with MS-DOS. For other platforms you must refer to the
specific documentation included in archive that contains POV-Ray.

3.1              Installing POV-Ray

Specific installation instructions are included with the executable program
for your computer. In general, there are two ways to install POV-Ray.

[ Note that the generic word "directory" is used throughout. Your operating
system may use another word (subdirectory, folder, etc.) ]

1) The messy way: Create a directory called POVRAY and copy all POV-Ray files
into it. Edit and run all files and programs from this directory. This method
works, but is not recommended.

Or the preferred way:

2) Create a directory called POVRAY and several subdirectories called
INCLUDE, DEMO, SCENES, UTIL. The self-extracting archives used in some
versions of the program will create subdirectories for you. If you create
your own, the file tree for this should look something like this:

    \--
      |
      +POVRAY --
               |
               +INCLUDE
               |
               +DEMO
               |
               +SCENES
               |
               +UTIL


Copy the executable file and docs into the directory POVRAY. Copy the
standard include files into the subdirectory INCLUDE. Copy the sample scene
files into the subdirectory SCENES. And copy any POV-Ray related utility
programs and their related files into the subdirectory UTIL. Your own scene
files will go into the SCENES subdirectory. Also, you'll need to add the
directories \POVRAY and \POVRAY\UTIL to your "search path" so the executable
programs can be run from any directory.

Note that some operating systems don't have an equivalent to the multi-path
search command.

The second method is a bit more difficult to set-up, but is preferred. There
are many files associated with POV-Ray and they are far easier to deal with
when separated into several directories.

3.2              Basic Usage

Notice: If you did not install the program using the install.exe system, the
examples and instructions given here may not work! The installation process
configures povray.ini and several important batch files. Without these files
configured, the examples herein may not work.

POV-Ray's basic purpose is to read a scene description written in the POV
language and to write an image file. The scene files are plain ASCII text
files that you create using a text editor. Dozens of sample files are
included with this package to illustrate the various features.

You invoke POV-Ray by typing a command at the MS-DOS prompt. The command is
povray and it must be followed by one or more command line switches. Each
switch begins with a plus or minus sign. Blanks separate the switches. The
switches may be upper or lower case.

Note: The examples in this documentation assume you installed POV-Ray in the
c:\povray3 directory. The installer will let you install POV-Ray anywhere and
will properly configure it for the drive and directory you specified. You
just substitute that drive and directory anywhere we tell you to use
c:\povray3. Change to that directory now. Then type the following command
line and press [ENTER]

  POVRAY +ISHAPES +D1


The +I command (for input) tells the program what file to read as input. If
you don't give an extension on the file name, .pov is assumed. Thus +Ishapes
tells it to read in shapes.pov to be rendered.

The +D switch (for display) tells the program to turn the graphic preview
display on. A -D would turn it off. The number "1" tells it what type of
display to use. Type "1" is the old fashioned standard generic VGA at 320 by
200 resolution and just 256 colors. This is pretty much guaranteed to work on
any VGA video system.

There are other options in effect besides those you typed on the command
line. They are stored in a file called povray.ini which was created by the
install system. POV-Ray automatically looks for this file in the same
directory where povray.exe resides. See "INI Files" and "Using INI Files" for
more information on povray.ini and other INI files.

When you enter the command shown above, you will see brightly colored
geometric shapes begin to appear as POV-Ray calculates the color of each
pixel row by row. You will probably be disappointed with the graphic display
results. That is because this is only a preview display. The actual image is
in full 24-bit color but we cannot display that high quality using simple VGA
with a fixed set of 256 colors. If your hardware supports the VESA interface
standard or you have a VESA TSR driver loaded, try running with +DG rather
than +D1. This will give you access to all of the various modes your video
hardware can use. If you have 15-bit or 16- bit high color capability try
+DGH or if you have 24-bit true color capability try +DGT to see the image in
all its glory. See section "Display Types" below for more information on
graphics preview.

When the program finishes, you will hear beeps. After admiring the image,
press [ENTER]. You will see a text screen of statistics. If the text is too
much to fit on the screen you may press [CURSOR UP] or [CURSOR DOWN] keys to
read more text. Notice that there are tabs at the bottom of the screen. Press
[CURSOR LEFT] or [CURSOR RIGHT] keys to view other interesting text
information. Press [ENTER] again to exit POV-Ray.

If you do not have high color or true color ability you will have to view the
image file to see the real colors. The image file shapes.tga is written to
your current directory. By default POV-Ray creates files in TGA format. This
is a standard format for storing 24-bit true-color images. You will need an
image viewing program to view the file. Such programs are usually available
from the same place where you obtained POV-Ray but a viewer is not included
in this package.

If you cannot view TGA files you may add the switch +FN and POV-Ray will
output PNG (Portable Network Graphic) format. If PNG format viewer is not
available then type the following

  T2G SHAPES


and press [ENTER]. This will run a batch file that invokes the tga2gif
program. The program will read your shapes.tga file, create an optimal 256
color palette and write a GIF format file shapes.gif. Most image viewing
programs support GIF.

3.2.1            Running Files in Other Directories

Normally POV-Ray only looks in the current directory for the files it needs.
It does not search your MS-DOS path for data files; it only searches for
programs. In the sample scene you just ran, file shapes.pov was in the
current directory so this was no problem. That scene also needed other files
but your povray.ini file tells POV-Ray other places to search for necessary
files.

If you allowed the install system to update your autoexec.bat file, then you
can change to any drive or directory and can run POV-Ray from that directory.
You will also be able to use the batch files and utilities that came with
this package in any directory. For future reference let's call the
"use-c:\povray3-in-your-path-plan" as plan one.

There are some circumstances where you may not want to put c:\povray3 in your
path. There is a limit of 128 characters in your path statement and you may
not have room for it. Try rendering the shapes example from a different
directory. If it doesn't work, then you forgot to re-boot your system so the
new path takes effect. If after re-booting it still doesn't work, it probably
means your path is too full. You will have to adopt a different plan.

Chances are, you already have several directories in your path. Most systems
have c:\DOS, c:\windows or some directory such as c:\utility already in the
path. We have provided several small batch files that you can copy to that
directory. For future reference we'll call the
"put-batch-files-in-a-directory-already-on-the-path-plan" as plan  two.

At any DOS prompt, type the word path and press [ENTER]. It will show you
what directories are already on your path. Then copy the following files from
your c:\povray3 directory to any of the directories already on your path. The
files are:

  RUNPOV.BAT RERUNPOV.BAT RUNPHELP.BAT T2G.BAT


Once you have copied these files, try the following example. In this case, do
not invoke the program with the command povray. Instead use runpov as
follows:

  cd \POVRAY3\POV3DEMO\SHOWOFF
  RUNPOV +ISUNSET3 +D1


This changes to the \povray3\pov3demo\showoff directory where the file
sunset3.pov is found. It runs the file runpov.bat. That batch file is set up
to run POV-Ray even if it is not on the DOS path. It also passes the switches
along to POV-Ray. These batch files have other uses, even if you are using
plan one as described above or plan three as described below. For more on
these batch files, see "Batch Files".

All of the early examples in this document assumed you were running POV-Ray
from the directory where it was installed such as c:\povray3. This approach
of always using the installation directory is in fact plan three. If you are
using this method, you need to tell POV-Ray where else to look for files. In
the case of sunset3.pov you could do this:

  POVRAY +IC:\POVRAY3\POV3DEMO\SHOWOFF\SUNSET3 +D1


However some scenes need more than one file. For example the directory drums2
that can be found under \povray3\povscn\level3 contains three files:
drums.pov, drums.inc and rednewt.gif all of which are required for that one
scene. In this case you should use the +L switch (for library) to add new
library paths to those that POV-Ray will search. You would render the scene
with this command.

  POVRAY +L\POVRAY3\POVSCN\LEVEL3\DRUMS2 +IDRUMS +D1


3.2.2            INI Files

There were more options used in these renderings than just the switches +I,
+D, and +L that you specify. When you run the program, POV- Ray automatically
looks for the file povray.ini in whatever directory that povray.exe is in.
The povray.ini file contains many options that control how POV-Ray works. We
have set this file up so that it is especially easy to run your first scene
with minimal problems. The file should be placed in the same directory as
povray.exe and it will automatically read when POV-Ray is run. If you ever
move povray.exe to a different directory, be sure to move povray.ini too.

Complete details on all of the available switches and options that can be
given on the command line or in povray.ini are given in "POV-Ray Options".

You may also create INI files of your own with switches or options similar to
povray.ini. If you put a file name on the command line without a plus or
minus sign before it, POV-Ray reads it as an INI file. Try this...

  POVRAY RES120 +ISHAPES +D1


This causes POV-Ray to look for a file called res120.ini which we have
provided. It sets your resolution to 120 by 90 pixels for a quick preview.
The following INI files have been provided for you.

  SLOW.INIII           Turns on radiosity and anti-aliasing; very slow but
  ZIPFLI.INI ZIPFLC.INICreate an FLI/FLC animation from zipped images. See
                       "ANIMATION TIPS" below.


You can create your own custom INI's which can contain any command in the
reference guide.

3.2.3            Alternatives to POVRAY.INI

The povray.ini file is supposed to hold your favorite global default options
that you want to use all the time. You should feel free to edit it with new
options that suit your needs. However it must be located in the same
directory as povray.exe or it won't be found. The DOS path isn't searched nor
will +L commands help because povray.ini is processed before any command line
switches.

If your povray.exe resides on a CD-ROM then you can't edit the povray.ini on
the CD. There is an alternative. You may use an environment variable to
specify an alternative global default.

In your autoexec.bat file add a line similar to this:

  set POVINI=D:\DIRECT\FILE.INI


which sets the POVINI environment variable to whatever drive, directory and
INI file you choose. If you specify any POVINI environment variable then
povray.ini is not read. This is true even if the file you named doesn't
exist. Note that you are specifying an entire path and file name. This is not
a pointer to a directory containing povray.ini. It is a pointer to the actual
file itself.

Note that the POVRAYOPT environment variable in previous versions of POV-Ray
is no longer supported.

3.2.4            Batch Files

We've already described how the file runpov.bat can be used as an alternative
to running POV-Ray directly. runpov.bat also has one other use. It uses the
+GI switch to create a file called rerun.ini. This makes it very easy to run
the same file over again with the same parameters. When creating your own
scene files you will probably make dozens of test renders. This is a very
valuable feature. Here is how it works... Suppose you render a scene as
follows:

  RUNPOV +IMYSCENE +D1 RES120


This renders myscene.pov at 120 by 90 resolution. Note there is no such
scene. This is hypothetical. After viewing it, you noticed a mistake which
you fixed with your text editor. To rerun the scene type:

  RERUNPOV


and that's all. It will rerun the same scene you just ran. Suppose you want
more detail on the next run. You can add more switches or INI files. For
example:

  RERUNPOV RES320


will rerun at higher resolution. Subsequent uses of rerunpov will be at 320
by 200 until you tell it differently. As another example, the +A switch turns
on anti-aliasing. Typing "rerunpov +A" reruns with anti- aliasing on. All
subsequent reruns will have it on until you do a "rerunpov -A" to turn it
off. Note if you do another runpov it starts over from your povray.ini
defaults and it overwrites the old rerun.ini.

Two other batch files are included. runphelp.bat is only used as an
alternative way to run povhelp from another directory. If you used
installation plan two then use runphelp.bat rather than povhelp.exe. This
batch file serves no other purpose.

Finally t2g.bat invokes the tga2gif.exe program for converting TGA files to
GIF files. You could run \FILE {tga2gif} directly but its default parameters
do not generally produce the best results. If you use T2G instead, it adds
some command line switches which work better. For a full list of switches
available for tga2gif, type tga2gif with no parameters and it will display
the available switches and options.

3.2.5            Display Types

You have already seen how to turn on graphics preview using +D1. Here are
details on other variations of the +D switch. Use -D to turn the display off.
If you use -D then you will probably want to add the +V switch to turn on
verbose status messages so you can monitor the progress of the rendering
while in progress.

The number "1" after the +D tells it what kind of video hardware to use. If
you use +D alone or +D0 then POV-Ray will attempt to auto detect your
hardware type. Use +D? to see a message about what type of hardware POV-Ray
found.

You may also explicitly tell POV-Ray what hardware to use. The following
chart lists all of the supported types.

  +DIDiamond Computer Systems SpeedSTAR 24X


The most common type is a VESA standard card which uses +DG. VESA is a
standard software interface that works on a wide variety of cards. Those
cards which do not have VESA support directly built-in, generally have a
video driver that you can load to provide VESA support. The program UniVBE is
a high quality universal VESA driver that may work for you. It can be found
at http://www.povray.org or possibly other POV-Ray sites.

The options listed above had been tested worked under earlier versions of
POV-Ray but there have been many changes in the program and we cannot
guarantee these all still work. If you can use VESA then do so. It has been
well tested and will give you the most flexibility.

After the +D and the type, you may specify a 3rd character that specifies the
palette type.

  +D?3Use 332 palette with dithering (default and best for VGA systems). This
      is a fixed palette of 256 colors with each color consisting 3-bits of
  +D?0Use HSV palette option for VGA display. This is a fixed palette of 256
      colors where colors are matched according to hue, saturation and
  +D?HUse HiColor option. Displays more than 32,000 colors with dithering.
      Supported on VESA, SpeedSTAR 24X, ATI XL HiColor and Tseng 4000 based
  +D?TFor Truecolor 24 bit cards. Use 24 bit color. Supported on the Diamond
      SpeedSTAR 24X and cards with 24-bit VESA support only.


Here are some examples:

   +D0H Auto detect the VGA display type and display the image to the
        screen as it's being worked on. Use the 15-bit HiColor chip and
        dithering to display more than 32,000 colors on screen.
   +D4  Display to a TSENG 4000 chipset VGA using the 332 palette option.
   +D4H Display to a TSENG 4000 chipset VGA using the HiColor option.
   +DG0 Display to a VESA VGA adapter and use the HSV palette option.
   +DG3 Display to a VESA VGA adapter and use the 332 palette option.
   +DGH Display to a VESA VGA adapter and use the HiColor option for
        over 32,000 colors.
   +DGT Display to a VESA VGA adapter and use the TrueColor option for
        over 16 million colors.


Note that your VESA BIOS must support these options in order for you to use
them. Some cards may support HiColor and/or TrueColor at the hardware level
but not through their VESA BIOS.
