sdl_sound.pas 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562
  1. unit sdl_sound;
  2. {
  3. $Id: sdl_sound.pas,v 1.5 2004/12/23 23:38:40 savage Exp $
  4. }
  5. (*
  6. * SDL_sound -- An abstract sound format decoding API.
  7. * Copyright (C) 2001 Ryan C. Gordon.
  8. *
  9. * This library is free software; you can redistribute it and/or
  10. * modify it under the terms of the GNU Lesser General Public
  11. * License as published by the Free Software Foundation; either
  12. * version 2.1 of the License, or (at your option) any later version.
  13. *
  14. * This library is distributed in the hope that it will be useful,
  15. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17. * Lesser General Public License for more details.
  18. *
  19. * You should have received a copy of the GNU Lesser General Public
  20. * License along with this library; if not, write to the Free Software
  21. * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  22. *)
  23. (**
  24. * @overview
  25. *
  26. * The basic gist of SDL_sound is that you use an SDL_RWops to get sound data
  27. * into this library, and SDL_sound will take that data, in one of several
  28. * popular formats, and decode it into raw waveform data in the format of
  29. * your choice. This gives you a nice abstraction for getting sound into your
  30. * game or application; just feed it to SDL_sound, and it will handle
  31. * decoding and converting, so you can just pass it to your SDL audio
  32. * callback (or whatever). Since it gets data from an SDL_RWops, you can get
  33. * the initial sound data from any number of sources: file, memory buffer,
  34. * network connection, etc.
  35. *
  36. * As the name implies, this library depends on SDL: Simple Directmedia Layer,
  37. * which is a powerful, free, and cross-platform multimedia library. It can
  38. * be found at http://www.libsdl.org/
  39. *
  40. * Support is in place or planned for the following sound formats:
  41. * - .WAV (Microsoft WAVfile RIFF data, internal.)
  42. * - .VOC (Creative Labs' Voice format, internal.)
  43. * - .MP3 (MPEG-1 Layer 3 support, via the SMPEG library.)
  44. * - .MID (MIDI music converted to Waveform data, internal.)
  45. * - .MOD (MOD files, via MikMod and ModPlug.)
  46. * - .OGG (Ogg files, via Ogg Vorbis libraries.)
  47. * - .SHN (Shorten files, internal.)
  48. * - .RAW (Raw sound data in any format, internal.)
  49. * - .AU (Sun's Audio format, internal.)
  50. * - .AIFF (Audio Interchange format, internal.)
  51. * - .FLAC (Lossless audio compression, via libFLAC.)
  52. *
  53. * (...and more to come...)
  54. *
  55. * Please see the file COPYING in the source's root directory.
  56. *
  57. * This file written by Ryan C. Gordon. ([email protected])
  58. *)
  59. { April 03 2003 - DL : Added jedi-sdl.inc include file to support more }
  60. { Pascal compilers. Initial support is now included }
  61. { for GnuPascal, VirtualPascal, TMT and obviously }
  62. { continue support for Delphi Kylix and FreePascal. }
  63. { }
  64. { May 03 2003 - DL : under instruction from David Mears AKA }
  65. { Jason Siletto, I have added FPC Linux support. }
  66. { }
  67. {
  68. $Log: sdl_sound.pas,v $
  69. Revision 1.5 2004/12/23 23:38:40 savage
  70. Applied Patches supplied by Michalis Kamburelis ( THANKS! ), for tidier code.
  71. Revision 1.4 2004/08/14 22:54:30 savage
  72. Updated so that Library name defines are correctly defined for MacOS X.
  73. Revision 1.3 2004/05/10 14:10:04 savage
  74. Initial MacOS X support. Fixed defines for MACOS ( Classic ) and DARWIN ( MacOS X ).
  75. Revision 1.2 2004/03/30 20:23:28 savage
  76. Tidied up use of UNIX compiler directive.
  77. Revision 1.1 2004/02/16 22:16:40 savage
  78. v1.0 changes
  79. }
  80. {******************************************************************************}
  81. {$I jedi-sdl.inc}
  82. interface
  83. uses
  84. {$IFDEF WIN32}
  85. Windows,
  86. {$ENDIF}
  87. sdl;
  88. const
  89. {$IFDEF WIN32}
  90. SDLSoundLibName = 'SDL_sound.dll';
  91. {$ENDIF}
  92. {$IFDEF UNIX}
  93. {$IFDEF DARWIN}
  94. SDLSoundLibName = 'libSDL_sound.dylib';
  95. {$ELSE}
  96. SDLSoundLibName = 'libSDL_sound.so';
  97. {$ENDIF}
  98. {$ENDIF}
  99. {$IFDEF MACOS}
  100. SDLSoundLibName = 'SDL_sound';
  101. {$ENDIF}
  102. SOUND_VER_MAJOR = 0;
  103. {$EXTERNALSYM SOUND_VER_MAJOR}
  104. SOUND_VER_MINOR = 1;
  105. {$EXTERNALSYM SOUND_VER_MINOR}
  106. SOUND_VER_PATCH = 5;
  107. {$EXTERNALSYM SOUND_VER_PATCH}
  108. (**
  109. * These are flags that are used in a Sound_Sample to show various states.
  110. *
  111. * To use: 'if (sample.flags and SOUND_SAMPLEFLAG_ERROR) begin dosomething; end;'
  112. *
  113. * @param SOUND_SAMPLEFLAG_NONE nil flag.
  114. * @param SOUND_SAMPLEFLAG_NEEDSEEK SDL_RWops must be able to seek.
  115. * @param SOUND_SAMPLEFLAG_EOF end of input stream.
  116. * @param SOUND_SAMPLEFLAG_ERROR unrecoverable error.
  117. * @param SOUND_SAMPLEFLAG_EAGAIN function would block, or temp error.
  118. *)
  119. SOUND_SAMPLEFLAG_NONE = 0;
  120. {$EXTERNALSYM SOUND_SAMPLEFLAG_NONE}
  121. (* these are set at sample creation time... *)
  122. SOUND_SAMPLEFLAG_NEEDSEEK = 1;
  123. {$EXTERNALSYM SOUND_SAMPLEFLAG_NEEDSEEK}
  124. (* these are set during decoding... *)
  125. SOUND_SAMPLEFLAG_EOF = 1 shl 29;
  126. {$EXTERNALSYM SOUND_SAMPLEFLAG_EOF}
  127. SOUND_SAMPLEFLAG_ERROR = 1 shl 30;
  128. {$EXTERNALSYM SOUND_SAMPLEFLAG_ERROR}
  129. SOUND_SAMPLEFLAG_EAGAIN = 1 shl 31;
  130. {$EXTERNALSYM SOUND_SAMPLEFLAG_EAGAIN}
  131. (**
  132. * These are the basics of a decoded sample's data type = recordure: data format
  133. * (see AUDIO_U8 and friends in SDL_audio.h), number of channels, and sample
  134. * rate. If you need more explanation than that, you should stop developing
  135. * sound code right now.
  136. *
  137. * @param format Equivalent of SDL_AudioSpec.format.
  138. * @param channels Number of sound channels. 1 = mono, 2 = stereo.
  139. * @param rate Sample rate; frequency of sample points per second (44100,
  140. * 22050, 8000, etc.)
  141. *)
  142. type
  143. TSound_SampleFlags = Integer;
  144. PSound_AudioInfo = ^Sound_AudioInfo;
  145. Sound_AudioInfo = record
  146. format: Uint16;
  147. channels: Uint8;
  148. rate: Uint32;
  149. end;
  150. TSound_AudioInfo = Sound_AudioInfo;
  151. {$EXTERNALSYM Sound_AudioInfo}
  152. (**
  153. * Each decoder sets up one of these type = records, which can be retrieved via
  154. * the Sound_AvailableDecoders function. EVERY FIELD IN THIS IS READ-ONLY.
  155. *
  156. * @param extensions File extensions, list ends with nil. Read it like this:
  157. * const : PChar *ext;
  158. * for (ext := info.extensions; *ext <> nil; ext++)
  159. * printf(' File extension \'%s\'', *ext);
  160. * @param description Human readable description of decoder.
  161. * @param author 'Name Of Author <[email protected]>'
  162. * @param url URL specific to this decoder.
  163. *)
  164. PSound_DecoderInfo = ^Sound_DecoderInfo;
  165. Sound_DecoderInfo = record
  166. extensions: PChar;
  167. description: PChar;
  168. author: PChar;
  169. url: PChar;
  170. end;
  171. TSound_DecoderInfo = Sound_DecoderInfo;
  172. {$EXTERNALSYM Sound_DecoderInfo}
  173. (**
  174. * The Sound_Sample type = recordure is the heart of SDL_sound. This holds
  175. * information about a source of sound data as it is being decoded.
  176. * EVERY FIELD IN THIS IS READ-ONLY. Please use the API functions to
  177. * change them.
  178. *
  179. * @param opaque Internal use only. Don't touch.
  180. * @param decoder Decoder used for this sample.
  181. * @param desired Desired audio format for conversion.
  182. * @param actual Actual audio format of sample.
  183. * @param buffer Decoded sound data lands in here.
  184. * @param buffer_size Current size of (buffer), in bytes (Uint8).
  185. * @param flags Flags relating to this sample.
  186. *)
  187. PSound_Sample = ^Sound_Sample;
  188. Sound_Sample = record
  189. opaque: Pointer;
  190. decoder: PSound_DecoderInfo;
  191. desired: Sound_AudioInfo;
  192. actual: Sound_AudioInfo;
  193. buffer: Pointer;
  194. buffer_size: Uint32;
  195. flags: TSound_SampleFlags;
  196. end;
  197. TSound_Sample = Sound_Sample;
  198. {$EXTERNALSYM Sound_Sample}
  199. (**
  200. * Just what it says: a major.minor.patch style version number...
  201. *
  202. * @param major The major version number.
  203. * @param minor The minor version number.
  204. * @param patch The patchlevel version number.
  205. *)
  206. PSound_Version = ^Sound_Version;
  207. Sound_Version = record
  208. major: integer;
  209. minor: integer;
  210. patch: integer;
  211. end;
  212. TSound_Version = Sound_Version;
  213. {$EXTERNALSYM Sound_Version}
  214. (* functions and macros... *)
  215. procedure SOUND_GETVERSION(var x: TSound_Version);
  216. (**
  217. * Get the version of SDL_sound that is linked against your program. If you
  218. * are using a shared library (DLL) version of SDL_sound, then it is possible
  219. * that it will be different than the version you compiled against.
  220. *
  221. * This is a real function; the macro SOUND_VERSION tells you what version
  222. * of SDL_sound you compiled against:
  223. *
  224. * Sound_Version compiled;
  225. * Sound_Version linked;
  226. *
  227. * SOUND_VERSION(@compiled);
  228. * Sound_GetLinkedVersion(@linked);
  229. * printf('We compiled against SDL_sound version %d.%d.%d ...',
  230. * compiled.major, compiled.minor, compiled.patch);
  231. * printf('But we linked against SDL_sound version %d.%d.%d.',
  232. * linked.major, linked.minor, linked.patch);
  233. *
  234. * This function may be called safely at any time, even before Sound_Init.
  235. *
  236. * @param ver Sound_Version type = recordure to fill with shared library's version.
  237. *)
  238. procedure Sound_GetLinkedVersion(ver: PSound_Version);
  239. cdecl; external {$IFDEF __GPC__}name 'Sound_GetLinkedVersion'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  240. {$EXTERNALSYM Sound_GetLinkedVersion}
  241. (**
  242. * Initialize SDL_sound. This must be called before any other SDL_sound
  243. * function (except perhaps Sound_GetLinkedVersion). You should call
  244. * SDL_Init before calling this. Sound_Init will attempt to call
  245. * SDL_Init(SDL_INIT_AUDIO), just in . This is a safe behaviour, but it
  246. * may not configure SDL to your liking by itself.
  247. *
  248. * @returns nonzero on success, zero on error. Specifics of the
  249. * error can be gleaned from Sound_GetError.
  250. *)
  251. function Sound_Init: integer;
  252. cdecl; external {$IFDEF __GPC__}name 'Sound_Init'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  253. {$EXTERNALSYM Sound_Init}
  254. (**
  255. * Shutdown SDL_sound. This closes any SDL_RWops that were being used as
  256. * sound sources, and frees any resources in use by SDL_sound.
  257. *
  258. * All Sound_Sample pointers you had prior to this call are INVALIDATED.
  259. *
  260. * Once successfully deinitialized, Sound_Init can be called again to
  261. * restart the subsystem. All default API states are restored at this
  262. * point.
  263. *
  264. * You should call this BEFORE SDL_Quit. This will NOT call SDL_Quit
  265. * for younot
  266. *
  267. * @returns nonzero on success, zero on error. Specifics of the error
  268. * can be gleaned from Sound_GetError. If failure, state of
  269. * SDL_sound is undefined, and probably badly screwed up.
  270. *)
  271. function Sound_Quit: integer;
  272. cdecl; external {$IFDEF __GPC__}name 'Sound_Quit'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  273. {$EXTERNALSYM Sound_Quit}
  274. (**
  275. * Get a list of sound formats supported by this implementation of SDL_sound.
  276. * This is for informational purposes only. Note that the extension listed is
  277. * merely convention: if we list 'MP3', you can open an MPEG-1 Layer 3 audio
  278. * file with an extension of 'XYZ', if you like. The file extensions are
  279. * informational, and only required as a h : integer to choosing the correct
  280. * decoder, since the sound data may not be coming from a file at all, thanks
  281. * to the abstraction that an SDL_RWops provides.
  282. *
  283. * The result value is an array of pointers to Sound_DecoderInfo type = recordures,
  284. * with a nil entry to signify the end of the list:
  285. *
  286. * Sound_DecoderInfo **i;
  287. *
  288. * for (i := Sound_AvailableDecoders; *i <> nil; i++)
  289. * begin
  290. * printf('Supported sound format: : array[ 0..%s- 1 ] of , which is : array[ 0..%s- 1 ] of .',
  291. * i.extension, i.description);
  292. * // ...and other fields...
  293. * end;
  294. *
  295. * The return values are pointers to static internal memory, and should
  296. * be considered READ ONLY, and never freed.
  297. *
  298. * @returns READ ONLY nil-terminated array of READ ONLY type = recordures.
  299. *)
  300. function Sound_AvailableDecoders: PSound_DecoderInfo;
  301. cdecl; external {$IFDEF __GPC__}name 'Sound_AvailableDecoders'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  302. {$EXTERNALSYM Sound_AvailableDecoders}
  303. (**
  304. * Get the last SDL_sound error message as a nil-terminated string.
  305. * This will be nil if there's been no error since the last call to this
  306. * function. The pointer returned by this call points to an internal buffer.
  307. * Each thread has a unique error state associated with it, but each time
  308. * a new error message is set, it will overwrite the previous one associated
  309. * with that thread. It is safe to call this function at anytime, even
  310. * before Sound_Init.
  311. *
  312. * @returns READ ONLY string of last error message.
  313. *)
  314. function Sound_GetError: PChar;
  315. cdecl; external {$IFDEF __GPC__}name 'Sound_GetError'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  316. {$EXTERNALSYM Sound_GetError}
  317. (**
  318. * Clear the current error message, so the next call to Sound_GetError will
  319. * return nil.
  320. *)
  321. procedure Sound_ClearError;
  322. cdecl; external {$IFDEF __GPC__}name 'Sound_ClearError'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  323. {$EXTERNALSYM Sound_ClearError}
  324. (**
  325. * Start decoding a new sound sample. The data is read via an SDL_RWops
  326. * type = recordure (see SDL_rwops.h in the SDL include directory), so it may be
  327. * coming from memory, disk, network stream, etc. The (ext) parameter is
  328. * merely a h : integer to determining the correct decoder; if you specify, for
  329. * example, 'mp3' for an extension, and one of the decoders lists that
  330. * as a handled extension, then that decoder is given first shot at trying
  331. * to claim the data for decoding. If none of the extensions match (or the
  332. * extension is nil), then every decoder examines the data to determine if
  333. * it can handle it, until one accepts it. In such a your SDL_RWops will
  334. * need to be capable of rewinding to the start of the stream.
  335. * If no decoders can handle the data, a nil value is returned, and a human
  336. * readable error message can be fetched from Sound_GetError.
  337. * Optionally, a desired audio format can be specified. If the incoming data
  338. * is in a different format, SDL_sound will convert it to the desired format
  339. * on the fly. Note that this can be an expensive operation, so it may be
  340. * wise to convert data before you need to play it back, if possible, or
  341. * make sure your data is initially in the format that you need it in.
  342. * If you don't want to convert the data, you can specify nil for a desired
  343. * format. The incoming format of the data, preconversion, can be found
  344. * in the Sound_Sample type = recordure.
  345. * Note that the raw sound data 'decoder' needs you to specify both the
  346. * extension 'RAW' and a 'desired' format, or it will refuse to handle
  347. * the data. This is to prevent it from catching all formats unsupported
  348. * by the other decoders.
  349. * Finally, specify an initial buffer size; this is the number of bytes that
  350. * will be allocated to store each read from the sound buffer. The more you
  351. * can safely allocate, the more decoding can be done in one block, but the
  352. * more resources you have to use up, and the longer each decoding call will
  353. * take. Note that different data formats require more or less space to
  354. * store. This buffer can be resized via Sound_SetBufferSize ...
  355. * The buffer size specified must be a multiple of the size of a single
  356. * sample point. So, if you want 16-bit, stereo samples, then your sample
  357. * po : integer size is (2 channels * 16 bits), or 32 bits per sample, which is four
  358. * bytes. In such a , you could specify 128 or 132 bytes for a buffer,
  359. * but not 129, 130, or 131 (although in reality, you'll want to specify a
  360. * MUCH larger buffer).
  361. * When you are done with this Sound_Sample pointer, you can dispose of it
  362. * via Sound_FreeSample.
  363. * You do not have to keep a reference to (rw) around. If this function
  364. * suceeds, it stores (rw) internally (and disposes of it during the call
  365. * to Sound_FreeSample). If this function fails, it will dispose of the
  366. * SDL_RWops for you.
  367. *
  368. * @param rw SDL_RWops with sound data.
  369. * @param ext File extension normally associated with a data format.
  370. * Can usually be nil.
  371. * @param desired Format to convert sound data into. Can usually be nil,
  372. * if you don't need conversion.
  373. * @returns Sound_Sample pointer, which is used as a handle to several other
  374. * SDL_sound APIs. nil on error. If error, use
  375. * Sound_GetError to see what went wrong.
  376. *)
  377. function Sound_NewSample(rw: PSDL_RWops; const ext: PChar;
  378. desired: PSound_AudioInfo; bufferSize: Uint32): PSound_Sample;
  379. cdecl; external {$IFDEF __GPC__}name 'Sound_NewSample'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  380. {$EXTERNALSYM Sound_NewSample}
  381. (**
  382. * This is identical to Sound_NewSample, but it creates an SDL_RWops for you
  383. * from the file located in (filename). Note that (filename) is specified in
  384. * platform-dependent notation. ('C:\\music\\mysong.mp3' on windows, and
  385. * '/home/icculus/music/mysong.mp3' or whatever on Unix, etc.)
  386. * Sound_NewSample's 'ext' parameter is gleaned from the contents of
  387. * (filename).
  388. *
  389. * @param filename file containing sound data.
  390. * @param desired Format to convert sound data into. Can usually be nil,
  391. * if you don't need conversion.
  392. * @param bufferSize size, in bytes, of initial read buffer.
  393. * @returns Sound_Sample pointer, which is used as a handle to several other
  394. * SDL_sound APIs. nil on error. If error, use
  395. * Sound_GetError to see what went wrong.
  396. *)
  397. function Sound_NewSampleFromFile(const filename: PChar; desired:
  398. PSound_AudioInfo; bufferSize: Uint32): PSound_Sample;
  399. cdecl; external {$IFDEF __GPC__}name 'Sound_NewSampleFromFile'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  400. {$EXTERNALSYM Sound_NewSampleFromFile}
  401. (**
  402. * Dispose of a Sound_Sample pointer that was returned from Sound_NewSample.
  403. * This will also close/dispose of the SDL_RWops that was used at creation
  404. * time, so there's no need to keep a reference to that around.
  405. * The Sound_Sample pointer is invalid after this call, and will almost
  406. * certainly result in a crash if you attempt to keep using it.
  407. *
  408. * @param sample The Sound_Sample to delete.
  409. *)
  410. procedure Sound_FreeSample(sample: PSound_Sample);
  411. cdecl; external {$IFDEF __GPC__}name 'Sound_FreeSample'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  412. {$EXTERNALSYM Sound_FreeSample}
  413. (**
  414. * Change the current buffer size for a sample. If the buffer size could
  415. * be changed, then the sample.buffer and sample.buffer_size fields will
  416. * reflect that. If they could not be changed, then your original sample
  417. * state is preserved. If the buffer is shrinking, the data at the end of
  418. * buffer is truncated. If the buffer is growing, the contents of the new
  419. * space at the end is undefined until you decode more into it or initialize
  420. * it yourself.
  421. *
  422. * The buffer size specified must be a multiple of the size of a single
  423. * sample point. So, if you want 16-bit, stereo samples, then your sample
  424. * po : integer size is (2 channels * 16 bits), or 32 bits per sample, which is four
  425. * bytes. In such a , you could specify 128 or 132 bytes for a buffer,
  426. * but not 129, 130, or 131 (although in reality, you'll want to specify a
  427. * MUCH larger buffer).
  428. *
  429. * @param sample The Sound_Sample whose buffer to modify.
  430. * @param new_size The desired size, in bytes, of the new buffer.
  431. * @returns non-zero if buffer size changed, zero on failure.
  432. *)
  433. function Sound_SetBufferSize(sample: PSound_Sample; new_size: Uint32): integer;
  434. cdecl; external {$IFDEF __GPC__}name 'Sound_SetBufferSize'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  435. {$EXTERNALSYM Sound_SetBufferSize}
  436. (**
  437. * Decode more of the sound data in a Sound_Sample. It will decode at most
  438. * sample.buffer_size bytes into sample.buffer in the desired format, and
  439. * return the number of decoded bytes.
  440. * If sample.buffer_size bytes could not be decoded, then please refer to
  441. * sample.flags to determine if this was an End-of-stream or error condition.
  442. *
  443. * @param sample Do more decoding to this Sound_Sample.
  444. * @returns number of bytes decoded into sample.buffer. If it is less than
  445. * sample.buffer_size, then you should check sample.flags to see
  446. * what the current state of the sample is (EOF, error, read again).
  447. *)
  448. function Sound_Decode(sample: PSound_Sample): Uint32;
  449. cdecl; external {$IFDEF __GPC__}name 'Sound_Decode'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  450. {$EXTERNALSYM Sound_Decode}
  451. (**
  452. * Decode the remainder of the sound data in a Sound_Sample. This will
  453. * dynamically allocate memory for the ENTIRE remaining sample.
  454. * sample.buffer_size and sample.buffer will be updated to reflect the
  455. * new buffer. Please refer to sample.flags to determine if the decoding
  456. * finished due to an End-of-stream or error condition.
  457. *
  458. * Be aware that sound data can take a large amount of memory, and that
  459. * this function may block for quite awhile while processing. Also note
  460. * that a streaming source (for example, from a SDL_RWops that is getting
  461. * fed from an Internet radio feed that doesn't end) may fill all available
  462. * memory before giving up...be sure to use this on finite sound sources
  463. * onlynot
  464. *
  465. * When decoding the sample in its entirety, the work is done one buffer at a
  466. * time. That is, sound is decoded in sample.buffer_size blocks, and
  467. * appended to a continually-growing buffer until the decoding completes.
  468. * That means that this function will need enough RAM to hold approximately
  469. * sample.buffer_size bytes plus the complete decoded sample at most. The
  470. * larger your buffer size, the less overhead this function needs, but beware
  471. * the possibility of paging to disk. Best to make this user-configurable if
  472. * the sample isn't specific and small.
  473. *
  474. * @param sample Do all decoding for this Sound_Sample.
  475. * @returns number of bytes decoded into sample.buffer. You should check
  476. * sample.flags to see what the current state of the sample is
  477. * (EOF, error, read again).
  478. *)
  479. function Sound_DecodeAll(sample: PSound_Sample): Uint32;
  480. cdecl; external {$IFDEF __GPC__}name 'Sound_DecodeAll'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  481. {$EXTERNALSYM Sound_DecodeAll}
  482. (**
  483. * Restart a sample at the start of its waveform data, as if newly
  484. * created with Sound_NewSample. If successful, the next call to
  485. * Sound_Decode : array[ 0..All- 1 ] of will give audio data from the earliest point
  486. * in the stream.
  487. *
  488. * Beware that this function will fail if the SDL_RWops that feeds the
  489. * decoder can not be rewound via it's seek method, but this can
  490. * theoretically be aprocedure ed by wrapping it in some sort of buffering
  491. * SDL_RWops.
  492. *
  493. * This function should ONLY fail if the RWops is not seekable, or
  494. * SDL_sound is not initialized. Both can be controlled by the application,
  495. * and thus, it is up to the developer's paranoia to dictate whether this
  496. * function's return value need be checked at all.
  497. *
  498. * If this function fails, the state of the sample is undefined, but it
  499. * is still safe to call Sound_FreeSample to dispose of it.
  500. *
  501. * On success, ERROR, EOF, and EAGAIN are cleared from sample.flags. The
  502. * ERROR flag is set on error.
  503. *
  504. * @param sample The Sound_Sample to rewind.
  505. * @return nonzero on success, zero on error. Specifics of the
  506. * error can be gleaned from Sound_GetError.
  507. *)
  508. function Sound_Rewind(sample: PSound_Sample): integer;
  509. cdecl; external {$IFDEF __GPC__}name 'Sound_Rewind'{$ELSE} SDLSoundLibName{$ENDIF __GPC__};
  510. {$EXTERNALSYM Sound_Rewind}
  511. implementation
  512. {$IFDEF __GPC__}
  513. {$L sdl_sound} { link sdl.dll.a or libsdl.so or libsdl.a }
  514. {$ELSE}
  515. {$ENDIF}
  516. procedure SOUND_GETVERSION(var x: TSound_Version);
  517. begin
  518. x.major := SOUND_VER_MAJOR;
  519. x.minor := SOUND_VER_MINOR;
  520. x.patch := SOUND_VER_PATCH;
  521. end;
  522. end.