/src/middleware/stb_vorbis/stb_vorbis.h

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