| blob | ae25b42ca2dad060f95b1ffe5cd56f52b8eba6b7 |
3 <html><head><title>Asynchronous Playback - ALURE</title><link rel="stylesheet" type="text/css" href="../styles/main.css"><script language=JavaScript src="../javascript/main.js"></script><script language=JavaScript src="../javascript/searchdata.js"></script></head><body class="ContentPage" onLoad="NDOnLoad()"><script language=JavaScript><!--
4 if (browserType) {document.write("<div class=" + browserType + ">");if (browserVer) {document.write("<div class=" + browserVer + ">"); }}// --></script>
6 <!-- Generated by Natural Docs, version 1.4 -->
7 <!-- http://www.naturaldocs.org -->
9 <!-- saved from url=(0026)http://www.naturaldocs.org -->
14 <div id=Content><div class="CSection"><div class=CTopic id=MainTopic><h1 class=CTitle><a name="Asynchronous_Playback"></a>Asynchronous Playback</h1><div class=CBody><!--START_ND_SUMMARY--><div class=Summary><div class=STitle>Summary</div><div class=SBorder><table border=0 cellspacing=0 cellpadding=0 class=STable><tr class="SMain"><td class=SEntry><a href="#Asynchronous_Playback" >Asynchronous Playback</a></td><td class=SDescription></td></tr><tr class="SGroup SIndent1"><td class=SEntry><a href="#Functions" >Functions</a></td><td class=SDescription></td></tr><tr class="SFunction SIndent2 SMarked"><td class=SEntry><a href="#alurePlaySourceStream" id=link1 onMouseOver="ShowTip(event, 'tt1', 'link1')" onMouseOut="HideTip('tt1')">alurePlaySourceStream</a></td><td class=SDescription>Plays a stream asynchronously, using the specified source ID. </td></tr><tr class="SFunction SIndent2"><td class=SEntry><a href="#alurePlaySource" id=link2 onMouseOver="ShowTip(event, 'tt2', 'link2')" onMouseOut="HideTip('tt2')">alurePlaySource</a></td><td class=SDescription>Plays the specified source ID and watches for it to stop. </td></tr><tr class="SFunction SIndent2 SMarked"><td class=SEntry><a href="#alureStopSource" id=link3 onMouseOver="ShowTip(event, 'tt3', 'link3')" onMouseOut="HideTip('tt3')">alureStopSource</a></td><td class=SDescription>Stops the specified source ID, and any associated asynchronous stream. </td></tr><tr class="SFunction SIndent2"><td class=SEntry><a href="#alurePauseSource" id=link4 onMouseOver="ShowTip(event, 'tt4', 'link4')" onMouseOut="HideTip('tt4')">alurePauseSource</a></td><td class=SDescription>Pauses the specified source ID, and any associated asynchronous stream. </td></tr><tr class="SFunction SIndent2 SMarked"><td class=SEntry><a href="#alureGetSourceOffset" id=link5 onMouseOver="ShowTip(event, 'tt5', 'link5')" onMouseOut="HideTip('tt5')">alureGetSourceOffset</a></td><td class=SDescription>Gets the sample offset of the specified source. </td></tr></table></div></div><!--END_ND_SUMMARY--></div></div></div>
16 <div class="CGroup"><div class=CTopic><h3 class=CTitle><a name="Functions"></a>Functions</h3></div></div>
18 <div class="CFunction"><div class=CTopic><h3 class=CTitle><a name="alurePlaySourceStream"></a>alurePlaySourceStream</h3><div class=CBody><blockquote><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters colspan=4>ALURE_API ALboolean ALURE_APIENTRY alurePlaySourceStream(</td></tr><tr><td> </td><td class=PType nowrap>ALuint </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>source,</td></tr><tr><td> </td><td class=PType nowrap>alureStream </td><td class=PParameterPrefix nowrap>*</td><td class=PParameter nowrap width=100%>stream,</td></tr><tr><td> </td><td class=PType nowrap>ALsizei </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>numBufs,</td></tr><tr><td> </td><td class=PType nowrap>ALsizei </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>loopcount,</td></tr><tr><td> </td><td class=PType nowrap>void </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>(*eos_callback)(void *userdata, ALuint source),</td></tr><tr><td> </td><td class=PType nowrap>void </td><td class=PParameterPrefix nowrap>*</td><td class=PParameter nowrap width=100%>userdata</td></tr><tr><td class=PAfterParameters colspan=4>)</td></tr></table></td></tr></table></blockquote><p>Plays a stream asynchronously, using the specified source ID. A stream can only be played asynchronously if it is not already playing. It is important that the current context is NOT changed while a stream is playing, otherwise the asynchronous method used to play may start calling OpenAL with invalid IDs. Also note that checking the state of the specified source is not a good method to determine if a stream is playing. If an underrun occurs, the source will enter a stopped state until it is automatically restarted. Instead, set a flag using the callback to indicate the stream being stopped.</p><h4 class=CHeading>Parameters</h4><table border=0 cellspacing=0 cellpadding=0 class=CDescriptionList><tr><td class=CDLEntry>source</td><td class=CDLDescription>The source ID to play the stream with. Any buffers on the source will be unqueued. It is valid to set source properties not related to the buffer queue or playback state (ie. you may change the source’s position, pitch, gain, etc, but you must not stop the source or queue/unqueue buffers on it). To pause the source, call <a href="#alurePauseSource" class=LFunction id=link6 onMouseOver="ShowTip(event, 'tt4', 'link6')" onMouseOut="HideTip('tt4')">alurePauseSource</a>.</td></tr><tr><td class=CDLEntry>stream</td><td class=CDLDescription>The stream to play asynchronously. Any valid stream will work, although looping will only work if the stream can be rewound (eg. streams made with <a href="stream-cpp.html#alureCreateStreamFromCallback" class=LFunction id=link7 onMouseOver="ShowTip(event, 'tt6', 'link7')" onMouseOut="HideTip('tt6')">alureCreateStreamFromCallback</a> cannot loop, but will play for as long as the callback provides data).</td></tr><tr><td class=CDLEntry>numBufs</td><td class=CDLDescription>The number of buffers used to queue with the OpenAL source. Each buffer will be filled with the chunk length specified when the stream was created. This value must be at least 2.</td></tr><tr><td class=CDLEntry>loopcount</td><td class=CDLDescription>The number of times to loop the stream. When the stream reaches the end of processing, it will be rewound to continue buffering data. A value of -1 will cause the stream to loop indefinitely (or until <a href="#alureStopSource" class=LFunction id=link8 onMouseOver="ShowTip(event, 'tt3', 'link8')" onMouseOut="HideTip('tt3')">alureStopSource</a> is called).</td></tr><tr><td class=CDLEntry>eos_callback</td><td class=CDLDescription>This callback will be called when the stream reaches the end, no more loops are pending, and the source reaches a stopped state. It will also be called if an error occured and playback terminated.</td></tr><tr><td class=CDLEntry>userdata</td><td class=CDLDescription>An opaque user pointer passed to the callback.</td></tr></table><h4 class=CHeading>Returns</h4><p>AL_FALSE on error.</p><h4 class=CHeading>See Also</h4><p><a href="#alureStopSource" class=LFunction id=link9 onMouseOver="ShowTip(event, 'tt3', 'link9')" onMouseOut="HideTip('tt3')">alureStopSource</a>, <a href="#alurePauseSource" class=LFunction id=link10 onMouseOver="ShowTip(event, 'tt4', 'link10')" onMouseOut="HideTip('tt4')">alurePauseSource</a>, <a href="#alureGetSourceOffset" class=LFunction id=link11 onMouseOver="ShowTip(event, 'tt5', 'link11')" onMouseOut="HideTip('tt5')">alureGetSourceOffset</a></p></div></div></div>
20 <div class="CFunction"><div class=CTopic><h3 class=CTitle><a name="alurePlaySource"></a>alurePlaySource</h3><div class=CBody><blockquote><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters colspan=4>ALURE_API ALboolean ALURE_APIENTRY alurePlaySource(</td></tr><tr><td> </td><td class=PType nowrap>ALuint </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>source,</td></tr><tr><td> </td><td class=PType nowrap>void </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>(*callback)(void *userdata, ALuint source),</td></tr><tr><td> </td><td class=PType nowrap>void </td><td class=PParameterPrefix nowrap>*</td><td class=PParameter nowrap width=100%>userdata</td></tr><tr><td class=PAfterParameters colspan=4>)</td></tr></table></td></tr></table></blockquote><p>Plays the specified source ID and watches for it to stop. When a source enters the AL_STOPPED state, the specified callback is called to alert the application. As with <a href="#alurePlaySourceStream" class=LFunction id=link12 onMouseOver="ShowTip(event, 'tt1', 'link12')" onMouseOut="HideTip('tt1')">alurePlaySourceStream</a>, the current context must not be changed while the source is being watched (before the callback is called or <a href="#alureStopSource" class=LFunction id=link13 onMouseOver="ShowTip(event, 'tt3', 'link13')" onMouseOut="HideTip('tt3')">alureStopSource</a> is called). It also must not be deleted while being watched.</p><h4 class=CHeading>Parameters</h4><table border=0 cellspacing=0 cellpadding=0 class=CDescriptionList><tr><td class=CDLEntry>source</td><td class=CDLDescription>The source ID to play. As with <a href="#alurePlaySourceStream" class=LFunction id=link14 onMouseOver="ShowTip(event, 'tt1', 'link14')" onMouseOut="HideTip('tt1')">alurePlaySourceStream</a>, it is valid to set source properties not related to the playback state (ie. you may change a source’s position, pitch, gain, etc). Pausing a source and restarting a paused source is allowed, and the callback will still be invoked when the source naturally reaches an AL_STOPPED state.</td></tr><tr><td class=CDLEntry>callback</td><td class=CDLDescription>The callback to be called when the source stops.</td></tr><tr><td class=CDLEntry>userdata</td><td class=CDLDescription>An opaque user pointer passed to the callback.</td></tr></table><h4 class=CHeading>Returns</h4><p>AL_FALSE on error.</p><h4 class=CHeading>See Also</h4><p><a href="#alureStopSource" class=LFunction id=link15 onMouseOver="ShowTip(event, 'tt3', 'link15')" onMouseOut="HideTip('tt3')">alureStopSource</a></p></div></div></div>
22 <div class="CFunction"><div class=CTopic><h3 class=CTitle><a name="alureStopSource"></a>alureStopSource</h3><div class=CBody><blockquote><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters nowrap>ALURE_API ALboolean ALURE_APIENTRY alureStopSource(</td><td class=PType nowrap>ALuint </td><td class=PParameter nowrap>source,</td></tr><tr><td></td><td class=PType nowrap>ALboolean </td><td class=PParameter nowrap>run_callback</td><td class=PAfterParameters nowrap>)</td></tr></table></td></tr></table></blockquote><p>Stops the specified source ID, and any associated asynchronous stream. The previously specified callback will be invoked if ‘run_callback’ is not AL_FALSE. Sources that were not started with <a href="#alurePlaySourceStream" class=LFunction id=link16 onMouseOver="ShowTip(event, 'tt1', 'link16')" onMouseOut="HideTip('tt1')">alurePlaySourceStream</a> or <a href="#alurePlaySource" class=LFunction id=link17 onMouseOver="ShowTip(event, 'tt2', 'link17')" onMouseOut="HideTip('tt2')">alurePlaySource</a> will still be stopped, but will not have any callback called for them.</p><h4 class=CHeading>Returns</h4><p>AL_FALSE on error.</p><h4 class=CHeading>See Also</h4><p><a href="#alurePlaySourceStream" class=LFunction id=link18 onMouseOver="ShowTip(event, 'tt1', 'link18')" onMouseOut="HideTip('tt1')">alurePlaySourceStream</a>, <a href="#alurePlaySource" class=LFunction id=link19 onMouseOver="ShowTip(event, 'tt2', 'link19')" onMouseOut="HideTip('tt2')">alurePlaySource</a></p></div></div></div>
24 <div class="CFunction"><div class=CTopic><h3 class=CTitle><a name="alurePauseSource"></a>alurePauseSource</h3><div class=CBody><blockquote><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters nowrap>ALURE_API ALboolean ALURE_APIENTRY alurePauseSource(</td><td class=PType nowrap>ALuint </td><td class=PParameter nowrap>source,</td></tr><tr><td></td><td class=PType nowrap>ALboolean </td><td class=PParameter nowrap>resume</td><td class=PAfterParameters nowrap>)</td></tr></table></td></tr></table></blockquote><p>Pauses the specified source ID, and any associated asynchronous stream. This is needed to avoid potential race conditions with sources that are playing an asynchronous stream. Pass AL_TRUE to ‘resume’ to resume a paused stream.</p><p>Note that it is possible for the specified source to become stopped, and any associated stream to finish, before this function is called, causing the callback to be delayed until after the function returns when the async thread detects the stopped source.</p><h4 class=CHeading>Returns</h4><p>AL_FALSE on error.</p><h4 class=CHeading>See Also</h4><p><a href="#alurePlaySourceStream" class=LFunction id=link20 onMouseOver="ShowTip(event, 'tt1', 'link20')" onMouseOut="HideTip('tt1')">alurePlaySourceStream</a>, <a href="#alurePlaySource" class=LFunction id=link21 onMouseOver="ShowTip(event, 'tt2', 'link21')" onMouseOut="HideTip('tt2')">alurePlaySource</a></p></div></div></div>
26 <div class="CFunction"><div class=CTopic><h3 class=CTitle><a name="alureGetSourceOffset"></a>alureGetSourceOffset</h3><div class=CBody><blockquote><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters nowrap>ALURE_API alureUInt64 ALURE_APIENTRY alureGetSourceOffset(</td><td class=PType nowrap>ALuint </td><td class=PParameter nowrap>source</td><td class=PAfterParameters nowrap>)</td></tr></table></td></tr></table></blockquote><p>Gets the sample offset of the specified source. For sources started with <a href="#alurePlaySourceStream" class=LFunction id=link22 onMouseOver="ShowTip(event, 'tt1', 'link22')" onMouseOut="HideTip('tt1')">alurePlaySourceStream</a>, this will be the total samples played. The offset will loop back to 0 when the stream rewinds for any specified loopcount. For non-streamed sources, the function will behave as if retrieving the AL_SAMPLE_OFFSET source value.</p><h4 class=CHeading>Returns</h4><p>(alureUInt64)-1 on error.</p><h4 class=CHeading>See Also</h4><p><a href="#alurePlaySourceStream" class=LFunction id=link23 onMouseOver="ShowTip(event, 'tt1', 'link23')" onMouseOut="HideTip('tt1')">alurePlaySourceStream</a></p></div></div></div>
31 <div id=Footer><a href="http://www.naturaldocs.org">Generated by Natural Docs</a></div><!--Footer-->
34 <div id=Menu><div class=MTitle>ALURE<div class=MSubTitle>API Reference</div></div><div class=MEntry><div class=MFile><a href="alure-cpp.html">Main and Miscellanious</a></div></div><div class=MEntry><div class=MFile><a href="buffer-cpp.html">File Loading</a></div></div><div class=MEntry><div class=MFile><a href="stream-cpp.html">Streaming</a></div></div><div class=MEntry><div class=MFile><a href="istream-cpp.html">File I/<wbr>O</a></div></div><div class=MEntry><div class=MFile id=MSelected>Asynchronous Playback</div></div><div class=MEntry><div class=MGroup><a href="javascript:ToggleMenu('MGroupContent1')">Index</a><div class=MGroupContent id=MGroupContent1><div class=MEntry><div class=MIndex><a href="../index/General.html">Everything</a></div></div><div class=MEntry><div class=MIndex><a href="../index/Functions.html">Functions</a></div></div></div></div></div><script type="text/javascript"><!--
36 --></script><div id=MSearchPanel class=MSearchPanelInactive><input type=text id=MSearchField value=Search onFocus="searchPanel.OnSearchFieldFocus(true)" onBlur="searchPanel.OnSearchFieldFocus(false)" onKeyUp="searchPanel.OnSearchFieldChange()"><select id=MSearchType onFocus="searchPanel.OnSearchTypeFocus(true)" onBlur="searchPanel.OnSearchTypeFocus(false)" onChange="searchPanel.OnSearchTypeChange()"><option id=MSearchEverything selected value="General">Everything</option><option value="Functions">Functions</option></select></div></div><!--Menu-->
40 <!--START_ND_TOOLTIPS-->
41 <div class=CToolTip id="tt1"><div class=CFunction><blockquote><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters colspan=4>ALURE_API ALboolean ALURE_APIENTRY alurePlaySourceStream(</td></tr><tr><td> </td><td class=PType nowrap>ALuint </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>source,</td></tr><tr><td> </td><td class=PType nowrap>alureStream </td><td class=PParameterPrefix nowrap>*</td><td class=PParameter nowrap width=100%>stream,</td></tr><tr><td> </td><td class=PType nowrap>ALsizei </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>numBufs,</td></tr><tr><td> </td><td class=PType nowrap>ALsizei </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>loopcount,</td></tr><tr><td> </td><td class=PType nowrap>void </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>(*eos_callback)(void *userdata, ALuint source),</td></tr><tr><td> </td><td class=PType nowrap>void </td><td class=PParameterPrefix nowrap>*</td><td class=PParameter nowrap width=100%>userdata</td></tr><tr><td class=PAfterParameters colspan=4>)</td></tr></table></td></tr></table></blockquote>Plays a stream asynchronously, using the specified source ID. </div></div><div class=CToolTip id="tt2"><div class=CFunction><blockquote><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters colspan=4>ALURE_API ALboolean ALURE_APIENTRY alurePlaySource(</td></tr><tr><td> </td><td class=PType nowrap>ALuint </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>source,</td></tr><tr><td> </td><td class=PType nowrap>void </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>(*callback)(void *userdata, ALuint source),</td></tr><tr><td> </td><td class=PType nowrap>void </td><td class=PParameterPrefix nowrap>*</td><td class=PParameter nowrap width=100%>userdata</td></tr><tr><td class=PAfterParameters colspan=4>)</td></tr></table></td></tr></table></blockquote>Plays the specified source ID and watches for it to stop. </div></div><div class=CToolTip id="tt3"><div class=CFunction><blockquote><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters nowrap>ALURE_API ALboolean ALURE_APIENTRY alureStopSource(</td><td class=PType nowrap>ALuint </td><td class=PParameter nowrap>source,</td></tr><tr><td></td><td class=PType nowrap>ALboolean </td><td class=PParameter nowrap>run_callback</td><td class=PAfterParameters nowrap>)</td></tr></table></td></tr></table></blockquote>Stops the specified source ID, and any associated asynchronous stream. </div></div><div class=CToolTip id="tt4"><div class=CFunction><blockquote><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters nowrap>ALURE_API ALboolean ALURE_APIENTRY alurePauseSource(</td><td class=PType nowrap>ALuint </td><td class=PParameter nowrap>source,</td></tr><tr><td></td><td class=PType nowrap>ALboolean </td><td class=PParameter nowrap>resume</td><td class=PAfterParameters nowrap>)</td></tr></table></td></tr></table></blockquote>Pauses the specified source ID, and any associated asynchronous stream. </div></div><div class=CToolTip id="tt5"><div class=CFunction><blockquote><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters nowrap>ALURE_API alureUInt64 ALURE_APIENTRY alureGetSourceOffset(</td><td class=PType nowrap>ALuint </td><td class=PParameter nowrap>source</td><td class=PAfterParameters nowrap>)</td></tr></table></td></tr></table></blockquote>Gets the sample offset of the specified source. </div></div><div class=CToolTip id="tt6"><div class=CFunction><blockquote><table border=0 cellspacing=0 cellpadding=0 class=Prototype><tr><td><table border=0 cellspacing=0 cellpadding=0><tr><td class=PBeforeParameters colspan=4>ALURE_API alureStream* ALURE_APIENTRY alureCreateStreamFromCallback(</td></tr><tr><td> </td><td class=PType nowrap>ALuint </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>(*callback)(void *userdata, ALubyte *data, ALuint bytes),</td></tr><tr><td> </td><td class=PType nowrap>void </td><td class=PParameterPrefix nowrap>*</td><td class=PParameter nowrap width=100%>userdata,</td></tr><tr><td> </td><td class=PType nowrap>ALenum </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>format,</td></tr><tr><td> </td><td class=PType nowrap>ALuint </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>samplerate,</td></tr><tr><td> </td><td class=PType nowrap>ALsizei </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>chunkLength,</td></tr><tr><td> </td><td class=PType nowrap>ALsizei </td><td class=PParameterPrefix nowrap></td><td class=PParameter nowrap width=100%>numBufs,</td></tr><tr><td> </td><td class=PType nowrap>ALuint </td><td class=PParameterPrefix nowrap>*</td><td class=PParameter nowrap width=100%>bufs</td></tr><tr><td class=PAfterParameters colspan=4>)</td></tr></table></td></tr></table></blockquote>Creates a stream using the specified callback to retrieve data. </div></div><!--END_ND_TOOLTIPS-->
46 <div id=MSearchResultsWindow><iframe src="" frameborder=0 name=MSearchResults id=MSearchResults></iframe><a href="javascript:searchPanel.CloseResultsWindow()" id=MSearchResultsWindowClose>Close</a></div>
50 if (browserType) {if (browserVer) {document.write("</div>"); }document.write("</div>");}// --></script></body></html>