3.2.1 Language Basics

POV-Ray 3.6 for UNIX documentation 3.2.2 Language Directives

3.3 Scene Settings

3.2.2 Language Directives

3.2.2.1 Include Files and the #include Directive

The language allows include files to be specified by placing the line

 #include "filename.inc"

at any point in the input file. The filename may be specified by any valid string expression but it usually is a literal string enclosed in double quotes. It may be up to 40 characters long (or your computer's limit), including the two double-quote characters.

The include file is read in as if it were inserted at that point in the file. Using include is almost the same as cutting and pasting the entire contents of this file into your scene.

Include files may be nested. You may have at most 10 nested include files. There is no limit on un-nested include files.

Generally, include files have data for scenes but are not scenes in themselves. By convention scene files end in .pov and include files end with .inc.

It is legal to specify drive and directory information in the file specification however it is discouraged because it makes scene files less portable between various platforms. Use of full lower case is also recommended but not required.

Note: if you ever intend to distribute any source files you make for POV-Ray, remember that some operating systems have case-sensitive file names).

It is typical to put standard include files in a special sub-directory. POV-Ray can only read files in the current directory or one referenced by the Library_Path option or +L switch. See section "Library Paths".

You may use the #local directive to declare identifiers which are temporary in duration and local to the include file in scope. For details see "#declare vs. #local".

3.2.2.2 The #declare and #local Directives

Identifiers may be declared and later referenced to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. There are several built-in identifiers which POV-Ray declares for you. See section "Float Expressions: Built-in Variables" and "Built-in Vector Identifiers" for details.

3.2.2.2.1 Declaring identifiers

An identifier is declared as follows.

DECLARATION:
    #declare IDENTIFIER = RVALUE |
    #local IDENTIFIER = RVALUE
RVALUE:
    FLOAT; | VECTOR; | COLOR; | STRING | OBJECT | TEXTURE |
    PIGMENT | NORMAL | FINISH | INTERIOR | MEDIA | DENSITY |
    COLOR_MAP | PIGMENT_MAP | SLOPE_MAP | NORMAL_MAP |
    DENSITY_MAP | CAMERA | LIGHT_SOURCE | FOG | RAINBOW |
    SKY_SPHERE | TRANSFORM

Where IDENTIFIER is the name of the identifier up to 40 characters long and RVALUE is any of the listed items. They are called that because they are values that can appear to the right of the equals sign. The syntax for each is in the corresponding section of this language reference. Here are some examples.

 #declare Rows = 5;
 #declare Count = Count+1;
 #local  Here = <1,2,3>;
 #declare White = rgb <1,1,1>;
 #declare Cyan = color blue 1.0 green 1.0;
 #declare Font_Name = "ariel.ttf"
 #declare Rod = cylinder {-5*x,5*x,1}
 #declare Ring = torus {5,1}
 #local  Checks = pigment { checker White, Cyan }
 object{ Rod scale y*5 }     // not "cylinder { Rod }"
 object {
  Ring
  pigment { Checks scale 0.5 }
  transform Skew
 }

Note: that there should be a semi-colon after the expression in all float, vector and color identifier declarations. This semi-colon is introduced in POV-Ray version 3.1. If omitted, it generates a warning and some macros may not work properly. Semicolons after other declarations are optional.

Declarations, like most language directives, can appear almost anywhere in the file - even within other statements. For example:

 #declare Here=<1,2,3>;
 #declare Count=0;         // initialize Count
 union {
  object { Rod translate Here*Count }
  #declare Count=Count+1;     // re-declare inside union
  object { Rod translate Here*Count }
  #declare Count=Count+1;     // re-declare inside union
  object { Rod translate Here*Count }
 }

As this example shows, you can re-declare an identifier and may use previously declared values in that re-declaration.

Note: object identifiers use the generic wrapper statement object{ ... }. You do not need to know what kind of object it is.

Declarations may be nested inside each other within limits. In the example in the previous section you could declare the entire union as a object. However for technical reasons there are instances where you may not use any language directive inside the declaration of floats, vectors or color expressions. Although these limits have been loosened somewhat since POV-Ray 3.1, they still exist.

Identifiers declared within #macro ... #end blocks are not created at the time the macro is defined. They are only created at the time the macro is actually invoked. Like all other items inside such a #macro definition, they are ignored when the macro is defined.

3.2.2.2.2 #declare vs. #local

Identifiers may be declared either global using #declare or local using the #local directive.

Those created by the #declare directive are permanent in duration and global in scope. Once created, they are available throughout the scene and they are not released until all parsing is complete or until they are specifically released using #undef. See "Destroying Identifiers".

Those created by the #local directive are temporary in duration and local in scope. They temporarily override any identifiers with the same name. See "Identifier Name Collisions".

If #local is used inside a #macro then the identifier is local to that macro. When the macro is invoked and the #local directive is parsed, the identifier is created. It persists until the #end directive of the macro is reached. At the #end directive, the identifier is destroyed. Subsequent invocations of the macro create totally new identifiers.

Use of #local within an include file but not in a macro, also creates a temporary identifier that is local to that include file. When the include file is included and the #local directive is parsed, the identifier is created. It persists until the end of the include file is reached. At the end of file the identifier is destroyed. Subsequent inclusions of the file create totally new identifiers.

Use of #local in the main scene file (not in an include file and not in a macro) is identical to #declare. For clarity sake you should not use #local in a main file except in a macro.

There is currently no way to create permanent, yet local identifiers in POV-Ray.

Local identifiers may be specifically released early using #undef but in general there is no need to do so. See "Destroying Identifiers".

3.2.2.2.3 Identifier Name Collisions

 #declare A = 123;
 #declare B = rgb<1,2,3>;
 #declare C = 0;
 #include "myinc.inc"

 #local A = 546;

 #local B = box{0,1}

 #local D = 789;

 #local D = D + 1;

 #declare D = D + 1;

3.2.2.2.4 Destroying Identifiers with #undef

Identifiers created with #declare will generally persist until parsing is complete. Identifiers created with #local will persist until the end of the macro or include file in which they were created. You may however un-define an identifier using the #undef directive. For example:

 #undef MyValue

If multiple local nested versions of the identifier exist, the most local most recent version is deleted and any identically named identifiers which were created at higher levels will still exist.

See also "The #ifdef and #ifndef Directives".

3.2.2.3 File I/O Directives

3.2.2.3.1 The #fopen Directive

FOPEN_DIRECTIVE:
    #fopen IDENTIFIER "filename" OPEN_TYPE
OPEN_TYPE:
    read | write | append

3.2.2.3.2 The #fclose Directive

FCLOSE_DIRECTIVE:
    #fclose FILE_HANDLE_IDENTIFIER

Where FILE_HANDLE_IDENTIFIER is previously opened file opened with the #fopen directive. See "The #fopen Directive".

3.2.2.3.3 The #read Directive

READ_DIRECTIVE:
  #read (FILE_HANDLE_IDENTIFIER, DATA_IDENTIFIER[,DATA_IDENTIFIER]..)
DATA_IDENTIFIER:
  UNDECLARED_IDENTIFIER | FLOAT_IDENTIFIER | VECTOR_IDENTIFIER | 
  STRING_IDENTIFIER

  #fopen MyFile "mydata.txt" read
  #while (defined(MyFile))
    #read (MyFile,Var1,Var2,Var3)
    ...
  #end

3.2.2.3.4 The #write Directive

WRITE_DIRECTIVE:
    #write( FILE_HANDLE_IDENTIFIER, DATA_ITEM[,DATA_ITEM]...)
DATA_ITEM:
    FLOAT | VECTOR | STRING

Where FILE_HANDLE_IDENTIFIER is the previously opened file. It is followed by one or more DATA_ITEMs separated by commas. The parentheses around the identifier list are required. A DATA_ITEM is any valid string expression, float expression, or vector expression. Float expressions are evaluated and written as signed float literals. If you require format control, you should use the str(VALUE,L,P) function to convert it to a formatted string. See "String Functions" for details on the str function. Vector expressions are evaluated into three signed float constants and are written with angle brackets and commas in standard POV-Ray vector notation. String expressions are evaluated and written as specified.

Note: data read by the #read directive must have comma delimiters between values and quotes around string data but the #write directive does not automatically output commas or quotes.

For example the following #read directive reads a string, float and vector.

 #read (MyFile,MyString,MyFloat,MyVect)

It expects to read something like:

 "A quote delimited string", -123.45, <1,2,-3>

The POV-Ray code to write this might be:

 #declare Val1 = -123.45;
 #declare Vect1 = <1,2,-3>;
 #write(MyFile,"\"A quote delimited string\",",Val1,",",Vect1,"\n")

See "String Literals" and "Text Formatting" for details on writing special characters such as quotes, newline, etc.

3.2.2.4 The #default Directive

POV-Ray creates a default texture when it begins processing. You may change those defaults as described below. Every time you specify a texture statement, POV-Ray creates a copy of the default texture. Anything you put in the texture statement overrides the default settings. If you attach a pigment, normal, or finish to an object without any texture statement then POV-Ray checks to see if a texture has already been attached. If it has a texture then the pigment, normal or finish will modify the existing texture. If no texture has yet been attached to the object then the default texture is copied and the pigment, normal or finish will modify that texture.

You may change the default texture, pigment, normal or finish using the language directive #default as follows:

DEFAULT_DIRECTIVE:
    #default {DEFAULT_ITEM }
DEFAULT_ITEM:
    TEXTURE | PIGMENT | NORMAL | FINISH

For example:

 #default {
   texture {
     pigment { rgb <1,0,0> }
     normal { bumps 0.3 }
     finish { ambient 0.4 }
   }
 }

This means objects will default to red bumps and slightly high ambient finish. Also you may change just part of it like this:

 #default {
  pigment {rgb <1,0,0>}
 }

This still changes the pigment of the default texture. At any time there is only one default texture made from the default pigment, normal and finish. The example above does not make a separate default for pigments alone.

Note: the special textures tiles and material_map or a texture with a texture_map may not be used as defaults.

You may change the defaults several times throughout a scene as you wish. Subsequent #default statements begin with the defaults that were in effect at the time. If you wish to reset to the original POV-Ray defaults then you should first save them as follows:

 //At top of file
 #declare Original_Default = texture {}

later after changing defaults you may restore it with...

 #default {texture {Original_Default}}

If you do not specify a texture for an object then the default texture is attached when the object appears in the scene. It is not attached when an object is declared. For example:

 #declare My_Object =
  sphere{ <0,0,0>, 1 } // Default texture not applied
  object{ My_Object }  // Default texture added here

You may force a default texture to be added by using an empty texture statement as follows:

 #declare My_Thing =
  sphere { <0,0,0>, 1 texture {} } // Default texture applied

The original POV-Ray defaults for all items are given throughout the documentation under each appropriate section.

3.2.2.5 The #version Directive

As POV-Ray has evolved from version 1.0 through 3.6 we have made every effort to maintain some amount of backwards compatibility with earlier versions. Some old or obsolete features can be handled directly without any special consideration by the user. Some old or obsolete features can no longer be handled at all. However some old features can still be used if you warn POV-Ray that this is an older scene. The #version directive can be used to switch version compatibility to different setting several times throughout a scene file. The syntax is:

VERSION_DIRECTIVE: 
    #version FLOAT;

Note: there should be a semi-colon after the float expression in a #version directive. This semi-colon is introduced in POV-Ray version 3.1. If omitted, it generates a warning and some macros may not work properly.

