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