Reference:Conditional Directives - Revision history

Clipka: indexentry fix

2016-05-03T23:06:59Z

indexentry fix

Jholsenback: indexentry tag repair

2015-03-10T15:52:46Z

indexentry tag repair

Jholsenback: indexentry tag repair

2015-03-10T15:43:25Z

indexentry tag repair

Jholsenback: indexentry tag repair

2015-03-10T15:42:43Z

indexentry tag repair

Jholsenback: indexentry tag repair

2015-03-10T15:41:13Z

indexentry tag repair

Jholsenback: added example

2013-08-30T14:53:15Z

added example

Jholsenback: 1 revision: Reference Migration Initial Load

2012-03-15T19:05:18Z

1 revision: Reference Migration Initial Load

Jholsenback: link repair

2012-03-15T11:56:48Z

link repair

New page

[[Category:Language Directives]]
{{#indexentry:Directives, language, conditional}}
POV-Ray allows a variety of 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 <code>[[Reference:Conditional Directives#The while...end Directive|:#while|#while]]</code> loop directive. You may nest conditional directives 200 levels deep.
{{#indexentry:Directives, language, #if}}
{{#indexentry:Directives, language, #else}}
{{#indexentry:Directives, language, #elseif}}
{{#indexentry:Directives, language, #end}}
{{#indexentry:if|else|elseif|end}}
{{#indexentry:#if|#else|#elseif|#end}}
==The if...else...end Directives==
The simplest conditional directive is the traditional <code>#if</code> directive. The syntax is:
<pre>
IF_DIRECTIVE:
#if ( Cond ) TOKENS... [ELSE_DIRECTIVE] #end
ELSE_DIRECTIVE:
#else TOKENS... |
#elseif ( Cond ) TOKENS... [ELSE_DIRECTIVE]
</pre>
The TOKENS are any number of POV-Ray keyword, identifiers, or punctuation and <code>(</code> Cond <code>)</code> is a float expression that is interpreted as a boolean value. The parentheses and the <code>#end</code> directive are required, an optional <code>#elseif</code> clause is now supported.
A value of 0.0 is <code>false</code> (numbers <= 1e-10 are also considered zero) while other any non-zero value is <code>true</code>.
For example:
<pre>
#if (Foo)
#debug "Foo is true\n"
#elseif (Bar)
#debug "Foo is false, but Bar is true\n"
#else
#debug "Foo and Bar are both false\n"
#end
</pre>
Note: Nesting directives in the following manner has been known to cause problems during the parse phase.
<pre>
#if( #if(yes) yes #end ) #end
</pre>

{{#indexentry:ifdef|ifndef|#ifdef|#ifndef}}
{{#indexentry:Directives, language, #ifdef}}
{{#indexentry:Directives, language, #ifndef}}
==The ifdef and ifndef Directives==
The <code>#ifdef</code> and <code>#ifndef</code> directive are similar to the <code>#if</code> directive however they are used to determine if an identifier has been previously declared.
<pre>
IFDEF_DIRECTIVE:
#ifdef ( IDENTIFIER ) TOKENS... [ELSE_DIRECTIVE] #end
IFNDEF_DIRECTIVE:
#ifndef ( IDENTIFIER ) TOKENS... [ELSE_DIRECTIVE] #end
ELSE_DIRECTIVE:
#else TOKENS... |
#elseif ( Cond ) TOKENS... [ELSE_DIRECTIVE]
</pre>
If the IDENTIFIER exists then the first group of tokens is parsed normally and the second set is skipped. If false, the first set is skipped and the second set is parsed. This is especially useful for replacing an undefined item with a default.
For example:
<pre>
#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
</pre>
The <code>#ifndef</code> directive works the opposite. The first group is parsed if the identifier is not defined. As with the <code>#if</code> directive, the <code>#else</code> clause is optional and the <code>#end</code> directive is required.
The <code>#ifdef</code> and <code>#ifndef</code> directives can be used to determine whether a specific element of an array has been assigned.
<pre>
#declare MyArray=array[10]
//#declare MyArray[0]=7;
#ifdef(MyArray[0])
#debug "first element is assigned\n"
#else
#debug "first element is not assigned\n"
#end
</pre>
Note: Additionally, just like the <code>#if</code> directive, the <code>#ifdef</code> and <code>#ifndef</code> directives now also supports an <code>#elseif</code> clause.

{{#indexentry:for|#for}}
==The for Directive==
A new <code>#for</code> loop construct is now available for simple loops incrementing Identifier from Start to End (inclusive) with the given Step size. The default Step size is +1.0.
The syntax is:
<pre>
#for (Identifier, Start, End [, Step])
//...
#end
</pre>

Some additional notes:
<ul>
<li>If Step is negative, comparison will be automatically adjusted to match a countdown pattern.</li>
<li>Start, End and Step are evaluated only once.</li>
<li>The loop counter is a full-fledged local variable. Any local variable of the same name already defined before the loop will be overwritten without warning (note that in the main scene file, all local variables outside of macros are effectively global); inside the loop, any tampering with the variable is possible for effect, as long as it is defined as a local numeric variable at the end of each iteration.</li>
<li>After the loop has terminated, the variable will remain defined, typically holding the value End+Step.</li>
<li>The loop counter must not be an array element.</li>
</ul>

Note: See the end of the next section for more information about <code>#break</code> directive behavior.

{{#indexentry:switch|case|range|break}}
{{#indexentry:#switch|#case|#range|#break}}
{{#indexentry:Directives, language, #switch}}
{{#indexentry:Directives, language, #case}}
{{#indexentry:Directives, language, #range}}
{{#indexentry:Directives, language, #break}}

==The switch, case, range and break Directives==
A more powerful conditional is the <code>#switch</code> directive. The syntax is as follows...
<pre>
SWITCH_DIRECTIVE:
#switch ( Switch_Value ) SWITCH_CLAUSE... [#else TOKENS...] #end
SWITCH_CLAUSE:
#case( Case_Value ) TOKENS... [#break] |
#range( Low_Value , High_Value ) TOKENS... [#break]
</pre>
The TOKENS are any number of POV-Ray keyword, identifiers, or punctuation and <code>(</code> Switch_Value <code>)</code> is a float expression. The parentheses are required. The <code>#end</code> directive is required. The SWITCH_CLAUSE comes in two varieties. In the <code>#case</code> variety, the float Switch_Value is compared to the float Case_Value. If they are equal, the condition is true.
Note: Values whose difference is less than 1e-10 are considered equal in
case of round off errors.
In the <code>#range</code> variety, Low_Value and High_Value are floats separated by a comma and enclosed in parentheses.
If Low_Value <= Switch_Value and Switch_Value <= High_Value then the condition is true.
In either variety, if the clause's condition is true, that clause's tokens are parsed normally and parsing continues until a <code>#break</code>, <code>#else</code> or <code>#end</code> directive is reached. If the condition is false, POV-Ray skips until another <code>#case</code> or <code>#range</code> is found.
There may be any number of <code>#case</code> or <code>#range</code> clauses in any order you want. If a clause evaluates true but no <code>#break</code> is specified, the parsing will fall through to the next <code>#case</code> or <code>#range</code> and that clause conditional is evaluated. Hitting <code>#break</code> while parsing a successful section causes an immediate jump to the <code>#end</code> without processing subsequent sections, even if a subsequent condition would also have been satisfied.
An optional <code>#else</code> clause may be the last clause. It is only executed if the clause before it was a false clause.
Additionally, within the <code>#switch</code> directive, the <code>#else</code> clause acts like a <code>#range</code> directive that encompasses any possible number. To avoid execution of the <code>#else</code> block, the preceding <code>#case</code> or <code>#range</code> directives must be ended with a <code>#break</code> statement.
Note: The above behavior applies only within the <code>#switch</code> directive.
For example:
<pre>
#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
</pre>
Note: As of version 3.7 the <code>#break</code> directive can now be used:
<ul>
<li>anywhere within a <code>#case</code> or <code>#range</code> block, to skip to the end of the <code>#switch</code> directive (previously, <code>#break</code> was only useful right before the next <code>#case</code>, <code>#range</code> or <code>#else</code> directive, to indicate that a slip-through was not desired).</li>
<li>anywhere within a loop block (both <code>#while</code> and <code>#for</code>), to terminate the loop.</li>
<li>anywhere within a <code>#macro</code> to preliminarily terminate the macro.</li>
</ul>
Example for the use in a loop:
<pre>
#local R = seed(4711);
#for (I, 1, 100)
#if (rand(R) < I/1000)
#break // terminate loop early
#end
#debug concat(str(I,0,0), " iterations and counting\n")
#end
</pre>
Where multiple <code>#switch</code>, loop and/or <code>#macro</code> blocks are nested, <code>#break</code> will leave only the innermost of these.

{{#indexentry:while|#while}}
{{#indexentry:Directives, language, #while}}
{{#indexentry:Directives, language, #end}}
==The while...end Directive==
The <code>#while</code> directive is a looping feature that makes it easy to place multiple objects in a pattern or other uses.
<pre>
WHILE_DIRECTIVE:
#while ( Cond ) TOKENS... #end
</pre>
The TOKENS are any number of POV-Ray keyword, identifiers, or punctuation marks which are the body of the loop. The <code>#while</code> 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: 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 <code>#end</code> directive is reached. At the end, POV-Ray loops back to the <code>#while</code> directive and the condition is re-evaluated. Looping continues until the condition fails. When it fails, parsing continues after the <code>#end</code> directive.
Note: It is possible for the condition to fail the first time and the loop is totally skipped. It is up to the user to insure that something inside the loop changes so that it eventually terminates.
Here is a properly constructed loop example:
<pre>
#declare Count=0;
#while (Count < 5)
object { MyObject translate x*3*Count }
#declare Count=Count+1;
#end
</pre>
This example places five copies of <code>MyObject</code> in a row spaced three units apart in the x-direction.

Note: See the end of the previous section for more information about <code>#break</code> directive behavior.

@@ Line 3: / Line 3: @@
 <p>POV-Ray allows a variety of 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 <code>[[Reference:Conditional Directives#The while...end Directive|:#while|#while]]</code> loop directive. You may nest conditional directives 200 levels deep.</p>
 {{#indexentry:Directives, language, #if}}
 {{#indexentry:Directives, language, #else}}
@@ Line 9: / Line 10: @@
 {{#indexentry:if|else|elseif|end}}
 {{#indexentry:#if|#else|#elseif|#end}}
 <p>The simplest conditional directive is the traditional <code>#if</code> directive. The syntax is:</p>
 <pre>
@@ Line 35: / Line 35: @@
 </pre>
 {{#indexentry:ifdef|ifndef|#ifdef|#ifndef}}
 {{#indexentry:Directives, language, #ifdef}}
 {{#indexentry:Directives, language, #ifndef}}
 <p>The <code>#ifdef</code> and <code>#ifndef</code> directive are similar to the <code>#if</code> directive however they are used to determine if an identifier has been previously declared.</p>
 <pre>
@@ Line 78: / Line 78: @@
 <p class="Note"><strong>Note:</strong> Additionally, just like the <code>#if</code> directive, the <code>#ifdef</code> and <code>#ifndef</code> directives now also supports an <code>#elseif</code> clause.</p>
 {{#indexentry:for|#for}}
 <p>A new <code>#for</code> loop construct is now available for simple loops incrementing Identifier from Start to End (inclusive) with the given Step size. The default Step size is  +1.0.</p>
 <p>The syntax is:</p>
@@ Line 106: / Line 106: @@
 <p class="Note"><strong>Note:</strong> See the <em>end</em> of the next section for more information about <code>#break</code> directive behavior.</p>
 {{#indexentry:switch|case|range|break}}
 {{#indexentry:#switch|#case|#range|#break}}
@@ Line 112: / Line 113: @@
 {{#indexentry:Directives, language, #range}}
 {{#indexentry:Directives, language, #break}}
 <p>A more powerful conditional is the <code>#switch</code> directive. The syntax is as follows...</p>
 <pre>
@@ Line 169: / Line 169: @@
 <p>Where multiple <code>#switch</code>, loop and/or <code>#macro</code> blocks are nested, <code>#break</code> will leave only the innermost of these.</p>
 {{#indexentry:while|#while}}
 {{#indexentry:Directives, language, #while}}
 {{#indexentry:Directives, language, #end}}
 <p>The <code>#while</code> directive is a looping feature that makes it easy to place multiple objects in a pattern or other uses.</p>
 <pre>

@@ Line 169: / Line 169: @@
 <p>Where multiple <code>#switch</code>, loop and/or <code>#macro</code> blocks are nested, <code>#break</code> will leave only the innermost of these.</p>
 ==The while...end Directive==
 <p>The <code>#while</code> directive is a looping feature that makes it easy to place multiple objects in a pattern or other uses.</p>

@@ Line 106: / Line 106: @@
 <p class="Note"><strong>Note:</strong> See the <em>end</em> of the next section for more information about <code>#break</code> directive behavior.</p>
 ==The switch, case, range and break Directives==
 <p>A more powerful conditional is the <code>#switch</code> directive. The syntax is as follows...</p>
@@ Line 163: / Line 169: @@
 <p>Where multiple <code>#switch</code>, loop and/or <code>#macro</code> blocks are nested, <code>#break</code> will leave only the innermost of these.</p>
 ==The while...end Directive==
 <p>The <code>#while</code> directive is a looping feature that makes it easy to place multiple objects in a pattern or other uses.</p>

← Older revision		Revision as of 15:41, 10 March 2015
Line 105:		Line 105:

	<p class="Note"><strong>Note:</strong> See the <em>end</em> of the next section for more information about <code>#break</code> directive behavior.</p>		<p class="Note"><strong>Note:</strong> See the <em>end</em> of the next section for more information about <code>#break</code> directive behavior.</p>
−
−	~~{{#indexentry:switch\|case\|range\|break}}~~
−	~~{{#indexentry:#switch\|#case\|#range\|#break}}~~
−	~~{{#indexentry:Directives, language, #switch}}~~
−	~~{{#indexentry:Directives, language, #case}}~~
−	~~{{#indexentry:Directives, language, #range}}~~
−	~~{{#indexentry:Directives, language, #break}}~~

	==The switch, case, range and break Directives==		==The switch, case, range and break Directives==

@@ Line 87: / Line 87: @@
 #end
 </pre>
 <p>
 Some additional notes:</p>

← Older revision	Revision as of 19:05, 15 March 2012
(No difference)