HowTo:Use macros and loops

Loops and Macros are usually created to do one set of code thousands of times. The beauty of the loop is that the code can reference an array or a spline to write a rollercoaster track or a roadway such that very complicated scenes can be created with the use of simple declared variables.

Loops

Loops may be constructed through the use of the #while statement. A typical loop may be constructed as follows.

#declare step = 0;
#declare steps = 100;
#while (step <= steps)
  #sphere { step*x, 0.4 pigment {Blue} }
  #declare step = step + 1;
#end

Nested loops may be created to generate a two or three dimensional aspect to the scene. Beware that creating extra nested loops will dramatically increase the parse time for the scene.

The following nested loop will draw a series of Blue balls on the XZ plain

#declare xpos = 0;
#declare zpos = 0;
#declare xfinal = 10;
#declare zfinal = 10;
#while (xpos <= xfinal)
  #while (zpos <= zfinal)
    #sphere { <xpos,0,zpos> 0.4 pigment {Blue} }
    #declare zpos = zpos + 1;
  #end
  #declare xpos = xpos + 1;
  #declare zpos = 0;
#end

Macros

The essential custom functions of PoV-Ray. These are blocks of code that make calculations, or make objects, or if used in a series can make many objects with all of them different.

Macros are declared like this:

#macro {Macro_Name}({Macro_Parameters})
  {Macro_Body}
#end

Macro Name

The name of the macro. Can be as simple or as complex as you want it to be. From a programmer's perspective, it's best to name it in a semi-descriptive way of what you're trying to do.

#macro MakeSpheres()
//Make a layer of spheres
#end

is much more understandable than

#macro MS()
//Make a layer of spheres
#end

Where as the latter of the two could be confused with "MakeSplines" or something. You never know.

Macro Parameters

A comma delineated list of variables that you will use in the macro. They can be changed if needed, but don't have to be always.

#macro MakeSpheres(height, layer_color)
//Make a layer of spheres
//  height - height of layer
//  layer_color - pigment of the layer
#end

Here, parameters for height and color are added. These can change the macro's behavior.

Macro Body

The real juice of the macro. This is where you do loops or object creation or loops with object creation, whatever. This is where you get the job done.

#macro MakeSpheres(height, layer_color)
//Make a layer of spheres
//  height - height of layer
//  layer_color - pigment of the layer
  #declare xpos = 0;
  #declare zpos = 0;
  #declare xfinal = 10;
  #declare zfinal = 10;
  #while (xpos <= xfinal)
    #while (zpos <= zfinal)
      // Notice that height and layer_color are inserted here.
      #sphere { <xpos,height,zpos> 0.4 pigment { layer_color } }
      #declare zpos = zpos + 1;
    #end
    #declare xpos = xpos + 1;
    #declare zpos = 0;
  #end
#end                

// The macro is invoked three times with different parameters
MakeSpheres(0, Blue)
MakeSpheres(2, Red)
MakeSpheres(1, White)