# HG changeset patch
# User John Tsiombikas <nuclear@member.fsf.org>
# Date 1340763385 -10800
# Node ID a7b96de14be845a32fba1351f88bab49199d5c8d
# Parent  b3374e30361cc3529654b8a92a2d364f5492d6e3# Parent  9841c90ec769e28ffdddb1c8f05bc83152ecb5ba
merged with main

diff -r b3374e30361c -r a7b96de14be8 include/sgl.h
--- a/include/sgl.h	Wed Jun 27 05:15:50 2012 +0300
+++ b/include/sgl.h	Wed Jun 27 05:16:25 2012 +0300
@@ -7,16 +7,49 @@
 #define SGL_STEREO		8
 #define SGL_MULTISAMPLE	16
 
-typedef void (*sgl_create_callback_t)(int);
-typedef void (*sgl_close_callback_t)(int);
+/* --- callback types ---
+ * All event callbacks are entered with the corresponding OpenGL context being current.
+ * It is safe to issue OpenGL commands in all callbacks functions, unless explicitly
+ * stated otherwise below.
+ */
+
+/* Create callback is called just after a window and its OpenGL context is created */
+typedef void (*sgl_create_callback_t)(int window);
+/* Close callback is called before the window and its OpenGL context is destroyed */
+typedef void (*sgl_close_callback_t)(int window);
+/* The display callback is called whenever the window needs repainting. This is
+ * the only place you should perform drawing.
+ */
 typedef void (*sgl_display_callback_t)(void);
-typedef void (*sgl_reshape_callback_t)(int, int);
-typedef void (*sgl_keyboard_callback_t)(int, int);
-typedef void (*sgl_mouse_callback_t)(int, int, int, int, int);
-typedef void (*sgl_motion_callback_t)(int, int, int);
-typedef void (*sgl_passive_callback_t)(int, int, int);
+/* Reshape is called whenever the window size changes, and at least once for
+ * each newly created window, just after the call to the create callback. */
+typedef void (*sgl_reshape_callback_t)(int width, int height);
+/* The keyboard callback is called whenever a key is pressed or released */
+typedef void (*sgl_keyboard_callback_t)(int key, int pressed);
+/* The mouse callback is called whenever a mouse button is pressed or released
+ * over the window. The first argument is the touch id for multitouch devices.
+ * For regular mouse events it is always 0. */
+typedef void (*sgl_mouse_callback_t)(int id, int button, int pressed, int x, int y);
+/* The motion callback is called when the user drags the mouse around with any
+ * mouse buttons held down.  The first argument is the touch id for multitouch
+ * devices. */
+typedef void (*sgl_motion_callback_t)(int id, int x, int y);
+/* Passive gets called whenever the mouse is moved without any button being
+ * held.  The first argument is the touch id for multitouch devices.
+ *
+ * Avoid setting this callback unless absolutely necessary, because it will
+ * generate a huge volume of events whenever the mouse moves over the window. */
+typedef void (*sgl_passive_callback_t)(int id, int x, int y);
+/* Setting the idle callback will change the behaviour of the library. Instead
+ * of blocking, to wait for events from the window system, it will poll for
+ * events and after processing them will call this idle callback.
+ *
+ * Avoid setting this callback unless absolutely necessary, because it will
+ * turn your program into busy-looping mode, consuming all possible CPU time
+ * allocated to it by the system. */
 typedef void (*sgl_idle_callback_t)(void);
 
+/* symbolic names for each callback */
 enum {
 	SGL_CREATE,
 	SGL_CLOSE,