Mercurial > SDL_sound_CoreAudio

changeset 357:b3ac77d08e79

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
More documentation cleanups and enhancements.
author Ryan C. Gordon <icculus@icculus.org>
date Fri, 07 Jun 2002 23:09:24 +0000
parents ea5c61aeb891
children f11c10ffa31a
files SDL_sound.h
diffstat 1 files changed, 72 insertions(+), 15 deletions(-) [+]
line wrap: on
line diff
--- a/SDL_sound.h	Fri Jun 07 13:31:39 2002 +0000
+++ b/SDL_sound.h	Fri Jun 07 23:09:24 2002 +0000
@@ -91,18 +91,24 @@
  * \code
  * if (sample->flags & SOUND_SAMPLEFLAG_ERROR) { dosomething(); }
  * \endcode
+ *
+ * \sa Sound_SampleNew
+ * \sa Sound_SampleNewFromFile
+ * \sa Sound_SampleDecode
+ * \sa Sound_SampleDecodeAll
+ * \sa Sound_SampleSeek
  */
 typedef enum
 {
     SOUND_SAMPLEFLAG_NONE    = 0,       /**< No special attributes. */
 
         /* these are set at sample creation time... */
-    SOUND_SAMPLEFLAG_CANSEEK = 1,       /**< sample can seek to arbitrary points. */
+    SOUND_SAMPLEFLAG_CANSEEK = 1,       /**< Sample can seek to arbitrary points. */
 
         /* these are set during decoding... */
-    SOUND_SAMPLEFLAG_EOF     = 1 << 29, /**< end of input stream. */
-    SOUND_SAMPLEFLAG_ERROR   = 1 << 30, /**< unrecoverable error. */
-    SOUND_SAMPLEFLAG_EAGAIN  = 1 << 31  /**< function would block, or temp error. */
+    SOUND_SAMPLEFLAG_EOF     = 1 << 29, /**< End of input stream. */
+    SOUND_SAMPLEFLAG_ERROR   = 1 << 30, /**< Unrecoverable error. */
+    SOUND_SAMPLEFLAG_EAGAIN  = 1 << 31  /**< Function would block, or temp error. */
 } Sound_SampleFlags;
 
 
@@ -114,6 +120,9 @@
  *  (see AUDIO_U8 and friends in SDL_audio.h), number of channels, and sample
  *  rate. If you need more explanation than that, you should stop developing
  *  sound code right now.
+ *
+ * \sa Sound_SampleNew
+ * \sa Sound_SampleNewFromFile
  */
 typedef struct
 {
@@ -140,6 +149,7 @@
  * }
  * \endcode
  *
