Mercurial > hg > sv-dependency-builds

comparison src/libvorbis-1.3.3/doc/vorbisfile/initialization.html @ 1:05aa0afa9217

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bring in flac, ogg, vorbis
author Chris Cannam
date Tue, 19 Mar 2013 17:37:49 +0000
parents
children
comparison
equal deleted inserted replaced
0:c7265573341e 1:05aa0afa9217
1 <html>
2
3 <head>
4 <title>Vorbisfile - Setup/Teardown</title>
5 <link rel=stylesheet href="style.css" type="text/css">
6 </head>
7
8 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
9 <table border=0 width=100%>
10 <tr>
11 <td><p class=tiny>Vorbisfile documentation</p></td>
12 <td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
13 </tr>
14 </table>
15
16 <H1>Setup/Teardown</h1> <p>In order to decode audio using
17 libvorbisfile, a bitstream containing Vorbis audio must be properly
18 initialized before decoding and cleared when decoding is finished.
19 The simplest possible case is to use <a
20 href="ov_fopen.html">ov_fopen()</a> to open the file for access, check
21 it for Vorbis content, and prepare it for playback. A successful <a
22 href="../libvorbis/return.html">return code</a> from <a
23 href="ov_fopen.html">ov_fopen()</a> indicates the file is ready for use.
24 Once the file is no longer needed, <a
25 href="ov_clear.html">ov_clear()</a> is used to close the file and
26 deallocate decoding resources.<p>
27
28 On systems other than Windows<a href="ov_open.html#winfoot">[a]</a>, an
29 application may also open a file itself using <tt>fopen()</tt>, then pass the
30 <tt>FILE *</tt> to libvorbisfile using <a
31 href="ov_open.html">ov_open()</a>. </b>Do not</b> call
32 <tt>fclose()</tt> on a file handle successfully submitted to <a
33 href="ov_open.html">ov_open()</a>; libvorbisfile does this in the <a
34 href="ov_clear.html">ov_clear()</a> call.<p>
35
36 An application that requires more setup flexibility may open a data
37 stream using <a href="ov_open_callbacks.html">ov_open_callbacks()</a>
38 to change default libvorbis behavior or specify non-stdio data access
39 mechanisms.<p>
40
41 <p>
42 All libvorbisfile initialization and deallocation routines are declared in "vorbis/vorbisfile.h".
43 <p>
44
45 <table border=1 color=black width=50% cellspacing=0 cellpadding=7>
46 <tr bgcolor=#cccccc>
47 <td><b>function</b></td>
48 <td><b>purpose</b></td>
49 </tr>
50 <tr valign=top>
51 <td><a href="ov_fopen.html">ov_fopen</a></td>
52 <td>Opens a file and initializes the Ogg Vorbis bitstream with default values. This must be called before other functions in the library may be
53 used.</td>
54 </tr>
55 <tr valign=top>
56 <td><a href="ov_open.html">ov_open</a></td>
57 <td>Initializes the Ogg Vorbis bitstream with default values from a passed in file handle. This must be called before other functions in the library may be
58 used. <a href="#winfoot"><em>Do not use this call under Windows [a];</em></a> Use <a href="ov_fopen.html">ov_fopen()</a> or <a href="ov_open_callbacks.html">ov_open_callbacks()</a> instead.</td>
59 </tr>
60 <tr valign=top>
61 <td><a href="ov_open_callbacks.html">ov_open_callbacks</a></td>
62 <td>Initializes the Ogg Vorbis bitstream from a file handle and custom file/bitstream manipulation routines. Used instead of <a href="ov_open.html">ov_open()</a> or <a href="ov_fopen.html">ov_fopen()</a> when altering or replacing libvorbis's default stdio I/O behavior, or when a bitstream must be initialized from a <tt>FILE *</tt> under Windows.</td>
63 </tr>
64
65 <tr valign=top>
66 <td><a href="ov_test.html">ov_test</a></td>
67
68 <td>Partially opens a file just far enough to determine if the file
69 is an Ogg Vorbis file or not. A successful return indicates that the
70 file appears to be an Ogg Vorbis file, but the <a
71 href="OggVorbis_File.html">OggVorbis_File</a> struct is not yet fully
72 initialized for actual decoding. After a <a href="../libvorbis/return.html">successful return</a>, the file
73 may be closed using <a href="ov_clear.html">ov_clear()</a> or fully
74 opened for decoding using <a
75 href="ov_test_open.html">ov_test_open()</a>.<p> This call is intended to
76 be used as a less expensive file open test than a full <a
77 href="ov_open.html">ov_open()</a>.<p>
78 Note that libvorbisfile owns the passed in file resource is it returns success; do not <tt>fclose()</tt> files owned by libvorbisfile.</td>
79
80 </tr>
81 <tr valign=top>
82 <td><a href="ov_test_callbacks.html">ov_test_callbacks</a></td>
83 <td>As above but allowing application-define I/O callbacks.<p>
84 Note that libvorbisfile owns the passed in file resource is it returns success; do not <tt>fclose()</tt> files owned by libvorbisfile.</td>
85
86 </tr>
87 <tr valign=top>
88 <td><a href="ov_test_open.html">ov_test_open</a><td>
89 Finish opening a file after a successful call to <a href="ov_test.html">ov_test()</a> or <a href="ov_test_callbacks.html">ov_test_callbacks()</a>.</td>
90 </tr>
91 <tr valign=top>
92 <td><a href="ov_clear.html">ov_clear</a></td> <td>Closes the
93 bitstream and cleans up loose ends. Must be called when
94 finished with the bitstream. After return, the <a
95 href="OggVorbis_File.html">OggVorbis_File</a> struct is
96 invalid and may not be used before being initialized again
97 before begin reinitialized.
98
99 </td>
100 </tr>
101 </table>
102
103 <br><br>
104 <hr noshade>
105
106 <table border=0 width=100%>
107 <tr valign=top>
108 <td><p class=tiny>copyright &copy; 2000-2010 Xiph.Org</p></td>
109 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
110 </tr><tr>
111 <td><p class=tiny>Vorbisfile documentation</p></td>
112 <td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
113 </tr>
114 </table>
115
116 </body>
117
118 </html>