current set of design docs, in .txt format

Original commit message from CVS:
current set of design docs, in .txt format

docs/design/part-conventions.txt

@@ -0,0 +1,31 @@
+Documentation conventions
+=========================
+
+Due to the potential for exponential growth, several abbreviating conventions will be used throughout this 
+documentation.  These conventions have grown primarily from extremely in-depth discussions of the architecure in IRC.  
+This has verified the safety of these conventions, if used properly.  There are no known namespace conflicts as long as 
+context is rigorously observed.
+
+Object classes
+--------------
+
+Since everything starts with Gst, we will generally refer to objects by the shorter name, i.e. Element or Pad.  These 
+names will always have their first letter capitalized.
+
+Function names
+--------------
+
+Within the context of a given object, functions defined in that object's header and/or source file will have their 
+object-specific prefix stripped.  For instance, gst_element_add_pad() would be referred to as simply _get_pad().  Note 
+that the trailing parentheses should always be present, but sometimes may not be.  A prefixing underscore (_) will 
+always tell you it's a function, however, regardless of the presence or absence of the trailing parentheses.
+
+#defines and enums
+------------------
+
+Values and macros defined as enums and preprocessor macros will be referred to in all capitals, as per their 
+definition.  This includes object flags and element states, as well as general enums.  Examples are the states NULL, 
+READY, PLAYING, and PAUSED; the element flags DECOUPLED and USE_COTHREAD, and state return values SUCCESS, FAILURE, and 
+ASYNC.  Where there is a prefix, as in the element flags, this is usually dropped, and implied.  Not however that 
+element flags should be cross-checked with the header, as there are currently two conventions in use: with and without 
+_FLAGS_ in the middle.

docs/design/part-gstelement.txt

@@ -0,0 +1,77 @@
+  gstelement
+    name
+    pads
+    state
+    loopfunction
+    threadstate
+    manager
+    ghostpads
+
+GstElement
+==========
+
+The Element is the most important object in the entire GStreamer system, as it defines the structure of the pipeline.  
+Elements include sources, filters, sinks, and containers (Bins).  They may be an intrinsic part of the core GStreamer
+library, or may be loaded from a plugin.  In some cases they're even fabricated from completely different systems (see
+the LADSPA plugin).  They are generally created from a GstElementFactory, which will be covered in another chapter, but
+for the intrinsic types they can be created with specific functions.
+
+Elements contains GstPads (also covered in another chapter), which are subsequently used to connect the Elements
+together to form a pipeline capable of passing and processing data.  They have a parent, which must be another Element.  
+This allows deeply nested pipelines, and the possibility of "black-box" meta-elements.
+
+Name
+----
+
+All elements are named, and while they should ideally be unique in any given pipeline, the do not have to be.  The only 
+guaranteed unique name for an element is its complete path in the object hierarchy.  Functions are provided to set and 
+get the name of the element.  _set_name() creates a local copy of the string passed.  _get_name() returns the actual 
+element's pointer.  Therefore, the argument to _set_name() is the responsibility of the caller to free if necessary, 
+but the return from _get_name() is definitely not to be messed with by the caller.  Accordingly, _get_name() returns an 
+const gchar *.
+
+Providing a new name to an element causes it to free its internal copy of the name and make a copy of the new name.
+This means that you must consider the pointer returned by _get_name() to be short-lived.  If you must make use of the 
+name beyond the immediate scope, it is suggested that you make yourself a copy of it.  If you know for a fact neither 
+the pointer nor its contents will change, you may retain the original pointer.  If you get odd results when using the 
+returned string, that's the first thing to check.
+
+
+Pads
+----
+
+GstPads are the property of a given GstElement.  They provide the connection capability, with allowing arbitrary 
+structure in the graph.  For any Element but a source or sink, there will be at least 2 Pads owned by the Element.  
+These pads are stored in a single GList within the Element.  Several counters are kept in order to allow quicker 
+determination of the type and properties of a given Element.
+
+Pads may be added to an element with _add_pad.  Retrieval is via _get_pad(), which operates on the name of the Pad (the
+unique key).  This means that all Pads owned by a given Element must have unique names (FIXME we don't verify this at
+_add time).  A pointer to the GList of pads may be obtained with _get_pad_list.  As with the element's name, 
+precaution must be taken with all these pointers, as they are the same pointer that the Element uses internally.  One 
+must be especially careful not to manipulate the list of pads.
+
+gst_element_add_pad(element,pads):
+	Sets the element as the parent of the pad, then adds the pad to the element's list of pads, keeping the counts 
+	of total, src, and sink pads up to date.  Emits the "new_pad" signal with the pad as argument.  Fails if either 
+	the element or pad are either NULL or not what they claim to be.  Should fail if the pad already has a parent.  
+	Should fail if the pad is already owned by the element.  Should fail if there's already a pad by that name in 
+	the the list of pads.
+
+pad = gst_element_get_pad(element,"padname"):
+	Searches through the list of pads 
+
+
+Ghost Pads
+----------
+
+
+State
+-----
+
+Elements use state to determine what the are capable of doing at any given moment.  The states are defined as follows:
+
+NULL	No state is held for the element
+READY	Devices are open
+PLAYING	
+PAUSED	

