/*
 *  call-seq:
 *    Clock.delay( time, gran=12, nice=false )  ->  Integer
 *
 *  time::  The target delay time, in milliseconds.
 *          (Non-negative integer. Required.)
 *  gran::  The assumed granularity (in ms) of the system clock.
 *          (Non-negative integer. Optional. Default: 12.)
 *  nice::  If true, try to let other ruby threads run during the delay.
 *          (true or false. Optional. Default: false.)
 *
 *  Returns:: The actual delay time, in milliseconds.
 *
 *  Pause the program for +time+ milliseconds. This function is more
 *  accurate than Clock.wait, but uses slightly more CPU time. Both
 *  this function and Clock.wait can be used to slow down the
 *  framerate so that the application doesn't use too much CPU time.
 *  See also Clock#tick for a good and easy way to limit the
 *  framerate.
 *
 *  This function uses "busy waiting" during the last part
 *  of the delay, for increased accuracy. The value of +gran+ affects
 *  how many milliseconds of the delay are spent in busy waiting, and thus
 *  how much CPU it uses. A smaller +gran+ value uses less CPU, but if
 *  it's smaller than the true system granularity, this function may
 *  delay a few milliseconds too long. The default value (12ms) is very
 *  safe, but a value of approximately 5ms would give a better balance
 *  between accuracy and CPU usage on most modern computers.
 *  A granularity of 0ms makes this method act the same as Clock.wait
 *  (i.e. no busy waiting at all, very low CPU usage).
 *
 *  If +nice+ is true, this function will try to allow other ruby
 *  threads to run during this function. Otherwise, other ruby threads
 *  will probably also be paused. Setting +nice+ to true is only
 *  useful if your application is multithreaded. It's safe (but
 *  pointless) to use this feature for single threaded applications.
 *
 *  The Rubygame timer system will be initialized when you call this
 *  function, if it has not been already. See Clock.runtime.
 *
 */
VALUE rbgm_clock_delay(int argc, VALUE *argv, VALUE module)
{
  rg_init_sdl_timer();

  VALUE vtime, vgran, vnice;

  rb_scan_args(argc,argv,"12", &vtime, &vgran, &vnice);

  int delay = NUM2INT(vtime);
  if( delay < 0 )
  {
    delay = 0;
  }

  int gran;
  if( RTEST(vgran) )
  {
    gran = NUM2UINT(vgran);
    if( gran < 0 )
    {
      gran = 0;
    }
  }
  else
  {
    gran = WORST_CLOCK_ACCURACY;
  }

  int nice = (vnice == Qtrue) ? 1 : 0;

  return UINT2NUM( accurate_delay(delay, gran, nice) );
}