From 2016c5ffe2503db33026280b4126a2ba1994cc34 Mon Sep 17 00:00:00 2001 From: Jack Moffitt Date: Wed, 19 Dec 2001 02:00:47 +0000 Subject: [PATCH] vorbisfile docs updated for rc3. svn path=/trunk/vorbis/; revision=2833 --- doc/vorbisfile/Makefile.am | 4 +- doc/vorbisfile/OggVorbis_File.html | 8 +-- doc/vorbisfile/decoding.html | 10 ++-- doc/vorbisfile/initialization.html | 12 +++++ doc/vorbisfile/ov_read_float.html | 96 +++++++++++++++++++++++++++++++++++ doc/vorbisfile/ov_test.html | 89 ++++++++++++++++++++++++++++++++ doc/vorbisfile/ov_test_callbacks.html | 88 ++++++++++++++++++++++++++++++++ doc/vorbisfile/ov_test_open.html | 75 +++++++++++++++++++++++++++ doc/vorbisfile/reference.html | 10 ++-- 9 files changed, 381 insertions(+), 11 deletions(-) create mode 100644 doc/vorbisfile/ov_read_float.html create mode 100644 doc/vorbisfile/ov_test.html create mode 100644 doc/vorbisfile/ov_test_callbacks.html create mode 100644 doc/vorbisfile/ov_test_open.html diff --git a/doc/vorbisfile/Makefile.am b/doc/vorbisfile/Makefile.am index 702543a..ac3ef87 100644 --- a/doc/vorbisfile/Makefile.am +++ b/doc/vorbisfile/Makefile.am @@ -14,6 +14,8 @@ doc_DATA = OggVorbis_File.html chaining_example_c.html chainingexample.html\ ov_serialnumber.html ov_streams.html ov_time_seek.html\ ov_time_tell.html ov_time_total.html overview.html reference.html\ seekexample.html seeking.html seeking_test_c.html seekingexample.html\ - style.css vorbis_comment.html vorbis_info.html vorbisfile_example_c.html + style.css vorbis_comment.html vorbis_info.html\ + vorbisfile_example_c.html ov_read_float.html ov_test.html\ + ov_test_open.html ov_test_callbacks.html EXTRA_DIST = $(doc_DATA) diff --git a/doc/vorbisfile/OggVorbis_File.html b/doc/vorbisfile/OggVorbis_File.html index 6748dee..a00e26b 100644 --- a/doc/vorbisfile/OggVorbis_File.html +++ b/doc/vorbisfile/OggVorbis_File.html @@ -9,7 +9,7 @@ - +

vorbisfile documentation

vorbisfile version 1.25 - 20000615

vorbisfile - 20011218
@@ -47,7 +47,7 @@ After use, the OggVorbis_File structure must be deallocated with a call to - + - +

copyright © 2000 vorbis team

copyright © 2001 vorbis team

Ogg Vorbis
team@vorbis.org

vorbisfile documentation

vorbisfile version 1.25 - 20000615

vorbisfile - 20011218
diff --git a/doc/vorbisfile/decoding.html b/doc/vorbisfile/decoding.html index bc35fd7..afb25c8 100644 --- a/doc/vorbisfile/decoding.html +++ b/doc/vorbisfile/decoding.html @@ -9,7 +9,7 @@ - +

vorbisfile documentation

vorbisfile version 1.25 - 20000615

vorbisfile - 20011218
@@ -30,17 +30,21 @@ All the vorbisfile decoding routines are declared in "vorbis/vorbisfile.h OggVorbis_File structure, which must have been initialized by a previous call to ov_open(). + + ov_read + This function decodes to floats instead of integer samples. +

- + - +

copyright © 2000 Xiphophorus

copyright © 2001 Xiphophorus

www.vorbis.org
team@icecast.org

vorbisfile documentation

vorbisfile version 1.25 - 20000615

vorbisfile - 20011218
diff --git a/doc/vorbisfile/initialization.html b/doc/vorbisfile/initialization.html index be09f65..fd0c5cc 100644 --- a/doc/vorbisfile/initialization.html +++ b/doc/vorbisfile/initialization.html @@ -37,6 +37,18 @@ All the vorbisfile initialization and deallocation routines are declared ov_clear Closes the bitstream and cleans up loose ends. Must be called when we're done with the bitstream. + +ov_test +Partially opens a vorbis file for testing. + + +ov_test_callbacks +Same as above but useful for non-files like streams. + + +ov_test_open +Finish open a file opened for testing. +

