Previous:Boolean Keywords Main Index Next:Vector Expressions

POV-Ray defines a variety of built-in functions for manipulating floats, vectors and strings. 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)

The following are the functions which return float values. They take one or more float, integer, vector, or string parameters. Assume that

and **A**

are any valid expression that evaluates to a float; **B**

is a float which is truncated to integer internally, **I**

, **S**

, **S1**

etc. are strings, and **S2**

, **V**

, **V1**

etc. are any vector expressions.**V2**

Absolute value of **abs(A)**

. If **A**

is negative, returns **A**

otherwise returns **-A**

.**A**

Arc-cosine of **acos(A) **

. Returns the angle, measured in radians, whose cosine is **A**

.**A**

Returns an integer value in the range 0 to 255 that is the ASCII value of the first character of the string **asc(S) **

. For example **S**

is 65 because that is the value of the character "A".**asc("ABC")**

Arc-sine of **asin(A) **

. Returns the angle, measured in radians, whose sine is **A**

.**A**

Arc-tangent of **atan2(A,B) **

. Returns the angle, measured in radians, whose tangent is **(A/B)**

. Returns appropriate value even if **(A/B)**

is zero. Use **B**

to compute usual atan(A) function.**atan2(A,1)**

Ceiling of **ceil(A)**

. Returns the smallest integer greater than **A**

. Rounds up to the next higher integer.**A**

Cosine of **cos(A) **

. Returns the cosine of the angle **A**

, where **A**

is measured in radians.**A**

**defined(***IDENTIFIER*

Returns **) **

if the identifier is currently defined, **true**

otherwise. This is especially useful for detecting end-of-file after a **false**

directive because the file identifer is automatically undefined when end-of-file is reached. See "The #read Directive" for details.**#read**

Convert radians to degrees. Returns the angle measured in degrees whose value in radians is **degrees(A) **

. Formula is **A***degrees=A/pi*180.0*.

**dimensions(***ARRAY_IDENTIFIER*

Returns the number of dimensions of a previously declared array identifier. For example if you do **) **

then **#declare MyArray=array[6][10]**

returns the value **dimensions(MyArray)**

.**2**

**dimension_size(***ARRAY_IDENTIFIER, FLOAT *

Returns the size of a given dimension of a previously declared array identifier. Dimensions are numbered left-to-right starting with 1. For example if you do **) **

then **#declare MyArray=array[6][10]**

returns the value **dimension_size(MyArray,2)**

.**10**

Integer division. The integer part of **div(A,B) **

.**(A/B)**

Exponential of **exp(A) **

. Returns the value of **A***e* raised to the power

where **A***e* is the base of the natural logarithm, i.e. the non-repeating value approximately equal to 2.71828182846.

Attempts to open the file specified by the string **file_exists(S) **

. The current directory and all library directories specified by the **S**

or **Library_Path**

options are also searched. See "Library Paths" for details. Returns **+L**

if successful and **1**

if unsuccessful.**0**

Floor of **floor(A) **

. Returns the largest integer less than **A**

. Rounds down to the next lower integer.**A**

Integer part of **int(A) **

. Returns the truncated integer part of **A**

. Rounds towards zero.**A**

Natural logarithm of **log(A) **

. Returns the natural logarithm base **A***e* of the value

.**A**

Maximum of **max(A,B) **

and **A**

. Returns **B**

if **A**

larger than **A**

. Otherwise returns **B**

.**B**

Minimum of **min(A,B) **

and **A**

. Returns **B**

if **A**

smaller than **A**

. Otherwise returns **B**

.**B**

Value of **mod(A,B) **

modulo **A**

. Returns the remainder after the integer division of **B**

/**A**

. Formula is **B***mod=((A/B)-int(A/B))*B.*

Exponentiation. Returns the value of **pow(A,B) **

raised to the power **A**

.**B**

Convert degrees to radians. Returns the angle measured in radians whose value in degrees is **radians(A) **

. Formula is **A***radians=A*pi/180.0.*

Returns the next pseudo-random number from the stream specified by the positive integer **rand(I) **

. You must call **I**

to initialize a random stream before calling **seed()**

. The numbers are uniformly distributed, and have values between **rand()**

and **0.0**

, inclusively. The numbers generated by separate streams are independent random variables.**1.0**

Initializes a new pseudo-random stream with the initial seed value **seed(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:**A**

#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

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.**rand()**

Sine of **sin(A) **

. Returns the sine of the angle **A**

, where **A**

is measured in radians.**A**

Compare string **strcmp(S1,S2) **

to **S1**

. Returns a float value zero if the strings are equal, a positive number if **S2**

comes after **S1**

in the ASCII collating sequence, else a negative number.**S2**

Length of **strlen(S) **

. Returns an integer value that is the number of characters in the string **S**

.**S**

Square root of **sqrt(A) **

. Returns the value whose square is **A**

.**A**

Tangent of **tan(A) **

. Returns the tangent of the angle **A**

, where **A**

is measured in radians.**A**

Convert string **val(S) **

to float. Returns a float value that is represented by the text in string **S**

. For example **S**

is 123.45 as a float.**val("123.45")**

Dot product of **vdot(V1,V2) **

and **V1**

. Returns a float value that is the dot product (sometimes called scalar product of **V2**

with **V1**

. Formula is **V2***vdot=V1.x*V2.x + V1.y*V2.y + V1.z*V2.z*. See the animated demo scene `VECT2.POV`

for an illustration.

Length of **vlength(V) **

. Returns a float value that is the length of vector **V**

. Formula is **V***vlength=sqrt(vdot(A,A))*. Can be used to compute the distance between two points.

.**Dist=vlength(V2-V1)**

See section "Vector Functions" and section "String Functions" for other functions which are somewhat float-related but which return vectors and strings. In addition to the above built-in functions, you may also define your own functions using the new

directive. See the section "User Defined Macros" for more details.**#macro**

Previous:Boolean Keywords Main Index Next:Vector Expressions