SDL::App::FPS::Timer - a timer class for SDL::App::FPS

	my $timer = SDL::App::FPS::Timer->new(
		$time_to_first_shot,
		$count,
		$delay_between_shots,
		$randomize,
		$now,
		$callback,
		@arguments_to_callback
	);

	&{$callback}($self,$timer,$overdue,@arguments);

# Timer class for SDL::App::FPS - it represents on timer that is checked on
# each frame

package SDL::App::FPS::Timer;

# (C) by Tels <http://bloodgate.com/>

use strict;

use Exporter;
use SDL::App::FPS::Thingy;
use vars qw/@ISA $VERSION/;
@ISA = qw/SDL::App::FPS::Thingy Exporter/;

$VERSION = '0.04';

sub _init
  {
  my $self = shift;

  # times can be negative, for instance when clock goes backwards!
  $self->{time} = shift;			
  $self->{count} = shift;			# count < 0 => infitite
  $self->{delay} = shift || $self->{time};
  $self->{rand} = abs(shift || 0);		# wiggle firing
  if (($self->{rand} > abs($self->{time})) ||
      ($self->{rand} > abs($self->{delay})))
    {
    require Carp;
    Carp::croak ("Timer rand value cannot be greater than time or delay");
    }
  $self->{start} = shift;			# time we started to live
  $self->{code} = shift;			# callback
  if (ref($self->{code}) ne 'CODE')
    {
    require Carp; Carp::croak ("Timer needs a coderef as callback!");
    }
  $self->{args} = [ @_ ];			# additional arguments
  $self->{due} = 0;				# not yet
  $self->{next_shot} = $self->{start} + $self->{time};
  # add in random delay if necc.
  if ($self->{rand} != 0)
    {
    $self->{next_shot} += int(rand($self->{rand})- $self->{rand} / 2);
    }
  $self->{overdue} = 0;				# when we fire, we are late
						# by this amount

  if ($self->{time} == 0)			# well, maybe due right now
    {
    $self->_should_fire($self->{start});
    $self->fire();
    }

  $self;
  }

sub next_shot
  {
  # when will next shot be fired?
  my $self = shift;
  $self->{next_shot};
  }

sub fired
  {
  # did this timer fire?
  my $self = shift;
  $self->{due};
  }

sub count
  {
  # how many shots left?
  my $self = shift;
  $self->{count};
  }

sub _should_fire
  {
  # fire the timer
  my ($self,$now) = @_;

  $self->{due} = 1;
  $self->{overdue} = $now - $self->{next_shot};		# we are so late
  # our next shot will be then (regardless of when this shot was fired)

  $self->{next_shot} += $self->{delay};
  if ($self->{rand} != 0)
    {
    $self->{next_shot} += int(rand($self->{rand}) - $self->{rand} / 2);
    }
  $self->{count}-- if $self->{count} > 0;		# one shot less
  $self->{time} = $self->{delay};			# allow a positive
							# time and then
							# negative delays
  $self->{overdue};
  }

sub fire
  {
  # when the timer determined that it was due, this routine must be called
  # to make it really fire 
  my ($self,$overdue) = @_;

  $overdue = $self->{overdue} if !defined $overdue;	# FPS.pm sets it

  # fire timer now
  &{$self->{code}}( $self->{app}, $self, $overdue, @{$self->{args} });
  }

sub due
  {
  # check whether this timer is due or not, return 0 for not due, otherwise
  # returns 1
  my ($self,$now,$time_warp) = @_;
 
  $self->{due} = 0;				# not yet
  return 0
    if ($time_warp == 0) || ($self->{count} == 0) || ($self->{active} == 0);

  # freeze backwards looking timers if time goes forward and vice versa
  if ($self->{time} > 0)
    {
    return 0 if $time_warp < 0 || $now < $self->{next_shot};
    }
  else
    {
    return 0 if $time_warp > 0 || $now > $self->{next_shot};
    }
  $self->_should_fire($now); 
  $self->fire($now);
  1;
  }

sub is_due
  {
  # check whether this timer is due or not, return undef for not due, otherwise
  # returns the overdue time (e.g. the time in ms the timer should have fired
  # ago). If it returns something else than -1, 
  my ($self,$now,$time_warp) = @_;
 
  $self->{due} = 0;				# not yet
  return 
    if ($time_warp == 0) || ($self->{count} == 0) || ($self->{active} == 0);

  # freeze backwards looking timers if time goes forward and vice versa
  if ($self->{time} > 0)
    {
    return if $time_warp < 0 || $now < $self->{next_shot};
    }
  else
    {
    return if $time_warp > 0 || $now > $self->{next_shot};
    }
  $self->_should_fire($now); 
  }

1;

__END__