Additionally you may use the Version=n.n option or the +MVn.n switch to establish the initial setting. See "Language Version" for details. For example one feature introduced in 2.0 that was incompatible with any 1.0 scene files is the parsing of float expressions. Using #version 1.0 turns off expression parsing as well as many warning messages so that nearly all 1.0 files will still work. Naturally the default setting for this option is #version 3.5.

Note: Some obsolete or re-designed features are totally unavailable in the current version of POV-Ray REGARDLES OF THE VERSION SETTING. Details on these features are noted throughout this documentation.

The built-in float identifier version contains the current setting of the version compatibility option. See "Float Expressions: Built-in Variables". Together with the built-in version identifier the #version directive allows you to save and restore the previous values of this compatibility setting. The new #local identifier option is especially useful here. For example suppose mystuff.inc is in version 1 format. At the top of the file you could put:

 #local 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

Future versions of POV-Ray may not continue to maintain full backward compatibility even with the #version directive. We strongly encourage you to phase in current version syntax as much as possible.

3.2.2.6 Conditional Directives

POV-Ray allows a variety of language directives to implement conditional parsing of various sections of your scene file. This is especially useful in describing the motion for animations but it has other uses as well. Also available is a #while loop directive. You may nest conditional directives 200 levels deep.

3.2.2.6.1 The #if...#else...#end Directives

IF_DIRECTIVE:
    #if ( Cond ) TOKENS... [#else TOKENS...] #end

 #declare Which=1;
 #if (Which)
   box { 0, 1 }
 #else
   sphere { 0, 1 }
 #end

 #declare Which=1;
 #if (Which)
   box { 0, 1 }
 #end

   #if( #if(yes) yes #end ) #end

3.2.2.6.2 The #ifdef and #ifndef Directives

IFDEF_DIRECTIVE:
    #ifdef ( IDENTIFIER ) TOKENS... [#else TOKENS...] #end
IFNDEF_DIRECTIVE:
    #ifndef ( IDENTIFIER ) TOKENS... [#else TOKENS...] #end

  #ifdef (User_Thing)
  // This section is parsed if the
  // identifier "User_Thing" was
  // previously declared
  object{User_Thing} // invoke identifier
 #else
  // This section is parsed if the
  // identifier "User_Thing" was not
  // previously declared
  box{<0,0,0>,<1,1,1>} // use a default
 #end
  // End of conditional part

 #declare MyArray=array[10]
 //#declare MyArray[0]=7;
 #ifdef(MyArray[0])
    #debug "first element is assigned\n"
 #else 
    #debug "first element is not assigned\n"
 #end

3.2.2.6.3 The #switch, #case, #range and #break Directives

SWITCH_DIRECTIVE:
   #switch ( Switch_Value ) SWITCH_CLAUSE... [#else TOKENS...] #end
SWITCH_CLAUSE:
   #case( Case_Value ) TOKENS... [#break] |
   #range( Low_Value , High_Value ) TOKENS... [#break]

 #switch (VALUE)
  #case (TEST_1)
   // This section is parsed if VALUE=TEST_1
  #break //First case ends
  #case (TEST_2)
   // This section is parsed if VALUE=TEST_2
  #break //Second case ends
  #range (LOW_1,HIGH_1)
   // This section is parsed if (VALUE>=LOW_1)&(VALUE<=HIGH_1)
  #break //Third case ends
  #range (LOW_2,HIGH_2)
   // This section is parsed if (VALUE>=LOW_2)&(VALUE<=HIGH_2)
  #break //Fourth case ends
  #else
   // This section is parsed if no other case or
   // range is true.
 #end // End of conditional part

3.2.2.6.4 The #while...#end Directive

WHILE_DIRECTIVE:
    #while ( Cond ) TOKENS... #end

 #declare Count=0;
 #while (Count < 5)
  object { MyObject translate x*3*Count }
  #declare Count=Count+1;
 #end

