From: Tim-Philipp Müller <tim@centricular.net>
Date: Sat, 28 Jul 2012 10:02:30 +0000 (+0100)
Subject: docs: update TOC design docs a little
X-Git-Tag: RELEASE-0.11.93~32
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=05daa261f15e8f65a60adc4f5adc01b556e1817c;p=platform%2Fupstream%2Fgstreamer.git

docs: update TOC design docs a little
---

diff --git a/docs/design/part-toc.txt b/docs/design/part-toc.txt
index 6b5ee43..bb7a477 100644
--- a/docs/design/part-toc.txt
+++ b/docs/design/part-toc.txt
@@ -58,15 +58,63 @@ timestamps for each item using gst_toc_entry_set_start_stop().
 The best way to process already created GstToc is to recursively go through
 the 'entries' and 'subentries' fields.
 
-2. Working with GstMessage
+
+2. TOC scope: global and current
+
+There are two main consumers for TOC information: applications and elements
+in the pipeline that are TOC writers (such as e.g. matroskamux).
+
+Applications typically want to know the entire table of contents (TOC) with
+all entries that can possibly be selected.
+
+TOC writers in the pipeline, however, would not want to write a TOC for all
+possible/available streams, but only for the current stream.
+
+When transcoding a title from a DVD, for example, the application would still
+want to know the entire TOC, with all titles, the chapters for each title,
+and the available angles. When transcoding to a file, we only want the TOC
+information that is relevant to the transcoded stream to be written into
+the file structure, e.g. the chapters of the title being transcoded (or
+possibly only chapters 5-7 if only those have been selected for playback/
+transcoding).
+
+This is why we may need to create two different TOCs for those two types
+of consumers.
+
+Elements that extract TOC information should send TOC events downstream.
+
+Like with tags, sinks will post a TOC message on the bus for the application
+with the global TOC, once a global TOC event reaches the sink.
+
+
+3. Working with GstMessage
+
+If a table of contents is available, applications will receive a TOC message
+on the pipeline's GstBus.
+
+A TOC message will be posted on the bus by sinks when the receive a TOC event
+containing a TOC with global scope. Elements extracting TOCs should not post
+a TOC message themselves, but send a TOC event downstream.
+
+The reason for this is that there may be cascades of TOCs (e.g. a zip archive
+containing multiple matroska files, each with a TOC).
 
 GstMessage with GstToc can be created using gst_message_new_toc() and parsed
 with gst_message_parse_toc(). The 'updated' parameter in these methods indicates
 whether the TOC was just discovered (set to false) or TOC was already found and
-have been updated (set to true). The common usage for such message is to post it
+have been updated (set to true). This message will typically be posted by sinks
 to pipeline in case you have discovered TOC data within your element.
 
-3. Working with GstEvent
+
+4. Working with GstEvent
+
+There are two types of TOC-related events:
+
+ - downstream TOC events that contain TOC information and
+   travel downstream
+
+ - toc-select events that travel upstream and can be used to select
+   a certain TOC entry for playback (similar to seek events)
 
 GstToc supports select event through GstEvent infrastructure. The idea is the
 following: when you receive TOC select event, parse it with