Section 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.

Section 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

Section 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.

RES120.INISets resolution to 120 by 90.
RES320.INISets resolution to 320 by 200.
RES640.INISets resolution to 640 by 480.
RES800.INISets resolution to 800 by 600.
RES1K.INISets resolution to 1024 by 768.
LOW.INISets low quality at 120 by 90.
SLOW.INITurns on radiosity and anti-aliasing; very slow but beautiful.
TGAFLI.INI TGAFLC.INICreate an FLI/FLC animation from TGA images.
PNGFLI.INI PNGFLC.INICreate an FLI/FLC animation from DTA images.
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.

Next Section
Table Of Contents