X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pages%2FSDL-Mixer-Effects.html-inc;h=1444dc32e87ff975d97d42912632f9fd46e96f59;hb=c8ad4fe9f211e727310a1ce6d23ffb1d7822d71f;hp=59c48488639ba2afbbe74173670aae9ba57d6dbf;hpb=b5d537cc3daf6b56e3b7b33a40aec03c1549c921;p=sdlgit%2FSDL-Site.git diff --git a/pages/SDL-Mixer-Effects.html-inc b/pages/SDL-Mixer-Effects.html-inc index 59c4848..1444dc3 100644 --- a/pages/SDL-Mixer-Effects.html-inc +++ b/pages/SDL-Mixer-Effects.html-inc @@ -4,11 +4,15 @@
SDL::Mixer::Effects -- SDL_Mixer sound effect functions and bindings
+SDL::Mixer::Effects - sound effect functions
Mixer
-Note: >= 1.2.10
+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(); + ++ +
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.
+ +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.
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.
+ +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.
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.
+ +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.
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.
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.