X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pages%2FSDL-Mixer.html-inc;h=71f387b6b7e2b36b3c3ed94ddd693272b2eb04e3;hb=3549ee6a3a96e3e1834ff3373567ab631acd42cc;hp=9dc1690843ce3bdb8beaba7641d45a2b809dc806;hpb=46beffd8f76fe150d946bf61c780e61de2affbdf;p=sdlgit%2FSDL-Site.git

diff --git a/pages/SDL-Mixer.html-inc b/pages/SDL-Mixer.html-inc
index 9dc1690..71f387b 100644
--- a/pages/SDL-Mixer.html-inc
+++ b/pages/SDL-Mixer.html-inc
@@ -4,46 +4,17 @@
 
 <ul><li><a href="#NAME">NAME</a></li>
 <li><a href="#CATEGORY">CATEGORY</a></li>
-<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
+<li><a href="#CONSTANTS">CONSTANTS</a></li>
 <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
 <li><a href="#METHODS">METHODS</a>
-<ul><li><a href="#new">new()</a></li>
-<li><a href="#query_spec">query_spec()</a></li>
-<li><a href="#reserve_channels">reserve_channels</a></li>
-<li><a href="#allocate_channels">allocate_channels()</a></li>
-<li><a href="#group_channel_channel_group">group_channel(channel,group)</a></li>
-<li><a href="#group_channels_from_to_group">group_channels(from,to,group)</a></li>
-<li><a href="#group_available_group">group_available(group)</a></li>
-<li><a href="#group_count_group">group_count(group)</a></li>
-<li><a href="#group_oldest">group_oldest()</a></li>
-<li><a href="#group_newer">group_newer()</a></li>
-<li><a href="#play_channel">play_channel()</a></li>
-<li><a href="#play_music">play_music()</a></li>
-<li><a href="#fade_in_channel_channel_chunk_loops_">fade_in_channel(channel,chunk,loops,ms,ticks)</a></li>
-<li><a href="#fade_in_music_music_loops_ms">fade_in_music(music,loops,ms)</a></li>
-<li><a href="#channel_volume_channel_volume">channel_volume(channel,volume)</a></li>
-<li><a href="#mucis_volume_volume">mucis_volume(volume)</a></li>
-<li><a href="#halt_channel_channel">halt_channel(channel)</a></li>
-<li><a href="#halt_group_group">halt_group(group)</a></li>
-<li><a href="#halt_music">halt_music()</a></li>
-<li><a href="#channel_expire_channel_ticks">channel_expire(channel,ticks)</a></li>
-<li><a href="#fade_out_channel_channel_ms">fade_out_channel(channel,ms)</a></li>
-<li><a href="#fade_out_group_group_ms">fade_out_group(group,ms)</a></li>
-<li><a href="#fade_out_music_ms">fade_out_music(ms)</a></li>
-<li><a href="#fading_music">fading_music()</a></li>
-<li><a href="#fading_channel">fading_channel()</a></li>
-<li><a href="#pause_channel">pause( channel )</a></li>
-<li><a href="#resume_channel">resume(channel)</a></li>
-<li><a href="#paused">paused()</a></li>
-<li><a href="#pause_music">pause_music()</a></li>
-<li><a href="#resume_music">resume_music()</a></li>
-<li><a href="#rewind_music">rewind_music()</a></li>
-<li><a href="#music_paused">music_paused()</a></li>
-<li><a href="#playing">playing()</a></li>
-<li><a href="#playing_music">playing_music ()</a></li>
+<ul><li><a href="#init">init</a></li>
+<li><a href="#quit">quit</a></li>
+<li><a href="#linked_version">linked_version</a></li>
+<li><a href="#open_audio">open_audio</a></li>
+<li><a href="#close_audio">close_audio</a></li>
+<li><a href="#query_spec">query_spec</a></li>
 </ul>
 </li>
-<li><a href="#set_panning_channel_left_right">set_panning($channel, $left, $right)</a></li>
 <li><a href="#AUTHORS">AUTHORS </a></li>
 <li><a href="#SEE_ALSO">SEE ALSO</a>
 </li>
@@ -52,7 +23,7 @@
 
 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
 <div id="NAME_CONTENT">
-<p>SDL::Mixer - a SDL perl extension</p>
+<p>SDL::Mixer - Sound and music functions</p>
 
 </div>
 <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
@@ -60,241 +31,178 @@
 <p>Mixer</p>
 
 </div>
-<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
-<div id="SYNOPSIS_CONTENT">
-<pre>  $mixer = new SDL::Mixer 	-frequency =&gt; MIX_DEFAULT_FREQUENCY,
-				-format =&gt; MIX_DEFAULT_FORMAT,
-				-channels =&gt; MIX_DEFAULT_CHANNELS,
-				-size =&gt; 4096;
+<h1 id="CONSTANTS">CONSTANTS</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="CONSTANTS_CONTENT">
+<p>The constants are exported by default. You can avoid this by doing:</p>
+<pre> use SDL::Mixer ();
 
 </pre>
