Section 6.2.3
Scene Parsing Options

POV-Ray reads in your scene file and processes it to create an internal model of your scene. The process is called parsing. As your file is parsed other files may be read along the way. This section covers options concerning what to parse, where to find it and what version specific assumptions it should make while parsing it.

Section 6.2.3.1
Input File Name

Input_File_Name=fileSets input file name to file
+IfileSame as Input_File_Name=file

You will probably always set this option but if you do not the default input filename is object.pov. If you do not have an extension then .pov is assumed. On case-sensitive operating systems both .pov and .POV are tried. A full path specification may be used (on MS-DOS systems +Ic:\povray3\mystuff\myfile.pov is allowed for example). In addition to specifying the input file name this also establishes the scene name.

The scene name is the input name with drive, path and extension stripped. In the above example the scene name is myfile. This name is used to create a default output file name and it is referenced other places.

If you use "-" as the input file name the input will be read from standard input. Thus you can pipe a scene created by a program to POV-Ray and render it without having a scene file.

Under MS-DOS you can try this feature by typing.

type ANYSCENE.POV | povray +I-

Section 6.2.3.2
Library Paths

Library_Path=pathAdd path to list of library paths
+LpathSame as Library_Path=path

POV-Ray looks for files in the current directory. If it does not find a file it needs it looks in various other library directories which you specify. POV-Ray does not search your operating system path. It only searches the current directory and directories which you specify with this option. For example the standard include files are usually kept in one special directory. You tell POV-Ray to look there with...

Library_Path=c:\povray3\include

