markdown/design/gstelement.md

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