Some random docs updates I had lying around

Original commit message from CVS:
Some random docs updates I had lying around

docs/manual/advanced-schedulers.xml

@@ -1,6 +1,42 @@
 <chapter id="cha-scheduler">
   <title>Understanding schedulers</title>
   <para> 
+    The scheduler is responsible for managing the plugins at runtime. The
+    main responsabilities are:
+    <itemizedlist>
+      <listitem>
+        <para>
+	  Preparing the plugins so they can be scheduled. 
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+	  Monitoring state changes and enabling/disabling the element in the
+	  chain.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+	  Choosing an element as the entry point for the pipeline.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+	  Selecting and distributing the global clock.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </para>
+  <para> 
+    The scheduler is a plugable component, this means that alternative schedulers
+    can be written and plugged into GStreamer. The default scheduler uses cothreads
+    to schedule the plugins in a pipeline. Cothreads are fast and lightweight 
+    user-space threads.
+  </para>
+  <para> 
+    There is usually no need to interact with the scheduler directly, however it some
+    cases it is feasable to set a specific clock or force a specific plugin as the
+    entry point in the pipeline.
   </para>
 
 </chapter>

docs/manual/schedulers.xml

@@ -1,6 +1,42 @@
 <chapter id="cha-scheduler">
   <title>Understanding schedulers</title>
   <para> 
+    The scheduler is responsible for managing the plugins at runtime. The
+    main responsabilities are:
+    <itemizedlist>
+      <listitem>
+        <para>
+	  Preparing the plugins so they can be scheduled. 
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+	  Monitoring state changes and enabling/disabling the element in the
+	  chain.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+	  Choosing an element as the entry point for the pipeline.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+	  Selecting and distributing the global clock.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </para>
+  <para> 
+    The scheduler is a plugable component, this means that alternative schedulers
+    can be written and plugged into GStreamer. The default scheduler uses cothreads
+    to schedule the plugins in a pipeline. Cothreads are fast and lightweight 
+    user-space threads.
+  </para>
+  <para> 
+    There is usually no need to interact with the scheduler directly, however it some
+    cases it is feasable to set a specific clock or force a specific plugin as the
+    entry point in the pipeline.
   </para>
 
 </chapter>

docs/random/wtay/DVDplayer

@@ -0,0 +1,41 @@
+A DVDplayer
+-----------
+
+1) set up a pipeline
+
+ <draw pipeline schematics here>
+
+2) set to playing
+
+ - dvdnav reads the ifo file. A set of events are generated to configure
+   various elements in the pipeline. These would include:
+     - SPU colors
+     - whatmore..
+
+ - first the src will read the DVD menu. this will contain mpeg2 data
+   and spu/nav info. after the menu is sent down the pipeline
+   the nav decoder waits for input somehow. The pipeline keeps on 
+   playing to animate the menus.
+
+ - somehow a button is pressed on the menu: a method is triggered in
+   the dvdnav plugin to tell it button X was pressed (event? app?).
+
+ - dvdnav reacts and starts to stream other data.
+
+ - nav packets in the stream indicate what can happen next.
+   - update the menu
+   - keep the menu
+   - hide the menu
+   - show the menu
+
+ - pressing the hotkey to bring up the menu triggers a method in dvdnav
+   which will send down nav info downstream to bring up the menu. 
+   A background picture (I frame) is sent downstream too.
+
+ - nav info can also happen while playing the movie. This can highlite 
+   some buttons the user can press.
+   
+ - selecting a button triggers some color/compositing changes in SPU/NAVdec
+   and an action on dvdnav.
+
+   

docs/random/wtay/abstract

@@ -1,12 +1,33 @@
-This talk will present the GStreamer Media framework. We will
+This paper will present the GStreamer Media framework. We 
 explain briefly what a media framework is and what its advantages
-are. This introduction will present the basic design of GStreamer
+are. This introduction presents the basic design of GStreamer
-and how the modularity can provide many benefits.
+and how the modularity can provide many benefits when building 
+multimedia applications ranging from simple audio/video players 
+to complex audio/video mixing and non linear editing.
 
-We will then go into more detail about the different components of
+We then go into more detail about the different components of
-the framework and how specific problems were solved, such as 
+the framework and how specific problems were solved.
-pipelines, scheduling, state changes, buffers, type negotiation and
+State changes are covered first as they bring the pipeline with
-events.
+all its components from a sleeping to a running state. The most
+interesting problem here is error recovery and thread interlocking.
 
-We will conclude the presentation with a little demonstration of 
+We expand on the scheduler that is responsible for making sure all 
-the provided tools and applications.
+of the components don't step on eachothers toes as they pass along 
+data. We explain one of the possible scheduling methods using
+cothreads and expand on how the number of cothread switches can
+be reduced in order to make the data flow as fast as possible.
+
+Since GStreamer is a very open system that can basically handle
+any media type, a mechanism is provided to negotiate the media
+types between plugins. We continue with an explanation of how
+this type negotiation is done.
+
+Events are the mechanism to indicate changes in the data that is
+flowing through the pipeline, such as End Of Stream notification
+or seek and flush events. We explain how these events work and
+how they interact with the scheduler.
+
+We finally cover some of the interesting libraries that are 
+provided with GStreamer, such as the bytestream library. We 
+explain how all the pieces fit together and how we combine different
+techniques to create a very fast read API.

