Mercurial > hg > sv-dependency-builds

annotate src/libvorbis-1.3.3/doc/vorbisfile/ov_fopen.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
rev   line source
Chris@1 1 <html>
Chris@1 2
Chris@1 3 <head>
Chris@1 4 <title>Vorbisfile - function - ov_fopen</title>
Chris@1 5 <link rel=stylesheet href="style.css" type="text/css">
Chris@1 6 </head>
Chris@1 7
Chris@1 8 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
Chris@1 9 <table border=0 width=100%>
Chris@1 10 <tr>
Chris@1 11 <td><p class=tiny>Vorbisfile documentation</p></td>
Chris@1 12 <td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
Chris@1 13 </tr>
Chris@1 14 </table>
Chris@1 15
Chris@1 16 <h1>ov_fopen</h1>
Chris@1 17
Chris@1 18 <p><i>declared in "vorbis/vorbisfile.h";</i></p>
Chris@1 19
Chris@1 20 <p>This is the simplest function used to open and initialize an OggVorbis_File
Chris@1 21 structure. It sets up all the related decoding structure.
Chris@1 22 <p>The first argument is a file path suitable
Chris@1 23 for passing to fopen(). <tt>vf</tt> should be a pointer to an empty
Chris@1 24 OggVorbis_File structure -- this is used for ALL the externally visible
Chris@1 25 libvorbisfile functions. Once this has been called, the same <a
Chris@1 26 href="OggVorbis_File.html">OggVorbis_File</a> struct should be passed
Chris@1 27 to all the libvorbisfile functions.
Chris@1 28 <p>The <tt>vf</tt> structure initialized using ov_fopen() must
Chris@1 29 eventually be cleaned using <a href="ov_clear.html">ov_clear()</a>.
Chris@1 30
Chris@1 31 <p>
Chris@1 32 It is often useful to call <tt>ov_fopen()</tt> simply to determine
Chris@1 33 whether a given file is a Vorbis bitstream. If the <tt>ov_fopen()</tt>
Chris@1 34 call fails, then the file is either inaccessable (errno is set) or not
Chris@1 35 recognizable as Vorbis (errno unchanged). If the call succeeds but
Chris@1 36 the initialized <tt>vf</tt> structure will not be used, the
Chris@1 37 application is responsible for calling <a
Chris@1 38 href="ov_clear.html">ov_clear()</a> to clear the decoder's buffers and
Chris@1 39 close the file.<p>
Chris@1 40
Chris@1 41 <br><br>
Chris@1 42 <table border=0 color=black cellspacing=0 cellpadding=7>
Chris@1 43 <tr bgcolor=#cccccc>
Chris@1 44 <td>
Chris@1 45 <pre><b>
Chris@1 46 int ov_fopen(char *path,<a href="OggVorbis_File.html">OggVorbis_File</a> *vf);
Chris@1 47 </b></pre>
Chris@1 48 </td>
Chris@1 49 </tr>
Chris@1 50 </table>
Chris@1 51
Chris@1 52 <h3>Parameters</h3>
Chris@1 53 <dl>
Chris@1 54 <dt><i>path</i></dt>
Chris@1 55 <dd>Null terminated string containing a file path suitable for passing to <tt>fopen()</tt>.
Chris@1 56 </dd>
Chris@1 57 <dt><i>vf</i></dt>
Chris@1 58 <dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
Chris@1 59 functions. Once this has been called, the same <tt>OggVorbis_File</tt>
Chris@1 60 struct should be passed to all the libvorbisfile functions.</dd>
Chris@1 61 </dl>
Chris@1 62
Chris@1 63
Chris@1 64 <h3>Return Values</h3>
Chris@1 65 <blockquote>
Chris@1 66 <li>0 indicates success</li>
Chris@1 67
Chris@1 68 <li>less than zero for failure:</li>
Chris@1 69 <ul>
Chris@1 70 <li>OV_EREAD - A read from media returned an error.</li>
Chris@1 71 <li>OV_ENOTVORBIS - Bitstream does not contain any Vorbis data.</li>
Chris@1 72 <li>OV_EVERSION - Vorbis version mismatch.</li>
Chris@1 73 <li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li>
Chris@1 74 <li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
Chris@1 75 </ul>
Chris@1 76 </blockquote>
Chris@1 77 <p>
Chris@1 78
Chris@1 79 <h3>Notes</h3>
Chris@1 80 <dl>
Chris@1 81
Chris@1 82 <dt><b>[a] Threaded decode</b><p>
Chris@1 83 <dd>If your decoder is threaded, it is recommended that you NOT call
Chris@1 84 <tt>ov_open_callbacks()</tt>
Chris@1 85 in the main control thread--instead, call <tt>ov_open_callbacks()</tt> in your decode/playback
Chris@1 86 thread. This is important because <tt>ov_open_callbacks()</tt> may be a fairly time-consuming
Chris@1 87 call, given that the full structure of the file is determined at this point,
Chris@1 88 which may require reading large parts of the file under certain circumstances
Chris@1 89 (determining all the logical bitstreams in one physical bitstream, for
Chris@1 90 example). See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads.
Chris@1 91 <p>
Chris@1 92
Chris@1 93 <dt><b>[b] Mixed media streams</b><p>
Chris@1 94 <dd>
Chris@1 95 As of Vorbisfile release 1.2.0, Vorbisfile is able to access the
Chris@1 96 Vorbis content in mixed-media Ogg streams, not just Vorbis-only
Chris@1 97 streams. For example, Vorbisfile may be used to open and access the
Chris@1 98 audio from an Ogg stream consisting of Theora video and Vorbis audio.
Chris@1 99 Vorbisfile 1.2.0 decodes the first logical audio stream of each
Chris@1 100 physical stream section.<p>
Chris@1 101
Chris@1 102 <dt><b>[c] Faster testing for Vorbis files</b><p>
Chris@1 103 <dd><a href="ov_test.html">ov_test()</a> and <a
Chris@1 104 href="ov_test_callbacks.html">ov_test_callbacks()</a> provide less
Chris@1 105 computationally expensive ways to test a file for Vorbisness, but
Chris@1 106 require more setup code.<p>
Chris@1 107
Chris@1 108 </dl>
Chris@1 109
Chris@1 110 <br><br>
Chris@1 111 <hr noshade>
Chris@1 112 <table border=0 width=100%>
Chris@1 113 <tr valign=top>
Chris@1 114 <td><p class=tiny>copyright &copy; 2000-2010 Xiph.Org</p></td>
Chris@1 115 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
Chris@1 116 </tr><tr>
Chris@1 117 <td><p class=tiny>Vorbisfile documentation</p></td>
Chris@1 118 <td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
Chris@1 119 </tr>
Chris@1 120 </table>
Chris@1 121
Chris@1 122 </body>
Chris@1 123
Chris@1 124 </html>