SDL::Mixer::Effects(3pm)

1SDL::Mixer::Effects(3pmU)ser Contributed Perl DocumentatiSoDnL::Mixer::Effects(3pm)
2
3
4

NAME

6       SDL::Mixer::Effects - sound effect functions
7

METHODS

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

AUTHORS

195       See "AUTHORS" in SDL.
196
197
198
199perl v5.38.0                      2023-07-21          SDL::Mixer::Effects(3pm)

NAME

CATEGORY

METHODS

AUTHORS