3.2.2.7 User Message Directives

3.2.2.7.1 Text Message Streams

TEXT_STREAM_DIRECTIVE:
    #debug STRING | #error STRING | #warning STRING

 #switch (clock*360)
  #range (0,180)
   #debug "Clock in 0 to 180 range\n"
  #break
  #range (180,360)
   #debug "Clock in 180 to 360 range\n"
  #break
  #else
   #warning "Clock outside expected range\n"
   #warning concat("Value is:",str(clock*360,5,0),"\n")
 #end

There are seven distinct text streams that POV-Ray uses for output. You may output only to three of them. On some versions of POV-Ray, each stream is designated by a particular color. Text from these streams are displayed whenever it is appropriate so there is often an intermixing of the text. The distinction is only important if you choose to turn some of the streams off or to direct some of the streams to text files. On some systems you may be able to review the streams separately in their own scroll-back buffer. See "Directing Text Streams to Files" for details on re-directing the streams to a text file.

Here is a description of how POV-Ray uses each stream. You may use them for whatever purpose you want except note that use of the #error stream causes a fatal error after the text is displayed.

Debug: This stream displays debugging messages. It was primarily designed for developers but this and other streams may also be used by the user to display messages from within their scene files.

Error: This stream displays fatal error messages. After displaying this text, POV-Ray will terminate. When the error is a scene parsing error, you may be shown several lines of scene text that leads up to the error.

Warning: This stream displays warning messages during the parsing of scene files and other warnings. Despite the warning, POV-Ray can continue to render the scene.

3.2.2.7.2 Text Formatting

Some escape sequences are available to include non-printing control characters in your text. These sequences are similar to those used in string literals in the C programming language. The sequences are:

For example:

 #debug "This is one line.\nBut this is another"\n

Depending on what platform you are using, they may not be fully supported for console output. However they will appear in any text file if you re-direct a stream to a file.

3.2.2.8 User Defined Macros

3.2.2.8.1 The #macro Directive

MACRO_DEFINITION:
#macro IDENTIFIER ([PARAM_IDENT] [, PARAM_IDENT]... ) TOKENS... #end

A macro must be declared before it is invoked. All macro names are global in scope and permanent in duration. You may redefine a macro by another #macro directive with the same name. The previous definition is lost. Macro names respond to #ifdef, #ifndef, and #undef directives. See "The #ifdef and #ifndef Directives" and "Destroying Identifiers with #undef".

3.2.2.8.2 Invoking Macros

MACRO_INVOCATION:
    MACRO_IDENTIFIER ( [ACTUAL_PARAM] [, ACTUAL_PARAM]... )
ACTUAL_PARAM:
    IDENTIFIER | RVALUE

An RVALUE is any value that can legally appear to the right of an equals sign in a #declare or #local declaration. See "Declaring identifiers" for information on RVALUEs. When the macro is invoked, a new local symbol table is created. The actual parameters are assigned to formal parameter identifiers as local, temporary variables. POV-Ray jumps to the body of the macro and continues parsing until the matching #end directive is reached. There, the local variables created by the parameters are destroyed as well as any local identifiers expressly created in the body of the macro. It then resumes parsing at the point where the macro was invoked. It is as though the body of the macro was cut and pasted into the scene at the point where the macro was invoked.

Note: it is possible to invoke a macro that was declared in another file. This is quite normal and in fact is how many "plug-ins" work (such as the popular Lens Flare macro). However, be aware that calling a macro that was declared in a file different from the one that it is being called from involves more overhead than calling one in the same file.

This is because POV-Ray does not tokenize and store its language. Calling a macro in another file therefore requires that the other file be opened and closed for each call. Normally, this overhead is inconsequential; however, if you are calling the macro many thousands of times, it can cause significant delays. A future version of the POV-Ray language will remove this problem.

Here is a simple macro that creates a window frame object when you specify the inner and outer dimensions.

