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.

1 files changed, 46 insertions, 0 deletions

diff --git a/docs/design/part-push-pull.txt b/docs/design/part-push-pull.txt
new file mode 100644
index 0000000000..6508b52adf
--- /dev/null
+++ b/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.
+
+