Previous:Command Line Switches Main Index Next:Using the POVINI Environment Variable

### Using INI Files

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. In fact a common error among new users is that they forget to put the `+I` switch before the input file name. Without the switch, POV-Ray thinks that the scene file `simple.pov` is an INI file. Don't forget! If no plus or minus precedes a command line switch, it is assumed to be an INI file name.

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

Because a blank space is considered a delimiter for command-line switches, POV-Ray has a difficult time reading file names or INI labels containing blanks. The rule is that INI-style options allow blanks in INI files but switches do not allow blanks whether in INI files or on the command line. For example:

     +Imy file.pov               ;doesn't work anywhere

     Input_File=my file.pov      ;works only in INI file

To nest INI files which have blanks in the file name or labels use the `Include_INI` option like this:

      Input_File=my file.pov

      Include_Ini=my options[this section]

Previous:Command Line Switches Main Index Next:Using the POVINI Environment Variable