/src/middleware/stb_vorbis/stb_vorbis.h

https://bitbucket.org/vivkin/gam3b00bs/ · C Header · 357 lines · 104 code · 59 blank · 194 comment · 2 complexity · ad9ce8b9eafe381910a2bccb662b1003 MD5 · raw file

  1. // Ogg Vorbis I audio decoder -- version 0.99996
  2. //
  3. // Written in April 2007 by Sean Barrett, sponsored by RAD Game Tools.
  4. //
  5. // Placed in the public domain April 2007 by the author: no copyright is
  6. // claimed, and you may use it for any purpose you like.
  7. //
  8. // No warranty for any purpose is expressed or implied by the author (nor
  9. // by RAD Game Tools). Report bugs and send enhancements to the author.
  10. //
  11. // Get the latest version and other information at:
  12. // http://nothings.org/stb_vorbis/
  13. // Todo:
  14. //
  15. // - seeking (note you can seek yourself using the pushdata API)
  16. //
  17. // Limitations:
  18. //
  19. // - floor 0 not supported (used in old ogg vorbis files)
  20. // - lossless sample-truncation at beginning ignored
  21. // - cannot concatenate multiple vorbis streams
  22. // - sample positions are 32-bit, limiting seekable 192Khz
  23. // files to around 6 hours (Ogg supports 64-bit)
  24. //
  25. // All of these limitations may be removed in future versions.
  26. //////////////////////////////////////////////////////////////////////////////
  27. //
  28. // HEADER BEGINS HERE
  29. //
  30. #ifndef STB_VORBIS_INCLUDE_STB_VORBIS_H
  31. #define STB_VORBIS_INCLUDE_STB_VORBIS_H
  32. #if defined(STB_VORBIS_NO_CRT) && !defined(STB_VORBIS_NO_STDIO)
  33. #define STB_VORBIS_NO_STDIO 1
  34. #endif
  35. #ifndef STB_VORBIS_NO_STDIO
  36. #include <stdio.h>
  37. #endif
  38. #ifdef __cplusplus
  39. extern "C" {
  40. #endif
  41. /////////// THREAD SAFETY
  42. // Individual stb_vorbis* handles are not thread-safe; you cannot decode from
  43. // them from multiple threads at the same time. However, you can have multiple
  44. // stb_vorbis* handles and decode from them independently in multiple thrads.
  45. /////////// MEMORY ALLOCATION
  46. // normally stb_vorbis uses malloc() to allocate memory at startup,
  47. // and alloca() to allocate temporary memory during a frame on the
  48. // stack. (Memory consumption will depend on the amount of setup
  49. // data in the file and how you set the compile flags for speed
  50. // vs. size. In my test files the maximal-size usage is ~150KB.)
  51. //
  52. // You can modify the wrapper functions in the source (setup_malloc,
  53. // setup_temp_malloc, temp_malloc) to change this behavior, or you
  54. // can use a simpler allocation model: you pass in a buffer from
  55. // which stb_vorbis will allocate _all_ its memory (including the
  56. // temp memory). "open" may fail with a VORBIS_outofmem if you
  57. // do not pass in enough data; there is no way to determine how
  58. // much you do need except to succeed (at which point you can
  59. // query get_info to find the exact amount required. yes I know
  60. // this is lame).
  61. //
  62. // If you pass in a non-NULL buffer of the type below, allocation
  63. // will occur from it as described above. Otherwise just pass NULL
  64. // to use malloc()/alloca()
  65. typedef struct
  66. {
  67. char *alloc_buffer;
  68. int alloc_buffer_length_in_bytes;
  69. } stb_vorbis_alloc;
  70. /////////// FUNCTIONS USEABLE WITH ALL INPUT MODES
  71. typedef struct stb_vorbis stb_vorbis;
  72. typedef struct
  73. {
  74. unsigned int sample_rate;
  75. int channels;
  76. unsigned int setup_memory_required;
  77. unsigned int setup_temp_memory_required;
  78. unsigned int temp_memory_required;
  79. int max_frame_size;
  80. } stb_vorbis_info;
  81. // get general information about the file
  82. extern stb_vorbis_info stb_vorbis_get_info(stb_vorbis *f);
  83. // get the last error detected (clears it, too)
  84. extern int stb_vorbis_get_error(stb_vorbis *f);
  85. // close an ogg vorbis file and free all memory in use
  86. extern void stb_vorbis_close(stb_vorbis *f);
  87. // this function returns the offset (in samples) from the beginning of the
  88. // file that will be returned by the next decode, if it is known, or -1
  89. // otherwise. after a flush_pushdata() call, this may take a while before
  90. // it becomes valid again.
  91. // NOT WORKING YET after a seek with PULLDATA API
  92. extern int stb_vorbis_get_sample_offset(stb_vorbis *f);
  93. // returns the current seek point within the file, or offset from the beginning
  94. // of the memory buffer. In pushdata mode it returns 0.
  95. extern unsigned int stb_vorbis_get_file_offset(stb_vorbis *f);
  96. /////////// PUSHDATA API
  97. #ifndef STB_VORBIS_NO_PUSHDATA_API
  98. // this API allows you to get blocks of data from any source and hand
  99. // them to stb_vorbis. you have to buffer them; stb_vorbis will tell
  100. // you how much it used, and you have to give it the rest next time;
  101. // and stb_vorbis may not have enough data to work with and you will
  102. // need to give it the same data again PLUS more. Note that the Vorbis
  103. // specification does not bound the size of an individual frame.
  104. extern stb_vorbis *stb_vorbis_open_pushdata(
  105. unsigned char *datablock, int datablock_length_in_bytes,
  106. int *datablock_memory_consumed_in_bytes,
  107. int *error,
  108. stb_vorbis_alloc *alloc_buffer);
  109. // create a vorbis decoder by passing in the initial data block containing
  110. // the ogg&vorbis headers (you don't need to do parse them, just provide
  111. // the first N bytes of the file--you're told if it's not enough, see below)
  112. // on success, returns an stb_vorbis *, does not set error, returns the amount of
  113. // data parsed/consumed on this call in *datablock_memory_consumed_in_bytes;
  114. // on failure, returns NULL on error and sets *error, does not change *datablock_memory_consumed
  115. // if returns NULL and *error is VORBIS_need_more_data, then the input block was
  116. // incomplete and you need to pass in a larger block from the start of the file
  117. extern int stb_vorbis_decode_frame_pushdata(
  118. stb_vorbis *f, unsigned char *datablock, int datablock_length_in_bytes,
  119. int *channels, // place to write number of float * buffers
  120. float ***output, // place to write float ** array of float * buffers
  121. int *samples // place to write number of output samples
  122. );
  123. // decode a frame of audio sample data if possible from the passed-in data block
  124. //
  125. // return value: number of bytes we used from datablock
  126. // possible cases:
  127. // 0 bytes used, 0 samples output (need more data)
  128. // N bytes used, 0 samples output (resynching the stream, keep going)
  129. // N bytes used, M samples output (one frame of data)
  130. // note that after opening a file, you will ALWAYS get one N-bytes,0-sample
  131. // frame, because Vorbis always "discards" the first frame.
  132. //
  133. // Note that on resynch, stb_vorbis will rarely consume all of the buffer,
  134. // instead only datablock_length_in_bytes-3 or less. This is because it wants
  135. // to avoid missing parts of a page header if they cross a datablock boundary,
  136. // without writing state-machiney code to record a partial detection.
  137. //
  138. // The number of channels returned are stored in *channels (which can be
  139. // NULL--it is always the same as the number of channels reported by
  140. // get_info). *output will contain an array of float* buffers, one per
  141. // channel. In other words, (*output)[0][0] contains the first sample from
  142. // the first channel, and (*output)[1][0] contains the first sample from
  143. // the second channel.
  144. extern void stb_vorbis_flush_pushdata(stb_vorbis *f);
  145. // inform stb_vorbis that your next datablock will not be contiguous with
  146. // previous ones (e.g. you've seeked in the data); future attempts to decode
  147. // frames will cause stb_vorbis to resynchronize (as noted above), and
  148. // once it sees a valid Ogg page (typically 4-8KB, as large as 64KB), it
  149. // will begin decoding the _next_ frame.
  150. //
  151. // if you want to seek using pushdata, you need to seek in your file, then
  152. // call stb_vorbis_flush_pushdata(), then start calling decoding, then once
  153. // decoding is returning you data, call stb_vorbis_get_sample_offset, and
  154. // if you don't like the result, seek your file again and repeat.
  155. #endif
  156. ////////// PULLING INPUT API
  157. #ifndef STB_VORBIS_NO_PULLDATA_API
  158. // This API assumes stb_vorbis is allowed to pull data from a source--
  159. // either a block of memory containing the _entire_ vorbis stream, or a
  160. // FILE * that you or it create, or possibly some other reading mechanism
  161. // if you go modify the source to replace the FILE * case with some kind
  162. // of callback to your code. (But if you don't support seeking, you may
  163. // just want to go ahead and use pushdata.)
  164. #if !defined(STB_VORBIS_NO_STDIO) && !defined(STB_VORBIS_NO_INTEGER_CONVERSION)
  165. extern int stb_vorbis_decode_filename(char *filename, int *channels, short **output);
  166. #endif
  167. extern int stb_vorbis_decode_memory(unsigned char *mem, int len, int *channels, short **output);
  168. // decode an entire file and output the data interleaved into a malloc()ed
  169. // buffer stored in *output. The return value is the number of samples
  170. // decoded, or -1 if the file could not be opened or was not an ogg vorbis file.
  171. // When you're done with it, just free() the pointer returned in *output.
  172. extern stb_vorbis * stb_vorbis_open_memory(unsigned char *data, int len,
  173. int *error, stb_vorbis_alloc *alloc_buffer);
  174. // create an ogg vorbis decoder from an ogg vorbis stream in memory (note
  175. // this must be the entire stream!). on failure, returns NULL and sets *error
  176. #ifndef STB_VORBIS_NO_STDIO
  177. extern stb_vorbis * stb_vorbis_open_filename(char *filename,
  178. int *error, stb_vorbis_alloc *alloc_buffer);
  179. // create an ogg vorbis decoder from a filename via fopen(). on failure,
  180. // returns NULL and sets *error (possibly to VORBIS_file_open_failure).
  181. extern stb_vorbis * stb_vorbis_open_file(FILE *f, int close_handle_on_close,
  182. int *error, stb_vorbis_alloc *alloc_buffer);
  183. // create an ogg vorbis decoder from an open FILE *, looking for a stream at
  184. // the _current_ seek point (ftell). on failure, returns NULL and sets *error.
  185. // note that stb_vorbis must "own" this stream; if you seek it in between
  186. // calls to stb_vorbis, it will become confused. Morever, if you attempt to
  187. // perform stb_vorbis_seek_*() operations on this file, it will assume it
  188. // owns the _entire_ rest of the file after the start point. Use the next
  189. // function, stb_vorbis_open_file_section(), to limit it.
  190. extern stb_vorbis * stb_vorbis_open_file_section(FILE *f, int close_handle_on_close,
  191. int *error, stb_vorbis_alloc *alloc_buffer, unsigned int len);
  192. // create an ogg vorbis decoder from an open FILE *, looking for a stream at
  193. // the _current_ seek point (ftell); the stream will be of length 'len' bytes.
  194. // on failure, returns NULL and sets *error. note that stb_vorbis must "own"
  195. // this stream; if you seek it in between calls to stb_vorbis, it will become
  196. // confused.
  197. #endif
  198. extern int stb_vorbis_seek_frame(stb_vorbis *f, unsigned int sample_number);
  199. extern int stb_vorbis_seek(stb_vorbis *f, unsigned int sample_number);
  200. // NOT WORKING YET
  201. // these functions seek in the Vorbis file to (approximately) 'sample_number'.
  202. // after calling seek_frame(), the next call to get_frame_*() will include
  203. // the specified sample. after calling stb_vorbis_seek(), the next call to
  204. // stb_vorbis_get_samples_* will start with the specified sample. If you
  205. // do not need to seek to EXACTLY the target sample when using get_samples_*,
  206. // you can also use seek_frame().
  207. extern void stb_vorbis_seek_start(stb_vorbis *f);
  208. // this function is equivalent to stb_vorbis_seek(f,0), but it
  209. // actually works
  210. extern unsigned int stb_vorbis_stream_length_in_samples(stb_vorbis *f);
  211. extern float stb_vorbis_stream_length_in_seconds(stb_vorbis *f);
  212. // these functions return the total length of the vorbis stream
  213. extern int stb_vorbis_get_frame_float(stb_vorbis *f, int *channels, float ***output);
  214. // decode the next frame and return the number of samples. the number of
  215. // channels returned are stored in *channels (which can be NULL--it is always
  216. // the same as the number of channels reported by get_info). *output will
  217. // contain an array of float* buffers, one per channel. These outputs will
  218. // be overwritten on the next call to stb_vorbis_get_frame_*.
  219. //
  220. // You generally should not intermix calls to stb_vorbis_get_frame_*()
  221. // and stb_vorbis_get_samples_*(), since the latter calls the former.
  222. #ifndef STB_VORBIS_NO_INTEGER_CONVERSION
  223. extern int stb_vorbis_get_frame_short_interleaved(stb_vorbis *f, int num_c, short *buffer, int num_shorts);
  224. extern int stb_vorbis_get_frame_short (stb_vorbis *f, int num_c, short **buffer, int num_samples);
  225. #endif
  226. // decode the next frame and return the number of samples per channel. the
  227. // data is coerced to the number of channels you request according to the
  228. // channel coercion rules (see below). You must pass in the size of your
  229. // buffer(s) so that stb_vorbis will not overwrite the end of the buffer.
  230. // The maximum buffer size needed can be gotten from get_info(); however,
  231. // the Vorbis I specification implies an absolute maximum of 4096 samples
  232. // per channel. Note that for interleaved data, you pass in the number of
  233. // shorts (the size of your array), but the return value is the number of
  234. // samples per channel, not the total number of samples.
  235. // Channel coercion rules:
  236. // Let M be the number of channels requested, and N the number of channels present,
  237. // and Cn be the nth channel; let stereo L be the sum of all L and center channels,
  238. // and stereo R be the sum of all R and center channels (channel assignment from the
  239. // vorbis spec).
  240. // M N output
  241. // 1 k sum(Ck) for all k
  242. // 2 * stereo L, stereo R
  243. // k l k > l, the first l channels, then 0s
  244. // k l k <= l, the first k channels
  245. // Note that this is not _good_ surround etc. mixing at all! It's just so
  246. // you get something useful.
  247. extern int stb_vorbis_get_samples_float_interleaved(stb_vorbis *f, int channels, float *buffer, int num_floats);
  248. extern int stb_vorbis_get_samples_float(stb_vorbis *f, int channels, float **buffer, int num_samples);
  249. // gets num_samples samples, not necessarily on a frame boundary--this requires
  250. // buffering so you have to supply the buffers. DOES NOT APPLY THE COERCION RULES.
  251. // Returns the number of samples stored per channel; it may be less than requested
  252. // at the end of the file. If there are no more samples in the file, returns 0.
  253. #ifndef STB_VORBIS_NO_INTEGER_CONVERSION
  254. extern int stb_vorbis_get_samples_short_interleaved(stb_vorbis *f, int channels, short *buffer, int num_shorts);
  255. extern int stb_vorbis_get_samples_short(stb_vorbis *f, int channels, short **buffer, int num_samples);
  256. #endif
  257. // gets num_samples samples, not necessarily on a frame boundary--this requires
  258. // buffering so you have to supply the buffers. Applies the coercion rules above
  259. // to produce 'channels' channels. Returns the number of samples stored per channel;
  260. // it may be less than requested at the end of the file. If there are no more
  261. // samples in the file, returns 0.
  262. #endif
  263. //////// ERROR CODES
  264. enum STBVorbisError
  265. {
  266. VORBIS__no_error,
  267. VORBIS_need_more_data=1, // not a real error
  268. VORBIS_invalid_api_mixing, // can't mix API modes
  269. VORBIS_outofmem, // not enough memory
  270. VORBIS_feature_not_supported, // uses floor 0
  271. VORBIS_too_many_channels, // STB_VORBIS_MAX_CHANNELS is too small
  272. VORBIS_file_open_failure, // fopen() failed
  273. VORBIS_seek_without_length, // can't seek in unknown-length file
  274. VORBIS_unexpected_eof=10, // file is truncated?
  275. VORBIS_seek_invalid, // seek past EOF
  276. // decoding errors (corrupt/invalid stream) -- you probably
  277. // don't care about the exact details of these
  278. // vorbis errors:
  279. VORBIS_invalid_setup=20,
  280. VORBIS_invalid_stream,
  281. // ogg errors:
  282. VORBIS_missing_capture_pattern=30,
  283. VORBIS_invalid_stream_structure_version,
  284. VORBIS_continued_packet_flag_invalid,
  285. VORBIS_incorrect_stream_serial_number,
  286. VORBIS_invalid_first_page,
  287. VORBIS_bad_packet_type,
  288. VORBIS_cant_find_last_page,
  289. VORBIS_seek_failed,
  290. };
  291. #ifdef __cplusplus
  292. }
  293. #endif
  294. #endif // STB_VORBIS_INCLUDE_STB_VORBIS_H
  295. //
  296. // HEADER ENDS HERE
  297. //
  298. //////////////////////////////////////////////////////////////////////////////