diff --git a/doc/vorbisfile/ov_read_float.html b/doc/vorbisfile/ov_read_float.html new file mode 100644 index 0000000..496f964 --- /dev/null +++ b/doc/vorbisfile/ov_read_float.html @@ -0,0 +1,96 @@ + + + +vorbisfile - function - ov_read_float + + + + + + + + + +

vorbisfile documentation

vorbisfile - 20011218

+ +

ov_read_float()

+ +

declared in "vorbis/vorbisfile.h";

+ +

+ This is the function used to decode a Vorbis file within a loop, but + returns samples in native float format instead of in integer formats. +

+ For more information on how ov_read_float() deals with the complex issues + of chaining, etc, refer to the documentation for ov_read(). +

+ +

+ + + + +
+

+long ov_read(OggVorbis_File *vf, float ***pcm_channels, int *bitstream);
+
+
+ +

Parameters

+
+
vf
+
A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile +functions.
+
pcm_channels
+
A pointer to an output buffer. The pointer will be set to the decoded output buffer.
+
bitstream
+
A pointer to the number of the current logical bitstream.
+
+ + +

Return Values

+
+
+
OV_HOLE
+
indicates there was an interruption in the data. +
(one of: garbage between pages, loss of sync followed by + recapture, or a corrupt page)
+
OV_EBADLINK
+
indicates that an invalid stream section was supplied to + libvorbisfile, or the requested link is corrupt.
+
0
+
indicates EOF
+
n
+
indicates actual number of bytes read. ov_read() will + decode at most one vorbis packet per invocation, so the value + returned will generally be less than length. +
+
+ +

Notes

+

Typical usage: +

+float **pcm; +bytes_read = ov_read_float(&vf,pcm,&current_section) +
+ +This decodes one packets worth of float samples. +

+ +
+

+
+ + + + + + + + +

copyright © 2001 vorbis team

Ogg Vorbis
team@vorbis.org

vorbisfile documentation

vorbisfile - 20011218

+ + + + + diff --git a/doc/vorbisfile/ov_test.html b/doc/vorbisfile/ov_test.html new file mode 100644 index 0000000..52f0fe8 --- /dev/null +++ b/doc/vorbisfile/ov_test.html @@ -0,0 +1,89 @@ + + + +vorbisfile - function - ov_test + + + + + + + + + +

vorbisfile documentation

vorbisfile - 20011218

+ +

ov_test

+ +

declared in "vorbis/vorbisfile.h";

+ +

+This partially opens a vorbis file to test for Vorbis-ness. It loads +the headers for the first chain, and tests for seekability (but does not seek). +Use ov_test_open() to finish opening the file +or ov_clear to close/free it. +

+ + + + + +
+

+int ov_test(FILE *f,OggVorbis_File *vf,char *initial,long ibytes);
+
+
+ +

Parameters

+
+
f
+
File pointer to an already opened file +or pipe (it need not be seekable--though this obviously restricts what +can be done with the bitstream).
+
vf
+
A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile +functions. Once this has been called, the same OggVorbis_File +struct should be passed to all the vorbisfile functions.
+
initial
+
Typically set to NULL. This parameter is useful if some data has already been +read from the file and the stream is not seekable. It is used in conjunction with ibytes. In this case, initial +should be a pointer to a buffer containing the data read.
+
ibytes
+
Typically set to 0. This parameter is useful if some data has already been +read from the file and the stream is not seekable. In this case, ibytes +should contain the length (in bytes) of the buffer. Used together with initial
+
+ + +

Return Values

