SDL_sound_CoreAudio: SDL_sound.h annotate

annotate SDL_sound.h @ 357:b3ac77d08e79

More documentation cleanups and enhancements.

author	Ryan C. Gordon <icculus@icculus.org>
date	Fri, 07 Jun 2002 23:09:24 +0000
parents	2740fad98dfe
children	8c8ecd1008c9

rev	line source
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	1 /** \file SDL_sound.h */
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	2
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	3 /*
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	4 * SDL_sound -- An abstract sound format decoding API.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	5 * Copyright (C) 2001 Ryan C. Gordon.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	6 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	7 * This library is free software; you can redistribute it and/or
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	8 * modify it under the terms of the GNU Lesser General Public
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	9 * License as published by the Free Software Foundation; either
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	10 * version 2.1 of the License, or (at your option) any later version.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	11 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	12 * This library is distributed in the hope that it will be useful,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	15 * Lesser General Public License for more details.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	16 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	17 * You should have received a copy of the GNU Lesser General Public
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	18 * License along with this library; if not, write to the Free Software
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	19 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	20 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	21
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	22 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	23 * \mainpage SDL_sound
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	24 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	25 * The latest version of SDL_sound can be found at:
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	26 * http://icculus.org/SDL_sound/
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	27 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	28 * The basic gist of SDL_sound is that you use an SDL_RWops to get sound data
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	29 * into this library, and SDL_sound will take that data, in one of several
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	30 * popular formats, and decode it into raw waveform data in the format of
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	31 * your choice. This gives you a nice abstraction for getting sound into your
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	32 * game or application; just feed it to SDL_sound, and it will handle
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	33 * decoding and converting, so you can just pass it to your SDL audio
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	34 * callback (or whatever). Since it gets data from an SDL_RWops, you can get
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	35 * the initial sound data from any number of sources: file, memory buffer,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	36 * network connection, etc.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	37 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	38 * As the name implies, this library depends on SDL: Simple Directmedia Layer,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	39 * which is a powerful, free, and cross-platform multimedia library. It can
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	40 * be found at http://www.libsdl.org/
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	41 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	42 * Support is in place or planned for the following sound formats:
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	43 * - .WAV (Microsoft WAVfile RIFF data, internal.)
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	44 * - .VOC (Creative Labs' Voice format, internal.)
305 c345a40a8a99 VERY preliminary work on Sound_Seek() API. Ryan C. Gordon <icculus@icculus.org> parents: 252 diff changeset	45 * - .MP3 (MPEG-1 Layer 3 support, via the SMPEG and mpglib libraries.)
252 c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	46 * - .MID (MIDI music converted to Waveform data, internal.)
c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	47 * - .MOD (MOD files, via MikMod and ModPlug.)
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	48 * - .OGG (Ogg files, via Ogg Vorbis libraries.)
252 c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	49 * - .SHN (Shorten files, internal.)
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	50 * - .RAW (Raw sound data in any format, internal.)
252 c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	51 * - .AU (Sun's Audio format, internal.)
c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	52 * - .AIFF (Audio Interchange format, internal.)
c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	53 * - .FLAC (Lossless audio compression, via libFLAC.)
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	54 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	55 * (...and more to come...)
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	56 *
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	57 * Please see the file COPYING in the source's root directory.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	58 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	59 * \author Ryan C. Gordon (icculus@clutteredmind.org)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	60 * \author many others, please see CREDITS in the source's root directory.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	61 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	62
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	63 #ifndef _INCLUDE_SDL_SOUND_H_
508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	64 #define _INCLUDE_SDL_SOUND_H_
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	65
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	66 #include "SDL.h"
19 734e5d75acec Now includes SDL_endian.h ... Ryan C. Gordon <icculus@icculus.org> parents: 15 diff changeset	67 #include "SDL_endian.h"
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	68
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	69 #ifdef __cplusplus
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	70 extern "C" {
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	71 #endif
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	72
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	73 /* !!! FIXME: Use SDLCALL instead. */
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	74 #ifndef DOXYGEN_SHOULD_IGNORE_THIS
130 ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	75 #ifdef SDL_SOUND_DLL_EXPORTS
ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	76 # undef DECLSPEC
ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	77 # define DECLSPEC __declspec(dllexport)
ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	78 #endif
ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	79
29 0e27c909c952 Upped version to 0.1.1 Ryan C. Gordon <icculus@icculus.org> parents: 19 diff changeset	80 #define SOUND_VER_MAJOR 0
0e27c909c952 Upped version to 0.1.1 Ryan C. Gordon <icculus@icculus.org> parents: 19 diff changeset	81 #define SOUND_VER_MINOR 1
252 c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	82 #define SOUND_VER_PATCH 5
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	83 #endif
29 0e27c909c952 Upped version to 0.1.1 Ryan C. Gordon <icculus@icculus.org> parents: 19 diff changeset	84
0e27c909c952 Upped version to 0.1.1 Ryan C. Gordon <icculus@icculus.org> parents: 19 diff changeset	85
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	86 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	87 * \enum Sound_SampleFlags
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	88 * \brief Flags that are used in a Sound_Sample to show various states.
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	89 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	90 * To use:
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	91 * \code
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	92 * if (sample->flags & SOUND_SAMPLEFLAG_ERROR) { dosomething(); }
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	93 * \endcode
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	94 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	95 * \sa Sound_SampleNew
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	96 * \sa Sound_SampleNewFromFile
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	97 * \sa Sound_SampleDecode
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	98 * \sa Sound_SampleDecodeAll
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	99 * \sa Sound_SampleSeek
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	100 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	101 typedef enum
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	102 {
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	103 SOUND_SAMPLEFLAG_NONE = 0, /*< No special attributes. /
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	104
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	105 /* these are set at sample creation time... */
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	106 SOUND_SAMPLEFLAG_CANSEEK = 1, /*< Sample can seek to arbitrary points. /
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	107
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	108 /* these are set during decoding... */
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	109 SOUND_SAMPLEFLAG_EOF = 1 << 29, /*< End of input stream. /
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	110 SOUND_SAMPLEFLAG_ERROR = 1 << 30, /*< Unrecoverable error. /
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	111 SOUND_SAMPLEFLAG_EAGAIN = 1 << 31 /*< Function would block, or temp error. /
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	112 } Sound_SampleFlags;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	113
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	114
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	115 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	116 * \struct Sound_AudioInfo
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	117 * \brief Information about an existing sample's format.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	118 *
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	119 * These are the basics of a decoded sample's data structure: data format
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	120 * (see AUDIO_U8 and friends in SDL_audio.h), number of channels, and sample
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	121 * rate. If you need more explanation than that, you should stop developing
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	122 * sound code right now.
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	123 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	124 * \sa Sound_SampleNew
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	125 * \sa Sound_SampleNewFromFile
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	126 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	127 typedef struct
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	128 {
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	129 Uint16 format; /*< Equivalent of SDL_AudioSpec.format. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	130 Uint8 channels; /*< Number of sound channels. 1 == mono, 2 == stereo. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	131 Uint32 rate; /*< Sample rate; frequency of sample points per second. /
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	132 } Sound_AudioInfo;
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	133
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	134
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	135 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	136 * \struct Sound_DecoderInfo
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	137 * \brief Information about available soudn decoders.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	138 *
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	139 * Each decoder sets up one of these structs, which can be retrieved via
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	140 * the Sound_AvailableDecoders() function. EVERY FIELD IN THIS IS READ-ONLY.
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	141 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	142 * The extensions field is a NULL-terminated list of ASCIZ strings. You
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	143 * should read it like this:
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	144 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	145 * \code
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	146 * const char **ext;
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	147 * for (ext = info->extensions; *ext != NULL; ext++) {
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	148 * printf(" File extension \"%s\"\n", *ext);
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	149 * }
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	150 * \endcode
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	151 *
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	152 * \sa Sound_AvailableDecoders
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	153 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	154 typedef struct
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	155 {
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	156 const char extensions; /< File extensions, list ends with NULL. */
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	157 const char description; /< Human readable description of decoder. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	158 const char author; /< "Name Of Author \<email@emailhost.dom\>" /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	159 const char url; /< URL specific to this decoder. /
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	160 } Sound_DecoderInfo;
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	161
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	162
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	163
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	164 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	165 * \struct Sound_Sample
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	166 * \brief Represents sound data in the process of being decoded.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	167 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	168 * The Sound_Sample structure is the heart of SDL_sound. This holds
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	169 * information about a source of sound data as it is being decoded.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	170 * EVERY FIELD IN THIS IS READ-ONLY. Please use the API functions to
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	171 * change them.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	172 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	173 typedef struct
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	174 {
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	175 void opaque; /< Internal use only. Don't touch. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	176 const Sound_DecoderInfo decoder; /< Decoder used for this sample. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	177 Sound_AudioInfo desired; /*< Desired audio format for conversion. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	178 Sound_AudioInfo actual; /*< Actual audio format of sample. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	179 void buffer; /< Decoded sound data lands in here. /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	180 Uint32 buffer_size; /*< Current size of (buffer), in bytes (Uint8). /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	181 Sound_SampleFlags flags; /*< Flags relating to this sample. /
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	182 } Sound_Sample;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	183
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	184
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	185 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	186 * \struct Sound_Version
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	187 * \brief Information the version of SDL_sound in use.
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	188 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	189 * Represents the library's version as three levels: major revision
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	190 * (increments with massive changes, additions, and enhancements),
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	191 * minor revision (increments with backwards-compatible changes to the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	192 * major revision), and patchlevel (increments with fixes to the minor
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	193 * revision).
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	194 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	195 * \sa SOUND_VERSION
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	196 * \sa Sound_GetLinkedVersion
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	197 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	198 typedef struct
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	199 {
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	200 int major; /*< major revision /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	201 int minor; /*< minor revision /
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	202 int patch; /*< patchlevel /
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	203 } Sound_Version;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	204
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	205
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	206 /* functions and macros... */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	207
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	208 /**
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	209 * \def SOUND_VERSION(x)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	210 * \brief Macro to determine SDL_sound version program was compiled against.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	211 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	212 * This macro fills in a Sound_Version structure with the version of the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	213 * library you compiled against. This is determined by what header the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	214 * compiler uses. Note that if you dynamically linked the library, you might
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	215 * have a slightly newer or older version at runtime. That version can be
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	216 * determined with Sound_GetLinkedVersion(), which, unlike SOUND_VERSION,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	217 * is not a macro.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	218 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	219 * \param x A pointer to a Sound_Version struct to initialize.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	220 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	221 * \sa Sound_Version
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	222 * \sa Sound_GetLinkedVersion
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	223 */
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	224 #define SOUND_VERSION(x) \
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	225 { \
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	226 (x)->major = SOUND_VER_MAJOR; \
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	227 (x)->minor = SOUND_VER_MINOR; \
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	228 (x)->patch = SOUND_VER_PATCH; \
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	229 }
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	230
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	231
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	232 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	233 * \fn void Sound_GetLinkedVersion(Sound_Version *ver)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	234 * \brief Get the version of SDL_sound that is linked against your program.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	235 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	236 * If you are using a shared library (DLL) version of SDL_sound, then it is
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	237 * possible that it will be different than the version you compiled against.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	238 *
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	239 * This is a real function; the macro SOUND_VERSION tells you what version
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	240 * of SDL_sound you compiled against:
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	241 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	242 * \code
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	243 * Sound_Version compiled;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	244 * Sound_Version linked;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	245 *
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	246 * SOUND_VERSION(&compiled);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	247 * Sound_GetLinkedVersion(&linked);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	248 * printf("We compiled against SDL_sound version %d.%d.%d ...\n",
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	249 * compiled.major, compiled.minor, compiled.patch);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	250 * printf("But we linked against SDL_sound version %d.%d.%d.\n",
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	251 * linked.major, linked.minor, linked.patch);
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	252 * \endcode
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	253 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	254 * This function may be called safely at any time, even before Sound_Init().
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	255 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	256 * \param ver Sound_Version structure to fill with shared library's version.
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	257 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	258 * \sa Sound_Version
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	259 * \sa SOUND_VERSION
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	260 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	261 DECLSPEC void Sound_GetLinkedVersion(Sound_Version *ver);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	262
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	263
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	264 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	265 * \fn Sound_Init(void)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	266 * \brief Initialize SDL_sound.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	267 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	268 * This must be called before any other SDL_sound function (except perhaps
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	269 * Sound_GetLinkedVersion()). You should call SDL_Init() before calling this.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	270 * Sound_Init() will attempt to call SDL_Init(SDL_INIT_AUDIO), just in case.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	271 * This is a safe behaviour, but it may not configure SDL to your liking by
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	272 * itself.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	273 *
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	274 * \return nonzero on success, zero on error. Specifics of the
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	275 * error can be gleaned from Sound_GetError().
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	276 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	277 * \sa Sound_Quit
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	278 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	279 DECLSPEC int Sound_Init(void);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	280
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	281
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	282 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	283 * \fn Sound_Quit(void)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	284 * \brief Shutdown SDL_sound.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	285 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	286 * This closes any SDL_RWops that were being used as sound sources, and frees
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	287 * any resources in use by SDL_sound.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	288 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	289 * All Sound_Sample pointers you had prior to this call are INVALIDATED.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	290 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	291 * Once successfully deinitialized, Sound_Init() can be called again to
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	292 * restart the subsystem. All default API states are restored at this
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	293 * point.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	294 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	295 * You should call this BEFORE SDL_Quit(). This will NOT call SDL_Quit()
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	296 * for you!
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	297 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	298 * \return nonzero on success, zero on error. Specifics of the error
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	299 * can be gleaned from Sound_GetError(). If failure, state of
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	300 * SDL_sound is undefined, and probably badly screwed up.
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	301 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	302 * \sa Sound_Init
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	303 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	304 DECLSPEC int Sound_Quit(void);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	305
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	306
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	307 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	308 * \fn const Sound_DecoderInfo **Sound_AvailableDecoders(void)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	309 * \brief Get a list of sound formats supported by this version of SDL_sound.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	310 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	311 * This is for informational purposes only. Note that the extension listed is
11 5ff1dce70aec Typos. Ryan C. Gordon <icculus@icculus.org> parents: 3 diff changeset	312 * merely convention: if we list "MP3", you can open an MPEG-1 Layer 3 audio
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	313 * file with an extension of "XYZ", if you like. The file extensions are
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	314 * informational, and only required as a hint to choosing the correct
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	315 * decoder, since the sound data may not be coming from a file at all, thanks
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	316 * to the abstraction that an SDL_RWops provides.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	317 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	318 * The returned value is an array of pointers to Sound_DecoderInfo structures,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	319 * with a NULL entry to signify the end of the list:
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	320 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	321 * \code
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	322 * Sound_DecoderInfo **i;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	323 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	324 * for (i = Sound_AvailableDecoders(); *i != NULL; i++)
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	325 * {
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	326 * printf("Supported sound format: [%s], which is [%s].\n",
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	327 * i->extension, i->description);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	328 * // ...and other fields...
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	329 * }
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	330 * \endcode
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	331 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	332 * The return values are pointers to static internal memory, and should
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	333 * be considered READ ONLY, and never freed.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	334 *
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	335 * \return READ ONLY Null-terminated array of READ ONLY structures.
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	336 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	337 * \sa Sound_DecoderInfo
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	338 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	339 DECLSPEC const Sound_DecoderInfo **Sound_AvailableDecoders(void);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	340
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	341
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	342 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	343 * \fn const char *Sound_GetError(void)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	344 * \brief Get the last SDL_sound error message as a null-terminated string.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	345 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	346 * This will be NULL if there's been no error since the last call to this
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	347 * function. The pointer returned by this call points to an internal buffer,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	348 * and should not be deallocated. Each thread has a unique error state
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	349 * associated with it, but each time a new error message is set, it will
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	350 * overwrite the previous one associated with that thread. It is safe to call
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	351 * this function at anytime, even before Sound_Init().
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	352 *
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	353 * \return READ ONLY string of last error message.
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	354 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	355 * \sa Sound_ClearError
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	356 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	357 DECLSPEC const char *Sound_GetError(void);
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	358
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	359
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	360 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	361 * \fn void Sound_ClearError(void)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	362 * \brief Clear the current error message.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	363 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	364 * The next call to Sound_GetError() after Sound_ClearError() will return NULL.
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	365 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	366 * \sa Sound_GetError
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	367 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	368 DECLSPEC void Sound_ClearError(void);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	369
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	370
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	371 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	372 * \fn Sound_Sample Sound_NewSample(SDL_RWops rw, const char ext, Sound_AudioInfo desired, Uint32 bufferSize)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	373 * \brief Start decoding a new sound sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	374 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	375 * The data is read via an SDL_RWops structure (see SDL_rwops.h in the SDL
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	376 * include directory), so it may be coming from memory, disk, network stream,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	377 * etc. The (ext) parameter is merely a hint to determining the correct
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	378 * decoder; if you specify, for example, "mp3" for an extension, and one of
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	379 * the decoders lists that as a handled extension, then that decoder is given
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	380 * first shot at trying to claim the data for decoding. If none of the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	381 * extensions match (or the extension is NULL), then every decoder examines
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	382 * the data to determine if it can handle it, until one accepts it. In such a
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	383 * case your SDL_RWops will need to be capable of rewinding to the start of
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	384 * the stream.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	385 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	386 * If no decoders can handle the data, a NULL value is returned, and a human
186 70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	387 * readable error message can be fetched from Sound_GetError().
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	388 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	389 * Optionally, a desired audio format can be specified. If the incoming data
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	390 * is in a different format, SDL_sound will convert it to the desired format
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	391 * on the fly. Note that this can be an expensive operation, so it may be
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	392 * wise to convert data before you need to play it back, if possible, or
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	393 * make sure your data is initially in the format that you need it in.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	394 * If you don't want to convert the data, you can specify NULL for a desired
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	395 * format. The incoming format of the data, preconversion, can be found
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	396 * in the Sound_Sample structure.
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	397 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	398 * Note that the raw sound data "decoder" needs you to specify both the
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	399 * extension "RAW" and a "desired" format, or it will refuse to handle
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	400 * the data. This is to prevent it from catching all formats unsupported
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	401 * by the other decoders.
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	402 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	403 * Finally, specify an initial buffer size; this is the number of bytes that
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	404 * will be allocated to store each read from the sound buffer. The more you
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	405 * can safely allocate, the more decoding can be done in one block, but the
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	406 * more resources you have to use up, and the longer each decoding call will
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	407 * take. Note that different data formats require more or less space to
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	408 * store. This buffer can be resized via Sound_SetBufferSize() ...
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	409 *
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	410 * The buffer size specified must be a multiple of the size of a single
186 70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	411 * sample point. So, if you want 16-bit, stereo samples, then your sample
70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	412 * point size is (2 channels * 16 bits), or 32 bits per sample, which is four
70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	413 * bytes. In such a case, you could specify 128 or 132 bytes for a buffer,
70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	414 * but not 129, 130, or 131 (although in reality, you'll want to specify a
70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	415 * MUCH larger buffer).
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	416 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	417 * When you are done with this Sound_Sample pointer, you can dispose of it
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	418 * via Sound_FreeSample().
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	419 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	420 * You do not have to keep a reference to (rw) around. If this function
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	421 * suceeds, it stores (rw) internally (and disposes of it during the call
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	422 * to Sound_FreeSample()). If this function fails, it will dispose of the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	423 * SDL_RWops for you.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	424 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	425 * \param rw SDL_RWops with sound data.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	426 * \param ext File extension normally associated with a data format.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	427 * Can usually be NULL.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	428 * \param desired Format to convert sound data into. Can usually be NULL,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	429 * if you don't need conversion.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	430 * \param bufferSize Size, in bytes, to allocate for the decoding buffer.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	431 * \return Sound_Sample pointer, which is used as a handle to several other
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	432 * SDL_sound APIs. NULL on error. If error, use
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	433 * Sound_GetError() to see what went wrong.
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	434 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	435 * \sa Sound_NewSampleFromFile
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	436 * \sa Sound_SetBufferSize
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	437 * \sa Sound_Decode
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	438 * \sa Sound_DecodeAll
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	439 * \sa Sound_Seek
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	440 * \sa Sound_Rewind
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	441 * \sa Sound_FreeSample
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	442 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	443 DECLSPEC Sound_Sample Sound_NewSample(SDL_RWops rw, const char *ext,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	444 Sound_AudioInfo *desired,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	445 Uint32 bufferSize);
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	446
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	447 /**
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	448 * \fn Sound_Sample Sound_NewSampleFromFile(const char filename, Sound_AudioInfo *desired, Uint32 bufferSize)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	449 * \brief Start decoding a new sound sample from a file on disk.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	450 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	451 * This is identical to Sound_NewSample(), but it creates an SDL_RWops for you
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	452 * from the file located in (filename). Note that (filename) is specified in
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	453 * platform-dependent notation. ("C:\\music\\mysong.mp3" on windows, and
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	454 * "/home/icculus/music/mysong.mp3" or whatever on Unix, etc.)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	455 * Sound_NewSample()'s "ext" parameter is gleaned from the contents of
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	456 * (filename).
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	457 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	458 * \param filename file containing sound data.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	459 * \param desired Format to convert sound data into. Can usually be NULL,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	460 * if you don't need conversion.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	461 * \param bufferSize size, in bytes, of initial read buffer.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	462 * \return Sound_Sample pointer, which is used as a handle to several other
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	463 * SDL_sound APIs. NULL on error. If error, use
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	464 * Sound_GetError() to see what went wrong.
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	465 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	466 * \sa Sound_NewSample
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	467 * \sa Sound_SetBufferSize
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	468 * \sa Sound_Decode
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	469 * \sa Sound_DecodeAll
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	470 * \sa Sound_Seek
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	471 * \sa Sound_Rewind
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	472 * \sa Sound_FreeSample
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	473 */
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	474 DECLSPEC Sound_Sample Sound_NewSampleFromFile(const char filename,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	475 Sound_AudioInfo *desired,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	476 Uint32 bufferSize);
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	477
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	478 /**
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	479 * \fn void Sound_FreeSample(Sound_Sample *sample)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	480 * \brief Dispose of a Dispose of a Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	481 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	482 * This will also close/dispose of the SDL_RWops that was used at creation
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	483 * time, so there's no need to keep a reference to that around.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	484 * The Sound_Sample pointer is invalid after this call, and will almost
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	485 * certainly result in a crash if you attempt to keep using it.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	486 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	487 * \param sample The Sound_Sample to delete.
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	488 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	489 * \sa Sound_NewSample
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	490 * \sa Sound_NewSampleFromFile
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	491 */
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	492 DECLSPEC void Sound_FreeSample(Sound_Sample *sample);
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	493
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	494
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	495 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	496 * \fn int Sound_SetBufferSize(Sound_Sample *sample, Uint32 new_size)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	497 * \brief Change the current buffer size for a sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	498 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	499 * If the buffer size could be changed, then the sample->buffer and
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	500 * sample->buffer_size fields will reflect that. If they could not be
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	501 * changed, then your original sample state is preserved. If the buffer is
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	502 * shrinking, the data at the end of buffer is truncated. If the buffer is
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	503 * growing, the contents of the new space at the end is undefined until you
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	504 * decode more into it or initialize it yourself.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	505 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	506 * The buffer size specified must be a multiple of the size of a single
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	507 * sample point. So, if you want 16-bit, stereo samples, then your sample
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	508 * point size is (2 channels * 16 bits), or 32 bits per sample, which is four
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	509 * bytes. In such a case, you could specify 128 or 132 bytes for a buffer,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	510 * but not 129, 130, or 131 (although in reality, you'll want to specify a
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	511 * MUCH larger buffer).
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	512 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	513 * \param sample The Sound_Sample whose buffer to modify.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	514 * \param new_size The desired size, in bytes, of the new buffer.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	515 * \return non-zero if buffer size changed, zero on failure.
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	516 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	517 * \sa Sound_Decode
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	518 * \sa Sound_DecodeAll
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	519 */
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	520 DECLSPEC int Sound_SetBufferSize(Sound_Sample *sample, Uint32 new_size);
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	521
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	522
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	523 /**
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	524 * \fn Uint32 Sound_Decode(Sound_Sample *sample)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	525 * \brief Decode more of the sound data in a Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	526 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	527 * It will decode at most sample->buffer_size bytes into sample->buffer in the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	528 * desired format, and return the number of decoded bytes.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	529 * If sample->buffer_size bytes could not be decoded, then please refer to
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	530 * sample->flags to determine if this was an end-of-stream or error condition.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	531 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	532 * \param sample Do more decoding to this Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	533 * \return number of bytes decoded into sample->buffer. If it is less than
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	534 * sample->buffer_size, then you should check sample->flags to see
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	535 * what the current state of the sample is (EOF, error, read again).
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	536 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	537 * \sa Sound_DecodeAll
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	538 * \sa Sound_SetBufferSize
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	539 * \sa Sound_Seek
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	540 * \sa Sound_Rewind
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	541 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	542 DECLSPEC Uint32 Sound_Decode(Sound_Sample *sample);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	543
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	544
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	545 /**
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	546 * \fn Uint32 Sound_DecodeAll(Sound_Sample *sample)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	547 * \brief Decode the remainder of the sound data in a Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	548 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	549 * This will dynamically allocate memory for the ENTIRE remaining sample.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	550 * sample->buffer_size and sample->buffer will be updated to reflect the
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	551 * new buffer. Please refer to sample->flags to determine if the decoding
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	552 * finished due to an End-of-stream or error condition.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	553 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	554 * Be aware that sound data can take a large amount of memory, and that
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	555 * this function may block for quite awhile while processing. Also note
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	556 * that a streaming source (for example, from a SDL_RWops that is getting
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	557 * fed from an Internet radio feed that doesn't end) may fill all available
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	558 * memory before giving up...be sure to use this on finite sound sources
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	559 * only!
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	560 *
170 e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	561 * When decoding the sample in its entirety, the work is done one buffer at a
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	562 * time. That is, sound is decoded in sample->buffer_size blocks, and
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	563 * appended to a continually-growing buffer until the decoding completes.
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	564 * That means that this function will need enough RAM to hold approximately
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	565 * sample->buffer_size bytes plus the complete decoded sample at most. The
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	566 * larger your buffer size, the less overhead this function needs, but beware
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	567 * the possibility of paging to disk. Best to make this user-configurable if
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	568 * the sample isn't specific and small.
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	569 *
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	570 * \param sample Do all decoding for this Sound_Sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	571 * \return number of bytes decoded into sample->buffer. You should check
170 e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	572 * sample->flags to see what the current state of the sample is
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	573 * (EOF, error, read again).
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	574 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	575 * \sa Sound_Decode
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	576 * \sa Sound_SetBufferSize
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	577 */
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	578 DECLSPEC Uint32 Sound_DecodeAll(Sound_Sample *sample);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	579
223 249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	580
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	581 /**
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	582 * \fn int Sound_Rewind(Sound_Sample *sample)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	583 * \brief Rewind a sample to the start.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	584 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	585 * Restart a sample at the start of its waveform data, as if newly
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	586 * created with Sound_NewSample(). If successful, the next call to
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	587 * Sound_Decode[All]() will give audio data from the earliest point
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	588 * in the stream.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	589 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	590 * Beware that this function will fail if the SDL_RWops that feeds the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	591 * decoder can not be rewound via it's seek method, but this can
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	592 * theoretically be avoided by wrapping it in some sort of buffering
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	593 * SDL_RWops.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	594 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	595 * This function should ONLY fail if the RWops is not seekable, or
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	596 * SDL_sound is not initialized. Both can be controlled by the application,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	597 * and thus, it is up to the developer's paranoia to dictate whether this
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	598 * function's return value need be checked at all.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	599 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	600 * If this function fails, the state of the sample is undefined, but it
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	601 * is still safe to call Sound_FreeSample() to dispose of it.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	602 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	603 * On success, ERROR, EOF, and EAGAIN are cleared from sample->flags. The
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	604 * ERROR flag is set on error.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	605 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	606 * \param sample The Sound_Sample to rewind.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	607 * \return nonzero on success, zero on error. Specifics of the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	608 * error can be gleaned from Sound_GetError().
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	609 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	610 * \sa Sound_Seek
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	611 */
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	612 DECLSPEC int Sound_Rewind(Sound_Sample *sample);
223 249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	613
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	614
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	615 /**
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	616 * \fn int Sound_Seek(Sound_Sample *sample, Uint32 ms)
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	617 * \brief Seek to a different point in a sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	618 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	619 * Reposition a sample's stream. If successful, the next call to
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	620 * Sound_Decode[All]() will give audio data from the offset you
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	621 * specified.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	622 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	623 * The offset is specified in milliseconds from the start of the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	624 * sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	625 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	626 * Beware that this function can fail for several reasons. If the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	627 * SDL_RWops that feeds the decoder can not seek, this call will almost
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	628 * certainly fail, but this can theoretically be avoided by wrapping it
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	629 * in some sort of buffering SDL_RWops. Some decoders can never seek,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	630 * others can only seek with certain files. The decoders will set a flag
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	631 * in the sample at creation time to help you determine this.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	632 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	633 * You should check sample->flags & SOUND_SAMPLEFLAG_CANSEEK
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	634 * before attempting. Sound_Seek() reports failure immediately if this
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	635 * flag isn't set. This function can still fail for other reasons if the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	636 * flag is set.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	637 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	638 * This function can be emulated in the application with Sound_Rewind()
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	639 * and predecoding a specific amount of the sample, but this can be
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	640 * extremely inefficient. Sound_Seek() accelerates the seek on a
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	641 * with decoder-specific code.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	642 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	643 * If this function fails, the sample should continue to function as if
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	644 * this call was never made. If there was an unrecoverable error,
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	645 * sample->flags & SOUND_SAMPLEFLAG_ERROR will be set, which you regular
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	646 * decoding loop can pick up.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	647 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	648 * On success, ERROR, EOF, and EAGAIN are cleared from sample->flags.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	649 *
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	650 * \param sample The Sound_Sample to seek.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	651 * \param ms The new position, in milliseconds from start of sample.
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	652 * \return nonzero on success, zero on error. Specifics of the
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	653 * error can be gleaned from Sound_GetError().
357 b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	654 *
b3ac77d08e79 More documentation cleanups and enhancements. Ryan C. Gordon <icculus@icculus.org> parents: 353 diff changeset	655 * \sa Sound_Rewind
353 2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	656 */
2740fad98dfe Tweaked and enhanced for Doxygen support. Ryan C. Gordon <icculus@icculus.org> parents: 305 diff changeset	657 DECLSPEC int Sound_Seek(Sound_Sample *sample, Uint32 ms);
305 c345a40a8a99 VERY preliminary work on Sound_Seek() API. Ryan C. Gordon <icculus@icculus.org> parents: 252 diff changeset	658
c345a40a8a99 VERY preliminary work on Sound_Seek() API. Ryan C. Gordon <icculus@icculus.org> parents: 252 diff changeset	659
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	660 #ifdef __cplusplus
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	661 }
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	662 #endif
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	663
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	664 #endif /* !defined _INCLUDE_SDL_SOUND_H_ */
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	665
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	666 /* end of SDL_sound.h ... */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	667

Mercurial > SDL_sound_CoreAudio

annotate SDL_sound.h @ 357:b3ac77d08e79