[xiph-commits] r17095 - trunk/ogg/doc

Sun Mar 28 03:15:49 PDT 2010

Author: xiphmont
Date: 2010-03-28 03:15:49 -0700 (Sun, 28 Mar 2010)
New Revision: 17095

Added:
   trunk/ogg/doc/packets.png
   trunk/ogg/doc/pages.png
Modified:
   trunk/ogg/doc/oggstream.html
Log:
Add two new figures illustrating packets, pages, logical bitstreams and 
physical bitstreams.



Modified: trunk/ogg/doc/oggstream.html
===================================================================

--- trunk/ogg/doc/oggstream.html	2010-03-27 16:27:05 UTC (rev 17094)
+++ trunk/ogg/doc/oggstream.html	2010-03-28 10:15:49 UTC (rev 17095)
@@ -60,11 +60,44 @@
   color: #888888;
   clear: both;
 }
+
+.caption {
+  color: #000000;
+  background-color: #aabbff;
+  margin: 1em;
+  margin-left: 2em;
+  margin-right: 2em;
+  padding: 1em;
+  padding-bottom: 0em;
+  overflow: hidden;
+}
+
+.caption p {
+  clear: none;
+}
+
+.caption img {
+  display: block;
+  margin: 0px;
+  margin-left: auto;
+  margin-right: auto;
+  margin-bottom: 1.5em;
+  background-color: #ffffff;
+  padding: 10px;
+}
+   
+#thepage {
+  margin-left: auto;
+  margin-right: auto;
+  width: 840px;
+}
+
 </style>
 
 </head>
 
 <body>
+<div id="thepage">
 
 <div id="xiphlogo">
   <a href="http://www.xiph.org/"><img src="fish_xiph_org.png" alt="Fish Logo and Xiph.org"/></a>
@@ -332,6 +365,20 @@
 <em>logical bitstream</em> of apparently random bytes with no internal
 landmarks.
 
+<div class="caption">
+  <img src="packets.png"> 
+
+  <p> Packets of raw codec data are not typically internally framed.
+  When they are strung together into a stream without any container to
+  provide framing, they lose their individual boundaries. Seek and
+  capture are not possible within an unframed stream, and for many
+  codecs with variable length payloads and/or early-packet termination
+  (such as Vorbis), it may become impossible to recover the original
+  frame boundaries even if the stream is scanned linearly from
+  beginning to end.
+
+</div>
+
 <p>Logical bitstream packets are grouped and framed into Ogg pages
 along with a unique stream <em>serial number</em> to produce a
 <em>physical bitstream</em>.  An <em>elementary stream</em> is a
@@ -341,6 +388,23 @@
 mechanism is designed to recognize, verify and handle single pages at
 a time from the overall bitstream.
 
+<div class="caption">
+  <img src="pages.png"> 
+
+  <p> The primary purpose of a container is to provide framing for raw
+  packets, marking the packet boundaries so the exact packets can be
+  retrieved for decode later.  The container also provides secondary
+  functions such as capture, timestamping, sequencing, stream
+  identification and so on.  Not all of these functions are represented in the diagram.
+
+  <p>In the Ogg container, pages do not necessarily contain
+  integer numbers of packets. Packets may span across page boundaries
+  or even multiple pages.  This is necessary as pages have a maximum
+  possible size in order to provide capture guarantees, but packet
+  size is unbounded.
+</div>
+
+
 <p><a href="framing.html">Ogg Bitstream Framing</a> specifies
 the page format of an Ogg bitstream, the packet coding process
 and elementary bitstreams in detail.
@@ -455,8 +519,8 @@
 consecutively. Such a physical bitstream obeys all the rules of both
 chained and multiplexed streams.  Each link, when unchained, must
 stand on its own as a valid physical bitstream.  Chained streams do
-not mix; a new segment may not begin until all streams in the
-preceding segment have terminated. </p>
+not mix or interleave; a new segment may not begin until all streams
+in the preceding segment have terminated. </p>
 
 <h2>Examples</h2>
 
@@ -489,5 +553,6 @@
   These pages &copy; 1994 - 2010 Xiph.Org. All rights reserved.
 </div>
 
+</div>
 </body>
 </html>

Added: trunk/ogg/doc/packets.png
===================================================================
(Binary files differ)


Property changes on: trunk/ogg/doc/packets.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

Added: trunk/ogg/doc/pages.png
===================================================================
(Binary files differ)


Property changes on: trunk/ogg/doc/pages.png
___________________________________________________________________
Added: svn:mime-type
   + application/octet-stream

