docs/design/part-gstelement.txt

   1   gstelement
   2     name
   3     pads
   4     state
   5     loopfunction
   6     threadstate
   7     manager
   8     ghostpads
   9
  10 GstElement
  11 ==========
  12
  13 The Element is the most important object in the entire GStreamer system, as it
  14 defines the structure of the pipeline.  Elements include sources, filters,
  15 sinks, and containers (Bins).  They may be an intrinsic part of the core
  16 GStreamer library, or may be loaded from a plugin.  In some cases they're even
  17 fabricated from completely different systems (see the LADSPA plugin).  They
  18 are generally created from a GstElementFactory, which will be covered in
  19 another chapter, but for the intrinsic types they can be created with specific
  20 functions.
  21
  22 Elements contains GstPads (also covered in another chapter), which are
  23 subsequently used to connect the Elements together to form a pipeline capable
  24 of passing and processing data.  They have a parent, which must be another
  25 Element.  This allows deeply nested pipelines, and the possibility of
  26 "black-box" meta-elements.
  27
  28 Name
  29 ----
  30
  31 All elements are named, and while they should ideally be unique in any given
  32 pipeline, they do not have to be.  The only guaranteed unique name for an
  33 element is its complete path in the object hierarchy.  In other words, an
  34 element's name is unique inside its parent.  (This follows from GstObject's
  35 name explanation)
  36
  37 This uniqueness is guaranteed through all functions where either parentage
  38 or name of an element is changed.
  39
  40
  41 Pads
  42 ----
  43
  44 GstPads are the property of a given GstElement.  They provide the connection capability, with allowing arbitrary
  45 structure in the graph.  For any Element but a source or sink, there will be at least 2 Pads owned by the Element.
  46 These pads are stored in a single GList within the Element.  Several counters are kept in order to allow quicker
  47 determination of the type and properties of a given Element.
  48
  49 Pads may be added to an element with _add_pad.  Retrieval is via _get_pad(), which operates on the name of the Pad (the
  50 unique key).  This means that all Pads owned by a given Element must have unique names (FIXME we don't verify this at
  51 _add time).  A pointer to the GList of pads may be obtained with _get_pad_list.  As with the element's name,
  52 precaution must be taken with all these pointers, as they are the same pointer that the Element uses internally.  One
  53 must be especially careful not to manipulate the list of pads.
  54
  55 gst_element_add_pad(element,pads):
  56         Sets the element as the parent of the pad, then adds the pad to the element's list of pads, keeping the counts
  57         of total, src, and sink pads up to date.  Emits the "new_pad" signal with the pad as argument.  Fails if either
  58         the element or pad are either NULL or not what they claim to be.  Should fail if the pad already has a parent.
  59         Should fail if the pad is already owned by the element.  Should fail if there's already a pad by that name in
  60         the the list of pads.
  61
  62 pad = gst_element_get_pad(element,"padname"):
  63         Searches through the list of pads
  64
  65
  66 Ghost Pads
  67 ----------
  68
  69
  70 State
  71 -----
  72
  73 An element has a state. More info in part-states.txt.