-
-</div>
-<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
-<div id="DESCRIPTION_CONTENT">
-<p>SDL::Mixer allows you access to the SDL mixer library, enablig sound and
-music volume setting, playing, pausing and resuming, as well as fading
-the sound and music in and out.</p>
-
-</div>
-<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
-<div id="METHODS_CONTENT">
-
-</div>
-<h2 id="new">new()</h2>
-<div id="new_CONTENT">
-<pre>	$mixer = SDL::Mixer-&gt;new(	-frequency =&gt; MIX_DEFAULT_FREQUENCY,
-					-format    =&gt; MIX_DEFAULT_FORMAT,
-					-channels  =&gt; MIX_DEFAULT_CHANNELS,
-					-size      =&gt; 4096);
+<p>and access them directly:</p>
+<pre> SDL::Mixer::MIX_DEFAULT_FREQUENCY;
 
 </pre>
-<p>Creates a new SDL::Mixer object. <code>$size</code> is the buffer size in bytes.</p>
-
-</div>
-<h2 id="query_spec">query_spec()</h2>
-<div id="query_spec_CONTENT">
-<pre>	my $specs = SDL::Mixer::query_spec();
+<p>or by choosing the export tags below:</p>
+<p>Export tag: ':init'</p>
+<pre> MIX_INIT_FLAC
+ MIX_INIT_MOD
+ MIX_INIT_MP3
+ MIX_INIT_OGG
 
 </pre>
-<p>Returns a hash reference, containing the following keys and their respective
-values:</p>
-<pre>	-status
-	-frequency
-	-channels
-	-format
+<p>Export tag: ':default'</p>
+<pre> MIX_CHANNELS
+ MIX_DEFAULT_FORMAT
+ MIX_DEFAULT_FREQUENCY
+ MIX_DEFAULT_CHANNELS
+ MIX_MAX_VOLUME
+ MIX_CHANNEL_POST
 
 </pre>
-
-</div>
-<h2 id="reserve_channels">reserve_channels</h2>
-<div id="reserve_channels_CONTENT">
-<pre>	$mixer-&gt;reserve_channels(4);
+<p>Export tag: ':fading'</p>
+<pre> MIX_NO_FADING
+ MIX_FADING_OUT
+ MIX_FADING_IN
 
 </pre>
-<p>Reserve so many channels.</p>
-
-</div>
-<h2 id="allocate_channels">allocate_channels()</h2>
-<div id="allocate_channels_CONTENT">
-<pre>	$mixer-&gt;reserve_channels(2);
+<p>Export tag: ':type'</p>
+<pre> MUS_NONE
+ MUS_CMD
+ MUS_WAV
+ MUS_MOD
+ MUS_MID
+ MUS_OGG
+ MUS_MP3
+ MUS_MP3_MAD
+ MUS_MP3_FLAC
 
 </pre>
-<p>Allocate so many channels.</p>
-
-</div>
-<h2 id="group_channel_channel_group">group_channel(channel,group)</h2>
-<div id="group_channel_channel_group_CONTENT">
-<p>Group the channel number <code>$channel</code> into group <code>$group</code>.</p>
-
-</div>
-<h2 id="group_channels_from_to_group">group_channels(from,to,group)</h2>
-<div id="group_channels_from_to_group_CONTENT">
-<p>Groups a range of channels</p>
-
-</div>
-<h2 id="group_available_group">group_available(group)</h2>
-<div id="group_available_group_CONTENT">
-<p>Return true when the group is available.</p>
-
-</div>
-<h2 id="group_count_group">group_count(group)</h2>
-<div id="group_count_group_CONTENT">
-<p>Returns the number of channels in the group</p>
-
-</div>
-<h2 id="group_oldest">group_oldest()</h2>
-<div id="group_oldest_CONTENT">
-
-
-
-
-
-</div>
-<h2 id="group_newer">group_newer()</h2>
-<div id="group_newer_CONTENT">
-
-
-
-
 
 </div>
-<h2 id="play_channel">play_channel()</h2>
-<div id="play_channel_CONTENT">
-
-
-
-
+<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="DESCRIPTION_CONTENT">
+<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 
+in and out.</p>
 
 </div>
-<h2 id="play_music">play_music()</h2>
-<div id="play_music_CONTENT">
-<p>Play <code>$music</code> <code>$loop</code> times.</p>
+<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="METHODS_CONTENT">
 
 </div>
