Where IDENTIFIER is the name of the identifier up to 40 characters long and STRING is a string literal, string identifier or function which returns a string value. Here are some examples...
As the last example shows, you can re-declare a string identifier and may use previously declared values in that re-declaration.
The built-in float identifier pi is obviously useful in math expressions involving circles.
The built-in float identifiers on,off, yes, no, true and false are designed for use as boolean constants.
The built-in vector identifiers x, y and z provide much greater readability for your scene files when used in vector expressions. For example....
An expression like 5*x evaluates to 5 <1,0,0> or <5,0,0>.
Similarly u and v may be used in 2D vectors. When using 4D vectors you should use x, y, z, and t and POV-Ray will promote x, y and z to 4D when used where 4D is required.
Other INI options and switches may be used to animate scenes by automatically looping through the rendering of frames using various values for clock. By default, the clock value is 0 for the initial frame and 1 for the final frame. All other frames are interpolated between these values. For example if your object is supposed to rotate one full turn over the course of the animation you could specify rotate 360*clock*y. Then as clock runs from 0 to 1, the object rotates about the y-axis from 0 to 360 degrees.
Although the value of clock will change from frame-to-frame, it will never change throughout the parsing of a scene.
See section "Animation Options" for more details.
The INI option or switch only affects the initial setting. Unlike other built-in identifiers, you may change the value of version throughout a scene file. You do not use #declare to change it though. The #version language directive is used to change modes. Such changes may occur several times within scene files.
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 format. At the top of the file you could put:
Function calls consist of a keyword which specifies the name of the function followed by a parameter list enclosed in parentheses. Parameters are separated by commas. For example:
Functions evaluate to values that are floats, vectors or strings and may be used in expressions or statements anywhere that literals or identifiers of that type may be used.
abs(A): Absolute value of A. If A is negative, returns -A otherwise returns A.
acos(A): Arc-cosine of A. Returns the angle, measured in radians, whose cosine is A.
asin(A): Arc-sine of A. Returns the angle, measured in radians, whose sine is A.
atan2(A,B): Arc-tangent of (A/B). Returns the angle, measured in radians, whose tangent is (A/B). Returns appropriate value even if B is zero. Use atan2(A,1) to compute usual atan(A) function.
ceil(A): Ceiling of A. Returns the smallest integer greater than A. Rounds up to the next higher integer.
cos(A): Cosine of A. Returns the cosine of the angle A, where A is measured in radians.
degrees(A): Convert radians to degrees. Returns the angle measured in degrees whose value in radians is A. Formula is degrees=A/pi*180.0.
div(A,B): Integer division. The integer part of (A/B).
exp(A): Exponential of A. Returns the value of e raised to the power A where e is the base of the natural logarithm, i.e. the non-repeating value approximately equal to 2.71828182846.
floor(A): Floor of A. Returns the largest integer less than A. Rounds down to the next lower integer.
int(A): Integer part of A. Returns the truncated integer part of A. Rounds towards zero.
log(A): Natural logarithm of A. Returns the natural logarithm base e of the value A.
max(A,B): Maximum of A and B. Returns A if A larger than B. Otherwise returns B.
min(A,B): Minimum of A and B. Returns A if A smaller than B. Otherwise returns B.
mod(A,B): Value of A modulo B. Returns the remainder after the integer division of A/B. Formula is mod=((A/B)-int(A/B))*B.
pow(A,B): Exponentiation. Returns the value of A raised to the power B.
radians(A): Convert degrees to radians. Returns the angle measured in radians whose value in degrees is A. Formula is radians=A*pi/180.0.
rand(A): Returns the next pseudo-random number from the stream specified by the positive integer A. You must call seed() to initialize a random stream before calling rand(). The numbers are uniformly distributed, and have values between 0.0 and 1.0, inclusively. The numbers generated by separate streams are independent random variables.
seed(A): Initializes a new pseudo-random stream with the initial seed value A. The number corresponding to this random stream is returned. Any number of pseudo-random streams may be used as shown in the example below:
Multiple random generators are very useful in situations where you use rand() to place a group of objects, and then decide to use rand() in another location earlier in the file to set some colors or place another group of objects. Without separate rand() streams, all of your objects would move when you added more calls to rand(). This is very annoying.
sin(A): Sine of A. Returns the sine of the angle A, where A is measured in radians.
sqrt(A): Square root of A. Returns the value whose square is A.
tan(A): Tangent of A. Returns the tangent of the angle A, where A is measured in radians.
vaxis_rotate(A,B,F): Rotate A about B by F. Given the x,y,z coordinates of a point in space designated by the vector A, rotate that point about an arbitrary axis defined by the vector B. Rotate it through an angle specified in degrees by the float value F. The result is a vector containing the new x,y,z coordinates of the point.
vcross(A,B): Cross product of A and B. Returns a vector that is the vector cross product of the two vectors. The resulting vector is perpendicular to the two original vectors and its length is proportional to the angle between them. See the animated demo scene VECT2.POV for an illustration.
vdot(A,B): Dot product of A and B. Returns a float value that is the dot product (sometimes called scaler product of A with B. Formula is vdot=A.x*B.x + A.y*B.y + A.z*B.z. See the animated demo scene VECT2.POV for an illustration.
vlength(A): Length of A. Returns a float value that is the length of vector A. Can be used to compute the distance between two points. Dist=vlength(B-A). Formula is vlength=sqrt(vdot(A,A)).
vnormalize(A): Normalize vector A. Returns a unit length vector that is the same direction as A. Formula is vnormalize=A/vlength(A).
vrotate(A,B): Rotate A about origin by B. Given the x,y,z coordinates of a point in space designated by the vector A, rotate that point about the origin by an amount specified by the vector B. Rotate it about the x-axis by an angle specified in degrees by the float value B.x. Similarly B.y and B.z specify the amount to rotate in degrees about the y-axis and z-axis. The result is a vector containing the new x,y,z coordinates of the point.
asc(S1): ASCII value of S1. Returns an integer value in the range 0 to 255 that is the ASCII value of the first character of S1. For example asc("ABC") is 65 because that is the value of the character "A".
chr(A): Character whose ASCII value is A. Returns a single character string. The ASCII value of the character is specified by an integer A which must be in the range 0 to 255. For example chr(70) is the string "F". When rendering text objects you should be aware that the characters rendered for values of A > 127 are dependent on the (TTF) font being used. Many (TTF) fonts use the Latin-1 (ISO 8859-1) character set, but not all do.
concat(S1,S2,[S3...]): Concatenate strings S1 and S2. Returns a string that is the concatenation of all parameter strings. Must have at least 2 parameters but may have more. For example:
If the float value A was 12.34 the result is "Value is 12.3 inches" which is a string.
file_exists(S1): Search for file specified by S1. Attempts to open the file whose name is specified by the string S1. The current directory and all directories specified in any Library_Path INI options or +L command line switches are searched. File is immediately closed. Returns a boolean value 1 on success and 0 on failure.
str(A,L,P): Convert float A to a formatted string. Returns a formatted string representation of float value A. The float parameter L specifies the minimum length of the string and the type of left padding used if the string's representation is shorter than the minimum. If L is positive then the padding is with blanks. If L is negative then the padding is with zeros. The overall minimum length of the formatted string is abs(L). If the string needs to be longer, it will be made as long as necessary to represent the value.
str(123.456,0,3) "123.456" str(123.456,4,3) "123.456" str(123.456,9,3) " 123.456" str(123.456,-9,3) "00123.456" str(123.456,0,2) "123.46" str(123.456,0,0) "123" str(123.456,5,0) " 123" str(123.000,7,2) " 123.00" str(123.456,0,-1) "123.456000" (platform specific)
strcmp(S1,S2): Compare string S1 to S2. Returns a float value zero if the strings are equal, a positive number if S1 comes after S2 in the ASCII collating sequence, else a negative number.
strlen(S1): Length of S1. Returns an integer value that is the number of characters in the string S1.
strlwr(S1): Lower case of S1. Returns a new string in which all upper case letters in the string S1 are converted to lower case. The original string is not affected. For example strlwr("Hello There!") results in "hello there!".
substr(S1,P,L): Sub-string from S1. Returns a string that is a subset of the characters in parameter S1 starting at the position specified by the integer value P for a length specified by the integer value L. For example substr("ABCDEFGHI",4,2) evaluates to the string "EF". If P+L>strlen(S1) an error occurs.
strupr(S1): Upper case of S1. Returns a new string in which all lower case letters in the string S1 are converted to upper case. The original string is not affected. For example strupr("Hello There!") results in "HELLO THERE!".
val(S1): Convert string S1 to float. Returns a float value that is represented by the text in S1. For example val("123.45") is 123.45 as a float.
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.