NAME¶
SDL::Mixer::Effects - sound effect functions
CATEGORY¶
Mixer
METHODS¶
register¶
SDL::Mixer::Effects::register( $channel, $effect_callback, $done_callback, $arg );
Hook a processor function into a channel for post processing effects. You may
just be reading the data and displaying it, or you may be altering the stream
to add an echo. Most processors also have state data that they allocate as
they are in use, this would be stored in the $arg data space. When a processor
is finished being used, any function passed into $done_callback will be
called.
The effects are put into a linked list, and always appended to the end, meaning
they always work on previously registered effects output.
Returns: Zero on errors, such as a nonexisting channel.
Note: Passing MIX_CHANNEL_POST will register the $effect_callback as an
postmix effect.
Note: Do not use this on a threaded perl. This will crash.
Example:
use SDL;
use SDL::Mixer;
use SDL::Mixer::Channels;
use SDL::Mixer::Effects;
use SDL::Mixer::Samples;
my @last_stream = ();
my $echo_effect_func = sub
{
my $channel = shift;
my $samples = shift;
my $position = shift;
my @stream = @_;
my @stream2 = @stream;
my $offset = $samples / 2;
for(my $i = 0; $i < $samples; $i+=2)
{
if($i < $offset)
{
if(scalar(@last_stream) == $samples)
{
$stream2[$i] = $stream[$i] * 0.6 + $last_stream[$samples + $i - $offset] * 0.4; # left
$stream2[$i + 1] = $stream[$i + 1] * 0.6 + $last_stream[$samples + $i - $offset + 1] * 0.4; # right
}
}
else
{
$stream2[$i] = $stream[$i] * 0.6 + $stream[$i - $offset] * 0.4; # left
$stream2[$i + 1] = $stream[$i + 1] * 0.6 + $stream[$i - $offset + 1] * 0.4; # right
}
}
@last_stream = @stream;
return @stream2;
};
my $effect_done = sub
{
# you may do something here
};
SDL::Mixer::open_audio( 44100, SDL::Constants::AUDIO_S16, 2, 1024 );
my $playing_channel = SDL::Mixer::Channels::play_channel( -1, SDL::Mixer::Samples::load_WAV('test/data/sample.wav'), -1 );
SDL::Mixer::Effects::register($playing_channel, $echo_effect_func, $effect_done, 0);
SDL::delay(2000);
SDL::Mixer::Effects::unregister($playing_channel, $echo_effect_func);
SDL::Mixer::close_audio();
SDL::quit();
unregister¶
SDL::Mixer::Effects::unregister( $channel, $effect_callback );
Remove the registered effect function from the effect list for channel. If the
channel is active the registered effect will have its $done_callback function
called, if it was specified in SDL::Mixer::Effects::register.
Returns: Zero on errors, such as invalid channel, or effect function not
registered on channel.
Note: Do not use this on a threaded perl. This will crash.
unregister_all¶
SDL::Mixer::Effects::unregister_all( $channel );
This removes all effects registered to $channel. If the channel is active all
the registered effects will have their $done_callback functions called, if
they were specified in SDL::Mixer::Effects::register.
Returns: Zero on errors, such as channel not existing.
Note: Do not use this on a threaded perl. This will crash.
set_post_mix¶
SDL::Mixer::Effects::set_post_mix( $effect_callback, $arg );
Hook a processor function to the postmix stream for post processing effects. You
may just be reading the data and displaying it, or you may be altering the
stream to add an echo. This processor is never really finished, until you call
it without arguments. There can only be one postmix function used at a time
through this method. Use SDL::Mixer::Effects::register with MIX_CHANNEL_POST
to use multiple postmix processors. This postmix processor is run AFTER all
the registered postmixers set up by SDL::Mixer::Effects::register.
Note: Do not use this on a threaded perl. This will crash.
set_distance¶
SDL::Mixer::Effects::set_distance( $channel, $distance );
This effect simulates a simple attenuation of volume due to distance. The volume
never quite reaches silence, even at max distance (255).
NOTE: Using a distance of 0 will cause the effect to unregister itself from
channel. You cannot unregister it any other way, unless you use
SDL::Mixer::Effects::unregister_all on the channel.
Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect
failed.
set_panning¶
SDL::Mixer::Effects::set_panning( $channel, $left, $right );
This effect will only work on stereo audio. Meaning you called
SDL::Mixer::open_audio with 2 channels.
Note: Setting both left and right to 255 will unregister the effect from
channel. You cannot unregister it any other way, unless you use
SDL::Mixer::Effects::unregister_all on the channel.
Note: Using this function on a mono audio device will not register the
effect, nor will it return an error status.
Returns: Zero on errors, such as bad channel, or if
SDL::Mixer::Effects::register failed.
set_position¶
SDL::Mixer::Effects::set_position( $channel, $angle, $distance );
This effect emulates a simple 3D audio effect. It's not all that realistic, but
it can help improve some level of realism. By giving it the angle and distance
from the camera's point of view, the effect pans and attenuates volumes.
$angle is the direction in relation to forward from 0 to 360 degrees. Larger
angles will be reduced to this range using angles % 360.
- •
- 0 = directly in front.
- •
- 90 = directly to the right.
- •
- 180 = directly behind.
- •
- 270 = directly to the left.
So you can see it goes clockwise starting at directly in front.
$distance is 0(close/loud) to 255(far/quiet).
Note: Using angle and distance of 0, will cause the effect to unregister
itself from channel. You cannot unregister it any other way, unless you use
SDL::Mixer::Effects::unregister_all on the channel.
Returns: Zero on errors, such as an invalid channel, or if
SDL::Mixer::Effects::register failed.
set_reverse_stereo¶
SDL::Mixer::Effects::set_reverse_stereo( $channel, $flip );
If you pass 1 to $flip it simple reverse stereo, swaps left and right channel
sound.
Note: Using a flip of 0, will cause the effect to unregister itself from
channel. You cannot unregister it any other way, unless you use
SDL::Mixer::Effects::register on the channel.
AUTHORS¶
See "AUTHORS" in SDL.