Add voxelarea.lua helper to builtin

3 files changed, 57 insertions, 1 deletions

diff --git a/builtin/builtin.lua b/builtin/builtin.lua
index f10c6c7cf..d573cba90 100644
--- a/builtin/builtin.lua
+++ b/builtin/builtin.lua
@@ -25,4 +25,4 @@ dofile(minetest.get_modpath("__builtin").."/static_spawn.lua")
 dofile(minetest.get_modpath("__builtin").."/detached_inventory.lua")
 dofile(minetest.get_modpath("__builtin").."/falling.lua")
 dofile(minetest.get_modpath("__builtin").."/features.lua")
-
+dofile(minetest.get_modpath("__builtin").."/voxelarea.lua")
diff --git a/builtin/voxelarea.lua b/builtin/voxelarea.lua
new file mode 100644
index 000000000..9426c3acf
--- /dev/null
+++ b/builtin/voxelarea.lua
@@ -0,0 +1,46 @@
+VoxelArea = {
+	MinEdge = {x=1, y=1, z=1},
+	MaxEdge = {x=0, y=0, z=0},
+	ystride = 0,
+	zstride = 0,
+}
+
+function VoxelArea:new(o)
+	o = o or {}
+	setmetatable(o, self)
+	self.__index = self
+
+	local e = o:getExtent()
+	o.ystride = e.x
+	o.zstride = e.x * e.y
+
+	return o
+end
+
+function VoxelArea:getExtent()
+	return {
+		x = self.MaxEdge.x - self.MinEdge.x + 1,
+		y = self.MaxEdge.y - self.MinEdge.y + 1,
+		z = self.MaxEdge.z - self.MinEdge.z + 1,
+	}
+end
+
+function VoxelArea:getVolume()
+	local e = self:getExtent()
+	return e.x * e.y * e.z
+end
+
+function VoxelArea:index(x, y, z)
+	local i = (z - self.MinEdge.z) * self.zstride +
+			  (y - self.MinEdge.y) * self.ystride +
+			  (x - self.MinEdge.x) + 1
+	return math.floor(i)
+end
+
+function VoxelArea:indexp(p)
+	local i = (p.z - self.MinEdge.z) * self.zstride +
+			  (p.y - self.MinEdge.y) * self.ystride +
+			  (p.x - self.MinEdge.x) + 1
+	return math.floor(i)
+end
+
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 5920b97a0..c39098a7a 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -1572,6 +1572,16 @@ methods:
   ^ will be ignored
 - update_liquids():  Update liquid flow
 
+VoxelArea: A helper class for voxel areas
+- Can be created via VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}
+- Coordinates are *inclusive*, like most other things in Minetest
+methods:
+- getExtent():  returns a 3d vector containing the size of the area formed by MinEdge and MaxEdge
+- getVolume():  returns the volume of the area formed by MinEdge and MaxEdge
+- index(x, y, z):  returns the index of an absolute position in a flat array starting at 1
+  ^ useful for things like VoxelManip, raw Schematic specifiers, PerlinNoiseMap:get2d/3dMap, and so on
+- indexp(p):  same as above, except takes a vector
+
 Mapgen objects
 ---------------
 A mapgen object is a construct used in map generation.  Mapgen objects can be used by an on_generate