HowTo:Use macros and loops

2008-04-01T03:52:13Z

Zemoxian: Added a macro example that expands on the previous loop example

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.

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

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

<source lang="pov">
#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
</source>

== 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:
<source lang="pov">#macro {Macro_Name}({Macro_Parameters})
{Macro_Body}
#end</source>

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

<source lang="pov">#macro MakeSpheres()
//Make a layer of spheres
#end</source>
is much more understandable than
<source lang="pov">#macro MS()
//Make a layer of spheres
#end</source>
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.
<source lang="pov">#macro MakeSpheres(height, layer_color)
//Make a layer of spheres
// height - height of layer
// layer_color - pigment of the layer
#end</source>
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.

<source lang="pov">#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)</source>

POV-Wiki - User contributions [en]

HowTo:Use macros and loops