Two slashes are used for single line comments. Anything on a line after a double slash ( // ) is ignored by the ray-tracer. For example:
You can have scene file information on the line in front of the comment as in:
The other type of comment is used for multiple lines. It starts with " /* " and ends with " */ ". Everything in-between is ignored. For example:
This can be useful if you want to temporarily remove elements from a scene file. /* ... */ comments can comment out lines containing other // comments and thus can be used to temporarily or permanently comment out parts of a scene. /* ... */ comments can be nested, the following is legal:
Use comments liberally and generously. Well used, they really improve the readability of scene files.
Where POV-Ray needs an integer value it allows you to specify a float value and it truncates it to an integer. When POV-Ray needs a logical or boolean value it interprets any non-zero float as true and zero as false. Because float comparisons are subject to rounding errors POV-Ray accepts values extremely close to zero as being false when doing boolean functions. Typically values whose absolute values are less than a preset value epsilon are considered false for logical expressions. The value of epsilon is system dependent but is generally about 1.0e-10. Two floats a and b are considered to be euqal if abs(a-b) < epsilon. Float literals are represented by an optional sign ("+" or "-") digits, an optional decimal point and more digits. If the number is an integer you may omit the decimal point and trailing zero. If it is all fractional you may omit the leading zero. POV-Ray supports scientific notation for very large or very small numbers. The following are all valid float literals:
-2.0 -4 34 3.4e6 2e-5 .3 0.6
Where IDENTIFIER is the name of the identifier up to 40 characters long and EXPRESSION is any valid expression which evaluates to a float value. Here are some examples.
As the last example shows, you can re-declare a float identifier and may use previously declared values in that re-declaration. There are several built-in identifiers which POV-Ray declares for you. See "Built-in Identifiers" for details.
() expressions in parentheses first +A -A !A unary minus, unary plus and logical "not" A*B A/B multiplication and division A+B A-B addition and subtraction
Relational, logical and conditional expressions may also be created. However there is a restriction that these types of expressions must be enclosed in parentheses first. This restriction, which is not imposed by most computer languages, is necessary because POV-Ray allows mixing of float and vector expressions. Without the parentheses there is an ambiguity problem. Parentheses are not required for the unary logical not operator "!" as shown above. The operators and their precedence are shown here.
Relational expressions: The operands are arithmetic expressions and the result is always boolean with 1 for true and 0 for false. All relational operators have the same precedence.
| (A < B) | A is less than B |
| (A <= B) | A is less than or equal to B |
| (A = B) | A is equal to B (actually abs(A-B)<EPSILON) |
| (A != B) | A is not equal to B (actually abs(A-B)>=EPSILON) |
| (A >= B) | A is greater than or equal to B |
| (A > B) | A is greater than B |
Logical expressions: The operands are converted to boolean values of 0 for false and 1 for true. The result is always boolean. All logical operators have the same precedence. Note that these are not bitwise operations, they are logical.
| (A & B) | true only if both A and B are true, false otherwise |
| (A | B) | true if either A or B or both are true |
Conditional expressions: The operand C is boolean while operands A and B are any expressions. The result is of the same type as A and B.
| (C ? A : B) | if C then A else B |
Assuming the various identifiers have been declared, the following are examples of valid expressions...
1+2+3 2*5 1/3 Row*3 Col*5 (Offset-5)/2 This/That+Other*Thing ((This<That) & (Other>=Thing)?Foo:Bar)
Expressions are evaluated left to right with innermost parentheses evaluated first, then unary +, - or !, then multiply or divide, then add or subtract, then relational, then logical, then conditional.
POV-Ray vectors may have from two to five components but the vast majority of vectors have three components. Unless specified otherwise, you should assume that the word vector means a three component vector. POV-Ray operates in a 3D x, y, z coordinate system and you will use three component vectors to specify x, y and z values. In some places POV-Ray needs only two coordinates. These are often specified by a 2D vector called an UV vector . Fractal objects use 4D vectors. Color expressions use 5D vectors but allow you to specify 3, 4 or 5 components and use default values for the unspecified components. Unless otherwise noted, all 2, 4 or 5 component vectors work just like 3D vectors but they have a different number of components.
The commas between components are necessary to keep the program from thinking that the 2nd term is the single float expression 3.2-5.4578 and that there is no 3rd term. If you see an error message such as Float expected but '>' found instead you probably have missed a comma.
Sometimes POV-Ray requires you to specify floats and vectors side-by-side. The rules for vector expressions allow for mixing of vectors with vectors or vectors with floats so commas are required separators whenever an ambiguity might arise. For example \langle 1,2,3>-4 evaluates as a mixed float and vector expression where 4 is subtracted from each component resulting in \langle -3,-2,-1>. However the comma in <1,2,3>,-4 means this is a vector followed by a float.
Each component may be a full float expression. For example \langle This+3,That/3,5*Other_Thing> is a valid vector.
Where IDENTIFIER is the name of the identifier up to 40 characters long and EXPRESSION is any valid expression which evaluates to a vector value. Here are some examples...
Note that you invoke a vector identifier by using its name without any angle brackets. As the last example shows, you can re-declare a vector identifier and may use previously declared values in that re-declaration. There are several built-in identifiers which POV-Ray declares for you. See "Built-in Identifiers" for details.
Conditional expressions such as (C ? A : B) require that C is a float expression but A and B may be vector expressions. The result is that the entire conditional evaluates as a valid vector. For example if Foo and Bar are floats then
You may use the dot operator to extract a single component from a vector. Suppose the identifier Spot was previously defined as a vector. Then Spot.x is a float value that is the first component of this x, y, z vector. Similarly Spot.y and Spot.z reference the 2nd and 3rd components. If Spot was a two component UV vector you could use Spot.u and Spot.v to extract the first and second component. For a 4D vector use .x , .y , .z and .t to extract each float component. The dot operator is also used in color expressions which are covered later.
Versions of POV-Ray prior to 3.0 only allowed such use of a float as a vector in various limited places such as scale and turbulence. However you may now use this trick anywhere. For example...
When promoting a float into a vector of 2, 3, 4 or 5 components, all components are set to the float value, however when promoting a vector of a lower number of components into a higher order vector, all remaining components are set to zero. For example if POV-Ray expects a 4D vector and you specify 9 the result is <9,9,9,9> but if you specify <7,6> the result is \langle 7,6,0,0>.
The 4th component, called filter , specifies the amount of filtered transparency of a substance. Some real-world examples of filtered transparency are stained glass windows or tinted cellophane. The light passing through such objects is tinted by the appropriate color as the material selectively absorbs some frequencies of light while allowing others to pass through. The color of the object is subtracted from the light passing through so this is called subtractive transparency.
The 5th component, called transmit , specifies the amount of non-filtered light that is transmitted through a surface. Some real-world examples of non-filtered transparency are thin see-through cloth, fine mesh netting and dust on a surface. In these examples, all frequencies of light are allowed to pass through tiny holes in the surface. Although the amount of light passing through is diminished, the color of the light passing through is unchanged. The color of the object is added to the light passing through so this is called additive transparency.
Note that early versions of POV-Ray used the keyword alpha to specify filtered transparency. However that word is often used to describe non-filtered transparency. For this reason alpha is no longer used.
Each of the five components of a color are float values which are normally in the range between 0.0 and 1.0. However any values, even negatives may be used.
Colors may be specified using vectors, keywords with floats or identifiers. You may also create very complex color expressions from combinations of any of these using various familiar operators. The syntax for specifying a color has evolved since POV-Ray was first released. We have maintained the original keyword-based syntax and added a short-cut vector notation. Either the old or new syntax is acceptable however the vector syntax is easier to use when creating color expressions.
where VECTOR3 , VECTOR4 or VECTOR5 are any valid vector expressions of 3, 4 or 5 components. For example
This specifies a color whose red component is 1.0 or 100% of full intensity. The green component is 0.5 or 50% of full intensity and the blue component is 0.2 or 20% of full intensity. Although the filter and transmit components are not explicitly specified, they exist and are set to their default values of 0 or no transparency.
The rgbf keyword requires a four component vector. The 4th component is the filter component and the transmit component defaults to zero. Similarly the rgbt keyword requires four components where the 4th value is moved to the 5th component which is transmit and then the filter component is set to zero.
The rgbft keyword allows you to specify all five components. Internally in expressions all five are always used.
Under most circumstances the keyword color is optional and may be omitted. We also support the British or Canadian spelling colour . Under some circumstances, if the vector expression is a 5 component expression or there is a color identifier in the expression then the rgbtf keyword is optional.
Table Of Contents