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?