Section 7.1.6.2
String Identifiers

String identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows...

#declare IDENTIFIER = STRING

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...

#declare Font_Name = "ariel.ttf" #declare Inc_File = "myfile.inc" #declare Name = "John" #declare Name = concat(Name," Doe")

As the last example shows, you can re-declare a string identifier and may use previously declared values in that re-declaration.

Section 7.1.7
Built-in Identifiers

There are several built-in float and vector identifiers. You can use them to specify values or to create expressions but you cannot re-declare them to change their values.

Section 7.1.7.1
Constant Built-in Identifiers

Most built-in identifiers never change value. They are defined as though the following lines were at the start of every scene.

#declare pi = 3.1415926535897932384626 #declare true = 1 #declare yes = 1 #declare on = 1 #declare false = 0 #declare no = 0 #declare off = 0 #declare u = <1,0> #declare v = <0,1> #declare x = <1,0,0> #declare y = <0,1,0> #declare z = <0,0,1> #declare t = <0,0,0,1>

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....

plane { y, 1} // The normal vector is obviously "y". plane { <0,1,0>, 1} // This is harder to read. translate 5*x // Move 5 units in the "x" direction. translate <5,0,0> // This is less obvious.

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.

Section 7.1.7.2
Built-in Identifier 'clock'

The built-in float identifier clock is used to control animations in POV-Ray. Unlike some animation packages, the action in POV-Ray animated scenes does not depend upon the integer frame numbers. Rather you should design your scenes based upon the float identifier clock. For non-animated scenes its default value is 0 but you can set it to any float value using the INI file option Clock=n.n or the command-line switch +Kn.n to pass a single float value your scene file.

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.

Section 7.1.7.3
Built-in Identifier 'version'

The built-in float identifier version contains the current setting of the version compatibility option. Although this value defaults to 3 which is the current POV-Ray version number, the initial value of version may be set by the INI file option Version=n.n or by the +MVn.n command-line switch. This tells POV-Ray to parse the scene file using syntax from an earlier version of POV-Ray.

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:

#declare Temp_Vers = version // Save previous value #version 1.0 // Change to 1.0 mode ... // Version 1.0 stuff goes here... #version Temp_Vers // Restore previous version

Section 7.1.8
Functions

POV-Ray defines a variety of built-in functions for manipulating floats, vectors and strings. The functions are listed grouped according to their usage and not by the type of value they return. For example vdot computes the dot product of two vectors and is listed as a vector function even though it returns a single float value.

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:

keyword(param1,param2)

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.

Section 7.1.8.1
Float Functions

The following are the functions which take one or more float parameters and return float values. Assume that A and B are any valid expression that evaluates to a float. See section "Vector Functions" and section "String Functions" for other functions which return float values but whose primary purpose is more closely related to vectors and strings.

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:

#declare R1 = seed(0) #declare R2 = seed(12345) #sphere { <rand(R1), rand(R1), rand(R1)>, rand(R2) }

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.

Section 7.1.8.2
Vector Functions

The following are the functions which take one or more vector and float parameters and return vector or float values. All of these functions support only three component vectors. Assume that A and B are any valid expression that evaluates to a three component vector and that F is any valid expression that evaluates to a float.

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.

Section 7.1.8.3
String Functions

The following are the functions which take one or more string and float parameters and return string or float values. Assume that S1 and S2 are any valid strings and that A, L and P are any valid expressions that evaluate to floats.

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:

concat("Value is ", str(A,3,1), " inches")

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.

The float parameter P specifies the number of digits after the decimal point. If P is negative then a compiler-specific default precision is use. Here are some examples:

  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.

Section 7.2
Language Directives

The POV Scene Language contains several statements called language directives which tell the file parser how to do its job. These directives can appear in almost any place in the scene file - even in the middle of some other statements. They are used to include other text files in the stream of commands, to declare identifiers, to define conditional or looped parsing and to control other important aspects of scene file processing.

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.
Next Section
Table Of Contents