Section 7.2
Language Directives

The POV Scene Language contains several statements called language directives which tell the file parser how to do its job. These directives can appear in almost any place in the scene file - even in the middle of some other statements. They are used to include other text files in the stream of commands, to declare identifiers, to define conditional or looped parsing and to control other important aspects of scene file processing.

Each directive begins with the hash character # (often called a number sign or pound sign). It is followed by a keyword and optionally other parameters.

In versions of POV-Ray prior to 3.0, the use of this # character was optional. Language directives could only be used between objects, camera or light_source statements and could not appear within those statements. The exception was the #include which could appear anywhere. Now that all language directives can be used almost anywhere, the # character is mandatory.

The following keywords introduce language directives.


#break              #default            #statistics
#case               #else               #switch
#debug              #end                #version
#declare            #render             #warning


Earlier versions of POV-Ray considered the keyword
#max_intersections and the keyword #max_trace_level to
be language directives but they have been moved to the
global_settings statement. Their use as a directive still works
but it generates a warning and may be discontinued in the future.

Section 7.2.1
Include Files

The language allows include files to be specified by placing the line

#include "filename.inc"

at any point in the input file. The filename may be specified by any valid string expression but it usually is a literal string enclosed in double quotes. It may be up to 40 characters long (or your computer's limit), including the two double-quote characters.

The include file is read in as if it were inserted at that point in the file. Using include is the same as actually cutting and pasting the entire contents of this file into your scene.

Include files may be nested. You may have at most 10 nested include files. There is no limit on un-nested include files.

Generally, include files have data for scenes but are not scenes in themselves. By convention scene files end in .pov and include files end with .inc.

It is legal to specify drive and directory information in the file specification however it is discouraged because it makes scene files less portable between various platforms.

It is typical to put standard include files in a special sub-directory. POV-Ray can only read files in the current directory or one referenced by the Library_Path option (See section "Library Paths").

Section 7.2.2
Declare

Identifiers may be declared and later referenced to make scene files more readable and to parametrize scenes so that changing a single declaration changes many values. There are several built-in identifiers which POV-Ray declares for you. See section "Built-in Identifiers" for details.

Section 7.2.2.1
Declaring identifiers

An identifier is declared as follows.

#declare IDENTIFIER = ITEM

Where IDENTIFIER is the name of the identifier up to 40 characters long and ITEM is any of the following

float, vector, color or string expressions objects (all kinds) texture, pigment, normal, finish or halo color_map, pigment_map, slope_map, normal_map camera, light_source atmosphere fog rainbow sky_sphere transform

Here are some examples.

#declare Rows = 5 #declare Count = Count+1 #declare Here = <1,2,3> #declare White = rgb <1,1,1> #declare Cyan = color blue 1.0 green 1.0 #declare Font_Name = "ariel.ttf" #declare Ring = torus {5,1} #declare Checks = pigment { checker White, Cyan } object{ Rod scale y*5 } // not "cylinder { Rod }" object { Ring pigment { Checks scale 0.5 } transform Skew }

Declarations, like most language directives, can appear anywhere in the file - even within other statements. For example:

#declare Here=<1,2,3> #declare Count=0 // initialize Count union { object { Rod translate Here*Count } #declare Count=Count+1 // re-declare inside union object { Rod translate Here*Count } #declare Count=Count+1 // re-declare inside union object { Rod translate Here*Count } }

As this example shows, you can re-declare an identifier and may use previously declared values in that re-declaration. However if you attempt to re-declare an identifier as anything other than its original type, it will generate a warning message.

Declarations may be nested inside each other within limits. In the example in the previous section you could declare the entire union as a object. However for technical reasons you may not use any language directive inside the declaration of floats, vectors or color expressions.

Section 7.2.3
Default Directive

POV-Ray creates a default texture when it begins processing. You may change those defaults as described below. Every time you specify a texture statement, POV-Ray creates a copy of the default texture. Anything you put in the texture statement overrides the default settings. If you attach a pigment, normal or finish to an object without any texture statement then POV-Ray checks to see if a texture has already been attached. If it has a texture then the pigment, normal or finish will modify the existing texture. If no texture has yet been attached to the object then the default texture is copied and the pigment, normal or finish will modify that texture.

You may change the default texture, pigment, normal or finish using the language directive #default as follows:

#default { texture { pigment {...} normal {...} finish {...} } }

Or you may change just part of it like this:

#default { pigment {...} }

This still changes the pigment of the default texture. At any time there is only one default texture made from the default pigment, normal and finish. The example above does not make a separate default for pigments alone. Note that the special textures tiles and material_map or a texture with a texture_map may not be used as defaults.

You may change the defaults several times throughout a scene as you wish. Subsequent #default statements begin with the defaults that were in effect at the time. If you wish to reset to the original POV-Ray defaults then you should first save them as follows:

//At top of file #declare Original_Default = texture {}

later after changing defaults you may restore it with...

#default {texture {Original_Default}}

If you do not specify a texture for an object then the default texture is attached when the object appears in the scene. It is not attached when an object is declared. For example:

#declare My_Object = sphere{ <0,0,0>, 1 } // Default texture not applied object { My_Object } // Default texture added here

You may force a default texture to be added by using an empty texture statement as follows:

#declare My_Thing = sphere { <0,0,0>, 1 texture {} } // Default texture applied

The original POV-Ray defaults for all items are given throughout the documentation under each appropriate section.

Section 7.2.4
Version Directive

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 +MV1.0 command line switch or the Version=1.0 INI option 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 is used to change modes within scene files. This switch or INI options only affects the initial setting.

Together with the built-in version identifier the #version directive allows you to save and restore the previous values of this compatibility setting. For example suppose mystuff.inc is in version 1.0 format. At the top of the file you could put:

#declare Temp_Vers = version // Save previous value #version 1.0 // Change to 1.0 mode ... // Version 1.0 stuff goes here ... #version Temp_Vers // Restore previous version

Previous versions of POV-Ray would not allow you to change versions inside an object or declaration but that restriction has been lifted for POV-Ray 3.0.

Future versions of POV-Ray may not continue to maintain full backward compatibility even with the #version directive. We strongly encourage you to phase in 3.0 syntax as much as possible.

Next Section
Table Of Contents