SDL_sound_CoreAudio: SDL_sound.h comparison

comparison SDL_sound.h @ 184:47cc2de2ae36

Changed reference to "LICENSE" file to "COPYING".

author	Ryan C. Gordon <icculus@icculus.org>
date	Wed, 26 Dec 2001 10:40:25 +0000
parents	e91fb8d5bd62
children	70561bf8d5fd

comparison

equal deleted inserted replaced

-:26996236d790
+:47cc2de2ae36
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
 /**
+* @overview
+*
 * The basic gist of SDL_sound is that you use an SDL_RWops to get sound data
 *  into this library, and SDL_sound will take that data, in one of several
 *  popular formats, and decode it into raw waveform data in the format of
 *  your choice. This gives you a nice abstraction for getting sound into your
 *  game or application; just feed it to SDL_sound, and it will handle
 *   - .AU
 *   - .AIFF
 *
 *   (...and more to come...)
 *
-* Please see the file LICENSE in the source's root directory.
+* Please see the file COPYING in the source's root directory.
 *
 *  This file written by Ryan C. Gordon. (icculus@clutteredmind.org)
 */
 #ifndef _INCLUDE_SDL_SOUND_H_
 #define SOUND_VER_MAJOR 0
 #define SOUND_VER_MINOR 1
 #define SOUND_VER_PATCH 3
-/*
+/**
-* These are flags that are used in a Sound_Sample (below) to show various
+* These are flags that are used in a Sound_Sample to show various states.
-*  states.
 *
 *   To use: "if (sample->flags & SOUND_SAMPLEFLAG_ERROR) { dosomething(); }"
+*
+*  @param SOUND_SAMPLEFLAG_NONE     null flag.
+*  @param SOUND_SAMPLEFLAG_NEEDSEEK SDL_RWops must be able to seek.
+*  @param SOUND_SAMPLEFLAG_EOF      end of input stream.
+*  @param SOUND_SAMPLEFLAG_ERROR    unrecoverable error.
+*  @param SOUND_SAMPLEFLAG_EAGAIN   function would block, or temp error.
 */
 typedef enum __SOUND_SAMPLEFLAGS__
 {
-SOUND_SAMPLEFLAG_NONE      = 0,       /* Null flag.                      */
+SOUND_SAMPLEFLAG_NONE      = 0,
 /* these are set at sample creation time... */
-SOUND_SAMPLEFLAG_NEEDSEEK  = 1,       /* SDL_RWops must be able to seek. */
+SOUND_SAMPLEFLAG_NEEDSEEK  = 1,
 /* these are set during decoding... */
-SOUND_SAMPLEFLAG_EOF       = 1 << 29, /* end of input stream.            */
+SOUND_SAMPLEFLAG_EOF       = 1 << 29,
-SOUND_SAMPLEFLAG_ERROR     = 1 << 30, /* unrecoverable error.            */
+SOUND_SAMPLEFLAG_ERROR     = 1 << 30,
-SOUND_SAMPLEFLAG_EAGAIN    = 1 << 31  /* would block, or temp error.     */
+SOUND_SAMPLEFLAG_EAGAIN    = 1 << 31
 } Sound_SampleFlags;
-/*
+/**
-* Basics of a decoded sample's data structure: data format (see AUDIO_U8 and
+* These are the basics of a decoded sample's data structure: data format
-*  friends in SDL_audio.h), number of channels, and sample rate. If you need
+*  (see AUDIO_U8 and friends in SDL_audio.h), number of channels, and sample
-*  more explanation than that, you should stop developing sound code right
+*  rate. If you need more explanation than that, you should stop developing
-*  now.
+*  sound code right now.
+*
+*   @param format Equivalent of SDL_AudioSpec.format.
+*   @param channels Number of sound channels. 1 == mono, 2 == stereo.
+*   @param rate Sample rate; frequency of sample points per second (44100,
+*                22050, 8000, etc.)
 */
 typedef struct __SOUND_AUDIOINFO__
 {
 Uint16 format;
 Uint8 channels;
 Uint32 rate;
 } Sound_AudioInfo;
-/*
+/**
 * Each decoder sets up one of these structs, which can be retrieved via
 *  the Sound_AvailableDecoders() function. EVERY FIELD IN THIS IS READ-ONLY.
+*
+*   @param extensions File extensions, list ends with NULL. Read it like this:
+*           const char **ext;
+*           for (ext = info->extensions; *ext != NULL; ext++)
+*                printf("   File extension \"%s\"\n", *ext);
+*   @param description Human readable description of decoder.
+*   @param author "Name Of Author <email@emailhost.dom>"
+*   @param url URL specific to this decoder.
 */
 typedef struct __SOUND_DECODERINFO__
 {
-const char **extensions;    /* File extensions, list ends with NULL.  */
+const char **extensions;
-const char *description;    /* Human readable description of decoder. */
+const char *description;
-const char *author;         /* "Name Of Author <email@emailhost.dom>" */
+const char *author;
-const char *url;            /* URL specific to this decoder.          */
+const char *url;
 } Sound_DecoderInfo;
