cannam@86: cannam@86: cannam@86: cannam@86: Vorbisfile - function - ov_read cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

cannam@86: cannam@86:

ov_read()

cannam@86: cannam@86:

declared in "vorbis/vorbisfile.h";

cannam@86: cannam@86:

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

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

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

cannam@86: cannam@86:

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

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

cannam@86: cannam@86:

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

Parameters

cannam@86:

vf: A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile cannam@86: 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 cannam@86: ig endian. Typical value is 0.
word: Specifies word size. Possible arguments are 1 for 8-bit samples, or 2 or cannam@86: 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.

cannam@86: cannam@86: cannam@86:

Return Values

cannam@86:

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

cannam@86: cannam@86:

Notes

cannam@86:

Typical usage: cannam@86:

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

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

cannam@86: cannam@86: cannam@86: cannam@86:

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:

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

cannam@86: cannam@86: cannam@86: cannam@86: