[sdlgit/SDL-Site.git] / pages / SDL-Mixer.html-inc

<div class="pod">
<!-- INDEX START -->
<h3 id="TOP">Index</h3>

<ul><li><a href="#NAME">NAME</a></li>
<li><a href="#CATEGORY">CATEGORY</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#METHODS">METHODS</a>
<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="#AUTHORS">AUTHORS </a></li>
<li><a href="#SEE_ALSO">SEE ALSO</a>
</li>
</ul><hr />
<!-- INDEX END -->

<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="NAME_CONTENT">
<p>SDL::Mixer - Sound and music functions</p>

</div>
<h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="CATEGORY_CONTENT">
<p>Mixer</p>

</div>
<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>
<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="METHODS_CONTENT">

</div>
<h2 id="init">init</h2>
<div id="init_CONTENT">
<pre> my $init_flags = SDL::Mixer::init( $flags );

</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;

 my $init_flags = SDL::Mixer::init( MIX_INIT_MP3 | MIX_INIT_MOD | MIX_INIT_FLAC | MIX_INIT_OGG );

 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;

</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>

<p><strong>Note</strong>: Only available for SDL_mixer &gt;= 1.2.10</p>

</div>
<h2 id="quit">quit</h2>
<div id="quit_CONTENT">
<pre> SDL::Mixer::quit();

</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="linked_version">linked_version</h2>
<div id="linked_version_CONTENT">
<pre> $version = SDL::Mixer::linked_version();

</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;

 my $version = SDL::Mixer::linked_version();

 printf(&quot;%d.%d.%d\n&quot;, $version-&gt;major, $version-&gt;minor, $version-&gt;patch); # prints &quot;1.2.8&quot; for me

</pre>

</div>
<h2 id="open_audio">open_audio</h2>
<div id="open_audio_CONTENT">
<pre> my $audio_opened = SDL::Mixer::open_audio( $frequency, $format, $channels, $chunksize );

</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;

</pre>

</div>
<h2 id="close_audio">close_audio</h2>
<div id="close_audio_CONTENT">
<pre> SDL::Mixer::close_audio();

</pre>
<p>Close the mixer and halting all playing audio. This function does not return anything.</p>

</div>
<h2 id="query_spec">query_spec</h2>
<div id="query_spec_CONTENT">
<pre> my @query_spec = @{ SDL::Mixer::query_spec() };

</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;

 my ($status, $freq, $format, $channels) = @{ SDL::Mixer::query_spec() };

 printf(&quot;%s, %s, %s, %s\n&quot;, $status, $freq, $format, $channels);

</pre>

</div>
<h1 id="AUTHORS">AUTHORS </h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="AUTHORS_CONTENT">
<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-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>
Commit	Line	Data
162a0989	1	<div class="pod">
	2	<!-- INDEX START -->
	3	<h3 id="TOP">Index</h3>
	4
	5	<ul><li><a href="#NAME">NAME</a></li>
bfdd9c2e	6	<li><a href="#CATEGORY">CATEGORY</a></li>
162a0989	7	<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
162a0989	8	<li><a href="#METHODS">METHODS</a>
b5d537cc	9	<ul><li><a href="#init">init</a></li>
	10	<li><a href="#quit">quit</a></li>
	11	<li><a href="#linked_version">linked_version</a></li>
	12	<li><a href="#open_audio">open_audio</a></li>
	13	<li><a href="#close_audio">close_audio</a></li>
	14	<li><a href="#query_spec">query_spec</a></li>
162a0989	15	</ul>
162a0989	16	</li>
449a007b	17	<li><a href="#AUTHORS">AUTHORS </a></li>
449a007b	18	<li><a href="#SEE_ALSO">SEE ALSO</a>
162a0989	19	</li>
	20	</ul><hr />
	21	<!-- INDEX END -->
	22
	23	<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
	24	<div id="NAME_CONTENT">
b5d537cc	25	<p>SDL::Mixer - Sound and music functions</p>
162a0989	26
162a0989	27	</div>
bfdd9c2e	28	<h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
	29	<div id="CATEGORY_CONTENT">
	30	<p>Mixer</p>
	31
	32	</div>
162a0989	33	<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
162a0989	34	<div id="DESCRIPTION_CONTENT">
b5d537cc	35	<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
b5d537cc	36	in and out.</p>
162a0989	37
	38	</div>
	39	<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
	40	<div id="METHODS_CONTENT">
	41
	42	</div>