docs/random/wtay/capsnego2-docs

@@ -162,7 +162,10 @@ 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.
+Real caps negotiation starts as soon as an element is in the READY state or higher.
+This means that the connect functions of the pads are only called when the element
+is at least READY. The intersection between two pads is made at connect time, 
+regardless of element state.
 
 
 GstPad connection
@@ -194,14 +197,14 @@ Note that pad caps are never set for non fixed caps.
 !Example 1:
 ! 
 ! 1. before connecting the pads, they both have a set of possible media types,
-!    on the pad, through the gstcaps function or on the padtemplate (here
+!    on the pad, through the getcaps function or on the padtemplate (here
 !    represented with capital letters)
 !
 !    srcpad                       sinkpad
 !       A                           B
 !       B                           F
 !       C                           A
-!	                          G
+!	                            G
 !
 ! 2. when performing the connection, the intersection between the two sets of caps
 !    is made.
@@ -218,7 +221,7 @@ Note that pad caps are never set for non fixed caps.
 ! 
 ! 4. if the caps are accepted, the intersection caps are set on both pads.
 ! 
-! 5. plugins will typically no configure themselves if they get variable caps.
+! 5. plugins will typically not configure themselves if they get variable caps.
 !    It is possible though for a plugin to select one of the caps, fixate
 !    some properties and refine the filter to fixed caps (see later)
 !
@@ -266,16 +269,37 @@ Note that pad caps are never set for non fixed caps.
 !
 
 
-
 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 
 GstPadConnectFunction callback that an element can provide for a pad.
-iRemember that this connection is _always_ called, not only whith fixed caps
+Remember that this connection is _always_ called, not only whith fixed caps
 but also with variable caps (if any).
 
+We will explain some of the common situations with some examples.
+
+!Example 4:
+!
+! 1. We have a simple mpeg audio decoder connected to a simple audio sink.
+!    The mpeg decoder doesn't have a connect function on 
+!
+!
+!
+!
+!
+!
+!
+!
+!
+!
+!
+!
+!
+!
+!
+!
 
 
 

docs/random/wtay/clocking

@@ -81,7 +81,7 @@ clock providers and receivers are collected in the bins on element
 add/remove, recursing bins if needed. 
 
 the toplevel bin with a scheduler selects the global clock and calls
-set_clock on itself.
+set_clock on itself. This happens in the NULL->READY state.
 
 bins dispatch the set_clock to to all of the reveivers. Bins with
 a scheduler and another use_clock do nothing.
@@ -134,6 +134,13 @@ set to 0.
 When the clock is enabled again, it should start counting from where
 it was last disabled.
 
+NULL->READY     : distribute clock, clock_reset, 
+READY->PAUSED   : clock_activate (FALSE)
+PAUSED->PLAYING : clock_activate (TRUE)
+PLAYING->PAUSED : clock_activate (FALSE);
+PAUSED->READY   : clock_reset
+READY->NULL     : delete clock;
+
 
 automatic Clock selection
 -------------------------
@@ -155,6 +162,39 @@ stutter and cracle if this is the case.	QoS and a resampler could solve
 this.
 
 
+Use Cases
+---------
+                     -- queue ! mpeg2dec ! videosink
+                    /
+filesrc ! mpegdemux 
+                    \
+                     -- queue ! mad ! osssink
+
+
+videosink is a receiver
+osssink is a provider
+
+osssink is selected as a clock provider since it is a Sink. The global
+pipeline distributes the clock to videosink and osssink.
+osssink sees that it receives its own clock.
+
+osssink uses the OSS ioctls to determine the number of bytes processed
+by the hardware. using the audio rate it can figure out the exact time
+and updates its clock with a resolution that matches the resolution 
+as closely as possible. 
+
+videosink blocks on the clock. with each update of the clock videosink
+is unblocked if the current time >= wait time and shows the frame.
+
+when osssink is PAUSED, the clock will not be updated anymore. osssink
+instructs its clock to convert all requests to select() calls.
+When it is set to PLAYING again, it resumes normal operation.
+
+
+
+
+
+
 
 
 

docs/random/wtay/registry

@@ -20,6 +20,42 @@ user/system registry
 
 first query the user registry, then fall back to system registry.
 
+model:
+------
+
+registry_pool
+ !
+ !---> registry (name, priority)
+ !
+ !
+ !---> registry (name, priority)
+ !        !
+ !	  !-> plugin
+ !	  !
+ !	  !-> plugin
+ !       ...    !
+ !              !-> feature ...
+ !
+ ...
+
+
+A registrypool holds a list of registries each with a priority
+
+A registry contains a list of plugins (or libraries)
+
+A plugin contains a list of features (elementfactories, typefacories, ...)
+
+Loading the registry will do
+
+ - instantiate empty GstPlugin objects (loaded flag == FALSE)
+ - instantiate empty plugin features
+
+
+
+
+
+
+ 
 API
 ---