Piece generators are introduced.

Author: EVGVir

README.md

@@ -19,3 +19,4 @@ The library supports the following features:
 - [Movements reflection](doc#movements-reflection) - layers rotation
   in the order opposite to a provided one.
 - A set of predefined [patterns](doc/patterns-3x3x3) for 3x3x3 cubes.
+- [Pieces form customization](doc#piece-generator).

doc/README.md

@@ -187,3 +187,56 @@ rubik_cube_reflect_movements(fwd_movements)
 ```
 
 ![](movements-reflection/movements-reflection.gif)
+
+
+Advanced Technics
+-----------------
+
+### [Piece Generators](piece-generators)
+
+Pieces form can be customized by means of piece generators —
+special macros which can be separatly implemented. Each generator must
+be implemented in a separate file. A cube created by a customized
+generator is created by the `rubik_cube_generate_cube(...)` macro
+instead of `rubik_cube_create_cube(...)`.
+
+A generator implementation must contain only the body of the macro
+without `#macro ...` part (because of scene description language
+limitations). The macro is taking the following parameters (and so
+they are available in the file as predefined variables):
+- `dim` — the cube dimensions (3D vector).
+- `pos` — position of the piece to be generated (3D vector). The
+  position coordinates corresponds to the piece number in order from
+  left to right, from bottom to top and from front to back.
+- `gen_param` — a parameter which is passed to the generator. If
+  several parameters must be passed, they can be combined in an array.
+
+Normally, a generator returns a piece which is embedded into a cube
+with coordinates `<0, 0, 0>`, `<1, 1, 1>`.
+
+For example, a cube made of spheres of two alternating colors:
+
+![](piece-generators/sphere.png)
+
+can be created by the following
+[piece generator](piece-generators/sphere.inc):
+```
+sphere {
+  0, 0.5
+  pigment {
+    gen_param[mod(pos.x + pos.y + pos.z, 2)]
+  }
+  translate 0.5
+}
+```
+
+The file with such implemetation is then
+[passed](piece-generators/sphere.pov) to the
+`rubik_cube_generate_cube(...)` macro to create a cube:
+```
+rubik_cube_generate_cube(
+  <3, 3, 3>,              // Cube dimensions.
+  "sphere.inc",           // Piece generator.
+  array[2] {Red, White}   // Piece generator parameter.
+)
+```

doc/piece-generators/sphere.inc

@@ -0,0 +1,7 @@
+sphere {
+  0, 0.5
+  pigment {
+    gen_param[mod(pos.x + pos.y + pos.z, 2)]
+  }
+  translate 0.5
+}

doc/piece-generators/sphere.ini

@@ -0,0 +1,5 @@
+Input_File_Name=sphere.pov
+Library_Path=../..
+Width=320
+Height=240
+Antialias=true

doc/piece-generators/sphere.png

@@ -0,0 +1,10 @@
+#include "../doc-scene.inc"
+#include "rubik-cube.inc"
+
+rubik_cube_to_object(
+  rubik_cube_generate_cube(
+    <3, 3, 3>,
+    "sphere.inc",
+    array[2] {Red, White}
+  )
+)

doc/piece-generators/sphere.pov

@@ -0,0 +1,24 @@
+// Generates a piece of cube with defined colors. Each piece is a cube
+// of 1 unit size.
+//
+// gen_param - array of six colors to be applied for the cube. Colors
+//   are ordered in the following way: right face (0); top face (1);
+//   back face (2); left face (3); bottom face (4); front face (5).
+//   Note. Interior faces are colored in black.
+
+object {
+  #local piece_colors = gen_param;
+
+  #if (pos.x != 0)         #local piece_colors[3] = Black; #end
+  #if (pos.x != dim.x - 1) #local piece_colors[0] = Black; #end
+  #if (pos.y != 0)         #local piece_colors[4] = Black; #end
+  #if (pos.y != dim.y - 1) #local piece_colors[1] = Black; #end
+  #if (pos.z != 0)         #local piece_colors[5] = Black; #end
+  #if (pos.z != dim.z - 1) #local piece_colors[2] = Black; #end
+
+  Round_Box(<-0.5, -0.5, -0.5>, <0.5, 0.5, 0.5>, 0.1, 1)
+  pigment {
+    cubic piece_colors[0], piece_colors[1], piece_colors[2], piece_colors[3], piece_colors[4], piece_colors[5]
+  }
+  translate 0.5
+}

rubik-cube-generator-cube.inc

@@ -8,49 +8,41 @@
 #declare rubik_cube_colors_classic = array[6] {Green, Red, Yellow, Blue, Orange, White};
 
 
-// Generates a piece of cube with defined colors.
+// Generates a piece of cube.
 //
-// colors - array of six colors to be applied for the piece. Colors
-//   are ordered in the same manner as for rubik_cube_create_cube()
-//   macro.
+// dim - dimensions of the cube (3D vector).
+// pos - piece position (3D vector), where the coordinates are numbers
+//   from 0 to corresponding dimension minus one.
+// gen_name - name of the file that contains the generator
+//   implementation.
+// gen_param - a parameter which is passed to the generator. If
+//   several parameters must be passed, they can be combined in an
+//   array.
+//
+// Normally, a generator returns a piece which is embedded into a cube
+// with coordinates <0, 0, 0>, <1, 1, 1>.
 //
 // Returns the generated piece.
-#macro rubik_cube_create_piece(colors)
-  object {
-    Round_Box(<-0.5, -0.5, -0.5>, <0.5, 0.5, 0.5>, 0.1, 1)
-    pigment {
-      cubic colors[0], colors[1], colors[2], colors[3], colors[4], colors[5]
-    }
-    translate <0.5, 0.5, 0.5>
-  }
+#macro rubik_cube_generate_piece(dim, pos, gen_name, gen_param)
+  #include gen_name
 #end
 
 
 // Returns a new cube (3D array of the generated cube pieces).
-// Pieces of the cube are smaller cubes of 1 unit size, so a cube
-// 3x3x3 will have size of 3 units.
+// Pieces of the cube are created by the provided generator.
 //
 // dim - dimensions of the cube (3D vector).
-// colors - array of six colors to be applied for the cube. Colors are
-//   ordered in the following way: right face (0); top face (1); back
-//   face (2); left face (3); bottom face (4); front face (5).
-//   Note. Interior faces are colored in black.
-#macro rubik_cube_create_cube(dim, colors)
+// gen_name - name of the file that contains the generator
+//   implementation.
+// gen_param - parameter which is passed to the generator.
+#macro rubik_cube_generate_cube(dim, gen_name, gen_param)
   #local rcube = array[dim.x][dim.y][dim.z];
   #for (pos_x, 0, dim.x - 1)
     #for (pos_y, 0, dim.y - 1)
       #for (pos_z, 0, dim.z - 1)
-        #local piece_colors = colors;
-        #if (pos_x != 0)         #local piece_colors[3] = Black; #end
-        #if (pos_x != dim.x - 1) #local piece_colors[0] = Black; #end
-        #if (pos_y != 0)         #local piece_colors[4] = Black; #end
-        #if (pos_y != dim.y - 1) #local piece_colors[1] = Black; #end
-        #if (pos_z != 0)         #local piece_colors[5] = Black; #end
-        #if (pos_z != dim.z - 1) #local piece_colors[2] = Black; #end
-
         #local rcube[pos_x][pos_y][pos_z] =
         object {
-          rubik_cube_create_piece(piece_colors)
+          rubik_cube_generate_piece(dim, <pos_x, pos_y, pos_z>, gen_name, gen_param)
           transform {
             translate <pos_x, pos_y, pos_z> - <dim.x / 2, dim.y / 2, dim.z / 2>
           }
@@ -63,6 +55,20 @@
 #end
 
 
+// Returns a new cube (3D array of the generated cube pieces).
+// Pieces of the cube are smaller cubes of 1 unit size, so a cube
+// 3x3x3 will have size of 3 units.
+//
+// dim - dimensions of the cube (3D vector).
+// colors - array of six colors to be applied for the cube. Colors are
+//   ordered in the following way: right face (0); top face (1); back
+//   face (2); left face (3); bottom face (4); front face (5).
+//   Note. Interior faces are colored in black.
+#macro rubik_cube_create_cube(dim, colors)
+  rubik_cube_generate_cube(dim, "rubik-cube-generator-cube.inc", colors)
+#end
+
+
 // Returns dimensions of the layers perpendicular to the provided
 // axis.
 //

rubik-cube.inc

@@ -3,4 +3,5 @@
 ../doc/layers-rotation/layers-rotation-2x4x2.ini
 ../doc/layers-rotation/layers-rotation-3x3x3.ini
 ../doc/notation/notation.ini
+../doc/piece-generators/sphere.ini
 ../doc/simple-cube/simple-cube.ini