<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>SDL_sound: SDL_sound.h File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css">
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.9 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li class="current"><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div class="tabs">
<ul>
<li><a href="files.html"><span>File List</span></a></li>
<li><a href="globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>SDL_sound.h File Reference</h1><code>#include "SDL.h"</code><br>
<code>#include "SDL_endian.h"</code><br>
<p>
<a href="SDL__sound_8h_source.html">Go to the source code of this file.</a><table border="0" cellpadding="0" cellspacing="0">
<tr><td></td></tr>
<tr><td colspan="2"><br><h2>Data Structures</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">struct </td><td class="memItemRight" valign="bottom"><a class="el" href="structSound__AudioInfo.html">Sound_AudioInfo</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Information about an existing sample's format. <a href="structSound__AudioInfo.html#_details">More...</a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">struct </td><td class="memItemRight" valign="bottom"><a class="el" href="structSound__DecoderInfo.html">Sound_DecoderInfo</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Information about available soudn decoders. <a href="structSound__DecoderInfo.html#_details">More...</a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">struct </td><td class="memItemRight" valign="bottom"><a class="el" href="structSound__Sample.html">Sound_Sample</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Represents sound data in the process of being decoded. <a href="structSound__Sample.html#_details">More...</a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">struct </td><td class="memItemRight" valign="bottom"><a class="el" href="structSound__Version.html">Sound_Version</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Information the version of SDL_sound in use. <a href="structSound__Version.html#_details">More...</a><br></td></tr>
<tr><td colspan="2"><br><h2>Defines</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#059b1c022acec0abbdab4a981b6e8e7d">SOUND_VERSION</a>(x)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Macro to determine SDL_sound version program was compiled against. <a href="#059b1c022acec0abbdab4a981b6e8e7d"></a><br></td></tr>
<tr><td colspan="2"><br><h2>Enumerations</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">enum </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#bf2c8cef39e83f01531f0bf255bdc625">Sound_SampleFlags</a> { <br>
<a class="el" href="SDL__sound_8h.html#bf2c8cef39e83f01531f0bf255bdc625192a6518e94eabf9cd5c45babc9635ee">SOUND_SAMPLEFLAG_NONE</a> = 0,
<a class="el" href="SDL__sound_8h.html#bf2c8cef39e83f01531f0bf255bdc625334d72e6e376dae44baa66746398bbaa">SOUND_SAMPLEFLAG_CANSEEK</a> = 1,
<a class="el" href="SDL__sound_8h.html#bf2c8cef39e83f01531f0bf255bdc625e0b562eebb0bf6cdf3da87eb1b4914be">SOUND_SAMPLEFLAG_EOF</a> = 1 << 29,
<a class="el" href="SDL__sound_8h.html#bf2c8cef39e83f01531f0bf255bdc6255d6c02e3276932f2217ee09a51eed65f">SOUND_SAMPLEFLAG_ERROR</a> = 1 << 30,
<br>
<a class="el" href="SDL__sound_8h.html#bf2c8cef39e83f01531f0bf255bdc625b269a22d877556f5569dc737ad984e1a">SOUND_SAMPLEFLAG_EAGAIN</a> = 1 << 31
<br>
}</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Flags that are used in a <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a> to show various states. <a href="SDL__sound_8h.html#bf2c8cef39e83f01531f0bf255bdc625">More...</a><br></td></tr>
<tr><td colspan="2"><br><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#bda6027ae5b226e626a9e1ea1f6e626c">Sound_GetLinkedVersion</a> (<a class="el" href="structSound__Version.html">Sound_Version</a> *ver)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get the version of SDL_sound that is linked against your program. <a href="#bda6027ae5b226e626a9e1ea1f6e626c"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#44e4cafdb81fc9f9135796bcfd3fb44f">Sound_Init</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Initialize SDL_sound. <a href="#44e4cafdb81fc9f9135796bcfd3fb44f"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#94408f49764dc122b0fad0397dccc941">Sound_Quit</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Shutdown SDL_sound. <a href="#94408f49764dc122b0fad0397dccc941"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">const <a class="el" href="structSound__DecoderInfo.html">Sound_DecoderInfo</a> ** </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#bbae3fccdec9fad347aa71a29bd4f074">Sound_AvailableDecoders</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get a list of sound formats supported by this version of SDL_sound. <a href="#bbae3fccdec9fad347aa71a29bd4f074"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">const char * </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#db99dd3e7266c234e437bebf3be9e061">Sound_GetError</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get the last SDL_sound error message as a null-terminated string. <a href="#db99dd3e7266c234e437bebf3be9e061"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#7c0a82fc646c5b819b8d0e81bea029fb">Sound_ClearError</a> (void)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Clear the current error message. <a href="#7c0a82fc646c5b819b8d0e81bea029fb"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="structSound__Sample.html">Sound_Sample</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#10b9c44cc1cc2ff8a93977b43870cb53">Sound_NewSample</a> (SDL_RWops *rw, const char *ext, <a class="el" href="structSound__AudioInfo.html">Sound_AudioInfo</a> *desired, Uint32 bufferSize)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Start decoding a new sound sample. <a href="#10b9c44cc1cc2ff8a93977b43870cb53"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="structSound__Sample.html">Sound_Sample</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#0869896a4bb39ee002257aa1cb3c39ec">Sound_NewSampleFromFile</a> (const char *fname, <a class="el" href="structSound__AudioInfo.html">Sound_AudioInfo</a> *desired, Uint32 bufferSize)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Start decoding a new sound sample from a file on disk. <a href="#0869896a4bb39ee002257aa1cb3c39ec"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#7f16cbb883e57b772bae0507ac4d5488">Sound_FreeSample</a> (<a class="el" href="structSound__Sample.html">Sound_Sample</a> *sample)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Dispose of a <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a>. <a href="#7f16cbb883e57b772bae0507ac4d5488"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#c09076aa2bdc14d08130e25a6915279d">Sound_SetBufferSize</a> (<a class="el" href="structSound__Sample.html">Sound_Sample</a> *sample, Uint32 new_size)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Change the current buffer size for a sample. <a href="#c09076aa2bdc14d08130e25a6915279d"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">Uint32 </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#6dbdf33dc4bc6b832fec2f4ffe5d546e">Sound_Decode</a> (<a class="el" href="structSound__Sample.html">Sound_Sample</a> *sample)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Decode more of the sound data in a <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a>. <a href="#6dbdf33dc4bc6b832fec2f4ffe5d546e"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">Uint32 </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#07f8d77bb5449be3707625f58de1aba7">Sound_DecodeAll</a> (<a class="el" href="structSound__Sample.html">Sound_Sample</a> *sample)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Decode the remainder of the sound data in a <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a>. <a href="#07f8d77bb5449be3707625f58de1aba7"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#720f92a75c0340c879c945ec3e9fdf70">Sound_Rewind</a> (<a class="el" href="structSound__Sample.html">Sound_Sample</a> *sample)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Rewind a sample to the start. <a href="#720f92a75c0340c879c945ec3e9fdf70"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="SDL__sound_8h.html#d8b48e7fdb78c95e7ff88cea097af18b">Sound_Seek</a> (<a class="el" href="structSound__Sample.html">Sound_Sample</a> *sample, Uint32 ms)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Seek to a different point in a sample. <a href="#d8b48e7fdb78c95e7ff88cea097af18b"></a><br></td></tr>
</table>
<hr><h2>Detailed Description</h2>
<hr><h2>Define Documentation</h2>
<a class="anchor" name="059b1c022acec0abbdab4a981b6e8e7d"></a><!-- doxytag: member="SDL_sound.h::SOUND_VERSION" ref="059b1c022acec0abbdab4a981b6e8e7d" args="(x)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define SOUND_VERSION </td>
<td>(</td>
<td class="paramtype">x </td>
<td class="paramname"> </td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
<b>Value:</b><div class="fragment"><pre class="fragment">{ \
(x)->major = SOUND_VER_MAJOR; \
(x)->minor = SOUND_VER_MINOR; \
(x)->patch = SOUND_VER_PATCH; \
}
</pre></div>Macro to determine SDL_sound version program was compiled against.
<p>
This macro fills in a <a class="el" href="structSound__Version.html" title="Information the version of SDL_sound in use.">Sound_Version</a> structure with the version of the library you compiled against. This is determined by what header the compiler uses. Note that if you dynamically linked the library, you might have a slightly newer or older version at runtime. That version can be determined with <a class="el" href="SDL__sound_8h.html#bda6027ae5b226e626a9e1ea1f6e626c" title="Get the version of SDL_sound that is linked against your program.">Sound_GetLinkedVersion()</a>, which, unlike SOUND_VERSION, is not a macro.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>x</em> </td><td>A pointer to a <a class="el" href="structSound__Version.html" title="Information the version of SDL_sound in use.">Sound_Version</a> struct to initialize.</td></tr>
</table>
</dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="structSound__Version.html" title="Information the version of SDL_sound in use.">Sound_Version</a> <p>
<a class="el" href="SDL__sound_8h.html#bda6027ae5b226e626a9e1ea1f6e626c" title="Get the version of SDL_sound that is linked against your program.">Sound_GetLinkedVersion</a> </dd></dl>
</div>
</div><p>
<hr><h2>Enumeration Type Documentation</h2>
<a class="anchor" name="bf2c8cef39e83f01531f0bf255bdc625"></a><!-- doxytag: member="SDL_sound.h::Sound_SampleFlags" ref="bf2c8cef39e83f01531f0bf255bdc625" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">enum <a class="el" href="SDL__sound_8h.html#bf2c8cef39e83f01531f0bf255bdc625">Sound_SampleFlags</a> </td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Flags that are used in a <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a> to show various states.
<p>
To use: <div class="fragment"><pre class="fragment"> <span class="keywordflow">if</span> (sample->flags & <a class="code" href="SDL__sound_8h.html#bf2c8cef39e83f01531f0bf255bdc6255d6c02e3276932f2217ee09a51eed65f">SOUND_SAMPLEFLAG_ERROR</a>) { dosomething(); }
</pre></div><p>
<dl class="see" compact><dt><b>See also:</b></dt><dd>Sound_SampleNew <p>
Sound_SampleNewFromFile <p>
Sound_SampleDecode <p>
Sound_SampleDecodeAll <p>
Sound_SampleSeek </dd></dl>
<dl compact><dt><b>Enumerator: </b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><em><a class="anchor" name="bf2c8cef39e83f01531f0bf255bdc625192a6518e94eabf9cd5c45babc9635ee"></a><!-- doxytag: member="SOUND_SAMPLEFLAG_NONE" ref="bf2c8cef39e83f01531f0bf255bdc625192a6518e94eabf9cd5c45babc9635ee" args="" -->SOUND_SAMPLEFLAG_NONE</em> </td><td>
No special attributes. </td></tr>
<tr><td valign="top"><em><a class="anchor" name="bf2c8cef39e83f01531f0bf255bdc625334d72e6e376dae44baa66746398bbaa"></a><!-- doxytag: member="SOUND_SAMPLEFLAG_CANSEEK" ref="bf2c8cef39e83f01531f0bf255bdc625334d72e6e376dae44baa66746398bbaa" args="" -->SOUND_SAMPLEFLAG_CANSEEK</em> </td><td>
Sample can seek to arbitrary points. </td></tr>
<tr><td valign="top"><em><a class="anchor" name="bf2c8cef39e83f01531f0bf255bdc625e0b562eebb0bf6cdf3da87eb1b4914be"></a><!-- doxytag: member="SOUND_SAMPLEFLAG_EOF" ref="bf2c8cef39e83f01531f0bf255bdc625e0b562eebb0bf6cdf3da87eb1b4914be" args="" -->SOUND_SAMPLEFLAG_EOF</em> </td><td>
End of input stream. </td></tr>
<tr><td valign="top"><em><a class="anchor" name="bf2c8cef39e83f01531f0bf255bdc6255d6c02e3276932f2217ee09a51eed65f"></a><!-- doxytag: member="SOUND_SAMPLEFLAG_ERROR" ref="bf2c8cef39e83f01531f0bf255bdc6255d6c02e3276932f2217ee09a51eed65f" args="" -->SOUND_SAMPLEFLAG_ERROR</em> </td><td>
Unrecoverable error. </td></tr>
<tr><td valign="top"><em><a class="anchor" name="bf2c8cef39e83f01531f0bf255bdc625b269a22d877556f5569dc737ad984e1a"></a><!-- doxytag: member="SOUND_SAMPLEFLAG_EAGAIN" ref="bf2c8cef39e83f01531f0bf255bdc625b269a22d877556f5569dc737ad984e1a" args="" -->SOUND_SAMPLEFLAG_EAGAIN</em> </td><td>
Function would block, or temp error. </td></tr>
</table>
</dl>
</div>
</div><p>
<hr><h2>Function Documentation</h2>
<a class="anchor" name="bbae3fccdec9fad347aa71a29bd4f074"></a><!-- doxytag: member="SDL_sound.h::Sound_AvailableDecoders" ref="bbae3fccdec9fad347aa71a29bd4f074" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">const <a class="el" href="structSound__DecoderInfo.html">Sound_DecoderInfo</a> ** Sound_AvailableDecoders </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"> </td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Get a list of sound formats supported by this version of SDL_sound.
<p>
This is for informational purposes only. Note that the extension listed is merely convention: if we list "MP3", you can open an MPEG-1 Layer 3 audio file with an extension of "XYZ", if you like. The file extensions are informational, and only required as a hint to choosing the correct decoder, since the sound data may not be coming from a file at all, thanks to the abstraction that an SDL_RWops provides.<p>
The returned value is an array of pointers to <a class="el" href="structSound__DecoderInfo.html" title="Information about available soudn decoders.">Sound_DecoderInfo</a> structures, with a NULL entry to signify the end of the list:<p>
<div class="fragment"><pre class="fragment"> <a class="code" href="structSound__DecoderInfo.html" title="Information about available soudn decoders.">Sound_DecoderInfo</a> **i;
<span class="keywordflow">for</span> (i = <a class="code" href="SDL__sound_8h.html#bbae3fccdec9fad347aa71a29bd4f074" title="Get a list of sound formats supported by this version of SDL_sound.">Sound_AvailableDecoders</a>(); *i != NULL; i++)
{
printf(<span class="stringliteral">"Supported sound format: [%s], which is [%s].\n"</span>,
i->extension, i-><a class="code" href="structSound__DecoderInfo.html#c1241b30e4121aedd4286351b27f93d5">description</a>);
<span class="comment">// ...and other fields...</span>
}
</pre></div><p>
The return values are pointers to static internal memory, and should be considered READ ONLY, and never freed.<p>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>READ ONLY Null-terminated array of READ ONLY structures.</dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="structSound__DecoderInfo.html" title="Information about available soudn decoders.">Sound_DecoderInfo</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="7c0a82fc646c5b819b8d0e81bea029fb"></a><!-- doxytag: member="SDL_sound.h::Sound_ClearError" ref="7c0a82fc646c5b819b8d0e81bea029fb" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void Sound_ClearError </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"> </td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Clear the current error message.
<p>
The next call to <a class="el" href="SDL__sound_8h.html#db99dd3e7266c234e437bebf3be9e061" title="Get the last SDL_sound error message as a null-terminated string.">Sound_GetError()</a> after <a class="el" href="SDL__sound_8h.html#7c0a82fc646c5b819b8d0e81bea029fb" title="Clear the current error message.">Sound_ClearError()</a> will return NULL.<p>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="SDL__sound_8h.html#db99dd3e7266c234e437bebf3be9e061" title="Get the last SDL_sound error message as a null-terminated string.">Sound_GetError</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="6dbdf33dc4bc6b832fec2f4ffe5d546e"></a><!-- doxytag: member="SDL_sound.h::Sound_Decode" ref="6dbdf33dc4bc6b832fec2f4ffe5d546e" args="(Sound_Sample *sample)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Uint32 Sound_Decode </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structSound__Sample.html">Sound_Sample</a> * </td>
<td class="paramname"> <em>sample</em> </td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Decode more of the sound data in a <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a>.
<p>
It will decode at most sample->buffer_size bytes into sample->buffer in the desired format, and return the number of decoded bytes. If sample->buffer_size bytes could not be decoded, then please refer to sample->flags to determine if this was an end-of-stream or error condition.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>sample</em> </td><td>Do more decoding to this <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a>. </td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>number of bytes decoded into sample->buffer. If it is less than sample->buffer_size, then you should check sample->flags to see what the current state of the sample is (EOF, error, read again).</dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="SDL__sound_8h.html#07f8d77bb5449be3707625f58de1aba7" title="Decode the remainder of the sound data in a Sound_Sample.">Sound_DecodeAll</a> <p>
<a class="el" href="SDL__sound_8h.html#c09076aa2bdc14d08130e25a6915279d" title="Change the current buffer size for a sample.">Sound_SetBufferSize</a> <p>
<a class="el" href="SDL__sound_8h.html#d8b48e7fdb78c95e7ff88cea097af18b" title="Seek to a different point in a sample.">Sound_Seek</a> <p>
<a class="el" href="SDL__sound_8h.html#720f92a75c0340c879c945ec3e9fdf70" title="Rewind a sample to the start.">Sound_Rewind</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="07f8d77bb5449be3707625f58de1aba7"></a><!-- doxytag: member="SDL_sound.h::Sound_DecodeAll" ref="07f8d77bb5449be3707625f58de1aba7" args="(Sound_Sample *sample)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Uint32 Sound_DecodeAll </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structSound__Sample.html">Sound_Sample</a> * </td>
<td class="paramname"> <em>sample</em> </td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Decode the remainder of the sound data in a <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a>.
<p>
This will dynamically allocate memory for the ENTIRE remaining sample. sample->buffer_size and sample->buffer will be updated to reflect the new buffer. Please refer to sample->flags to determine if the decoding finished due to an End-of-stream or error condition.<p>
Be aware that sound data can take a large amount of memory, and that this function may block for quite awhile while processing. Also note that a streaming source (for example, from a SDL_RWops that is getting fed from an Internet radio feed that doesn't end) may fill all available memory before giving up...be sure to use this on finite sound sources only!<p>
When decoding the sample in its entirety, the work is done one buffer at a time. That is, sound is decoded in sample->buffer_size blocks, and appended to a continually-growing buffer until the decoding completes. That means that this function will need enough RAM to hold approximately sample->buffer_size bytes plus the complete decoded sample at most. The larger your buffer size, the less overhead this function needs, but beware the possibility of paging to disk. Best to make this user-configurable if the sample isn't specific and small.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>sample</em> </td><td>Do all decoding for this <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a>. </td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>number of bytes decoded into sample->buffer. You should check sample->flags to see what the current state of the sample is (EOF, error, read again).</dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="SDL__sound_8h.html#6dbdf33dc4bc6b832fec2f4ffe5d546e" title="Decode more of the sound data in a Sound_Sample.">Sound_Decode</a> <p>
<a class="el" href="SDL__sound_8h.html#c09076aa2bdc14d08130e25a6915279d" title="Change the current buffer size for a sample.">Sound_SetBufferSize</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="7f16cbb883e57b772bae0507ac4d5488"></a><!-- doxytag: member="SDL_sound.h::Sound_FreeSample" ref="7f16cbb883e57b772bae0507ac4d5488" args="(Sound_Sample *sample)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void Sound_FreeSample </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structSound__Sample.html">Sound_Sample</a> * </td>
<td class="paramname"> <em>sample</em> </td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Dispose of a <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a>.
<p>
This will also close/dispose of the SDL_RWops that was used at creation time, so there's no need to keep a reference to that around. The <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a> pointer is invalid after this call, and will almost certainly result in a crash if you attempt to keep using it.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>sample</em> </td><td>The <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a> to delete.</td></tr>
</table>
</dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="SDL__sound_8h.html#10b9c44cc1cc2ff8a93977b43870cb53" title="Start decoding a new sound sample.">Sound_NewSample</a> <p>
<a class="el" href="SDL__sound_8h.html#0869896a4bb39ee002257aa1cb3c39ec" title="Start decoding a new sound sample from a file on disk.">Sound_NewSampleFromFile</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="db99dd3e7266c234e437bebf3be9e061"></a><!-- doxytag: member="SDL_sound.h::Sound_GetError" ref="db99dd3e7266c234e437bebf3be9e061" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">const char * Sound_GetError </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"> </td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Get the last SDL_sound error message as a null-terminated string.
<p>
This will be NULL if there's been no error since the last call to this function. The pointer returned by this call points to an internal buffer, and should not be deallocated. Each thread has a unique error state associated with it, but each time a new error message is set, it will overwrite the previous one associated with that thread. It is safe to call this function at anytime, even before <a class="el" href="SDL__sound_8h.html#44e4cafdb81fc9f9135796bcfd3fb44f" title="Initialize SDL_sound.">Sound_Init()</a>.<p>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>READ ONLY string of last error message.</dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="SDL__sound_8h.html#7c0a82fc646c5b819b8d0e81bea029fb" title="Clear the current error message.">Sound_ClearError</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="bda6027ae5b226e626a9e1ea1f6e626c"></a><!-- doxytag: member="SDL_sound.h::Sound_GetLinkedVersion" ref="bda6027ae5b226e626a9e1ea1f6e626c" args="(Sound_Version *ver)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void Sound_GetLinkedVersion </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structSound__Version.html">Sound_Version</a> * </td>
<td class="paramname"> <em>ver</em> </td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Get the version of SDL_sound that is linked against your program.
<p>
If you are using a shared library (DLL) version of SDL_sound, then it is possible that it will be different than the version you compiled against.<p>
This is a real function; the macro SOUND_VERSION tells you what version of SDL_sound you compiled against:<p>
<div class="fragment"><pre class="fragment"> <a class="code" href="structSound__Version.html" title="Information the version of SDL_sound in use.">Sound_Version</a> compiled;
<a class="code" href="structSound__Version.html" title="Information the version of SDL_sound in use.">Sound_Version</a> linked;
<a class="code" href="SDL__sound_8h.html#059b1c022acec0abbdab4a981b6e8e7d" title="Macro to determine SDL_sound version program was compiled against.">SOUND_VERSION</a>(&compiled);
<a class="code" href="SDL__sound_8h.html#bda6027ae5b226e626a9e1ea1f6e626c" title="Get the version of SDL_sound that is linked against your program.">Sound_GetLinkedVersion</a>(&linked);
printf(<span class="stringliteral">"We compiled against SDL_sound version %d.%d.%d ...\n"</span>,
compiled.<a class="code" href="structSound__Version.html#68ed43edb6114f117edd45084baae1b4">major</a>, compiled.<a class="code" href="structSound__Version.html#095420931df560c545e0cf0d6fecf56a">minor</a>, compiled.<a class="code" href="structSound__Version.html#7ebc29f83c1a812ee24b556ad6dfc1f4">patch</a>);
printf(<span class="stringliteral">"But we linked against SDL_sound version %d.%d.%d.\n"</span>,
linked.<a class="code" href="structSound__Version.html#68ed43edb6114f117edd45084baae1b4">major</a>, linked.<a class="code" href="structSound__Version.html#095420931df560c545e0cf0d6fecf56a">minor</a>, linked.<a class="code" href="structSound__Version.html#7ebc29f83c1a812ee24b556ad6dfc1f4">patch</a>);
</pre></div><p>
This function may be called safely at any time, even before <a class="el" href="SDL__sound_8h.html#44e4cafdb81fc9f9135796bcfd3fb44f" title="Initialize SDL_sound.">Sound_Init()</a>.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ver</em> </td><td><a class="el" href="structSound__Version.html" title="Information the version of SDL_sound in use.">Sound_Version</a> structure to fill with shared library's version.</td></tr>
</table>
</dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="structSound__Version.html" title="Information the version of SDL_sound in use.">Sound_Version</a> <p>
<a class="el" href="SDL__sound_8h.html#059b1c022acec0abbdab4a981b6e8e7d" title="Macro to determine SDL_sound version program was compiled against.">SOUND_VERSION</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="44e4cafdb81fc9f9135796bcfd3fb44f"></a><!-- doxytag: member="SDL_sound.h::Sound_Init" ref="44e4cafdb81fc9f9135796bcfd3fb44f" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Sound_Init </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"> </td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Initialize SDL_sound.
<p>
This must be called before any other SDL_sound function (except perhaps <a class="el" href="SDL__sound_8h.html#bda6027ae5b226e626a9e1ea1f6e626c" title="Get the version of SDL_sound that is linked against your program.">Sound_GetLinkedVersion()</a>). You should call SDL_Init() before calling this. <a class="el" href="SDL__sound_8h.html#44e4cafdb81fc9f9135796bcfd3fb44f" title="Initialize SDL_sound.">Sound_Init()</a> will attempt to call SDL_Init(SDL_INIT_AUDIO), just in case. This is a safe behaviour, but it may not configure SDL to your liking by itself.<p>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>nonzero on success, zero on error. Specifics of the error can be gleaned from <a class="el" href="SDL__sound_8h.html#db99dd3e7266c234e437bebf3be9e061" title="Get the last SDL_sound error message as a null-terminated string.">Sound_GetError()</a>.</dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="SDL__sound_8h.html#94408f49764dc122b0fad0397dccc941" title="Shutdown SDL_sound.">Sound_Quit</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="10b9c44cc1cc2ff8a93977b43870cb53"></a><!-- doxytag: member="SDL_sound.h::Sound_NewSample" ref="10b9c44cc1cc2ff8a93977b43870cb53" args="(SDL_RWops *rw, const char *ext, Sound_AudioInfo *desired, Uint32 bufferSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structSound__Sample.html">Sound_Sample</a> * Sound_NewSample </td>
<td>(</td>
<td class="paramtype">SDL_RWops * </td>
<td class="paramname"> <em>rw</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>ext</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structSound__AudioInfo.html">Sound_AudioInfo</a> * </td>
<td class="paramname"> <em>desired</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">Uint32 </td>
<td class="paramname"> <em>bufferSize</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Start decoding a new sound sample.
<p>
The data is read via an SDL_RWops structure (see SDL_rwops.h in the SDL include directory), so it may be coming from memory, disk, network stream, etc. The (ext) parameter is merely a hint to determining the correct decoder; if you specify, for example, "mp3" for an extension, and one of the decoders lists that as a handled extension, then that decoder is given first shot at trying to claim the data for decoding. If none of the extensions match (or the extension is NULL), then every decoder examines the data to determine if it can handle it, until one accepts it. In such a case your SDL_RWops will need to be capable of rewinding to the start of the stream.<p>
If no decoders can handle the data, a NULL value is returned, and a human readable error message can be fetched from <a class="el" href="SDL__sound_8h.html#db99dd3e7266c234e437bebf3be9e061" title="Get the last SDL_sound error message as a null-terminated string.">Sound_GetError()</a>.<p>
Optionally, a desired audio format can be specified. If the incoming data is in a different format, SDL_sound will convert it to the desired format on the fly. Note that this can be an expensive operation, so it may be wise to convert data before you need to play it back, if possible, or make sure your data is initially in the format that you need it in. If you don't want to convert the data, you can specify NULL for a desired format. The incoming format of the data, preconversion, can be found in the <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a> structure.<p>
Note that the raw sound data "decoder" needs you to specify both the extension "RAW" and a "desired" format, or it will refuse to handle the data. This is to prevent it from catching all formats unsupported by the other decoders.<p>
Finally, specify an initial buffer size; this is the number of bytes that will be allocated to store each read from the sound buffer. The more you can safely allocate, the more decoding can be done in one block, but the more resources you have to use up, and the longer each decoding call will take. Note that different data formats require more or less space to store. This buffer can be resized via <a class="el" href="SDL__sound_8h.html#c09076aa2bdc14d08130e25a6915279d" title="Change the current buffer size for a sample.">Sound_SetBufferSize()</a> ...<p>
The buffer size specified must be a multiple of the size of a single sample point. So, if you want 16-bit, stereo samples, then your sample point size is (2 channels * 16 bits), or 32 bits per sample, which is four bytes. In such a case, you could specify 128 or 132 bytes for a buffer, but not 129, 130, or 131 (although in reality, you'll want to specify a MUCH larger buffer).<p>
When you are done with this <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a> pointer, you can dispose of it via <a class="el" href="SDL__sound_8h.html#7f16cbb883e57b772bae0507ac4d5488" title="Dispose of a Sound_Sample.">Sound_FreeSample()</a>.<p>
You do not have to keep a reference to (rw) around. If this function suceeds, it stores (rw) internally (and disposes of it during the call to <a class="el" href="SDL__sound_8h.html#7f16cbb883e57b772bae0507ac4d5488" title="Dispose of a Sound_Sample.">Sound_FreeSample()</a>). If this function fails, it will dispose of the SDL_RWops for you.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>rw</em> </td><td>SDL_RWops with sound data. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>ext</em> </td><td>File extension normally associated with a data format. Can usually be NULL. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>desired</em> </td><td>Format to convert sound data into. Can usually be NULL, if you don't need conversion. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>bufferSize</em> </td><td>Size, in bytes, to allocate for the decoding buffer. </td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd><a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a> pointer, which is used as a handle to several other SDL_sound APIs. NULL on error. If error, use <a class="el" href="SDL__sound_8h.html#db99dd3e7266c234e437bebf3be9e061" title="Get the last SDL_sound error message as a null-terminated string.">Sound_GetError()</a> to see what went wrong.</dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="SDL__sound_8h.html#0869896a4bb39ee002257aa1cb3c39ec" title="Start decoding a new sound sample from a file on disk.">Sound_NewSampleFromFile</a> <p>
<a class="el" href="SDL__sound_8h.html#c09076aa2bdc14d08130e25a6915279d" title="Change the current buffer size for a sample.">Sound_SetBufferSize</a> <p>
<a class="el" href="SDL__sound_8h.html#6dbdf33dc4bc6b832fec2f4ffe5d546e" title="Decode more of the sound data in a Sound_Sample.">Sound_Decode</a> <p>
<a class="el" href="SDL__sound_8h.html#07f8d77bb5449be3707625f58de1aba7" title="Decode the remainder of the sound data in a Sound_Sample.">Sound_DecodeAll</a> <p>
<a class="el" href="SDL__sound_8h.html#d8b48e7fdb78c95e7ff88cea097af18b" title="Seek to a different point in a sample.">Sound_Seek</a> <p>
<a class="el" href="SDL__sound_8h.html#720f92a75c0340c879c945ec3e9fdf70" title="Rewind a sample to the start.">Sound_Rewind</a> <p>
<a class="el" href="SDL__sound_8h.html#7f16cbb883e57b772bae0507ac4d5488" title="Dispose of a Sound_Sample.">Sound_FreeSample</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="0869896a4bb39ee002257aa1cb3c39ec"></a><!-- doxytag: member="SDL_sound.h::Sound_NewSampleFromFile" ref="0869896a4bb39ee002257aa1cb3c39ec" args="(const char *fname, Sound_AudioInfo *desired, Uint32 bufferSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structSound__Sample.html">Sound_Sample</a> * Sound_NewSampleFromFile </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>filename</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structSound__AudioInfo.html">Sound_AudioInfo</a> * </td>
<td class="paramname"> <em>desired</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">Uint32 </td>
<td class="paramname"> <em>bufferSize</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Start decoding a new sound sample from a file on disk.
<p>
This is identical to <a class="el" href="SDL__sound_8h.html#10b9c44cc1cc2ff8a93977b43870cb53" title="Start decoding a new sound sample.">Sound_NewSample()</a>, but it creates an SDL_RWops for you from the file located in (filename). Note that (filename) is specified in platform-dependent notation. ("C:\\music\\mysong.mp3" on windows, and "/home/icculus/music/mysong.mp3" or whatever on Unix, etc.) <a class="el" href="SDL__sound_8h.html#10b9c44cc1cc2ff8a93977b43870cb53" title="Start decoding a new sound sample.">Sound_NewSample()</a>'s "ext" parameter is gleaned from the contents of (filename).<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>filename</em> </td><td>file containing sound data. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>desired</em> </td><td>Format to convert sound data into. Can usually be NULL, if you don't need conversion. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>bufferSize</em> </td><td>size, in bytes, of initial read buffer. </td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd><a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a> pointer, which is used as a handle to several other SDL_sound APIs. NULL on error. If error, use <a class="el" href="SDL__sound_8h.html#db99dd3e7266c234e437bebf3be9e061" title="Get the last SDL_sound error message as a null-terminated string.">Sound_GetError()</a> to see what went wrong.</dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="SDL__sound_8h.html#10b9c44cc1cc2ff8a93977b43870cb53" title="Start decoding a new sound sample.">Sound_NewSample</a> <p>
<a class="el" href="SDL__sound_8h.html#c09076aa2bdc14d08130e25a6915279d" title="Change the current buffer size for a sample.">Sound_SetBufferSize</a> <p>
<a class="el" href="SDL__sound_8h.html#6dbdf33dc4bc6b832fec2f4ffe5d546e" title="Decode more of the sound data in a Sound_Sample.">Sound_Decode</a> <p>
<a class="el" href="SDL__sound_8h.html#07f8d77bb5449be3707625f58de1aba7" title="Decode the remainder of the sound data in a Sound_Sample.">Sound_DecodeAll</a> <p>
<a class="el" href="SDL__sound_8h.html#d8b48e7fdb78c95e7ff88cea097af18b" title="Seek to a different point in a sample.">Sound_Seek</a> <p>
<a class="el" href="SDL__sound_8h.html#720f92a75c0340c879c945ec3e9fdf70" title="Rewind a sample to the start.">Sound_Rewind</a> <p>
<a class="el" href="SDL__sound_8h.html#7f16cbb883e57b772bae0507ac4d5488" title="Dispose of a Sound_Sample.">Sound_FreeSample</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="94408f49764dc122b0fad0397dccc941"></a><!-- doxytag: member="SDL_sound.h::Sound_Quit" ref="94408f49764dc122b0fad0397dccc941" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Sound_Quit </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"> </td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Shutdown SDL_sound.
<p>
This closes any SDL_RWops that were being used as sound sources, and frees any resources in use by SDL_sound.<p>
All <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a> pointers you had prior to this call are INVALIDATED.<p>
Once successfully deinitialized, <a class="el" href="SDL__sound_8h.html#44e4cafdb81fc9f9135796bcfd3fb44f" title="Initialize SDL_sound.">Sound_Init()</a> can be called again to restart the subsystem. All default API states are restored at this point.<p>
You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit() for you!<p>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>nonzero on success, zero on error. Specifics of the error can be gleaned from <a class="el" href="SDL__sound_8h.html#db99dd3e7266c234e437bebf3be9e061" title="Get the last SDL_sound error message as a null-terminated string.">Sound_GetError()</a>. If failure, state of SDL_sound is undefined, and probably badly screwed up.</dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="SDL__sound_8h.html#44e4cafdb81fc9f9135796bcfd3fb44f" title="Initialize SDL_sound.">Sound_Init</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="720f92a75c0340c879c945ec3e9fdf70"></a><!-- doxytag: member="SDL_sound.h::Sound_Rewind" ref="720f92a75c0340c879c945ec3e9fdf70" args="(Sound_Sample *sample)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int Sound_Rewind </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structSound__Sample.html">Sound_Sample</a> * </td>
<td class="paramname"> <em>sample</em> </td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Rewind a sample to the start.
<p>
Restart a sample at the start of its waveform data, as if newly created with <a class="el" href="SDL__sound_8h.html#10b9c44cc1cc2ff8a93977b43870cb53" title="Start decoding a new sound sample.">Sound_NewSample()</a>. If successful, the next call to Sound_Decode[All]() will give audio data from the earliest point in the stream.<p>
Beware that this function will fail if the SDL_RWops that feeds the decoder can not be rewound via it's seek method, but this can theoretically be avoided by wrapping it in some sort of buffering SDL_RWops.<p>
This function should ONLY fail if the RWops is not seekable, or SDL_sound is not initialized. Both can be controlled by the application, and thus, it is up to the developer's paranoia to dictate whether this function's return value need be checked at all.<p>
If this function fails, the state of the sample is undefined, but it is still safe to call <a class="el" href="SDL__sound_8h.html#7f16cbb883e57b772bae0507ac4d5488" title="Dispose of a Sound_Sample.">Sound_FreeSample()</a> to dispose of it.<p>
On success, ERROR, EOF, and EAGAIN are cleared from sample->flags. The ERROR flag is set on error.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>sample</em> </td><td>The <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a> to rewind. </td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>nonzero on success, zero on error. Specifics of the error can be gleaned from <a class="el" href="SDL__sound_8h.html#db99dd3e7266c234e437bebf3be9e061" title="Get the last SDL_sound error message as a null-terminated string.">Sound_GetError()</a>.</dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="SDL__sound_8h.html#d8b48e7fdb78c95e7ff88cea097af18b" title="Seek to a different point in a sample.">Sound_Seek</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="d8b48e7fdb78c95e7ff88cea097af18b"></a><!-- doxytag: member="SDL_sound.h::Sound_Seek" ref="d8b48e7fdb78c95e7ff88cea097af18b" args="(Sound_Sample *sample, Uint32 ms)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int Sound_Seek </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structSound__Sample.html">Sound_Sample</a> * </td>
<td class="paramname"> <em>sample</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">Uint32 </td>
<td class="paramname"> <em>ms</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Seek to a different point in a sample.
<p>
Reposition a sample's stream. If successful, the next call to Sound_Decode[All]() will give audio data from the offset you specified.<p>
The offset is specified in milliseconds from the start of the sample.<p>
Beware that this function can fail for several reasons. If the SDL_RWops that feeds the decoder can not seek, this call will almost certainly fail, but this can theoretically be avoided by wrapping it in some sort of buffering SDL_RWops. Some decoders can never seek, others can only seek with certain files. The decoders will set a flag in the sample at creation time to help you determine this.<p>
You should check sample->flags & SOUND_SAMPLEFLAG_CANSEEK before attempting. <a class="el" href="SDL__sound_8h.html#d8b48e7fdb78c95e7ff88cea097af18b" title="Seek to a different point in a sample.">Sound_Seek()</a> reports failure immediately if this flag isn't set. This function can still fail for other reasons if the flag is set.<p>
This function can be emulated in the application with <a class="el" href="SDL__sound_8h.html#720f92a75c0340c879c945ec3e9fdf70" title="Rewind a sample to the start.">Sound_Rewind()</a> and predecoding a specific amount of the sample, but this can be extremely inefficient. <a class="el" href="SDL__sound_8h.html#d8b48e7fdb78c95e7ff88cea097af18b" title="Seek to a different point in a sample.">Sound_Seek()</a> accelerates the seek on a with decoder-specific code.<p>
If this function fails, the sample should continue to function as if this call was never made. If there was an unrecoverable error, sample->flags & SOUND_SAMPLEFLAG_ERROR will be set, which you regular decoding loop can pick up.<p>
On success, ERROR, EOF, and EAGAIN are cleared from sample->flags.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>sample</em> </td><td>The <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a> to seek. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>ms</em> </td><td>The new position, in milliseconds from start of sample. </td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>nonzero on success, zero on error. Specifics of the error can be gleaned from <a class="el" href="SDL__sound_8h.html#db99dd3e7266c234e437bebf3be9e061" title="Get the last SDL_sound error message as a null-terminated string.">Sound_GetError()</a>.</dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="SDL__sound_8h.html#720f92a75c0340c879c945ec3e9fdf70" title="Rewind a sample to the start.">Sound_Rewind</a> </dd></dl>
</div>
</div><p>
<a class="anchor" name="c09076aa2bdc14d08130e25a6915279d"></a><!-- doxytag: member="SDL_sound.h::Sound_SetBufferSize" ref="c09076aa2bdc14d08130e25a6915279d" args="(Sound_Sample *sample, Uint32 new_size)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int Sound_SetBufferSize </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structSound__Sample.html">Sound_Sample</a> * </td>
<td class="paramname"> <em>sample</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">Uint32 </td>
<td class="paramname"> <em>new_size</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Change the current buffer size for a sample.
<p>
If the buffer size could be changed, then the sample->buffer and sample->buffer_size fields will reflect that. If they could not be changed, then your original sample state is preserved. If the buffer is shrinking, the data at the end of buffer is truncated. If the buffer is growing, the contents of the new space at the end is undefined until you decode more into it or initialize it yourself.<p>
The buffer size specified must be a multiple of the size of a single sample point. So, if you want 16-bit, stereo samples, then your sample point size is (2 channels * 16 bits), or 32 bits per sample, which is four bytes. In such a case, you could specify 128 or 132 bytes for a buffer, but not 129, 130, or 131 (although in reality, you'll want to specify a MUCH larger buffer).<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>sample</em> </td><td>The <a class="el" href="structSound__Sample.html" title="Represents sound data in the process of being decoded.">Sound_Sample</a> whose buffer to modify. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>new_size</em> </td><td>The desired size, in bytes, of the new buffer. </td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>non-zero if buffer size changed, zero on failure.</dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="SDL__sound_8h.html#6dbdf33dc4bc6b832fec2f4ffe5d546e" title="Decode more of the sound data in a Sound_Sample.">Sound_Decode</a> <p>
<a class="el" href="SDL__sound_8h.html#07f8d77bb5449be3707625f58de1aba7" title="Decode the remainder of the sound data in a Sound_Sample.">Sound_DecodeAll</a> </dd></dl>
</div>
</div><p>
</div>
<hr size="1"><address style="text-align: right;"><small>Generated on Thu Oct 1 23:26:48 2009 for SDL_sound by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.9 </small></address>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
6547eb8411a104bc398ae983b959fd62
>
files
>
9
