docs/random/wtay/events2

   1 INITIAL RAMBLINGS
   2 -----------------
   3
   4 some random ramblings about the event system:
   5
   6 Possible candidates for events
   7 ------------------------------
   8
   9   - QoS
  10   - EOS
  11   - Seek
  12   - caps nego??
  13   - bufferpool get??
  14   - ...
  15
  16 Assumptions for events
  17 ----------------------
  18
  19 - They are tied to a pad.
  20 - get rid of gst_pad_set_*_function (except for the chain/get ones)
  21 - occur async to dataflow. (need locking?)
  22 - fixed set of events only for core features. (elements cannot abuse
  23      events for doing dataflow)
  24
  25 Questions
  26 ---------
  27
  28 limit the valid directions an event can travel in? ie. Can EOS only
  29 travel downstream (left to right)?
  30
  31 eg. Seek travels upstream, but it makes sense to also make it travel
  32     downstream (the case of a disksink, where we overwrite the header)
  33
  34
  35 Setting an event function
  36 -------------------------
  37
  38 void gst_pad_set_event_function (GstPad *pad, gint event_mask,
  39                                  GstEventFunction *function);
  40
  41
  42 event masks:
  43
  44 typedef enum {
  45   GST_EVENT_EOS                 = (1 << 0),
  46   GST_EVENT_QOS                 = (1 << 1),
  47   GST_EVENT_SEEK                = (1 << 2),
  48   GST_EVENT_CAPS                = (1 << 3),
  49 } GstEventType;
  50
  51 Event structure
  52 ---------------
  53
  54 typedef struct {
  55   GstEventType type;
  56   GstEventMinorType minor;
  57   guint64 timestamp;  /* also sequence number ?? */
  58
  59   union {
  60     /* EOS stuff */
  61     /* QoS stuff */
  62     /* Seek stuff */
  63     GstSeekType type; /* time, bytes, ... */
  64     gint64 offset;
  65     gint64 lenth;
  66     /* Caps stuff */
  67     GstCaps *caps;
  68   } data;
  69 } GstEvent;
  70
  71
  72 typedef enum {
  73   GST_EVENT_MINOR_NONE,
  74   /* EOS stuff */
  75
  76   /* QoS stuff */
  77   /* Seek stuff */
  78   GST_EVENT_MINOR_OFFSET,
  79   GST_EVENT_MINOR_TIME,
  80
  81   /* caps nego stuff */
  82   GST_EVENT_MINOR_CAPS_TRY,
  83   GST_EVENT_MINOR_CAPS_START,
  84   GST_EVENT_MINOR_CAPS_FINAL,
  85 } GstEventMinorType;
  86
  87
  88 Receiving events
  89 ----------------
  90
  91 a sample GstEventFunction, the event functions returns TRUE if the event is handled,
  92 FALSE otherwise.
  93
  94 gboolean
  95 gst_anelement_handle_event (GstPad *pad, GstEvent *event)
  96 {
  97   if (event->type == GST_EVENT_EOS) {
  98     /* do something */
  99     return TRUE;
 100   }
 101   else if (event->type == GST_EVENT_CAPS) {
 102     if (event->minor == GST_EVENT_CAPS_TRY) {
 103       /* try using this caps structure */
 104       return TRUE; /* return FALSE to proxy ???*/
 105     }
 106   }
 107   return FALSE;
 108 }
 109
 110
 111 Default event handler for pads
 112 ------------------------------
 113
 114 gboolean
 115 gst_pad_handle_event (GstPad *pad, GstEvent *event)
 116 {
 117   GstElement *element;
 118   GList *pads;
 119   GstPad *srcpad;
 120   gboolean result = TRUE;
 121   GstPadDirection dir = GST_PAD_DIRECTION (pad);
 122
 123   g_return_val_if_fail (pad != NULL, FALSE);
 124   g_return_val_if_fail (GST_IS_REAL_PAD(pad), FALSE);   // NOTE the restriction
 125
 126   element = GST_ELEMENT (gst_object_get_parent (GST_OBJECT (pad)));
 127
 128   /* send out the events to all pad with opposite direction */
 129   pads = gst_element_get_pad_list(element);
 130   while (pads) {
 131     otherpad = GST_PAD(pads->data);
 132     pads = g_list_next(pads);
 133
 134     if (gst_pad_get_direction(otherpad) != dir) {
 135       result &= gst_pad_send_event (GST_REAL_PAD(otherpad), event);
 136     }
 137   }
 138
 139   /* result is combined result of all handlers? */
 140   return result;
 141 }
 142
 143