+ * \sa Sound_AvailableDecoders
  */
 typedef struct
 {
@@ -244,6 +254,9 @@
  * This function may be called safely at any time, even before Sound_Init().
  *
  * \param ver Sound_Version structure to fill with shared library's version.
+ *
+ * \sa Sound_Version
+ * \sa SOUND_VERSION
  */
 DECLSPEC void Sound_GetLinkedVersion(Sound_Version *ver);
 
@@ -258,8 +271,10 @@
  *  This is a safe behaviour, but it may not configure SDL to your liking by
  *  itself.
  *
- *  \return nonzero on success, zero on error. Specifics of the
- *           error can be gleaned from Sound_GetError().
+ * \return nonzero on success, zero on error. Specifics of the
+ *         error can be gleaned from Sound_GetError().
+ *
+ * \sa Sound_Quit
  */
 DECLSPEC int Sound_Init(void);
 
@@ -281,8 +296,10 @@
  *  for you!
  *
  *  \return nonzero on success, zero on error. Specifics of the error
- *           can be gleaned from Sound_GetError(). If failure, state of
- *           SDL_sound is undefined, and probably badly screwed up.
+ *          can be gleaned from Sound_GetError(). If failure, state of
+ *          SDL_sound is undefined, and probably badly screwed up.
+ *
+ * \sa Sound_Init
  */
 DECLSPEC int Sound_Quit(void);
 
@@ -315,7 +332,9 @@
  * The return values are pointers to static internal memory, and should
  *  be considered READ ONLY, and never freed.
  *
- *  \return READ ONLY Null-terminated array of READ ONLY structures.
+ * \return READ ONLY Null-terminated array of READ ONLY structures.
+ *
+ * \sa Sound_DecoderInfo
  */
 DECLSPEC const Sound_DecoderInfo **Sound_AvailableDecoders(void);
 
@@ -331,7 +350,9 @@
  *  overwrite the previous one associated with that thread. It is safe to call
  *  this function at anytime, even before Sound_Init().
  *
- *  \return READ ONLY string of last error message.
+ * \return READ ONLY string of last error message.
+ *
+ * \sa Sound_ClearError
  */
 DECLSPEC const char *Sound_GetError(void);
 
@@ -341,6 +362,8 @@
  * \brief Clear the current error message.
  *
  * The next call to Sound_GetError() after Sound_ClearError() will return NULL.
+ *
+ * \sa Sound_GetError
  */
 DECLSPEC void Sound_ClearError(void);
 
@@ -406,8 +429,16 @@
  *                   if you don't need conversion.
  *    \param bufferSize Size, in bytes, to allocate for the decoding buffer.
  *   \return Sound_Sample pointer, which is used as a handle to several other
- *            SDL_sound APIs. NULL on error. If error, use
- *            Sound_GetError() to see what went wrong.
+ *           SDL_sound APIs. NULL on error. If error, use
+ *           Sound_GetError() to see what went wrong.
+ *
+ * \sa Sound_NewSampleFromFile
+ * \sa Sound_SetBufferSize
+ * \sa Sound_Decode
+ * \sa Sound_DecodeAll
+ * \sa Sound_Seek
+ * \sa Sound_Rewind
+ * \sa Sound_FreeSample
  */
 DECLSPEC Sound_Sample *Sound_NewSample(SDL_RWops *rw, const char *ext,
                                               Sound_AudioInfo *desired,
@@ -429,8 +460,16 @@
  *                   if you don't need conversion.
  *    \param bufferSize size, in bytes, of initial read buffer.
  *   \return Sound_Sample pointer, which is used as a handle to several other
- *            SDL_sound APIs. NULL on error. If error, use
- *            Sound_GetError() to see what went wrong.
+ *           SDL_sound APIs. NULL on error. If error, use
+ *           Sound_GetError() to see what went wrong.
+ *
+ * \sa Sound_NewSample
+ * \sa Sound_SetBufferSize
+ * \sa Sound_Decode
+ * \sa Sound_DecodeAll
+ * \sa Sound_Seek
+ * \sa Sound_Rewind
+ * \sa Sound_FreeSample
  */
 DECLSPEC Sound_Sample *Sound_NewSampleFromFile(const char *filename,
                                                       Sound_AudioInfo *desired,
@@ -446,6 +485,9 @@
  *  certainly result in a crash if you attempt to keep using it.
  *
  *    \param sample The Sound_Sample to delete.
+ *
+ * \sa Sound_NewSample
+ * \sa Sound_NewSampleFromFile
  */
 DECLSPEC void Sound_FreeSample(Sound_Sample *sample);
 
@@ -471,6 +513,9 @@
  *    \param sample The Sound_Sample whose buffer to modify.
  *    \param new_size The desired size, in bytes, of the new buffer.
  *   \return non-zero if buffer size changed, zero on failure.
+ *
+ * \sa Sound_Decode
+ * \sa Sound_DecodeAll
  */
 DECLSPEC int Sound_SetBufferSize(Sound_Sample *sample, Uint32 new_size);
 
@@ -482,12 +527,17 @@
  * It will decode at most sample->buffer_size bytes into sample->buffer in the
  *  desired format, and 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.
+ *  sample->flags to determine if this was an end-of-stream or error condition.
  *
  *    \param sample Do more decoding to this Sound_Sample.
  *   \return 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).
+ *
+ * \sa Sound_DecodeAll
+ * \sa Sound_SetBufferSize
+ * \sa Sound_Seek
+ * \sa Sound_Rewind
  */
 DECLSPEC Uint32 Sound_Decode(Sound_Sample *sample);
 
@@ -521,6 +571,9 @@
  *   \return number of bytes decoded into sample->buffer. You should check
  *           sample->flags to see what the current state of the sample is
  *           (EOF, error, read again).
+ *
+ * \sa Sound_Decode
+ * \sa Sound_SetBufferSize
  */
 DECLSPEC Uint32 Sound_DecodeAll(Sound_Sample *sample);
 
@@ -553,6 +606,8 @@
  *    \param sample The Sound_Sample to rewind.
  *   \return nonzero on success, zero on error. Specifics of the
  *           error can be gleaned from Sound_GetError().
+ *
+ * \sa Sound_Seek
  */
 DECLSPEC int Sound_Rewind(Sound_Sample *sample);
 
@@ -596,6 +651,8 @@
  *    \param ms The new position, in milliseconds from start of sample.
  *   \return nonzero on success, zero on error. Specifics of the
  *           error can be gleaned from Sound_GetError().
+ *
+ * \sa Sound_Rewind
  */
 DECLSPEC int Sound_Seek(Sound_Sample *sample, Uint32 ms);