docs/design/: Some more docs.

Original commit message from CVS:
* docs/design/draft-push-pull.txt:
* docs/design/part-MT-refcounting.txt:
* docs/design/part-TODO.txt:
* docs/design/part-caps.txt:
* docs/design/part-events.txt:
* docs/design/part-gstbus.txt:
* docs/design/part-gstpipeline.txt:
* docs/design/part-messages.txt:
* docs/design/part-push-pull.txt:
* docs/design/part-query.txt:
Some more docs.

ChangeLog

@@ -1,3 +1,17 @@
+2005-04-21  Wim Taymans  <wim@fluendo.com>
+
+	* docs/design/draft-push-pull.txt:
+	* docs/design/part-MT-refcounting.txt:
+	* docs/design/part-TODO.txt:
+	* docs/design/part-caps.txt:
+	* docs/design/part-events.txt:
+	* docs/design/part-gstbus.txt:
+	* docs/design/part-gstpipeline.txt:
+	* docs/design/part-messages.txt:
+	* docs/design/part-push-pull.txt:
+	* docs/design/part-query.txt:
+	Some more docs.
+
 2005-04-21  Wim Taymans  <wim@fluendo.com>
 
 	* gst/gstmessage.c: (_gst_message_copy), (_gst_message_free),

docs/design/draft-push-pull.txt

@@ -0,0 +1,90 @@
+DRAFT push-pull scheduling
+--------------------------
+
+Observations:
+
+  - The main scheduling mode is chain based scheduling where the source
+    element pushes buffers through the pipeline to the sinks. this is
+    called the push model
+
+  - In the pull model, some plugin pulls buffers from an upstream peer
+    element before consuming and/or pushing them further downstream.
+
+
+Usages of pull based scheduling:
+
+  - sinks that pull in data, possibly at fixed intervals driven by some
+    hardware device (audiocard, videodevice, ...).
+
+  - Efficient random access to resources. Especially usefull for certain
+    types of demuxers.
+
+
+API for pull-based scheduling:
+
+  - an element that wants to pull data from a peer element needs to call
+    the pull_range() method. This methods requires an offset and a size.
+    It is possible to leave the offset and size at -1, indicating that
+    any offset or size is acceptable, this of course removes the advantages
+    of getrange based scheduling.
+
+
+Types of pull based scheduling:
+
+  - some sources can do random access (file source, ...)
+
+  - some sources can read a random number of bytes but not at a random
+    offset. (audio cards, ...)
+
+  - some sources can do random access in a range of bytes but not in
+    another range. (a caching network source).
+
+  - some sources can do a fixed size data but without an offset. 
+    (video sources, ...)
+  
+      
+Current scheduling decision:
+
+  - core selects scheduling type starting on sinks by looking at existence
+    of loop function on sinkpad and calling _check_pull_region() on the
+    source pad to activate the pads in push/pull mode.
+
+  - element proxies pull mode pad activation to peer pad.
+
+Problems:
+
+  - core makes a touch desicion without knowing anything about the 
+    element. 
+    
+
+Requirements:
+
+  - element should be able to select scheduling method itself based on
+    how it can use the peer element pull_region. This includes if the
+    peer can operate with or without offset/size. This also means that
+    the core does not need to select the scheduling method anymore and
+    allows for more afficient scheduling methods adjusted for the 
+    particular element.
+
+
+Proposition:
+
+  - pads are activated without the core selecting a method.
+
+  - pads queries scheduling mode of peer pad. This query is rather
+    finegrained and allows the element to know if the peer supports
+    offsets and sizes in the get_region function.
+  
+  - pad selects scheduling mode and informs the peer pad of this
+    decision.
+
+
+
+
+    
+
+  
+
+
+    
+     

docs/design/part-MT-refcounting.txt

@@ -106,6 +106,11 @@ Object locking:
   Object locking is used for all objects extending from GstObject such as
   GstElement, GstPad.
 
+  Object locking can be done with recursive locks or regular mutexes. Object
+  locks in GStreamer are implemented with mutexes which cause deadlocks when
+  locked recursively from the same thread. This is done because regular mutexes
+  are cheaper.
+
 Atomic operations
 
   Atomic operations are operations that are performed as one consistent
@@ -174,6 +179,8 @@ Objects
   then be placed under control of a parent. The floating ref keeps the object
   alive until it is parented, and once the object is parented you can forget
   about it.
+
+  also see part-relations.txt
   
 * parent-child relations
 
@@ -198,6 +205,7 @@ Objects
        object.
      - remove the object from the list.
 
+  also see part-relations.txt
 
 * Properties
   
@@ -332,8 +340,8 @@ Objects
   In some cases it is not a good idea to hold the lock for a long time while
   iterating the list. The state change code for a bin in GStreamer, for example,
   has to iterate over each element and perform a blocking call on each of them
