Provided by: libsdl-perl_2.548-4_amd64 bug

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.