[sdlsound] Unclear on SDL_Sound SOUND_SAMPLEFLAG_EAGAIN

[Ryan C. Gordon]

On 01/07/2014 12:01 AM, Greg Toombs wrote:
> Ok. So does that mean that, if a subsequent decode succeeds, it's safe
> to use the whole buffer? In other words, if I see EAGAIN, how do I
> interpret the returned byte count?

The returned byte count from Sound_Decode() is the number of decoded 
samples you have to work with. It's never safe to work with the whole 
buffer, it's only safe to work with the number of samples Sound_Decode() 
reported are in the buffer (which will actually _be_ the whole buffer in 
normal conditions).

If it returns less than sample->buffer_size, you're either at the end of 
the data or there was a problem...the EOF, ERROR, and EAGAIN flags tell 
you which happened: EOF for "no more data," ERROR for "no more data 
because something went wrong" and EAGAIN for "no more data, but try 
again and there might be."

EAGAIN isn't uncommon; most of the decoders will set it if they get a 
short read, because they aren't sure if they're at the end of the buffer 
or had a problem and the RWops is just handing over what it managed to 
get before reporting a problem. Often times the next attempt to decode 
will return zero bytes and an EOF flag.

It's worth noting that this is a lot of explaining for a flag you might 
not need. Here's what the playsound_simple.c demo app does:

     /* if there wasn't previously an error or EOF, read more. */
     if ( ((sample->flags & SOUND_SAMPLEFLAG_ERROR) == 0) &&
          ((sample->flags & SOUND_SAMPLEFLAG_EOF) == 0) )
     {
          data->decoded_bytes = Sound_Decode(sample);
          data->decoded_ptr = sample->buffer;
     } /* if */

It doesn't check EAGAIN...it either got enough data or it didn't, or 
there's definitely no more data coming or it needs to keep checking.

--ryan.