# HG changeset patch
# User Ryan C. Gordon <icculus@icculus.org>
# Date 1011300946 0
# Node ID 249186e314312447ac994d7c193de1cb7a008b63
# Parent  d6b24586822ae90d87c7508e46f60b95ed9abd9e
Sound_Rewind() support code.

diff -r d6b24586822a -r 249186e31431 SDL_sound.c
--- a/SDL_sound.c	Thu Jan 17 20:54:46 2002 +0000
+++ b/SDL_sound.c	Thu Jan 17 20:55:46 2002 +0000
@@ -782,5 +782,25 @@
     return(newBufSize);
 } /* Sound_DecodeAll */
 
+
+int Sound_Rewind(Sound_Sample *sample)
+{
+    Sound_SampleInternal *internal;
+    BAIL_IF_MACRO(!initialized, ERR_NOT_INITIALIZED, 0);
+
+    internal = (Sound_SampleInternal *) sample->opaque;
+    if (!internal->funcs->rewind(sample))
+    {
+        sample->flags |= SOUND_SAMPLEFLAG_ERROR;
+        return(0);
+    } /* if */
+
+    sample->flags &= !SOUND_SAMPLEFLAG_EAGAIN;
+    sample->flags &= !SOUND_SAMPLEFLAG_ERROR;
+    sample->flags &= !SOUND_SAMPLEFLAG_EOF;
+    return(1);
+} /* Sound_Rewind */
+
+
 /* end of SDL_sound.c ... */
 
diff -r d6b24586822a -r 249186e31431 SDL_sound.h
--- a/SDL_sound.h	Thu Jan 17 20:54:46 2002 +0000
+++ b/SDL_sound.h	Thu Jan 17 20:55:46 2002 +0000
@@ -455,6 +455,36 @@
  */
 extern DECLSPEC Uint32 Sound_DecodeAll(Sound_Sample *sample);
 
+
+ /**
+  * Restart a sample at the start of its waveform data, as if newly
+  *  created with Sound_NewSample(). If successful, the next call to
+  *  Sound_Decode[All]() will give audio data from the earliest point
+  *  in the stream.
+  *
+  * 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.
+  *
+  * 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.
+  *
+  * If this function fails, the state of the sample is undefined, but it
+  *  is still safe to call Sound_FreeSample() to dispose of it.
+  *
+  * On success, ERROR, EOF, and EAGAIN are cleared from sample->flags. The
+  *  ERROR flag is set on error.
+  *
+  *    @param sample The Sound_Sample to rewind.
+  *   @return nonzero on success, zero on error. Specifics of the
+  *           error can be gleaned from Sound_GetError().
+  */
+extern DECLSPEC int Sound_Rewind(Sound_Sample *sample);
+
+
 #ifdef __cplusplus
 }
 #endif
diff -r d6b24586822a -r 249186e31431 SDL_sound_internal.h
--- a/SDL_sound_internal.h	Thu Jan 17 20:54:46 2002 +0000
+++ b/SDL_sound_internal.h	Thu Jan 17 20:55:46 2002 +0000
@@ -155,6 +155,24 @@
          *  method.
          */
     Uint32 (*read)(Sound_Sample *sample);
+
+        /*
+         * Reset the decoding to the beginning of the stream. Nonzero on
+         *  success, zero on failure.
+         *  
+         * The purpose of this method is to allow for higher efficiency than
+         *  an application could get by just recreating the sample externally;
+         *  not only do they not have to reopen the RWops, reallocate buffers,
+         *  and potentially pass the data through several rejecting decoders,
+         *  but certain decoders will not have to recreate their existing
+         *  state (search for metadata, etc) since they already know they
+         *  have a valid audio stream with a given set of characteristics.
+         *
+         * The decoder is responsible for calling seek() on the associated
+         *  SDL_RWops. A failing call to seek() should be the ONLY reason that
+         *  this method should ever fail!
+         */
+    int (*rewind)(Sound_Sample *sample);
 } Sound_DecoderFunctions;