-  causing infinite bin locking. In this case the cookie can be used to iterate a
-  list.
+  potentially causing infinite bin locking. In this case the cookie can be used 
+  to iterate a list.
 
   Example:
 

docs/design/part-TODO.txt

@@ -10,7 +10,9 @@
 - only emit EOS in PLAYING. Make sure elements reemit the EOS message when going to
   PLAYING again.
 
-- implement return values from events in addition to the gboolean.
+- implement return values from events in addition to the gboolean. This should be
+  done by making the event contain a GstStructure with input/output values, similar
+  to GstMessage.
 
 - implement query ala events as opposed to the current return value of only a 
   guint64. I don't have a use case where this a problem yet, though.
@@ -24,12 +26,8 @@
   executing code. Can this be done with a flush to unlock all downstream chain
   functions?
 
-- implement seek in GstPipeline.
-
-- make events use GstStructure like GstMessage instead of the current union.
-
 - make the seek event return the time where the seek will happen so that GstPipeline
-  can update the stream time.
+  can update the stream time. This is linked with making the events return values.
 
 - implement clock selection as explained in part-gstpipeline.txt
 

docs/design/part-caps.txt

@@ -0,0 +1,20 @@
+Caps
+----
+
+Caps are lighweight refcounted objects describing media types.
+They are composed of an array of GstStructures.
+
+Caps are exposed on GstPadTemplates to describe all possible types a
+given pad can handle. They are also stored in the registry along with
+a description of the element.
+
+Caps are exposed on the element pads using the get_caps pad function.
+This function describes the possible types that the pad can handle or
+produce (see part-pads.txt and part-negotiation.txt).
+
+Caps are also attached to buffers to describe to content of the data
+pointed to be the buffer.
+
+Various methods exist to work with the media types such as substracting
+or intersecting.
+

docs/design/part-events.txt

@@ -103,7 +103,7 @@ A seek event is issued by the application to start playback of a new
 position in the stream. It is called form the application thread and
 travels upstream.
 
-The seek event contains the new start end end position of playback
+The seek event contains the new start and end position of playback
 after the seek is performed. Optionally the end position can be left
 at -1 to continue playback to the end of the stream.
 
@@ -131,7 +131,8 @@ The general flow of executing the seek is as follows:
  2) lock the STREAM_LOCK. This will work since the chain/loop function
     was unlocked in step 1).
 
- 3) perform the seek.
+ 3) perform the seek. since the STREAM_LOCK is held, the streaming thread
+    will wait for the seek to complete.
 
  4) send a flush event with the done flag set to allow streaming again.
 

docs/design/part-gstbus.txt

@@ -6,7 +6,8 @@ a first-in first-out way from the streaming threads to the application.
 
 Since the application typically only wants to deal with delivery of these
 messages from one thread, the GstBus will marshall the messages between
-different threads.
+different threads. This is important since the actual streaming of media
+is done in another thread than the application.
 
 The GstBus provides support for GSource based notifications. This makes it
 possible to handle the delivery in the glib mainloop.

docs/design/part-gstpipeline.txt

@@ -27,6 +27,23 @@ The application can retrieve the GstBus and integrate it in the
 mainloop or it can just _pop() messages off in its own thread.
 
 
+State changes
+-------------
+
+In addition to the normal state change procedure of its parent class
+GstBin, the pipeline performs the following actions during a state change:
+
+ - READY -> PAUSED:
+    - Select and set a clock.
+
+ - PAUSED -> PLAYING:
+    - calculate the stream time.
+
+The GstPipeline will also wait for any async state change to complete before
+proceeding to the next state change. This is usefull for the application because
+it does not have to deal with ASYNC state changes then.
+
+
 Clock selection
 ---------------
 

docs/design/part-messages.txt

@@ -4,3 +4,72 @@ Messages
 Messages are refcounted lightweight objects to signal the application
 of pipeline events. 
 
