Previous:The #macro Directive Main Index Next:Are POV-Ray Macros a Function or a Macro?

#### Invoking Macros

You invoke the macro by specifying the macro name followed by a list of zero or more actual parameters enclosed in parentheses and separated by commas. The number of actual parameters must match the number of formal parameters in the definition. The parentheses are required even if no parameters are specified. The syntax is:

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.

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.

Previous:The #macro Directive Main Index Next:Are POV-Ray Macros a Function or a Macro?