pages/SDL-Mixer.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="#CONSTANTS">CONSTANTS</a></li>
   8 <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
   9 <li><a href="#METHODS">METHODS</a>
  10 <ul><li><a href="#init">init</a></li>
  11 <li><a href="#quit">quit</a></li>
  12 <li><a href="#linked_version">linked_version</a></li>
  13 <li><a href="#open_audio">open_audio</a></li>
  14 <li><a href="#close_audio">close_audio</a></li>
  15 <li><a href="#query_spec">query_spec</a></li>
  16 </ul>
  17 </li>
  18 <li><a href="#SEE_ALSO">SEE ALSO</a></li>
  19 <li><a href="#AUTHORS">AUTHORS</a>
  20 </li>
  21 </ul><hr />
  22 <!-- INDEX END -->
  23
  24 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
  25 <div id="NAME_CONTENT">
  26 <p>SDL::Mixer - Sound and music functions</p>
  27
  28 </div>
  29 <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
  30 <div id="CATEGORY_CONTENT">
  31 <p>Mixer</p>
  32
  33 </div>
  34 <h1 id="CONSTANTS">CONSTANTS</h1><p><a href="#TOP" class="toplink">Top</a></p>
  35 <div id="CONSTANTS_CONTENT">
  36 <p>The constants are exported by default. You can avoid this by doing:</p>
  37 <pre> use SDL::Mixer ();
  38
  39 </pre>
  40 <p>and access them directly:</p>
  41 <pre> SDL::Mixer::MIX_DEFAULT_FREQUENCY;
  42
  43 </pre>
  44 <p>or by choosing the export tags below:</p>
  45 <p>Export tag: ':init'</p>
  46 <pre> MIX_INIT_FLAC
  47  MIX_INIT_MOD
  48  MIX_INIT_MP3
  49  MIX_INIT_OGG
  50
  51 </pre>
  52 <p>Export tag: ':defaults'</p>
  53 <pre> MIX_CHANNELS
  54  MIX_DEFAULT_FORMAT
  55  MIX_DEFAULT_FREQUENCY
  56  MIX_DEFAULT_CHANNELS
  57  MIX_MAX_VOLUME
  58  MIX_CHANNEL_POST
  59
  60 </pre>
  61 <p>Export tag: ':fading'</p>
  62 <pre> MIX_NO_FADING
  63  MIX_FADING_OUT
  64  MIX_FADING_IN
  65
  66 </pre>
  67 <p>Export tag: ':type'</p>
  68 <pre> MUS_NONE
  69  MUS_CMD
  70  MUS_WAV
  71  MUS_MOD
  72  MUS_MID
  73  MUS_OGG
  74  MUS_MP3
  75  MUS_MP3_MAD
  76  MUS_MP3_FLAC
  77
  78 </pre>
  79 <p>Export tag: ':format'</p>
  80 <pre> AUDIO_U8
  81  AUDIO_S8
  82  AUDIO_U16LSB
  83  AUDIO_S16LSB
  84  AUDIO_U16MSB
  85  AUDIO_S16MSB
  86  AUDIO_U16
  87  AUDIO_S16
  88  AUDIO_U16SYS
  89  AUDIO_S16SYS
  90
  91 </pre>
  92 <p>Export tag: ':status'</p>
  93 <pre> SDL_AUDIO_STOPPED
  94  SDL_AUDIO_PLAYING
  95  SDL_AUDIO_PAUSED
  96
  97 </pre>
  98
  99 </div>
 100 <h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
 101 <div id="DESCRIPTION_CONTENT">
 102 <p>SDL::Mixer allows you to enable sound, alter music volume settings, and lets you play, pause and resume, as well as fading the sound and music
 103 in and out.</p>
 104
 105 </div>
 106 <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
 107 <div id="METHODS_CONTENT">
 108
 109 </div>
 110 <h2 id="init">init</h2>
 111 <div id="init_CONTENT">
 112 <pre> my $init_flags = SDL::Mixer::init( $flags );
 113
 114 </pre>
 115 <p>Loads dynamic libraries and prepares them for use. Flags should be one or more flags from init flags OR'd together.
 116 It returns the flags successfully initialized, or 0 on failure.</p>
 117 <p>Example:</p>
 118 <pre> use SDL::Mixer;
 119
 120  my $init_flags = SDL::Mixer::init( MIX_INIT_MP3 | MIX_INIT_MOD | MIX_INIT_FLAC | MIX_INIT_OGG );
 121
 122  print(&quot;We have MP3 support!\n&quot;)  if $init_flags &amp; MIX_INIT_MP3;
 123  print(&quot;We have MOD support!\n&quot;)  if $init_flags &amp; MIX_INIT_MOD;
 124  print(&quot;We have FLAC support!\n&quot;) if $init_flags &amp; MIX_INIT_FLAC;
 125  print(&quot;We have OGG support!\n&quot;)  if $init_flags &amp; MIX_INIT_OGG;
 126
 127 </pre>
 128 <p>Flags:</p>
 129 <ul>
 130                 <li>MIX_INIT_MP3        </li>
 131                 <li>MIX_INIT_MOD        </li>
 132                 <li>MIX_INIT_FLAC       </li>
 133                 <li>MIX_INIT_OGG</li>
 134 </ul>
 135
 136 <p><strong>Note</strong>: Only available for SDL_mixer &gt;= 1.2.10</p>
 137
 138 </div>
 139 <h2 id="quit">quit</h2>
 140 <div id="quit_CONTENT">
 141 <pre> SDL::Mixer::quit();
 142
 143 </pre>
 144 <p>This function unloads the liraries previously loaded with <a href="#init">init()</a>.</p>
 145 <p><strong>Note</strong>: Only available for SDL_mixer &gt;= 1.2.10</p>
 146
 147 </div>
 148 <h2 id="linked_version">linked_version</h2>
 149 <div id="linked_version_CONTENT">
 150 <pre> $version = SDL::Mixer::linked_version();
 151
 152 </pre>
 153 <p><code>linked_version</code> gives you the major-, minor-, and patchlevel for SDL_mixer. This way you can check if e.g. <a href="#init">init()</a> and <a href="#quit">quit()</a>
 154 are available.</p>
 155 <p>Example:</p>
 156 <pre> use SDL::Mixer;
 157  use SDL::Version;
 158
 159  my $version = SDL::Mixer::linked_version();
 160
 161  printf(&quot;%d.%d.%d\n&quot;, $version-&gt;major, $version-&gt;minor, $version-&gt;patch); # prints &quot;1.2.8&quot; for me
 162
 163 </pre>
 164
 165 </div>
 166 <h2 id="open_audio">open_audio</h2>
 167 <div id="open_audio_CONTENT">
 168 <pre> my $audio_opened = SDL::Mixer::open_audio( $frequency, $format, $channels, $chunksize );
 169
 170 </pre>
 171 <p><code>open_audio</code> will initialize SDL_mixer if it is not yet initialized, see note. SDL_mixer may not be able to provide the exact specifications
 172 your provided, however it will automatically translate between the expected format and the real one. You can retrieve the real format using
 173 <a href="http://search.cpan.org/perldoc?query_spec">query_spec</a>. </p>
 174 <p>Returns 0 on success, -1 on error.</p>
 175 <p><strong>Note</strong>: You must not use <code>AUDIO_S16</code>, <code>AUDIO_U16</code>, <code>AUDIO_S16LSB</code>, or <code>AUDIO_U16LSB.</code> They are not portable, and SDL will not return an
 176 error code when they fail. The result will be a horrible staticy noise. You can usually use <code>AUDIO_S16SYS</code>, though not always. Future versions
 177 of SDL should take this parameter only as a hint, then read back the value that the OS (for example, OSS or ALSA) has chosen to use in case the
 178 desired audio type is not supported. </p>
 179 <p><strong>Note</strong>: When already initialized, this function will not re-initialize SDL_mixer, nor fail. It will merely increment the number of times
 180 <a href="/SDL-Mixer.html#close_audio">SDL::Mixer::close_audio</a> must be called to actually get it to uninitialize. This serves as a very simplistic method for multiple application
 181 components to use SDL_mixer without necessitating a great deal of inter-component awareness. Be warned however that in such a situation, the
 182 latest components to initialize SDL_mixer will probably not get the SDL_mixer settings they're expecting. </p>
 183 <p>Example:</p>
 184 <pre> use SDL;
 185  use SDL::Mixer;
 186
 187  printf(&quot;Error initializing SDL_mixer: %s\n&quot;, SDL::get_error()) unless SDL::Mixer::open_audio(44100, AUDIO_S16, 2, 1024) == 0;
 188
 189 </pre>
 190
 191 </div>
 192 <h2 id="close_audio">close_audio</h2>
 193 <div id="close_audio_CONTENT">
 194 <pre> SDL::Mixer::close_audio();
 195
 196 </pre>
 197 <p>Close the mixer and halting all playing audio. This function does not return anything.</p>
 198
 199 </div>
 200 <h2 id="query_spec">query_spec</h2>
 201 <div id="query_spec_CONTENT">
 202 <pre> my @query_spec = @{ SDL::Mixer::query_spec() };
 203
 204 </pre>
 205 <p>Find out what the actual audio device parameters are.
 206 This function returns 1 as first array element (status) if the audio has been opened, 0 otherwise.</p>
 207 <p>Example:</p>
 208 <pre> use SDL::Mixer;
 209
 210  my ($status, $freq, $format, $channels) = @{ SDL::Mixer::query_spec() };
 211
 212  printf(&quot;%s, %s, %s, %s\n&quot;, $status, $freq, $format, $channels);
 213
 214 </pre>
 215
 216 </div>
 217 <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
 218 <div id="SEE_ALSO_CONTENT">
 219 <p><a href="http://search.cpan.org/perldoc?perl">perl</a>, <a href="SDL-Mixer-Channels.html">SDL::Mixer::Channels</a>, <a href="SDL-Mixer-Effects.html">SDL::Mixer::Effects</a>, <a href="SDL-Mixer-Groups.html">SDL::Mixer::Groups</a>, <a href="SDL-Mixer-Music.html">SDL::Mixer::Music</a>.</p>
 220
 221 </div>
 222 <h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p>
 223 <div id="AUTHORS_CONTENT">
 224 <p>See <b>AUTHORS</b> in <cite>SDL</cite>.</p>
 225
 226 </div>
 227 </div>