Mercurial > SDL_sound_CoreAudio

changeset 184:47cc2de2ae36

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Changed reference to "LICENSE" file to "COPYING".
author Ryan C. Gordon <icculus@icculus.org>
date Wed, 26 Dec 2001 10:40:25 +0000
parents 26996236d790
children 6bb68b3bdcf1
files CHANGELOG INSTALL Makefile.am SDL_sound.c SDL_sound.h SDL_sound_internal.h TODO decoders/aiff.c decoders/flac.c decoders/midi.c decoders/mod.c decoders/mp3.c decoders/ogg.c decoders/raw.c decoders/shn.c decoders/skeleton.c decoders/voc.c extra_rwops.c extra_rwops.h playsound/playsound.c
diffstat 20 files changed, 96 insertions(+), 58 deletions(-) [+]
line wrap: on
line diff
--- a/CHANGELOG	Wed Dec 26 10:39:16 2001 +0000
+++ b/CHANGELOG	Wed Dec 26 10:40:25 2001 +0000
@@ -2,6 +2,8 @@
  * CHANGELOG.
  */
 
+12262001 - Changed remaining references to the "LICENSE" file into "COPYING".
+           Work progresses on the ADPCM-compressed .wav decoder.
 12162001 - FLAC decoder now checks for the magic number unless the file
            extension is recognized. This was changed back because searching
            for metadata, while probably more effective, is VERY expensive (and
--- a/INSTALL	Wed Dec 26 10:39:16 2001 +0000
+++ b/INSTALL	Wed Dec 26 10:40:25 2001 +0000
@@ -3,7 +3,7 @@
 
 ALL PLATFORMS:
 
-Please understand your rights and mine: read the text file LICENSE in the root
+Please understand your rights and mine: read the text file COPYING in the root
 of the source tree. If you can't abide by it, delete this source tree now.
 
 The best documentation for the SDL_sound API is SDL_sound.h. It is VERY
--- a/Makefile.am	Wed Dec 26 10:39:16 2001 +0000
+++ b/Makefile.am	Wed Dec 26 10:40:25 2001 +0000
@@ -21,6 +21,6 @@
 
 EXTRA_DIST =	\
 	CREDITS \
-	LICENSE \
+	COPYING \
 	CHANGELOG
         
--- a/SDL_sound.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/SDL_sound.c	Wed Dec 26 10:40:25 2001 +0000
@@ -23,7 +23,7 @@
  *
  * Documentation is in SDL_sound.h ... It's verbose, honest.  :)
  *
- * 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)
  */
--- a/SDL_sound.h	Wed Dec 26 10:39:16 2001 +0000
+++ b/SDL_sound.h	Wed Dec 26 10:40:25 2001 +0000
@@ -18,6 +18,8 @@
  */
 
 /**
+ * @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
@@ -46,7 +48,7 @@
  *
  *   (...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)
  */
@@ -72,31 +74,41 @@
 #define SOUND_VER_PATCH 3
 
 
-/*
- * These are flags that are used in a Sound_Sample (below) to show various
- *  states.
+/**
+ * These are flags that are used in a Sound_Sample to show various 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_ERROR     = 1 << 30, /* unrecoverable error.            */
-    SOUND_SAMPLEFLAG_EAGAIN    = 1 << 31  /* would block, or temp error.     */
+    SOUND_SAMPLEFLAG_EOF       = 1 << 29,
+    SOUND_SAMPLEFLAG_ERROR     = 1 << 30,
+    SOUND_SAMPLEFLAG_EAGAIN    = 1 << 31
 } Sound_SampleFlags;
 
 
-/*
- * Basics of a decoded sample's data structure: data format (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.
+/**
+ * These are the basics of a decoded sample's data structure: data format
+ *  (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.
+ *
+ *   @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__
 {
@@ -106,40 +118,60 @@
 } 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 *description;    /* Human readable description of decoder. */
-    const char *author;         /* "Name Of Author <email@emailhost.dom>" */
-    const char *url;            /* URL specific to this decoder.          */
+    const char **extensions;
+    const char *description;    
+    const char *author;
+    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.                   */
-    const Sound_DecoderInfo *decoder;  /* Decoder used for this sample.  */
-    Sound_AudioInfo desired;     /* Desired audio format for conversion. */
-    Sound_AudioInfo actual;      /* Actual audio format of sample.       */
-    void *buffer;                /* Decoded sound data lands in here.    */
-    Uint32 buffer_size;          /* Current size of (buffer), in bytes.  */
-    Sound_SampleFlags flags;     /* Flags relating to this sample.       */
+    void *opaque;
+    const Sound_DecoderInfo *decoder;
+    Sound_AudioInfo desired;
+    Sound_AudioInfo actual;
+    void *buffer;
+    Uint32 buffer_size;
+    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__
 {
@@ -177,6 +209,8 @@
  *           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);
 
@@ -188,8 +222,8 @@
  *  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
- *          gleaned from Sound_GetLastError().
+ *  @returns nonzero on success, zero on error. Specifics of the
+ *           error can be gleaned from Sound_GetLastError().
  */
 extern DECLSPEC int Sound_Init(void);
 
@@ -207,9 +241,9 @@
  * 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
- *          gleaned from Sound_GetLastError(). If failure, state of SDL_sound
- *          is undefined, and probably badly screwed up.
+ *  @returns nonzero on success, zero on error. Specifics of the error
+ *           can be gleaned from Sound_GetLastError(). If failure, state of
+ *           SDL_sound is undefined, and probably badly screwed up.
  */
 extern DECLSPEC int Sound_Quit(void);
 
@@ -238,7 +272,7 @@
  * 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);
 