#macro Make_Frame(OuterWidth,OuterHeight,InnerWidth,
                  InnerHeight,Depth)
  #local Horz = (OuterHeight-InnerHeight)/2;
  #local Vert = (OuterWidth-InnerWidth)/2;
  difference {
    box{
	  <0,0,0>,<OuterWidth,OuterHeight,Depth>
	}
    box{
	  <Vert,Horz,-0.1>,
      <OuterWidth-Vert,OuterHeight-Horz,Depth+0.1>
	}
  }
#end
Make_Frame(8,10,7,9,1) //invoke the macro

In this example, the macro has five float parameters. The actual parameters (the values 8, 10, 7, 9, and 1) are assigned to the five identifiers in the #macro formal parameter list. It is as though you had used the following five lines of code.

 #local OuterWidth = 8;
 #local OuterHeight = 10;
 #local InnerWidth, = 7;
 #local InnerHeight = 9;
 #local Depth = 1;

These five identifiers are stored in the same symbol table as any other local identifier such as Horz or Vert in this example. The parameters and local variables are all destroyed when the #end statement is reached. See "Identifier Name Collisions" for a detailed discussion of how local identifiers, parameters, and global identifiers work when a local identifier has the same name as a previously declared identifier.

3.2.2.8.3 Are POV-Ray Macros a Function or a Macro?

POV-Ray macros are a strange mix of macros and functions. In traditional computer programming languages, a macro works entirely by token substitution. The body of the routine is inserted into the invocation point by simply copying the tokens and parsing them as if they had been cut and pasted in place. Such cut-and-paste substitution is often called macro substitution because it is what macros are all about. In this respect, POV-Ray macros are exactly like traditional macros in that they use macro substitution for the body of the macro. However traditional macros also use this cut-and-paste substitution strategy for parameters but POV-Ray does not.

Suppose you have a macro in the C programming language Typical_Cmac(Param) and you invoke it as Typical_Cmac(else A=B). Anywhere that Param appears in the macro body, the four tokens else, A, =, and B are substituted into the program code using a cut-and-paste operation. No type checking is performed because anything is legal. The ability to pass an arbitrary group of tokens via a macro parameter is a powerful (and sadly often abused) feature of traditional macros.

After careful deliberation, we have decided against this type of parameters for our macros. The reason is that POV-Ray uses commas more frequently in its syntax than do most programming languages. Suppose you create a macro that is designed to operate on one vector and two floats. It might be defined OurMac(V,F1,F2). If you allow arbitrary strings of tokens and invoke a macro such as OurMac(<1,2,3>,4,5) then it is impossible to tell if this is a vector and two floats or if its 5 parameters with the two tokens < and 1 as the first parameter. If we design the macro to accept 5 parameters then we cannot invoke it like this... OurMac(MyVector,4,5).

Function parameters in traditional programming languages do not use token substitution to pass values. They create temporary, local variables to store parameters that are either constant values or identifier references which are in effect a pointer to a variable. POV-Ray macros use this function-like system for passing parameters to its macros. In our example OurMac(<1,2,3>,4,5), POV-Ray sees the < and knows it must be the start of a vector. It parses the whole vector expression and assigns it to the first parameter exactly as though you had used the statement #local V=<1,2,3>;.

Although we say that POV-Ray parameters are more like traditional function parameters than macro parameters, there still is one difference. Most languages require you to declare the type of each parameter in the definition before you use it but POV-Ray does not. This should be no surprise because most languages require you to declare the type of any identifier before you use it but POV-Ray does not. This means that if you pass the wrong type value in a POV-Ray macro parameter, it may not generate an error until you reference the identifier in the macro body. No type checking is performed as the parameter is passed. So in this very limited respect, POV-Ray parameters are somewhat macro-like but are mostly function-like.

3.2.2.8.4 Returning a Value Like a Function