-<h2 id="fade_in_channel_channel_chunk_loops_">fade_in_channel(channel,chunk,loops,ms,ticks)</h2>
-<div id="fade_in_channel_channel_chunk_loops_-2">
-<p>Fades a channel in</p>
+<h2 id="init">init</h2>
+<div id="init_CONTENT">
+<pre> my $init_flags = SDL::Mixer::init( $flags );
 
-</div>
-<h2 id="fade_in_music_music_loops_ms">fade_in_music(music,loops,ms)</h2>
-<div id="fade_in_music_music_loops_ms_CONTENT">
-<p>Fades the music in over a number of ms, looping as it does</p>
+</pre>
+<p>Loads dynamic libraries and prepares them for use. Flags should be one or more flags from init flags OR'd together.
+It returns the flags successfully initialized, or 0 on failure.</p>
+<p>Example:</p>
+<pre> use SDL::Mixer;
 
-</div>
-<h2 id="channel_volume_channel_volume">channel_volume(channel,volume)</h2>
-<div id="channel_volume_channel_volume_CONTEN">
-<p>Sets the volume for a single channel</p>
+ my $init_flags = SDL::Mixer::init( MIX_INIT_MP3 | MIX_INIT_MOD | MIX_INIT_FLAC | MIX_INIT_OGG );
 
-</div>
-<h2 id="mucis_volume_volume">mucis_volume(volume)</h2>
-<div id="mucis_volume_volume_CONTENT">
-<p>Set the volume for the music.</p>
+ print(&quot;We have MP3 support!\n&quot;)  if $init_flags &amp; MIX_INIT_MP3;
+ print(&quot;We have MOD support!\n&quot;)  if $init_flags &amp; MIX_INIT_MOD;
+ print(&quot;We have FLAC support!\n&quot;) if $init_flags &amp; MIX_INIT_FLAC;
+ print(&quot;We have OGG support!\n&quot;)  if $init_flags &amp; MIX_INIT_OGG;
 
-</div>
-<h2 id="halt_channel_channel">halt_channel(channel)</h2>
-<div id="halt_channel_channel_CONTENT">
-<p>Stops a specific channel</p>
+</pre>
+<p>Flags:</p>
+<ul>
+		<li>MIX_INIT_MP3	</li>
+		<li>MIX_INIT_MOD	</li>
+		<li>MIX_INIT_FLAC	</li>
+		<li>MIX_INIT_OGG</li>
+</ul>
 
-</div>
-<h2 id="halt_group_group">halt_group(group)</h2>
-<div id="halt_group_group_CONTENT">
-<p>Stops a group of channels</p>
+<p><strong>Note</strong>: Only available for SDL_mixer &gt;= 1.2.10</p>
 
 </div>
-<h2 id="halt_music">halt_music()</h2>
-<div id="halt_music_CONTENT">
-<p>Stops the music</p>
+<h2 id="quit">quit</h2>
+<div id="quit_CONTENT">
+<pre> SDL::Mixer::quit();
 
-</div>
-<h2 id="channel_expire_channel_ticks">channel_expire(channel,ticks)</h2>
-<div id="channel_expire_channel_ticks_CONTENT">
-<p>Ignores the channel after <code>ticks</code> has expired</p>
+</pre>
+<p>This function unloads the liraries previously loaded with <a href="#init">init()</a>.</p>
+<p><strong>Note</strong>: Only available for SDL_mixer &gt;= 1.2.10</p>
 
 </div>
-<h2 id="fade_out_channel_channel_ms">fade_out_channel(channel,ms)</h2>
-<div id="fade_out_channel_channel_ms_CONTENT">
-<p>Fade the channel number <code>$channel</code> in <code>$ms</code> ms out.</p>
+<h2 id="linked_version">linked_version</h2>
+<div id="linked_version_CONTENT">
+<pre> $version = SDL::Mixer::linked_version();
 
-</div>
-<h2 id="fade_out_group_group_ms">fade_out_group(group,ms)</h2>
-<div id="fade_out_group_group_ms_CONTENT">
-<p>Fade the channel group <code>$group</code> in <code>$ms</code> ms out.</p>
+</pre>
+<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> 
+are available.</p>
+<p>Example:</p>
+<pre> use SDL::Mixer;
+ use SDL::Version;
 
-</div>
-<h2 id="fade_out_music_ms">fade_out_music(ms)</h2>
-<div id="fade_out_music_ms_CONTENT">
-<p>Fade the music in <code>$ms</code> ms out.</p>
+ my $version = SDL::Mixer::linked_version();
 
-</div>
-<h2 id="fading_music">fading_music()</h2>
-<div id="fading_music_CONTENT">
-<p>Return true when the music is currently fading in or out.</p>
+ printf(&quot;%d.%d.%d\n&quot;, $version-&gt;major, $version-&gt;minor, $version-&gt;patch); # prints &quot;1.2.8&quot; for me
 