-/*
+/**
 * The Sound_Sample structure is the heart of SDL_sound. This holds
 *  information about a source of sound data as it is being decoded.
 *  EVERY FIELD IN THIS IS READ-ONLY. Please use the API functions to
 *  change them.
+*
+*  @param opaque Internal use only. Don't touch.
+*  @param decoder Decoder used for this sample.
+*  @param desired Desired audio format for conversion.
+*  @param actual Actual audio format of sample.
+*  @param buffer Decoded sound data lands in here.
+*  @param buffer_size Current size of (buffer), in bytes (Uint8).
+*  @param flags Flags relating to this sample.
 */
 typedef struct __SOUND_SAMPLE__
 {
-void *opaque;                /* Internal use only.                   */
+void *opaque;
-const Sound_DecoderInfo *decoder;  /* Decoder used for this sample.  */
+const Sound_DecoderInfo *decoder;
-Sound_AudioInfo desired;     /* Desired audio format for conversion. */
+Sound_AudioInfo desired;
-Sound_AudioInfo actual;      /* Actual audio format of sample.       */
+Sound_AudioInfo actual;
-void *buffer;                /* Decoded sound data lands in here.    */
+void *buffer;
-Uint32 buffer_size;          /* Current size of (buffer), in bytes.  */
+Uint32 buffer_size;
-Sound_SampleFlags flags;     /* Flags relating to this sample.       */
+Sound_SampleFlags flags;
 } Sound_Sample;
-/*
+/**
-* Just what it says: a x.y.z style version number...
+* Just what it says: a major.minor.patch style version number...
+*
+*   @param major The major version number.
+*   @param minor The minor version number.
+*   @param patch The patchlevel version number.
 */
 typedef struct __SOUND_VERSION__
 {
 int major;
 int minor;
 *           compiled.major, compiled.minor, compiled.patch);
 * printf("But we linked against SDL_sound version %d.%d.%d.\n",
 *           linked.major, linked.minor, linked.patch);
 *
 * 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.
 */
 extern DECLSPEC void Sound_GetLinkedVersion(Sound_Version *ver);
 /**
 *  function (except perhaps Sound_GetLinkedVersion()). You should call
 *  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.
 *
-*  @return nonzero on success, zero on error. Specifics of the error can be
+*  @returns nonzero on success, zero on error. Specifics of the
-*          gleaned from Sound_GetLastError().
+*           error can be gleaned from Sound_GetLastError().
 */
 extern DECLSPEC int Sound_Init(void);
 /**
 *  point.
 *
 * You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit()
 *  for you!
 *
-*  @return nonzero on success, zero on error. Specifics of the error can be
+*  @returns nonzero on success, zero on error. Specifics of the error
-*          gleaned from Sound_GetLastError(). If failure, state of SDL_sound
+*           can be gleaned from Sound_GetLastError(). If failure, state of
-*          is undefined, and probably badly screwed up.
+*           SDL_sound is undefined, and probably badly screwed up.
 */
 extern DECLSPEC int Sound_Quit(void);
 /**
 * }
 *
 * 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.
+*  @returns READ ONLY Null-terminated array of READ ONLY structures.
 */
 extern DECLSPEC const Sound_DecoderInfo **Sound_AvailableDecoders(void);
 /**
 *  Each thread has a unique error state associated with it, but each time
 *  a new error message is set, it will 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.
+*  @returns READ ONLY string of last error message.
 */
 extern DECLSPEC const char *Sound_GetError(void);
 /**
 *    @param rw SDL_RWops with sound data.
 *    @param ext File extension normally associated with a data format.
 *               Can usually be NULL.
 *    @param desired Format to convert sound data into. Can usually be NULL,
 *                   if you don't need conversion.
-*   @return Sound_Sample pointer, which is used as a handle to several other
+*   @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.
 */
 extern DECLSPEC Sound_Sample *Sound_NewSample(SDL_RWops *rw, const char *ext,
 Sound_AudioInfo *desired,
 *
 *    @param filename file containing sound data.
 *    @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.
-*   @return Sound_Sample pointer, which is used as a handle to several other
+*   @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.
 */
 extern DECLSPEC Sound_Sample *Sound_NewSampleFromFile(const char *filename,
 Sound_AudioInfo *desired,
 *  specify 128 or 132 bytes for a buffer, but not 129, 130, or 131, although
 *  in reality, you'll want to specify a MUCH larger buffer.
 *
 *    @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.
+*  @returns non-zero if buffer size changed, zero on failure.
 */
 extern DECLSPEC int Sound_SetBufferSize(Sound_Sample *sample, Uint32 new_size);
 /**
 *  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.
-*   @return 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);
 *  larger your buffer size, the less overhead this function needs, but beware
 *  the possibility of paging to disk. Best to make this user-configurable if
 *  the sample isn't specific and small.
 *
 *    @param sample Do all decoding for this Sound_Sample.
-*   @return number of bytes decoded into sample->buffer. You should check
+*   @returns 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).
 */
 extern DECLSPEC Uint32 Sound_DecodeAll(Sound_Sample *sample);

Mercurial > SDL_sound_CoreAudio

comparison SDL_sound.h @ 184:47cc2de2ae36