+Messages are implemented as a subclass of GstData with a generic 
+GstStructure as the content. This allows for writing custom messages without
+requiring an API change while allowing a wide range of different types
+of messages.
+
+Messages are posted by objects in the pipeline and are passed to the 
+application using the GstBus. 
+
+
+Message types
+-------------
+
+  GST_MESSAGE_EOS:
+
+    The pipeline went to EOS. This means that all the sink elements in the
+    pipeline posted the EOS message to the bus.
+  
+  GST_MESSAGE_ERROR:
+  
+    An element in the pipeline got into an error state. The message carries
+    a GError and a debug string describing the error. This usually means that
+    part of the pipeline is not streaming anymore.
+  
+  GST_MESSAGE_WARNING:
+  
+    An element in the pipeline encountered a condition that made it produce a
+    warning. This could be a recoverable decoding error or some other non fatal
+    event. The pipeline continues streaming after a warning.
+  
+  GST_MESSAGE_INFO:
+
+    An element produced an informational message.
+  
+  GST_MESSAGE_TAG:
+
+    An element decoded metadata about the stream. The message carries a GstTagList
+    with the tag information.
+  
+  GST_MESSAGE_BUFFERING:
+  
+    An element is buffering data and that could potentially take some time.
+  
+  GST_MESSAGE_STATE_CHANGED:
+
+    An element changed state in the pipeline. The message carries the old an new
+    state of the element.
+  
+  GST_MESSAGE_STEP_DONE:
+
+    An element stepping frames has finished.
+  
+  GST_MESSAGE_NEW_CLOCK:
+
+    A new clock was selected for the pipeline.
+
+  GST_MESSAGE_STRUCTURE_CHANGE:
+
+    The pipeline changed of structure, This means elements were added or removed or
+    pads were linked or unlinked.
+
+  GST_MESSAGE_STREAM_STATUS:
+
+   An element posted information about the stream it is handling. This could include
+   information about the length of the stream.
+    
+  GST_MESSAGE_APPLICATION:
+
+    An element posted an application specific message.
+

docs/design/part-push-pull.txt

@@ -0,0 +1,46 @@
+push-pull
+---------
+
+Normally a source element will push data to the downstream element using
+the gst_pad_push() method. The downstream peer pad will receive the
+buffer in the Chain function. In the push mode, the source element is the
+driving force in the pipeline as it initiates data transport.
+
+It is also possible for an element to pull data from an upstream element.
+The downstream element does this by calling gst_pad_pull_range() on one
+of its sinkpads. In this mode, the upstream element is the driving force 
+in the pipeline as it initiates data transfer.
+
+It is important that the elements are in the correct state to handle a
+push() or a pull_range() from the peer element. For push() based elements
+this means that all downstream elements should be in the correct state and
+for pull_range() based elements this means the upstream elements should
+be in the correct state.
+
+Most sinkpads implement a chain function. This is the most common case.
+sinkpads implementing a loop function will be the exception. Likewise
+srcpads implementing a getrange function will be the exception.
+
+
+state changes
+-------------
+
+The GstBin sets the state of all the sink elements. These are the elements
+without source pads.
+
+Setting the state on an element will first activate all the sinkpads. For
+each of the sinkpads, gst_pad_check_pull_range() is performed. If the 
+sinkpad supports a loopfunction and the peer pad returns TRUE from the
+GstPadCheckPullRange function, then the peer pad is activated first as
+it must be in the right state to handle a _pull_range(). Note that the
+state change of the element is not yet performed, just the activate function
+is called on the source pad. This means that elements that implement a
+getrange function must be prepared to get their activate function called
+before their state change function.
+
+Elements that have multiple sinkpads that require all of them to operate
+in the same mode (push/pull) can use the _check_pull_range() on all
+their pads and can then remove the loop functions if one of the pads does
+not support pull based mode.
+
+

docs/design/part-query.txt

@@ -0,0 +1,69 @@
+Query
+-----
+
+Queries are used to get information about the state of the stream.
+Various queries exist such as get the total length and the position
+
+A query can be performed on a pad or on an element. Both the element
+and the pad query have default behaviour unless a custom query handler
+is installed.
+
+The default pad query handler will forward the query to an internally
+linked pad. This internally linked pad is either obtained by calling
+the internal_links function of the pad or by using the default 
+function (which selects the pads with oposite directions from the parent
+element).
+
+The default element query function will select a random source pad to
+send the event to.
+
+The pad query function has the following prototype:
+
+    gboolean (*GstPadQueryFunction) (GstPad *pad, GstQueryType type,
+                                     GstFormat *format, gint64  *value);
+
+The query function can return a single value in one of the defined
+formats.
+
+The function returns TRUE if the query could be performed. The returned
+values are undefined when this function returns FALSE.
+
+
+Query types
+-----------
+
+ GST_QUERY_TOTAL:
+
+   get the total length of the stream in the given format.
+
+ GST_QUERY_POSITION:
+
+   get the current position in the stream in the given format.
+
+ GST_QUERY_LATENCY:
+
+   get the latency introduced in the stream in the given format.
+   This query can be used to retrieve how much data is queued in a
+   queue or in a hardware device such as an audio sink.
+
+ GST_QUERY_JITTER:
+
+   Get the jitter, this is the difference between the expected and real
+   time a buffer is captured or played.
+
+ GST_QUERY_START:
+
+   Query the position in the stream where the last start position was
+   configured. When a seek was performed to play a stream from A to B,
+   this query will return A.
+
+ GST_QUERY_SEGMENT_END:
+
+   Query the position in the stream where the last end position was
+   configured. When a seek was performed to play a stream from A to B,
+   this query will return B.
+
+ GST_QUERY_RATE:
+
+   Query the current playback rate of the stream.
+