# HG changeset patch # User Ryan C. Gordon # Date 1009363225 0 # Node ID 47cc2de2ae36031ab800615a4a6f78c642a8d753 # Parent 26996236d79062338e6477ae71f361e21ee58394 Changed reference to "LICENSE" file to "COPYING". diff -r 26996236d790 -r 47cc2de2ae36 CHANGELOG --- 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 diff -r 26996236d790 -r 47cc2de2ae36 INSTALL --- 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 diff -r 26996236d790 -r 47cc2de2ae36 Makefile.am --- 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 diff -r 26996236d790 -r 47cc2de2ae36 SDL_sound.c --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 SDL_sound.h --- 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 " + * @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 " */ - 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). */ diff -r 26996236d790 -r 47cc2de2ae36 SDL_sound_internal.h --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 TODO --- 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 diff -r 26996236d790 -r 47cc2de2ae36 decoders/aiff.c --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 decoders/flac.c --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 decoders/midi.c --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 decoders/mod.c --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 decoders/mp3.c --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 decoders/ogg.c --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 decoders/raw.c --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 decoders/shn.c --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 decoders/skeleton.c --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 decoders/voc.c --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 extra_rwops.c --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 extra_rwops.h --- 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) */ diff -r 26996236d790 -r 47cc2de2ae36 playsound/playsound.c --- 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) */