src/timer.c

   1 #include "timer.h"
   2
   3 extern ChimaraGlkPrivate *glk_data;
   4
   5 /**
   6  * You can request that an event be sent at fixed intervals, regardless of what
   7  * the player does. Unlike input events, timer events can be tested for with
   8  * glk_select_poll() as well as glk_select().
   9  *
  10  * Initially, there is no timer and you get no timer events. If you call
  11  * glk_request_timer_events(N), with N not 0, you will get timer events about
  12  * every N milliseconds thereafter. (Assuming that they are supported -- if
  13  * not, glk_request_timer_events() has no effect.) Unlike keyboard and mouse
  14  * events, timer events will continue until you shut them off. You do not have
  15  * to re-request them every time you get one. Call glk_request_timer_events(0)
  16  * to stop getting timer events.
  17  *
  18  * The rule is that when you call glk_select() or glk_select_poll(), if it has
  19  * been more than N milliseconds since the last timer event, and (for
  20  * glk_select()) if there is no player input, you will receive an event whose
  21  * type is evtype_Timer. (win, val1, and val2 will all be 0.)
  22  *
  23  * Timer events do not stack up. If you spend 10N milliseconds doing
  24  * computation, and then call glk_select(), you will not get ten timer events
  25  * in a row. The library will simply note that it has been more than N
  26  * milliseconds, and return a timer event right away. If you call glk_select()
  27  * again immediately, it will be N milliseconds before the next timer event.
  28  *
  29  * This means that the timing of timer events is approximate, and the library
  30  * will err on the side of being late. If there is a conflict between player
  31  * input events and timer events, the player input takes precedence. [This
  32  * prevents the user from being locked out by overly enthusiastic timer events.
  33  * Unfortunately, it also means that your timer can be locked out on slower
  34  * machines, if the player pounds too enthusiastically on the keyboard. Sorry.
  35  * If you want a real-time operating system, talk to Wind River.]
  36  *
  37  * [I don't have to tell you that a millisecond is one thousandth of a second,
  38  * do I?]
  39  *
  40  * NOTE: setting a new timer will overwrite the old timer if one was in place.
  41  */
  42 void
  43 glk_request_timer_events(glui32 millisecs)
  44 {
  45         // Stop any existing timer
  46         if(glk_data->timer_id != 0) {
  47                 g_source_remove(glk_data->timer_id);
  48                 glk_data->timer_id = 0;
  49         }
  50
  51         if(millisecs == 0)
  52                 return;
  53
  54         glk_data->timer_id = g_timeout_add(millisecs, push_timer_event, NULL);
  55 }
  56
  57 /**
  58  * Internal function: push a new timer event on the event stack.
  59  * Will always return TRUE
  60  */
  61 gboolean
  62 push_timer_event(gpointer data)
  63 {
  64         event_throw(evtype_Timer, NULL, 0, 0);
  65
  66         return TRUE;
  67 }