1.1 --- a/include/sgl.h	Wed Jun 27 05:15:50 2012 +0300
     1.2 +++ b/include/sgl.h	Wed Jun 27 05:16:25 2012 +0300
     1.3 @@ -7,16 +7,49 @@
     1.4  #define SGL_STEREO		8
     1.5  #define SGL_MULTISAMPLE	16
     1.6  
     1.7 -typedef void (*sgl_create_callback_t)(int);
     1.8 -typedef void (*sgl_close_callback_t)(int);
     1.9 +/* --- callback types ---
    1.10 + * All event callbacks are entered with the corresponding OpenGL context being current.
    1.11 + * It is safe to issue OpenGL commands in all callbacks functions, unless explicitly
    1.12 + * stated otherwise below.
    1.13 + */
    1.14 +
    1.15 +/* Create callback is called just after a window and its OpenGL context is created */
    1.16 +typedef void (*sgl_create_callback_t)(int window);
    1.17 +/* Close callback is called before the window and its OpenGL context is destroyed */
    1.18 +typedef void (*sgl_close_callback_t)(int window);
    1.19 +/* The display callback is called whenever the window needs repainting. This is
    1.20 + * the only place you should perform drawing.
    1.21 + */
    1.22  typedef void (*sgl_display_callback_t)(void);
    1.23 -typedef void (*sgl_reshape_callback_t)(int, int);
    1.24 -typedef void (*sgl_keyboard_callback_t)(int, int);
    1.25 -typedef void (*sgl_mouse_callback_t)(int, int, int, int, int);
    1.26 -typedef void (*sgl_motion_callback_t)(int, int, int);
    1.27 -typedef void (*sgl_passive_callback_t)(int, int, int);
    1.28 +/* Reshape is called whenever the window size changes, and at least once for
    1.29 + * each newly created window, just after the call to the create callback. */
    1.30 +typedef void (*sgl_reshape_callback_t)(int width, int height);
    1.31 +/* The keyboard callback is called whenever a key is pressed or released */
    1.32 +typedef void (*sgl_keyboard_callback_t)(int key, int pressed);
    1.33 +/* The mouse callback is called whenever a mouse button is pressed or released
    1.34 + * over the window. The first argument is the touch id for multitouch devices.
    1.35 + * For regular mouse events it is always 0. */
    1.36 +typedef void (*sgl_mouse_callback_t)(int id, int button, int pressed, int x, int y);
    1.37 +/* The motion callback is called when the user drags the mouse around with any
    1.38 + * mouse buttons held down.  The first argument is the touch id for multitouch
    1.39 + * devices. */
    1.40 +typedef void (*sgl_motion_callback_t)(int id, int x, int y);
    1.41 +/* Passive gets called whenever the mouse is moved without any button being
    1.42 + * held.  The first argument is the touch id for multitouch devices.
    1.43 + *
    1.44 + * Avoid setting this callback unless absolutely necessary, because it will
    1.45 + * generate a huge volume of events whenever the mouse moves over the window. */
    1.46 +typedef void (*sgl_passive_callback_t)(int id, int x, int y);
    1.47 +/* Setting the idle callback will change the behaviour of the library. Instead
    1.48 + * of blocking, to wait for events from the window system, it will poll for
    1.49 + * events and after processing them will call this idle callback.
    1.50 + *
    1.51 + * Avoid setting this callback unless absolutely necessary, because it will
    1.52 + * turn your program into busy-looping mode, consuming all possible CPU time
    1.53 + * allocated to it by the system. */
    1.54  typedef void (*sgl_idle_callback_t)(void);
    1.55  
    1.56 +/* symbolic names for each callback */
    1.57  enum {
    1.58  	SGL_CREATE,
    1.59  	SGL_CLOSE,