docs/design/: Small doc updates

Original commit message from CVS:
* docs/design/part-TODO.txt:
* docs/design/part-caps.txt:
* docs/design/part-clocks.txt:
* docs/design/part-negotiation.txt:
* docs/design/part-preroll.txt:
Small doc updates

ChangeLog

@@ -1,3 +1,12 @@
+2005-06-02  Wim Taymans  <wim@fluendo.com>
+
+	* docs/design/part-TODO.txt:
+	* docs/design/part-caps.txt:
+	* docs/design/part-clocks.txt:
+	* docs/design/part-negotiation.txt:
+	* docs/design/part-preroll.txt:
+	Small doc updates 
+
 2005-05-30  Wim Taymans  <wim@fluendo.com>
 
 	* gst/elements/gstidentity.c: (gst_identity_event),

docs/design/part-TODO.txt

@@ -14,9 +14,6 @@
   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.
-
 - implement state change order on get<->loop-get<->loop elements. This probably 
   requires a backtracking algorithm.
 

docs/design/part-caps.txt

@@ -8,7 +8,7 @@ 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.
+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).
 

docs/design/part-clocks.txt

@@ -81,7 +81,7 @@ It is possible to perform a blocking wait on the same ID from multiple
 threads. However, registering the same ID for multiple async notifications is 
 not possible, the callback will only be called once.
 
-None of the wait operations unref the GstClockID, the application is 
+None of the wait operations unref the GstClockID, the owner is 
 responsible for unreffing the ids itself. This holds for both periodic and
 single shot notifications. 
 

docs/design/part-negotiation.txt

@@ -12,7 +12,7 @@ negotiation.
 
 The basics of negotiation are as follows:
 
- - GstCaps (see part-caps.txt) are attached and refcounted before they
+ - GstCaps (see part-caps.txt) are refcounted before they
    are attached to a buffer to describe the contents of the buffer.
    It is possible to add a NULL caps to a buffer, this means that the
    buffer type did not change relative to the previous buffer. If no
@@ -22,7 +22,8 @@ The basics of negotiation are as follows:
  - Before receiving a buffer, an element must check if the datatype of
    the buffer has changed. The element should reconfigure itself to the
    new format before processing the buffer data. If the data type on
-   the buffer is not acceptable, the element should refuse the buffer.
+   the buffer is not acceptable, the element should refuse the buffer by 
+   returning an appropriate return value from the chain function.
 
  - When requesting a buffer from a bufferpool, the prefered type should
    be passed to the buffer allocation function. After receiving a buffer
@@ -102,7 +103,7 @@ The general flow for a sink pad starting a renegotiation.
               |                 |
  get buffer   |  alloc_buf      |
  from pool    |---------------->| 
- with type    |                 | Create buffer of new type B.
+ with type A  |                 | Create buffer of new type B.
               |                 |
  check type   |<----------------|
  and          |                 |

docs/design/part-preroll.txt

@@ -6,6 +6,9 @@ has been queued on the input pad or pads. This process is called prerolling
 and is needed to fill the pipeline with buffers so that the transition to
 PLAYING goes as fast as possible with no visual delay for the user.
 
+Preroll is also crucial in maintaining correct audio and video synchronsation
+and ensuring that no buffers are dropped in the sinks.
+
 After receiving a buffer (or EOS) on a pad the chain/event function should
 wait to render the buffers or in the EOS case, wait to post the EOS
 message.
@@ -37,6 +40,9 @@ The following conditions unlock the preroll:
 
  - a state change
  - a flush event
+
+When the preroll is unlocked by one of these events, a return value of
+GST_FLOW_WRONG_STATE is to be returned to the peer pad.
  
 
 Result of the preroll