@@ -252,7 +286,7 @@
  *  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);
 
@@ -313,7 +347,7 @@
  *               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.
  */
@@ -333,7 +367,7 @@
  *    @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.
  */
@@ -371,7 +405,7 @@
  *
  *    @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);
 
@@ -384,7 +418,7 @@
  *  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).
  */
@@ -415,7 +449,7 @@
  *  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).
  */
--- a/SDL_sound_internal.h	Wed Dec 26 10:39:16 2001 +0000
+++ b/SDL_sound_internal.h	Wed Dec 26 10:40:25 2001 +0000
@@ -21,7 +21,7 @@
  * Internal function/structure declaration. Do NOT include in your
  *  application.
  *
- * 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)
  */
--- a/TODO	Wed Dec 26 10:39:16 2001 +0000
+++ b/TODO	Wed Dec 26 10:40:25 2001 +0000
@@ -17,6 +17,8 @@
 - Make some of the SNDDBG() strings more uniform.
 - SMPEG only works after calling SDL_OpenAudio(). Why?
 - Shrink buffer in Sound_DecodeAll to fit exact size of sample after decoding.
+- Make Sound_SetError() and Sound_GetError() use their own buffers, so they
+  don't piddle over SDL errors, and vice-versa.
 
 Decoders to implement:
 - .MID
--- a/decoders/aiff.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/decoders/aiff.c	Wed Dec 26 10:40:25 2001 +0000
@@ -36,7 +36,7 @@
  * standard; basically the parts of it that I can easily understand and test.
  * It's a start, though.
  *
- * Please see the file LICENSE in the source's root directory.
+ * Please see the file COPYING in the source's root directory.
  *
  *  This file was written by Torbjörn Andersson. (d91tan@Update.UU.SE)
  */
--- a/decoders/flac.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/decoders/flac.c	Wed Dec 26 10:40:25 2001 +0000
@@ -24,7 +24,7 @@
  *  Codec. It depends on libFLAC for decoding, which can be grabbed from:
  *  http://flac.sourceforge.net
  *
- * 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 Torbjörn Andersson. (d91tan@Update.UU.SE)
  */
--- a/decoders/midi.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/decoders/midi.c	Wed Dec 26 10:40:25 2001 +0000
@@ -38,7 +38,7 @@
  *  external decoder" thing so this version should either be scrapped or
  *  cannibalized for ideas. :-)
  *
- * 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 Torbjörn Andersson. (d91tan@Update.UU.SE)
  */
--- a/decoders/mod.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/decoders/mod.c	Wed Dec 26 10:40:25 2001 +0000
@@ -23,7 +23,7 @@
  * This driver handles anything our subset of MikMod handles. It is based on
  *  SDL_mixer's MikMod music player.
  *
- * 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 Torbjörn Andersson (d91tan@Update.UU.SE)
  */
--- a/decoders/mp3.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/decoders/mp3.c	Wed Dec 26 10:40:25 2001 +0000
@@ -24,7 +24,7 @@
  *  Napster.  :)  It depends on the SMPEG library for decoding, which can
  *  be grabbed from: http://www.lokigames.com/development/smpeg.php3
  *
- * 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)
  */
--- a/decoders/ogg.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/decoders/ogg.c	Wed Dec 26 10:40:25 2001 +0000
@@ -27,7 +27,7 @@
  *   Ogg Vorbis: http://www.xiph.org/ogg/vorbis/
  *   vorbisfile documentation: http://www.xiph.org/ogg/vorbis/doc/vorbisfile/
  *
- * 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)
  */
--- a/decoders/raw.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/decoders/raw.c	Wed Dec 26 10:40:25 2001 +0000
@@ -33,7 +33,7 @@
  *  there will be no conversion overhead, but these routines need to know how
  *  to treat the bits, since it's all random garbage otherwise.
  *
- * 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)
  */
--- a/decoders/shn.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/decoders/shn.c	Wed Dec 26 10:40:25 2001 +0000
@@ -36,7 +36,7 @@
  * The Shorten format was gleaned from the shorten codebase, by Tony
  *  Robinson and SoftSound Limited.
  *
- * 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)
  */
--- a/decoders/skeleton.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/decoders/skeleton.c	Wed Dec 26 10:40:25 2001 +0000
@@ -24,7 +24,7 @@
  *  have done a search and replace on "fmt" and "FMT" and changed this
  *  comment. This is the default comment in the skeleton decoder file...
  *
- * 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)
  */
--- a/decoders/voc.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/decoders/voc.c	Wed Dec 26 10:40:25 2001 +0000
@@ -32,7 +32,7 @@
  *    SDL_mixer: http://www.libsdl.org/projects/SDL_mixer/
  *    sox: http://www.freshmeat.net/projects/sox/
  *
- * 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)
  */
--- a/extra_rwops.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/extra_rwops.c	Wed Dec 26 10:40:25 2001 +0000
@@ -20,7 +20,7 @@
 /*
  * Some extra RWops that are needed or are just handy to have.
  *
- * 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)
  */
--- a/extra_rwops.h	Wed Dec 26 10:39:16 2001 +0000
+++ b/extra_rwops.h	Wed Dec 26 10:40:25 2001 +0000
@@ -20,7 +20,7 @@
 /*
  * Some extra RWops that are needed or are just handy to have.
  *
- * 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)
  */
--- a/playsound/playsound.c	Wed Dec 26 10:39:16 2001 +0000
+++ b/playsound/playsound.c	Wed Dec 26 10:40:25 2001 +0000
@@ -20,7 +20,7 @@
 /**
  * This is a quick and dirty test of SDL_sound.
  *
- * 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)
  */