SDL_sound: The ModPlug patches and Sound_Rewind()...

[Ryan C. Gordon]

The ModPlug patches are in CVS. Thank you very much.

Now, about this Sound_Rewind() thing, here're my thoughts.

Externally, it's simple:

 /**
  * 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.
  *
  * If this function fails, the state of the sample is undefined, but it
  *  is still safe to call Sound_FreeSample() to dispose of it.
  *
  *    @param sample The Sound_Sample to rewind.
  *   @return nonzero on success, zero on error. Specifics of the
  *           error can be gleaned from Sound_GetError().
  */
 int Sound_Rewind(Sound_Sample *sample)


Internally, we'd add a new method to Sound_DecoderFunctions called
rewind:

int (*rewind)(Sound_Sample *sample);

Which tells a given decoder to reset itself to the beginning of the
stream. Nonzero on success, zero on failure. If it fails, SDL_sound will
call the decoder's close() method followed by its open() method to attempt
to force a rewind, and failing that will report the problem to the calling
application.

The purpose of the new rewind() method in the decoder 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.

That's my proposal. Thoughts, additions, flames, and donuts are welcome.

--ryan.