You must not specify any final path separators ("\" or "/") at the end.

Multiple uses of this option switch do not override previous settings. Up to ten unique paths may be specified. If you specify the exact same path twice it is only counts once. The current directory will be searched first followed by the indicated library directories in the order in which you specified them.


Section 6.2.3.3
Language Version

Version=n.nSet initial language compatibility to version n.n
+MVn.nSame as Version=n.n

While many language changes have been made for POV-Ray 3.0, all of version 2.0 syntax and most of version 1.0 syntax still works. Whenever possible we try to maintain backwards compatibility. One feature introduced in 2.0 that was incompatible with any 1.0 scene files is the parsing of float expressions. Setting Version=1.0 or using +MV1.0 turns off expression parsing as well as many warning messages so that nearly all 1.0 files will still work. The changes between 2.0 and 3.0 are not as extensive. Setting Version=2.0 is only necessary to eliminate some warning messages. Naturally the default setting for this option is Version=3.0.

The #version language directive can also be used to change modes several times within scene files. The above options affect only the initial setting. See section "Version Directive" for more details about the language version directive.


Section 6.2.3.4
Removing User Bounding

Remove_Bounds=boolTurn unnecessary bounds removal on/off
+URTurn unnecessary bounds removal on
-URTurn unnecessary bounds removal off
Split_Unions=boolTurn split bounded unions on/off
+SUTurn split bounded unions on
-SUTurn split bounded unions off

Early versions of POV-Ray had no system of automatic bounding or spatial sub-division to speed up ray-object intersection tests. Users had to manually create bounding boxes to speed up the rendering. POV-Ray 3.0 has more sophisticated automatic bounding than any previous version. In many cases the manual bounding on older scenes is slower than the new automatic systems. Therefore POV-Ray removes manual bounding when it knows it will help. In rare instances you may want to keep manual bounding. Some older scenes incorrectly used bounding when they should have used clipping. If POV-Ray removes the bounds in these scenes the image will not look right. To turn off the automatic removal of manual bounds you should specify Remove_Bounds=off or use -UR. The default is Remove_Bounds=on.

One area where the jury is still out is the splitting of manually bounded unions. Unbounded unions are always split into their component parts so that automatic bounding works better. Most users do not bound unions because they know that doing so is usually slower. If you do manually bound a union we presume you really want it bound. For safety sake we do not presume to remove such bounds. If you want to remove manual bounds from unions you should specify Split_Unions=on or use +SU. The default is Split_Unions=off.


Section 6.2.4
Shell-out to Operating System

Pre_Scene_Command=sSet command before entire scene
Pre_Frame_Command=sSet command before each frame
Post_Scene_Command=sSet command after entire scene
Post_Frame_Command=sSet command after each frame
User_Abort_Command=sSet command when user aborts POV-Ray
Fatal_Error_Command=sSet command when POV-Ray has fatal error

Note that no +/- switches are available for these options. They cannot be used from the command line. They may only be used from INI files.

POV-Ray offers you the opportunity to shell-out to the operating system at several key points to execute another program or batch file. Usually this is used to manage files created by the internal animation loop however the shell commands are available for any scene. The CMD is a single line of text which is passed to the operating system to execute a program. For example

Post_Scene_Command=tga2gif -d -m myfile

would use the utility tga2gif with the -D and -M parameters to convert myfile.tga to myfile.gif after the scene had finished rendering.


Section 6.2.4.1
String Substitution in Shell Commands

It could get cumbersome to change the Post_Scene_Command every time you changed scene names. POV-Ray can substitute various values into a CMD string for you. For example:

Post_Scene_Command=tga2gif -d -m %s

POV-Ray will substitute the %s with the scene name in the command. The scene name is the Input_File_Name or +I setting with any drive, directory or extension removed. For example:

Input_File_Name=c:\povray3\scenes\waycool.pov

is stripped down to the scene name waycool which results in...

Post_Scene_Command=tga2gif -d -m waycool

In an animation it may be necessary to have the exact output file name with the frame number included. The string %o will substitute the output file name. Suppose you want to save your output files in a zip archive using pkzip. You could do...

Post_Frame_Command=pkzip -m %s %o

After rendering frame 12 of myscene.pov POV-Ray would shell to the operating system with "pkzip -m myscene mysce012.tga". The -M switch in pkzip moves mysce012.tga to myscene.zip and removes it from the directory. Note that %o includes frame numbers only when in an animation loop. During the Pre_Scene_Command and Post_Scene_Command there is no frame number so the original, unnumbered Output_File_Name is used. Any User_Abort_Command or Fatal_Error_Command not inside the loop will similarly give an unnumbered %o substitution.

Here is the complete list of substitutions available for a common string.

%oOutput file name with extension and embedded frame number if any
%sScene name derived by stripping path and ext from input name
%nFrame number of this frame
%kClock value of this frame
%hHeight of image in pixels
%wWidth of image in pixels
%%A single % sign.

Section 6.2.4.2
Shell Command Sequencing

Here is the sequence of events in an animation loop. Non-animated scenes work the exact same way except there is no loop.

  1)  Process all INI file keywords and command line switches just once.
  2)  Open any text output streams and do Create_INI if any.
  3)  Execute Pre_Scene_Command if any.
  4)  Loop through frames (or just do once on non-animation).
      a)  Execute Pre_Frame_Command if any.
      b)  Parse entire scene file, open output file and read settings,
          turn on display, render the frame, destroy all objects,
          textures etc., close output file, close display.
      c)  Execute Post_Frame_Command if any.
      d)  Go back to 4 a until all frames are done.
  5)  Execute Post_Scene_Command if any.
  6)  Exit POV-Ray.

If the user interrupts processing the User_Abort_Command, if any, is executed. User aborts can only occur during the parsing and rendering parts of step 4 a above.

If a fatal error occurs that POV-Ray notices the Fatal_Error_Command, if any, is executed. Sometimes an unforeseen bug or memory error could cause a total crash of the program in which case there is no chance to shell out. Fatal errors can occur just about anywhere including during the processing of switches or INI files. If a fatal error occurs before POV-Ray has read the Fatal_Error_Command string then obviously no shell can occur.

Note that the entire scene is re-parsed for every frame. Future versions of POV-Ray may allow you to hold over parts of a scene from one frame to the next but for now it starts from scratch every time. Note also that the Pre_Frame_Command occurs before the scene is parsed. You might use this to call some custom scene generation utility before each frame. This utility could rewrite your .pov or .inc files if needed. Perhaps you will want to generate new .gif or .tga files for image maps or height fields on each frame.


Next Section
Table Of Contents