Previous:Returning a Value Like a Function   Main Index   Next:POV-Ray Coordinate System

Returning Values Via Parameters

Sometimes it is necessary to have a macro return more than one value or you may simply prefer to return a value via a parameter as is typical in traditional programming language procedures. POV-Ray macros are capable of returning values this way. The syntax for POV-Ray macro parameters says that the actual parameter may be an IDENTIFIER or an RVALUE. Values may only be returned via a parameter if the parameter is an IDENTIFIER. Parameters that are RVALUES are constant values that cannot return information. An RVALUE is anything that legally may appear to the right of an equals sign in a #declare or #local directive. For example consider the following trivial macro which rotates an object about the x-axis.

 #macro Turn_Me(Stuff,Degrees)

   #declare Stuff = object{Stuff rotate x*Degrees}

 #end

This attempts to re-declare the identifier Stuff as the rotated version of the object. However the macro might be invoked with Turn_Me(box{0,1},30) which uses a box object as an RVALUE parameter. This won't work because the box is not an identifier. You can however do this

   #declare MyObject=box{0,1}

   Turn_Me(MyObject,30)

The identifier MyObject now contains the rotated box.

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

Previous:Returning a Value Like a Function   Main Index   Next:POV-Ray Coordinate System