-</div>
-<h2 id="fading_channel">fading_channel()</h2>
-<div id="fading_channel_CONTENT">
-<p>Return true when the channel number <code>$channel</code> is currently fading in or out.</p>
+</pre>
 
 </div>
-<h2 id="pause_channel">pause( channel )</h2>
-<div id="pause_channel_CONTENT">
-<p>Pause the channel <code>$channel</code>.</p>
+<h2 id="open_audio">open_audio</h2>
+<div id="open_audio_CONTENT">
+<pre> my $audio_opened = SDL::Mixer::open_audio( $frequency, $format, $channels, $chunksize );
 
-</div>
-<h2 id="resume_channel">resume(channel)</h2>
-<div id="resume_channel_CONTENT">
-<p>Resume the channel <code>$channel</code>.</p>
+</pre>
+<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 
+your provided, however it will automatically translate between the expected format and the real one. You can retrieve the real format using 
+<a href="http://search.cpan.org/perldoc?query_spec">query_spec</a>. </p>
+<p>Returns 0 on success, -1 on error.</p>
+<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 
+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 
+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 
+desired audio type is not supported. </p>
+<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 
+<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 
+components to use SDL_mixer without necessitating a great deal of inter-component awareness. Be warned however that in such a situation, the 
+latest components to initialize SDL_mixer will probably not get the SDL_mixer settings they're expecting. </p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Mixer;
+
+ printf(&quot;Error initializing SDL_mixer: %s\n&quot;, SDL::get_error()) unless SDL::Mixer::open_audio(44100, AUDIO_S16, 2, 1024) == 0;
 
-</div>
-<h2 id="paused">paused()</h2>
-<div id="paused_CONTENT">
-<p>Return true when the channel is currently paused.</p>
+</pre>
 
 </div>
-<h2 id="pause_music">pause_music()</h2>
-<div id="pause_music_CONTENT">
-<p>Pause the music play.</p>
+<h2 id="close_audio">close_audio</h2>
+<div id="close_audio_CONTENT">
+<pre> SDL::Mixer::close_audio();
 
-</div>
-<h2 id="resume_music">resume_music()</h2>
-<div id="resume_music_CONTENT">
-<p>Resume the music play.</p>
+</pre>
+<p>Close the mixer and halting all playing audio. This function does not return anything.</p>
 
 </div>
-<h2 id="rewind_music">rewind_music()</h2>
-<div id="rewind_music_CONTENT">
-<p>Resets the music file to the beginning</p>
+<h2 id="query_spec">query_spec</h2>
+<div id="query_spec_CONTENT">
+<pre> my @query_spec = @{ SDL::Mixer::query_spec() };
 
-</div>
-<h2 id="music_paused">music_paused()</h2>
-<div id="music_paused_CONTENT">
-<p>Return true when the music is currently paused.</p>
+</pre>
+<p>Find out what the actual audio device parameters are.
+This function returns 1 as first array element (status) if the audio has been opened, 0 otherwise.</p>
+<p>Example:</p>
+<pre> use SDL::Mixer;
 
-</div>
-<h2 id="playing">playing()</h2>
-<div id="playing_CONTENT">
-<p>Return true when the channel is currently playing.</p>
+ my ($status, $freq, $format, $channels) = @{ SDL::Mixer::query_spec() };
 
-</div>
-<h2 id="playing_music">playing_music ()</h2>
-<div id="playing_music_CONTENT">
-<p>Return true when the music is currently playing.</p>
+ printf(&quot;%s, %s, %s, %s\n&quot;, $status, $freq, $format, $channels);
 
-</div>
-<h1 id="set_panning_channel_left_right">set_panning($channel, $left, $right)</h1><p><a href="#TOP" class="toplink">Top</a></p>
-<div id="set_panning_channel_left_right_CONTE">
-<p>Sets the volume for the left or right channels. To do true panning:</p>
+</pre>
 
 </div>
 <h1 id="AUTHORS">AUTHORS </h1><p><a href="#TOP" class="toplink">Top</a></p>
 <div id="AUTHORS_CONTENT">
-<p>David J. Goehrig, basic doc added by Tels &lt;http://bloodgate.com&gt;.</p>
+<p>Tobias Leich [FROGGS]</p>
 
 </div>
 <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
 <div id="SEE_ALSO_CONTENT">
-<p><a href="http://search.cpan.org/perldoc?perl">perl</a>, <a href="/SDL-Music.html">SDL::Music</a> and <a href="/SDL-Sound.html">SDL::Sound</a>.</p>
+<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>
 
 </div>
 </div>
\ No newline at end of file