Chris@1: Chris@1: Chris@1: Chris@1: Vorbisfile - function - ov_read Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1:

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

Chris@1: Chris@1:

ov_read()

Chris@1: Chris@1:

declared in "vorbis/vorbisfile.h";

Chris@1: Chris@1:

Chris@1: This is the main function used to decode a Vorbis file within a Chris@1: loop. It returns up to the specified number of bytes of decoded PCM audio Chris@1: in the requested endianness, signedness, and word size. If the audio is Chris@1: multichannel, the channels are interleaved in the output buffer. Chris@1: If the passed in buffer is large, ov_read() will not fill Chris@1: it; the passed in buffer size is treated as a limit and Chris@1: not a request. Chris@1: Chris@1:

The output channels are in stream order and not remapped. Vorbis I Chris@1: defines channel order as follows: Chris@1: Chris@1:

one channel - the stream is monophonic Chris@1:
two channels - the stream is stereo. channel order: left, right Chris@1:
three channels - the stream is a 1d-surround encoding. channel order: left, Chris@1: center, right Chris@1:
four channels - the stream is quadraphonic surround. channel order: front left, Chris@1: front right, rear left, rear right Chris@1:
five channels - the stream is five-channel surround. channel order: front left, Chris@1: center, front right, rear left, rear right Chris@1:
six channels - the stream is 5.1 surround. channel order: front left, center, Chris@1: front right, rear left, rear right, LFE Chris@1:
seven channels - the stream is 6.1 surround. channel order: front left, center, Chris@1: front right, side left, side right, rear center, LFE Chris@1:
eight channels - the stream is 7.1 surround. channel order: front left, center, Chris@1: front right, side left, side right, rear left, rear right, Chris@1: LFE Chris@1:
greater than eight channels - channel use and order is undefined Chris@1:

Chris@1: Chris@1:

Note that up to this point, the Vorbisfile API could more or less hide the Chris@1: multiple logical bitstream nature of chaining from the toplevel Chris@1: application if the toplevel application didn't particularly care. Chris@1: However, when reading audio back, the application must be aware Chris@1: that multiple bitstream sections do not necessarily use the same Chris@1: number of channels or sampling rate.

ov_read() passes Chris@1: back the index of the sequential logical bitstream currently being Chris@1: decoded (in *bitstream) along with the PCM data in order Chris@1: that the toplevel application can handle channel and/or sample Chris@1: rate changes. This number will be incremented at chaining Chris@1: boundaries even for non-seekable streams. For seekable streams, it Chris@1: represents the actual chaining index within the physical bitstream. Chris@1:

Chris@1: Chris@1:

Chris@1: Chris@1: Chris@1: Chris@1: Chris@1:
Chris@1:
Chris@1: long ov_read(OggVorbis_File *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream); Chris@1:
Chris@1:
Chris@1: Chris@1:

Parameters

Chris@1:

vf: A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile Chris@1: functions.
buffer: A pointer to an output buffer. The decoded output is inserted into this buffer.
length: Number of bytes to be read into the buffer. Should be the same size as the buffer. A typical value is 4096.
bigendianp: Specifies big or little endian byte packing. 0 for little endian, 1 for b Chris@1: ig endian. Typical value is 0.
word: Specifies word size. Possible arguments are 1 for 8-bit samples, or 2 or Chris@1: 16-bit samples. Typical value is 2.
sgned: Signed or unsigned data. 0 for unsigned, 1 for signed. Typically 1.
bitstream: A pointer to the number of the current logical bitstream.

Chris@1: Chris@1: Chris@1:

Return Values

Chris@1:

Chris@1:
Chris@1:
OV_HOLE
Chris@1:
indicates there was an interruption in the data. Chris@1:
(one of: garbage between pages, loss of sync followed by Chris@1: recapture, or a corrupt page)
Chris@1:
OV_EBADLINK
Chris@1:
indicates that an invalid stream section was supplied to Chris@1: libvorbisfile, or the requested link is corrupt.
Chris@1:
OV_EINVAL
Chris@1:
indicates the initial file headers couldn't be read or Chris@1: are corrupt, or that the initial open call for vf Chris@1: failed.
Chris@1:
0
Chris@1:
indicates EOF
Chris@1:
n
Chris@1:
indicates actual number of bytes read. ov_read() will Chris@1: decode at most one vorbis packet per invocation, so the value Chris@1: returned will generally be less than length. Chris@1:
Chris@1:

Chris@1: Chris@1:

Notes

Chris@1:

Typical usage: Chris@1:

Chris@1: bytes_read = ov_read(&vf, Chris@1: buffer, 4096,0,2,1,&current_section) Chris@1:

Chris@1: Chris@1: This reads up to 4096 bytes into a buffer, with signed 16-bit Chris@1: little-endian samples. Chris@1:

Chris@1: Chris@1: Chris@1: Chris@1:

Chris@1:

Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1: Chris@1:

copyright © 2000-2010 Xiph.Org	Ogg Vorbis
Vorbisfile documentation	vorbisfile version 1.3.2 - 20101101

Chris@1: Chris@1: Chris@1: Chris@1: