Difference between revisions of "HowTo:Use macros and loops"

From POV-Wiki
Jump to navigation Jump to search
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
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 and Macros are usually created to do one set of code many 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 ==
 +
See also [[HowTo:Use_conditional_structures#The_.23while.2C_.23end_construct_.28Loops.29|HowTo:Use_conditional_structures#The #while, #end construct]]
  
 
Loops may be constructed through the use of the #while statement. A typical loop may be constructed as follows.
 
Loops may be constructed through the use of the #while statement. A typical loop may be constructed as follows.
Line 14: Line 15:
 
</source>
 
</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.
+
Nested loops may be created to generate a two or three dimensional aspect to the scene. Beware that creating extra nested loops may dramatically increase the parse time for the scene.
  
 
The following nested loop will draw a series of Blue balls on the XZ plain
 
The following nested loop will draw a series of Blue balls on the XZ plain
Line 44: Line 45:
 
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.
 
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 MakeMetal()
+
<source lang="pov">#macro MakeSpheres()
//Make a metal-type material
+
//Make a layer of spheres
 
#end</source>
 
#end</source>
 
is much more understandable than
 
is much more understandable than
<source lang="pov">#macro MM()
+
<source lang="pov">#macro MS()
//make a metal-type material
+
//Make a layer of spheres
 
#end</source>
 
#end</source>
Where as the latter of the two could be confused with "MakeMatte" or something. You never know.
+
Where as the latter of the two could be confused with "MakeSplines" or something. You never know.
  
 
===Macro Parameters===
 
===Macro Parameters===
 
A comma delineated list of variables that you will use in the macro.
 
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.
 
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===
 
===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.
 
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>

Latest revision as of 20:08, 10 June 2008

Loops and Macros are usually created to do one set of code many 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

See also HowTo:Use_conditional_structures#The #while, #end construct

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 may 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)