PageRenderTime 11ms CodeModel.GetById 8ms app.highlight 1ms RepoModel.GetById 1ms app.codeStats 0ms

/lib/pods/SDL/Mixer/Effects.pod

http://github.com/PerlGameDev/SDL
Unknown | 194 lines | 122 code | 72 blank | 0 comment | 0 complexity | 15b980ad4d9188d726696f55ba468025 MD5 | raw file
  1
  2=pod
  3
  4=head1 NAME
  5
  6SDL::Mixer::Effects - sound effect functions
  7
  8=head1 CATEGORY
  9
 10Mixer
 11
 12=head1 METHODS
 13
 14=head2 register
 15
 16 SDL::Mixer::Effects::register( $channel, $effect_callback, $done_callback, $arg );
 17
 18Hook 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 
 19the 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 C<$arg> data 
 20space. When a processor is finished being used, any function passed into C<$done_callback> will be called.
 21
 22The effects are put into a linked list, and always appended to the end, meaning they always work on previously registered effects output.
 23
 24Returns: Zero on errors, such as a nonexisting channel.
 25
 26B<Note>: Passing MIX_CHANNEL_POST will register the C<$effect_callback> as an postmix effect.
 27
 28B<Note>: Do not use this on a threaded perl. This will crash.
 29
 30Example:
 31
 32 use SDL;
 33 use SDL::Mixer;
 34 use SDL::Mixer::Channels;
 35 use SDL::Mixer::Effects;
 36 use SDL::Mixer::Samples;
 37 
 38 my @last_stream        = ();
 39 my $echo_effect_func   = sub
 40 {
 41     my $channel  = shift;
 42     my $samples  = shift;
 43     my $position = shift;
 44     my @stream   = @_;
 45 
 46     my @stream2 = @stream;
 47     my $offset  = $samples / 2;
 48     for(my $i = 0; $i < $samples; $i+=2)
 49     {
 50         if($i < $offset)
 51         {
 52             if(scalar(@last_stream) == $samples)
 53             {
 54                 $stream2[$i]     = $stream[$i]     * 0.6 + $last_stream[$samples + $i - $offset]     * 0.4; # left
 55                 $stream2[$i + 1] = $stream[$i + 1] * 0.6 + $last_stream[$samples + $i - $offset + 1] * 0.4; # right
 56             }
 57         }
 58         else
 59         {
 60             $stream2[$i]     = $stream[$i]     * 0.6 + $stream[$i - $offset]     * 0.4; # left
 61             $stream2[$i + 1] = $stream[$i + 1] * 0.6 + $stream[$i - $offset + 1] * 0.4; # right
 62         }
 63     }
 64 
 65     @last_stream = @stream;
 66     return @stream2;
 67 };
 68 
 69 my $effect_done = sub
 70 {
 71     # you may do something here
 72 };
 73 
 74 SDL::Mixer::open_audio( 44100, SDL::Constants::AUDIO_S16, 2, 1024 );
 75 
 76 my $playing_channel = SDL::Mixer::Channels::play_channel( -1, SDL::Mixer::Samples::load_WAV('test/data/sample.wav'), -1 );
 77 SDL::Mixer::Effects::register($playing_channel, $echo_effect_func, $effect_done, 0);
 78 SDL::delay(2000);
 79 SDL::Mixer::Effects::unregister($playing_channel, $echo_effect_func);
 80 
 81 SDL::Mixer::close_audio();
 82 SDL::quit();
 83
 84=head2 unregister
 85
 86 SDL::Mixer::Effects::unregister( $channel, $effect_callback );
 87
 88Remove the registered effect function from the effect list for channel.
 89If the channel is active the registered effect will have its C<$done_callback> function called, if it was specified in 
 90L<SDL::Mixer::Effects::register|SDL::Mixer::Effects/"register">.
 91
 92Returns: Zero on errors, such as invalid channel, or effect function not registered on channel. 
 93
 94B<Note>: Do not use this on a threaded perl. This will crash.
 95
 96=head2 unregister_all
 97
 98 SDL::Mixer::Effects::unregister_all( $channel );
 99
