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 < 1,2,3>-4 evaluates as a mixed float and vector expression where 4 is subtracted from each component resulting in < -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 < 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 section "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 < 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.
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.
This specifies a color whose red component is 1.0 or 100% of full intensity and the green component is 0.5 or 50% of full intensity. Although the blue, filter and transmit components are not explicitly specified, they exist and are set to their default values of 0. The component keywords may be given in any order and if any component is unspecified its value defaults to zero.
Where IDENTIFIER is the name of the identifier up to 40 characters long and COLOR_VECTOR or COLOR_KEYWORDS are any valid color specifications as described in the two previous sections of this document. Here are some examples...
As the LightGray example shows you do not need any color keywords when creating color expressions based on previously declared colors. The last example shows you may use a color identifier with the keyword style syntax. Make sure that the identifier comes first before any other component keywords.
Like floats and vectors, you may re-define colors throughout a scene but the need to do so is rare.
You may use the dot operator to extract a single component from a color. Suppose the identifier Shade was previously defined as a color. Then Shade.red is the float value of the red component of Shade. Similarly Shade.green, Shade.blue, Shade.filter and Shade.transmit extract the float value of the other color components.
When using filter transparency, the colors which come through are multiplied by the primary color components. For example if gray light such as rgb <0.9,0.9,0.9> passes through a filter such as rgbf <1.0,0.5,0.0,1.0> the result is rgb <0.9,0.45,0.0> with the red let through 100%, the green cut in half from 0.9 to 0.45 and the blue totally blocked. Often users mistakenly specify a clear object by
but this has implied red, green and blue values of zero. You've just specified a totally black filter so no light passes through. The correct way is either
or
In the 2nd example it doesn't matter what the rgb values are. All of the light passes through untouched.
Another pitfall is the use of color identifiers and expressions with color keywords. For example...
this substitutes whatever was the red component of My_Color with a red component of 0.5 however...
adds 0.5 to the red component of My_Color and even less obvious...
that cuts the red component in half as you would expect but it also multiplies the green, blue, filter and transmit components by zero! The part of the expression after the multiply operator evaluates to rgbft <0.5,0,0,0,0> as a full 5 component color.
The following example results in no change to My_Color.
This is because the identifier fully overwrites the previous value. When using identifiers with color keywords, the identifier should be first.
One final issue, some POV-Ray syntax allows full color specifications but only uses the rgb part. In these cases it is legal to use a float where a color is needed. For example:
The ambient keyword expects a color so the value 1 is promoted to <1,1,1,1,1> which is no problem. However
is legal but it may or may not be what you intended. The 0.4 is promoted to <0.4,0.4,0.4,0.4,0.> with the filter and transmit set to 0.4 as well. It is more likely you wanted...
in which case a 3 component vector is expected. Therefore the 0.4 is promoted to <0.4,0.4,0.4,0.0,0.0> with default zero for filter and transmit.
"Here" "There" "myfile.gif" "textures.inc"
Note if you need to specify a quote mark in a string literal you must preceed it with a backslash. For example
"Joe said \"Hello\" as he walked in."
is converted to
Joe said "Hello" as he walked in.
If you need to specify a backslash, most of the time you need do nothing special. However if the string ends in a backslash, you will have to specify two. For example:
"This is a backslash and so is this"
Is converted to:
This is a backslash and so is this\
The
regardless usage however other formating codes such as \n for new line are supported in user message streams. See "Text Formatting" for details.