From b2339ceaec8eb1b3225cd642f611ccaf0daf98be Mon Sep 17 00:00:00 2001
From: NatureFreshMilk <naturefreshmilk@github.com>
Date: Tue, 19 Mar 2019 08:21:47 +0100
Subject: [PATCH] add some docs for #20

---
 doc/incrementalrendering.md | 58 +++++++++++++++++++++++++++++++++++++
 readme.md                   |  4 +++
 2 files changed, 62 insertions(+)
 create mode 100644 doc/incrementalrendering.md

diff --git a/doc/incrementalrendering.md b/doc/incrementalrendering.md
new file mode 100644
index 0000000..7e4e4f5
--- /dev/null
+++ b/doc/incrementalrendering.md
@@ -0,0 +1,58 @@
+
+# Incremental rendering
+
+Incremental rendering works with the help of the *mtime* column
+on the minetest database.
+
+Every insert or update changes the *mtime* column to the current timestamp (with the help of triggers).
+This way changes to the blocks can be detected by remembering the mtime of the
+last query.
+
+
+## Table *blocks* (minetest db)
+
+posx	| posy	| posz	| data	| mtime
+---	| ---	| ---	| ---	|
+10	| 11	| 12	| ABC	| 1552977950000
+20      | 21    | 22    | 123   | 1552977950010
+30      | 31    | 32    | XYZ   | **1552977950020**
+40      | 41    | 42    | A12   | 1552977950030
+50      | 51    | 52    | B34   | 1552977950040
+
+## Table *settings* (mapserver db)
+
+key		| value
+---		|
+last\_mtime	| **1552977950020**
+
+## Query example
+
+The following query will return all changed blocks since the last call:
+
+```
+select posx,posy,posz,data,mtime
+from blocks b
+where b.mtime > 1552977950020
+order by b.mtime asc
+limit 1000
+
+```
+
+Additionally it will limit the returned rows so the mapserver can be started and stopped at any time
+without processing all new data at once.
+
+After that query the highest *mtime* is stored again in the mapserver database.
+
+## Schedule
+
+Incremental rendering is executed periodically:
+
+* Without pause between calls if there is more data available (catch-up after mapserver downtime)
+* With a 5 second pause between calls if there is no new data
+
+## About realtime
+
+Of course there are delays between placing/removing blocks and the tiles on the mapserver.
+The minetest setting ** server\_map\_save\_interval ** is responsible for the delay to the mapserver (defaults to 5.3 seconds)
+Don't try to decrease this value too much on your minetest instance, it has a performance impact!
+
diff --git a/readme.md b/readme.md
index 1603d03..3010f92 100644
--- a/readme.md
+++ b/readme.md
@@ -14,6 +14,10 @@ Realtime mapserver for [Minetest](https://minetest.net)
 * [License](doc/license.md)
 * [Changelog](doc/changelog.md)
 
+# How it works
+
+See: [Incremental rendering](doc/incrementalrendering.md)
+
 # Compatibility
 
 * Minetest 0.4.15 - 0.4.17.1