From 056f99228ba618b1ea36fb6d8f300544b404fea7 Mon Sep 17 00:00:00 2001
From: Marcel Hellkamp <marc@gsites.de>
Date: Tue, 3 Apr 2018 13:28:20 +0200
Subject: [PATCH] Update README.md

---
 README.md | 37 +++++++++++++++++++++++++++++--------
 1 file changed, 29 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index d80e6bb..931483f 100755
--- a/README.md
+++ b/README.md
@@ -13,14 +13,22 @@ Pixelflut Protocol
 Pixelflut defines four main commands that are always supported to get you started:
 
 * `HELP`: Returns a short introductional help text.
-* `SIZE`: Returns the size of the canvas in pixel.
-* `PX <x> <y>` Return the current color of a pixel at position (x, y).
+* `SIZE`: Returns the size of the visible canvas in pixel as `SIZE <w> <h>`.
+* `PX <x> <y>` Return the current color of a pixel as `PX <x> <y> <rrggbb>`.
 * `PX <x> <y> <rrggbb(aa)>`: Draw a single pixel at position (x, y) with the specified hex color code.
   If the color code contains an alpha channel value, it is blended with the current color of the pixel.
 
-You can send multiple commands over the same TCP socket by terminating each command with a single newline character (`\n`).
+You can send multiple commands over the same connection by terminating each command with a single newline character (`\n`).
 
-Example: `echo "PX 23 42 ff8000" | netcat pixelflut.example.com 1337`
+Example:
+
+    $ echo "SIZE" | netcat pixelflut.example.com 1337
+    SIZE 800 600
+    $ echo "PX 23 42 ff8000" | netcat pixelflut.example.com 1337
+    $ echo "PX 32 42" | netcat pixelflut.example.com 1337
+    PX 23 42 ff8000
+
+Implementations MAY support additional commands or have less strict parsing rules (e.g. allow `\r\n` or any whitespace between parameters) but they MUST support the commands above. 
 
 Server Implementations
 ----------------------
@@ -29,7 +37,7 @@ This repository contains multiple implementations of the pixelflut protocol. Pul
 
 ### `/pixelflut` (python server)
 
-Server written in Python, based on gevent and pygame. Easy to hack with, but a bit slow.
+Server written in Python, based on gevent and pygame. Easy to hack with, but a bit slow. In fact, it was slowed down on purpose to be more fair and encourage smart drawing techniques instead of image spamming. Perfect for small groups.
 
     cd pixelflut
     sudo apt-get install python-gevent python-pygame python-cairo
@@ -38,7 +46,7 @@ Server written in Python, based on gevent and pygame. Easy to hack with, but a b
 
 #### `/pixelwar` (java server)
 
-Server written in Java8, based on netty and awt. Optimized for speed and large player groups, fast networks or high resolution projectors.
+Server written in Java8, based on netty and awt. Optimized for speed and large player groups, fast networks or high resolution projectors. This is probably the most portable version and runs on windows, too.
 
     cd pixelwar
     sudo apt-get install maven openjdk-8-jdk
@@ -47,7 +55,7 @@ Server written in Java8, based on netty and awt. Optimized for speed and large p
 
 #### `/pixelnuke` (C server)
 
-Server written in C, based on libevent2, OpenGL, GLFW and pthreads. It won't get any faster than this.
+Server written in C, based on libevent2, OpenGL, GLFW and pthreads. It won't get any faster than this. Prfect for fast networks and large groups.
 
     cd pixelnuke
     sudo apt-get install build-essential libevent-dev libglew-dev libglfw3-dev
@@ -61,8 +69,21 @@ Keyboard controls:
 * `c`: Clear the screen (50% black, hit multiple times)
 * `q` or `ESC`: Quit
 
+Additional Commands:
+
+* `STATS` Return statistics as `STATS <name>:<value> ...`
+  * `px:<uint>` Number of pixels drawn so far. Will overflow eventually.
+  * `conn:<uint>` Number of currently connected clients.
+
+Planned Features:
+- [x] Toggle between windowed/fullscreen mode and switch monitors in fullscreen-mode.
+- [ ] Persist pixel buffer between restarts. Use an mmap-ed file for pixel data?
+- [ ] Save to PPM (via key, timer or admin command) and add docs/tools to convert these into a video.
+- [ ] Support to draw directly to a framebuffer (no OpenGL or X Server dependency -> Raspberry-PI compatible)
+- [ ] Showcase-Mode: Players won't draw at the same time, but take turns. Each player gets N seconds of exclusive draw time)
+- [ ] Limit concurrent connections per IP.
+- [ ] Admin commands: Unlock additional commands with a password (e.g. `PX2 <x> <y> <rrggbbaa>` to draw to the overlay layer)
 
-Pull requests that improve performance or portability (e.g. Windows or RasPI) are always welcomed.
 
 Even more implementations
 -------------------------