--- /dev/null
+<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
+<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
+<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
+
+<h1><font color=#000070>
+Ogg Vorbis I format specification: bitpacking convention
+</font></h1>
+
+<em>Last update to this document: July 14, 2002</em><br>
+
+<h1>Overview</h1>
+
+The Vorbis codec uses relatively unstructured raw packets containing
+arbitrary-width binary integer fields. Logically, these packets are a
+bitstream in which bits are coded one-by-one by the encoder and then
+read one-by-one in the same monotonically increasing order by the
+decoder. Most current binary storage arrangements group bits into a
+native word size of eight bits (octets), sixteen bits, thirty-two bits
+or, less commonly other fixed word sizes. The Vorbis bitpacking
+convention specifies the correct mapping of the logical packet
+bitstream into an actual representation in fixed-width words.
+
+<h2>octets, bytes and words</h2>
+
+In most contemporary architectures, a 'byte' is synonymous with an
+'octet', that is, eight bits. This has not always been the case;
+seven, ten, eleven and sixteen bit 'bytes' have been used. For
+purposes of the bitpacking convention, a byte implies the native,
+smallest integer storage representation offered by a platform. On
+modern platforms, this is generally assumed to be eight bits (not
+necessarily because of the processor but because of the
+filesystem/memory architecture. Modern filesystems invariably offer
+bytes as the fundamental atom of storage). A 'word' is an integer
+size that is a grouped multiple of this smallest size.<p>
+
+The most ubiquitous architectures today consider a 'byte' to be an
+octet (eight bits) and a word to be a group of two, four or eight
+bytes (16,32 or 64 bits). Note however that the Vorbis bitpacking
+convention is still well defined for any native byte size; Vorbis uses
+the native bit-width of a given storage system. This document assumes
+that a byte is one octet for purposes of example.<p>
+
+<h2>bit order</h2>
+
+A byte has a well-defined 'least significant' bit [LSb], which is the
+only bit set when the byte is storing the two's complement integer
+value +1. A byte's 'most significant' bit [MSb] is at the opposite
+end of the byte. Bits in a byte are numbered from zero at the LSb to
+<i>n</i> (<i>n</i>=7 in an octet) for the MSb.<n>
+
+<h2>byte order</h2>
+
+Words are native groupings of multiple bytes. Several byte orderings
+are possible in a word; the common ones are 3-2-1-0 ('big endian' or
+'most significant byte first' in which the highest-valued byte comes
+first), 0-1-2-3 ('little endian' or 'least significant byte first' in
+which the lowest value byte comes first) and less commonly 3-1-2-0 and
+0-2-1-3 ('mixed endian').<p>
+
+The Vorbis bitpacking convention specifies storage and bitstream
+manipulation at the byte, not word, level, thus host word ordering is
+of a concern only during optimization when writing high performance
+code that operates on a word of storage at a time rather than by byte.
+Logically, bytes are always coded and decoded in order from byte zero
+through byte <em>n</em>.<p>
+
+<h2>coding bits into byte sequences</h2>
+
+The Vorbis codec has need to code arbitrary bit-width integers, from
+zero to 32 bits wide, into packets. These integer fields are not
+aligned to the boundaries of the byte representation; the next field
+is written at the bit position that the previous field ends.<p>
+
+The encoder logically packs integers by writing the LSb of an binary
+integer to the logical bitstream first, followed by next least
+significant bit, etc, until the requested number of bits have been
+coded. When packing the bits into bytes, the encoder begins by
+placing the LSb of the integer to be written into the least
+significant unused bit position of the destination byte, followed by
+the next-least significant bit of the source integer and so on up to
+the requested number of bits. When all bits of the destination byte
+have been filled, encoding continues by zeroing all bits of the next
+byte and writing the next bit into the bit position 0 of that byte.
+Decoding follows the same process as encoding, but by reading bits
+from the byte stream and reassembling them into integers.<p>
+
+<h2>signedness</h2>
+
+The signedness of a specific number resulting from decode is to be
+interpreted by the decoder given decode context. That is, the three
+bit binary pattern 'b111' can be taken to represent either 'seven' as
+an unsigned integer, or '-1' as a signed, two's complement integer.
+The encoder and decoder are responsible for knowing if fields are to
+be treated as signed or unsigned.
+
+
+<h2>coding example</h2>
+
+Code the 4 bit integer value '12' [b1100] into an empty bytestream.
+Bytestream result:
+
+<pre>
+ |
+ V
+
+ 7 6 5 4 3 2 1 0
+byte 0 [0 0 0 0 1 1 0 0] <-
+byte 1 [ ]
+byte 2 [ ]
+byte 3 [ ]
+ ...
+byte n [ ] bytestream length == 1 byte
+
+</pre>
+
+Continue by coding the 3 bit integer value '-1' [b111]:
+
+<pre>
+ |
+ V
+
+ 7 6 5 4 3 2 1 0
+byte 0 [0 1 1 1 1 1 0 0] <-
+byte 1 [ ]
+byte 2 [ ]
+byte 3 [ ]
+ ...
+byte n [ ] bytestream length == 1 byte
+</pre>
+
+Continue by coding the 7 bit integer value '17' [b0010001]:
+
+<pre>
+ |
+ V
+
+ 7 6 5 4 3 2 1 0
+byte 0 [1 1 1 1 1 1 0 0]
+byte 1 [0 0 0 0 1 0 0 0] <-
+byte 2 [ ]
+byte 3 [ ]
+ ...
+byte n [ ] bytestream length == 2 bytes
+ bit cursor == 6
+</pre>
+
+Continue by coding the 13 bit integer value '6969' [b110 11001110 01]:
+
+<pre>
+ |
+ V
+
+ 7 6 5 4 3 2 1 0
+byte 0 [1 1 1 1 1 1 0 0]
+byte 1 [0 1 0 0 1 0 0 0]
+byte 2 [1 1 0 0 1 1 1 0]
+byte 3 [0 0 0 0 0 1 1 0] <-
+ ...
+byte n [ ] bytestream length == 4 bytes
+
+</pre>
+
+<h2>decoding example</h2>
+
+Reading from the beginning of the bytestream encoded in the above example:
+
+<pre>
+ |
+ V
+
+ 7 6 5 4 3 2 1 0
+byte 0 [1 1 1 1 1 1 0 0] <-
+byte 1 [0 1 0 0 1 0 0 0]
+byte 2 [1 1 0 0 1 1 1 0]
+byte 3 [0 0 0 0 0 1 1 0] bytestream length == 4 bytes
+
+</pre>
+
+We read two, two-bit integer fields, resulting in the returned numbers
+'b00' and 'b11'. Two things are worth noting here:
+
+<ul>
+<li>Although these four bits were originally written as a single four-bit
+integer, reading some other combination of bit-widths from the
+bitstream is well defined. There are no artificial alignment
+boundaries maintained in the bitstream. <li>The second value is the
+two-bit-wide integer 'b11'. This value may be interpreted either as
+the unsigned value '3', or the signed value '-1'. Signedness is
+dependent on decode context.
+</uL>
+
+
+<h2>end-of-packet alignment</h2>
+
+The typical use of bitpacking is to produce many independent
+byte-aligned packets which are embedded into a larger byte-aligned
+container structure, such as an Ogg transport bitstream. Externally,
+each bytestream (encoded bitstream) must begin and end on a byte
+boundary. Often, the encoded bitstream is not an integer number of
+bytes, and so there is unused (uncoded) space in the last byte of a
+packet.<p>
+
+Unused space in the last byte of a bytestream is always zeroed during
+the coding process. Thus, should this unused space be read, it will
+return binary zeroes.<p>
+
+Attempting to read past the end of an encoded packet results in an
+'end-of-packet' condition. End-of-packet is not to be considered an
+error; it is merely a state indicating that there is insufficient
+remaining data to fulfill the desired read size. Vorbis uses truncated
+packets as a normal mode of operation, and as such, decoders must
+handle reading past the end of a packet as a typical mode of
+operation. Any further read operations after an 'end-of-packet'
+condition shall also return 'end-of-packet'.<p>
+
+
+<h2> reading zero bits</h2>
+
+Reading a zero-bit-wide integer returns the value '0' and does not
+increment the stream cursor. Reading to the end of the packet (but
+not past, such that an 'end-of-packet' condition has not triggered)
+and then reading a zero bit integer shall succeed, returning 0, and
+not trigger an end-of-packet condition. Reading a zero-bit-wide
+integer after a previous read sets 'end-of-packet' shall also fail
+with 'end-of-packet'<p>
+
+<hr>
+<a href="http://www.xiph.org/">
+<img src="white-xifish.png" align=left border=0>
+</a>
+<font size=-2 color=#505050>
+
+Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</a> effort
+to protect essential tenets of Internet multimedia from corporate
+hostage-taking; Open Source is the net's greatest tool to keep
+everyone honest. See <a href="http://www.xiph.org/about.html">About
+the Xiph.org Foundation</a> for details.
+<p>
+
+Ogg Vorbis is the first Ogg audio CODEC. Anyone may freely use and
+distribute the Ogg and Vorbis specification, whether in a private,
+public or corporate capacity. However, the Xiph.org Foundation and
+the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
+specification and certify specification compliance.<p>
+
+Xiph.org's Vorbis software CODEC implementation is distributed under a
+BSD-like license. This does not restrict third parties from
+distributing independent implementations of Vorbis software under
+other licenses.<p>
+
+Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
+of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
+pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
+reserved.<p>
+
+</body>
+
projects / platform / upstream / libvorbis.git / commitdiff