gstreamer/docs/design/part-gstelement.txt
Erik Walthinsen c824d8eaf9 current set of design docs, in .txt format
Original commit message from CVS:
current set of design docs, in .txt format
2001-01-20 20:08:59 +00:00

77 lines
3.8 KiB
Text

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