docs/design/part-gstobject.txt

@@ -0,0 +1,42 @@
+GstObject
+=========
+
+The base class for the entire GStreamer hierarchy is the GstObject.  It is currently a bit of a hack caused by the
+fact that GStreamer is built on top of GtkObject.  GObject should help, if it's designed properly.  Currently the 
+capabilities provided by GstObject are quite underutilized, this will be fixed with a refactoring of the 
+object system and a code cleanup at some point in the future.  If nothing else, it serves as an easy check to see if a 
+given object belongs to GStreamer.
+
+Parentage
+---------
+
+A pointer is available to store the current parent of the object.  This one of the two fundamental requires for a 
+hierarchical system such as GStreamer (for the other, read up on GstBin).  Three functions are provided: _set_parent(), 
+_get_parent(), and _unparent().  The third is required because there is an explicit check in _set_parent(): an object 
+must not already have a parent if you wish to set one.  You must unparent the object first.  This allows for new 
+additions later.
+
+Refcounting
+-----------
+
+A reference count is kept for the object.  When this is fully utilized, it will enable generic destruction of objects 
+by simply reducing the reference count to zero.  GObject should provide these capabilities, however.
+
+Locking
+-------
+
+The GstObject contains the necessary primitives to lock the object in a thread-safe manner.  This will be used to 
+provide general thread-safety as needed.  However, this lock is generic, i.e. it covers the whole object.  Note that 
+this does *not* mean that no other thread can modify the object at the same time that the lock is held.  It only means 
+that any two sections of code that obey the lock are guaranteed to not be running simultaneously.
+
+This lock will ideally be used for parentage and refcounting, which is reasonable, since they are the only possible 
+things to protect in the GstObject.
+
+Path Generation
+---------------
+
+Due to the base nature of the GstObject, it becomes the only reasonable place to put this particular function
+(_get_path_string).  It will generate a string describing the parent hierarchy of a given GstObject.  Currently it is
+forced to use several child-class-specific functions, because we do not properly use the base capabilities (parentage,
+etc.) of GstObject properly.

docs/design/part-standards.txt

@@ -0,0 +1,16 @@
+Ownership of dynamic objects
+----------------------------
+
+Any object-oriented system or language that doesn't have automatic garbage collection has many potential pitfalls as 
+far as the pointers go.  Therefore, some standards must be adhered to as far as who owns what.
+
+Strings:
+Arguments passed into a function are owned by the caller, and the function will make a copy of the string for its own 
+internal use.  The string should be const gchar *.  Strings returned from a function remain the property of the 
+function called, and the caller must make a copy if it is to use the string for an extended duration.
+
+Objects:
+The ownership of an object during a function call depends on the type of function.  If the function is simply returning 
+something from the object, such as _get_name(), the caller retains ownership.  If the object passed is to be 
+manipulated in some way, it is generally the case that the function will take over the ownership.  This should be 
+expressed as a reference increment on that object, but isn't in the general case (yet).