+
+
  • +0 for success
    • + +
  • less than zero for failure:
    • + +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2001 vorbis team

    Ogg Vorbis
    team@vorbis.org

    vorbisfile documentation

    vorbisfile - 20011218

    + + + + + diff --git a/doc/vorbisfile/ov_test_callbacks.html b/doc/vorbisfile/ov_test_callbacks.html new file mode 100644 index 0000000..604215c --- /dev/null +++ b/doc/vorbisfile/ov_test_callbacks.html @@ -0,0 +1,88 @@ + + + +vorbisfile - function - ov_test_callbacks + + + + + + + + + +

    vorbisfile documentation

    vorbisfile - 20011218

    + +

    ov_test_callbacks

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    This is an alternative function used to open and test an OggVorbis_File +structure when using a data source other than a file. It allows you to specify custom file manipulation routines and sets up all the related decoding structure. +

    Once this has been called, the same OggVorbis_File +struct should be passed to all the vorbisfile functions. +

    +

    + + + + +
    +
    
+int ov_test_callbacks(void *datasource, OggVorbis_File *vf, char *initial, long ibytes, ov_callbacks callbacks);
+
    +
    + +

    Parameters

    +
    +
    f
    +
    File pointer to an already opened file +or pipe (it need not be seekable--though this obviously restricts what +can be done with the bitstream).
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile +functions. Once this has been called, the same OggVorbis_File +struct should be passed to all the vorbisfile functions.
    +
    initial
    +
    Typically set to NULL. This parameter is useful if some data has already been +read from the file and the stream is not seekable. It is used in conjunction with ibytes. In this case, initial +should be a pointer to a buffer containing the data read.
    +
    ibytes
    +
    Typically set to 0. This parameter is useful if some data has already been +read from the file and the stream is not seekable. In this case, ibytes +should contain the length (in bytes) of the buffer. Used together with initial.
    +
    callbacks
    +
    Pointer to a completed ov_callbacks struct which indicates desired custom file manipulation routines.
    +
    + + +

    Return Values

    +
    +
  • +0 for success
    • +
  • less than zero for failure:
    • + +
    +

    + +

    + + + + + + + + +

    copyright © 2001 vorbis team

    Ogg Vorbis
    team@vorbis.org

    vorbisfile documentation

    vorbisfile - 20011218

    + + + + + diff --git a/doc/vorbisfile/ov_test_open.html b/doc/vorbisfile/ov_test_open.html new file mode 100644 index 0000000..c2fdbb9 --- /dev/null +++ b/doc/vorbisfile/ov_test_open.html @@ -0,0 +1,75 @@ + + + +vorbisfile - function - ov_test_open + + + + + + + + + +

    vorbisfile documentation

    vorbisfile - 20011218

    + +

    ov_test_open

    + +

    declared in "vorbis/vorbisfile.h";

    + +

    +Finish opening a file partially opened with ov_test() +or ov_test_callbacks(). +

    + + + + + +
    +
    
+int ov_test_open(OggVorbis_File *vf);
+
    +
    + +

    Parameters

    +
    +
    vf
    +
    A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile +functions. Once this has been called, the same OggVorbis_File +struct should be passed to all the vorbisfile functions.
    +
    + + +

    Return Values

    +
    +
  • +0 for success
    • + +
  • less than zero for failure:
    • + +
    +

    + +

    +

    + + + + + + + + +

    copyright © 2001 vorbis team

    Ogg Vorbis
    team@vorbis.org

    vorbisfile documentation

    vorbisfile - 20011218

    + + + + + diff --git a/doc/vorbisfile/reference.html b/doc/vorbisfile/reference.html index 0649e22..770baca 100644 --- a/doc/vorbisfile/reference.html +++ b/doc/vorbisfile/reference.html @@ -9,7 +9,7 @@ - +

    vorbisfile documentation

    vorbisfile version 1.25 - 20000615

    vorbisfile - 20011218
    @@ -26,9 +26,13 @@ ov_open()
    ov_open_callbacks()
    ov_clear()
    +ov_test()
    +ov_test_callbacks()
    +ov_test_open()

    Decoding
    ov_read()
    +ov_read_float()

    Seeking
    ov_raw_seek()
    @@ -53,11 +57,11 @@
    - + - +

    copyright © 2000 vorbis team

    copyright © 2001 vorbis team

    Ogg Vorbis
    team@vorbis.org

    vorbisfile documentation

    vorbisfile version 1.25 - 20000615

    vorbisfile - 20011218
    -- 2.7.4