pages/SDL-Mixer-Effects.html-inc

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