SDL_sound_CoreAudio: SDL_sound.h comparison

comparison SDL_sound.h @ 186:70561bf8d5fd

Updated and clarified some documentation.

author	Ryan C. Gordon <icculus@icculus.org>
date	Thu, 27 Dec 2001 23:05:32 +0000
parents	47cc2de2ae36
children	e2cb8bfe8051

comparison

equal deleted inserted replaced

-:6bb68b3bdcf1
+:70561bf8d5fd
 *  SDL_Init() before calling this. Sound_Init() 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.
 *
 *  @returns nonzero on success, zero on error. Specifics of the
-*           error can be gleaned from Sound_GetLastError().
+*           error can be gleaned from Sound_GetError().
 */
 extern DECLSPEC int Sound_Init(void);
 /**
 *
 * You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit()
 *  for you!
 *
 *  @returns nonzero on success, zero on error. Specifics of the error
-*           can be gleaned from Sound_GetLastError(). If failure, state of
+*           can be gleaned from Sound_GetError(). If failure, state of
 *           SDL_sound is undefined, and probably badly screwed up.
 */
 extern DECLSPEC int Sound_Quit(void);
 *  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.
 * If no decoders can handle the data, a NULL value is returned, and a human
-*  readable error message can be fetched from Sound_GetLastError().
+*  readable error message can be fetched from Sound_GetError().
 * 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.
 *  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 Sound_SetBufferSize() ...
 * The buffer size specified must be a multiple of the size of a single
-*  sample (not to be confused with a single Sound_Sample). So, if you want
+*  sample point. So, if you want 16-bit, stereo samples, then your sample
-*  16-bit, stereo samples, then your sample size is (2 channels * 16 bits),
+*  point size is (2 channels * 16 bits), or 32 bits per sample, which is four
-*  or 32 bits per sample, which is four bytes. In such a case, you could
+*  bytes. In such a case, you could specify 128 or 132 bytes for a buffer,
-*  specify 128 or 132 bytes for a buffer, but not 129, 130, or 131, although
+*  but not 129, 130, or 131 (although in reality, you'll want to specify a
-*  in reality, you'll want to specify a MUCH larger buffer.
+*  MUCH larger buffer).
 * When you are done with this Sound_Sample pointer, you can dispose of it
 *  via Sound_FreeSample().
 * 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 Sound_FreeSample()). If this function fails, it will dispose of the
 *               Can usually be NULL.
 *    @param desired Format to convert sound data into. Can usually be NULL,
 *                   if you don't need conversion.
 *   @returns Sound_Sample pointer, which is used as a handle to several other
 *            SDL_sound APIs. NULL on error. If error, use
-*            Sound_GetLastError() to see what went wrong.
+*            Sound_GetError() to see what went wrong.
 */
 extern DECLSPEC Sound_Sample *Sound_NewSample(SDL_RWops *rw, const char *ext,
 Sound_AudioInfo *desired,
 Uint32 bufferSize);
 *    @param desired Format to convert sound data into. Can usually be NULL,
 *                   if you don't need conversion.
 *    @param bufferSize size, in bytes, of initial read buffer.
 *   @returns Sound_Sample pointer, which is used as a handle to several other
 *            SDL_sound APIs. NULL on error. If error, use
-*            Sound_GetLastError() to see what went wrong.
+*            Sound_GetError() to see what went wrong.
 */
 extern DECLSPEC Sound_Sample *Sound_NewSampleFromFile(const char *filename,
 Sound_AudioInfo *desired,
 Uint32 bufferSize);
 *  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.
 *
 * The buffer size specified must be a multiple of the size of a single
-*  sample (not to be confused with a single Sound_Sample). So, if you want
+*  sample point. So, if you want 16-bit, stereo samples, then your sample
-*  16-bit, stereo samples, then your sample size is (2 channels * 16 bits),
+*  point size is (2 channels * 16 bits), or 32 bits per sample, which is four
-*  or 32 bits per sample, which is four bytes. In such a case, you could
+*  bytes. In such a case, you could specify 128 or 132 bytes for a buffer,
-*  specify 128 or 132 bytes for a buffer, but not 129, 130, or 131, although
+*  but not 129, 130, or 131 (although in reality, you'll want to specify a
-*  in reality, you'll want to specify a MUCH larger buffer.
+*  MUCH larger buffer).
 *
 *    @param sample The Sound_Sample whose buffer to modify.
 *    @param new_size The desired size, in bytes, of the new buffer.
 *  @returns non-zero if buffer size changed, zero on failure.
 */
 *  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.
 *
 *    @param sample Do more decoding to this Sound_Sample.
-*   @returns number of bytes decoded into sample->buffer. If it is less than
+*  @returns 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).
 */
 extern DECLSPEC Uint32 Sound_Decode(Sound_Sample *sample);

Mercurial > SDL_sound_CoreAudio

comparison SDL_sound.h @ 186:70561bf8d5fd