When the body of a macro consists of statements that create an entire item such as an object, texture, etc. then the macro acts like a function which returns a single value. The Make_Frame macro example in the section "Invoking Macros" above is such a macro which returns a value that is an object. Here are some examples of how you might invoke it.

 union {  //make a union of two objects
   object{ Make_Frame(8,10,7,9,1) translate  20*x}
   object{ Make_Frame(8,10,7,9,1) translate -20*x}
 }
 #declare BigFrame = object{ Make_Frame(8,10,7,9,1)}
 #declare SmallFrame = object{ Make_Frame(5,4,4,3,0.5)}

Because no type checking is performed on parameters and because the expression syntax for floats, vectors, and colors is identical, you can create clever macros which work on all three. See the sample scene MACRO3.POV which includes this macro to interpolate values.

// Define the macro.  Parameters are:
//   T:  Middle value of time
//   T1: Initial time
//   T2: Final time
//   P1: Initial position (may be float, vector or color)
//   P2: Final position (may be float, vector or color)
//   Result is a value between P1 and P2 in the same proportion
//    as T is between T1 and T2.
#macro Interpolate(T,T1,T2,P1,P2)
   (P1+(T1+T/(T2-T1))*(P2-P1))
#end

You might invoke it with P1 and P2 as floats, vectors, or colors as follows.

sphere{
  Interpolate(I,0,15,<2,3,4>,<9,8,7>), //center location is vector
  Interpolate(I,0,15,3.0,5.5)          //radius is float
  pigment {
    color Interpolate(I,0,15,rgb<1,1,0>,rgb<0,1,1>)
  }
}

As the float value I varies from 0 to 15, the location, radius, and color of the sphere vary accordingly.

There is a danger in using macros as functions. In a traditional programming language function, the result to be returned is actually assigned to a temporary variable and the invoking code treats it as a variable of a given type. However macro substitution may result in invalid or undesired syntax. The definition of the macro Interpolate above has an outermost set of parentheses. If those parentheses are omitted, it will not matter in the examples above, but what if you do this...

 #declare Value = Interpolate(I,0,15,3.0,5.5)*15;

The end result is as if you had done...

 #declare Value = P1+(T1+T/(T2-T1))*(P2-P1) * 15;

which is syntactically legal but not mathematically correct because the P1 term is not multiplied. The parentheses in the original example solves this problem. The end result is as if you had done...

 #declare Value = (P1+(T1+T/(T2-T1))*(P2-P1)) * 15;

which is correct.

3.2.2.8.5 Returning Values Via Parameters

 #macro Turn_Me(Stuff,Degrees)
   #declare Stuff = object{Stuff rotate x*Degrees}
 #end

   #declare MyObject=box{0,1}
   Turn_Me(MyObject,30)

See "Identifier Name Collisions" for a detailed discussion of how local identifiers, parameters, and global identifiers work when a local identifier has the same name as a previously declared identifier.

While it is obvious that MyObject is an identifier and box{0,1} is not, it should be noted that Turn_Me(object{MyObject},30) will not work because object{MyObject} is considered an object statement and is not a pure identifier. This mistake is more likely to be made with float identifiers versus float expressions. Consider these examples.

  #declare Value=5.0;
  MyMacro(Value)     //MyMacro can change the value of Value but...
  MyMacro(+Value)    //This version and the rest are not lone
  MyMacro(Value+0.0) // identifiers. They are float expressions
  MyMacro(Value*1.0) // which cannot be changed.

Although all four invocations of MyMacro are passed the value 5.0, only the first may modify the value of the identifier.

More about "#macro"

• 3.8.4.8 Macro in 3.8.4 Language Directives
• 3.2.2.8 User Defined Macros in 3.2.2 Language Directives

More about "texture"

• 3.5 Textures in 3 POV-Ray Reference
• 3.8.10 Texture in 3.8 Quick Reference

3.2.1 Language Basics

3.2.2 Language Directives

3.3 Scene Settings