From 74f4b1bc3b627ba4c7e03498234d88cacdfbe97b Mon Sep 17 00:00:00 2001 From: Aki Date: Wed, 29 Sep 2021 22:52:49 +0200 Subject: Squashed 'vorbis/' content from commit d22c3ab5f git-subtree-dir: vorbis git-subtree-split: d22c3ab5f633460abc2532feee60ca0892134cbf --- doc/vorbisfile/ov_open_callbacks.html | 147 ++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 doc/vorbisfile/ov_open_callbacks.html (limited to 'doc/vorbisfile/ov_open_callbacks.html') diff --git a/doc/vorbisfile/ov_open_callbacks.html b/doc/vorbisfile/ov_open_callbacks.html new file mode 100644 index 0000000..6d59e0b --- /dev/null +++ b/doc/vorbisfile/ov_open_callbacks.html @@ -0,0 +1,147 @@ + + + +Vorbisfile - function - ov_open_callbacks + + + + + + + + + +

Vorbisfile documentation

vorbisfile version 1.3.2 - 20101101

+ +

ov_open_callbacks

+ +

declared in "vorbis/vorbisfile.h";

+ +

This is an alternative function used to open and initialize an +OggVorbis_File structure when using a data source other than a file, +when its necessary to modify default file access behavior, or to +initialize a Vorbis decode from a FILE * pointer under +Windows where ov_open() cannot be used. It +allows the application to specify custom file manipulation routines +and sets up all the related decoding structures. + +

Once ov_open_callbacks() has been called, the same +OggVorbis_File struct should be passed to all the +libvorbisfile functions. Unlike ov_fopen() and ov_open(), ov_open_callbacks() may be used to +instruct vorbisfile to either automatically close or not to close the +file/data access handle in ov_clear(). +Automatic closure is disabled by passing NULL as the close callback, +or using one of the predefined callback sets that specify a NULL close +callback. The application is responsible for closing a file when a +call to ov_open_callbacks() is unsuccessful.

+ +See also Callbacks and Non-stdio I/O for +information on designing and specifying custom callback functions.

+ +

+ + + + +
+

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

Parameters

+
+
datasource
+
Pointer to a data structure allocated by the calling application, containing any state needed by the callbacks provided.
+
vf
+
A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile +functions. Once this has been called, the same OggVorbis_File +struct should be passed to all the libvorbisfile functions.
+
initial
+
Typically set to NULL. This parameter is useful if some data has already been +read from the stream 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 stream and the stream is not seekable. In this case, ibytes +should contain the length (in bytes) of the buffer. Used together with initial.
+
callbacks
+
A completed ov_callbacks struct which indicates desired custom file manipulation routines. vorbisfile.h defines several preprovided callback sets; see ov_callbacks for details.
+
+ + +

Return Values

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

    + +

    Notes

    +
    + +
    [a] Windows and use as an ov_open() substitute

    Windows +applications should not use ov_open() due +to the likelihood of CRT linking +mismatches and runtime protection faults +[ov_open:a]. ov_open_callbacks() is a safe substitute; specifically: + +

    ov_open_callbacks(f, vf, initial, ibytes, OV_CALLBACKS_DEFAULT);
+
    + +... provides exactly the same functionality as ov_open() but will always work correctly under +Windows, regardless of linking setup details.

    + +

    [b] Threaded decode

    +

    If your decoder is threaded, it is recommended that you NOT call +ov_open_callbacks() +in the main control thread--instead, call ov_open_callbacks() in your decode/playback +thread. This is important because ov_open_callbacks() may be a fairly time-consuming +call, given that the full structure of the file is determined at this point, +which may require reading large parts of the file under certain circumstances +(determining all the logical bitstreams in one physical bitstream, for +example). See Thread Safety for other information on using libvorbisfile with threads. +

    + +

    [c] Mixed media streams

    +

    +As of Vorbisfile release 1.2.0, Vorbisfile is able to access the +Vorbis content in mixed-media Ogg streams, not just Vorbis-only +streams. For example, Vorbisfile may be used to open and access the +audio from an Ogg stream consisting of Theora video and Vorbis audio. +Vorbisfile 1.2.0 decodes the first logical audio stream of each +physical stream section.

    + +

    [d] Faster testing for Vorbis files

    +

    ov_test() and ov_test_callbacks() provide less +computationally expensive ways to test a file for Vorbisness, but +require more setup code.

    + +

    + +

    +
    + + + + + + + + +

    copyright © 2000-2010 Xiph.Org

    Ogg Vorbis

    Vorbisfile documentation

    vorbisfile version 1.3.2 - 20101101

    + + + + -- cgit v1.1