b5d537cc	43	<h2 id="init">init</h2>
b5d537cc	44	<div id="init_CONTENT">
3bc8c797	45	<pre> my $init_flags = SDL::Mixer::init( $flags );
162a0989	46
162a0989	47	</pre>
3bc8c797	48	<p>Loads dynamic libraries and prepares them for use. Flags should be one or more flags from init flags OR'd together.
	49	It returns the flags successfully initialized, or 0 on failure.</p>
	50	<p>Example:</p>
	51	<pre> use SDL::Mixer;
	52
	53	my $init_flags = SDL::Mixer::init( MIX_INIT_MP3 \| MIX_INIT_MOD \| MIX_INIT_FLAC \| MIX_INIT_OGG );
	54
	55	print("We have MP3 support!\n") if $init_flags & MIX_INIT_MP3;
	56	print("We have MOD support!\n") if $init_flags & MIX_INIT_MOD;
	57	print("We have FLAC support!\n") if $init_flags & MIX_INIT_FLAC;
	58	print("We have OGG support!\n") if $init_flags & MIX_INIT_OGG;
	59
	60	</pre>
	61	<p>Flags:</p>
	62	<ul>
	63	<li>MIX_INIT_MP3 </li>
	64	<li>MIX_INIT_MOD </li>
	65	<li>MIX_INIT_FLAC </li>
	66	<li>MIX_INIT_OGG</li>
	67	</ul>
	68
	69	<p><strong>Note</strong>: Only available for SDL_mixer >= 1.2.10</p>
162a0989	70
162a0989	71	</div>
b5d537cc	72	<h2 id="quit">quit</h2>
b5d537cc	73	<div id="quit_CONTENT">
3bc8c797	74	<pre> SDL::Mixer::quit();
162a0989	75
162a0989	76	</pre>
3bc8c797	77	<p>This function unloads the liraries previously loaded with <a href="#init">init()</a>.</p>
3bc8c797	78	<p><strong>Note</strong>: Only available for SDL_mixer >= 1.2.10</p>
162a0989	79
162a0989	80	</div>
b5d537cc	81	<h2 id="linked_version">linked_version</h2>
b5d537cc	82	<div id="linked_version_CONTENT">
3bc8c797	83	<pre> $version = SDL::Mixer::linked_version();
	84
	85	</pre>
	86	<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>
	87	are available.</p>
	88	<p>Example:</p>
	89	<pre> use SDL::Mixer;
	90	use SDL::Version;
	91
	92	my $version = SDL::Mixer::linked_version();
	93
	94	printf("%d.%d.%d\n", $version->major, $version->minor, $version->patch); # prints "1.2.8" for me
162a0989	95
162a0989	96	</pre>
162a0989	97
162a0989	98	</div>
b5d537cc	99	<h2 id="open_audio">open_audio</h2>
b5d537cc	100	<div id="open_audio_CONTENT">
3bc8c797	101	<pre> my $audio_opened = SDL::Mixer::open_audio( $frequency, $format, $channels, $chunksize );
	102
	103	</pre>
	104	<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
	105	your provided, however it will automatically translate between the expected format and the real one. You can retrieve the real format using
	106	<a href="http://search.cpan.org/perldoc?query_spec">query_spec</a>. </p>
	107	<p>Returns 0 on success, -1 on error.</p>
	108	<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
	109	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
	110	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
	111	desired audio type is not supported. </p>
	112	<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
92e293d6	113	<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
3bc8c797	114	components to use SDL_mixer without necessitating a great deal of inter-component awareness. Be warned however that in such a situation, the
	115	latest components to initialize SDL_mixer will probably not get the SDL_mixer settings they're expecting. </p>
	116	<p>Example:</p>
	117	<pre> use SDL;
	118	use SDL::Mixer;
	119
	120	printf("Error initializing SDL_mixer: %s\n", SDL::get_error()) unless SDL::Mixer::open_audio(44100, AUDIO_S16, 2, 1024) == 0;
162a0989	121
b5d537cc	122	</pre>
162a0989	123
162a0989	124	</div>
b5d537cc	125	<h2 id="close_audio">close_audio</h2>
b5d537cc	126	<div id="close_audio_CONTENT">
3bc8c797	127	<pre> SDL::Mixer::close_audio();
162a0989	128
b5d537cc	129	</pre>
3bc8c797	130	<p>Close the mixer and halting all playing audio. This function does not return anything.</p>
162a0989	131
162a0989	132	</div>
b5d537cc	133	<h2 id="query_spec">query_spec</h2>
b5d537cc	134	<div id="query_spec_CONTENT">
3bc8c797	135	<pre> my @query_spec = @{ SDL::Mixer::query_spec() };
	136
	137	</pre>
	138	<p>Find out what the actual audio device parameters are.
	139	This function returns 1 as first array element (status) if the audio has been opened, 0 otherwise.</p>
	140	<p>Example:</p>
	141	<pre> use SDL::Mixer;
	142
	143	my ($status, $freq, $format, $channels) = @{ SDL::Mixer::query_spec() };
	144
	145	printf("%s, %s, %s, %s\n", $status, $freq, $format, $channels);
162a0989	146
b5d537cc	147	</pre>
162a0989	148
162a0989	149	</div>
449a007b	150	<h1 id="AUTHORS">AUTHORS </h1><p><a href="#TOP" class="toplink">Top</a></p>
449a007b	151	<div id="AUTHORS_CONTENT">
b5d537cc	152	<p>Tobias Leich [FROGGS]</p>
449a007b	153
	154	</div>
	155	<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
	156	<div id="SEE_ALSO_CONTENT">
55bbf7a2	157	<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>
449a007b	158
449a007b	159	</div>
162a0989	160	</div>