docs/design/part-gstelement.txt

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