/lib/pods/SDL/Time.pod

http://github.com/PerlGameDev/SDL · Unknown · 73 lines · 41 code · 32 blank · 0 comment · 0 complexity · 9913c69a1565afbfda5088f053955ce9 MD5 · raw file

  1. =pod
  2. =head1 NAME
  3. SDL::Time - An SDL Perl extension for managing timers
  4. =head1 CATEGORY
  5. Core
  6. =head1 SYNOPSIS
  7. use warnings;
  8. use strict;
  9. use threads;
  10. use threads::shared;
  11. use SDL::Time;
  12. package foo;
  13. use SDL ':all';
  14. SDL::init(SDL_INIT_TIMER);
  15. my $tick :shared = 0;
  16. sub ticker { $tick++; warn $tick; return 100; }
  17. package main;
  18. my $id = SDL::Time::add_timer(100, 'foo::ticker');
  19. sleep(2);
  20. SDL::Time::remove_timer($id);
  21. =head1 METHODS
  22. =head2 add_timer
  23. my $id = SDL::Timer::add_timer( $ms_interval, $callback );
  24. This runs in a separate thread and a cloned Perl thread.
  25. C<threads> and C<threads::shared> must be used to share any variables the timer uses.
  26. The C<$callback> function, specified with a string of the function's name, will be called after the milliseconds of C<$interval> have elapsed.
  27. The actual delay may be longer than specified depending on the underlying OS.
  28. The callback function is passed the current timer interval as well as the C<$interval> parameter and should return the next timer interval.
  29. If the return value from the callback is 0, the timer is cancelled; otherwise, the timer will continue to run.
  30. The timer callback function may run in a different thread to your main program, so it shouldn't call any functions from within itself.
  31. You may call SDL::push_event, however.
  32. C<SDL::Time::add_timer> returns the identifier value of the generated timer or undef on error.
  33. B<Note:> You must initialize (C<SDL::init>) the timer subsystem to use this function.
  34. =head2 remove_timer
  35. SDL::Timer::remove_timer( $id );
  36. The other way to cancel a timer is to use C<SDL::Time::remove_timer> on the C<$id> of a timer.
  37. This ID is the return value of the C<SDL::Time::add_timer> function.
  38. C<SDL::Time::remove_timer> returns C<0> on success or C<-1> on error.
  39. =head1 AUTHORS
  40. See L<SDL/AUTHORS>.
  41. =cut