From bc62c3aaedc84c73a1039554bddc937abce77ed5 Mon Sep 17 00:00:00 2001
From: robo9k <robo@9k.lv>
Date: Sat, 7 Jun 2014 16:11:20 +0200
Subject: [PATCH] Add pure Python usage example for issue #3

q3py_hello.py uses ctypes to implement a part of the Quake 3
`game` module by printing hello world.
---
 doc/Doxyfile               |  2 +-
 doc/examples/q3py_hello.py | 45 ++++++++++++++++++++++++++++++++++++++
 doc/mainpage.dox           | 11 ++++++++++
 3 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 doc/examples/q3py_hello.py

diff --git a/doc/Doxyfile b/doc/Doxyfile
index 576b35b..b07b9fa 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -728,7 +728,7 @@ EXCLUDE_SYMBOLS        =
 # directories that contain example code fragments that are included (see
 # the \include command).
 
-EXAMPLE_PATH           = $(SRCDIR)/src
+EXAMPLE_PATH           = $(SRCDIR)/doc/examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
diff --git a/doc/examples/q3py_hello.py b/doc/examples/q3py_hello.py
new file mode 100644
index 0000000..f7afeb8
--- /dev/null
+++ b/doc/examples/q3py_hello.py
@@ -0,0 +1,45 @@
+import q3py
+import ctypes
+
+
+# Game module initialization function.
+# defined in ioq3/code/game/g_public.h
+GAME_INIT = 0
+
+# Engine system trap to print errors from game module.
+# Defined in ioq3/code/game/g_public.h
+G_ERROR = 1
+
+
+# Compare with trap_Error() from ioq3/code/game/g_syscalls.c
+def qerror(msg):
+    c_msg = ctypes.create_string_buffer(msg)
+
+    return q3py.syscall(G_ERROR, ctypes.addressof(c_msg))
+
+
+# Compare with G_InitGame() from ioq3/code/game/g_main.c
+def init_game(level_time, random_seed, restart):
+    print("Python init_game(level_time={level_time}, "
+          "random_seed={random_seed}, "
+          "restart={restart})".format(level_time=level_time,
+                                    random_seed=random_seed,
+                                    restart=restart))
+    qerror(b"Hello, Quake 3!")
+
+
+# Compare with vmMain() from ioq3/code/game/g_main.c
+def vm_main(cmd, arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8,
+            arg9, arg10, arg11):
+
+    if (cmd == GAME_INIT):
+        init_game(arg0, arg1, bool(arg2))
+
+    return -1
+
+
+# Related to dllEntry() in ioq3/code/game/g_syscalls.c
+def dll_entry():
+    print("Python dll_entry() called")
+
+    return vm_main
diff --git a/doc/mainpage.dox b/doc/mainpage.dox
index 984b08f..93e32fb 100644
--- a/doc/mainpage.dox
+++ b/doc/mainpage.dox
@@ -6,4 +6,15 @@ TODO: Describe how quake3.exe <-> q3py.so <-> libpython.so <-> my.py works
 
 For instructions on how to download, compile, install, configure
 and run q3py take a look at the \ref manual "user manual".
+
+\example q3py_hello.py
+To run this example;
+\code
+Q3PY_ENTRYPOINT='q3py_hello:dll_entry' PYTHONPATH=. ioq3ded +set vm_game 0 +map q3dm6
+\endcode
+
+Which sets this Python module and its `dll_entry()` method as q3py's
+entry point, instructs Python to look for modules in the current
+directory, starts the ioquake3 dedicated server with native game module
+and loads an arbitrary map.
 */