18e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels% -*- mode: latex; TeX-master: "Vorbis_I_spec"; -*- 28e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels%!TEX root = Vorbis_I_spec.tex 38e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels% $Id$ 48e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\section{Bitpacking Convention} \label{vorbis:spec:bitpacking} 58e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 68e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsection{Overview} 78e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 88e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThe Vorbis codec uses relatively unstructured raw packets containing 98e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsarbitrary-width binary integer fields. Logically, these packets are a 108e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbitstream in which bits are coded one-by-one by the encoder and then 118e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsread one-by-one in the same monotonically increasing order by the 128e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsdecoder. Most current binary storage arrangements group bits into a 138e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsnative word size of eight bits (octets), sixteen bits, thirty-two bits 148e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsor, less commonly other fixed word sizes. The Vorbis bitpacking 158e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsconvention specifies the correct mapping of the logical packet 168e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbitstream into an actual representation in fixed-width words. 178e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 188e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 198e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{octets, bytes and words} 208e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 218e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsIn most contemporary architectures, a 'byte' is synonymous with an 228e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels'octet', that is, eight bits. This has not always been the case; 238e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsseven, ten, eleven and sixteen bit 'bytes' have been used. For 248e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelspurposes of the bitpacking convention, a byte implies the native, 258e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelssmallest integer storage representation offered by a platform. On 268e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsmodern platforms, this is generally assumed to be eight bits (not 278e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsnecessarily because of the processor but because of the 288e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfilesystem/memory architecture. Modern filesystems invariably offer 298e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbytes as the fundamental atom of storage). A 'word' is an integer 308e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelssize that is a grouped multiple of this smallest size. 318e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 328e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThe most ubiquitous architectures today consider a 'byte' to be an 338e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsoctet (eight bits) and a word to be a group of two, four or eight 348e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbytes (16, 32 or 64 bits). Note however that the Vorbis bitpacking 358e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsconvention is still well defined for any native byte size; Vorbis uses 368e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsthe native bit-width of a given storage system. This document assumes 378e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsthat a byte is one octet for purposes of example. 388e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 398e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{bit order} 408e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 418e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsA byte has a well-defined 'least significant' bit (LSb), which is the 428e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsonly bit set when the byte is storing the two's complement integer 438e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsvalue +1. A byte's 'most significant' bit (MSb) is at the opposite 448e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsend of the byte. Bits in a byte are numbered from zero at the LSb to 458e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels$n$ ($n=7$ in an octet) for the 468e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsMSb. 478e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 488e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 498e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 508e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{byte order} 518e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 528e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsWords are native groupings of multiple bytes. Several byte orderings 538e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsare possible in a word; the common ones are 3-2-1-0 ('big endian' or 548e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels'most significant byte first' in which the highest-valued byte comes 558e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfirst), 0-1-2-3 ('little endian' or 'least significant byte first' in 568e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelswhich the lowest value byte comes first) and less commonly 3-1-2-0 and 578e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels0-2-1-3 ('mixed endian'). 588e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 598e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThe Vorbis bitpacking convention specifies storage and bitstream 608e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsmanipulation at the byte, not word, level, thus host word ordering is 618e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsof a concern only during optimization when writing high performance 628e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscode that operates on a word of storage at a time rather than by byte. 638e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsLogically, bytes are always coded and decoded in order from byte zero 648e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsthrough byte $n$. 658e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 668e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 678e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 688e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{coding bits into byte sequences} 698e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 708e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThe Vorbis codec has need to code arbitrary bit-width integers, from 718e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelszero to 32 bits wide, into packets. These integer fields are not 728e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsaligned to the boundaries of the byte representation; the next field 738e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsis written at the bit position at which the previous field ends. 748e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 758e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThe encoder logically packs integers by writing the LSb of a binary 768e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsinteger to the logical bitstream first, followed by next least 778e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelssignificant bit, etc, until the requested number of bits have been 788e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscoded. When packing the bits into bytes, the encoder begins by 798e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsplacing the LSb of the integer to be written into the least 808e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelssignificant unused bit position of the destination byte, followed by 818e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsthe next-least significant bit of the source integer and so on up to 828e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsthe requested number of bits. When all bits of the destination byte 838e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelshave been filled, encoding continues by zeroing all bits of the next 848e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte and writing the next bit into the bit position 0 of that byte. 858e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsDecoding follows the same process as encoding, but by reading bits 868e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfrom the byte stream and reassembling them into integers. 878e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 888e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 898e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 908e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{signedness} 918e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 928e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThe signedness of a specific number resulting from decode is to be 938e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsinterpreted by the decoder given decode context. That is, the three 948e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbit binary pattern 'b111' can be taken to represent either 'seven' as 958e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsan unsigned integer, or '-1' as a signed, two's complement integer. 968e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThe encoder and decoder are responsible for knowing if fields are to 978e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbe treated as signed or unsigned. 988e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 998e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1008e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1018e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{coding example} 1028e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1038e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsCode the 4 bit integer value '12' [b1100] into an empty bytestream. 1048e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsBytestream result: 1058e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1068e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{Verbatim}[commandchars=\\\{\}] 1078e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels | 1088e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels V 1098e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1108e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 7 6 5 4 3 2 1 0 1118e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 0 [0 0 0 0 1 1 0 0] <- 1128e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 1 [ ] 1138e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 2 [ ] 1148e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 3 [ ] 1158e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels ... 1168e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte n [ ] bytestream length == 1 byte 1178e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1188e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{Verbatim} 1198e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1208e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1218e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsContinue by coding the 3 bit integer value '-1' [b111]: 1228e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1238e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{Verbatim}[commandchars=\\\{\}] 1248e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels | 1258e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels V 1268e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1278e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 7 6 5 4 3 2 1 0 1288e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 0 [0 1 1 1 1 1 0 0] <- 1298e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 1 [ ] 1308e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 2 [ ] 1318e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 3 [ ] 1328e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels ... 1338e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte n [ ] bytestream length == 1 byte 1348e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{Verbatim} 1358e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1368e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1378e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsContinue by coding the 7 bit integer value '17' [b0010001]: 1388e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1398e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{Verbatim}[commandchars=\\\{\}] 1408e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels | 1418e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels V 1428e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1438e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 7 6 5 4 3 2 1 0 1448e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 0 [1 1 1 1 1 1 0 0] 1458e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 1 [0 0 0 0 1 0 0 0] <- 1468e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 2 [ ] 1478e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 3 [ ] 1488e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels ... 1498e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte n [ ] bytestream length == 2 bytes 1508e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels bit cursor == 6 1518e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{Verbatim} 1528e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1538e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1548e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsContinue by coding the 13 bit integer value '6969' [b110 11001110 01]: 1558e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1568e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{Verbatim}[commandchars=\\\{\}] 1578e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels | 1588e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels V 1598e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1608e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 7 6 5 4 3 2 1 0 1618e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 0 [1 1 1 1 1 1 0 0] 1628e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 1 [0 1 0 0 1 0 0 0] 1638e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 2 [1 1 0 0 1 1 1 0] 1648e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 3 [0 0 0 0 0 1 1 0] <- 1658e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels ... 1668e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte n [ ] bytestream length == 4 bytes 1678e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1688e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{Verbatim} 1698e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1708e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1718e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1728e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1738e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{decoding example} 1748e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1758e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsReading from the beginning of the bytestream encoded in the above example: 1768e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1778e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{Verbatim}[commandchars=\\\{\}] 1788e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels | 1798e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels V 1808e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1818e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 7 6 5 4 3 2 1 0 1828e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 0 [1 1 1 1 1 1 0 0] <- 1838e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 1 [0 1 0 0 1 0 0 0] 1848e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 2 [1 1 0 0 1 1 1 0] 1858e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte 3 [0 0 0 0 0 1 1 0] bytestream length == 4 bytes 1868e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1878e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{Verbatim} 1888e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1898e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1908e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsWe read two, two-bit integer fields, resulting in the returned numbers 1918e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels'b00' and 'b11'. Two things are worth noting here: 1928e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1938e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\begin{itemize} 1948e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item Although these four bits were originally written as a single 1958e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsfour-bit integer, reading some other combination of bit-widths from the 1968e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbitstream is well defined. There are no artificial alignment 1978e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsboundaries maintained in the bitstream. 1988e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 1998e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\item The second value is the 2008e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelstwo-bit-wide integer 'b11'. This value may be interpreted either as 2018e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsthe unsigned value '3', or the signed value '-1'. Signedness is 2028e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsdependent on decode context. 2038e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\end{itemize} 2048e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2058e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2068e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2078e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2088e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{end-of-packet alignment} 2098e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2108e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsThe typical use of bitpacking is to produce many independent 2118e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbyte-aligned packets which are embedded into a larger byte-aligned 2128e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscontainer structure, such as an Ogg transport bitstream. Externally, 2138e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelseach bytestream (encoded bitstream) must begin and end on a byte 2148e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsboundary. Often, the encoded bitstream is not an integer number of 2158e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsbytes, and so there is unused (uncoded) space in the last byte of a 2168e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelspacket. 2178e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2188e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsUnused space in the last byte of a bytestream is always zeroed during 2198e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsthe coding process. Thus, should this unused space be read, it will 2208e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsreturn binary zeroes. 2218e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2228e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsAttempting to read past the end of an encoded packet results in an 2238e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels'end-of-packet' condition. End-of-packet is not to be considered an 2248e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelserror; it is merely a state indicating that there is insufficient 2258e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsremaining data to fulfill the desired read size. Vorbis uses truncated 2268e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelspackets as a normal mode of operation, and as such, decoders must 2278e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelshandle reading past the end of a packet as a typical mode of 2288e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsoperation. Any further read operations after an 'end-of-packet' 2298e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelscondition shall also return 'end-of-packet'. 2308e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2318e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2328e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2338e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels\subsubsection{reading zero bits} 2348e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2358e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas EckelsReading a zero-bit-wide integer returns the value '0' and does not 2368e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsincrement the stream cursor. Reading to the end of the packet (but 2378e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsnot past, such that an 'end-of-packet' condition has not triggered) 2388e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsand then reading a zero bit integer shall succeed, returning 0, and 2398e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsnot trigger an end-of-packet condition. Reading a zero-bit-wide 2408e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelsinteger after a previous read sets 'end-of-packet' shall also fail 2418e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckelswith 'end-of-packet'. 2428e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2438e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2448e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2458e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2468e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 2478e01cdce135d5d816f92d7bb83f9a930aa1b45aeLucas Eckels 248