100This removes all effects registered to C<$channel>. If the channel is active all the registered effects will have their C<$done_callback> 
101functions called, if they were specified in L<SDL::Mixer::Effects::register|SDL::Mixer::Effects/"register">.
102
103Returns: Zero on errors, such as channel not existing. 
104
105B<Note>: Do not use this on a threaded perl. This will crash.
106
107=head2 set_post_mix
108
109 SDL::Mixer::Effects::set_post_mix( $effect_callback, $arg );
110
111Hook 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 
112altering the stream to add an echo. This processor is never really finished, until you call it without arguments.
113There can only be one postmix function used at a time through this method. Use L<SDL::Mixer::Effects::register|SDL::Mixer::Effects/"register"> 
114with MIX_CHANNEL_POST to use multiple postmix processors.
115This postmix processor is run AFTER all the registered postmixers set up by L<SDL::Mixer::Effects::register|SDL::Mixer::Effects/"register">. 
116
117B<Note>: Do not use this on a threaded perl. This will crash.
118
119=head2 set_distance
120
121 SDL::Mixer::Effects::set_distance( $channel, $distance );
122
123This effect simulates a simple attenuation of volume due to distance. The volume never quite reaches silence, even at max distance (C<255>).
124
125NOTE: Using a distance of C<0> will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use 
126L<SDL::Mixer::Effects::unregister_all|SDL::Mixer::Effects/"unregister_all"> on the channel.
127
128Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed. 
129
130=head2 set_panning
131
132 SDL::Mixer::Effects::set_panning( $channel, $left, $right );
133
134This effect will only work on stereo audio. Meaning you called L<SDL::Mixer::open_audio|SDL::Mixer/"open_audio"> with 2 channels. 
135
136B<Note>: Setting both left and right to 255 will unregister the effect from channel. You cannot unregister it any other way, unless you use 
137L<SDL::Mixer::Effects::unregister_all|SDL::Mixer::Effects/"unregister_all"> on the channel.
138
139B<Note>: Using this function on a mono audio device will not register the effect, nor will it return an error status.
140
141Returns: Zero on errors, such as bad channel, or if L<SDL::Mixer::Effects::register|SDL::Mixer::Effects/"register"> failed. 
142
143=head2 set_position
144
145 SDL::Mixer::Effects::set_position( $channel, $angle, $distance );
146
147This 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 
148angle and distance from the camera's point of view, the effect pans and attenuates volumes.
149
150C<$angle> is the direction in relation to forward from 0 to 360 degrees. Larger angles will be reduced to this range using angles % 360.
151
152=over 4
153
154=item *
155
1560 = directly in front.
157
158=item *
159
16090 = directly to the right.
161
162=item *
163
164180 = directly behind.
165
166=item *
167
168270 = directly to the left.
169
170=back
171
172So you can see it goes clockwise starting at directly in front.
173
174C<$distance> is C<0>(close/loud) to C<255>(far/quiet).
175
176B<Note>: Using angle and distance of C<0>, will cause the effect to unregister itself from channel. You cannot unregister it any other way, 
177unless you use L<SDL::Mixer::Effects::unregister_all|SDL::Mixer::Effects/"unregister_all"> on the channel.
178
179Returns: Zero on errors, such as an invalid channel, or if L<SDL::Mixer::Effects::register|SDL::Mixer::Effects/"register"> failed. 
180
181=head2 set_reverse_stereo
182
183 SDL::Mixer::Effects::set_reverse_stereo( $channel, $flip );
184
185If you pass C<1> to C<$flip> it simple reverse stereo, swaps left and right channel sound.
186
187B<Note>: Using a flip of C<0>, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use 
188L<SDL::Mixer::Effects::register|SDL::Mixer::Effects/"register"> on the channel. 
189
190=head1 AUTHORS
191
192See L<SDL/AUTHORS>.
193
194=cut