Mercurial > hg > sv-dependency-builds

comparison src/libvorbis-1.3.3/doc/vorbisfile/OggVorbis_File.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 - datatype - OggVorbis_File</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>OggVorbis_File</h1>
17
18 <p><i>declared in "vorbis/vorbisfile.h"</i></p>
19
20 <p>
21 The OggVorbis_File structure defines an Ogg Vorbis file.
22 <p>
23
24 This structure is used in all libvorbisfile routines. Before it can
25 be used, it must be initialized by <a
26 href="ov_open.html">ov_open()</a>, <a
27 href="ov_fopen.html">ov_fopen()</a>, or <a
28 href="ov_open_callbacks.html">ov_open_callbacks()</a>. <em>Important
29 Note:</em> The use of <a href="ov_open.html">ov_open()</a> is
30 discouraged under Windows due to a peculiarity of Windows linking
31 convention; use <a href="ov_fopen.html">ov_fopen()</a> or <a
32 href="ov_open_callbacks.html">ov_open_callbacks()</a> instead. This
33 caution only applies to Windows; use of <a
34 href="ov_open.html">ov_open()</a> is appropriate for all other
35 platforms. See the <a href="ov_open.html">ov_open()</a> page for more
36 information.
37
38 <p>
39 After use, the OggVorbis_File structure must be deallocated with a
40 call to <a href="ov_clear.html">ov_clear()</a>.
41
42 <p>
43 Note that once a file handle is passed to a successful <a
44 href="ov_open.html">ov_open()</a> call, the handle is owned by
45 libvorbisfile and will be closed by libvorbisfile later during the
46 call to <a href="ov_clear.html">ov_clear()</a>. The handle should not
47 be used or closed outside of the libvorbisfile API. Similarly, files
48 opened by <a href="ov_fopen.html">ov_fopen()</a> will also be closed
49 internally by vorbisfile in <a href="ov_clear.html">ov_clear()</a>.<p>
50
51 <a href="ov_open_callbacks.html">ov_open_callbacks()</a> allows the
52 application to choose whether libvorbisfile will or will not close the
53 handle in <a href="ov_clear.html">ov_clear()</a>; see the <a
54 href="ov_open_callbacks.html">ov_open_callbacks()</a> page for more information.<p>
55
56 If a call to <a href="ov_open.html">ov_open()</a> or <a
57 href="ov_open_callbacks.html">ov_open_callbacks()</a> <b>fails</b>,
58 libvorbisfile does <b>not</b> assume ownership of the handle and the
59 application is expected to close it if necessary. A failed <a
60 href="ov_fopen.html">ov_fopen()</a> call will internally close the
61 file handle if the open process fails.<p>
62
63 <br><br>
64 <table border=0 width=100% color=black cellspacing=0 cellpadding=7>
65 <tr bgcolor=#cccccc>
66 <td>
67 <pre><b>typedef struct {
68 void *datasource; /* Pointer to a FILE *, etc. */
69 int seekable;
70 ogg_int64_t offset;
71 ogg_int64_t end;
72 ogg_sync_state oy;
73
74 /* If the FILE handle isn't seekable (eg, a pipe), only the current
75 stream appears */
76 int links;
77 ogg_int64_t *offsets;
78 ogg_int64_t *dataoffsets;
79 long *serialnos;
80 ogg_int64_t *pcmlengths;
81 vorbis_info *vi;
82 vorbis_comment *vc;
83
84 /* Decoding working state local storage */
85 ogg_int64_t pcm_offset;
86 int ready_state;
87 long current_serialno;
88 int current_link;
89
90 ogg_int64_t bittrack;
91 ogg_int64_t samptrack;
92
93 ogg_stream_state os; /* take physical pages, weld into a logical
94 stream of packets */
95 vorbis_dsp_state vd; /* central working state for the packet->PCM decoder */
96 vorbis_block vb; /* local working space for packet->PCM decode */
97
98 <a href="ov_callbacks.html">ov_callbacks</a> callbacks;
99
100 } OggVorbis_File;</b></pre>
101 </td>
102 </tr>
103 </table>
104
105 <h3>Relevant Struct Members</h3>
106 <dl>
107 <dt><i>datasource</i></dt>
108
109 <dd>Pointer to file or other ogg source. When using stdio based
110 file/stream access, this field contains a <tt>FILE</tt> pointer. When using
111 custom IO via callbacks, libvorbisfile treats this void pointer as a
112 black box only to be passed to the callback routines provided by the
113 application.</dd>
114
115 <dt><i>seekable</i></dt>
116 <dd>Read-only int indicating whether file is seekable. E.g., a physical file is seekable, a pipe isn't.</dd>
117 <dt><i>links</i></dt>
118 <dd>Read-only int indicating the number of logical bitstreams within the physical bitstream.</dd>
119 <dt><i>ov_callbacks</i></dt>
120 <dd>Collection of file manipulation routines to be used on this data source. When using stdio/FILE access via <a href="ov_open.html">ov_open()</a>, the callbacks will be filled in with stdio calls or wrappers to stdio calls.</dd>
121 </dl>
122
123 <br><br>
124 <hr noshade>
125 <table border=0 width=100%>
126 <tr valign=top>
127 <td><p class=tiny>copyright &copy; 2000-2010 Xiph.Org</p></td>
128 <td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
129 </tr><tr>
130 <td><p class=tiny>Vorbisfile documentation</p></td>
131 <td align=right><p class=tiny>vorbisfile version 1.3.2 - 20101101</p></td>
132 </tr>
133 </table>
134
135 </body>
136
137 </html>