1.2.8.2 Using INI Files

Note: although the term 'INI file' is used by POV-Ray, this was implemented before the widespread acceptance of Microsoft Windows, and while POV-Ray's INI files are almost identical to those of Windows, there are some minor differences (the foremost being that it is legal to have multiple instances of the same item in a section). INI files are used on all platform versions of POV-Ray, not just on the Windows platform.

Because it is difficult to set more than a few options on a command line, you have the ability to put multiple options in one or more text files. These initialization files or INI files have .ini as their default extension. Previous versions of POV-Ray called them default files or DEF files. You may still use existing DEF files with this version of POV-Ray.

The majority of options you use will be stored in INI files. The command line switches are recommended for options which you will turn off or on frequently as you perform test renderings of a scene you are developing. The file povray.ini is automatically read if present. You may specify additional INI files on the command-line by simply typing the file name on the command line. For example:

  POVRAY MYOPTS.INI

If no extension is given, then .ini is assumed. POV-Ray knows this is not a switch because it is not preceded by a plus or minus.

You may have multiple INI files on the command line along with switches. For example:

  POVRAY MYOPTS +V OTHER

This reads options from myopts.ini, then sets the +V switch, then reads options from other.ini.

An INI file is a plain ASCII text file with options of the form...

  Option_keyword=VALUE ; Text after semicolon is a comment

For example the INI equivalent of the switch +Isimple.pov is...

  Input_File_Name=simple.pov

Options are read top to bottom in the file but in general may be specified in any order. If you specify an option more than once, the previous values are generally overwritten with the last specification. The only exception is the Library_Path=path options. Up to 25 unique paths may be specified.

Almost all INI-style options have equivalent + or - switches. The option reference section gives a detailed description of all POV-Ray options. It includes both the INI-style settings and the +/- switches.

The INI keywords are not case sensitive. Only one INI option is permitted per line of text. You may also include switches in your INI file if they are easier for you. You may have multiple switches per line but you should not mix switches and INI options on the same line. You may nest INI files by simply putting the file name on a line by itself with no equals sign after it. Nesting may occur up to ten levels deep. For example:

  ; This is a sample INI file. This entire line is a comment.
  ; Blank lines are permitted.
  Input_File_Name=simple.pov ;This sets the input file name
  +W80 +H60 ; Traditional +/- switches are permitted too
  MOREOPT   ; Read MOREOPT.INI and continue with next line
  +V        ; Another switch
  ; That's all folks!

INI files may have labeled sections so that more than one set of options may be stored in a single file. Each section begins with a label in [] brackets. For example:

  ; RES.INI
  ; This sample INI file is used to set resolution.
  +W120 +H100  ; This section has no label.
               ; Select it with "RES"
  [Low]
  +W80 +H60    ; This section has a label.
               ; Select it with "RES[Low]"
  [Med]
  +W320 +H200  ; This section has a label.
               ; Select it with "RES[Med]"
  [High]
  +W640 +H480  ; Labels are not case sensitive.
               ; "RES[high]" works
  [Really High]
  +W800 +H600  ; Labels may contain blanks

When you specify the INI file you should follow it with the section label in brackets. For example...

  POVRAY RES[Med] +Imyfile.pov

POV-Ray reads res.ini and skips all options until it finds the label Med. It processes options after that label until it finds another label and then it skips. If no label is specified on the command line then only the unlabeled area at the top of the file is read. If a label is specified, the unlabeled area is ignored.

If a file or path contains blanks the whole file and path specification has to be put in quotes. You may either use a double-quote oir a single-quote, but you have to use the same at the beginning and end. For example:

 +I"my file.pov"
 +I'my file.pov'
 Input_File="my file.pov"
 Input_File='my file.pov'

By using either single or double quotes it is possible to specify files whose name or path contains either as part of the name. For example:

 +I"file's.pov"
 +I'my "big" file.pov'
 Input_File="file's.pov"
 Input_File='my "big" file.pov'