docs: add overview of GstToc usage

docs/design/Makefile.am

@@ -44,6 +44,7 @@ EXTRA_DIST = \
 	part-stream-status.txt \
 	part-streams.txt \
 	part-synchronisation.txt \
+	part-toc.txt \
 	part-TODO.txt \
 	part-trickmodes.txt
 

docs/design/part-toc.txt

@@ -0,0 +1,89 @@
+Implementing GstToc support in GStreamer elements
+
+1. General info about GstToc structure
+
+GstToc introduces a general way to handle chapters within multimedia
+formats. GstToc can be represented as tree structure with arbitrary
+hierarchy. Tree item can be either of two types: chapter or edition.
+Chapter acts like a part of the media data, for example audio track
+in CUE sheet, or part of the movie. Edition acts like some kind of
+alternative way to process media content, for example DVD angles.
+GstToc has one limitation on tree structure: on the same level of
+hierarchy there couldn't be items of different type, i.e. you shouldn't
+have editions and chapters mixed together. Here is an example of right TOC:
+
+  -------  TOC  -------
+           /  \
+   edition1    edition2
+   |           |
+   -chapter1   -chapter3
+   -chapter2       
+
+Here are two editions, the first contains two chapters, and the second
+has only one chapter. And here is an example of invalid TOC:
+
+  -------  TOC  -------
+           /  \
+   edition1    chapter1
+   |                 
+   -chapter1
+   -chapter2    
+ 
+Here you have edition1 and chapter1 mixed on the same level of hierarchy,
+and such TOC will be considered broken.
+
+GstToc has 'entries' field of GList type which consists of children items.
+Each item is of type GstTocEntry. Also GstToc has list of tags and
+GstStructure called 'info'. Please, use GstToc.info and GstTocEntry.info
+fields this way: create a GstStructure, put all info related to your element
+there and put this structure into the 'info' field under the name of your
+element. Some fields in the 'info' structure can be used for internal
+purposes, so you should use it in the way described above to not to
+overwrite already existent fields.
+
+Let's look at GstTocEntry a bit closer. One of the most important fields
+is 'uid', which must be unique for each item within the TOC. This is used
+to identify each item inside TOC, especially when element receives TOC
+select event with UID to seek on. Field 'subentries' of type GList contains
+children items of type GstTocEntry. Thus you can achieve arbitrary hierarchy
+level. Field 'type' can be either GST_TOC_ENTRY_TYPE_CHAPTER or
+GST_TOC_ENTRY_TYPE_EDITION which corresponds to chapter or edition type of
+item respectively. Field 'pads' of type GList contains list of GStreamer
+pads related to the item. It can be used for example to link a TOC with
+specific pad. Field 'tags' is a list of tags related to the item. And field
+'info' is similar to GstToc.info described above.
+
+So, a little more about managing GstToc. Use gst_toc_new() and gst_toc_free()
+to create/free it. GstTocEntry can be created using gst_toc_entry_new() and
+gst_toc_entry_new_with_pad(). The latter method used to create GstTocEntry
+linked to particular pad. While building GstToc you can set start and stop
+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 GstQuery
+
+GstQuery with GstToc can be created using gst_query_new_toc(). Use
+gst_query_set_toc() to set TOC into the query and parse it with
+gst_query_parse_toc(). The 'extend_uid' parameter (0 for root level) in two
+last methods should be used for TOC extending: get GstTocEntry with
+gst_toc_find_entry() by given UID and use it to add your own chapters/editions.
+The common action on such query is to set TOC for it.
+
+3. Working with GstMessage
+
+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
+to pipeline in case you have discovered TOC data within your element.
+
+4. Working with GstEvent
+
+GstToc supports select event through GstEvent infrastructure. The idea is the
+following: when you receive TOC select event, parse it with
+gst_event_parse_toc_select() and seek stream (if it is not streamable) for
+specified TOC UID (you can use gst_toc_find_entry() to find entry in TOC by UID).
+To create TOC select event use gst_event_new_toc_select(). The common action on
+such event is to seek to specified UID within your element. 
+