Mercurial > hg > sv-dependency-builds

annotate src/libvorbis-1.3.3/doc/programming.html @ 86:98c1576536ae

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bring in flac, ogg, vorbis
author Chris Cannam <cannam@all-day-breakfast.com>
date Tue, 19 Mar 2013 17:37:49 +0000
parents
children
rev   line source
cannam@86 1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
cannam@86 2 <html>
cannam@86 3 <head>
cannam@86 4
cannam@86 5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-15"/>
cannam@86 6 <title>Ogg Vorbis Documentation</title>
cannam@86 7
cannam@86 8 <style type="text/css">
cannam@86 9 body {
cannam@86 10 margin: 0 18px 0 18px;
cannam@86 11 padding-bottom: 30px;
cannam@86 12 font-family: Verdana, Arial, Helvetica, sans-serif;
cannam@86 13 color: #333333;
cannam@86 14 font-size: .8em;
cannam@86 15 }
cannam@86 16
cannam@86 17 a {
cannam@86 18 color: #3366cc;
cannam@86 19 }
cannam@86 20
cannam@86 21 img {
cannam@86 22 border: 0;
cannam@86 23 }
cannam@86 24
cannam@86 25 #xiphlogo {
cannam@86 26 margin: 30px 0 16px 0;
cannam@86 27 }
cannam@86 28
cannam@86 29 #content p {
cannam@86 30 line-height: 1.4;
cannam@86 31 }
cannam@86 32
cannam@86 33 h1, h1 a, h2, h2 a, h3, h3 a {
cannam@86 34 font-weight: bold;
cannam@86 35 color: #ff9900;
cannam@86 36 margin: 1.3em 0 8px 0;
cannam@86 37 }
cannam@86 38
cannam@86 39 h1 {
cannam@86 40 font-size: 1.3em;
cannam@86 41 }
cannam@86 42
cannam@86 43 h2 {
cannam@86 44 font-size: 1.2em;
cannam@86 45 }
cannam@86 46
cannam@86 47 h3 {
cannam@86 48 font-size: 1.1em;
cannam@86 49 }
cannam@86 50
cannam@86 51 li {
cannam@86 52 line-height: 1.4;
cannam@86 53 }
cannam@86 54
cannam@86 55 #copyright {
cannam@86 56 margin-top: 30px;
cannam@86 57 line-height: 1.5em;
cannam@86 58 text-align: center;
cannam@86 59 font-size: .8em;
cannam@86 60 color: #888888;
cannam@86 61 clear: both;
cannam@86 62 }
cannam@86 63 </style>
cannam@86 64
cannam@86 65 </head>
cannam@86 66
cannam@86 67 <body>
cannam@86 68
cannam@86 69 <div id="xiphlogo">
cannam@86 70 <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.Org"/></a>
cannam@86 71 </div>
cannam@86 72
cannam@86 73 <h1>Programming with Xiph.Org <tt>libvorbis</tt></h1>
cannam@86 74
cannam@86 75 <h2>Description</h2>
cannam@86 76
cannam@86 77 <p>Libvorbis is the Xiph.Org Foundation's portable Ogg Vorbis CODEC
cannam@86 78 implemented as a programmatic library. Libvorbis provides primitives
cannam@86 79 to handle framing and manipulation of Ogg bitstreams (used by the
cannam@86 80 Vorbis for streaming), a full analysis (encoding) interface as well as
cannam@86 81 packet decoding and synthesis for playback.</p>
cannam@86 82
cannam@86 83 <p>The libvorbis library does not provide any system interface; a
cannam@86 84 full-featured demonstration player included with the library
cannam@86 85 distribtion provides example code for a variety of system interfaces
cannam@86 86 as well as a working example of using libvorbis in production code.</p>
cannam@86 87
cannam@86 88 <h2>Encoding Overview</h2>
cannam@86 89
cannam@86 90 <h2>Decoding Overview</h2>
cannam@86 91
cannam@86 92 <p>Decoding a bitstream with libvorbis follows roughly the following
cannam@86 93 steps:</p>
cannam@86 94
cannam@86 95 <ol>
cannam@86 96 <li>Frame the incoming bitstream into pages</li>
cannam@86 97 <li>Sort the pages by logical bitstream and buffer then into logical streams</li>
cannam@86 98 <li>Decompose the logical streams into raw packets</li>
cannam@86 99 <li>Reconstruct segments of the original data from each packet</li>
cannam@86 100 <li>Glue the reconstructed segments back into a decoded stream</li>
cannam@86 101 </ol>
cannam@86 102
cannam@86 103 <h3>Framing</h3>
cannam@86 104
cannam@86 105 <p>An Ogg bitstream is logically arranged into pages, but to decode
cannam@86 106 the pages, we have to find them first. The raw bitstream is first fed
cannam@86 107 into an <tt>ogg_sync_state</tt> buffer using <tt>ogg_sync_buffer()</tt>
cannam@86 108 and <tt>ogg_sync_wrote()</tt>. After each block we submit to the sync
cannam@86 109 buffer, we should check to see if we can frame and extract a complete
cannam@86 110 page or pages using <tt>ogg_sync_pageout()</tt>. Extra pages are
cannam@86 111 buffered; allowing them to build up in the <tt>ogg_sync_state</tt>
cannam@86 112 buffer will eventually exhaust memory.</p>
cannam@86 113
cannam@86 114 <p>The Ogg pages returned from <tt>ogg_sync_pageout</tt> need not be
cannam@86 115 decoded further to be used as landmarks in seeking; seeking can be
cannam@86 116 either a rough process of simply jumping to approximately intuited
cannam@86 117 portions of the bitstream, or it can be a precise bisection process
cannam@86 118 that captures pages and inspects data position. When seeking,
cannam@86 119 however, sequential multiplexing (chaining) must be accounted for;
cannam@86 120 beginning play in a new logical bitstream requires initializing a
cannam@86 121 synthesis engine with the headers from that bitstream. Vorbis
cannam@86 122 bitstreams do not make use of concurent multiplexing (grouping).</p>
cannam@86 123
cannam@86 124 <h3>Sorting</h3>
cannam@86 125
cannam@86 126 <p>The pages produced by <tt>ogg_sync_pageout</tt> are then sorted by
cannam@86 127 serial number to seperate logical bitstreams. Initialize logical
cannam@86 128 bitstream buffers (<tt>og_stream_state</tt>) using
cannam@86 129 <tt>ogg_stream_init()</tt>. Pages are submitted to the matching
cannam@86 130 logical bitstream buffer using <tt>ogg_stream_pagein</tt>; the serial
cannam@86 131 number of the page and the stream buffer must match, or the page will
cannam@86 132 be rejected. A page submitted out of sequence will simply be noted,
cannam@86 133 and in the course of outputting packets, the hole will be flagged
cannam@86 134 (<tt>ogg_sync_pageout</tt> and <tt>ogg_stream_packetout</tt> will
cannam@86 135 return a negative value at positions where they had to recapture the
cannam@86 136 stream).</p>
cannam@86 137
cannam@86 138 <h3>Extracting packets</h3>
cannam@86 139
cannam@86 140 <p>After submitting page[s] to a logical stream, read available packets
cannam@86 141 using <tt>ogg_stream_packetout</tt>.</p>
cannam@86 142
cannam@86 143 <h3>Decoding packets</h3>
cannam@86 144
cannam@86 145 <h3>Reassembling data segments</h3>
cannam@86 146
cannam@86 147 <h2>Ogg Bitstream Manipulation Structures</h2>
cannam@86 148
cannam@86 149 <p>Two of the Ogg bitstream data structures are intended to be
cannam@86 150 transparent to the developer; the fields should be used directly.</p>
cannam@86 151
cannam@86 152 <h3>ogg_packet</h3>
cannam@86 153
cannam@86 154 <pre>
cannam@86 155 typedef struct {
cannam@86 156 unsigned char *packet;
cannam@86 157 long bytes;
cannam@86 158 long b_o_s;
cannam@86 159 long e_o_s;
cannam@86 160
cannam@86 161 size64 granulepos;
cannam@86 162
cannam@86 163 } ogg_packet;
cannam@86 164 </pre>
cannam@86 165
cannam@86 166 <dl>
cannam@86 167 <dt>packet:</dt>
cannam@86 168 <dd>a pointer to the byte data of the raw packet</dd>
cannam@86 169 <dt>bytes:</dt>
cannam@86 170 <dd>the size of the packet' raw data</dd>
cannam@86 171 <dt>b_o_s:</dt>
cannam@86 172 <dd>beginning of stream; nonzero if this is the first packet of
cannam@86 173 the logical bitstream</dd>
cannam@86 174 <dt>e_o_s:</dt>
cannam@86 175 <dd>end of stream; nonzero if this is the last packet of the
cannam@86 176 logical bitstream</dd>
cannam@86 177 <dt>granulepos:</dt>
cannam@86 178 <dd>the absolute position of this packet in the original
cannam@86 179 uncompressed data stream.</dd>
cannam@86 180 </dl>
cannam@86 181
cannam@86 182 <h4>encoding notes</h4>
cannam@86 183
cannam@86 184 <p>The encoder is responsible for setting all of
cannam@86 185 the fields of the packet to appropriate values before submission to
cannam@86 186 <tt>ogg_stream_packetin()</tt>; however, it is noted that the value in
cannam@86 187 <tt>b_o_s</tt> is ignored; the first page produced from a given
cannam@86 188 <tt>ogg_stream_state</tt> structure will be stamped as the initial
cannam@86 189 page. <tt>e_o_s</tt>, however, must be set; this is the means by
cannam@86 190 which the stream encoding primitives handle end of stream and cleanup.</p>
cannam@86 191
cannam@86 192 <h4>decoding notes</h4>
cannam@86 193
cannam@86 194 <p><tt>ogg_stream_packetout()</tt> sets the fields
cannam@86 195 to appropriate values. Note that granulepos will be >= 0 only in the
cannam@86 196 case that the given packet actually represents that position (ie, only
cannam@86 197 the last packet completed on any page will have a meaningful
cannam@86 198 <tt>granulepos</tt>). Intervening frames will see <tt>granulepos</tt> set
cannam@86 199 to -1.</p>
cannam@86 200
cannam@86 201 <h3>ogg_page</h3>
cannam@86 202
cannam@86 203 <pre>
cannam@86 204 typedef struct {
cannam@86 205 unsigned char *header;
cannam@86 206 long header_len;
cannam@86 207 unsigned char *body;
cannam@86 208 long body_len;
cannam@86 209 } ogg_page;
cannam@86 210 </pre>
cannam@86 211
cannam@86 212 <dl>
cannam@86 213 <dt>header:</dt>
cannam@86 214 <dd>pointer to the page header data</dd>
cannam@86 215 <dt>header_len:</dt>
cannam@86 216 <dd>length of the page header in bytes</dd>
cannam@86 217 <dt>body:</dt>
cannam@86 218 <dd>pointer to the page body</dd>
cannam@86 219 <dt>body_len:</dt>
cannam@86 220 <dd>length of the page body</dd>
cannam@86 221 </dl>
cannam@86 222
cannam@86 223 <p>Note that although the <tt>header</tt> and <tt>body</tt> pointers do
cannam@86 224 not necessarily point into a single contiguous page vector, the page
cannam@86 225 body must immediately follow the header in the bitstream.</p>
cannam@86 226
cannam@86 227 <h2>Ogg Bitstream Manipulation Functions</h2>
cannam@86 228
cannam@86 229 <h3>
cannam@86 230 int ogg_page_bos(ogg_page *og);
cannam@86 231 </h3>
cannam@86 232
cannam@86 233 <p>Returns the 'beginning of stream' flag for the given Ogg page. The
cannam@86 234 beginning of stream flag is set on the initial page of a logical
cannam@86 235 bitstream.</p>
cannam@86 236
cannam@86 237 <p>Zero indicates the flag is cleared (this is not the initial page of a
cannam@86 238 logical bitstream). Nonzero indicates the flag is set (this is the
cannam@86 239 initial page of a logical bitstream).</p>
cannam@86 240
cannam@86 241 <h3>
cannam@86 242 int ogg_page_continued(ogg_page *og);
cannam@86 243 </h3>
cannam@86 244
cannam@86 245 <p>Returns the 'packet continued' flag for the given Ogg page. The packet
cannam@86 246 continued flag indicates whether or not the body data of this page
cannam@86 247 begins with packet continued from a preceeding page.</p>
cannam@86 248
cannam@86 249 <p>Zero (unset) indicates that the body data begins with a new packet.
cannam@86 250 Nonzero (set) indicates that the first packet data on the page is a
cannam@86 251 continuation from the preceeding page.</p>
cannam@86 252
cannam@86 253 <h3>
cannam@86 254 int ogg_page_eos(ogg_page *og);
cannam@86 255 </h3>
cannam@86 256
cannam@86 257 <p>Returns the 'end of stream' flag for a give Ogg page. The end of page
cannam@86 258 flag is set on the last (terminal) page of a logical bitstream.</p>
cannam@86 259
cannam@86 260 <p>Zero (unset) indicates that this is not the last page of a logical
cannam@86 261 bitstream. Nonzero (set) indicates that this is the last page of a
cannam@86 262 logical bitstream and that no addiitonal pages belonging to this
cannam@86 263 bitstream may follow.</p>
cannam@86 264
cannam@86 265 <h3>
cannam@86 266 size64 ogg_page_granulepos(ogg_page *og);
cannam@86 267 </h3>
cannam@86 268
cannam@86 269 <p>Returns the position of this page as an absolute position within the
cannam@86 270 original uncompressed data. The position, as returned, is 'frames
cannam@86 271 encoded to date up to and including the last whole packet on this
cannam@86 272 page'. Partial packets begun on this page but continued to the
cannam@86 273 following page are not included. If no packet ends on this page, the
cannam@86 274 frame position value will be equal to the frame position value of the
cannam@86 275 preceeding page. If none of the original uncompressed data is yet
cannam@86 276 represented in the logical bitstream (for example, the first page of a
cannam@86 277 bitstream consists only of a header packet; this packet encodes only
cannam@86 278 metadata), the value shall be zero.</p>
cannam@86 279
cannam@86 280 <p>The units of the framenumber are determined by media mapping. A
cannam@86 281 vorbis audio bitstream, for example, defines one frame to be the
cannam@86 282 channel values from a single sampling period (eg, a 16 bit stereo
cannam@86 283 bitstream consists of two samples of two bytes for a total of four
cannam@86 284 bytes, thus a frame would be four bytes). A video stream defines one
cannam@86 285 frame to be a single frame of video.</p>
cannam@86 286
cannam@86 287 <h3>
cannam@86 288 int ogg_page_pageno(ogg_page *og);
cannam@86 289 </h3>
cannam@86 290
cannam@86 291 <p>Returns the sequential page number of the given Ogg page. The first
cannam@86 292 page in a logical bitstream is numbered zero; following pages are
cannam@86 293 numbered in increasing monotonic order.</p>
cannam@86 294
cannam@86 295 <h3>
cannam@86 296 int ogg_page_serialno(ogg_page *og);
cannam@86 297 </h3>
cannam@86 298
cannam@86 299 <p>Returns the serial number of the given Ogg page. The serial number is
cannam@86 300 used as a handle to distinguish various logical bitstreams in a
cannam@86 301 physical Ogg bitstresm. Every logical bitstream within a
cannam@86 302 physical bitstream must use a unique (within the scope of the physical
cannam@86 303 bitstream) serial number, which is stamped on all bitstream pages.</p>
cannam@86 304
cannam@86 305 <h3>
cannam@86 306 int ogg_page_version(ogg_page *og);
cannam@86 307 </h3>
cannam@86 308
cannam@86 309 <p>Returns the revision of the Ogg bitstream structure of the given page.
cannam@86 310 Currently, the only permitted number is zero. Later revisions of the
cannam@86 311 bitstream spec will increment this version should any changes be
cannam@86 312 incompatable.</p>
cannam@86 313
cannam@86 314 <h3>
cannam@86 315 int ogg_stream_clear(ogg_stream_state *os);
cannam@86 316 </h3>
cannam@86 317
cannam@86 318 <p>Clears and deallocates the internal storage of the given Ogg stream.
cannam@86 319 After clearing, the stream structure is not initialized for use;
cannam@86 320 <tt>ogg_stream_init</tt> must be called to reinitialize for use.
cannam@86 321 Use <tt>ogg_stream_reset</tt> to reset the stream state
cannam@86 322 to a fresh, intiialized state.</p>
cannam@86 323
cannam@86 324 <p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
cannam@86 325 <tt>os</tt>, allowing use of this call on stream structures in static
cannam@86 326 or automatic storage. <tt>ogg_stream_destroy</tt>is a complimentary
cannam@86 327 function that frees the pointer as well.</p>
cannam@86 328
cannam@86 329 <p>Returns zero on success and non-zero on failure. This function always
cannam@86 330 succeeds.</p>
cannam@86 331
cannam@86 332 <h3>
cannam@86 333 int ogg_stream_destroy(ogg_stream_state *os);
cannam@86 334 </h3>
cannam@86 335
cannam@86 336 <p>Clears and deallocates the internal storage of the given Ogg stream,
cannam@86 337 then frees the storage associated with the pointer <tt>os</tt>.</p>
cannam@86 338
cannam@86 339 <p><tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
cannam@86 340 <tt>os</tt>, allowing use of that call on stream structures in static
cannam@86 341 or automatic storage.</p>
cannam@86 342
cannam@86 343 <p>Returns zero on success and non-zero on failure. This function always
cannam@86 344 succeeds.</p>
cannam@86 345
cannam@86 346 <h3>
cannam@86 347 int ogg_stream_init(ogg_stream_state *os,int serialno);
cannam@86 348 </h3>
cannam@86 349
cannam@86 350 <p>Initialize the storage associated with <tt>os</tt> for use as an Ogg
cannam@86 351 stream. This call is used to initialize a stream for both encode and
cannam@86 352 decode. The given serial number is the serial number that will be
cannam@86 353 stamped on pages of the produced bitstream (during encode), or used as
cannam@86 354 a check that pages match (during decode).</p>
cannam@86 355
cannam@86 356 <p>Returns zero on success, nonzero on failure.</p>
cannam@86 357
cannam@86 358 <h3>
cannam@86 359 int ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
cannam@86 360 </h3>
cannam@86 361
cannam@86 362 <p>Used during encoding to add the given raw packet to the given Ogg
cannam@86 363 bitstream. The contents of <tt>op</tt> are copied;
cannam@86 364 <tt>ogg_stream_packetin</tt> does not retain any pointers into
cannam@86 365 <tt>op</tt>'s storage. The encoding proccess buffers incoming packets
cannam@86 366 until enough packets have been assembled to form an entire page;
cannam@86 367 <tt>ogg_stream_pageout</tt> is used to read complete pages.</p>
cannam@86 368
cannam@86 369 <p>Returns zero on success, nonzero on failure.</p>
cannam@86 370
cannam@86 371 <h3>
cannam@86 372 int ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
cannam@86 373 </h3>
cannam@86 374
cannam@86 375 <p>Used during decoding to read raw packets from the given logical
cannam@86 376 bitstream. <tt>ogg_stream_packetout</tt> will only return complete
cannam@86 377 packets for which checksumming indicates no corruption. The size and
cannam@86 378 contents of the packet exactly match those given in the encoding
cannam@86 379 process. </p>
cannam@86 380
cannam@86 381 <p>Returns zero if the next packet is not ready to be read (not buffered
cannam@86 382 or incomplete), positive if it returned a complete packet in
cannam@86 383 <tt>op</tt> and negative if there is a gap, extra bytes or corruption
cannam@86 384 at this position in the bitstream (essentially that the bitstream had
cannam@86 385 to be recaptured). A negative value is not necessarily an error. It
cannam@86 386 would be a common occurence when seeking, for example, which requires
cannam@86 387 recapture of the bitstream at the position decoding continued.</p>
cannam@86 388
cannam@86 389 <p>If the return value is positive, <tt>ogg_stream_packetout</tt> placed
cannam@86 390 a packet in <tt>op</tt>. The data in <tt>op</tt> points to static
cannam@86 391 storage that is valid until the next call to
cannam@86 392 <tt>ogg_stream_pagein</tt>, <tt>ogg_stream_clear</tt>,
cannam@86 393 <tt>ogg_stream_reset</tt>, or <tt>ogg_stream_destroy</tt>. The
cannam@86 394 pointers are not invalidated by more calls to
cannam@86 395 <tt>ogg_stream_packetout</tt>.</p>
cannam@86 396
cannam@86 397 <h3>
cannam@86 398 int ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
cannam@86 399 </h3>
cannam@86 400
cannam@86 401 <p>Used during decoding to buffer the given complete, pre-verified page
cannam@86 402 for decoding into raw Ogg packets. The given page must be framed,
cannam@86 403 normally produced by <tt>ogg_sync_pageout</tt>, and from the logical
cannam@86 404 bitstream associated with <tt>os</tt> (the serial numbers must match).
cannam@86 405 The contents of the given page are copied; <tt>ogg_stream_pagein</tt>
cannam@86 406 retains no pointers into <tt>og</tt> storage.</p>
cannam@86 407
cannam@86 408 <p>Returns zero on success and non-zero on failure.</p>
cannam@86 409
cannam@86 410 <h3>
cannam@86 411 int ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
cannam@86 412 </h3>
cannam@86 413
cannam@86 414 <p>Used during encode to read complete pages from the stream buffer. The
cannam@86 415 returned page is ready for sending out to the real world.</p>
cannam@86 416
cannam@86 417 <p>Returns zero if there is no complete page ready for reading. Returns
cannam@86 418 nonzero when it has placed data for a complete page into
cannam@86 419 <tt>og</tt>. Note that the storage returned in og points into internal
cannam@86 420 storage; the pointers in <tt>og</tt> are valid until the next call to
cannam@86 421 <tt>ogg_stream_pageout</tt>, <tt>ogg_stream_packetin</tt>,
cannam@86 422 <tt>ogg_stream_reset</tt>, <tt>ogg_stream_clear</tt> or
cannam@86 423 <tt>ogg_stream_destroy</tt>.</p>
cannam@86 424
cannam@86 425 <h3>
cannam@86 426 int ogg_stream_reset(ogg_stream_state *os);
cannam@86 427 </h3>
cannam@86 428
cannam@86 429 <p>Resets the given stream's state to that of a blank, unused stream;
cannam@86 430 this may be used during encode or decode.</p>
cannam@86 431
cannam@86 432 <p>Note that if used during encode, it does not alter the stream's serial
cannam@86 433 number. In addition, the next page produced during encoding will be
cannam@86 434 marked as the 'initial' page of the logical bitstream.</p>
cannam@86 435
cannam@86 436 <p>When used during decode, this simply clears the data buffer of any
cannam@86 437 pending pages. Beginning and end of stream cues are read from the
cannam@86 438 bitstream and are unaffected by reset.</p>
cannam@86 439
cannam@86 440 <p>Returns zero on success and non-zero on failure. This function always
cannam@86 441 succeeds.</p>
cannam@86 442
cannam@86 443 <h3>
cannam@86 444 char *ogg_sync_buffer(ogg_sync_state *oy, long size);
cannam@86 445 </h3>
cannam@86 446
cannam@86 447 <p>This call is used to buffer a raw bitstream for framing and
cannam@86 448 verification. <tt>ogg_sync_buffer</tt> handles stream capture and
cannam@86 449 recapture, checksumming, and division into Ogg pages (as required by
cannam@86 450 <tt>ogg_stream_pagein</tt>).</p>
cannam@86 451
cannam@86 452 <p><tt>ogg_sync_buffer</tt> exposes a buffer area into which the decoder
cannam@86 453 copies the next (up to) <tt>size</tt> bytes. We expose the buffer
cannam@86 454 (rather than taking a buffer) in order to avoid an extra copy many
cannam@86 455 uses; this way, for example, <tt>read()</tt> can transfer data
cannam@86 456 directly into the stream buffer without first needing to place it in
cannam@86 457 temporary storage.</p>
cannam@86 458
cannam@86 459 <p>Returns a pointer into <tt>oy</tt>'s internal bitstream sync buffer;
cannam@86 460 the remaining space in the sync buffer is at least <tt>size</tt>
cannam@86 461 bytes. The decoder need not write all of <tt>size</tt> bytes;
cannam@86 462 <tt>ogg_sync_wrote</tt> is used to inform the engine how many bytes
cannam@86 463 were actually written. Use of <tt>ogg_sync_wrote</tt> after writing
cannam@86 464 into the exposed buffer is mandantory.</p>
cannam@86 465
cannam@86 466 <h3>
cannam@86 467 int ogg_sync_clear(ogg_sync_state *oy);
cannam@86 468 </h3>
cannam@86 469
cannam@86 470 <p><tt>ogg_sync_clear</tt>
cannam@86 471 clears and deallocates the internal storage of the given Ogg sync
cannam@86 472 buffer. After clearing, the sync structure is not initialized for
cannam@86 473 use; <tt>ogg_sync_init</tt> must be called to reinitialize for use.
cannam@86 474 Use <tt>ogg_sync_reset</tt> to reset the sync state and buffer to a
cannam@86 475 fresh, intiialized state.</p>
cannam@86 476
cannam@86 477 <p><tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
cannam@86 478 <tt>oy</tt>, allowing use of this call on sync structures in static
cannam@86 479 or automatic storage. <tt>ogg_sync_destroy</tt>is a complimentary
cannam@86 480 function that frees the pointer as well.</p>
cannam@86 481
cannam@86 482 <p>Returns zero on success and non-zero on failure. This function always
cannam@86 483 succeeds.</p>
cannam@86 484
cannam@86 485 <h3>
cannam@86 486 int ogg_sync_destroy(ogg_sync_state *oy);
cannam@86 487 </h3>
cannam@86 488
cannam@86 489 <p>Clears and deallocates the internal storage of the given Ogg sync
cannam@86 490 buffer, then frees the storage associated with the pointer
cannam@86 491 <tt>oy</tt>.</p>
cannam@86 492
cannam@86 493 <p>An alternative function,<tt>ogg_sync_clear</tt>, does not call
cannam@86 494 <tt>free()</tt> on the pointer <tt>oy</tt>, allowing use of that call on
cannam@86 495 stream structures in static or automatic storage.</p>
cannam@86 496
cannam@86 497 <p>Returns zero on success and non-zero on failure. This function always
cannam@86 498 succeeds.</p>
cannam@86 499
cannam@86 500 <h3>
cannam@86 501 int ogg_sync_init(ogg_sync_state *oy);
cannam@86 502 </h3>
cannam@86 503
cannam@86 504 <p>Initializes the sync buffer <tt>oy</tt> for use.</p>
cannam@86 505
cannam@86 506 <p>Returns zero on success and non-zero on failure. This function always
cannam@86 507 succeeds.</p>
cannam@86 508
cannam@86 509 <h3>
cannam@86 510 int ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
cannam@86 511 </h3>
cannam@86 512
cannam@86 513 <p>Reads complete, framed, verified Ogg pages from the sync buffer,
cannam@86 514 placing the page data in <tt>og</tt>.</p>
cannam@86 515
cannam@86 516 <p>Returns zero when there's no complete pages buffered for
cannam@86 517 retrieval. Returns negative when a loss of sync or recapture occurred
cannam@86 518 (this is not necessarily an error; recapture would be required after
cannam@86 519 seeking, for example). Returns positive when a page is returned in
cannam@86 520 <tt>og</tt>. Note that the data in <tt>og</tt> points into the sync
cannam@86 521 buffer storage; the pointers are valid until the next call to
cannam@86 522 <tt>ogg_sync_buffer</tt>, <tt>ogg_sync_clear</tt>,
cannam@86 523 <tt>ogg_sync_destroy</tt> or <tt>ogg_sync_reset</tt>.</p>
cannam@86 524
cannam@86 525 <h3>
cannam@86 526 int ogg_sync_reset(ogg_sync_state *oy);
cannam@86 527 </h3>
cannam@86 528
cannam@86 529 <p><tt>ogg_sync_reset</tt> resets the sync state in <tt>oy</tt> to a
cannam@86 530 clean, empty state. This is useful, for example, when seeking to a
cannam@86 531 new location in a bitstream.</p>
cannam@86 532
cannam@86 533 <p>Returns zero on success, nonzero on failure.</p>
cannam@86 534
cannam@86 535 <h3>
cannam@86 536 int ogg_sync_wrote(ogg_sync_state *oy, long bytes);
cannam@86 537 </h3>
cannam@86 538
cannam@86 539 <p>Used to inform the sync state as to how many bytes were actually
cannam@86 540 written into the exposed sync buffer. It must be equal to or less
cannam@86 541 than the size of the buffer requested.</p>
cannam@86 542
cannam@86 543 <p>Returns zero on success and non-zero on failure; failure occurs only
cannam@86 544 when the number of bytes written were larger than the buffer.</p>
cannam@86 545
cannam@86 546 <div id="copyright">
cannam@86 547 The Xiph Fish Logo is a
cannam@86 548 trademark (&trade;) of Xiph.Org.<br/>
cannam@86 549
cannam@86 550 These pages &copy; 1994 - 2005 Xiph.Org. All rights reserved.
cannam@86 551 </div>
cannam@86 552
cannam@86 553 </body>
cannam@86 554 </html>