SDL_sound_CoreAudio: SDL_sound.h annotate

annotate SDL_sound.h @ 302:414cfef0978e

Cleaned up archive support. Fixes segfault when playing non-archived sounds with latest PhysicsFS.

author	Ryan C. Gordon <icculus@icculus.org>
date	Mon, 08 Apr 2002 13:31:15 +0000
parents	c54eae85f5f1
children	c345a40a8a99

rev	line source
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	1 /*
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	2 * SDL_sound -- An abstract sound format decoding API.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	3 * Copyright (C) 2001 Ryan C. Gordon.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	4 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	5 * This library is free software; you can redistribute it and/or
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	6 * modify it under the terms of the GNU Lesser General Public
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	7 * License as published by the Free Software Foundation; either
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	8 * 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	9 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	10 * This library is distributed in the hope that it will be useful,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	13 * Lesser General Public License for more details.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	14 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	15 * You should have received a copy of the GNU Lesser General Public
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	16 * License along with this library; if not, write to the Free Software
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	18 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	19
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	20 /**
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	21 * @overview
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	22 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	23 * 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	24 * 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	25 * 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	26 * 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	27 * 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	28 * 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	29 * 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	30 * the initial sound data from any number of sources: file, memory buffer,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	31 * network connection, etc.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	32 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	33 * As the name implies, this library depends on SDL: Simple Directmedia Layer,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	34 * which is a powerful, free, and cross-platform multimedia library. It can
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	35 * be found at http://www.libsdl.org/
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	36 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	37 * 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	38 * - .WAV (Microsoft WAVfile RIFF data, internal.)
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	39 * - .VOC (Creative Labs' Voice format, internal.)
11 5ff1dce70aec Typos. Ryan C. Gordon <icculus@icculus.org> parents: 3 diff changeset	40 * - .MP3 (MPEG-1 Layer 3 support, via the SMPEG library.)
252 c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	41 * - .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	42 * - .MOD (MOD files, via MikMod and ModPlug.)
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	43 * - .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	44 * - .SHN (Shorten files, internal.)
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	45 * - .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	46 * - .AU (Sun's Audio format, internal.)
c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	47 * - .AIFF (Audio Interchange format, internal.)
c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	48 * - .FLAC (Lossless audio compression, via libFLAC.)
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	49 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	50 * (...and more to come...)
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	51 *
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	52 * Please see the file COPYING in the source's root directory.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	53 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	54 * This file written by Ryan C. Gordon. (icculus@clutteredmind.org)
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	55 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	56
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	57 #ifndef _INCLUDE_SDL_SOUND_H_
508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	58 #define _INCLUDE_SDL_SOUND_H_
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	59
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	60 #include "SDL.h"
19 734e5d75acec Now includes SDL_endian.h ... Ryan C. Gordon <icculus@icculus.org> parents: 15 diff changeset	61 #include "SDL_endian.h"
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	62
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	63 #ifdef __cplusplus
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	64 extern "C" {
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	65 #endif
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	66
130 ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	67 #ifdef SDL_SOUND_DLL_EXPORTS
ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	68 # undef DECLSPEC
ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	69 # define DECLSPEC __declspec(dllexport)
ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	70 #endif
ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	71
ac49f81e42d6 Win32 fix, upped version to 0.1.3. Ryan C. Gordon <icculus@icculus.org> parents: 44 diff changeset	72
29 0e27c909c952 Upped version to 0.1.1 Ryan C. Gordon <icculus@icculus.org> parents: 19 diff changeset	73 #define SOUND_VER_MAJOR 0
0e27c909c952 Upped version to 0.1.1 Ryan C. Gordon <icculus@icculus.org> parents: 19 diff changeset	74 #define SOUND_VER_MINOR 1
252 c54eae85f5f1 Upped version to 0.1.5. Ryan C. Gordon <icculus@icculus.org> parents: 223 diff changeset	75 #define SOUND_VER_PATCH 5
29 0e27c909c952 Upped version to 0.1.1 Ryan C. Gordon <icculus@icculus.org> parents: 19 diff changeset	76
0e27c909c952 Upped version to 0.1.1 Ryan C. Gordon <icculus@icculus.org> parents: 19 diff changeset	77
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	78 /**
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	79 * These are flags that are used in a Sound_Sample to show various states.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	80 *
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	81 * To use: "if (sample->flags & SOUND_SAMPLEFLAG_ERROR) { dosomething(); }"
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	82 *
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	83 * @param SOUND_SAMPLEFLAG_NONE null flag.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	84 * @param SOUND_SAMPLEFLAG_NEEDSEEK SDL_RWops must be able to seek.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	85 * @param SOUND_SAMPLEFLAG_EOF end of input stream.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	86 * @param SOUND_SAMPLEFLAG_ERROR unrecoverable error.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	87 * @param SOUND_SAMPLEFLAG_EAGAIN function would block, or temp error.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	88 */
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	89 typedef enum __SOUND_SAMPLEFLAGS__
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	90 {
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	91 SOUND_SAMPLEFLAG_NONE = 0,
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	92
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	93 /* these are set at sample creation time... */
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	94 SOUND_SAMPLEFLAG_NEEDSEEK = 1,
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	95
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	96 /* these are set during decoding... */
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	97 SOUND_SAMPLEFLAG_EOF = 1 << 29,
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	98 SOUND_SAMPLEFLAG_ERROR = 1 << 30,
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	99 SOUND_SAMPLEFLAG_EAGAIN = 1 << 31
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	100 } Sound_SampleFlags;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	101
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	102
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	103 /**
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	104 * 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	105 * (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	106 * 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	107 * sound code right now.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	108 *
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	109 * @param format Equivalent of SDL_AudioSpec.format.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	110 * @param channels Number of sound channels. 1 == mono, 2 == stereo.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	111 * @param rate Sample rate; frequency of sample points per second (44100,
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	112 * 22050, 8000, etc.)
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	113 */
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	114 typedef struct __SOUND_AUDIOINFO__
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	115 {
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	116 Uint16 format;
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	117 Uint8 channels;
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	118 Uint32 rate;
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	119 } Sound_AudioInfo;
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	120
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	121
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	122 /**
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	123 * 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	124 * 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	125 *
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	126 * @param extensions File extensions, list ends with NULL. Read it like this:
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	127 * const char **ext;
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	128 * for (ext = info->extensions; *ext != NULL; ext++)
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	129 * printf(" File extension \"%s\"\n", *ext);
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	130 * @param description Human readable description of decoder.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	131 * @param author "Name Of Author <email@emailhost.dom>"
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	132 * @param url URL specific to this decoder.
3 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 typedef struct __SOUND_DECODERINFO__
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	135 {
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	136 const char **extensions;
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	137 const char *description;
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	138 const char *author;
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	139 const char *url;
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	140 } Sound_DecoderInfo;
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	141
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	142
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	143
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	144 /**
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	145 * The Sound_Sample structure is the heart of SDL_sound. This holds
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	146 * information about a source of sound data as it is being decoded.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	147 * 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	148 * change them.
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	149 *
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	150 * @param opaque Internal use only. Don't touch.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	151 * @param decoder Decoder used for this sample.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	152 * @param desired Desired audio format for conversion.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	153 * @param actual Actual audio format of sample.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	154 * @param buffer Decoded sound data lands in here.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	155 * @param buffer_size Current size of (buffer), in bytes (Uint8).
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	156 * @param flags Flags relating to this sample.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	157 */
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	158 typedef struct __SOUND_SAMPLE__
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	159 {
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	160 void *opaque;
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	161 const Sound_DecoderInfo *decoder;
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	162 Sound_AudioInfo desired;
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	163 Sound_AudioInfo actual;
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	164 void *buffer;
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	165 Uint32 buffer_size;
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	166 Sound_SampleFlags flags;
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	167 } Sound_Sample;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	168
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	169
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	170 /**
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	171 * Just what it says: a major.minor.patch style version number...
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	172 *
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	173 * @param major The major version number.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	174 * @param minor The minor version number.
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	175 * @param patch The patchlevel version number.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	176 */
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	177 typedef struct __SOUND_VERSION__
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	178 {
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	179 int major;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	180 int minor;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	181 int patch;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	182 } Sound_Version;
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
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	185
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	186 /* functions and macros... */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	187
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	188 #define SOUND_VERSION(x) { \
508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	189 (x)->major = SOUND_VER_MAJOR; \
508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	190 (x)->minor = SOUND_VER_MINOR; \
508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	191 (x)->patch = SOUND_VER_PATCH; \
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	192 }
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	193
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	194 /**
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	195 * Get the version of SDL_sound that is linked against your program. If you
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	196 * are using a shared library (DLL) version of SDL_sound, then it is possible
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	197 * that it will be different than the version you compiled against.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	198 *
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	199 * 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	200 * of SDL_sound you compiled against:
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	201 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	202 * Sound_Version compiled;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	203 * Sound_Version linked;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	204 *
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	205 * SOUND_VERSION(&compiled);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	206 * Sound_GetLinkedVersion(&linked);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	207 * printf("We compiled against SDL_sound version %d.%d.%d ...\n",
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	208 * compiled.major, compiled.minor, compiled.patch);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	209 * printf("But we linked against SDL_sound version %d.%d.%d.\n",
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	210 * linked.major, linked.minor, linked.patch);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	211 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	212 * 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	213 *
47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	214 * @param ver Sound_Version structure to fill with shared library's version.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	215 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	216 extern DECLSPEC void Sound_GetLinkedVersion(Sound_Version *ver);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	217
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	218
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	219 /**
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	220 * Initialize SDL_sound. This must be called before any other SDL_sound
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	221 * function (except perhaps Sound_GetLinkedVersion()). You should call
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	222 * SDL_Init() before calling this. Sound_Init() will attempt to call
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	223 * SDL_Init(SDL_INIT_AUDIO), just in case. This is a safe behaviour, but it
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	224 * may not configure SDL to your liking by itself.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	225 *
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	226 * @returns nonzero on success, zero on error. Specifics of the
186 70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	227 * error can be gleaned from Sound_GetError().
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	228 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	229 extern DECLSPEC int Sound_Init(void);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	230
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 /**
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	233 * Shutdown SDL_sound. This closes any SDL_RWops that were being used as
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	234 * sound sources, and frees any resources in use by SDL_sound.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	235 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	236 * All Sound_Sample pointers you had prior to this call are INVALIDATED.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	237 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	238 * 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	239 * restart the subsystem. All default API states are restored at this
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	240 * point.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	241 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	242 * 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	243 * for you!
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	244 *
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	245 * @returns nonzero on success, zero on error. Specifics of the error
186 70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	246 * can be gleaned from Sound_GetError(). If failure, state of
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	247 * SDL_sound is undefined, and probably badly screwed up.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	248 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	249 extern DECLSPEC int Sound_Quit(void);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	250
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	251
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	252 /**
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	253 * Get a list of sound formats supported by this implementation of SDL_sound.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	254 * 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	255 * 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	256 * 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	257 * informational, and only required as a hint to choosing the correct
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	258 * 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	259 * to the abstraction that an SDL_RWops provides.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	260 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	261 * The returned value is an array of pointers to Sound_DecoderInfo structures,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	262 * with a NULL entry to signify the end of the list:
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 * Sound_DecoderInfo **i;
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	265 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	266 * for (i = Sound_AvailableDecoders(); *i != NULL; i++)
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	267 * {
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	268 * printf("Supported sound format: [%s], which is [%s].\n",
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	269 * i->extension, i->description);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	270 * // ...and other fields...
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	271 * }
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	272 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	273 * The return values are pointers to static internal memory, and should
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	274 * be considered READ ONLY, and never freed.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	275 *
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	276 * @returns READ ONLY Null-terminated array of READ ONLY structures.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	277 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	278 extern DECLSPEC const Sound_DecoderInfo **Sound_AvailableDecoders(void);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	279
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 * Get the last SDL_sound error message as a null-terminated string.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	283 * This will be NULL if there's been no error since the last call to this
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	284 * function. The pointer returned by this call points to an internal buffer.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	285 * Each thread has a unique error state associated with it, but each time
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	286 * a new error message is set, it will overwrite the previous one associated
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	287 * with that thread. It is safe to call this function at anytime, even
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	288 * before Sound_Init().
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	289 *
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	290 * @returns READ ONLY string of last error message.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	291 */
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	292 extern DECLSPEC const char *Sound_GetError(void);
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	293
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	294
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	295 /**
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	296 * Clear the current error message, so the next call to Sound_GetError() will
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	297 * return NULL.
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	298 */
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	299 extern DECLSPEC void Sound_ClearError(void);
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	300
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	301
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	302 /**
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	303 * Start decoding a new sound sample. The data is read via an SDL_RWops
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	304 * structure (see SDL_rwops.h in the SDL include directory), so it may be
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	305 * coming from memory, disk, network stream, etc. The (ext) parameter is
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	306 * merely a hint to determining the correct decoder; if you specify, for
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	307 * example, "mp3" for an extension, and one of the decoders lists that
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	308 * as a handled extension, then that decoder is given first shot at trying
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	309 * to claim the data for decoding. If none of the extensions match (or the
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	310 * extension is NULL), then every decoder examines the data to determine if
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	311 * it can handle it, until one accepts it. In such a case your SDL_RWops will
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	312 * need to be capable of rewinding to the start of the stream.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	313 * 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	314 * readable error message can be fetched from Sound_GetError().
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	315 * Optionally, a desired audio format can be specified. If the incoming data
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	316 * 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	317 * 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	318 * 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	319 * 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	320 * 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	321 * format. The incoming format of the data, preconversion, can be found
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	322 * in the Sound_Sample structure.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	323 * 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	324 * 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	325 * 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	326 * by the other decoders.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	327 * 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	328 * 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	329 * 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	330 * 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	331 * take. Note that different data formats require more or less space to
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	332 * 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	333 * 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	334 * 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	335 * 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	336 * 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	337 * 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	338 * MUCH larger buffer).
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	339 * When you are done with this Sound_Sample pointer, you can dispose of it
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	340 * via Sound_FreeSample().
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	341 * You do not have to keep a reference to (rw) around. If this function
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	342 * suceeds, it stores (rw) internally (and disposes of it during the call
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	343 * to Sound_FreeSample()). If this function fails, it will dispose of the
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	344 * SDL_RWops for you.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	345 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	346 * @param rw SDL_RWops with sound data.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	347 * @param ext File extension normally associated with a data format.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	348 * Can usually be NULL.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	349 * @param desired Format to convert sound data into. Can usually be NULL,
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	350 * if you don't need conversion.
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	351 * @returns Sound_Sample pointer, which is used as a handle to several other
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	352 * SDL_sound APIs. NULL on error. If error, use
186 70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	353 * Sound_GetError() to see what went wrong.
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	354 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	355 extern DECLSPEC Sound_Sample Sound_NewSample(SDL_RWops rw, const char *ext,
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	356 Sound_AudioInfo *desired,
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	357 Uint32 bufferSize);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	358
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	359 /**
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	360 * This is identical to Sound_NewSample(), but it creates an SDL_RWops for you
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	361 * from the file located in (filename). Note that (filename) is specified in
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	362 * platform-dependent notation. ("C:\\music\\mysong.mp3" on windows, and
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	363 * "/home/icculus/music/mysong.mp3" or whatever on Unix, etc.)
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	364 * Sound_NewSample()'s "ext" parameter is gleaned from the contents of
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	365 * (filename).
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	366 *
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	367 * @param filename file containing sound data.
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	368 * @param desired Format to convert sound data into. Can usually be NULL,
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	369 * if you don't need conversion.
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	370 * @param bufferSize size, in bytes, of initial read buffer.
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	371 * @returns Sound_Sample pointer, which is used as a handle to several other
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	372 * SDL_sound APIs. NULL on error. If error, use
186 70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	373 * Sound_GetError() to see what went wrong.
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	374 */
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	375 extern DECLSPEC Sound_Sample Sound_NewSampleFromFile(const char filename,
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	376 Sound_AudioInfo *desired,
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	377 Uint32 bufferSize);
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	378
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	379 /**
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	380 * Dispose of a Sound_Sample pointer that was returned from Sound_NewSample().
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	381 * This will also close/dispose of the SDL_RWops that was used at creation
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	382 * time, so there's no need to keep a reference to that around.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	383 * The Sound_Sample pointer is invalid after this call, and will almost
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	384 * certainly result in a crash if you attempt to keep using it.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	385 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	386 * @param sample The Sound_Sample to delete.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	387 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	388 extern DECLSPEC void Sound_FreeSample(Sound_Sample *sample);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	389
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	390
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	391 /**
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	392 * Change the current buffer size for a sample. If the buffer size could
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	393 * be changed, then the sample->buffer and sample->buffer_size fields will
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	394 * reflect that. If they could not be changed, then your original sample
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	395 * state is preserved. If the buffer is shrinking, the data at the end of
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	396 * buffer is truncated. If the buffer is growing, the contents of the new
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	397 * space at the end is undefined until you decode more into it or initialize
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	398 * it yourself.
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	399 *
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	400 * 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	401 * 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	402 * 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	403 * 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	404 * 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	405 * MUCH larger buffer).
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	406 *
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	407 * @param sample The Sound_Sample whose buffer to modify.
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	408 * @param new_size The desired size, in bytes, of the new buffer.
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	409 * @returns non-zero if buffer size changed, zero on failure.
3 fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	410 */
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	411 extern DECLSPEC int Sound_SetBufferSize(Sound_Sample *sample, Uint32 new_size);
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	412
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	413
fd6cd0e04e6f First stab at implementation complete. Ryan C. Gordon <icculus@icculus.org> parents: 1 diff changeset	414 /**
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	415 * Decode more of the sound data in a Sound_Sample. It will decode at most
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	416 * sample->buffer_size bytes into sample->buffer in the desired format, and
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	417 * return the number of decoded bytes.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	418 * If sample->buffer_size bytes could not be decoded, then please refer to
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	419 * sample->flags to determine if this was an End-of-stream or error condition.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	420 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	421 * @param sample Do more decoding to this Sound_Sample.
186 70561bf8d5fd Updated and clarified some documentation. Ryan C. Gordon <icculus@icculus.org> parents: 184 diff changeset	422 * @returns 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	423 * sample->buffer_size, then you should check sample->flags to see
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	424 * what the current state of the sample is (EOF, error, read again).
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	425 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	426 extern DECLSPEC Uint32 Sound_Decode(Sound_Sample *sample);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	427
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	428
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	429 /**
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	430 * Decode the remainder of the sound data in a Sound_Sample. This will
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	431 * dynamically allocate memory for the ENTIRE remaining sample.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	432 * sample->buffer_size and sample->buffer will be updated to reflect the
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	433 * new buffer. Please refer to sample->flags to determine if the decoding
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	434 * finished due to an End-of-stream or error condition.
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	435 *
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	436 * 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	437 * this function may block for quite awhile while processing. Also note
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	438 * 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	439 * 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	440 * 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	441 * only!
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	442 *
170 e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	443 * 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	444 * 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	445 * 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	446 * 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	447 * 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	448 * 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	449 * 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	450 * the sample isn't specific and small.
e91fb8d5bd62 Updated Sound_DecodeAll()'s comments. Ryan C. Gordon <icculus@icculus.org> parents: 149 diff changeset	451 *
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	452 * @param sample Do all decoding for this Sound_Sample.
184 47cc2de2ae36 Changed reference to "LICENSE" file to "COPYING". Ryan C. Gordon <icculus@icculus.org> parents: 170 diff changeset	453 * @returns 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	454 * 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	455 * (EOF, error, read again).
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	456 */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	457 extern DECLSPEC Uint32 Sound_DecodeAll(Sound_Sample *sample);
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	458
223 249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	459
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	460 /**
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	461 * Restart a sample at the start of its waveform data, as if newly
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	462 * created with Sound_NewSample(). If successful, the next call to
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	463 * Sound_Decode[All]() will give audio data from the earliest point
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	464 * in the stream.
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	465 *
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	466 * Beware that this function will fail if the SDL_RWops that feeds the
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	467 * decoder can not be rewound via it's seek method, but this can
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	468 * theoretically be avoided by wrapping it in some sort of buffering
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	469 * SDL_RWops.
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	470 *
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	471 * This function should ONLY fail if the RWops is not seekable, or
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	472 * SDL_sound is not initialized. Both can be controlled by the application,
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	473 * and thus, it is up to the developer's paranoia to dictate whether this
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	474 * function's return value need be checked at all.
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	475 *
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	476 * If this function fails, the state of the sample is undefined, but it
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	477 * is still safe to call Sound_FreeSample() to dispose of it.
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	478 *
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	479 * On success, ERROR, EOF, and EAGAIN are cleared from sample->flags. The
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	480 * ERROR flag is set on error.
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	481 *
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	482 * @param sample The Sound_Sample to rewind.
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	483 * @return nonzero on success, zero on error. Specifics of the
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	484 * error can be gleaned from Sound_GetError().
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	485 */
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	486 extern DECLSPEC int Sound_Rewind(Sound_Sample *sample);
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	487
249186e31431 Sound_Rewind() support code. Ryan C. Gordon <icculus@icculus.org> parents: 194 diff changeset	488
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	489 #ifdef __cplusplus
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	490 }
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	491 #endif
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	492
1 508aac690b19 Whoops...changed some overlooked "voice" to "sound". Ryan C. Gordon <icculus@icculus.org> parents: 0 diff changeset	493 #endif /* !defined _INCLUDE_SDL_SOUND_H_ */
0 1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	494
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	495 /* end of SDL_sound.h ... */
1078b3528e6f Initial revision Ryan C. Gordon <icculus@icculus.org> parents: diff changeset	496

Mercurial > SDL_sound_CoreAudio

annotate SDL_sound.h @ 302:414cfef0978e