STATUS: pull on srcpads is outdated, they use _get
--------------------------------------------------

0) definitions:

All pads without further specifiers are assumed to belong to the element
in question.  The pad's peer is always denoted with ->peer.  If there's
question, pads will be prefixed with self-> and other-> as necessary.

All elements in this document have at most one source and one sink pad,
called srcpad and sinkpad. Multi-pad cases are supposed to be simple
extrapolations except in a couple strange cases, to be covered elsewhere.


1) loop functions:

A loop function will call gst_pad_pull(sinkpad), do something, and call
gst_pad_push(srcpad).

gst_pad_pull first checks to see if there's a buffer in the pen.  If not,
it calls that pad's pullfunc handler, passing it the peer pad.  When that
finishes, we check again and return the buffer.  If no buffer, we squawk.
The pullfunc handler simply causes a cothread switch to the peer pad's
context;

gst_pad_push places the buffer in the peer pad's pen, and calls the local
pad's pushfunc.  The pushfunc simply causes a switch to the peer pad's
context.


2) chain functions

The loopfunc constructed around a chain function starts by finding all
sink pads.  For each sink pad, it calls gst_pad_pull.  This causes a
switch to the peer pad's context and a buffer to appear, which is
returned.  The pad is the handed off to the chain function, which
presumably does some processing and calls gst_pad_push(), which causes a
context switch to that pad's peer.


3) source

The loopfunc must repeatedly call the srcpad's pull


---------------------------------	---------------------------------
 srcpad				|	| sinkpad
				|	|
 GstPad *peer;			| <-p->	| GstPad *peer;
   pointer to peer pad		|	|   pointer to peer pad
				|	|
 funcptr *pushfunc;		| --s->	| funcptr *pushfunc;
   causes switch to peer ctx	|	|   element uses buffer in pen,
				|	|
 funcptr *pullfunc;		| <-s--	| funcptr *pullfunc;
   element puts buffer in pen,	|	|   causes switch to peer ctx
   calls gst_pad_push()		|	|
				|	|
 funcptr *pullregion func	| <-s--	| funcptr *pullregionfunc;
   element puts region in pen	|	|   causes switch to peer ctx
   calls gst_pad_push()		|	|
---------------------------------	---------------------------------