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