diff --git a/docs/design/part-conventions.txt b/docs/design/part-conventions.txt new file mode 100644 index 0000000000..da634b8f5a --- /dev/null +++ b/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. diff --git a/docs/design/part-gstelement.txt b/docs/design/part-gstelement.txt new file mode 100644 index 0000000000..9cb57eceb7 --- /dev/null +++ b/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 diff --git a/docs/design/part-gstobject.txt b/docs/design/part-gstobject.txt new file mode 100644 index 0000000000..7445016c9d --- /dev/null +++ b/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. diff --git a/docs/design/part-standards.txt b/docs/design/part-standards.txt new file mode 100644 index 0000000000..c28b0246f8 --- /dev/null +++ b/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).