Section 7.2.5
Conditional Directives

POV-Ray 3.0 allows a variety of new language directives to implement conditional parsing of various sections of your scene file. This is especially useful in describing the motion for animations but it has other uses as well. Also available is a #while loop directive. You may nest conditional directives 200 levels deep.

Section 7.2.5.1
IF ELSE Directives

The simplest conditional directive is a traditional #if directive. It is of the form...

#if (COND) // This section is // parsed if COND is true #else // This section is // parsed if COND is false #end // End of conditional part

where (COND) is a float expression that evaluates to a boolean value. A value of 0.0 is false and any non-zero value is true. Note that extremely small values of about 1e-10 are considered zero in case of round off errors. The parentheses around the condition are required. The #else directive is optional. The #end directive is required.

Section 7.2.5.2
IFDEF Directives

The #ifdef directive is similar to the #if directive however it is used to determine if an identifier has been previously declared. After the #ifdef directive instead of a boolean expression you put a lone identifier enclosed in parentheses. For example:

#ifdef (User_Thing) // This section is parsed if the // identifier "User_Thing" was // previously declared object{User_Thing} // invoke identifier #else // This section is parsed if the // identifier "User_Thing" was not // previously declared box{<0,0,0>,<1,1,1>} // use a default #end // End of conditional part

The #else directive is optional. The #end directive is required.

Section 7.2.5.3
IFNDEF Directives

The #ifndef directive is similar to the #ifdef directive however it is used to determine if the given identifier isn't declared yet. For example:

#ifndef (User_Thing) // This section is parsed if the // identifier "User_Thing" was not // previously declared box{<0,0,0>,<1,1,1>} // use a default #else // This section is parsed if the // identifier "User_Thing" was // previously declared object{User_Thing} // invoke identifier #end // End of conditional part

The #else directive is optional. The #end directive is required.

Section 7.2.5.4
SWITCH CASE and RANGE Directives

A more powerful conditional is the #switch directive. The syntax is as follows...

#switch (VALUE) #case (TEST_1) // This section is parsed if VALUE=TEST_1 #break //First case ends #case (TEST_2) // This section is parsed if VALUE=TEST_2 #break //Second case ends #range (LOW_1,HIGH_1) // This section is parsed if (VALUE>=LOW_1)&(VALUE<=HIGH_1) #break //Third case ends #range (LOW_2,HIGH_2) // This section is parsed if (VALUE>=LOW_2)&(VALUE<=HIGH_2) #break //Fourth case ends #else // This section is parsed if no other case or // range is true. #end // End of conditional part

The float expression VALUE following the #switch directive is evaluated and compared to the values in the #case or #range directives. When using #case, it is followed by a float expression TEST_1 in parentheses. It is compared to the VALUE. As usual in POV-Ray, float comparisons are considered equal if their difference is under 1e-10. If the values are equal, parsing continues normally until a #break, #else or #end directive is reached. If the comparison fails POV-Ray skips until another #case or #range is found.

If you use the #range directive it is followed by two float expressions LOW_1 and HIGH_1 which are enclosed in parentheses and separated by a comma. If the switch VALUE is in the range specified then parsing continues normally until a #break, #else or #end directive is reached. If the VALUE is outside the range the comparison fails and POV-Ray skips until another #case or #range is found.

If no #case or #range succeeds the #else section is parsed. The #else directive is optional. If no #else is specified and no match succeeds then parsing resumes after the #end directive.

There may be any number of #case or #range directives in any order you want. If a segment evaluates true but no #break is specified, the parsing will fall through to the next #case or #range and will continue until a #break, #else or #end. Hitting a #break while parsing a successful section causes an immediate jump to the #end without processing subsequent sections, even if a subsequent condition would also have been satisfied.

Section 7.2.5.5
WHILE Directive

The #while directive is a looping feature that makes it easy to place multiple objects in a pattern or other uses. The #while directive is followed by a float expression that evaluates to a boolean value. A value of 0.0 is false and any non-zero value is true. Note that extremely small values of about 1e-10 are considered zero in case of round off errors. The parentheses around the expression are required. If the condition is true parsing continues normally until an #end directive is reached. At the end, POV-Ray loops back to the #while directive and the condition is re-evaluated. Looping continues until the condition fails. When it fails, parsing continues after the #end directive. For example:

#declare Count=0 #while (Count < 5) object{MyObject translate x*3*Count} #declare Count=Count+1 #end

This example places five copies of MyObject in a row spaced three units apart in the x-direction.

Section 7.2.6
User Message Directives

With the addition of conditional and loop directives, the POV-Ray language has the potential to be more like an actual programming language. This means that it will be necessary to have some way to see what is going on when trying to debug loops and conditionals. To fulfill this need we have added the ability to print text messages to the screen. You have a choice of five different text streams to use including the ability to generate a fatal error if you find it necessary. Limited formatting is available for strings output by this method.

Section 7.2.6.1
Text Message Streams

The syntax for a text message is any of the following:

#debug STRING #error STRING #render STRING #statistics STRING #warning STRING

Where STRING is any valid string of text including string identifiers or functions which return strings. For example:

#switch (clock*360) #range (0,180) #render "Clock in 0 to 180 range\n" #break #range (180,360) #render "Clock in 180 to 360 range\n" #break #else #warning "Clock outside expected range\n" #warning concat("Value is:",str(clock*360,5,0),"\n") #end

There are seven distinct text streams that POV-Ray uses for output. You may output only to five of them. On some versions of POV-Ray, each stream is designated by a particular color. Text from these streams are displayed whenever it is appropriate so there is often an intermixing of the text. The distinction is only important if you choose to turn some of the streams off or to direct some of the streams to text files. On some systems you may be able to review the streams separately in their own scroll-back buffer. See "Console Text Output" for details on re-directing the streams to a text file.

Here is a description of how POV-Ray uses each stream. You may use them for whatever purpose you want except note that use of the #error stream causes a fatal error after the text is displayed.

DEBUG: This stream displays debugging messages. It was primarily designed for developers but this and other streams may also be used by the user to display messages from within their scene files.

FATAL: This stream displays fatal error messages. After displaying this text, POV-Ray will terminate. When the error is a scene parsing error, you may be shown several lines of scene text that leads up to the error.

RENDER: This stream displays information about what options you have specified to render the scene. It includes feedback on all of the major options such as scene name, resolution, animation settings, anti-aliasing and others.

STATISTICS: This stream displays statistics after a frame is rendered. It includes information about the number of rays traced, the length of time of the processing and other information.

WARNING: This stream displays warning messages during the parsing of scene files and other warnings. Despite the warning, POV-Ray can continue to render the scene.

The BANNER and STATUS streams can not be accessed by the user.

Next Section
Table Of Contents