Added an unfinished capsnego doc.

Original commit message from CVS:
Added an unfinished capsnego doc.

diff --git a/docs/random/wtay/capsnego2-docs b/docs/random/wtay/capsnego2-docs
new file mode 100644 (file)
index 0000000..7861969
--- /dev/null
+++ b/docs/random/wtay/capsnego2-docs
@@ -0,0 +1,178 @@
+purpose
+-------
+
+GStreamer has a very flexible mechanism to describe media types using
+mime types and key/value pairs (GstCaps). The definition of media types 
+is entirely done by the plugins which can set the media type to one or 
+more of the plugins GstPads. 
+
+Pads with the same mime type and 'compatible' properties are allowed to
+connect. It is possible that a pad can accept or produce many different 
+media types.
+
+The purpose of caps negotiation is to provide a framework for plugins so
+that they can agree on a common media type for their pads.
+
+
+Capabilities (GstCaps)
+----------------------
+
+The core component in the caps negotiation system are GstCaps. They consist
+of:
+
+ - a name (ex. "my_audio_capabilities") 
+ - a mime-type (ex. audio/raw, audio/mp3, ...)
+ - a list of key/value pairs (ex. channels=2, rate=44100, ...)
+
+The list of key/value pairs is maintained by the GstProps object.
+
+The GstProps object maintains a GList of GstPropsEntries. An entry has
+a key, which is always a string constant (internally converted to a GQuark)
+and a value, which can be one of the following:
+
+ - an integer constant (ex. 5)
+ - a float contant (ex. 1.0)
+ - a string constant (ex. "int")
+ - a boolean constant (ex. FALSE)
+ - a fourcc constant (ex. I420) 
+     * fourcc codes are usually used to describe a video format
+
+In addition to these constant values, the following variable values are
+supported too:
+
+ - an integer range (ex. 0-200)
+ - a float range (ex. 1.0-3.0)
+ - a list of values (ex. 1, 2, 5). 
+     * A List cannot contain another list and the
+       entries in the list should all have the
+       same type (int, float, string, fourcc). It is
+       allowed to mix integers/floats and  
+       integer/float ranges in a list.
+
+A capability is usually described as follows:
+
+                                GST_CAPS_NEW (
+      capability name --->        "my_audio_capabilities",
+      mime-type --------->        "audio/raw",
+                          (        "format",   GST_PROPS_STRING ("int"),
+      GstProps ---------> (        "channels", GST_PROPS_INT_RANGE (1, 2),
+       (list of entries)  (        "rate",     GST_PROPS_INT (44100)
+                                )
+
+                               (-----------)   (--------------------------)
+                                  entry key         entry value
+
+Two capabilities can be chained together to form a larger capability:
+
+                              (  GST_CAPS_NEW (
+                              (    "my_mp3_capability",
+                             (    "audio/mp3",
+       one capability ---->  (    NULL    
+        created by chaining   (  ),
+        two capabilities.     (  GST_CAPS_NEW (
+                              (    "my_vorbis_capability",
+                             (    "audio/vorbis",
+                             (    NULL
+                              (  )
+
+Capabilities always work as constraints, this means that they constrain the
+media type tp the given mime-type and properties. By this definition a NULL 
+GstCaps or a NULL GstProps means: no constraints.
+
+
+Variable capabilities vs. fixed capabilities
+--------------------------------------------
+
+A GstProps structure is said to be fixed if it doesn't contain lists or
+ranges, otherwise it is a variable GstProps. A variable GstProps, by definitin
+does not constrain the media type to a set of fixed properties.
+
+A GstCaps is said to be fixed if it is not chained and it doesn't contain
+a variable GstProps component.
+
+
+GstCaps compatibility
+---------------------
+
+<write me>
+
+
+GstCaps usage
+-------------
+
+GstCaps are used in the following data structures:
+
+ - padtemplates. 
+    * padtemplates are added to elementfactory to describe the possible
+      pads that an element created from said factory can have.
+    * padtemplates contain the name, direction and presence of the pads.
+    * padtemplates also describe the media types that this element can
+      accept/produce using GstCaps.
+    * padtemplates can provide fixed or variable GstCaps for the pads.
+    * padtemplates can be used by the element to create its pads and is
+      highly recommended.
+    * the padtemplate GstCaps are saved into the registry so that the
+      media types an element can operate on, are known without having to
+      bring the element into memory.
+      
+ - pad caps
+    * pad caps are _fixed_ caps attached to a pad to describe the exact media
+      type this pad is handling. A pad with caps is said to be a "tainted" pad.
+      
+ - connection filters
+    * a connection filter is created when two pads are connected. It describes 
+      the media type(s) that _can_ flow through this connection. 
+
+ - application connection filters
+    * When the application connects two pads, it can specify an application
+      connection filter that will act as additional constraints on the media types
+      that can flow through the connection.
+
+Connection filters are cleared when two connected pads are disconnected.
+
+
+
+Purpose of caps negotiation
+---------------------------
+
+The purpose of the caps negotiation procedure is to set "pad caps" on a pad
+so that it is compatible with the "connection filter". This has to be done 
+_before_ any data passing happens through the connection.  Data passing between two 
+pads is _not_ allowed when the pad caps are not compatible with the connection 
+filter or when the pad caps of two pads participating in the connection are not
+equal.
+
+Caps negotiation starts as early as possible.
+
+
+Pad connect functions
+---------------------
+
+A Pad can be notified when another pad is connected or reconnected to it with
+fixed or variable caps. This notification will be done with the optional 
+GstPadConnect callback that an element can provide for a pad.
+
+The pad connection 
+
+
+
+GstPad connection
+-----------------
+
+
+
+
+
+
+      
+
+
+
+
+
+
+
+
+
+
+