NAME

SDL2::timer - SDL Time Management Routines

SYNOPSIS

    use SDL2 qw[:timer];

DESCRIPTION

SDL2::timer contains functions for dealing with time.

Functions

These may be imported by name or with the :timer tag.

SDL_GetTicks( )

Get the number of milliseconds since SDL library initialization.

        my $time = SDL_GetTicks( );

This value wraps if the program runs for more than ~49 days.

Returns an unsigned 32-bit value representing the number of milliseconds since the SDL library initialized.

SDL_TICKS_PASSED( ... )

Compare SDL ticks values, and return true if lhs has passed rhs.

For example, if you want to wait 100 ms, you could do this:

    my $timeout = SDL_GetTicks() + 100;
    while ( !SDL_TICKS_PASSED( SDL_GetTicks(), $timeout ) ) {

        # ... do work until timeout has elapsed
    }

Expected parameters include:

lhs - tick value to compare

rhs - tick value to compare

SDL_GetPerformanceCounter( )

Get the current value of the high resolution counter.

        my $high_timer = SDL_GetPerformanceCounter( );

This function is typically used for profiling.

The counter values are only meaningful relative to each other. Differences between values can be converted to times by using SDL_GetPerformanceFrequency( ).

Returns the current counter value.

SDL_GetPerformanceFrequency( )

Get the count per second of the high resolution counter.

        my $hz = SDL_GetPerformanceFrequency( );

Returns a platform-specific count per second.

SDL_Delay( ... )

Wait a specified number of milliseconds before returning.

        SDL_Delay( 1000 );

This function waits a specified number of milliseconds before returning. It waits at least the specified time, but possibly longer due to OS scheduling.

Expected parameters include:

ms - the number of milliseconds to delay

SDL_AddTimer( ... )

Call a callback function at a future time.

   my $id = SDL_AddTimer( 1000, sub ( $interval, $data ) { warn 'ping!'; $interval; } );

If you use this function, you must pass SDL_INIT_TIMER to SDL_Init( ... ).

The callback function is passed the current timer interval and returns the next timer interval. If the returned value is the same as the one passed in, the periodic alarm continues, otherwise a new alarm is scheduled. If the callback returns 0, the periodic alarm is cancelled.

The callback is run on a separate thread.

Timers take into account the amount of time it took to execute the callback. For example, if the callback took 250 ms to execute and returned 1000 (ms), the timer would only wait another 750 ms before its next iteration.

Timing may be inexact due to OS scheduling. Be sure to note the current time with SDL_GetTicks( ) or SDL_GetPerformanceCounter( ) in case your callback needs to adjust for variances.

Expected parameters include:

interval - the timer delay, in milliseconds, passed to callback

callback - the CODE reference to call when the specified interval elapses

param - a pointer that is passed to callback

Returns a timer ID or 0 if an error occurs; call SDL_GetError( ) for more information.

SDL_RemoveTimer( ... )

Remove a timer created with SDL_AddTimer( ... ).

        SDL_RemoveTimer( $id );

Expected parameters include:

id - the ID of the timer to remove

Returns SDL_TRUE if the timer is removed or SDL_FALSE if the timer wasn't found.

Defined Types

Time keeps on slipping...

SDL_TimerCallback

Function prototype for the timer callback function.

The callback function is passed the current timer interval and returns the next timer interval.

Parameters to expect include:

interval

param

If the returned value is the same as the one passed in, the periodic alarm continues, otherwise a new alarm is scheduled. If the callback returns 0, the periodic alarm is cancelled.

SDL_TimerID

Timer ID type.

LICENSE

Copyright (C) Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms found in the Artistic License 2. Other copyrights, terms, and conditions may apply to data transmitted through this module.

AUTHOR

Sanko Robinson <sanko@cpan.org>

cpanm SDL2::FFI

perl -MCPAN -e shell
install SDL2::FFI